QDK PIC24/dsPIC-C30 - Quantum Leaps

QP state machine frameworks for PIC24/dsPIC 

QDK 

PIC24/dsPIC-C30 

Document Revision D 

October 2012 

Copyright © Quantum Leaps, LLC 

www.quantum-leaps.com 

www.state-machine.com

Table of Contents 

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

1.1 About QP .................................................................................................................................................... 2 

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

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

1.4 Licensing QP .............................................................................................................................................. 4 

2 Getting Started ................................................................................................................................................ 5 

2.1 Software Installation ....................................................................................................................................... 5 

2.2 Building the QP Libraries ............................................................................................................................... 7 

2.3 Building and Running the Examples .............................................................................................................. 8 

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

3.1 The qep_port.h Header File ........................................................................................................................... 12 

3.2 The qf_port.h Header File .............................................................................................................................. 12 

3.3 ISRs in the Non-Preemptive “Vanilla” Configuration ...................................................................................... 14 

3.4 QP Idle Loop Customization in QF_onIdle() ................................................................................................... 16 

4 Preemptive Configuration with QK ................................................................................................................ 17 

4.1 QK-specific ISR Entry and Exit Macros (file qk_port.h) .................................................................................. 17 

4.2 ISRs with the Preemptive QK Kernel ............................................................................................................. 19 

4.3 Idle Loop Customization in the QK Port ......................................................................................................... 22 

4.4 Testing QK Preemption Scenarios ................................................................................................................. 23 

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

5.1 Communication between NMIs and QP ......................................................................................................... 26 

5.2 Implementation Considerations for the NMIs ................................................................................................. 26 

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

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

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

6.3 BSP initialization ............................................................................................................................................ 28 

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

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

7 The QS Software Tracing Instrumentation ................................................................................................... 30 

7.1 QS Time Stamp Callback QS_onGetTime() ................................................................................................... 31 

7.2 QS Trace Output in QF_onIdle()/QK_onIdle() ................................................................................................ 33 

7.3 Invoking the QSpy Host Application ............................................................................................................... 33 

8 Related Documents and References ............................................................................................................. 34 

9 Contact Information ........................................................................................................................................ 35 

Copyright © Quantum Leaps, LLC. All Rights Reserved. 

i

1 Introduction 

This QP Development Kit (QDK) describes how to use the QP state machine frameworks 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 

Q-SPY software 

tracing output to 

host PC (RS232) 

Power LED 

9V DC power 

User LEDs 


1 of 35



www.state-machine.com/pic 

The actual hardware/software used to test this QDK 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/C 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 

QP is a family of very lightweight, open source, state machine frameworks for 

developing event-driven applications. QP enables building well-structured 

embedded applications as a set of concurrently executing hierarchical state 

machines (UML statecharts) directly in C or C++ without big tools. QP is 

described in great detail in the book “Practical UML Statecharts in C/C++, 

Second Edition: Event-Driven Programming for Embedded Systems” [PSiCC2] 

(Newnes, 2008). 

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

processor (QEP), a portable real-time framework (QF), a tiny preemptive kernel 

(QK), and software tracing instrumentation (QS). Current versions of QP 

include: QP/C and QP/C++, which require about 4KB of code and a few 

hundred bytes of RAM, and the ultra-lightweight QP-nano, which requires only 

1-2KB of code and just several bytes of RAM. QP can work with or without a traditional RTOS or OS. In 

the simplest configuration, QP can completely replace a traditional RTOS. QP can manage up to 63 

concurrently executing tasks structured as state machines (called active objects in UML). 

Figure 2: QP components and their relationship with the target hardware, board support package 

(BSP), and the application comprised of state machines 


2 of 35




1.2 About the QP Port to PIC24/dsPIC 

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

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

ports the hardware priority levels are allocated as follows: 

1. All QP 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 services, such as QF_tick(), QActive_postFIFO(), QF_publish(), and Q_NEW(). The 

maskable interrupts can nest on each other, which is the default in PIC24/dsPIC. 

3. This QP 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 services for 

signaling the QP tasks (active objects). 

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 

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 


3 of 35




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.2). 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 technically impossible. The term means here that 

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

that no additional latency is 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. 

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

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

of the Dining Philosopher Problem (DPP) example for each processor. The DPP application is described 

in Chapter 7 of [PSiCC2] as well as in the Application Note “Dining Philosopher Problem” [QL AN-DPP 

08] (included in the QDK distribution): 

 

 

 

 

The Dining Philosopher Problem example with the cooperative “vanilla” kernel for 

PIC24FJ128GA010; 

The Dining Philosopher Problem example with the preemptive QK” kernel for PIC24FJ128GA010 

