QDK-nano PIC24/dsPIC-C30 - Quantum Leaps

QP state machine frameworks for PIC24/dsPIC 

QDK-nano 

PIC24/dsPIC-C30 

Document Revision C 

October 2012 

Copyright © Quantum Leaps, LLC 

www.quantum-leaps.com 

www.state-machine.com

Table of Contents 

1 Introduction ..................................................................................................................................................... 1 

1.1 About QP-nano ........................................................................................................................................... 2 

1.2 About the QP-nano Port to PIC24/dsPIC .................................................................................................... 3 

1.3 What’s Included in the QDK-nano-PIC24-dsPIC? .......................................................................................... 4 

1.4 Licensing QP-nano ..................................................................................................................................... 5 

2 Getting Started ................................................................................................................................................ 6 

2.1 Software Installation ....................................................................................................................................... 6 

2.2 Building and Running the Examples .............................................................................................................. 8 

3 Non-Preemptive “Vanilla” Port ...................................................................................................................... 10 

3.1 The qpn_port.h Header File ........................................................................................................................... 10 

3.2 ISRs in the Non-Preemptive “Vanilla” Configuration ...................................................................................... 11 

3.3 QP Idle Loop Customization in QF_onIdle() ................................................................................................... 13 

4 Preemptive Configuration with QK-nano ................................................................................................... 15 

4.1 QK-nano-specific ISR Entry and Exit Macros (file qpn_port.h) ....................................................................... 15 

4.2 ISRs with the Preemptive QK-nano Kernel .................................................................................................... 17 

4.3 Idle Loop Customization in the QK-nano Port ................................................................................................ 20 

4.4 Testing QK Preemption Scenarios ................................................................................................................. 21 

5 Implementing “Zero Interrupt Latency” with the NMI .................................................................................. 24 

5.1 Communication between NMIs and QP-nano ................................................................................................ 24 

5.2 Implementation Considerations for the NMIs ................................................................................................. 24 

6 BSP for the Explorer 16 Board ....................................................................................................................... 25 

6.1 Setting the Sizes of Stack and Heap .............................................................................................................. 25 

6.2 The BSP header file bsp.h ............................................................................................................................. 26 

6.3 BSP initialization ............................................................................................................................................ 26 

6.4 Starting Interrupts in QF_onStartup() ............................................................................................................. 26 

6.5 Assertion Handling Policy in Q_onAssert() .................................................................................................... 27 

7 Related Documents and References ............................................................................................................. 28 

8 Contact Information ........................................................................................................................................ 29 

Copyright © Quantum Leaps, LLC. All Rights Reserved. 

i

1 Introduction 

This QP-nano Development Kit (QDK-nano) describes how to use the QP-nano state machine 

framework with the Microchip PIC24/dsPIC MCUs/DSCs and the Microchip C30 compiler. 

USB cable 

to host PC 

Figure 1: Explorer 16 board with MPLAB ICD2 debugger 

MPLAB ICD2 

in-circuit debugger 

PIC24FJ128GA010 

or 

dsPIC33FJ256GP710 

target device 

Power LED 

9V DC power 

User LEDs 


1 of 29



www.state-machine.com/pic 

The actual hardware/software used to test this QDK-nano is described below (see Figure 1): 

1. Microchip Explorer 16 Development Board with PIC24FJ128GA010 or dsPIC33FJ256 daughter board 

2. Microchip MPLAB® ICD2 in-circuit debugger 

3. Microchip MPLAB® IDE v8.83 

4. Microchip MPLAB C30 compiler v3.31 

5. QP-nano 4.5.02 or higher 

As shown in Figure 1, the Explorer 16 Development Board accepts PIC24 and dsPIC daughter boards. 

The port has been tested with PIC24FJ128GA010 daughter board as well as with dsPIC33FJ256 

daughter board. However, the described QP port should be applicable to almost all Microchip 16-bit 

PIC24 and dsPIC devices. 

1.1 About QP-nano 

QP-nano is an ultra-lightweight, open source, state machine framework 

and RTOS for developing real-time embedded applications. QP-nano has 

been specifically designed to enable event-driven programming with 

concurrent hierarchical state machines (UML statecharts) on low-end 8- and 

16-bit single-chip MCUs and DSPs, such as PICmicro, PIC24/dsPIC, 8051, 

AVR, MSP430, 68HC08/11/12, R8C/Tiny, H8/S, TMS320C28x, Cypress 

PSoC, 8051 and others alike, with a few hundred bytes of RAM and a few 

kilobytes of ROM. With QP-nano, coding of modern state machines directly in 

C is a non-issue. No big design automation tools are needed. 

As shown in Figure 2, QP-nano consists of a universal UML-compliant event 

processor (QEP-nano), a highly portable event-driven framework (QF-nano), 

and a tiny run-to-completion kernel (QK-nano). 

Figure 2 QP-nano components and their relationship with the target hardware, board support 

package (BSP), and the application comprised of state machines 

State 

Machine 

State 

Machine 

State 

Machine 

State 

Machine 

Application 

(Your code) 

QEP-nano UML-Compliant 

Event Processor 

QF-nano Event-Driven 

Framework 

BSP 

QK-nano Preemptive Kernel, 

Cooperative Kernel, 

or other OS/RTOS 

Target 


2 of 29




The QP-nano framework can manage up to 8 concurrently executing hierarchical state machines and 

requires only 1-2KB of code (ROM) and just several bytes of RAM. This tiny footprint, especially in RAM, 

makes QP-nano ideal for high volume, cost-sensitive applications, such as motor control, lighting control, 

capacitive touch sensing, remote access control, RFID, thermostats, small appliances, toys, power 

supplies, battery chargers, or just about any system-on-a-chip (SoC or ASIC) that contains a small 

processor inside. 

Also, because the event-driven paradigm naturally uses the CPU only when handling events and 

otherwise can very easily switch the CPU into a low-power sleep mode, QP-nano is particularly suitable 

for ultra-low power applications, such as wireless sensor networks or implantable medical devices. 

All versions of QP, including QP-nano, are described in detail in the book "Practical UML Statecharts in 

C/C++, 2nd Edition: Event-Driven Programming for Embedded Systems" [PSiCC2] published by Newnes 

in 2008 (see www.state-machine.com/psicc2). QP-nano has a strong user community and has been 

applied worldwide in industries, such as: consumer electronics, telecommunications, equipment, industrial 

automation, transportation systems, medical devices, and many more. Please refer to the www.statemachine.com 

website for more information. 

1.2 About the QP-nano Port to PIC24/dsPIC 

Figure 3 shows the architecture of the QP-nano port to PIC24/dsPIC. The port takes advantage of the 

PIC24/dsPIC interrupt priority level (IPL) management hardware. In both cooperative and preemptive QPnano 

ports the hardware priority levels are allocated as follows: 

1. All QP-nano tasks (active objects) as well as the QP idle loop execute at the lowest IPL of zero. 

2. IPL levels 1 through 6 are used for maskable interrupts. These maskable interrupts (IPL 1..6) can call 

QP-nano services, such as QF_tick() and QActive_postISR(). The maskable interrupts can nest 

on each other, which is the default in PIC24/dsPIC. 

