Using Registers Directly

Overview

In some cases users may wish to utilize chip functionality that is not supported yet by FSP. While we encourage contacting us when new feature requests arise it takes time before any updates are made. In the meantime, it is recommended to use the register definition files accessed via renesas.h to add custom functionality as needed. Official ARM CMSIS documentation refers to this format of related register definition files as device header files. Within Renesas, these files are often referred to as an IO define or more commonly iodefine.

What's in an "iodefine"?

Iodefine files contain definitions for all the I/O registers on a device. For RA for Wireless FSP, one iodefine header is provided per device group (RA6W1, RA6W2 etc.) that contains all the register definitions provided in the hardware manual for that group. These headers are accessed via renesas.h, which selects the appropriate file based on the MCU configured in the project.

Where are iodefine files located?

In RA for Wireless FSP, iodefine files are stored in ra/fsp/src/bsp_w/cmsis/Device/RENESAS/Include. This includes both renesas.h as well as the device group specific iodefine headers.

Using the register definitions

Each peripheral register set is provided as a struct. In general, the template to follow is:

peripheral abbreviation + channel number (empty if 1) + -> + register name [ + _b. + bitfield name]

Basic register access

Registers are most commonly accessed whole. For example, say we want to read control register of SPI channel 2:

uint32_t spi_ctrl = SPI2->SPI2_CTRL_REG;

As shown in the template, the iodefines can also be used to access bitfields. For example, to set word length for SPI channel 2 to 32 bit:

SPI2->SPI2_CONFIG_REG_b.SPI_WORD_LENGTH = 31;

Bitfield macros

It is worth noting that each bitfield access will cause a full read-modify-write which cannot be combined by the compiler because the register definitions are by necessity volatile. This can be very size and speed inefficient, particularly when the peripheral is on a very slow clock. It is recommended to write whole registers wherever possible. This is made easier by macros that are provided alongside the register definitions.

Every bitfield has two associated macros: _Msk (bitfield mask) and _Pos (bit position). These macros can be used to manipulate whole registers instead of using bitfield access when multiple bitfields are modified simultaneously. For example, setting both word length and mode for SPI2:

uint32_t config_reg   = SPI2->SPI2_CONFIG_REG;
config_reg           &= ~(SPI2_SPI2_CONFIG_REG_SPI_WORD_LENGTH_Msk | SPI2_SPI2_CONFIG_REG_SPI_SLAVE_EN_Msk);
config_reg           |= (7 << SPI2_SPI2_CONFIG_REG_SPI_WORD_LENGTH_Pos) | SPI2_SPI2_CONFIG_REG_SPI_SLAVE_EN_Msk;
SPI2->SPI2_CONFIG_REG = config_reg;

Arrays

Some registers are part of an array. These are typically listed in the manual using indexes like "n" or "m", but may occasionally be listed with individual numbers or letters. Accessing register arrays is just like accessing a regular array. In the example, setting of pending bit of a device specific interrupt in the NVIC register:

/* Set Pending Interrupt */
NVIC->ISPR[(((uint32_t)IRQn) >> 5UL)] = (uint32_t)(1UL << (((uint32_t)IRQn) & 0x1FUL));

Note

Not all indices may be available in every array. Be sure to check the hardware manual to verify which registers are provided on the device in use.

Tips for writing hardware drivers

Channel register access

FSP drivers often calculate a register offset in the Open function. This is typically done by multiplying the channel by the offset between between channels 1 and 2. For example, here is the calculation for SPI:

   /* Save register base address. */
    uint32_t base_address  = (uint32_t) SPI + (p_cfg->channel * ((uint32_t) SPI2 - (uint32_t) SPI));
    p_instance_ctrl->p_reg = (SPI_Type *) base_address;

When drivers need to support multiple channels of a peripheral it can be helpful to save the offset in a persistent variable or structure so that it only needs to be calculated once.