(described in Chapter 10 of [PSiCC2]); 

The Dining Philosopher Problem example with the cooperative “vanilla” kernel for 

dsPIC33FJ256GP710; and 

The Dining Philosopher Problem example with the preemptive QK” kernel for dsPIC33FJ256GP710 

(described in Chapter 10 of [PSiCC2]); 

1.4 Licensing QP 

The Generally Available (GA) distribution of QP 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. 


4 of 35




2 Getting Started 

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

2.1 Software Installation 

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

for a specific QDK 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 Listing 1 shows the 

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

structure is described in detail in a separate Quantum Leaps Application Note: “QP Directory Structure”). 

NOTE: Every QDK contains only the QP port and example(s) pertaining to the specific MCU and 

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

separate download from www.state-machine.com/downloads/. 

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

/ 

- QP Root Directory 

+-doc\ 

| +-AN_DPP.pdf - Application Note “Dining Philosopher Problem Example” 

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

| 

+-ports/ 

- QP ports 

| +-pic24-dspic\ - Pic24-dspic ports 

| | +-vanilla\ - Ports to the non-preemptive “vanilla” kernel 

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

| | | | +-dbg\ – Debug build 

| | | | | +-libqp_24FJ128GA010.a – QP library for PIC24FJ128GA010 

| | | | | +-libqp_33FJ256GP710.a – QP library for dsPIC33FJ256GP710 

| | | | +-rel\ – Release build 



| | | | +-spy\ – Spy build 



| | | | +-make_24FJ128GA010.bat – Batch to build QP for PIC24FJ128GA010 

| | | | +-make_33FJ256GP710.bat – Batch to build QP for dsPIC33FJ256GP710 

| | | | +-qep_port.h – QEP platform-dependent public include 

| | | | +-qf_port.h – QF platform-dependent public include 

| | | | +-qs_port.h – QS platform-dependent public include 

| | | 

| | +-qk\ - QK (Quantum Kernel) ports 


| | | | +-dbg\ – Debug build 



| | | | +-rel\ – Release build 



| | | | +-spy\ – Spy build 



5 of 35





| | | | +-make_24FJ128GA010.bat – Batch to build QP for PIC24FJ128GA010 

| | | | +-make_33FJ256GP710.bat – Batch to build QP for dsPIC33FJ256GP710 

| | | | +-qep_port.h – QEP platform-dependent public include 

| | | | +-qf_port.h – QF platform-dependent public include 

| | | | +-qk_port.h – QK platform-dependent public include 

| | | | +-qs_port.h – QS platform-dependent public include 

| 

+-examples\ 

- subdirectory containing the QP example files 

| +-pic24-dspic\ - PIC24-dsPIC examples 

| | +-vanilla\ - Ports to the non-preemptive “vanilla” kernel 


| | | | +-dpp-explorer16_pic24\ - DPP example for Explorer 16 with PIC24 chip 

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

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

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

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

| | | | | +-spy\ - directory containing the Spy build 

| | | | | | 

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

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

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

| | | | | +-philo.c - the Philosopher active objects 

| | | | | +-dpp.h - the DPP application header file 

| | | | | +-table.c - the Table active object 

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

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

| | | | | +-dpp-spy.mcp – MPLAB project for Spy configuration 

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

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

| | | | | 

| | | | +-dpp-explorer16_dspic\ - DPP example for Explorer 16 with dsPIC chip 






| | | | | | 

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









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

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

| | | 

| | +-qk\ - Ports to the preemptive QK kernel 


| | | | +-dpp-qk-explorer16_pic24\ - DPP example for Explorer 16 with PIC24 chip 





6 of 35






| | | | | | 

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









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

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

| | | | | 

| | | | +-dpp-qk-explorer16_dspic\ - DPP example for Explorer 16 with dsPIC chip 






| | | | | | 

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









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

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

2.2 Building the QP Libraries 

All QP components are deployed as libraries that you statically link to your application. The pre-built 

libraries for QEP, QF, QK, and QS are provided inside the \ports\pic24-dspic directory. This 

section describes steps you need to take to rebuild the libraries yourself. 

NOTE: To achieve commonality among different development tools, Quantum Leaps software does 

not use the vendor-specific IDEs, such as the MPLAB IDE, for building the QP libraries. Instead, QP 

supports command-line build process based on simple batch scripts. 

The code distribution contains the batch file make__.bat for building all the libraries 

located in the \ports\pic24-dspic\... directory. For example, to build the debug version of all 

the QP libraries for PIC24-dsPIC, with the MPLAB C30 compiler, QK kernel, you open a console window 

on a Windows PC, change directory to \ports\pic24-dspic\qk\mplab-c30\, and invoke the 

batch by typing at the command prompt the following command: 

