Directories and Files in the QP/C Distribution

The following annotated directory tree lists the most important directories and files provided in the standard QP distribution. The explanation section immediately following the directory tree explains the structure in more detail.

 (1) qpc\                 - QP/C root directory
       |
 (2)   +-qpc.chm          - "QP/C Reference Manual" in CHM Help format
       |
 (3)   +-doxygen\         - QP documentation generated with Doxygen
       | +-html\          - "QP/C Reference Manual" in HTML format
 (4)   | | +-index.html   - The HTML index page for the "QP/C Reference Manual"
       | | +- . . .
       | +-Doxyfile       - Doxygen configuration file to generate the Manual
       | +- . . .
       |
 (5)   +-examples\        - QP examples
 (6)   | +-80x86\         - Examples for the 80x86 processor
 (7)   | | +-dos\         - Examples for DOS with the "vanilla" cooperative kernel
 (8)   | | | +-watcom\    - Examples with the Open Watcom compiler
 (9)   | | | | +-l\       - Examples using the Large memory model
(10)   | | | | | +-dpp\   - Dining Philosopher Problem (DPP) example for DOS
       | | | | | | +-dbg\ - Debug build
       | | | | | | | +-dpp.exe - Debug executable
(11)   | | | | | | +-rel\      - Release build
       | | | | | | | +-dpp.exe - Release executable
(12)   | | | | | | +-spy\      - Spy build (with QS tracing instrumentation)
       | | | | | | | +-dpp.exe - Spy executable
(13)   | | | | | | +-make.bat  - batch script to build the application
       | | | | | |
       | | | | | +-game\       - "Fly 'n' Shoot" game example
       | | | | | | +-dbg\      - Debug build
       | | | | | | | +-GAME.EXE   - Debug executable
       | | | | | | +-make.bat  - batch script to build the application
       | | | | | | +-game.h    - The application header file
       | | | | | | +-bsp.c     - BSP for the application
       | | | | | | +-main.c    - main() function
       | | | | | |
       | | | | | +-calc\    - Calculator example
       | | | | | +-qhsmtst\ - QHsmTst example (PSiCC2  in Chapter 2)
       | | | | | |
(14)   | | | | | +-comp\    - "Orthogonal Component" pattern (PSiCC2 Chapter 5)
       | | | | | +-defer\   - "Deferred Event" pattern (PSiCC2 Chapter 5)
       | | | | | +-history\ - "Transition to History" pattern (PSiCC2 Chapter 5)
       | | | | | +-hook\    - "Ultimate Hook" pattern (Chapter 5)
       | | | | | +-reminder\ - "Reminder" pattern (PSiCC2 Chapter 5)
       | | |
(15)   | | +-qk\          - Examples for the QK preemptive kernel
(16)   | | +-ucos2\       - Examples for the µC/OS-II RTOS
       | | |
(17)   | | +-linux\       - Examples for Linux (POSIX)
       | | | +-gnu\       - Examples with the GNU compiler
       | | | | +-dpp\     - Dining Philosopher Problem (DPP) example for Linux
       | | | | | +-dbg\   - Debug build
       | | | | | +-rel\      - Release build
       | | | | | +-spy\      - Spy build (with software instrumentation)
(18)   | | | | | +-Makefile  - GNU Makefile to build the DPP application
       | | | | | +-. . .
       | |
