QDK PIC24/dsPIC-XC16 - Quantum Leaps

QP state machine frameworks for PIC24/dsPIC 

QDK 

PIC24/dsPIC-XC16 

Document Revision E 

February 2013

Table of Contents 

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

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

1.2 About QM .............................................................................................................................................. 3 

1.3 About this QDK ......................................................................................................................................... 3 

1.4 About the QP Port to PIC24/dsPIC ........................................................................................................ 4 

1.5 What’s Included in the QDK-PIC24-dsPIC .............................................................................................. 5 

1.6 Licensing QP ......................................................................................................................................... 5 

1.7 Licensing QM ........................................................................................................................................ 5 

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

2.1 Building the QP Libraries .......................................................................................................................... 8 

2.2 Building and Running the Examples ......................................................................................................... 9 

2.2.1 Building the Example Projects in the MPLABX IDE ........................................................................ 9 

2.2.2 Programming the Example to Run under the MPLAB Debugger ................................................... 9 

2.2.3 Collecting the QS software trace .................................................................................................... 10 

3 Cooperative “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.3.1 PSV Usage in ISRs ....................................................................................................................... 15 

3.3.2 Shadow Registers Usage in ISRs ................................................................................................. 15 

3.3.3 Assigning/Changing Interrupt Priorities in Software ....................................................................... 15 

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

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.2.1 Explanation of ISR code for the preemptive QK kernel ................................................................. 20 

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

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

4.4.1 Interrupt Nesting Test ..................................................................................................................... 24 

4.4.2 Task Preemption Test .................................................................................................................... 24 

4.4.3 Other Tests .................................................................................................................................... 25 

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 Microstick II 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() ............................................................................................... 29 

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/C state machine framework with the 

Microchip PIC24/dsPIC MCUs/DSCs and the Microchip MPLABX IDE and the XC16 compiler. The actual 

hardware/software used to test this QDK as shown in Figure 1 and described below: 

Figure 1: Microstick II board with TTL-RS232 transceiver 

Microstick II 

board with 

PKOB debugger 

User LED 

USB to PC 

(power + debugging) 

PIC24/dsPIC 

device 

QS data 

to host PC 

TTL to RS232 

transceiver board 

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

1. Microchip Microstick II board [Microstick2] with PIC24FJ64GB002 or dsPIC33FJ128MC devices 

2. Microchip MPLABX® IDE v1.41 and XC16 compiler v1.10 

3. QP/C 4.5.04 or higher 


1 of 35



www.state-machine.com/pic 

NOTE: For the QS (Q-SPY) software tracing output, you also need a 

TTL-to-RS-232 transceiver board. Such boards are available from a 

number of vendors. For example Figure 1 shows the RS232 to TTL 

converter board 3.3V to 5V from NKC Electronics ($9.99 

http://www.nkcelectronics.com/rs232-to-ttl-converter-board- 

33v232335.html). 

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

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 QM 

QM (QP Modeler) is a free, cross-platform, graphical UML modeling tool for 

designing and implementing real-time embedded applications based on the 

QP state machine frameworks. QM is available for Windows, Linux, and 

Mac OS X. QM provides intuitive diagramming environment for creating good 

looking hierarchical state machine diagrams and hierarchical outline of your 

entire application. QM eliminates coding errors by automatic generation of 

compact C or C++ code that is 100% traceable from your design. Please visit 

state-machine.com/qm for more information about QM. 

1.3 About this QDK 

This QDK provides working examples of code running under both the cooperative Vanilla kernel and the 

preemptive QK kernel. The example code is based on the Dining Philosopher Problem (DPP) sample 

application described in Chapter 7 of [PSiCC2] as well as in the Application Note “Dining Philosopher 

Problem” [QL AN-DPP 08] (included in the example code distribution). 

The entire source code included with this QDK can be edited manually in a traditional code editor. 

However, significant parts of the code have been generated automatically by the QM modeling tool 