3. This QP-nano port never disables the IPL level 7, which is the Non-Maskable Interrupt (NMI) level. 

The NMI-level interrupt(s) cannot call any QP services. But the NMI can trigger a maskable interrupt, 

as shown by the dashed arrow in Figure 3. This triggered interrupt of IPL 1..6 can call QP-nano 

services for signaling the QP tasks (active objects). 

This layered software architecture fits very naturally with the PIC24/dsPIC hardware. The QP ports (both 

cooperative and preemptive) allow nesting of interrupts, which is the default in PIC24/dsPIC. Both 

cooperative and preemptive QP ports can work with the interrupt service routines (ISRs) generated by the 

C30 compiler, although the preemptive version requires special macros to be invoked upon entering and 

exiting ISRs. 

The interrupt locking policy is implemented very efficiently by means of the DISI instruction (see 

Section 3.1). As described in Section 8.2.3 of “PIC24F Family Reference Manual” [PIC24 Ref], “The DISI 

instruction only disables interrupts with priority levels 1-6. Priority level 7 interrupts and all trap events still 

have the ability to interrupt the CPU when the DISI instruction is active.” This means that interrupts with 

IPL of 7 are never disabled and thus run with “zero interrupt latency”. 

NOTE: Obviously, true “zero interrupt latency” is impossible to achieve. The term means here that 

the NMI-level interrupt(s) execute with the minimal latency achievable in PIC24/dsPIC hardware and 

that there is no additional latency added to the NMI-level interrupt(s) because of interrupt locking in 

QP. 

The use of NMI to achieve “zero interrupt latency” is explained in Section 5. 


3 of 29




Figure 3: Architecture of the PIC24/dsPIC port 

(IPL = 7) Non-Maskable Interrupt (NMI) 

IPL Level 7 

(NMI level) 

(IPL = 6) User interrupt 



IPL Levels 1-6 

(interrupt level) 




(QP prio = n) User task (active object) 

(QP prio = n-1) User task (active object) 

. . . 

(QP prio = 2) User task (active object) 

IPL Level 0 

(task level) 

(QP prio = 1) User task (active object) 

(QP prio = 0) Idle task 

1.3 What’s Included in the QDK-nano-PIC24-dsPIC? 

This QDK provides a basic Board Support Package (BSP) for PIC24 and dsPIC MCUs and two versions 

of the PEdestrian LIght CONtroller (PELICAN) crossing example for each processor. The PELICAN 

application is described in Chapter 12 of [PSiCC2] as well as in the Application Note “PEdestrian LIght 

CONtroller (PELICAN) Crossing” [QL AN-PELICAN 08] (included in the QDK-nano distribution): 

 

 

 

 

The PELICAN crossing example with the cooperative “vanilla” kernel for PIC24FJ128GA010; 

The PELICAN crossing example with the preemptive QK-nano kernel for PIC24FJ128GA010; 

The PELICAN crossing example with the cooperative “vanilla” kernel for dsPIC33FJ256GP710; and 

The PELICAN crossing example with the preemptive QK-nano kernel for dsPIC33FJ256GP710. 


4 of 29




1.4 Licensing QP-nano 

The Generally Available (GA) distribution of QP-nano available for download from the www.statemachine.com/downloads 

website is offered with the following two licensing options: 

 

 

The GNU General Public License version 2 (GPL) as published by the Free 

Software Foundation and appearing in the file GPL.TXT included in the packaging of 

every Quantum Leaps software distribution. The GPL open source license allows 

you to use the software at no charge under the condition that if you redistribute the 

original software or applications derived from it, the complete source code for your 

application must be also available under the conditions of the GPL (GPL Section 

2[b]). 

One of several Quantum Leaps commercial licenses, which are designed for 

customers who wish to retain the proprietary status of their code and therefore cannot 

use the GNU General Public License. The customers who license Quantum Leaps 

software under the commercial licenses do not use the software under the GPL and 

therefore are not subject to any of its terms. 

For more information, please visit the licensing section of our website at: www.statemachine.com/licensing. 


5 of 29




2 Getting Started 

This section describes how to install, build, and use QDK-PIC24-dsPIC-C30. 

2.1 Software Installation 

The QDK-nano code is distributed in a ZIP archive (qdkn_pic24_dspic-c30_.zip, where 

stands for a specific QDK-nano version, such as 4.0.04). You can uncompress the archive into any 

directory. The installation directory you choose will be referred henceforth as . The following 

shows the directory structure and selected files included in the QP-nano distribution. (Please note that the 

QP-nano directory structure is described in detail in a separate Quantum Leaps Application Note: “QP 

Directory Structure”). 

NOTE: Every QDK-nano contains only example(s) pertaining to the specific MCU and compiler, but 

does not include the platform-independent baseline code of QP-nano, which is available for a 

separate download. It is strongly recommended that you read Chapter 12 in [PSiCC2] before you 

start with this QDK-nano. 

Listing 1: Selected QP directories and files after installing QDK-nano-PIC24/dsPIC-C30 

/ 

- QP-nano Root Directory 

| 

+-doc\ 

| +-AN_PELICAN.pdf - Application Note “PELICAN crossing example” 

| +-QDKn_PIC24-dsPIC.pdf – This QDK-nano Manual “QDK-nano PIC24-dsPIC-C30” 

| 

+-examples\ 

- subdirectory containing the QP example files 

| +-pic24_dspic\ - PIC24/dsPIC examples 

| | +-mplab-c30\ - Microchip MPLAB C30 compiler 

| | | +-pelican-explorer16_pic24\ - PELICAN example for Explorer 16 with PIC24 

| | | | +-dbg\ - directory containing the Debug build 

| | | | | +-pelican-dbg.cof - image of the application 

| | | | | +-pelican-dbg.map - map file of the application 

| | | | +-rel\ - directory containing the Release build 

| | | | | 

| | | | +-bsp.c - BSP for Explorer 16 with PIC24FJ128GA010 

| | | | +-bsp.h - BSP header file 

| | | | +-main.c - the main function 

| | | | +-pelican.c - the PELICAN active objects 

| | | | +-pelican.h - the PELICAN application header file 

| | | | +-ped.c - the Pedestrian active object 

| | | | +-pelican-dbg.mcp – MPLAB project for Debug configuration 

| | | | +-pelican-rel.mcp – MPLAB project for Release configuration 

| | | | +-pelican-explorer16_pic24.mcw – MPLAB workspace for the application 

| | | | +-p24FJ128GA010.gld - Linker script for PIC24FJ128GA010 

| | | | +-qpn_port.h - QP-nano port to PIC24FJ128GA010 with Vanilla kernel 

| | | | | 

| | | +-pelican-explorer16_dspic\ - PELICAN example for Explorer 16 with dsPIC 






6 of 29




| | | | | 









| | | | +-pelican-explorer16_dspic.mcw – MPLAB workspace for the application 

| | | | +-p33FJ256GP710.gld - Linker script for dsPIC33FJ256GP710 

| | | | +-qpn_port.h - QP-nano port to dsPIC33FJ256GP710 with Vanilla kernel 

| | | 

| | | +-pelican-qk-explorer16_pic24\ - PELICAN example for Explorer 16 with QK 





| | | | | 