(19)   | +-arm-cortex\    - Examples for ARM Cortex processor
       | | +-vanilla\     - Examples for the cooperative "vanilla" kernel
       | | | +-iar\       - Examples with the IAR compiler
       | | | | +-dpp-ev-lm3s811\  - DPP example for for EV-LM3S811 board
       | | | | +-game-ev-lm3s811\ - "Fly 'n' Shoot" example for EV-LM3S811 board
       | | | | +-. . .    - Other examples for ARM Cortex
       | | | +-gnu\       - Examples with the GNU compiler (Code Sourcery G++)
       | | | | +-dpp-ev-lm3s811\  - DPP example for for EV-LM3S811 board
       | | | | +-game-ev-lm3s811\ - "Fly 'n' Shoot" example for EV-LM3S811 board
       | | | | +-. . .    - Other examples for ARM Cortex
       | | |
       | | +-qk\          - Examples for the preemptive QK kernel
       | | | +-iar\       - Examples with the IAR compiler
       | | | | +-dpp-qk-ev-lm3s811\  - DPP example for for EV-LM3S811 board
       | | | | +-game-qk-ev-lm3s811\ - "Fly 'n' Shoot" example for EV-LM3S811 board
       | | | | +-. . .    - Other examples for ARM Cortex
       | | | +-gnu\       - Examples with the GNU compiler (Code Sourcery G++)
       | | | | +-dpp-qk-ev-lm3s811\  - DPP example for for EV-LM3S811 board
       | | | | +-game-qk-ev-lm3s811\ - "Fly 'n' Shoot" example for EV-LM3S811 board
       | | | | +-. . .    - Other examples for ARM Cortex
       | |
       | +-. . .          - Examples for other CPUs and compiler
       |
(20)   +-include\         - QP platform-independent header files
       | +-qassert.h      - QP assertions
       | +-qep.h          - QEP platform-independent interface
       | +-qf.h           - QF platform-independent interface
       | +-qk.h           - QK platform-independent interface
       | +-qs.h           - QS platform-independent active interface
       | +-qs_dummy.h     - QS platform-independent inactive interface
       | +-qequeue.h      - QF native event queue facility
       | +-qmpool.h       - QF native memory pool facility
       | +-qpset.h        - QF native priority set facility
       | +-qvanilla.h     - QF native "vanilla" cooperative kernel interface
       |
(21)   +-qep\             - QEP hierarchical event processor
       | +-source\        - QEP platform-independent source code (*.c files)
       | | +- . . .
       |
(22)   +-qf\              - QF real-time framework
       | +-source\        - QF platform-independent source code (*.c files)
       | | +- . . .
       |
(23)   +-qk\              - QK preemptive kernel
       | +-source\        - QK platform-independent source code (*.c files)
       | | +- . . .
       |
(24)   +-qs\              - QS software tracing (target component)
       | +-source\        - QS platform-independent source code (*.c files)
       | | +- . . .
       |
(25)   +-ports\           - Platform-specific QP ports
(26)   | +-80x86\         - Ports to the 80x86 processor
(27)   | | +-dos\         - Ports to DOS with the "vanilla" cooperative kernel
(28)   | | | +-watcom\    - Ports with the Open Watcom compiler
(29)   | | | | +-l\       - Ports using the Large memory model
(30)   | | | | | +-dbg\   - Debug build
(31)   | | | | | | +-qf.lib   - QF  library
(32)   | | | | | | +-qep.lib  - QEP library
       | | | | | +-rel\   - Release build
       | | | | | +-spy\   - Spy build (with software instrumentation)
       | | | | | | +-qep.lib  - QEP library
       | | | | | | +-qf.lib   - QF  library
       | | | | | | +-qs.lib   - QS  library
       | | | | | |
(33)   | | | | | +-make.bat   - batch script for building the QP libraries
(34)   | | | | | +-qep_port.h - QEP platform-dependent include file
(35)   | | | | | +-qf_port.h  - QF  platform-dependent include file
(36)   | | | | | +-qs_port.h  - QS  platform-dependent include file
(37)   | | | | | +-qp_port.h  - QP  platform-dependent include file
       | | |
       | | +-qk\          - Ports to the QK preemptive kernel
       | | | +-. . .
       | | |
       | | +-ucos2\       - Ports to the MicroC/OS-II RTOS
       | | | +-watcom\    - Ports with the Open Watcom compiler
       | | | | +-l\       - Ports using the Large memory model