from the dpp.qm model file included in the QDK. The preferred way of developing QP applications is to 

make all the changes in the model and generate the code automatically. 

Figure 3: The example model opened in the QM modeling tool 

NOTE: The significant parts of the source code (files dpp.h, philo.c, and table.c) have been 

generated by the QM modeling tool from the dpp.qm model, which is the same for the Vanilla and 

QK versions of the DPP application. These files can be edited by hand (after unchecking the readonly 

property), but the changes made at the code level won't be incorporated back into the model. 


3 of 35




1.4 About the QP Port to PIC24/dsPIC 

Figure 4 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 4. This triggered interrupt of IPL 1..6 can call QP services for 

signaling the QP tasks (active objects). 

Figure 4: 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 


4 of 35




XC18 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.5 What’s Included in the QDK-PIC24-dsPIC 

This QDK provides the QP port for PIC24 and dsPIC MCUs and two versions of the Dining Philosopher 

Problem (DPP) example for each processor (with the cooperative “vanilla” kernel and the preemptive QK 

kernel). The actual devices used for testing were: PIC24FJ64GB002 (PIC24) and dsPIC33FJ128MC 

(dsPIC). 

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

1.7 Licensing QM 

The QM graphical modeling tool available for download from the www.statemachine.com/downloads 

website is free to use, but is not open source. During the 

installation you will need to accept a basic End-User License Agreement (EULA), 

which legally protects Quantum Leaps from any warranty claims, prohibits removing 

any copyright notices from QM, selling it, and creating similar competitive products. 


5 of 35




2 Getting Started 

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

for a specific QDK version, such as 4.5.02). 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-XC16 

/ 

- QP Root Directory 

+-doc\ 

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

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

| 

+-ports/ 

- QP ports 

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

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

| | | +-xc16\ - Microchip MPLABX XC16 compiler 

| | | | +-dbg\ – Debug build 

| | | | | +-libqp_24FJ64GB002.a – QP library for PIC24FJ64GB002 

| | | | | +-libqp_33FJ128MC802.a – QP library for dsPIC33FJ128MC802 

| | | | +-rel\ – Release build 



| | | | +-spy\ – Spy build 



| | | | +-make_24FJ64GB002.bat – Batch to build QP for PIC24FJ64GB002 

| | | | +-make_33FJ128MC802.bat – Batch to build QP for dsPIC33FJ128MC802 

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



| | | | +-make_24FJ64GB002.bat – Batch to build QP for PIC24FJ64GB002 

| | | | +-make_33FJ128MC802.bat – Batch to build QP for dsPIC33FJ128MC802 

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

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


6 of 35




| | | | +-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-microstick2-pic24.X\ - DPP example for Microstick II with PIC24 

| | | | | +-build\ - directory containing the builds 

| | | | | +-dist\ - directory containing the distribution (binaries) 

| | | | | +-nbproject\ - Net Beans project (MPLABX project data) 

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

| | | | | +-dpp.qm - the DPP model file for QM 

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

| | | | | 

| | | | +-dpp-microstick2-dspic.X\ - DPP example for Microstick II with dsPIC 




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







| | | 

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


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




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







| | | | | 

| | | | +-dpp-qk-microstick2-dspic.X\ - DPP example for Microstick II with dsPIC 




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








7 of 35




2.1 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 MPLABX 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 MPLABX XC16 compiler, QK kernel, you open a console window on a 

Windows PC, change directory to \ports\pic24-dspic\qk\xc16\, and invoke the batch by typing 

at the command prompt the following command: 

make_24FJ64GB002.bat 

For the PIC24FJ64GB002 MCU and 

make_33FJ128MC802.bat 

for the dsPIC33FJ128MC802 MCU. 

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

installed the XC16 compiler into a different directory. 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\- 

xc16\dbg\. The make_24FJ64GB002.bat files assume that the Microchip MPLABX XC16 toolset has 

been installed in the directory C:\tools\Microchip\xc16\v1.10. 