make_24FJ128GA010.bat 

For the PIC24FJ128GA010 MCU and 

make_33FJ256GP710.bat 


7 of 35




for the dsPIC33FJ256GP710 MCU. 

NOTE: You adjust the MCU type by changing the symbol PIC_DEVICE at the top of the 

make_.bat file. 

The build process should produce the QP libraries in the location: \ports\pic24-dspic\qk\- 

mplab-c30\dbg\. The make_24FJ128GA010.bat files assume that the Microchip MPLAB C30 toolset 

has been installed in the directory C:\tools\Microchip\mplab-c30. 

NOTE: You need to adjust the symbol MPLAB_C30 at the top of the batch scripts if you’ve installed 

the MPLAB C30 compiler into a different directory. 

In order to take advantage of the QS (“spy”) instrumentation, you need to build the QS version of the QP 

library. You achieve this by invoking the make_2800_ml.bat utility with the “spy” target, like this: 

make_24FJ128GA010 spy 

The make process should produce the QP library in the directory: \ports\pic24-dspic\qk\- 

mplab-c30\spy\. 

You choose the build configuration by providing a target to the make_24FJ128GA010.bat utility. The 

default target is “dbg”. Other targets are “rel”, and “spy”, respectively. 

Table 1 Make targets for the Debug, Release, and Spy library versions 

Software Version 

Build command 

Debug (default) 

make_ 

Release 

make_ rel 

Spy 

make_ spy 

2.3 Building and Running the Examples 

The examples included in this QDK are based on the standard DPP application implemented with active 

objects (see Quantum Leaps Application Note: “Dining Philosophers Problem Application” [QL AN-DPP 

08] included in this QDK). The example directory contains the MPLAB workspaces and project file that 

you can load into the MPLAB IDE, as shown in Figure 4. 


8 of 35




Figure 4: The MPLAB IDE with the DPP example 

Program 

target device 

button 

Select project 

for the build 

configuration 

2.3.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 dpp-dbg.mcp (located in \examples\pic18\- 

vanilla\mplab-c18\dpp-picdem2plus\). 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. 

2.3.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.3.3 Programming the Example to Run Standalone 

The DPP example application comes with the dpp-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 


9 of 35




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 DPP application should start running 

standalone. 

2.3.4 Collecting the QS software trace 

QS (QP-Spy) is a software tracing facility built into all QP components and also available to the 

Application code. QS allows you to gain unprecedented visibility into your application by selectively 

logging almost all interesting events occurring within state machines, the framework, the kernel, and your 

application code. QS software tracing is minimally intrusive, offers precise time-stamping, sophisticated 

runtime filtering of events, and good data compression (see Chapter 11 in [PSiCC2]). 

The dpp-spy.mcp project contains the Spy configuration that enables the QS software tracing and links 

with the Spy-versions of the QP libraries (see Listing 1). You select the Spy configuration by activating the 

dpp-spy.mcp project in the MPLAB IDE (see Figure 4). 

Before you download and start the DPP-Spy configuration to the Explorer 16 board, you should connect 

the board’s build-in DB9 connector to your workstation via a straight serial cable. Figure 5 shows the 

QSPY output received from the DPP-Spy configuration. 

NOTE: Please note that only a small subset of the QSPY records are allowed through the QS filters. 

Please refer to the source code (bsp.c) and the “QSPY Reference Manual” [QSPY 08] for more 

information about using the QS filters. 

You launch the QSPY utility on a Windows PC as follows. Change the directory to the QSPY host utility 

\tools\qspy\win32\mingw\rel and execute: 

qspy –cCOM1 –b38400 –O2 –F2 –S2 –E1 –Q1 –P1 –B1 

The meaning of the parameters is as follows: 

-cCOM1 specifies COM port (change to actual COM port number you’re using) 

-b38400 specifies the baud rate (depends on the oscillator frequency of your board, see Section 7) 

-O2 specifies the size of an object pointer to 2 bytes 

-F2 specifies the size of a function pointer to 2 bytes. 

-E1 specifies the size of an event to 1 byte (an event may have up to 255 bytes). 

-Q1 specifies the size of a memory queue counter to 1 byte (a event queue can fit up to 255 events). 

-P1 specifies the size of a memory pool counter to 1 byte (a memory pool can manage up to 255 memory 

blocks). 

-B1 specifies the size of a memory block to 1 byte (a memory pool can manage block up to 255 bytes). 


10 of 35




Figure 5: QSpy output from the DPP-QSpy configuration 

“Dictionary” 

trace records 

Time stamp 

column 

State entry 

Transition 

Internal 

Transition 


11 of 35




3 Non-Preemptive “Vanilla” Port 