(38)   | | | | | +-ucos2.86\  - MicroC/OS-II v2.86 object code and header files
(39)   | | | | | +-src\       - Port-specific source files
(40)   | | | | | | +-qf_port.c - QF port to µC/OS-II source file
       | | | | | +-. . .
       | | |
       | | +-linux\       - Ports to the Linux operating system (POSIX)
       | | | +-gnu\       - Ports with the GNU compiler
       | | | | +-src\         - Port-specific source files
       | | | | | +- qf_port.c - QF port to Linux source file
       | | | | +-. . .
       | |
       | +-arm-cortex\    - Ports to the ARM Cortex processor
       | | +-vanilla\     - Ports to the cooperative "vanilla" kernel
       | | | +-iar\       - Ports with the IAR compiler
       | | | | | +-dbg\   - Debug build
       | | | | | +-rel\   - Release build
       | | | | | +-spy\   - Spy build (with software instrumentation)
       | | | | | +-make_cortex-m3.bat - batch script for building QP libraries
       | | | | | +-qep_port.h - QEP platform-dependent include file
       | | | | | +-qf_port.h  - QF  platform-dependent include file
       | | | | | +-qs_port.h  - QS  platform-dependent include file
       | | | | | +-qp_port.h  - QP  platform-dependent include file
       | | | . . .
       | | | +-gnu\       - Ports with the GNU compiler (Code Sourcery G++)
       | | | | | +-dbg\   - Debug build
       | | | | | +-rel\   - Release build
       | | | | | +-spy\   - Spy build (with software instrumentation)
       | | | | | +-make_cortex-m3_cs.bat - batch script for building QP libraries
       | | | | | +-qep_port.h - QEP platform-dependent include file
       | | | | | +-qf_port.h  - QF  platform-dependent include file
       | | | | | +-qs_port.h  - QS  platform-dependent include file
       | | | | | +-qp_port.h  - QP  platform-dependent include file
       | | | . . .
       | | +-qk\          - Ports to the preemptive QK kernel
       | |   +-iar\       - Ports with the IAR compiler
       | |   +-gnu\       - Ports with the GNU compiler (Code Sourcery G++)
       | +-. . .          - Ports to other CPUs
       |
(41)   +-tools\           - QP-related tools for the host machine
(42)   | +-qspy\          - QSPY host application
       | | +-include\     - QSPY header files
       | | +-source\      - QSPY platform-independent source files
(43)   | | +-linux\       - QSPY port to Linux
       | | | +-gnu\       - QSPY port with the GNU compiler
       | | | | +-rel\     - Release build
       | | | | | +-qspy       - Linux executable (not provided -- must be built)
(44)   | | | | +-Makefile     - GNU Makefile to bulid QSPY for Linux
(45)   | | +-win32\       - QSPY ports to Win32
(46)   | | | +-mingw\     - QSPY port with the open source MinGW GNU compiler
       | | | | +-rel\     - Release build
       | | | | | +-qspy.exe   - Windows executable (console app)
       | | | | +-Makefile     - GNU Makefile to bulid QSPY for Win32 under MinGW
       | | | +-vc2008\    - QSPY port with Visual C++ 2008
(47)   | | | | +-Release\ - Release build
       | | | | | +-qspy.exe   - Windows executable (console app)
       | | | | +-qspy.sln     - Visual C++ solution to build QSPY
(48)   | | | +-vc6\       - QSPY port with Visual C++ 6.0
       | | | | +-Release\ - Release build
       | | | | | +-qspy.exe   - Windows executable (console app)
       | | | | +-qspy.dsw     - Visual C++ 6.0 workspace to build QSPY
(49)   | | +-matlab\      - MATLAB scripts to import QSPY data to MATLAB

• (1) Every QP version, such as QP/C, QP/C++, ir QP-nano resides in the separate directory branch, called henceforth QP Root Directory. The essential element of the design is that the QP Root Directory can be "plugged into" any branch of a hierarchical file system and you can move the QP Root Directory around, or even have multiple versions of the QP Root Directories. You can also freely choose the name of the QP Root Directory, although I recommend the directory names qpc\ for QP/C and qpcpp\ for QP/C++. The ability to relocate the QP Root Directory means that only relative paths should be used in the Makefiles, build scripts, workspaces, or project files.

• (2) The file qpc.chm contains the "QP/C Reference Manual" in CHM format.

• (3) The doxygen\ directory contains this "QP/C Reference Manual" generated with the Doxygen utility.

