This section introduces the Nested Vectored Interrupt Controller(NVIC) HAL APIs including terms and acronyms, details on how to use this driver, supported features, enums, structures and functions. More...

Overview

This section introduces the Nested Vectored Interrupt Controller(NVIC) HAL APIs including terms and acronyms, details on how to use this driver, supported features, enums, structures and functions.

NVIC usage follows the CMSIS except it doesn't support direct registration of ISR in the vector table, but it uses hal_nvic_register_isr_handler function to improve software efficiency and debugging.

Terms and acronyms

Terms	Details
NVIC	Nested Vectored Interrupt Controller. NVIC is the interrupt controller of ARM Cortex-M4. For more details, please refer to NVIC introduction in ARM Cortex-M4 Processor Technical Reference Manual .
ISR	Interrupt service routine.
IRQ	Interrupt request.
CMSIS	Cortex Microcontroller Software Interface Standard. For more information, please refer to CMSIS .

How to use this driver

Using the NVIC.
- Step 1. Call the hal_nvic_init() function to initialize the NVIC IRQ priority according to the exception number. By default, the lower the exception number the higher is the priority.
- Step 2. Call the hal_nvic_register_isr_handler() function to register an ISR handler before using the NVIC IRQ.
- Step 3. Use CMSIS interface to adjust the IRQ priority, if needed.
- Step 4. Call the hal_nvic_enable_irq() to enable the IRQ.
- Sample code:
  // Define a callback (an ISR) function.
  void isr_handler(hal_nvic_irq_t irq_number)
  {
  // Do something.
  }
  
  ret = hal_nvic_init(); // Should be called only once at initialization.
  if (HAL_NVIC_STATUS_OK != ret) {
  // Error handler;
  }
  ret = hal_nvic_register_isr_handler(irq_number, isr_handler); // Register an IRQ handler.
  if (HAL_NVIC_STATUS_OK != ret) {
  // Error handler;
  }
  hal_nvic_enable_irq(irq_number);
  // Change the IRQ priority (optional).
  hal_nvic_disable_irq(irq_number); // Disable the IRQ number.
  hal_nvic_set_priority(irq_number, DEFAULT_IRQ_PRIORITY); // Change the priority of the IRQ number, if needed.
  hal_nvic_enable_irq(irq_number); // Enable the IRQ number.
  
  void function_task(void)
  {
  // function_task() runs only in thread mode.
  }
  void function_isr(void)
  {
  // function_task() runs only in handler mode.
  }
  
  // It needs to take different actions according to the Cortex-M4 current exception status.
  if (HAL_NVIC_QUERY_EXCEPTION_NUMBER == 0) {
  // Cortex-M4 is in thread mode.
  function_task();
  } else {
  // Cortex-M4 is handling the exception and the exception number is HAL_NVIC_QUERY_EXCEPTION_NUMBER.
  function_isr();
  }
  
  // Preserve the original IRQ settings.
  void example(void)
  {
  uint32_t mask;
  hal_nvic_save_and_set_interrupt_mask(&mask); // Save the current IRQ settings.
  // Do something with the protected critical resource when the IRQ is disabled.
  hal_nvic_restore_interrupt_mask(mask); // Restore the IRQ settings.
  }
  void test(void)
  {
  uint32_t mask;
  hal_nvic_save_and_set_interrupt_mask(&mask); // Save the current IRQ settings.
  example();
  // The IRQ is still disabled;
  // Do something with the protected critical resouce when the IRQ is disabled.
  hal_nvic_restore_interrupt_mask(mask); // Restore the original IRQ settings in the mask.
  }

Functions
hal_nvic_status_t	hal_nvic_register_isr_handler (hal_nvic_irq_t irq_number, hal_nvic_isr_t isr_handler)
	This function is used to register a callback (an ISR) for NVIC IRQ. More...

hal_nvic_status_t	hal_nvic_init (void)
	This function initializes the NVIC IRQ with default priority. More...

hal_nvic_status_t	hal_nvic_enable_irq (hal_nvic_irq_t irq_number)
	This function enables a device-specific interrupt in the NVIC interrupt controller. More...

hal_nvic_status_t	hal_nvic_disable_irq (hal_nvic_irq_t irq_number)
	This function disables a device-specific interrupt in the NVIC interrupt controller. More...

uint32_t	hal_nvic_get_pending_irq (hal_nvic_irq_t irq_number)
	This function reads the pending register in the NVIC and returns the pending bit for the specified interrupt. More...

hal_nvic_status_t	hal_nvic_set_pending_irq (hal_nvic_irq_t irq_number)
	This function sets the pending bit of an external interrupt. More...

hal_nvic_status_t	hal_nvic_clear_pending_irq (hal_nvic_irq_t irq_number)
	This function clears the pending bit of an external interrupt. More...

hal_nvic_status_t	hal_nvic_set_priority (hal_nvic_irq_t irq_number, uint32_t priority)
	This function sets the priority of an interrupt. More...