The “vanilla” port shows how to use QP on a bare metal PIC24-dsPIC-based system with the 

cooperative “vanilla” kernel. In this version you’re using the non-preemptive kernel built-into the QF 

framework and your’e not using the QK component. 

3.1 The qep_port.h Header File 

The QEP header file for the PIC24/dsPIC port is located in \ports\pic24-dspic\vanilla\mplabc30\qep_port.h. 

Listing 2 shows the qep_port.h header file for PIC24/dsPIC. 

NOTE: The QP port to the cooperative “Vanilla” kernel qep_port.h is generic and should not need 

to change for other PIC24/dsPIC applications. 

Listing 2: qep_port.h header file for the cooperative QP configuration and MPLAB-C30 compiler 

#ifndef qep_port_h 

#define qep_port_h 

(1) #define Q_SIGNAL_SIZE 2 

/* 2-byte signal space (64K signals) */ 

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

(2) 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; 

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

#endif /* qep_port_h */ 

(1) The macro Q_SIGNAL_SIZE defines the size (in bytes) of event signals. The allowed values are 1, 2, 

or 4 bytes. Here the value of Q_SIGNAL_SIZE is set to 2, which means that the QP application can 

use up to 64K different signals. 

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

compiler does not provide the standard header file. 

3.2 The qf_port.h Header File 

The QF header file for the PIC24/dsPIC port is located in \ports\pic24-dspic\ vanilla\mplabc30\qf_port.h. 

This file specifies the interrupt locking/unlocking policy (QF critical section) as well as 

the configuration constants for QF (see Chapter 8 in [PSiCC2]). 

The most important porting decision you need to make in the qf_port.h header file is the policy for 

locking and unlocking interrupts. The PIC24/dsPIC CPU allows using the simplest “unconditional interrupt 

unlocking” policy (see Section 7.3.2 of the book “Practical UML Statecharts in C/C++, Second Edition” 


12 of 35




[PSiCC2]), because PIC24/dsPIC can mask interrupt groups (INT1 - INT12) and individual interrupts in 

the Peripheral Interrupt Expansion (PIE) module. Listing 3 shows the qf_port.h header file for 

PIC24/dsPIC. 

Listing 3: The qf_port.h header file for PIC24/dsPIC. 

/* The maximum number of active objects in the application, see NOTE01 */ 

(1) #define QF_MAX_ACTIVE 8 

(2) #define QF_EVENT_SIZ_SIZE 1 

(3) #define QF_EQUEUE_CTR_SIZE 1 

(4) #define QF_MPOOL_SIZ_SIZE 1 

(5) #define QF_MPOOL_CTR_SIZE 1 

(6) #define QF_TIMEEVT_CTR_SIZE 2 

/* QF interrupt disable/enable, see NOTE02 */ 

(7) #define QF_INT_DISABLE() __asm__ volatile("disi #0x3FFF") 

(8) #define QF_INT_ENABLE() __asm__ volatile("disi #0x0000") 

/* QF critical section entry/exit, see NOTE02 */ 

(9) /* QF_CRIT_STAT_TYPE not defined: unconditional interrupt unlocking" policy */ 

(10) #define QF_CRIT_ENTRY(dummy) __asm__ volatile("disi #0x3FFF") 

(11) #define QF_CRIT_EXIT(dummy) __asm__ volatile("disi #0x0000") 

#include "qep_port.h" /* QEP port */ 

#include "qvanilla.h" /* "Vanilla" cooperative kernel */ 

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

(1) The QF_MAX_ACTIVE specifies the maximum number of active object priorities in the application. 

You always need to provide this constant in the QF port. Here, QF_MAX_ACTIVE is set to 8 to 

conserve some RAM, but you can increase this value up to 63 inclusive. 

(2-5) These object sizes in QF are all set to 1, meaning that uint8_t will be used to represent the various 

object sizes. 

NOTE: Please refer to Chapter 8 of [PSiCC2] for discussion of all configurable QF parameters. 

(6) These time event counter is configured to 2-bytes, meaning that timeouts of up to 65535 clock ticks 

can be handled in this QF port. 

(7) The interrupt disable 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. 

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). 

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

section. 


13 of 35




(9) The QF_CRIT_STAT_TYPE macro is not defined, which means that the simple policy of “unconditional 

interrupt disabling and enabling” is applied (see Section 7.3 in [PSiCC2]). 

(10) The critical section entry macro disables interrupts (see step (7)). 

(11) The critical section exit macro unconditionally enables interrupts (see step (8)). 

3.3 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-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 4: 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 */ 

#ifdef Q_SPY 

(5) l_tickTime += BSP_TMR2_PERIOD; /* account for TMR2 overflow */ 

#endif 