| | | | +-pelican-qk-explorer16_pic24.mcw – MPLAB workspace for the application 

| | | | +-p24FJ128GA010.gld - Linker script for PIC24FJ128GA010 

| | | | +-qpn_port.h - QP-nano port to PIC24FJ128GA010 with QK-nano kernel 

| | | | 

| | | +-pelican-qk-explorer16_dspic\ - PELICAN example for Explorer 16 with QK 





| | | | | 









| | | | +-pelican-qk-explorer16_dspic.mcw – MPLAB workspace for the application 

| | | | +-p33FJ256GP710.gld - Linker script for dsPIC33FJ256GP710 

| | | | +-qpn_port.h - QP-nano port to dsPIC33FJ256GP710 with QK-nano kernel 


7 of 29




2.2 Building and Running the Examples 

The examples included in this QDK-nano are based on the standard PELICAN crossing application 

implemented with active objects (see Quantum Leaps Application Note: “PEdestrian LIght CONtrolled 

(PELICAN) Crossing Example” [QL AN-PELICAN 08] included in this QDK-nano). The example directory 

contains the MPLAB workspaces and project file that you can load into the MPLAB IDE, as shown in 

Figure 4. 

Figure 4: The MPLAB IDE with the PELICAN example 

Program 

target device 

button 

Select project 

for the build 

configuration 

2.2.1 Building the Example Projects in the MPLAB IDE 

1. Connect the Explorer 16 board to the MPLAB ICD 2 In-Circuit debugger and to the PC as described 

in the Quick Start Guide. 

2. Connect the USB cable between the MPLAB ICD 2 In-Circuit Debugger and the PC. 

3. Open the MPLAB IDE and open the project pelican-dbg.mcp (located in \examples\- 

pic24_dspic\mplab-c30\pelican-explorer16_pic24\). Figure 4 shows the screen shot of the 

MPLAB IDE after opening the project. 

4. Build the project by select Project->Make menu or by pressing F10. 


8 of 29




2.2.2 Programming the Example to Run under the MPLAB Debugger 

After a successful build, you can load the program to the target device by pressing the “Program Target 

Device” button, which is shown in Figure 4. 

2.2.3 Programming the Example to Run Standalone 

The DPP example application comes with the pelican-rel.mcp project, which is intended for 

standalone execution on the Explorer 16 board without the debugger. Once you activate and build this 

project in the MPLAB IDE, you need to de-select the ICD 2 as the Debugger and select ICD 2 as the 

Programmer (you cannot configure ICD 2 as a programmer and debugger simultaneously). To program 

the code into the PIC24/dsPIC device, you click the “Program Target Device” icon. After the programming 

is done, you can release the device out of reset by clicking the appropriate icon. You can also disconnect 

the ICD 2 completely and power-cycle the board. The programmed PELICAN application should start 

running standalone. 


9 of 29




3 Non-Preemptive “Vanilla” Port 

The example of using QP-nano with the cooperative “Vanilla” kernel is located in the directory: \- 

examples\pic24_dspic\mplab-c30\pelican-explorer16_pic24\ for PIC24 and \examples\- 

pic24_dspic\mplab-c30\pelican-explorer16_dspic\ for dsPIC. This section describes the generic 

QP-nano configuration, which consist of the qpn_port.h header file. The board-specific elements are 

common for both the non-preemptive and preemptive (QK-nano) configuration and will be covered in 

Section 6. 

3.1 The qpn_port.h Header File 

You configure and customize QP-nano through the header file qpn_port.h, which is included by the QPnano 

source files (qepn.c and qfn.c) as well as in all your application C modules. 

NOTE: The QP-nano port to the cooperative “Vanilla” kernel qpn_port.h is generic and should not 

need to change (except for the QF_MAX_ACTIVE definition) for other PIC24/dsPIC applications. 

Listing 2: qpn_port.h header file for the non-preemptive QP-nano configuration and C30 compiler 

(1) #define Q_NFSM 

(2) #define Q_PARAM_SIZE 2 

(3) #define QF_TIMEEVT_CTR_SIZE 2 

/* maximum # active objects--must match EXACTLY the QF_active[] definition */ 

(4) #define QF_MAX_ACTIVE 2U 

/* task-level interrupt nesting policy, see NOTE01 */ 

(5) #define QF_INT_LOCK() __asm__ volatile("disi #0x3FFF") 

(6) #define QF_INT_UNLOCK() __asm__ volatile("disi #0x0000") 

/* ISR-level interrupt locking policy for PIC24/dsPIC, see NOTE02 */ 

(7) #define QF_ISR_NEST 

/* Exact-width types. WG14/N843 C99 Standard, Section 7.18.1.1 */ 

(8) typedef signed char int8_t; 

typedef signed int int16_t; 

typedef signed long int32_t; 

typedef unsigned char uint8_t; 

typedef unsigned int uint16_t; 

typedef unsigned long uint32_t; 

(9) #include "qepn.h" /* QEP-nano platform-independent public interface */ 

(10) #include "qfn.h" /* QF-nano platform-independent public interface */ 

(1) Defining the macro Q_NFSM eliminates the code for the simple non-hierarchical FSMs. 

(2) The macro Q_PARAM_SIZE defines the size (in bytes) of the scalar event parameter. The allowed 

values are 0 (no parameter), 1, 2, or 4 bytes. Here the value of Q_PARAM_SIZE is set to 2, so that 


10 of 29




QP-nano will use uint16_t. If you don’t define this macro in qpn_port.h, the default of 0 (no 

parameter) will be assumed. 

(3) The macro QF_TIMEEVT_CTR_SIZE defines the size (in bytes) of the time event down-counter. The 

allowed values are 0 (no time events), 1, 2, or 4 bytes. Here the value of QF_TIMEEVT_CTR_SIZE is 

set to 2, so that QP-nano will use uint16_t. If you don’t define this macro in qpn_port.h, the 

default of 0 (no time events) will be assumed. 

(4) You must define the QF_MAX_ACTIVE macro as the exact number of active objects used in the 

application. The provided value must be between 1 and 8 and must be consistent with the definition 

of the QF_active[] array in main.c. 

(5) The interrupt locking macro resolves to the single instruction DISI #0x3FFF, which disables 

interrupts for 16383 instruction cycles. The number of cycles is much longer than any actual critical 

section in QP-nano. 

NOTE: The DISI instruction only disables interrupts with priority levels 1-6. Priority level 7 interrupts 

and all trap events still have the ability to interrupt the CPU when the DISI instruction is active. This 

means that from the perspective of QP, the level 7 interrupts are treated as non-maskable interrupts 

(NMIs). Such non-maskable interrupts cannot call any QP services. In particular, they cannot post 

events (see also Section 5). 

(6) The DISI #0 instruction is then used to unconditionally unlock the interrupts at the end of the critical 

section. 

(7) The interrupt nesting is allowed, as it is the default for PIC24/dsPIC. 

(8) The C99-standard exact-width integer types are defined explicitly, because the MPLAB C30 

compiler does not provide the standard header file. 

(9) The qpn_port.h must include the QEP-nano event processor interface qepn.h. 

(10) The qpn_port.h must include the QF-nano real-time framework interface qfn.h. 

3.2 ISRs in the Non-Preemptive “Vanilla” Configuration 

