Application Note: JN-AN-1040

Application Note: JN-AN-1040 Using DIO Interrupts

This Application Note describes how to use DIO interrupts on a Jennic wireless microcontroller. It describes the differences between using Application Callbacks and the Application Queue API, and is organised as follows: Differences between Application Queue API and Application Callback methods Initialisation and enabling interrupts Registering a callback function Using masks to determine the interrupt source

Application Overview
The interrupt handling mechanisms described in this document are demonstrated in the example source files supplied in the .zip file for this Application Note: example1.c uses the Application Queue API example2.c uses Application Callbacks

Interrupt Handling Mechanisms

Interrupts can be handled using either the Application Queue API or Application Callbacks defined in the Integrated Peripherals API. These mechanisms are outlined below.

Application Queue API

The Application Queue API can only be used with the IEEE 802.15.4 stack. It provides a queue-based interface between an application and both the stack and hardware drivers. The API handles all interrupts from the IEEE 802.15.4 MAC sub-layer and on-chip peripherals, packaging them and placing them in one of three specific queues which are regularly polled. Application code is added by the user to process an interrupt after a poll. For detailed information, refer to the Application Queue API Reference Manual (JN-RM-2025).

Application Callbacks
Callbacks are functions defined by the user that are passed to the Integrated Peripherals API. When an interrupt occurs, these functions are called directly by the underlying software. However, since the callback functions operate in interrupt context, they must return quickly so as not to delay program execution. This can mean that the Application Queue API is sometimes more suitable, since it takes interrupt processing out of interrupt context. Reference material for registering callbacks is available in the Integrated Peripherals API Reference Manual (JN-RM-2001).

JN-AN-1040 (v1.0) 11-Dec-2006

Jennic 2006

Jennic
Initialisation and Enabling Interrupts

Application Note: JN-AN-1040

The application initialisation process varies slightly depending on which method is used to handle interrupts. Using Application Callbacks: In this case, the function u32AppApiInit() must be called (parameters that are not used can be set to NULL as seen in the source code example2.c). This call ensures that the interrupt vector tables are initialised correctly - for more details of the parameters to this call, see the 802.15.4 Stack API Reference Manual (JN-RM-2002). The callback function also needs to be registered. This function will then be called when an interrupt occurs. The process for this registration is described in the next section of this Application Note. Using Application Queue API: In this case, the function u32AppQApiInit() must be called, which initialises the Application Queue API interfaces (as seen in the source code example1.c). Apart from the above differences, the initialisation code in the examples is identical in the following aspects: Setting the direction of the required pins in this case, DIO9 is connected to SW1 and will therefore be an input, while DIO14 is connected LED1 and will be an output:
vAHI_DioSetDirection(E_AHI_DIO9_INT, 0); vAHI_DioSetDirection(0, E_AHI_DIO14_INT);

Initialising the state of input and output pins that is, enabling pull-ups for inputs and turning the LED off by driving the output DIO14 high:
vAHI_DioSetPullup(!E_AHI_DIO14_INT, E_AHI_DIO14_INT); vAHI_DioSetOutput(E_AHI_DIO14_INT, 0);

Setting the interrupt condition that is, whether the interrupt occurs on a rising edge or a falling edge. In the example, the interrupt is triggered on a rising edge:
vAHI_DioInterruptEdge(E_AHI_DIO9_INT, 0);

Finally, enabling the interrupt itself:

vAHI_DioInterruptEnable(E_AHI_DIO9_INT, 0);

Registering a Callback Function

Registering a callback function involves passing a pointer to the interrupt handling function as a parameter of the register function. This is demonstrated on line 89 in example2.c:
vAHI_SysCtrlRegisterCallback(vDIOInterruptCallback);

Here, a pointer to vDIOInterruptCallback() is passed as the parameter. The function vDIOInterruptCallback() is now responsible for interrupt handling, and must also conform to the PR_HWINT_APPCALLBACK type. This means that it must not have a return value and must accept two uint32 parameters. Therefore, vDIOInterruptCallback() is defined as:
PRIVATE void vDIOInterruptCallback (uint32 u32Device, uint32 u32ItemBitmap);

Jennic 2006

JN-AN-1040 (v1.0) 11-Dec-2006

Application Note: JN-AN-1040

Jennic

Using Masks to Determine Interrupt Source

Once an interrupt has occurred, the source of the interrupt can be determined by using masks against the information provided by the stack, i.e. the device ID (u32Device) and the item bitmap (u32ItemBitmap). The device ID identifies which device has generated the interrupt and the item bitmap indicates the source within the device. Tables that show the range of possible values are provided in the Integrated Peripherals API Reference Manual (JN-RM-2001). This process is illustrated in both example programs - in the vProcessIncomingHwEvent() function of example1.c and in the vDIOInterruptCallback() function of example2.c:
if ( (u32Device == E_AHI_DEVICE_SYSCTRL) && (u32ItemBitmap & E_AHI_DIO9_INT) )

Here the code is filtering for system controller interrupts caused by DIO9. The system controller handles interrupts from the comparator, wake timers and DIO. Therefore, to determine the source, the item bitmap is compared against the mask for DIO9. Once the source has been determined, the interrupt can be processed as appropriate.

Building and Downloading an Application

To build and download one of the example applications, follow the instructions below: 1. Ensure that the project directory is located in <JENNIC_SDK_ROOT>\cygwin\jennic\developer where <JENNIC_SDK_ROOT> is the path into which the Jennic SDK was installed (by default, this is C:\Jennic). 2. Build the application using either the supplied makefile, located in the Build directory, or the supplied Code::Blocks project file (.cbp file) for the example these files for the example are numbered appropriately (1 or 2). The Code::Blocks file is designed to be used only with the version of the Code::Blocks IDE available from the Support area of the Jennic web site. Download the resulting binary file to the board. You can do this using the Jennic JN51xx Flash Programmer application or directly from Code::Blocks.

3.

Caution: If problems occur when using your current Code::Blocks version, download the new version along with the latest version of this Application Note from the Support area of the Jennic web site (www.jennic.com/support).

JN-AN-1040 (v1.0) 11-Dec-2006

Jennic 2006

Jennic
Revision History
Version 1.0 Notes Initial release

Application Note: JN-AN-1040

Corporate Headquarters Furnival Street Sheffield S1 4QT United Kingdom Tel +44 (0)114 281 2655 Fax +44 (0)114 281 2951 E-mail info@jennic.com United States Sales Office 1322 Scott Street, Suite 203 Point Loma CA 92106 USA Tel +1 619 223 2215 Fax +1 619 223 2081 E-mail info@us.jennic.com

Japan Sales Office Osakaya building 4F 1-11-8 Higashigotanda Shinagawa-ku, Tokyo 141-0022, Japan Tel +81 3 5449 7501 Fax +81 3 5449 0741 E-mail info@jp.jennic.com United States Sales Office 1060 First Avenue, Suite 400 King of Prussia PA 19406 USA Tel +1 619 223 2215 Fax +1 619 223 2081 E-mail info@us.jennic.com

Taiwan Sales Office 19F-1, 182, Sec.2 Tun Hwa S. Road Taipei 106 Taiwan Tel +886 2 2735 7357 Fax +886 2 2739 5687 E-mail info@tw.jennic.com

Jennic 2006

JN-AN-1040 (v1.0) 11-Dec-2006