2019-01-15 19:23:45 +01:00
|
|
|
# stm32-ada
|
2019-01-15 23:50:29 +01:00
|
|
|
Ada bindings for STM32 internals
|
2021-07-15 17:26:58 +02:00
|
|
|
|
2021-07-29 16:32:46 +02:00
|
|
|
## Design directions
|
|
|
|
|
2021-08-03 18:16:33 +02:00
|
|
|
Main design goal is a type safety. Specific enumerations and records are used
|
|
|
|
in hardware definitions. Common structure of a peripherial module
|
|
|
|
is a record with all its registers and
|
|
|
|
every register is a record with all its fields. That is every field is
|
|
|
|
addressed using scheme `Unit.Register.Field`
|
|
|
|
|
|
|
|
While it is generally preferred to have entities same identifiers as in STM's
|
|
|
|
user manuals, it is not always possible. So some of them have originel or
|
|
|
|
a bit changed name.
|
|
|
|
- The identifier clashes with Ada keyword. E. g. `ABORT` bit-field is renamed to `ABRT`.
|
|
|
|
- Identifier is not given by UM. This is common case for bit-field values.
|
|
|
|
They taken descriptive names based on original UM text.
|
|
|
|
- Identifier decomposition and generalization. Bitfield identifiers are
|
|
|
|
shortened if they have common part. Also if two or more registers have same or
|
|
|
|
analogous fields they commonly share the same record type, thus having same
|
|
|
|
field names. Thus RCC's xxxRST, xxxEN and xxxLPEN registers a defined the same
|
|
|
|
with RST/EN/LPEN part removed from their bit fields.
|
|
|
|
|
2021-07-29 16:32:46 +02:00
|
|
|
### Compiler implication
|
|
|
|
|
|
|
|
`System.Address` should be standard 32 bit byte address as in CPU registers
|
|
|
|
and peripherals (DMA etc.).
|
|
|
|
|
2021-08-03 18:16:33 +02:00
|
|
|
### Development boards supported
|
|
|
|
|
|
|
|
stm32f429disco (stm32f429disc1) -- board available from STM.
|
|
|
|
429disco in examples.
|
|
|
|
|
|
|
|
STM32F407Z-based board from PiSwords. Widely available from chinese suppliers.
|
|
|
|
407z_piswords in examples.
|
|
|
|
|
2021-10-27 18:01:25 +02:00
|
|
|
### Default values
|
|
|
|
|
|
|
|
Default values are given to register and their field according to following rules:
|
|
|
|
- cleared by writing '0' (rc_w0) fields set to logic '1', that is True;
|
|
|
|
- clered by writing '1' (rc_w1) field set to logic '0', that is False;
|
|
|
|
- for read-only registers default values are not set;
|
|
|
|
- when reset state is specified default is set to it;
|
|
|
|
- there may be convenient to set default to some specific value, those cases are documented.
|
|
|
|
|
2021-08-19 18:03:16 +02:00
|
|
|
## Current inconsistencies and importabilities
|
|
|
|
|
|
|
|
GNAT's System'To_Address attribute is used in peripherials definitions
|
|
|
|
(STM32.*model-name*.Units packages).
|
|
|
|
I currently cannot decide if Preelaborate is really needed there.
|
|
|
|
|
2021-11-24 12:56:29 +01:00
|
|
|
## Common implementation notes
|
|
|
|
|
|
|
|
### Interrupts
|
|
|
|
|
|
|
|
Interrupt handling in multitasked (Ravenscar) profiles require support from OS / RTL.
|
|
|
|
That is, no interrupt definitions done there.
|
|
|
|
Use `Ada.Interrupts.Names` to define interrupt handlers.
|
|
|
|
This obviously limit the set of supported devices to ones supplied with compiler.
|
|
|
|
|
|
|
|
Interrupts in minimal (ZFP) profiles though do not require any system support
|
|
|
|
as they fully handled by user code.
|
|
|
|
However interrupt vector table should be implementer by the user too.
|
|
|
|
For this maybe some constants will be set.
|
|
|
|
|
2021-07-15 17:26:58 +02:00
|
|
|
## Hardware quirks and workarounds
|
|
|
|
|
|
|
|
### APB
|
|
|
|
|
2021-08-03 18:16:33 +02:00
|
|
|
APB does not support partial writes to 32-bit registers.
|
|
|
|
The library provides access to register fields as records.
|
2021-07-15 17:26:58 +02:00
|
|
|
This could lead compiler to emit byte and half-word writes
|
|
|
|
to APB registers causing erroneous effects.
|
|
|
|
As a workaround those registers should be read to local variable,
|
2021-08-03 18:16:33 +02:00
|
|
|
this variable altered, and then written back to the hardware.
|
2021-07-15 17:26:58 +02:00
|
|
|
GNAT users may not need the workaround, because of its pragma
|
|
|
|
`Volatile_Full_Access` used in this library.
|
|
|
|
|
2021-10-27 18:09:09 +02:00
|
|
|
## SVD conversion scripts
|
|
|
|
|
|
|
|
Put SVD data directory (e.g. STM32F4_svd_V1.2) under tools/imported_data directory.
|
|
|
|
Scripts and makefile in tools/would convert it to .ads files
|
|
|
|
(they obvously need editing, however compiled fine)
|
|
|
|
and stripped text files needed primarily for comparisons.
|
|
|
|
|
2021-07-15 17:26:58 +02:00
|
|
|
## Compiler specific notes
|
|
|
|
|
|
|
|
There are compiler-specific pragmas so your compiler may complain about them.
|
|
|
|
|
|
|
|
|
|
|
|
### GNAT
|
|
|
|
|
|
|
|
`Volatile_Full_Access` pragma is used on (at least writable) APB registers
|
|
|
|
as byte- and half-wide writes are not supported by APB. Read STM docs on
|
2021-07-20 18:41:32 +02:00
|
|
|
what those accesses actually do.
|
|
|
|
|
|
|
|
Currently GPR cannot manage aggregate projects for different targets.
|
2021-08-03 18:16:33 +02:00
|
|
|
GNU Make script is used to build whole set of libraries instead.
|