The MPLAB C30 compiler supports writing interrupts in C. In the non-preemptive “vanilla” port, the ISRs 

are identical as in the simplest of all “superloop” (main+ISRs), and there is nothing QP-nano-specific in 

the structure of the ISRs. The only QP-specific requirement is that you provide a periodic system clock 

tick ISR and you invoke QF_tick() in it. The ISRs are located in the bsp.c file found in the application 

directory. 

NOTE: The non-preemptive “vanilla” kernel allows interrupts nesting, as the interrupt preemptions 

are handled entirely by the PIC24/dsPIC hardware. 

Listing 3: The system tick interrupt calling QF_tick() function to manage armed time events. 

(1) void __attribute__((__interrupt__, 

(2) auto_psv)) 

(3) _T2Interrupt(void) 

{ 

(4) _T2IF = 0; /* clear Timer 2 interrupt flag */ 


11 of 29




(5) QF_tick(); /* handle all armed time events in QF */ 

} 

/* perform other work, if necessary */ 

(1) In the MPLAB C30 The ISR must be declared with the attribute __interrupt__. 

(2) The auto_psv attribute will cause the compiler to preserve the previous contents of PSVPAG and 

set it to section .const. Upon exit, the previous value of PSVPAG will be restored. Alternatively, if 

the ISR does not access the PSVPAG access, the attribute no_auto_psv can be used (see Section 

8.10 in [MPLAB C30] for more details). 

NOTE: If you don’t explicitly specify the no_auto_psv attribute, the compiler will err on the safe side 

and will implicitly insert the auto_psv atribute. 

(3) Every ISR must be a void (void) function. 

(4) Most ISRs in the PIC24/dsPIC architecture must explicitly clear the interrupt flag for the interrupt 

source. 

(5) The system clock tick ISR must invoke QF_tick(), and can also perform other actions, if 

necessary. The function QF_tick() cannot be reentered, that is, it necessarily must run to 

completion and return before it can be called again. This requirement is automatically fulfilled, 

because the same interrupt priority cannot preempt the running priority in PIC24/dsPIC. 

3.2.1 PSV Usage in ISRs 

This QP port to PIC24/dsPIC can work with ISRs that preserve the PSVPAG register as well as ISRs that 

don’t. The preserving of the PSVPAG register is controlled by the attributes auto_psv and no_auto_psv 

that the MPLAB C30 compiler supports for this purpose (see Listing 3(2)). 

If an ISR references const variables or string literals using the constants-in-code memory model, the 

auto_psv attribute should be added to the ISR definition. This attribute will cause the compiler to 

preserve the previous contents of PSVPAG and set it to section .const. Upon exit, the previous value of 

PSVPAG will be restored. Alternatively, if the ISR does not access the PSVPAG access, the attribute 

no_auto_psv can be used (see Section 8.10 in [MPLAB C30] for more details). The no_auto_psv 

attribute results in slightly faster ISR with one register less saved on the stack. 

3.2.2 Shadow Registers Usage in ISRs 

The non-preemptive “vanilla” QP-nano port to PIC24/dsPIC can work with ISRs that preserve the context 

in the shadow registers available in the PIC24/dsPIC CPU. To request the compiler to use the fast context 

save (using the push.s and pop.s instructions), tag the function with the __shadow__ attribute. For 

example: 

void __attribute__((__interrupt__, __shadow__)) _T2Interrupt(void); 

NOTE: Generally, shadow registers should be used at one IPL level only (typically the highest). 

When interrupt nesting is allowed, which is the default in the PIC24/dsPIC architecture, the shadow 

registers can get corrupted if they are used by interrupts of two or more different IPL levels. 


12 of 29




3.2.3 Assigning/Changing Interrupt Priorities in Software 

Each ISR in PIC24/dsPIC runs at a pre-configured IPL level. The default IPL level assigned to all ISRs out 

of reset is 4. It is strongly recommended, however, to assign priority to each used interrupt explicitly 

before enabling the interrupt. For example, the highlighted code in Listing 4 shows assigning the priority 

to the Timer2 interrupt in function QF_onStartup(): 

Listing 4: Configuring interrupts in function QF_onStartup() (file bsp.c) 

#define TIMER2_ISR_PRIO 4 

. . . 

void QF_onStartup(void) { /* entered with interrupts locked */ 

T2CON = 0; /* Use Internal Osc (Fcy), 16 bit mode, prescaler = 1 */ 

TMR2 = 0; /* Start counting from 0 and clear the prescaler count */ 

PR2 = BSP_TMR2_PERIOD - 1; /* set the timer period */ 

_T2IP = TIMER2_ISR_PRIO; /* set Timer 2 interrupt priority */ 

_T2IF = 0; /* clear the interrupt for Timer 2 */ 

_T2IE = 1; /* enable interrupt for Timer 2 */ 

T2CONbits.TON = 1; /* start Timer 2 */ 

} 

NOTE: All ISRs that call QP services must have priorities not exceeding 6 (1 through 6). Priority 7 is 

reserved for the NMI, as described in Section 5. 

3.3 QP Idle Loop Customization in QF_onIdle() 

The cooperative “vanilla” kernel can very easily detect the situation when no events are available, in 

which case QF_run() calls the QF_onIdle() callback. You can use QF_onIdle() to suspended the CPU 

to save power, if your CPU supports such a power-saving mode. Please note that QF_onIdle() is called 

repetitively from the event loop whenever the event loop has no more events to process, in which case 

only an interrupt can provide new events. The QF_onIdle() callback is called with interrupts locked, 

because the determination of the idle condition might change by any interrupt posting an event. 

The PIC24/dsPIC CPU supports several power-saving levels (consult the data sheets of particular 

PIC24/dsPIC devices for details). The following piece of code shows the QF_onIdle() callback that puts 

PIC24/dsPIC into the IDLE power-saving mode. Please note that PIC24/dsPIC architecture allows for an 

atomic setting the low-power mode and enabling interrupts at the same time. 

Listing 5: QF_onIdle() for the non-preemptive (“vanilla”) QP-nano port to PIC24/dsPIC 

(1) void QF_onIdle(void) { /* entered with int locked, NOTE01 */ 

(2) LED_ON (IDLE_LED); /* blink the IDLE LED, see NOTE02 */ 

(3) LED_OFF(IDLE_LED); 

(4) #ifdef NDEBUG 

(5) __asm__ volatile("disi #0x0001"); 

(6) Idle(); /* transition to Idle mode, see NOTE03 */ 

#else 

(7) QF_INT_UNLOCK(dummy); /* unlock interrupts, see NOTE01 */ 

#endif 

} 


13 of 29




(1) The QF_onIdle() callback is always called with interrupts locked to prevent any race condition 

between posting events from ISRs and transitioning to the sleep mode. 

(2-3) The LED D10 on the Explorer 16 board is used to visualize the idle loop activity. The LED is toggled 

on and off, which causes the LED to “glow” at the intensity proportional to the rate of invocations of 

the idle callback. The idle LED is toggled with interrupts locked, which means that the intensity of the 

LED “glow” is not skewed by preemptions from interrupts or tasks. 

(4) The low-power mode stops the CPU clock, so it can interfere with the debugger. Here, the lowpower 

