NVIC_Set_Interrupt_Priority: change to use 4-bit fields.

(viz STM32F10xxx Cortex-M3 programming manual PM0056 and
Cortex-M3-Generic-User-Guide.pdf)

Doxygen commentary added

include/libopencm3/stm32/f1/nvic_f1.h

@@ -27,6 +27,10 @@
  */
 
 /* User Interrupts */
+/** @defgroup nvic_stn32f1_userint STM32F1xx User Interrupts
+@ingroup STM32F_nvic_defines
+
+@{*/
 #define NVIC_WWDG_IRQ			0
 #define NVIC_PVD_IRQ			1
 #define NVIC_TAMPER_IRQ			2
@@ -95,5 +99,6 @@
 #define NVIC_CAN2_RX1_IRQ		65
 #define NVIC_CAN2_SCE_IRQ		66
 #define NVIC_OTG_FS_IRQ			67
+/*@}*/
 
 #endif

include/libopencm3/stm32/nvic.h

@@ -1,3 +1,26 @@
+/** @file
+
+@ingroup STM32F
+
+@brief <b>libopencm3 STM32F Nested Vectored Interrupt Controller</b>
+
+@version 1.0.0
+
+@author @htmlonly &copy; @endhtmlonly 2010 Piotr Esden-Tempski <piotr@esden.net>
+
+@date 8 July 2012
+
+LGPL License Terms @ref lgpl_license
+ */
+/** @defgroup STM32F_nvic_defines
+
+@brief Defined Constants and Types for the STM32F Nested Vectored Interrupt Controller
+
+@ingroup STM32F_defines
+
+LGPL License Terms @ref lgpl_license
+
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -65,6 +88,11 @@
 /* --- IRQ channel numbers-------------------------------------------------- */
 
 /* Cortex M3 System Interrupts */
+/** @defgroup nvic_sysint Cortex M3 System Interrupts
+@ingroup STM32F_nvic_defines
+
+IRQ numbers -3 and -6 to -9 are reserved
+@{*/
 #define NVIC_NMI_IRQ			-14
 #define NVIC_HARD_FAULT_IRQ		-13
 #define NVIC_MEM_MANAGE_IRQ		-12
@@ -76,9 +104,10 @@
 /* irq number -3 reserved */
 #define NVIC_PENDSV_IRQ			-2
 #define NVIC_SYSTICK_IRQ		-1
+/*@}*/
 
 
-/* Note: User interrupts are family specific and are defined in a familiy
+/* Note: User interrupts are family specific and are defined in a family
  * specific header file in the corresponding subfolder.
  */
 
@@ -103,6 +132,6 @@ void nvic_clear_pending_irq(u8 irqn);
 u8 nvic_get_active_irq(u8 irqn);
 u8 nvic_get_irq_enabled(u8 irqn);
 void nvic_set_priority(u8 irqn, u8 priority);
-void nvic_generate_software_interrupt(u8 irqn);
+void nvic_generate_software_interrupt(u16 irqn);
 
 #endif

lib/stm32/nvic.c

@@ -1,3 +1,25 @@
+/** @file
+
+@ingroup STM32F
+
+@brief <b>libopencm3 STM32F Nested Vectored Interrupt Controller</b>
+
+@version 1.0.0
+
+@author @htmlonly &copy; @endhtmlonly 2010 Thomas Otto <tommi@viadmin.org>
+@author @htmlonly &copy; @endhtmlonly 2012 Fergus Noble <fergusnoble@gmail.com>
+
+@date 7 July 2012
+
+The STM32F series provides up to 68 maskable user interrupts for the STM32F10x
+series, and 87 for the STM32F2xx and STM32F4xx series.
+
+The NVIC registers are defined by the ARM standards
+@see Cortex-M3 Devices Generic User Guide
+
+
+LGPL License Terms @ref lgpl_license
+*/
 /*
  * This file is part of the libopencm3 project.
  *
@@ -20,47 +42,122 @@
 
 #include <libopencm3/stm32/nvic.h>
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Enable Interrupt
+
+Enables a user interrupt.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+*/
+
 void nvic_enable_irq(u8 irqn)
 {
 	NVIC_ISER(irqn / 32) = (1 << (irqn % 32));
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Disable Interrupt
+
+Disables a user interrupt.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+*/
+
 void nvic_disable_irq(u8 irqn)
 {
 	NVIC_ICER(irqn / 32) = (1 << (irqn % 32));
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Return Pending Interrupt
+
+True if the interrupt has occurred and is waiting for service.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+@return Boolean. Interrupt pending.
+*/
+
 u8 nvic_get_pending_irq(u8 irqn)
 {
 	return NVIC_ISPR(irqn / 32) & (1 << (irqn % 32)) ? 1 : 0;
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Set Pending Interrupt
+
+Force a user interrupt to a pending state. No effect if the interrupt is already
+pending.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+*/
+
 void nvic_set_pending_irq(u8 irqn)
 {
 	NVIC_ISPR(irqn / 32) = (1 << (irqn % 32));
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Clear Pending Interrupt
+
+Force remove a user interrupt from a pending state. No effect if the interrupt is
+actively being serviced.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+*/
+
 void nvic_clear_pending_irq(u8 irqn)
 {
 	NVIC_ICPR(irqn / 32) = (1 << (irqn % 32));
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Return Active Interrupt
+
+Interrupt has occurred and is currently being serviced.
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+@return Boolean. Interrupt active.
+*/
+
 u8 nvic_get_active_irq(u8 irqn)
 {
 	return NVIC_IABR(irqn / 32) & (1 << (irqn % 32)) ? 1 : 0;
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Return Enabled Interrupt
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+@return Boolean. Interrupt enabled.
+*/
+
 u8 nvic_get_irq_enabled(u8 irqn)
 {
 	return NVIC_ISER(irqn / 32) & (1 << (irqn % 32)) ? 1 : 0;
 }
 
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Set Interrupt Priority
+
+@param[in] irqn Unsigned int8. Interrupt number @ref nvic_stn32f1_userint
+@param[in] priority Unsigned int8. Interrupt priority (0 ... 255)
+*/
+
 void nvic_set_priority(u8 irqn, u8 priority)
 {
-	NVIC_IPR(irqn) = priority;
+	NVIC_IPR(irqn / 4) = ((priority << ((irqn % 4) * 8));
 }
 
-void nvic_generate_software_interrupt(u8 irqn)
+/*-----------------------------------------------------------------------------*/
+/** @brief NVIC Software Trigger Interrupt
+
+Generate an interrupt from software. This has no effect for unprivileged access
+unless the privilege level has been elevated through the System Control Registers.
+
+@param[in] sgin Unsigned int16. Interrupt number (0 ... 239)
+*/
+
+void nvic_generate_software_interrupt(u16 irqn)
 {
 	if (irqn <= 239)
 		NVIC_STIR |= irqn;