NOTE: It is highly recommended that you re-build the QP libraries yourself, because the libraries that 

ship in the QDK have been built with optimizations disabled due to the expiration of the license key. 

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_24FJ64GB002.bat utility with the “spy” target, like this: 

make_24FJ64GB002.bat spy 

The script should produce the QP library in the directory: \ports\pic24-dspic\qk\xc16\spy\. 

You choose the build configuration by providing a target to the make_24FJ64GB002.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 


8 of 35




2.2 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 MPLABX workspaces and project file that 

you can load into the MPLABX IDE, as shown in Figure 5. 

Figure 5: The MPLABX IDE with the DPP example 

Active build 

configuration 

Build 

tool 

Debug 

tool 

2.2.1 Building the Example Projects in the MPLABX IDE 

1. Connect the USB cable between the Microstick II board and the PC. 

2. Launch the MPLABX IDE and open the project (menu File | Open Project...) located in \- 

examples\pic24_dspic\vanilla\xc16\dpp-qk-microstick2-pic24.X\). Figure 5 shows the 

screen shot of the MPLABX IDE after opening the project. 

3. Select the build configuration from the combo box next to the hammer tool (Figure 5) 

4. Build the project by clicking on the hammer tool. 

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 Debug button, 

which is shown in Figure 5. 


9 of 35




2.2.3 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 Spy configuration enables the QS software tracing and links with the Spy-versions of the QP libraries 

(see Listing 1). In the MPLABX IDE you select the Spy configuration by means of the combo box located 

near the “hammer” button (see Figure 5). 

For the QS (Q-SPY) software tracing output, you need to connect a TTL to RS-232 transceiver to the 

Microstick II board, as shown in Figure 6. The figure shows the RS232 to TTL converter board 3.3V to 5V 

from NKC Electronics (http://www.nkcelectronics.com/rs232-to-ttl-converter-board-33v232335.html), but 

you can use any other equivalent board. 

NOTE: To connect the transceiver, you might need to solder the pins into the connectors of the 

Microstick II board, as shown in Figure 6. 

Figure 6: Connecting RS232-TTL board to the Microstick II board. 

J6 

J6[5] 

GND 

VDD 

Q-SPY trace 

data to host 

TTL-RS-232 

transceiver 

board 

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) 


10 of 35




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

Figure 7: QSpy output from the spy build configuration of the DPP example 


11 of 35




3 Cooperative “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\xc16\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 XC16 compiler 

#ifndef qep_port_h 

#define qep_port_h 

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

(1) #include 

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

#endif /* qep_port_h */ 

(1) The XC16 compiler support the C99 exact-width integer types 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\xc16\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” 

[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 


12 of 35




(6) #define QF_TIMEEVT_CTR_SIZE 2 

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

(7) #define QF_INT_DISABLE() __builtin_disi(0x3FFFU) 

(8) #define QF_INT_ENABLE() __builtin_disi(0x0000U) 

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

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

(10) #define QF_CRIT_ENTRY(dummy) __builtin_disi(0x3FFFU) 

(11) #define QF_CRIT_EXIT(dummy) __builtin_disi(0x0000U) 

/* fast log-base-2 with FBCL instruction, NOTE03 */ 

(12) #define QF_LOG2(n_) ((uint8_t)(15 + __builtin_fbcl(n_))) 

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

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

(12) The QF_LOG2() macro is defined to take advantage of the FBCL instruction. 

NOTE: FBCL instruction (Find First Bit Change Left) determines the exponent of a value by detecting 

the first bit change starting from the value’s sign bit and working towards the LSB. Since the 

PIC24/dsPIC’s barrel shifter uses negative values to specify a left shift, the FBCL instruction returns 

the negated exponent of a value. This value added to 15 gives the log-2. 


13 of 35




3.3 ISRs in the Non-Preemptive “Vanilla” Configuration 

The MPLABX XC16 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 XC16 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 [XC16] 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. 

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


14 of 35




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 XC16 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 [XC16] 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 = (uint16_t)(BSP_TMR2_PERIOD – 1.0 + 0.5); /* Timer2 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 */ 

} 

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. 