mode is activated only in the Release build configuration when the macro NDEBUG is 

defined. 

(5) Interrupts are locked for just one following machine instruction, which ensures that interrupts will 

unlock after the IDLE mode. 

(6) The IDLE mode is activated by executing the IDLE instruction. 

NOTE: The PIC24/dsPIC allows for atomic transition to the Idle or Sleep modes with interrupts 

locked, as it should be done for a deterministic transition to the low-power mode (see [Samek 07a]). 

(7) When the idle/sleep mode is not used, interrupts are simply unlocked. 


14 of 29




4 Preemptive Configuration with QK-nano 

The QP-nano port to PIC24/dsPIC with the preemptive kernel (QK-nano) is similar to the “vanilla” port. In 

particular, the interrupt locking/unlocking policy is the same, and the BSP is almost identical, except for 

some extra considerations for the ISRs. 

4.1 QK-nano-specific ISR Entry and Exit Macros (file qpn_port.h) 

The preemptive QP-nano port to PIC24/dsPIC also allows writing ISRs in C, so no explicit assembly 

programming is necessary. However, the preemptive QK kernel requires (as all preemptive kernels do) 

notifying the kernel about entering and exiting the ISR, so that the kernel can avoid context switching 

inside ISRs, but knows when to perform asynchronous preemptions when the last nested ISR returns to 

the task level. 

While working with the compiler-generated ISRs, the biggest problem for a preemptive kernel is to 

reliably detect that a given ISR is not nesting on top of another ISR, so that only the last interrupt 

returning to the task level performs context switch, if necessary. 

NOTE: Unlike most other processors, PIC24/dsPIC does not disable interrupts upon the entry to the 

interrupt service routine. PIC24/dsPIC merely raises the current IPL to the level of currently serviced 

interrupt. This means that the currently serviced interrupt can be preempted by a higher-level 

interrupt even at the very first instruction. Consequently, incrementing the interrupt nesting counter 

(QK_intNest_) is not a reliable way of accounting for interrupt nesting, because it can miss an 

interrupt nesting level no matter how early in the ISR it is performed. 

For PIC24/dsPIC, a reliable way of detecting nesting of interrupts is to check the preempted status 

register SR, which is saved on the interrupt stack as shown in Figure 5. Only if the preempted IPL 

(bits SR) is non-zero, the current interrupt preempts the task level and performing a context switch 

is allowed. 

Figure 5: Interrupt stack frame for PIC24/dsPIC 

Low memory 

High memory 

15 

PC 

SR 

PC 

Register saved by the C30 compiler 


… 


0 

IPL3 status bit 

(CORCON). 

Stack pointer 

(w15) 

While checking the stacked SR is quite easy in assembly, it is much trickier for the compiler-generated 

ISRs. The compiler generates different stack frames depending on the actually clobbered registers in the 

body of the ISR as well as the attributes of the ISR and even the optimization level used to compile the 

code. Consequently, it is difficult to know the offset of the stacked SR from the current stack pointer w15 

that is accessible inside the ISR, (again see Figure 5). 


15 of 29




The solution used in this QK port is to use the __preprologue__ attribute of the compiler-generated ISR 

to check the stacked SR before the compiler pushes any registers to the stack and alters the stack 

pointer. The IPL extracted from the stacked SR is then stored in the global variable QK_intNest_, which 

in this case is not used as the interrupt nesting counter, but rather as a bitmask (a set) of preempted IPL 

levels. More precisely, the QK-nano-specific ISR entry code added before any compiler-generated code 

checks the stacked IPL level in SR and sets the bit corresponding to the preempted IPL in the 

QK_intNest_ bitmask, as illustrated in Figure 6. In the QK-specific ISR exit code, the current IPL is 

extracted from the SR and the bit corresponding to the current IPL is cleared in the QK_intNest_ 

bitmask. 

Figure 6: Storing the preempted IPLs in the QK_intNest_ bitmask 

Bit number 

7 

6 

5 

4 

3 

2 

1 

0 

0 

0 

1 

0 

0 

0 

1 

1 

QK_intNest_ 

Unused level (IPL = 7) 

Preempted IPL = 5 



The QK-nano-specific interrupt entry and exit sequence defined in the header file qk_port.h shown in 

Listing 6 demonstrates one possible solution to this problem. The QK port header file for the PIC24/dsPIC 

port is located in \ports\pic24-dspic\qk\mplab-c30\qk_port.h. The upcoming Section “ISRs 

with the Preemptive QK-nano Kernel” explains how to use the macros QK_ISR_ENTRY() / 

QK_ISR_EXIT() and how these macros work at the assembly level. 

Listing 6: qpn_port.h header file for the preemptive QP port with QK 

. . . 

#define QF_ISR_NEST 

/* QK interrupt entry and exit */ 

(1) #define QK_ISR(psv_) \ 

(2) void __attribute__((__interrupt__(__preprologue__( \ 

"push RCOUNT \n" \ 

"push.d w0 \n" \ 

"mov.w [w15-8],w0 \n" \ 

"lsr.w w0,#13,w1 \n" \ 

"mov.w #1,w0 \n" \ 

"sl w0,w1,w0 \n" \ 

"ior.b _QK_intNest_\n" \ 

"bra .+6 ")) \ 

, psv_)) 

(3) #define QK_ISR_EXIT() do { \ 

register uint16_t this_sr; \ 


16 of 29




__asm__ volatile ( \ 

"mov.w SR,%0 \n" \ 

"lsr %0,#5,w0 \n" \ 

"and.w w0,#7,w0 \n" \ 

"mov.w #1,w1 \n" \ 

"sl w1,w0,w0 \n" \ 

"ior.b #1,w0 \n" \ 

"com.b w0,w0 \n" \ 

"disi #0x3FFF \n" \ 

"and.b _QK_intNest_" : "=r"(this_sr) : : "w0", "w1"); \ 

if (QK_intNest_ == 0) { \ 

uint8_t p = QK_schedPrio_(); \ 

if (p != (uint8_t)0) { \ 

__asm__ volatile ("clr.b SR"); \ 

QK_sched_(p); \ 

__asm__ volatile ("mov.w %0,SR" : : "r"(this_sr)); \ 

} \ 

} \ 

__asm__ volatile ("disi #0x0000"); \ 

} while (0); 

. . . 

#include "qepn.h" /* QEP-nano platform-independent public interface */ 

#include "qfn.h" /* QF-nano platform-independent public interface */ 

#include "qkn.h" /* QK-nano platform-independent public interface */ 

(1) The macro QK_ISR() defines the ISR attributes, as required by the MPLAB C30 compiler. The 

macro is designed to be before the actual ISR signature, as will be illustrated in Section 4.2. The 

argument psv_ controls PSV usage in the ISR and can be either auto_psv or no_auto_psv (see 

Section 3.2.1). 

(2) The macro QK_ISR() then uses the attribute __preprologue__ to define the specific interrupt entry 

sequence in assembly, which the compiler copies verbatim before any generated ISR code. 

(3) The macro QK_ISR_EXIT() must be invoked as the last instruction of every ISR of IPL 1..6. Again, 

the usage of this macro will be illustrated in Section 4.2. 

4.2 ISRs with the Preemptive QK-nano Kernel 