(6) QF_TICK(&l_T2Interrupt); /* 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) When software tracing is enabled, the ISR updates the 32-bit time stamp at tick, which is used to 

provide a 32-bit time stamp for the trace events. 


14 of 35




(6) 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.3.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 4(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.3.2 Shadow Registers Usage in ISRs 

The non-preemptive “vanilla” QP 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. 

3.3.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 5 shows assigning the priority 

to the Timer2 interrupt in function QF_onStartup(): 

Listing 5: 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 */ 

} 


15 of 35




3.4 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 DSP 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 6: QF_onIdle() for the non-preemptive (“vanilla”) QP port to PIC24/dsPIC 

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

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

(3) LED_OFF(IDLE_LED); 

(4) #ifdef Q_SPY 

. . . /* output Q-SPY trace data to the UART (see Section 7) */ 

(5) #elif defined NDEBUG 

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

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

#else 

(8) QF_INT_ENABLE(); /* enable interrupts, see NOTE01 */ 

#endif 

} 

(1) The QF_onIdle() callback is always called with interrupts disabled 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 still disabled, which means that the intensity 

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

(4) If QSPY software tracing is enabled, the QF_onIdle() callback tries to output one byte from the 

trace buffer to the SCI. See Section 7 for more information about QSPY software tracing. 

(5) 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. 

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

unlock after the IDLE mode. 

(7) 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]). 

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


16 of 35




4 Preemptive Configuration with QK 

The QP port to PIC24/dsPIC with the preemptive kernel (QK) 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-specific ISR Entry and Exit Macros (file qk_port.h) 

The preemptive QP 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 6. 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 6: 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 6). 


17 of 35




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-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 7. 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 7: 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-specific interrupt entry and exit sequence defined in the header file qk_port.h shown in Listing 7 

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 Kernel” explains how to use the macros QK_ISR_ENTRY() / QK_ISR_EXIT() and how 

these macros work at the assembly level. 

Listing 7: qk_port.h header file for the preemptive QP port with QK 

/* 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; \ 

__asm__ volatile ( \ 

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

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


18 of 35




"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 "qk.h" /* QK 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 Listing 8. The 

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

Section 3.3.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 Listing 8. 

4.2 ISRs with the Preemptive QK Kernel 

Even though the QK 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 8 shows how to write ISRs for the preemptive QK kernel: 

NOTE: The QK 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 8: T2Interrupt ISR for QK 

(1) QK_ISR(no_auto_psv) _T2Interrupt() { 

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

#ifdef Q_SPY 

(2) l_tickTime += BSP_TMR2_PERIOD; /* account for TMR2 overflow */ 

#endif 

QF_TICK(&l_T2Interrupt); /* handle all armed time events in QF */ 


19 of 35




(3) 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) When software tracing is enabled, the ISR updates the 32-bit time stamp at tick, which is used to 

provide a 32-bit time stamp for the trace events. 

(3) 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 9 shows the disassembled code for the _T2Interrupt ISR from Listing 8. 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 9: Disassembled code for T2Interrupt ISR 

72: QK_ISR(no_auto_psv) _T2Interrupt() { 

(1) 009F8 F80036 push.w 0x0036 

(2) 009FA BE9F80 mov.d 0x0000,[0x001e++] 

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

(4) 009FE DE00CD lsr 0x0000,#13,0x0002 

(5) 00A00 200010 mov.w #0x1,0x0000 

(6) 00A02 DD0001 sl 0x0000,0x0002,0x0000 

(7) 00A04 B76993 ior.b 0x0993 

(8) 00A06 370002 bra 0x000a0c 

(9) 00A08 F80036 push.w 0x0036 

(10) 00A0A BE9F80 mov.d 0x0000,[0x001e++] 

(11) 00A0C BE9F82 mov.d 0x0004,[0x001e++] 

(12) 00A0E BE9F84 mov.d 0x0008,[0x001e++] 

(13) 00A10 BE9F86 mov.d 0x000c,[0x001e++] 

(14) 00A12 781F88 mov.w 0x0010,[0x001e++] 

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

00A14 A9E084 bclr.b 0x0084,#7 

74: 

75: #ifdef Q_SPY 

76: l_tickTime += BSP_TMR2_PERIOD; /* TMR2 overflow */ 

77: #endif 

78: 

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

00A16 07027E rcall 0x000f14 

80: 

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

(15) 00A18 800218 mov.w 0x0042,0x0010 

(16) 00A1A DE4045 lsr 0x0010,#5,0x0000 

(17) 00A1C 600067 and.w 0x0000,#7,0x0000 

(18) 00A1E 200011 mov.w #0x1,0x0002 

(19) 00A20 DD0800 sl 0x0002,0x0000,0x0000 

(20) 00A22 B34010 ior.b #0x1,0x0000 


20 of 35




(21) 00A24 EAC000 com.b 0x0000,0x0000 

(22) 00A26 FC3FFF disi #16383 

(23) 00A28 B66993 and.b 0x0993 

(24) 00A2A E24993 cp0.b 0x0993 

(25) 00A2C 3A0003 bra nz, 0x000a34 

(26) 00A2E EF6042 clr.b 0x0042 

(27) 00A30 070178 rcall 0x000d22 

(28) 00A32 880218 mov.w 0x0010,0x0042 

(29) 00A34 FC0000 disi #0 

82: } 

