As a rule of thumb, no memory buffer is allocated by the driver. Allocation is done by the application and provided to the driver as pointer variables. This allows the author of the application freedom to choose how memory is allocated in the application. In many cases, memory management can be done at compile time by allocating memory statically. Allocation outside the driver also gives the user the possibility of using a memory manager of his choosing.
The parameter list for a given public ASF4 function shall have a hard limit of up to four parameters. If this limit is surpassed the function's purpose shall be redesigned or split into multiple function calls. Another approach would be to use a container for the parameters like a struct.
Some words/acronyms are given a special meaning in the framework to give the user a better understanding about the purpose of function/symbol/etc. These words are:
Short: cb
Typically used for functions or pointers. Refers to functions/code that is triggered by events in hardware or other parts of the software.
struct spi_dev_callbacks {
/* TX callback, see \ref spi_dev_cb_xfer_t. */
spi_dev_cb_xfer_t tx;
/* RX callback, see \ref spi_dev_cb_xfer_t. */
spi_dev_cb_xfer_t rx;
/* Complete callback, see \ref spi_dev_cb_complete. */
spi_dev_cb_complete_t complete;
Short: conf
Typically used to symbols, macros defining a configuration parameter or a set of configuration parameters.
#define CONF_SERCOM_0_USART_DORD CONF_SERCOM_USART_DATA_ORDER_LSB
#define CONF_SERCOM_0_USART_CPOL CONF_SERCOM_USART_CLOCK_POLARITY_TX_RISING_EDGE
#define CONF_SERCOM_0_USART_CMODE CONF_SERCOM_USART_COMMUNICATION_MODE_ASYNCHRONOUS
Short: deinit
int32_t adc_deinit(struct adc_descriptor *const descr);
Short: dev
Typically used when referring to something that can be described as a "device" like the abstracted device definition.
struct _adc_device {
struct _adc_callbacks adc_cb;
void *hw;
};
Short: init
Typically used for functions that initializes something, like a peripheral for instance.
int32_t usart_sync_init(struct usart_sync_descriptor *const descr, void *const hw);
Short: iface
Typically used when referring to driver interfaces (APIs) like the abstracted interface used between the HPL and HAL.
struct i2c_interface {
int32_t (*init)(struct i2c_device *i2c_dev);
int32_t (*deinit)(struct i2c_device *i2c_dev);
int32_t (*enable)(struct i2c_device *i2c_dev);
int32_t (*disable)(struct i2c_device *i2c_dev);
int32_t (*transfer)(struct i2c_device *i2c_dev, struct i2c_msg *msg);
int32_t (*set_baudrate)(struct i2c_device *i2c_dev, uint32_t clkrate, uint32_t baudrate);
Short: msg
Typically used when data sent over an interface has to be compiled from different data sources before it is sent. For instance, an I2C message has to consist of an address and data.
struct i2c_msg {
uint16_t addr;
volatile uint16_t flags;
int32_t len;
uint8_t *buffer;
Acronym: prvt
Typically used for private data members or symbols, which contain data that should not be accessed by external code (for instance user code, or it can even be localised to just parts of the owner code). Typically used for the hardware pointer member in the device descriptor struct as it should only be accessed by the HPL after it has be assigned.
struct spi_sync_dev {
/* Pointer to the hardware base or private data for special device. */
void *prvt;
/* CS information,
* Pointer to information list to configure and use I/O pins as SPI CSes
* (master), or CS pin information when \c cs_num is 0 (slave).
*/
union spi_dev_cs cs;
/* Number of Chip Select (CS), set to 0 for SPI slave, 0xFF to ignore CS behaviour */
int8_t cs_num;
/* Data size, number of bytes for each character */
uint8_t char_size;
/* Flags for the driver for implementation use (could change in implementation) */
uint16_t flags;
};
Short: stat
Typically used when referring to functions/symbols related to returning or storing status information.
Short: err
Typically used for containers/variables holding information about error state information in hardware or software, can also refer to callbacks or functions referring to error handling code.
static void dac_tx_error(struct _dac_device *device, const uint8_t ch);
Short: xfer
Typically used when referring to functions/symbols related to moving data in one or both direction.
enum spi_transfer_mode {
/* Leading edge is rising edge, data sample on leading edge. */
SPI_MODE_0,
/* Leading edge is rising edge, data sample on trailing edge. */
SPI_MODE_1,
/* Leading edge is falling edge, data sample on leading edge. */
SPI_MODE_2,
/* Leading edge is falling edge, data sample on trailing edge. */
SPI_MODE_3
};