uint32_t	hal_nvic_get_priority (hal_nvic_irq_t irq_number)
	This function reads the priority of an interrupt. More...

hal_nvic_status_t	hal_nvic_save_and_set_interrupt_mask (uint32_t *mask)
	This function saves the current IRQ settings in a temporary variable, and then disables the IRQ by setting the IRQ mask. More...

hal_nvic_status_t	hal_nvic_restore_interrupt_mask (uint32_t mask)
	This function restores the IRQ settings as specified in the mask. More...

Modules
	Define

	Enums

	Typedef

Function Documentation

hal_nvic_status_t hal_nvic_clear_pending_irq ( hal_nvic_irq_t irq_number )

This function clears the pending bit of an external interrupt.

Parameters

[in] irq_number is the NVIC IRQ number.

hal_nvic_status_t hal_nvic_disable_irq ( hal_nvic_irq_t irq_number )

This function disables a device-specific interrupt in the NVIC interrupt controller.

Parameters

[in] irq_number is the NVIC IRQ number.

hal_nvic_status_t hal_nvic_enable_irq ( hal_nvic_irq_t irq_number )

This function enables a device-specific interrupt in the NVIC interrupt controller.

Parameters

[in] irq_number is the NVIC IRQ number.

uint32_t hal_nvic_get_pending_irq ( hal_nvic_irq_t irq_number )

This function reads the pending register in the NVIC and returns the pending bit for the specified interrupt.

Parameters

[in] irq_number is the NVIC IRQ number.

Returns: To indicate whether this IRQ number is pending or not. If the return value is 0, the interrupt status is not pending. If the return value is 1, the interrupt status is pending. If the return value is other value, the IRQ number is invalid.

uint32_t hal_nvic_get_priority ( hal_nvic_irq_t irq_number )

This function reads the priority of an interrupt.

The interrupt number can be positive to specify an external (device specific) interrupt, or negative to specify an internal (core) interrupt.

Parameters

[in] irq_number is the NVIC IRQ number.

Returns: Interrupt Priority. Value is aligned automatically to the implemented priority bits of the microcontroller. If the return value is DEFAULT_IRQ_PRIORITY + 63, the IRQ number is invalid.

hal_nvic_status_t hal_nvic_init ( void )

This function initializes the NVIC IRQ with default priority.

The lower the exception number, the higher the priority.

hal_nvic_status_t hal_nvic_register_isr_handler	(	hal_nvic_irq_t	irq_number,
		hal_nvic_isr_t	isr_handler
	)

This function is used to register a callback (an ISR) for NVIC IRQ.

Parameters

[in]	irq_number	is the NVIC IRQ number.
[in]	isr_handler	is the NVIC IRQ's ISR.

Returns: To indicate whether this function call is successful. If the return value is HAL_NVIC_STATUS_OK, the operation completed successfully; If the return value is HAL_NVIC_STATUS_INVALID_PARAMETER, a wrong parameter is given, the parameter must be verified.

hal_nvic_status_t hal_nvic_restore_interrupt_mask ( uint32_t mask )

This function restores the IRQ settings as specified in the mask.

It should be used in conjunction with hal_nvic_save_and_set_interrupt_mask() to protect critical resources.

Parameters

[in] mask is an unsigned integer to specify the IRQ settings.

Returns: Indicates whether this function call is successful. If the return value is HAL_NVIC_STATUS_OK, the operation completed successfully; If the return value is HAL_NVIC_STATUS_INVALID_PARAMETER, a wrong parameter is given, the parameter must be verified.

hal_nvic_status_t hal_nvic_save_and_set_interrupt_mask ( uint32_t * mask )

This function saves the current IRQ settings in a temporary variable, and then disables the IRQ by setting the IRQ mask.

It should be used in conjunction with hal_nvic_restore_interrupt_mask() to protect the critical resources. When the IRQ is masked, please don't print any log, it maybe lead to some unexpected errors.

Parameters

[out] mask is used to store the current IRQ settings, upon the return of this function.

Returns: To indicate whether this function call is successful. If the return value is HAL_NVIC_STATUS_OK, the operation completed successfully. If the return value is HAL_NVIC_STATUS_INVALID_PARAMETER, a wrong parameter is given, the parameter must be verified.

hal_nvic_status_t hal_nvic_set_pending_irq ( hal_nvic_irq_t irq_number )

This function sets the pending bit of an external interrupt.

Parameters

[in] irq_number is the NVIC IRQ number.

hal_nvic_status_t hal_nvic_set_priority	(	hal_nvic_irq_t	irq_number,
		uint32_t	priority
	)

This function sets the priority of an interrupt.

Parameters

[in]	irq_number	is the NVIC IRQ number.
[in]	priority	is the priority to set.

Overview

Terms and acronyms

How to use this driver

Functions

Modules

Function Documentation