(30) 00A36 78044F mov.w [--0x001e],0x0010 

(31) 00A38 BE034F mov.d [--0x001e],0x000c 

(32) 00A3A BE024F mov.d [--0x001e],0x0008 

(33) 00A3C BE014F mov.d [--0x001e],0x0004 

(34) 00A3E BE004F mov.d [--0x001e],0x0000 

(35) 00A40 F90036 pop.w 0x0036 

(36) 00A42 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 6) are loaded from the stack to w0. 

Please note that after pushing RCOUNT and w0,w1 pair, this information is 8 words 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




4.11 “Function Call Conventions” in [MPLAB-C30]). However, these 9 registers are still less than a 

half of all PIC24/dsPIC registers that are saved by most other traditional preemptive kernels/RTOSs 

such as MicroC/OS-II or FreeRTOS.org. The traditional RTOSs must save the whole register file of 

the CPU, because the kernel cannot optimize the saved context for each individual ISR. 

(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




The following Listing 10 shows an example implementation of QK_onIdle() for the PIC24/dsPIC. Please 

note that the ilde-LED is turned on and off in a critical section (so that the intensity of the LED does not 

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 10: QK_onIdle() callback for PIC24/dsPIC. 

QF_INT_DISABLE(); 

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

LED_OFF(IDLE_LED); 

QF_INT_ENABLE(); 

#ifdef Q_SPY 

while (U2STAbits.UTXBF == 0U) { /* TX Buffer not full */ 

uint16_t b; 

QF_INT_DISABLE(); 

b = QS_getByte(); 

QF_INT_ENABLE(); 

if (b == QS_EOD) { /* End-Of-Data reached */ 

break; /* break out of the loop */ 

} 

U2TXREG = (uint8_t)b; /* stick the byte to TXREG for transmission */ 

} 

#elif defined 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 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() { 

static QEvent const eat_evt = { EAT_SIG, 0 }; 

_INT0IF = 0; 

QACTIVE_POST(AO_Table, &eat_evt, &l_INT0Interrupt); 

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. 


23 of 35




Figure 8 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 8. 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. 

Figure 8: 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. 


24 of 35




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. 

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 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 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. 


25 of 35




5 Implementing “Zero Interrupt Latency” with the NMI 

As noted in Section 3.2, 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 services (e.g., NMIs cannot post events to QP 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 the QP. 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 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 

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). The question is how to achieve such communication without 

calling QP 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 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. In other 

CPUs, such as RISC load-store architectures, the implementation of atomic access is trickier and requires 

using special swap (SWP) instructions. 

5.2 Implementation Considerations for the NMIs 

Because the NMIs run completely “free” and outside the QP 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. 


26 of 35




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\vanilla\ 

mplab-c30\dpp-qk-explorer16_pic24\ for PIC24 and \examples\pic24_dspic\vanilla\ 

mplab-c30\dpp-qk-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 9. 

Figure 9 Setting the size of heap and stack 


27 of 35




6.2 The BSP header file bsp.h 

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

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

#define BSP_TICKS_PER_SEC 100 

void BSP_init(void); 

void BSP_displyPhilStat(uint8_t n, char const *stat); 

void BSP_busyDelay(void); /* to artificially extend RTC processing */ 

6.3 BSP initialization 

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

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

Listing 11: 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 */ 

} 

if (QS_INIT((void *)0) == 0) { /* initialize the QS software tracing */ 

Q_ERROR(); 

} 

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 */ 

} 

6.5 Assertion Handling Policy in Q_onAssert() 

As described in Chapter 6 of [PSiCC2], all QP 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 


28 of 35




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 */ 

} 

} 


29 of 35




7 The QS Software Tracing Instrumentation 

QS is a software tracing facility built into all QP components and also available to the Application code. 

QS allows you to gain unprecedented visibility into your application by selectively logging al-most all 

interesting events occurring within state machines, the framework, the kernel, and your application code. 

QS software tracing is minimally intrusive, offers precise time-stamping, sophisticated runtime filtering of 