Even though the QK-nano interrupt entry/exit macros are somewhat involved, their use is actually very 

simple and enables very straightforward coding ISRs in C, without any need to use assembly. The 

following Listing 7 shows how to write ISRs for the preemptive QK-nano kernel: 

NOTE: The QK-nano interrupt entry and exit macros QK_ISR() and QK_ISR_EXIT() work only 

with the optimization level O1 or higher (O2, O3, or Os) in the C30 compiler. The MPLAB C30 

compiler will report a compile-time error “'asm' operand requires impossible reload” when no 

optimization is used. 

Listing 7: T2Interrupt ISR for QK-nano 

(1) QK_ISR(no_auto_psv) _T2Interrupt() { 

_T2IF = 0; /* clear Timer 2 interrupt flag */ 


17 of 29




QF_tick(); /* handle all armed time events in QF */ 

(2) QK_ISR_EXIT(); /* inform QK about exiting the ISR */ 

} 

(1) The macro QK_ISR() is used before the ISR signature. Here the PSV control is set to no_auto_ps, 

which avoids saving and restoring the PSVPAG register. If your ISR body references const variables 

or string literals using the constants-in-code memory model, you need to define this argument to 

auto_psv. 

(2) The macro QK_ISR_EXIT() is invoked at the end of every ISR to perform the asynchronous context 

switch, if necessary. 

4.2.1 Explanation of ISR code for the preemptive QK kernel 

Listing 8 shows the disassembled code for the _T2Interrupt ISR from Listing 7. The highlighted code is 

generated by the macros QK_ISR() and QK_ISR_EXIT(). The explanation section immediately following 

the listing clarifies the most important points. 

Listing 8: Disassembled code for T2Interrupt ISR 

55: QK_ISR(no_auto_psv) _T2Interrupt() { 

(1) 008C8 F80036 push.w 0x0036 

(2) 008CA BE9F80 mov.d 0x0000,[0x001e++] 

(3) 008CC 97B84F mov.w [0x001e-8],0x0000 

(4) 008CE DE00CD lsr 0x0000,#13,0x0002 

(5) 008D0 200010 mov.w #0x1,0x0000 

(6) 008D2 DD0001 sl 0x0000,0x0002,0x0000 

(7) 008D4 B76880 ior.b 0x0880 

(8) 008D6 370002 bra 0x0008dc 

(9) 008D8 F80036 push.w 0x0036 

(10) 008DA BE9F80 mov.d 0x0000,[0x001e++] 

(11) 008DC BE9F82 mov.d 0x0004,[0x001e++] 

(12) 008DE BE9F84 mov.d 0x0008,[0x001e++] 

(13) 008E0 BE9F86 mov.d 0x000c,[0x001e++] 

(14) 008E2 781F88 mov.w 0x0010,[0x001e++] 

56: _T2IF = 0; /* clear Timer 2 interrupt flag */ 

008E4 A9E084 bclr.b 0x0084,#7 

57: QF_tick(); /* handle armed time events in QF-nano */ 

008E6 07FFD1 rcall 0x00088a 

58: 

59: QK_ISR_EXIT(); /* inform QK-nano about exiting ISR */ 

(15) 008E8 800218 mov.w 0x0042,0x0010 

(16) 008EA DE4045 lsr 0x0010,#5,0x0000 

(17) 008EC 600067 and.w 0x0000,#7,0x0000 

(18) 008EE 200011 mov.w #0x1,0x0002 

(19) 008F0 DD0800 sl 0x0002,0x0000,0x0000 

(20) 008F2 B34010 ior.b #0x1,0x0000 

(21) 008F4 EAC000 com.b 0x0000,0x0000 

(22) 008F6 FC3FFF disi #16383 

(23) 008F8 B66880 and.b 0x0880 

(24) 008FA E24880 cp0.b 0x0880 

(25) 008FC 3A0005 bra nz, 0x000908 


18 of 29




(26) 008FE E24885 cp0.b 0x0885 

(27) 00900 320003 bra z, 0x000908 

(28) 00902 EF6042 clr.b 0x0042 

(29) 00904 0700A0 rcall 0x000a46 

(30) 00906 880218 mov.w 0x0010,0x0042 

(31) 00908 FC0000 disi #0 

60: } 

(32) 0090A 78044F mov.w [--0x001e],0x0010 

(33) 0090C BE034F mov.d [--0x001e],0x000c 

(34) 0090E BE024F mov.d [--0x001e],0x0008 

(35) 00910 BE014F mov.d [--0x001e],0x0004 

(36) 00912 BE004F mov.d [--0x001e],0x0000 

(37) 00914 F90036 pop.w 0x0036 

(38) 00916 064000 retfie 

(1) The RCOUNT register (at address 0x36) is pushed to the stack. This is done to establish the same 

stack layout as the MPLAB C30 compiler does for all ISRs. 

(2) The register pair w0-w1 is pushed to the stack. Now these registers can be clobbered. 

(3) The stacked SRCORCONPC bits (see Figure 5) are loaded from the stack to w0. 

Please note that after pushing RCOUNT and w0,w1 pair, this information is 8 bytes away from the 

current stack pointer in w15. 

(4) The register w0 is left-shifted by 13 bits, so that the stacked IPL ends up in w1. 

(5) The register w1 is compared with zero. 

(6) The stacked IPL indicates that an ISR has been preempted, so the corresponding bit in the 

