The standard technique to enforce atomic access to volatile variables shared with ISRs, via "atomic access guards" or "interrupt guards", in particular when running a bare metal, single-threaded cooperative multi-tasking application with no operating system, is as follows:
// 1. save interrupt state
// 2. disable only the interrupts necessary
// You get atomic access to volatile variables shared with ISRs here,
// since ISRs are the only other "context" or running "thread" which
// might attempt to modify a shared memory block or variable.
// 3. restore interrupt state
See also where I describe this in detail here, including best practices (keep interrupts off for short period of time) and how to do atomic reads withOUT disabling interrupts first, via my doAtomicRead() repeat-read-loop function: Reading a 64 bit variable that is updated by an ISR.
I have previously documented how to do this for AVR microcontrollers/Arduino: How do I force atomicity in Atmel AVR mcus/Arduino?.
But, how do I do this for STM32 microcontrollers? I know there are a lot of ways.
Please cover the following techniques:
Via ARM-core CMSIS:
for global interrupts
for specific IRQs (Interrupt Requests)
Via STM32 HAL (Hardware Abstraction Layer)
Via FreeRTOS
This answer is related, but insufficient: How can I re-enable the stm32f103's external interrupt after I disable it?
Multiple ways to enable/disable interrupts in STM32 mcus:
1. Via ARM-core CMSIS:
1.A. For global interrupts
__enable_irq() // enable all interrupts
__disable_irq() // disable all interrupts
// Returns the current state of the priority mask bit from the Priority Mask
// Register. [0 if global interrupts are **enabled** and non-zero if they
// are **disabled**]
__get_PRIMASK()
For the definition of these functions, see:
https://github.com/ARM-software/CMSIS/blob/master/CMSIS/Include/cmsis_gcc.h
Contains at least:
__enable_irq()
__disable_irq()
__get_PRIMASK()
__set_PRIMASK()
STM32 example location: "stm/stm32f2xx/st_hal_v1.1.3/CMSIS/Include/cmsis_gcc.h":
To save and restore the interrupt state, use __get_PRIMASK(), like this:
// 1. back up interrupt state; `__get_PRIMASK()` returns 0 if interrupts
// are **enabled**, and non-zero if they are **disabled**.
bool interrupts_enabled = (__get_PRIMASK() == 0);
// do stuff
// 2. Disable interrupts
__disable_irq();
// 3. Restore backed-up-state
if (interrupts_enabled) {
__enable_irq();
}
When dealing with global interrupts, this is the best way for bare-metal, non-FreeRTOS code!
I think this technique is also cross-compatible with ALL ARM-core mcus, not just STM32.
I first learned this technique from Tilen Majerle, here: https://stm32f4-discovery.net/2015/06/how-to-properly-enabledisable-interrupts-in-arm-cortex-m/. His work and contributions to clear up this super-obfuscated stuff are infinitely valuable and appreciated!
His example:
void ImportantFunction1(void) {
/* Important function 1 */
uint32_t prim;
/* Do some stuff here which can be interrupted */
/* Read PRIMASK register, check interrupt status before you disable them */
/* Returns 0 if they are enabled, or non-zero if disabled */
prim = __get_PRIMASK();
/* Disable interrupts */
__disable_irq();
/* Do some stuff here which can not be interrupted */
/* Call subfunction */
ImportantFunction2();
/* Do some stuff here which can not be interrupted */
/* This part is still interrupt safe because ImportantFunction2 will not enable interrupts */
/* Enable interrupts back */
if (!prim) {
__enable_irq();
}
/* Do some stuff here which can be interrupted */
}
1.B. For specific IRQs (Interrupt Requests)
It is best to avoid disabling global interrupts, if possible, and disable only the fewest number of specific interrupts possible to achieve atomicity for your specific code. So, using these functions allows you to enable or disable only the specific interrupts you need to!
Enable or disable specific types of interrupts:
void NVIC_EnableIRQ(IRQn_Type IRQn);
void NVIC_DisableIRQ(IRQn_Type IRQn);
NVIC stands for "Nested Vector Interrupt Controller". Nested interrupts (meaning: a higher-priority interrupt can still fire within an ISR) are enabled by default on STM32 microcontrollers. Each interrupt type has a priority assigned to it, with lower priority numbers being higher priority, and higher-priority interrupts are able to fire while an ISR is being processed for a lower-priority interrupt. See here for a little more information on the STM32 NVIC: https://stm32f4-discovery.net/2014/05/stm32f4-stm32f429-nvic-or-nested-vector-interrupt-controller/.
Contrast this to AVR microcontrollers (ex: ATMega328 / Arduino Uno), which do not have priority-based interrupts, so by default, when any ISR is being processed, all interrupts (ie: global interrupts) are automatically disabled as the program enters the ISR. Note that even on AVR mcus, however, you can still manually enable nested interrupts / ISRs if you like by manually re-enabling global interrupts inside your ISR, via a call to interrupts() on Arduino or sei() (set interrupts) on raw AVR.
Each ARM-core microcontroller manufacturer, I believe, including STM32 types, must define and create its own list of IRQn_Type interrupt request types, so see below for the STM32 details on their specific interrupt types defined for each mcu.
2. Via STM32 HAL (Hardware Abstraction Layer) libraries
Enable or disable specific types of interrupts:
// enable interrupts
HAL_NVIC_EnableIRQ(IRQn_Type IRQn);
// disable interrupts
HAL_NVIC_DisableIRQ(IRQn_Type IRQn);
See, for example: "stm/stm32f2xx/st_hal_v1.1.3/STM32F2xx_HAL_Driver/Src/stm32f2xx_hal_cortex.c/.h" - definitions for those functions above are in those files. See them online:
https://github.com/STMicroelectronics/STM32CubeF2/blob/master/Drivers/STM32F2xx_HAL_Driver/Inc/stm32f2xx_hal_cortex.h#L264-L265
https://github.com/STMicroelectronics/STM32CubeF2/blob/master/Drivers/STM32F2xx_HAL_Driver/Src/stm32f2xx_hal_cortex.c#L178-L210
Here are the definitions of HAL_NVIC_EnableIRQ() and HAL_NVIC_DisableIRQ(). Notice that they just check to ensure your IRQn is valid, then they pass the input argument on to the ARM-core CMSIS NVIC_EnableIRQ() and NVIC_DisableIRQ() functions above!:
/**
* #brief Enables a device specific interrupt in the NVIC interrupt controller.
* #note To configure interrupts priority correctly, the NVIC_PriorityGroupConfig()
* function should be called before.
* #param IRQn External interrupt number.
* This parameter can be an enumerator of IRQn_Type enumeration
* (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32f2xxxx.h))
* #retval None
*/
void HAL_NVIC_EnableIRQ(IRQn_Type IRQn)
{
/* Check the parameters */
assert_param(IS_NVIC_DEVICE_IRQ(IRQn));
/* Enable interrupt */
NVIC_EnableIRQ(IRQn);
}
/**
* #brief Disables a device specific interrupt in the NVIC interrupt controller.
* #param IRQn External interrupt number.
* This parameter can be an enumerator of IRQn_Type enumeration
* (For the complete STM32 Devices IRQ Channels list, please refer to the appropriate CMSIS device file (stm32f2xxxx.h))
* #retval None
*/
void HAL_NVIC_DisableIRQ(IRQn_Type IRQn)
{
/* Check the parameters */
assert_param(IS_NVIC_DEVICE_IRQ(IRQn));
/* Disable interrupt */
NVIC_DisableIRQ(IRQn);
}
For IRQn_Types: see the appropriate definition file for your specific board! These are board-specific definitions, for your board from your manufacturer. Here are all of the boards in the STM32 F2xx line, for instance: https://github.com/STMicroelectronics/STM32CubeF2/tree/master/Drivers/CMSIS/Device/ST/STM32F2xx/Include. Let's look at the stm32f217xx.h file specifically:
https://github.com/STMicroelectronics/STM32CubeF2/blob/master/Drivers/CMSIS/Device/ST/STM32F2xx/Include/stm32f217xx.h
Raw view (since file is too big to view on GitHub otherwise): https://raw.githubusercontent.com/STMicroelectronics/STM32CubeF2/master/Drivers/CMSIS/Device/ST/STM32F2xx/Include/stm32f217xx.h
From this file, we can see the typedef enum definition for the IRQn_Type, which is the "STM32F2XX Interrupt Number Definition". Here is what it looks like:
/**
* #brief STM32F2XX Interrupt Number Definition, according to the selected device
* in #ref Library_configuration_section
*/
typedef enum
{
/****** Cortex-M3 Processor Exceptions Numbers ****************************************************************/
NonMaskableInt_IRQn = -14, /*!< 2 Non Maskable Interrupt */
HardFault_IRQn = -13, /*!< 3 Hard Fault Interrupt */
MemoryManagement_IRQn = -12, /*!< 4 Cortex-M3 Memory Management Interrupt */
BusFault_IRQn = -11, /*!< 5 Cortex-M3 Bus Fault Interrupt */
UsageFault_IRQn = -10, /*!< 6 Cortex-M3 Usage Fault Interrupt */
SVCall_IRQn = -5, /*!< 11 Cortex-M3 SV Call Interrupt */
DebugMonitor_IRQn = -4, /*!< 12 Cortex-M3 Debug Monitor Interrupt */
PendSV_IRQn = -2, /*!< 14 Cortex-M3 Pend SV Interrupt */
SysTick_IRQn = -1, /*!< 15 Cortex-M3 System Tick Interrupt */
/****** STM32 specific Interrupt Numbers **********************************************************************/
WWDG_IRQn = 0, /*!< Window WatchDog Interrupt */
PVD_IRQn = 1, /*!< PVD through EXTI Line detection Interrupt */
TAMP_STAMP_IRQn = 2, /*!< Tamper and TimeStamp interrupts through the EXTI line */
RTC_WKUP_IRQn = 3, /*!< RTC Wakeup interrupt through the EXTI line */
FLASH_IRQn = 4, /*!< FLASH global Interrupt */
RCC_IRQn = 5, /*!< RCC global Interrupt */
EXTI0_IRQn = 6, /*!< EXTI Line0 Interrupt */
EXTI1_IRQn = 7, /*!< EXTI Line1 Interrupt */
EXTI2_IRQn = 8, /*!< EXTI Line2 Interrupt */
EXTI3_IRQn = 9, /*!< EXTI Line3 Interrupt */
EXTI4_IRQn = 10, /*!< EXTI Line4 Interrupt */
DMA1_Stream0_IRQn = 11, /*!< DMA1 Stream 0 global Interrupt */
DMA1_Stream1_IRQn = 12, /*!< DMA1 Stream 1 global Interrupt */
DMA1_Stream2_IRQn = 13, /*!< DMA1 Stream 2 global Interrupt */
DMA1_Stream3_IRQn = 14, /*!< DMA1 Stream 3 global Interrupt */
DMA1_Stream4_IRQn = 15, /*!< DMA1 Stream 4 global Interrupt */
DMA1_Stream5_IRQn = 16, /*!< DMA1 Stream 5 global Interrupt */
DMA1_Stream6_IRQn = 17, /*!< DMA1 Stream 6 global Interrupt */
ADC_IRQn = 18, /*!< ADC1, ADC2 and ADC3 global Interrupts */
CAN1_TX_IRQn = 19, /*!< CAN1 TX Interrupt */
CAN1_RX0_IRQn = 20, /*!< CAN1 RX0 Interrupt */
CAN1_RX1_IRQn = 21, /*!< CAN1 RX1 Interrupt */
CAN1_SCE_IRQn = 22, /*!< CAN1 SCE Interrupt */
EXTI9_5_IRQn = 23, /*!< External Line[9:5] Interrupts */
TIM1_BRK_TIM9_IRQn = 24, /*!< TIM1 Break interrupt and TIM9 global interrupt */
TIM1_UP_TIM10_IRQn = 25, /*!< TIM1 Update Interrupt and TIM10 global interrupt */
TIM1_TRG_COM_TIM11_IRQn = 26, /*!< TIM1 Trigger and Commutation Interrupt and TIM11 global interrupt */
TIM1_CC_IRQn = 27, /*!< TIM1 Capture Compare Interrupt */
TIM2_IRQn = 28, /*!< TIM2 global Interrupt */
TIM3_IRQn = 29, /*!< TIM3 global Interrupt */
TIM4_IRQn = 30, /*!< TIM4 global Interrupt */
I2C1_EV_IRQn = 31, /*!< I2C1 Event Interrupt */
I2C1_ER_IRQn = 32, /*!< I2C1 Error Interrupt */
I2C2_EV_IRQn = 33, /*!< I2C2 Event Interrupt */
I2C2_ER_IRQn = 34, /*!< I2C2 Error Interrupt */
SPI1_IRQn = 35, /*!< SPI1 global Interrupt */
SPI2_IRQn = 36, /*!< SPI2 global Interrupt */
USART1_IRQn = 37, /*!< USART1 global Interrupt */
USART2_IRQn = 38, /*!< USART2 global Interrupt */
USART3_IRQn = 39, /*!< USART3 global Interrupt */
EXTI15_10_IRQn = 40, /*!< External Line[15:10] Interrupts */
RTC_Alarm_IRQn = 41, /*!< RTC Alarm (A and B) through EXTI Line Interrupt */
OTG_FS_WKUP_IRQn = 42, /*!< USB OTG FS Wakeup through EXTI line interrupt */
TIM8_BRK_TIM12_IRQn = 43, /*!< TIM8 Break Interrupt and TIM12 global interrupt */
TIM8_UP_TIM13_IRQn = 44, /*!< TIM8 Update Interrupt and TIM13 global interrupt */
TIM8_TRG_COM_TIM14_IRQn = 45, /*!< TIM8 Trigger and Commutation Interrupt and TIM14 global interrupt */
TIM8_CC_IRQn = 46, /*!< TIM8 Capture Compare Interrupt */
DMA1_Stream7_IRQn = 47, /*!< DMA1 Stream7 Interrupt */
FSMC_IRQn = 48, /*!< FSMC global Interrupt */
SDIO_IRQn = 49, /*!< SDIO global Interrupt */
TIM5_IRQn = 50, /*!< TIM5 global Interrupt */
SPI3_IRQn = 51, /*!< SPI3 global Interrupt */
UART4_IRQn = 52, /*!< UART4 global Interrupt */
UART5_IRQn = 53, /*!< UART5 global Interrupt */
TIM6_DAC_IRQn = 54, /*!< TIM6 global and DAC1&2 underrun error interrupts */
TIM7_IRQn = 55, /*!< TIM7 global interrupt */
DMA2_Stream0_IRQn = 56, /*!< DMA2 Stream 0 global Interrupt */
DMA2_Stream1_IRQn = 57, /*!< DMA2 Stream 1 global Interrupt */
DMA2_Stream2_IRQn = 58, /*!< DMA2 Stream 2 global Interrupt */
DMA2_Stream3_IRQn = 59, /*!< DMA2 Stream 3 global Interrupt */
DMA2_Stream4_IRQn = 60, /*!< DMA2 Stream 4 global Interrupt */
ETH_IRQn = 61, /*!< Ethernet global Interrupt */
ETH_WKUP_IRQn = 62, /*!< Ethernet Wakeup through EXTI line Interrupt */
CAN2_TX_IRQn = 63, /*!< CAN2 TX Interrupt */
CAN2_RX0_IRQn = 64, /*!< CAN2 RX0 Interrupt */
CAN2_RX1_IRQn = 65, /*!< CAN2 RX1 Interrupt */
CAN2_SCE_IRQn = 66, /*!< CAN2 SCE Interrupt */
OTG_FS_IRQn = 67, /*!< USB OTG FS global Interrupt */
DMA2_Stream5_IRQn = 68, /*!< DMA2 Stream 5 global interrupt */
DMA2_Stream6_IRQn = 69, /*!< DMA2 Stream 6 global interrupt */
DMA2_Stream7_IRQn = 70, /*!< DMA2 Stream 7 global interrupt */
USART6_IRQn = 71, /*!< USART6 global interrupt */
I2C3_EV_IRQn = 72, /*!< I2C3 event interrupt */
I2C3_ER_IRQn = 73, /*!< I2C3 error interrupt */
OTG_HS_EP1_OUT_IRQn = 74, /*!< USB OTG HS End Point 1 Out global interrupt */
OTG_HS_EP1_IN_IRQn = 75, /*!< USB OTG HS End Point 1 In global interrupt */
OTG_HS_WKUP_IRQn = 76, /*!< USB OTG HS Wakeup through EXTI interrupt */
OTG_HS_IRQn = 77, /*!< USB OTG HS global interrupt */
DCMI_IRQn = 78, /*!< DCMI global interrupt */
CRYP_IRQn = 79, /*!< CRYP crypto global interrupt */
HASH_RNG_IRQn = 80 /*!< Hash and Rng global interrupt */
} IRQn_Type;
2.A. Example usage using STM32 HAL:
To get exclusive access (to ensure strings are atomically printed, for instance) to the USART1 for printing debug chars via a HAL-based blocking (polled) mode (ie: via HAL_UART_Transmit()), you need to disable all interrupts for USART1_IRQn by doing the following. (This guarantees you get atomic access to this device):
// 1. Disable the UART IRQ
HAL_NVIC_DisableIRQ(USART1_IRQn);
// 2. Send your string (in HAL blocking/polled mode)
// Prototype for this function is from
// "...stm/stm32f7xx/st_hal_v1.1.2/STM32F7xx_HAL_Driver/Src/stm32f7xx_hal_uart.c":
// - `HAL_StatusTypeDef HAL_UART_Transmit(UART_HandleTypeDef *huart,
// uint8_t *pData, uint16_t Size, uint32_t Timeout)`
// Note: `huart` is defined by STM32CubeMX as `UART_HandleTypeDef huart1;`
// in "hal_source/Src/usart.c"
HAL_UART_Transmit(&huart1, (uint8_t *)my_str, strlen(my_str), HAL_MAX_DELAY);
// 3. Enable the UART_IRQ
// FUTURE WORK: make this nestable/more robust by only enabling the
// IRQ here if it was previously enabled before disabling it!
HAL_NVIC_EnableIRQ(USART1_IRQn);
3. Via FreeRTOS:
The FreeRTOS atomic-access-guard / interrupt-related functions are listed under the "Modules" section of the Kernel Control API here: Kernel Control:
taskYIELD()
taskENTER_CRITICAL() // interrupts off
taskEXIT_CRITICAL() // restore interrupts
taskENTER_CRITICAL_FROM_ISR() // interrupts off
taskEXIT_CRITICAL_FROM_ISR() // restore interrupts
taskDISABLE_INTERRUPTS() // interrupts off
taskENABLE_INTERRUPTS() // interrupts on
3.A. Higher-level macros:
These are the preferred macros to use, and are the freertos-recommended ones!
These all support nested calls, and end up calling portDISABLE_INTERRUPTS() anyway, which is the port implementation of the lower-level taskDISABLE_INTERRUPTS(), shown below.
From: https://www.freertos.org/taskENTER_CRITICAL_taskEXIT_CRITICAL.html
taskENTER_CRITICAL() // interrupts off
taskEXIT_CRITICAL() // restore interrupts
From: https://www.freertos.org/taskENTER_CRITICAL_FROM_ISR_taskEXIT_CRITICAL_FROM_ISR.html
taskENTER_CRITICAL_FROM_ISR()
taskEXIT_CRITICAL_FROM_ISR()
3.B. Lower-level macros:
These do NOT support nested calls!
Official documentation on them is on the main "Kernel Control" page:
taskDISABLE_INTERRUPTS()
taskENABLE_INTERRUPTS()
Notes and limiatations:
taskDISABLE_INTERRUPTS() at the link above states:
Normally this macro would not be called directly and taskENTER_CRITICAL() and taskEXIT_CRITICAL() should be used in its place.
taskENABLE_INTERRUPTS() at the link above states:
Normally this macro would not be called directly and taskENTER_CRITICAL() and taskEXIT_CRITICAL() should be used in its place.
Note also that the use of taskDISABLE_INTERRUPTS() is demonstrated as the technique used to panic inside an example macro definition for configASSERT().
From here: https://www.freertos.org/a00110.html#configASSERT, when used with a debugger, it is defined as:
/* Define configASSERT() to disable interrupts and sit in a loop. */
#define configASSERT( ( x ) ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); for( ;; ); }
My thoughts: perhaps in this one case (ie: hard asserting, or panicking), taskDISABLE_INTERRUPTS() might be preferred over taskENTER_CRITICAL() because no amount of calling taskEXIT_CRITICAL() from another thread will re-enable interrupts once taskDISABLE_INTERRUPTS() has been called [I think!?]--rather, one would have to explicitly (and accidentally) call taskENABLE_INTERRUPTS() (ex: from another thread) to re-enable interrupts once taskDISABLE_INTERRUPTS() has been called. In other words, using the low-level taskDISABLE_INTERRUPTS() call is appropriate here because it will truly cause the system to sit in a loop, as desired, whereas taskENTER_CRITICAL() would not.
3.C. Mutexes and other OS (Operating System)-enabled synchronization primitives
Beyond the examples above, you can also use FreeRTOS queues (which are thread-safe, unlike all containers in the C++ std library), mutexes, semaphores, task notifications, and other synchronization primitives, where able and where appropriate, to protect certain data which is shared between FreeRTOS tasks (threads), assuming you are running FreeRTOS.
See the list of these tools here: https://www.freertos.org/a00106.html, and in the left-hand navigation menus once you click on that link.
4. TODO: mutex primitives: raw, OS-free spin locks via atomic set_and_test() (read, modify, write) instructions
Add an atomic test_and_set() (set_and_test() or read_modify_write() really makes more sense as a function name for this, I think) demo using ARM-core CMSIS functions, or assembly, or whatever means necessary, to demonstrate writing a spin lock in STM32. I don't know how to do this yet so it will require finding the right function or operation to use. See here: https://en.wikipedia.org/wiki/Test-and-set#Pseudo-C_implementation_of_a_spin_lock:
volatile int lock = 0;
void critical() {
// Spin lock: loop forever until we get the lock; we know the lock was
// successfully obtained after exiting this while loop because the
// test_and_set() function locks the lock and returns the previous lock
// value. If the previous lock value was 1 then the lock was **already**
// locked by another thread or process. Once the previous lock value
// was 0, however, then it indicates the lock was **not** locked before we
// locked it, but now it **is** locked because we locked it, indicating
// we own the lock.
while (test_and_set(&lock) == 1);
critical section // only one process can be in this section at a time
lock = 0; // release lock when finished with the critical section
}
Here is a spin lock implementation I did in C11 using _Atomic types. It should work just fine for STM32 as well, and probably compiles to use the underlying exclusive STREX/LDREX operations to store (write) and read (load), but I'd have to check that by looking at the assembly. Additionally, this implementation would need to be modified to add safety anti-deadlock mechanisms such as automatic deferral, timeout, and retry, to prevent deadlock. See my notes here: Add basic mutex (lock) and spin lock implementations in C11, C++11, AVR, and STM32
5. See also:
My answer on this for AVR mcus/Arduino
My answer on the general practice and demo of using atomic access guards, and my doAtomicRead() func which ensures atomic access withOUT turning interrupts off
[my Q&A] Which variable types/sizes are atomic on STM32 microcontrollers?
[my answer] Programing STM32 like STM8 (register-level GPIO)
Atomic access to shared variables should only be achieved by turning interrupts off where more modern alternatives are not available, or sometimes in very simple projects where performance and latency are not an issue.
Disabling interrupts increases the latency of the system in ways which are difficult to predict, and should be avoided wherever possible.
On ARMv7M and higher cores (including all STM32F1xx, STM32F2xx, STM32F3xx, STM32F4xx, STM32F7xx, STM32H7xx, STM32G4xx, STM32L1xx, STM32L4xx, SRM32L5xx, STM32U5xx) atomic access should be achieved using LDREX/STREX exclusive access instructions. Complex message queues and semaphore systems can be built upon these primitives which do not ever require to disable interrupts. For an example look at the semaphore implementation in mbed-os.
The other members of the STM32 family (STM32F0xx, STM32G0xx and STM32L0xx) may turn individual interrupts off using NVIC_EnableIRQ/NVIC_EnableIRQ or as a last resort turn all interrupts off with __disable_irq()/__enable_irq().
I have the following function initGPIO. The goal is to enable the GPIOs 0, 1 and 2 on beaglebone using am335x. How can I enable the corresponding GPIO set to the reg_GPIO that are given in the header file? I have the header file GPIO.h which contains the GPIO's numbers, register number and register structure. I have tried to set the GPIO in the function initGPIO. Does it make sense?
gpio.h
#include <stdint.h>
#include <stdbool.h>
#define GPIO0 0 /*!< GPIO 0 number */
#define GPIO1 1 /*!< GPIO 1 number */
#define GPIO2 2 /*!< GPIO 2 number */
#define GPIO3 3 /*!< GPIO 3 number */
// Base address for each gpio hardware module.
#define GPIO0_REG 0x44E07000 //<! gpio0 hardware module address.
#define GPIO1_REG 0x4804C000 //<! gpio1 hardware module address.
#define GPIO2_REG 0x481AC000 //<! gpio2 hardware module address.
#define GPIO3_REG 0x481AE000 //<! gpio3 hardware module address.
// Register Structure
typedef struct
{
volatile uint32_t irqstatus_set_0; // Offset 0x34 - Enables specific interrupt event to trigger.
volatile uint32_t irqstatus_set_1; // Offset 0x38 - Enables specific interrupt event to trigger.
volatile uint32_t irqwaken_0; // Offset 0x44 - Enables wakeup events on an interrupt.
volatile uint32_t irqwaken_1; // Offset 0x48 - Enables wakeup events on an interrupt.
volatile uint32_t ctrl; // Offset 0x130 - Controls clock gating functionality, i.e. enables module.
volatile uint32_t oe; // Offset 0x134 – Output Enable pin (clear bit to 0) output capability.
volatile uint32_t datain; // Offset 0x138 - Registers data read from the GPIO pins.
volatile uint32_t dataout; // Offset 0x13c - Sets value of GPIO output pins.
volatile uint32_t cleardataout; // Offset 0x190 - Clears to 0 bits in dataout
volatile uint32_t setdataout; // Offset 0x194 - Sets to 1 bits in dataout
} GPIO_REGS;
void initGPIO();
gpio.c
/*!
* \brief Initialize GPIOs.
*
* Enables GPIO0, GPIO1, and GPIO2 (GPIO3 not used in IDP. Also configures the output pins
* used in the IDP to control relays and address the ADC's on relays.
*
*****************************************************************************************/
void initGPIO()
{
//enable GPIOs
GPIO_REGS gpio_regs;
//might need to change ctrl
gpio_regs.datain |= (GPIO0 << GPIO0_REG );
gpio_regs.datain |= (GPIO1 << GPIO1_REG );
gpio_regs.datain |= (GPIO2 << GPIO2_REG );
}
By default Beaglebones come with Debian Linux. Unless you've decided to drop that, the kernel has a GPIO driver which assumes control of all GPIO. You should not try to access raw GPIO registers directly, but rather talk to the kernel driver. The simplest way to do that is to install libgpiod (which may be installed by default on recent Beagles) and call its API.
For bare bone platforms you may be used to do something like this to access hardware addresses:
volatile GPIO_REGS* gpio1_regs = (GPIO_REGS*)0x44E07000;
volatile GPIO_REGS* gpio2_regs = (GPIO_REGS*)0x4804C000;
Now your code isn't doing this either, but I'm going to assume that is what you meant.
Except inside an OS the memory offsets in you user-space application don't map one-on-one to hardware address offsets and this simply won't work.
If you want direct register access to things like this, you'll have to do something like Memory Mapping using /dev/mem or if your platform supports it, /dev/gpiomem (I know Raspberry Pi supports this, I'm not sure about the BBB). This will check if you are allowed to access the hardware address range you want, as well as make sure the address range is mapped correctly in your user-space.
For example:
/* open /dev/mem */
int fd = open("/dev/mem", O_RDWR|O_SYNC);
if (fd >= 0) {
/* mmap GPIO */
volatile GPIO_REGS* gpio1_regs = mmap(NULL, getpagesize(), PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0x44E07000);
close(fd); /* No need to keep fd open after mmap */
/* Check for MAP_FAILED error */
if (gpio1_regs != (GPIO_REGS*)-1) {
/* Do whatever */
(The last argument to mmap is where you place your hardware address, I'm using 0x44E07000 in this example.)
For further reading, see also:
https://man7.org/linux/man-pages/man2/mmap.2.html
https://pagefault.blog/2017/03/14/access-hardware-from-userspace-with-mmap/
I have an Arduino device that runs on the Nordic SDK (it's a Red Bear Lab BLE nano). I want to be able to do a serial print into GTKTerm to be able to debug what is going on in my code. To do this I have the following code:
/*
* Copyright (c) 2014 Nordic Semiconductor. All Rights Reserved.
*
* The information contained herein is confidential property of Nordic Semiconductor. The use,
* copying, transfer or disclosure of such information is prohibited except by express written
* agreement with Nordic Semiconductor.
*
*/
/**
* #brief BLE Heart Rate Collector application main file.
*
* This file contains the source code for a sample heart rate collector.
*/
#include <stdint.h>
#include <stdio.h>
#include <string.h>
#include "nordic_common.h"
#include "nrf_sdm.h"
#include "ble.h"
#include "ble_hci.h"
#include "ble_db_discovery.h"
#include "softdevice_handler.h"
#include "app_util.h"
#include "app_error.h"
#include "boards.h"
#include "nrf_gpio.h"
#include "pstorage.h"
#include "device_manager.h"
#include "app_trace.h"
#include "ble_hrs_c.h"
#include "ble_bas_c.h"
#include "app_util.h"
#include "app_timer.h"
#include "bsp.h"
#include "bsp_btn_ble.h"
#define UART_TX_BUF_SIZE 256 /**< UART TX buffer size. */
#define UART_RX_BUF_SIZE 1 /**< UART RX buffer size. */
#define STRING_BUFFER_LEN 50
#define BOND_DELETE_ALL_BUTTON_ID 0 /**< Button used for deleting all bonded centrals during startup. */
#define APP_TIMER_PRESCALER 0 /**< Value of the RTC1 PRESCALER register. */
#define APP_TIMER_MAX_TIMERS (2+BSP_APP_TIMERS_NUMBER) /**< Maximum number of simultaneously created timers. */
#define APP_TIMER_OP_QUEUE_SIZE 2 /**< Size of timer operation queues. */
#define APPL_LOG app_trace_log /**< Debug logger macro that will be used in this file to do logging of debug information over UART. */
#define SEC_PARAM_BOND 1 /**< Perform bonding. */
#define SEC_PARAM_MITM 1 /**< Man In The Middle protection not required. */
#define SEC_PARAM_IO_CAPABILITIES BLE_GAP_IO_CAPS_NONE /**< No I/O capabilities. */
#define SEC_PARAM_OOB 0 /**< Out Of Band data not available. */
#define SEC_PARAM_MIN_KEY_SIZE 7 /**< Minimum encryption key size. */
#define SEC_PARAM_MAX_KEY_SIZE 16 /**< Maximum encryption key size. */
#define SCAN_INTERVAL 0x00A0 /**< Determines scan interval in units of 0.625 millisecond. */
#define SCAN_WINDOW 0x0050 /**< Determines scan window in units of 0.625 millisecond. */
#define MIN_CONNECTION_INTERVAL MSEC_TO_UNITS(7.5, UNIT_1_25_MS) /**< Determines minimum connection interval in millisecond. */
#define MAX_CONNECTION_INTERVAL MSEC_TO_UNITS(30, UNIT_1_25_MS) /**< Determines maximum connection interval in millisecond. */
#define SLAVE_LATENCY 0 /**< Determines slave latency in counts of connection events. */
#define SUPERVISION_TIMEOUT MSEC_TO_UNITS(4000, UNIT_10_MS) /**< Determines supervision time-out in units of 10 millisecond. */
#define TARGET_UUID 0x180D /**< Target device name that application is looking for. */
#define MAX_PEER_COUNT DEVICE_MANAGER_MAX_CONNECTIONS /**< Maximum number of peer's application intends to manage. */
#define UUID16_SIZE 2 /**< Size of 16 bit UUID */
/**#breif Macro to unpack 16bit unsigned UUID from octet stream. */
#define UUID16_EXTRACT(DST, SRC) \
do \
{ \
(*(DST)) = (SRC)[1]; \
(*(DST)) <<= 8; \
(*(DST)) |= (SRC)[0]; \
} while (0)
/**#brief Variable length data encapsulation in terms of length and pointer to data */
typedef struct
{
uint8_t * p_data; /**< Pointer to data. */
uint16_t data_len; /**< Length of data. */
}data_t;
typedef enum
{
BLE_NO_SCAN, /**< No advertising running. */
BLE_WHITELIST_SCAN, /**< Advertising with whitelist. */
BLE_FAST_SCAN, /**< Fast advertising running. */
} ble_scan_mode_t;
static ble_db_discovery_t m_ble_db_discovery; /**< Structure used to identify the DB Discovery module. */
static ble_hrs_c_t m_ble_hrs_c; /**< Structure used to identify the heart rate client module. */
static ble_bas_c_t m_ble_bas_c; /**< Structure used to identify the Battery Service client module. */
static ble_gap_scan_params_t m_scan_param; /**< Scan parameters requested for scanning and connection. */
static dm_application_instance_t m_dm_app_id; /**< Application identifier. */
static dm_handle_t m_dm_device_handle; /**< Device Identifier identifier. */
static uint8_t m_peer_count = 0; /**< Number of peer's connected. */
static ble_scan_mode_t m_scan_mode = BLE_FAST_SCAN; /**< Scan mode used by application. */
static uint16_t m_conn_handle; /**< Current connection handle. */
static volatile bool m_whitelist_temporarily_disabled = false; /**< True if whitelist has been temporarily disabled. */
static bool m_memory_access_in_progress = false; /**< Flag to keep track of ongoing operations on persistent memory. */
/**
* #brief Connection parameters requested for connection.
*/
static const ble_gap_conn_params_t m_connection_param =
{
(uint16_t)MIN_CONNECTION_INTERVAL, // Minimum connection
(uint16_t)MAX_CONNECTION_INTERVAL, // Maximum connection
0, // Slave latency
(uint16_t)SUPERVISION_TIMEOUT // Supervision time-out
};
static void scan_start(void);
#define APPL_LOG app_trace_log /**< Debug logger macro that will be used in this file to do logging of debug information over UART. */
/**#brief Function for initializing the UART.
*/
static void uart_init(void)
{
uint32_t err_code;
const app_uart_comm_params_t comm_params =
{
RX_PIN_NUMBER,
TX_PIN_NUMBER,
RTS_PIN_NUMBER,
CTS_PIN_NUMBER,
APP_UART_FLOW_CONTROL_ENABLED,
false,
UART_BAUDRATE_BAUDRATE_Baud38400
};
APP_UART_FIFO_INIT(&comm_params,
UART_RX_BUF_SIZE,
UART_TX_BUF_SIZE,
uart_error_handle,
APP_IRQ_PRIORITY_LOW,
err_code);
APP_ERROR_CHECK(err_code);
app_trace_init();
}
/** #brief Function for the Power manager.
*/
static void power_manage(void)
{
uint32_t err_code = sd_app_evt_wait();
APP_ERROR_CHECK(err_code);
}
int main(void)
{
bool erase_bonds;
// Initialize.
uart_init();
printf("Heart rate collector example (this is a custom log)\r\n");
for (;; )
{
power_manage();
}
}
The problem I am having is that only sometimes I will see an output in GTKterm. I am unable to find a pattern for when it works and when it doesn't. How would I go about debugging this?
How would I go about debugging this?
Some suggestions for starters:
Ensure that your terminal software is asserting the DTR signal. That was the solution found here.
Temporarily remove the call to power_manage() to ensure that is not part of the problem.
Change APP_UART_FLOW_CONTROL_ENABLED for APP_UART_FLOW_CONTROL_DISABLED to determine whether it is a flow control issue. You will not need flow control for output to a PC in any case. It may be needed if you are inputting to the device (especially with a buffer length of 1) or if you are sending to data to a slow device with limited buffering.
Verify ERR_CODE after calling APP_UART_FIFO_INIT to ensure no problems occurred at that stage. Possible error codes are defined here.
I'm working on a developing board that has a 32-bit ARM based microntroller on it (namely the board is Atmel SAM D21J18A). I'm still at the learning phase and I have a lot to go, but I'm really into embedded systems.
I have some background in C. However, it's obviously not enough. I was looking at the codes of an example project by Atmel, and I didn't really get some parts of it. Here is one of them:
#define PORT ((Port *)0x41004400UL) /**< \brief (PORT) APB Base Address */
Port is defined as:
typedef struct {
PortGroup Group[2]; /**< \brief Offset: 0x00 PortGroup groups [GROUPS] */
} Port;
and PortGroup is defined as:
typedef struct {
__IO PORT_DIR_Type DIR; /**< \brief Offset: 0x00 (R/W 32) Data Direction */
__IO PORT_DIRCLR_Type DIRCLR; /**< \brief Offset: 0x04 (R/W 32) Data Direction Clear */
__IO PORT_DIRSET_Type DIRSET; /**< \brief Offset: 0x08 (R/W 32) Data Direction Set */
__IO PORT_DIRTGL_Type DIRTGL; /**< \brief Offset: 0x0C (R/W 32) Data Direction Toggle */
__IO PORT_OUT_Type OUT; /**< \brief Offset: 0x10 (R/W 32) Data Output Value */
__IO PORT_OUTCLR_Type OUTCLR; /**< \brief Offset: 0x14 (R/W 32) Data Output Value Clear */
__IO PORT_OUTSET_Type OUTSET; /**< \brief Offset: 0x18 (R/W 32) Data Output Value Set */
__IO PORT_OUTTGL_Type OUTTGL; /**< \brief Offset: 0x1C (R/W 32) Data Output Value Toggle */
__I PORT_IN_Type IN; /**< \brief Offset: 0x20 (R/ 32) Data Input Value */
__IO PORT_CTRL_Type CTRL; /**< \brief Offset: 0x24 (R/W 32) Control */
__O PORT_WRCONFIG_Type WRCONFIG; /**< \brief Offset: 0x28 ( /W 32) Write Configuration */
RoReg8 Reserved1[0x4];
__IO PORT_PMUX_Type PMUX[16]; /**< \brief Offset: 0x30 (R/W 8) Peripheral Multiplexing n */
__IO PORT_PINCFG_Type PINCFG[32]; /**< \brief Offset: 0x40 (R/W 8) Pin Configuration n */
RoReg8 Reserved2[0x20];
} PortGroup;
So here, we are looking at the address 0x41004400UL, get the data in there, and then what happens?
I looked up for this but couldn't find anything useful. If you have any suggestions (tutorials, books etc.), please let me hear.
Nothing happens, because you only present some declarations. I'm not entirely sure what the question actually is, but to briefly explain that code:
0x41004400UL is obviously an address in I/O space (not regular memory) where a port starts (a set of I/O registers)
This Port consists of two groups with a similar arrangement of single registers
struct PortGroup models these registers exactly in the layout present on the hardware
To know the meaning of the Registers, look up the hardware documentation.
Generally you can access a hardware register in C in this manner:
#define PORT (*(volatile uint8_t*)0x1234)
0x1234 is the register address
uint8_t is the type of the register, in this case 1 byte large.
volatile is required so that the compiler knows it cannot optimize such a variable, but that each read or write to the variable stated in the code must actually be done.
(volatile uint8_t*) casts the integer literal to an address of the desired type.
The left-most * then take the contents of that address, so that the macro can be used just as if PORT was a regular variable.
Note that this does not allocate anything! It just assumes that there is a hardware register present at the given address, which can be accessed by the type specified (uint8_t).
Using the same method you can also have other C data types to correspond directly hardware registers. For example by using a handy struct, you can map the whole register area of a particular hardware peripheral. Such code is however a bit dangerous and questionable, since it must take things like alignment/struct padding and aliasing in account.
As for the specific code in your example, it is a typical awful register map for a particular hardware peripheral (looks like a plain general-purpose I/O port) on a certain microcontroller. One such beast is typically provided with each compiler supporting the MCU.
Such register maps are sadly always written in awful, completely non-portable ways. For example, two underscores __ is a forbidden identifier in C. Neither the compiler nor the programmer is allowed to declare such identifiers (7.1.3).
What's really strange is that they have omitted the volatile keyword. This means that you have one of these scenarios here:
The volatile keyword is hidden beneath the Port definition. Most likely this is the case, or
The register map is full of fatal bugs, or
The compiler is such an awful piece of crap that it doesn't optimize variables at all. Which would make the issues with volatile go away.
I would investigate this further.
As for struct padding and aliasing, the compiler vendor has likely implicitly assumed that only their compiler is to be used. They have no interest in providing you with a portable register map, so that you can switch the the competitor's compiler for the same MCU.