events, and good data compression (see Chapter 11 in PSiCC2 [PSiCC2]). 

This QDK demonstrates how to use the QS software tracing instrumentation to generate real-time trace of 

a running QP application. QS can be configured to send the trace data out of the serial port of the target 

device. On the Explorer 16 board, QS uses the built-in UART2 to send the trace data to the host. The QS 

platform-dependent implementation is located in the file bsp.c and looks as follows: 

(1) #ifdef Q_SPY 

Listing 12: QS implementation to send data with UART2 of PIC24/dsPIC MCU 

(2) static uint32_t l_tickTime; /* timestamp at tick */ 

(3) enum AppRecords { /* application-specific trace records */ 

PHILO_STAT = QS_USER 

}; 

#define QS_BUF_SIZE 

#define BAUD_RATE 

1024U 

38400U 

(4) uint8_t QS_onStartup(void const *arg) { 

(5) static uint8_t qsBuf[QS_BUF_SIZE]; /* buffer for Quantum Spy */ 

(6) QS_initBuf(qsBuf, sizeof(qsBuf)); /* initialize the QS trace buffer */ 

/* initialize the UART2 for transmitting the QS trace data */ 

(7) TRISFbits.TRISF5 = 0; /* set UART2 TX pin as output */ 

U2MODE = 0x0008; /* enable high baud rate */ 

U2STA = 0x0000; /* use default settings of 8N1 */ 

U2BRG = ((BSP_FCY_HZ / 4 / BAUD_RATE) - 1); /* baud rate generator */ 

U2MODEbits.UARTEN = 1; 

U2STAbits.UTXEN = 1; 

(8) QS_FILTER_ON(QS_ALL_RECORDS); 

/* setup the QS filters... */ 

// QS_FILTER_OFF(QS_QEP_STATE_EMPTY); 

// QS_FILTER_OFF(QS_QEP_STATE_ENTRY); 

// QS_FILTER_OFF(QS_QEP_STATE_EXIT); 

// QS_FILTER_OFF(QS_QEP_STATE_INIT); 

// QS_FILTER_OFF(QS_QEP_INIT_TRAN); 

// QS_FILTER_OFF(QS_QEP_INTERN_TRAN); 

// QS_FILTER_OFF(QS_QEP_TRAN); 

// QS_FILTER_OFF(QS_QEP_dummyD); 

QS_FILTER_OFF(QS_QF_ACTIVE_ADD); 

. . . 


30 of 35




return (uint8_t)1; /* indicate successfull QS initialization */ 

} 

/*..........................................................................*/ 

(9) void QS_onCleanup(void) { 

} 

/*..........................................................................*/ 

(10) void QS_onFlush(void) { 

uint16_t b; 

while ((b = QS_getByte()) != QS_EOD) { /* next QS trace byte available */ 

while (U2STAbits.UTXBF != 0U) { /* TX Buffer full */ 

} 

U2TXREG = (uint8_t)b; /* stick the byte to TXREG for transmission */ 

} 

} 

/*..........................................................................*/ 

/* NOTE: invoked within a critical section (inetrrupts disabled) */ 

(11) QSTimeCtr QS_onGetTime(void) { 

(12) if (_T2IF == 0) { 

(13) return l_tickTime + (uint32_t)TMR2; 

} 

else { 

(14) return l_tickTime + BSP_TMR2_PERIOD + (uint32_t)TMR2; 

} 

} 

#endif /* Q_SPY */ 

(1) The QS instrumentation is enabled only when the macro Q_SPY is defined 

(2) The l_tickTime variable is used to hold the 32-bit-wide the timestamp at tick and is updated in the 

system clock tick ISR. 

(3) This enumeration defines application-specific QS trace record(s), to demonstrate how to use them. 

(4) You need to define the QS_init() callback to initialize the QS software tracing. 

(5) You should adjust the QS buffer size (in bytes) to your particular application 

(6) You always need to call QS_initBuf() from QS_init() to initialize the trace buffer. 

(7) This block of code sets up UART2 to output data at the desired baud rate and standard format 

(8N1). 

(8) The QS filters are set-up statically. 

(9) The QS_onCleanup() callback performs the cleanup of QS. Here nothing needs to be done. 

(10) The QS_onFlush() callback flushes the QS trace buffer to the host. Typically, the function busywaits 

for the transfer to complete. It is only used in the initialization phase for sending the QS 

dictionary records to the host (see please refer to “QSP Reference Manual” section in the “QP/C 

Reference Manual” an also to Chapter 11 in [PSiCC2]) 

7.1 QS Time Stamp Callback QS_onGetTime() 

The platform-specific QS port must provide function QS_onGetTime() (Listing 12(11)) that returns the 