QK_intNest_ bitmask needs to be set. Here the bitmask (1




(15) The QK-specific ISR exit starts with placing the current SR into the this_sr local variable, which 

the C30 compiler decided to place in the w8 register. 

(16) The IPL bits from the current SR are right-shifted into w0. 

(17) All other SR bits, except the IPL bits in w0 are masked off in w0. 

(18-19) The bitmask (1




include any preemptions by interrupts and tasks). The transition to the Idle mode happens in a very 

straightforward way, because transition to idle mode is always safe under a preemptive priority-based 

kernel, such as QK. 

void QK_onIdle(void) { 

Listing 9: QK_onIdle() callback for PIC24/dsPIC. 

QF_INT_LOCK(); 

LED_ON (IDLE_LED); /* blink the IDLE LED, see NOTE01 */ 

LED_OFF(IDLE_LED); 

QF_INT_UNLOCK(); 

#ifdef NDEBUG 

Idle(); /* transition to Idle mode */ 

#endif 

} 

4.4 Testing QK Preemption Scenarios 

The technique described in this section will allow you to use the MPLAB debugger to trigger an interrupt 

at any machine instruction and observe the preemptions it causes. The interrupt used for the testing 

purposes is the GPIOA interrupt (INTID == 0). The ISR for this interrupt is shown below: 

The DPP example application for the preemptive QK-nano kernel includes special ISR (INT0 ISR) for 

convenient testing of various preemption scenarios, defined as follows: 

#define INT0_ISR_PRIO 6 

QK_ISR(auto_psv) _INT0Interrupt() { 

_INT0IF = 0; 

QActive_postISR(&AO_Ped, PEDS_WAITING_SIG, 0); 

QK_ISR_EXIT(); /* inform QK about exiting the ISR */ 

} 

The INT0 ISR, is assigned priority 6, which is higher than the priority of the system clock tick ISR. 

Figure 7 shows how to trigger the INT0 interrupt from the MPLAB debugger. From the debugger you need 

to first open the “File Registers” window (menu View | File Registers) as shown in Figure 7. You scroll to 

the IFS0 register at address 0x0084. To trigger the INT0 interrupt you need to write 1 to the leastsignificant 

bit (bit #0) of the IFS0 register. 

The general testing strategy is to break into the application at an interesting place for preemption, set 

breakpoints to verify which path through the code is taken, and trigger the INT0 interrupt, as described 

above. Next, you need to free-run the code (don’t use single stepping) so that the PIC24/dsPIC CPU can 

perform prioritization. You observe the order in which the breakpoints are hit. This procedure will become 

clearer after a few examples. 


21 of 29




Figure 7: Triggering the INT0 interrupt from the MPLAB debugger 

4.4.1 Interrupt Nesting Test 

The first interesting test is verifying that the preemptive scheduler QK_schedule_() is not called in a 

nested interrupt, but is called when the interrupt returns to the task level. 

To test this scenario, you place a breakpoint inside the _INT0Interrupt() and also inside the 

_T2Interrupt() ISR. When the breakpoint in the _T2Interrupt() is hit, you remove the original 

breakpoint and place another breakpoint at the very next machine instruction (use the Disassembly 

window) and also another breakpoint on the first instruction of the QK_schedule_() function. Next you 

trigger the INT0 interrupt per the instructions given in the previous section. You hit the Run button. 

The pass criteria of this test are as follows: 

1. The first breakpoint hit is the one inside the _INT0Interrupt() function, which means that the INT0 

ISR preempted the _T2Interrupt() ISR. 

2. The second breakpoint hit is the one in the _T2Interrupt(), which means that the Timer2 ISR 

continues after the _INT0Interrupt() completes. 

3. The last breakpoint hit is the one in QK_schedule_(), which means that the scheduler is called only 

after all interrupts are processed. 

You need to remove all breakpoints before proceeding to the next test. 

4.4.2 Task Preemption Test 

The next interesting test is verifying that tasks can preempt each other. You set a breakpoint anywhere in 

the Philosopher state machine code. You run the application until the breakpoint is hit. After this 

happens, you remove the original breakpoint and place another breakpoint at the very next machine 

instruction (use the Disassembly window). You also place a breakpoint inside the _INT0Interrupt() 

interrupt handler and on the first instruction at the first instruction of the QK_schedule_() function. Next 

you trigger the INT0 interrupt per the instructions given earlier. You hit the Run button. 

The pass criteria of this test are as follows: 

1. The first breakpoint hit is the one inside the _INT0Interrupt() function, which means that INT0 ISR 

preempted the Philospher task. 


22 of 29




2. The second breakpoint hit is the one in QK_schedule_() function, which means that the QK 

scheduler is activated before the control returns to the preempted Philosopher task. 

3. After hitting the breakpoint in QK_schedule_() function, you must first disable the Timer2 interrupts 

by clearing bit #7 in the IEC0 register at address 0x0094, in the “File Registers” window, in the similar 

way as you set the bit #0 in the IFS0 register to trigger INT0. 

4. Next, you single step into the QK_schedule_(). (NOTE: you might want to close the “File Registers” 

window to speed up the single stepping.) You verify that the scheduler invokes a state handler of the 

Table state machine. This proves that the Table task preempts the Philosopher task. 

5. After this you free-run the application and verify that the next breakpoint hit is the one inside the 

Philosopher state machine. This validates that the preempted task continues executing only after 

the preempting task (the Table state machine) completes. 

4.4.3 Other Tests 

Other interesting tests that you can perform include changing priority of the INT0 ISR to be lower than the 

priority of Timer2 ISR to verify that the QK-nano scheduler is still called only after all interrupts complete. 

In yet another test you could post an event to Philosopher active object rather than Table active object 

from the INT0 ISR to verify that the QK-nano scheduler will not preempt the Philosopher task by itself. 

Rather the extra event will be queued and the Philosopher task will process the queued event only after 

completing the current event processing. 


23 of 29




5 Implementing “Zero Interrupt Latency” with the NMI 

As noted in Section 3.1, the interrupt locking policy in this QP port locks only interrupts with IPL from 1 to 

6. The highest-level interrupts with IPL=7 are not locked at all. In other words, IPL=7-interrupts are nonmaskable 

(they are NMIs). This interrupt locking policy has two important consequences. 

First, the IPL=7-interrupts cannot call any QP-nano services (e.g., NMIs cannot post events to QP-nano 

tasks), because any system call from an NMI would run the risk of corrupting the internal QP data since 

the protection by critical sections does not apply for NMIs. 

On the flip side, however, the IPL=7-interrupts run completely “free” with the interrupt latency determined 

only by the underlying hardware and independent on the critical sections implemented in QP-nano. This is 

what is meant here by the term “Zero Interrupt Latency”. 

Such NMIs (IPL=7-interrupts, in this case) have many potential uses. They are very useful when the 

software must perform some simple operations very fast, but most of the time the software does not need 

to communicate with the task-level of QP-nano active objects. Consider for example a fast interrupt-driven 

UART interface. The ISR that receives bytes must remove the bytes from the FIFO very fast or else the 

FIFO will quickly overflow. However, the ISR might buffer the bytes and only need to notify the task level 

when the buffer fills up, which is relatively infrequently. 

NOTE: NMIs (IPL=7-interrupts, in this case) can be equally well used in the non-preemptive QP port 

as well as in the preemptive port with the QK kernel. 

5.1 Communication between NMIs and QP-nano 

From the previous discussion it is obvious that the NMIs must be able to communicate from time to time 

with the task level (active objects in QP-nano). The question is how to achieve such communication 

without calling QP-nano services directly? 

The solution is to call QP services indirectly, by triggering a regular (maskable) interrupt from the NMI. In 

the PIC24/dsPIC architecture you can very easily trigger an ISR by explicitly setting the corresponding 

interrupt flag (the same that you explicitly clear in the ISR). The triggered interrupt can call QP services, 

such as posting or publishing events to QP-nano active objects. 

The subtle, but important consideration is the communication between the NMI and the triggered 

maskable interrupt. Typically, such communication must occur by means of atomically-accessed shared 

variables. In the PIC24/dsPIC CISC architecture most 8- and 16-bit variables are read and written 

atomically (in one machine instruction), so implementing this way of communication is quite easy. 

5.2 Implementation Considerations for the NMIs 

Because the NMIs run completely “free” and outside the QP-nano framework, they don’t need to follow 

any conventions associated with regular maskable ISRs that can call QP services. Generally, the NMIs 

should run as fast as possible, because the interrupt latency for NMIs is determined typically by the 

execution time of the NMI itself. (In this QP port, only one IPL level 7 is available for NMIs, so NMIs 

cannot preempt each other). 

NMIs can be coded in C, and in fact the C30 compiler offers options to make these interrupts very 

efficient. On of these options is __shadow__, which uses fast context save and restore to the shadow 

registers. Obviously, you can use only one such fast ISR in your system to avoid corruption of the shadow 

registers. And finally, you should generally avoid calling any functions from the NMI, as this would force 

the compiler to save and restore w0-w7. 


24 of 29




6 BSP for the Explorer 16 Board 

The Board Support Package (BSP) for PIC24/dsPIC and Explorer 16 board (see Figure 1) with the nonpreemptive 

“vanilla” scheduler is located in the directory: \examples\pic24_dspic\mplabc30\pelican-explorer16_pic24\ 

for PIC24 and \examples\pic24_dspic\mplabc30\pelican-explorer16_dspic\ 

for dsPIC. The BSP consists of the following files: 

1. bsp.h contains the Board Support Package interface (BSP) 

2. bsp.c contains the implementation of the BSP, which includes all ISRs and all platform-specific QP 

callbacks. 

3. p24FJ128GA010.gld contains the linker command file for locating the application. 

6.1 Setting the Sizes of Stack and Heap 

You set the sizes of stack and heap through the MPLAB IDE, as shown in Figure 8. 

Figure 8: Setting the size of heap and stack 


25 of 29




6.2 The BSP header file bsp.h 

The BSP header file for the PELICAN application defines the desired ticking rate. This constant is useful 

for defining timeouts, which are always specified in units of clock ticks: 

#include /* for declaration of the SRBits register */ 

#define BSP_TICKS_PER_SEC 

100UL 

/* the system tick rate [Hz] */ 

/* street signals ..........................................................*/ 

enum BSP_CarsSignal { 

CARS_RED, CARS_YELLOW, CARS_GREEN, CARS_OFF 

}; 

enum BSP_PedsSignal { 

PEDS_DONT_WALK, PEDS_BLANK, PEDS_WALK 

}; 

void BSP_init(void); 

void BSP_signalCars(enum BSP_CarsSignal sig); 

void BSP_signalPeds(enum BSP_PedsSignal sig); 

#define BSP_showState(prio_, state_) ((void)0) 

6.3 BSP initialization 

The following BSP_init() function for the Explorer 16 board configures the DSP and peripherals as, 

shown in Listing 10. This file has been designed to be easily modifiable for other applications. 

Listing 10: The BSP_init() implementation in the bsp.c for the DPP example. 

void BSP_init(void) { 

RCONbits.SWDTEN = 0; /* disable Watchdog */ 

} 

TRISA = 0x00; /* set LED pins as outputs */ 

PORTA = 0x00; /* set LEDs drive state low */ 

6.4 Starting Interrupts in QF_onStartup() 

QP invokes the QF_onStartup() callback just before starting the background loop. The 

QF_onStartup() function must configure and start interrupts. At the minimum, QF_onStartup() must 

start the system clock tick interrupt. The following QF_onStartup() function enables the CPU Timer 0. 

void QF_onStartup(void) { /* entered with interrupts locked */ 

T2CON = 0; /* Use Internal Osc (Fcy), 16 bit mode, prescaler = 1 */ 

TMR2 = 0; /* Start counting from 0 and clear the prescaler count */ 

PR2 = BSP_TMR2_PERIOD - 1; /* set the timer period */ 

_T2IP = TIMER2_ISR_PRIO; /* set Timer 2 interrupt priority */ 

_T2IF = 0; /* clear the interrupt for Timer 2 */ 

_T2IE = 1; /* enable interrupt for Timer 2 */ 

T2CONbits.TON = 1; /* start Timer 2 */ 


26 of 29




} 

6.5 Assertion Handling Policy in Q_onAssert() 

As described in Chapter 6 of [PSiCC2], all QP-nano components use internally assertions to detect errors 

in the way application is using the QP services. You need to define how the application reacts in case of 

assertion failure by providing the callback function Q_onAssert(). Typically, you would put the system in 

a fail-safe state and try to reset. It is also a good idea to log some information as to where the assertion 

failed. 

The following code fragment shows the Q_onAssert() callback for PIC24/dsPIC. The function keeps 

locking interrupts in an endless loop. You can then break into the code with the debugger and inspect the 

cause of the assertion by backtracking the call stack. 

NOTE: This policy is only adequate for testing, but is not adequate for production release. 

void Q_onAssert(char const Q_ROM * const Q_ROM_VAR file, int line) { 

(void)file; /* avoid compiler warning */ 

(void)line; /* avoid compiler warning */ 

for (;;) { 

QF_INT_LOCK(dummy); /* make sure that interrupts are locked */ 

} 

} 


27 of 29




7 Related Documents and References 

Document 

[PSiCC2] “Practical UML Statecharts in C/C++, 

Second Edition”, Miro Samek, Newnes, 2008 

[QP-nano 08] “QP-nano Reference Manual”, 

Quantum Leaps, LLC, 2008 

[QL AN-Directory 07] “Application Note: QP 

Directory Structure”, Quantum Leaps, LLC, 2007 

[QL AN-PELICAN 08] “Application Note: PELICAN 

Crossing Application”, Quantum Leaps, LLC, 2008 

[MPLAB-C30] “MPLAB® C Compiler for PIC24 

MCUs and dsPIC® DSCs User’s Guide”, 

Microchip, 2008. 

[PIC24] “PIC24FJ128GA010 Family Data Sheet 

64/80/100-Pin General Purpose, 16-Bit Flash 

Microcontrollers”, Microchip, 2007. 

[dsPIC] “dsPIC30F/33F Programmer’s Reference 

Manual High-Performance Digital Signal 

Controllers”, Microchip, 2005. 

[QKernel] “Q.Kernel for PIC24 and dsPIC User 

Guide Version 2.1-1089”, Quasarsoft Ltd, 2009 

[AVIX] AVIX RTOS for Microchip 16-bit and 32-bit 

micro controllers belonging to the PIC24F, 

PIC24H, dsPIC30F, dsPIC33F and PIC32 families. 

[Samek 07a] “Using Low-Power Modes in 

Foreground/Background Systems”, Miro Samek, 

Embedded System Design, October 2007 

http://www.state-machine.com/doxygen/qpn/ 

Location 

Available from most online book retailers, such as 

amazon.com. See also: http://www.statemachine.com/psicc2.htm 

http://www.statemachine.com/doc/AN_QP_Directory_Structure.pdf 

http://www.statemachine.com/doc/AN_PELICAN.pdf 

Microchip literature #DS51284H, available on the 

Explorer 16 kit and online at www.microchip.com 

Microchip literature #DS39747D, available on the 


Microchip literature #DS70157B, available on the 


Document available for download from 

www.quasarsoft.com 

http://www.avix-rt.com/ 

http://www.embedded.com/design/202103425 


28 of 29




8 Contact Information 

Quantum Leaps, LLC 

103 Cobble Ridge Drive 

Chapel Hill, NC 27516 

USA 

+1 866 450 LEAP (toll free, USA only) 

+1 919 869-2998 (FAX) 

e-mail: info@quantum-leaps.com 

WEB : http://www.quantum-leaps.com 

http://www.state-machine.com 

“Practical UML 

Statecharts in C/C+ 

+, Second Edition: 

Event Driven 

Programming for 

Embedded 

Systems”, 

by Miro Samek, 

Newnes, 2008 

Microchip, Inc. 

Web: http://www.microchip.com 


29 of 29

QDK-nano PIC24/dsPIC-C30 - Quantum Leaps

Create successful ePaper yourself

Delete template?

Save as template?