15 of 35




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) Typically, the DPP application uses one LED to visualize the idle loop activity. Usually, 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. However, the Microstick II has only one user LED, which cannot be 

spared for the idle loop, because it is needed to show the DPP status. 

(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 8. 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 8: 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 8). 


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 9. 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 9: 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\xc16\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 XC16 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 XC16 compiler. The MPLABX XC16 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 */ 

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

} 


19 of 35




(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 

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

(22) 00A26 FC3FFF disi #16383 

(23) 00A28 B66993 and.b 0x0993 


20 of 35




(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 XC16 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 8) 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




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

the XC16 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




void QK_onIdle(void) { 

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

#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 QEvt const eat_evt = { EAT_SIG, 0U, 0U }; 

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

Figure 10 shows how to trigger the INT0 interrupt from the MPLABX debugger. From the debugger you 

need to first open the “File Registers” window (menu View | File Registers) as shown in Figure 10. 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. 


23 of 35




Figure 10: Triggering the INT0 interrupt from the MPLABX debugger 

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 privatization. You observe the order in which the breakpoints are hit. This procedure will become 

clearer after a few examples. 

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_sched_() 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_sched_(), 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. 

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

activated before the control returns to the preempted Philosopher task. 


24 of 35




3. After hitting the breakpoint in QK_sched_() 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_sched_(). (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 XC16 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 Microstick II 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\ 

xc16\dpp-qk-microstick2_pic24\ for PIC24 and \examples\pic24_dspic\vanilla\ 

xc16\dpp-qk-microstick2_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. 

6.1 Setting the Sizes of Stack and Heap 

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

Figure 11 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 

100U 

void BSP_init(void); 

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

void BSP_displayPaused(uint8_t paused); 

. . . 

6.3 BSP initialization 

The following BSP_init() function for the Microstick II board configures the DSP and peripherals as, 

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

element is configuring the FRC (Fast RC Oscillator) clock by setting the flash word 2. Of course, the clock 

configuration can be different in your projects, but it must be consistent with the settings for various 

peripherals, such as timers, UARTs, etc. 

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

_CONFIG2(FNOSC_FRC); /* set flash configuration for the device */ 

. . . 

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 = 0x0000U; /* Use Internal Osc (Fcy), 16 bit mode, prescaler = 1 */ 

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

PR2 = (uint16_t)(BSP_TMR2_PERIOD – 1.0 + 0.5); /* Timer2 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 */ 

} 


28 of 35




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 

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

QF_INT_DISABLE(); /* make sure that interrupts are disabled */ 

for (;;) { 

} 

} 


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 1024U 

#define BAUD_RATE 38400.0 

(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) RPOR5bits.RP11R = 5; /* Assign U2TX To Pin RP11 */ 

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

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

U2BRG = ((BSP_FCY_HZ / 4.0 / BAUD_RATE) – 1.0 + 0.5); /* baud rate */ 

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 12 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 12: 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 UART on the PIC24FJ CPU 

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

[Microstick2] “Microstick II Information Sheet”, 

Microchip, 2011 

[XC16] “MPLAB® XC16 C Compiler User’s 

Guide”, Microchip, 2012. 

[PIC24] “PIC24FJ64GB004 FAMILY”, Microchip, 

2010. 

[dsPIC] “dsPIC33FJ32MC302/304, 

dsPIC33FJ64MCX02/X04 and 

dsPIC33FJ128MCX02/X04”, Microchip, 2012. 

[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 #DS51951B, available online at 

www.microchip.com 

Microchip literature #DS52071B, available online at 


Microchip literature #DS39940D, available online at 


Microchip literature #DS70291G, available online at 


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-XC16 - Quantum Leaps

Create successful ePaper yourself

Delete template?

Save as template?