current time stamp in 32-bit resolution. To provide such a fine-granularity time stamp, the PIC24/dsPIC 

port uses the Timer2, which is the same timer already used for generation of the system clock-tick 

interrupt. 


31 of 35




NOTE: The QS_onGetTime() callback is always called with interrupts locked. 

Figure 10 shows how the Timer2 is extended to 32 bits. The TMR2 register counts up from zero to the 

reload value stored in the PR2 register. When TMR2 reaches PR2, the hardware automatically clears TMR2 

on the subsequent clock tick. Simultaneously, the hardware sets the _T2IF flag, which triggers the 

system clock tick interrupt. 

The system clock tick ISR _T2Interrupt() keeps updating the “tick count” variable l_tickTime (see 

Listing 4(5) and Listing 8(2)) by incrementing it each time by QS_tickPeriod_. The clock-tick ISR also 

clears the _T2IF flag. 

Figure 10: Using 16-bit Timer2 to provide 32-bit QS time stamp. 

count 

32-bit time stamp 

returned from 

QS_onGetTime() 

count in 

_T2Interrupt() 

System 

clock tick 

period 

0x00FFFFFF 

Count in TMR2 

Current Register 

Timer2 

Reload 

Value 

Register 

System 

clock-tick 

time 

Listing 12(11-15) shows the implementation of the function QS_onGetTime(), which combines all this 

information to produce a monotonic time stamp. 

(12) The QS_onGetTime() function tests the _T2IF flag to determine whether This flag being set means 

that the TMR2 counter has rolled over to zero, but the _T2Interrupt() ISR has not run yet 

(because interrupts are still locked). 

(13) Most of the time the _T2IF flag is not set, and the time stamp is simply the sum of l_tickTime + 

(uint32_t)TMR2). 

(13) If the _T2IF flag is set, the TMR2 counter misses one update period and must be additionally 

incremented by BSP_TMR2_PERIOD_, which is a compile-time constant. 


32 of 35




7.2 QS Trace Output in QF_onIdle()/QK_onIdle() 

To be minimally intrusive, the actual output of the QS trace data happens when the system has nothing 

else to do, that is, during the idle processing. The following code snippet shows the code placed either in 

the QF_onIdle() callback (“Vanilla” port), or QK_onIdle() callback (in the QK port): 

Listing 13: QS trace output using the UART0 of the Stellaris LM3S811 MCU 

#define UART_TXFIFO_DEPTH 16 

. . . 

void QK_onIdle(void) { 

. . . 

#ifdef Q_SPY 

(1) while (U2STAbits.UTXBF == 0U) { /* TX Buffer not full */ 

uint16_t b; 

(2) QF_INT_LOCK(dummy); 

(3) b = QS_getByte(); 

(4) QF_INT_UNLOCK(dummy); 

(5) if (b == QS_EOD) { /* End-Of-Data reached */ 

(6) break; /* break out of the loop */ 

} 

(7) U2TXREG = (uint8_t)b; /* stick the byte to TXREG for transmission */ 

} 

#elif defined NDEBUG 

__asm__ volatile("disi #0x0001"); 

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

#else 

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

#endif 

} 

(1) As long as the UTXBF (TX buffer full) flag is not set, the UART2 TX FIFO can accept new bytes. 

(2) Interrupts are locked to call QS_getByte(). 

(3) The function QS_getByte() returns the next byte or QS_EOD (end-of-data) if the QS ring buffer is 

empty. 

(4) The interrupts are unlocked after the call to QS_getByte(). 

(5-6) If end-of-data is reached the loop is terminated for this invocation of QK_onIdle(). 

(7) The byte obtained from the QS buffer is inserted into the UART2 transmit register for transmission. 

7.3 Invoking the QSpy Host Application 

The QSPY host application receives the QS trace data, parses it and displays on the host workstation 

(currently Windows or Linux). For the configuration options chosen in this port, you invoke the QSPY host 

application as follows (please refer to “QSP Reference Manual” section in the “QP/C Reference Manual” 

an also to Chapter 11 in [PSiCC2]): 

qspy –cCOM1 –b38400 –O2 –F2 –S1 –E1 –Q1 –P1 –B1 


33 of 35




8 Related Documents and References 

Document 

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

Second Edition”, Miro Samek, Newnes, 2008 

[QP 08] “QP Reference Manual”, Quantum 

Leaps, LLC, 2008 

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

Directory Structure”, Quantum Leaps, LLC, 2007 

[QL AN-DPP 08] “Application Note: Dining 

Philosopher Problem 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.state-machine.com/doc/AN_DPP.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 


34 of 35




9 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 


35 of 35

QDK PIC24/dsPIC-C30 - Quantum Leaps

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?