• (4) The html\ subdirectory contains this HTML verions of the "QP/C Reference Manual". In particular, the file index.html is the index page of the Manual.

• (5) The examples\ directory contains the application examples that are included in the standard QP/C distribution. The structure of the examples\ (and also ports\ directory) is the most complicated because of the large number of choices available, such as CPU architectures, compilers, operating systems, and compiler options. Each of those choices is represented as a separate level of nesting in a hierarchical directory tree, so that each dimension in the multi-dimensional space of options can be extended independently from the others. Also, the directory branch for each QP port is individually customizable, so each branch can represent only choices relevant for a given CPU, operating system, compiler, etc.

• (6) The CPU architecture is placed as the first level of nesting within the examples\ directory. Examples of CPU architectures are: 80x86, ARM, ARM Cortex, AVR, MSP430, M16C, etc. Please note that a separate directory is needed whenever the CPU architecture is significantly different. For example, even though the traditional ARM and the new ARM Cortex are related, the differences are significant enough to require a separate directory branch for ARM and ARM Cortex.

• (7) The second level of nesting, under the CPU architecture, is the operating system used. For example, in the 80x86 architecture, QP can operate under DOS (with the "vanilla" cooperative kernel), under the QK preemptive kernel, under the MicroC/OS-II RTOS, or under Linux (and perhaps other OSs, such as Win32).

Note:

The ordering of directory levels reflects the embedded focus in the QP design. In most standalone QF applications the CPU architecture is typically more important than the RTOS/OS. For general-purpose operating systems, such as Linux, the reversed order (operating system at a higher level than the CPU architecture) would perhaps feel more natural.

• (8) The next level of nesting, under each operating system directory, is the directory for the compiler used. For example, the DOS port can be compiled with the Open Watcom or perhaps with Borland C++. Similarly, the port to ARM Cortex with QK kernel can be compiled with the IAR, RealView, or GNU compilers.

• (9) In some ports, the compiler can emit code for various modes of the CPU. For example, a compiler for 80x86 under DOS can produce small, compact, large, or huge memory models. These different modes result in incompatible object code, and therefore each of them requires a separate branch. Please note that the compiler options level is optional. For example, the ARM Cortex CPU branch does not need the compiler options level.

• (10) Finally, the example application is located in its own directory. For example, the dpp\ directory contains the "Dining Philosopher Problem" application example for this particular CPU/Kernel/Compiler/Options combinations.

• (11) The dpp\dbg\ subdirectory contains the object files and the executable for the Debug configuration.

• (12) The dpp\rel\ subdirectory contains the object files and the executable for the Release configuration.

• (13) The dpp\spy\ subdirectory contains the object files and the executable for the Spy configuration (with the QS Software Tracing Instrumentation (Target Component)).

• (14) All five state designed patterns described in Chapter 5 of Practical UML Statecharts in C/C++, Second Edition (PSiCC2) are provided.

• (15) The directory qk\ contains examples for the QK preemptive kernel.

• (16) The directory ucos2\ contains examples for the MicroC/OS-II RTOS.

• (17) The directory linux\ contains examples for the Linux operating system.

Note:

The port to Linux also runs on many POSIX-compliant OSes/RTOSes, such as BSD, Solaris, MacOS X, and QNX.

• (18) The Makefile for building POSIX port is provided.

• (19) The directory arm-cortex\ contains QP examples for ARM Cortex.

• (20) The directory include\ contains platform-independent header files for QP all components. You need to point your C/C++ compiler to include files from this directory.

• (21-24) The platform-independent source code of each QP component is located in the separate directory. The sources files are only needed to re-build QP libraries, but you don't need to include these directories in the compiler's search path to build applications.

• (25) The directory ports\ contains platform-dependent header files and libraries to be used by QP applications. This directory structure is the most complicated because of the large number of choices available, such as CPU architectures, compilers, operating systems, and compiler options. Each of those choices is represented as a separate level of nesting in a hierarchical directory tree, so that each dimension in the multi-dimensional space of options can be extended independently from the others. Also, the directory branch for each port is individually customizable, so each branch can represent only choices relevant for a given CPU, operating system, compiler, etc.

• (26) The CPU architecture is placed as the first level of nesting within the ports\ directory. Examples of CPU architectures are: 80x86, ARM Cortex, ARM, AVR, MSP430, M16C, etc. Please note that a separate directory is needed whenever the CPU architecture is significantly different. For example, even though the traditional ARM and the new ARM Cortex are related, the differences are significant enough to require a separate directory branch for ARM and ARM Cortex.

• (27) The second level of nesting, under the CPU architecture, is the operating system used. For example, in the 80x86 architecture, QP can operate under DOS (with the "vanilla" cooperative kernel), under the QK preemptive kernel, under the MicroC/OS-II RTOS, or under Linux (and perhaps other OSs, such as Win32).

Note:

The ordering of directory levels reflects the embedded focus in the QP design. In most standalone QF applications the CPU architecture is typically more important than the RTOS/OS. For general-purpose operating systems, such as Linux, the reversed order (operating system at a higher level than the CPU architecture) would perhaps feel more natural.

• (28) The next level of nesting, under each operating system directory, is the directory for the compiler used. For example, the DOS port can be compiled with the Open Watcom or perhaps with Borland C++. Similarly, the port to ARM Cortex with QK kernel can be compiled with the IAR, RealView, or GNU compilers.

• (29) In some ports, the compiler can emit code for various modes of the CPU. For example, a compiler for 80x86 under DOS can produce small, compact, large, or huge memory models. These different modes result in incompatible object code, and therefore each of them requires a separate branch. Please note that the compiler options level is optional. For example, the ARM Cortex CPU branch does not need the compiler options level.

• (30) Finally, the QP libraries can be compiled with different compile-time switches and optimization options. For example, the dbg\ directory holds the Debug configuration, which contains the symbolic debug information.

• (31) Each specific build directory contains the QP library files. The actual library names should comply with the conventions used on a particular platform. For example, on Linux the libraries are typically named libXXX.a (e.g., libqep.a, libqf.a, etc.).

• (32) The rel\ directory holds the Release configuration, which typically does not contain debug information but might use aggressive optimizations for best performance.

• (33) The standard QP ports often contain a simple make.bat script or a Makefile for building all the QP libraries for the port. You typically can choose the build configuration by providing a target to the make.bat script or to the Makefile. The default target is "dbg". Other possible targets are "rel", and "spy". The following table summarizes the targets accepted by the make.bat scripts or the Makefiles.

Build Configuration	Build Command
Debug	make
Release	make rel
Spy	make spy

• (34) The qep_port.h header file contains platform-specific definitions of macros and typedef's for the QEP component.

• (35) The qf_port.h header file contains platform-specific definitions of macros and typedef's for the QF component.

• (36) The qk_port.h header file contains platform-specific definitions of macros and typedef's for the QK component.

• (37) The qs_port.h header file contains platform-specific definitions of macros and typedef's for the QS component.

• (38) The subdirectory ucos2.86\ contains the headers and object files of MicroC/OS-II v2.86, compiled for 80x86 with the Open Watcom compiler. This directory is provided only to allow you re-building the example applications based on the QF port to MicroC/OS-II. Typically, however, you will need to obtain the MicroC/OS-II source code to re-build it for the actual processor you're using.

• (39-40) QP ports to an external RTOS or OS, such as MicroC/OS-II or Linux require some "glue-code" to bolt the QF framework to the external RTOS/OS. This source code is placed in the file qf_port.c in the subdirectory src\.

• (41) The directory tools\ contains host-resident tools used for QP (see qspy_page).

• (42) The directory qspy\ contains the portable QSPY host utility.

• (43) The subdirectory linux\ contains QSPY port to Linux.

• (44) The Makefile for building Linux QSPY executable is provided.

• (45) The subdirectory win32\ contains QSPY port to Win32.

• (46-48) The Windows version of QSPY can be build with three different compilers.

• (49) The subdirectory matlab\ contains scripts to import QSPY data to MATLAB. You need to place this directory on the MATLAB path to convenietly access the scripts.

Copyright © 2002-2011 Quantum Leaps, LLC. All Rights Reserved.