mirror of
https://github.com/QuantumLeaps/qpc.git
synced 2025-02-04 07:13:16 +08:00
521 lines
39 KiB
Plaintext
521 lines
39 KiB
Plaintext
/**
|
|
\page tutorial QP/C Tutorial
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps.</I>
|
|
|
|
|
|
|
|
This Tutorial presents an example project implemented entirely with the QP/C active object framework using UML state machines and the event-driven paradigm. The example application is an interactive "Fly 'n' Shoot"-type game, which behaves intentionally similarly to the original "Quickstart" application that ships pre-programmed into the <a href="http://www.ti.com/tool/ek-lm3s811">LM3S811 evaluation kit from Texas Instruments</a> (see \ref F2s4 "Figure 2-4"), so that you can directly compare the event-driven approach with the traditional solution to essentially the same problem specification.
|
|
|
|
The <A HREF="http://sourceforge.net/projects/qpc/files/QP_C/"><B>QP/C Baseline Code</B></A> contains two versions of the game. A <B>Windows version</B> is provided for the standard Windows-based PC so that you don't need any special embedded board or toolset to play the game and experiment with the code. Also provided is an <B>embedded version</B> for the inexpensive ARM Cortex-M3 <a href="http://www.ti.com/tool/ek-lm3s811">EK-LM3S811 evaluation kit</a>. Both the PC and the ARM versions use the exact <B>same</B> source code for all application components and differ only in the Board Support Package (BSP).
|
|
|
|
\note To focus the discussion, this tutorial assumes that you are using a <B>Windows</B>-based PC. But the QP/C frameworks can be used on Linux and Mac OS X hosts just as well, and most of the discussion applies to these host operating systems.
|
|
|
|
\note The 16-bit DOS version of the "Fly 'n' Shoot" game described in the PSiCC2 book is still provided in the QP/C Baseline Code, but 16-bit DOS is no longer supported in modern Windows, so this version is not discussed here.
|
|
|
|
The tutorial consists of the following steps:
|
|
|
|
- \subpage tutorial1
|
|
- \subpage tutorial2
|
|
- \subpage tutorial3
|
|
- \subpage tutorial4
|
|
- \subpage tutorial5
|
|
- \subpage tutorial6
|
|
- \subpage tutorial7
|
|
|
|
|
|
Next Step: \ref tutorial1
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
/**
|
|
\page tutorial1 Step 1: Installing QP/C and Qtools
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial \n
|
|
Next Step: \ref tutorial2
|
|
|
|
\section S11 Downloading and Installing QP/C™
|
|
|
|
The <B>QP/C Baseline Code</B> is available for download from <A HREF="http://sourceforge.net/projects/qpc/files/QP_C/"><B>SourceForge.net</B></A>. On SourceForge choose the latest QP/C version folder and click on a self-extracting Windows EXE or a platform-independent ZIP file. The following screen shot shows the self-extracting Windows EXE, where you choose the destination folder for QP/C.
|
|
|
|
|
|
|
|
\note The QP/C installer will automatically create the <B>sub-directory `qpc` </B> inside the destination folder you specify. The rest of this tutorial assumes that you have chosen the default destination folder (`C:\qp\`), so that the QP/C installation directory will become `C:\qp\qpc` .
|
|
|
|
\section S12 Downloading and Installing Qtools™
|
|
|
|
<B>Qtools</B> is a collection of various open source tools for working with QP, such as the <a href="http://www.state-machine.com/doxygen/qspy/index.html">QSPY host application</a> for processing the QS software traces or the QFSGEN utility for generating ROM-based file systems. The Qtools collection for Windows, contains additionally the <b>GNU make</b> and the <b>GNU C/C++ compiler (MinGW)</b>, which you will use to build the "Fly 'n' Shoot" game example on Windows.
|
|
|
|
Qtools installation is very similar to installing the QP/C framework. The <B>Qtools Collection</B> is available for download from <A HREF="http://sourceforge.net/projects/qpc/files/Qtools/"><B>SourceForge.net</B></A>. On SourceForge choose the latest Qtools version folder and click on the self-extracting Windows EXE. The following screen shot shows extracting the Qtools files using the Windows EXE, where you choose the destination folder for the Qtools collection.
|
|
|
|
|
|
|
|
\note The Qtools installer will automatically create the <B>sub-directory `qtools` </B> inside the destination folder you specify. The rest of this tutorial assumes that you have chosen the default destination folder (`C:\tools\`), so that the Qtools installation directory will become `C:\tools\qtools`.
|
|
|
|
|
|
\section S13 Defining Environment Variables
|
|
|
|
To complete the installation process you need to define the <B>QPC</B> and <B>QTOOLS</B> environment variables and you need to append the <B>;\%QTOOLS\%\\bin</B> to the <B>PATH</B> variable on your machine (note the use of the semicolon <b>;</b> to separate directories in the <B>PATH</B>). All this will enable you to place your QP projects anywhere in your file system, without any particular relation to the location of the QP/C framework and to conveniently access the Qtools utilities on your PC.
|
|
|
|
\note The project files, make files, and build scripts provided in the QP/C distribution assume that the environment variable <B>QPC</B> has been defined and will not work if this variable is not provided.
|
|
|
|
The following table shows the environment variables and example values you need to define, assuming that you have installed QP/C into the default location `C:\qp\` and Qtools into the default location `C:\tools\` :
|
|
|
|
<CENTER>
|
|
Environment Variable | Example Value (adjust for your system)
|
|
---------------------|---------------------------------------
|
|
<B>QPC</B> | `C:\qp\qpc`
|
|
<B>QTOOLS</B> | `C:\tools\qtools`
|
|
<B>PATH</B> | `...;%%QTOOLS%\bin` (append to the <B>PATH</B>)
|
|
</CENTER>
|
|
|
|
\subsection S131 Editing Environment Variables on Windows 7
|
|
|
|
-# From the Desktop or the Start button, <B>right-click</B> My Computer and click Properties.
|
|
|
|
-# Click <B>Advanced System Settings</B> link in the left column.
|
|
|
|
-# In the System Properties window click the <B>Environment Variables</B> button.
|
|
|
|
|
|
|
|
\note Don't forget to insert a semicolon <b>;</b> to separate directories in the <B>PATH</B>
|
|
|
|
\subsection S132 Checking Environment Variable Settings on Windows
|
|
|
|
After you edit the environment variables on your system, you should verify your definitions by launching the Command Prompt window and typing the command <b>set</b>. The following screen shot shows the correctly defined variables <b>PATH</b>, <b>QPC</b>, and <b>QTOOLS</b>:
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial \n
|
|
Next Step: \ref tutorial2
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
/**
|
|
\page tutorial2 Step 2: Let's Play
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial1 \n
|
|
Next Step: \ref tutorial3
|
|
|
|
This step describes how to run the "Fly 'n' Shoot" game on Windows and on the ARM Cortex-M3 EK-LM3S811 board. Both the PC and the ARM versions use the exact <B>same</B> source code for all application components and differ only in the Board Support Package (BSP).
|
|
|
|
|
|
\section S21 Running the Game on Windows
|
|
|
|
You can run the "Fly 'n' Shoot" game on any Windows-based PC by simply double-clicking on the executable <b>game-gui.exe</b> located in the directory `<qp>\qpc\examples\win32\mingw\game-gui\dbg\`, where `<qp>` denotes the destination folder you chose to extract QP/C into. The following screen shot shows the relevant fragment of the QP/C directory tree in the Windows Explorer:
|
|
|
|
|
|
|
|
\anchor F2s2
|
|
|
|
|
|
As you can see in (see \ref F2s2 "Figure 2-2"), the Windows emulates quite realistically the EK-LM3S811 board. Specifically the 96x16 OLED display is pixel-exact (it is actually magnified 2:1 on Windows to see the small display better). You also have a realistic USER push button as well as the USER LED, which lights up as long as the USER push button is depressed.
|
|
|
|
\note The The QP/C Baseline Code provides the <b>complete C source code</b> for all the needed graphical components, such as color graphic displays, segment displays, LEDs, user-defined push-buttons, etc. This toolkit enables you to build realistic prototypes (<b>rapid prototyping</b>) of your embedded devices and develop most of the C code on Windows, which is much more productive than on real hardware. Please visit <a href="http://www.state-machine.com/win32">state-machine.com/win32</a> for more information.
|
|
|
|
|
|
\section S22 Game Description
|
|
The first screen you see is the Quantum Leaps <b>logo screen</b> with the <a href="http://www.state-machine.com">state-machine.com</a> website address.
|
|
|
|
After 5 seconds, the game switches to the <b>demo mode</b> with the text "Push Button" text flashing in the middle of the display. At the top of the display you see a legend of keystrokes recognized by the application. You need to press the USER button with your mouse or hit the SPACE key to start playing the game (<b>playing mode</b>).
|
|
|
|
Your objective in the game is to navigate a space ship through an endless horizontal tunnel with mines. Any collision with the tunnel or the mine destroys the ship. You can move the ship up and down with turning the mouse wheel up and down, or by pressing the UP-arrow and DOWN-arrow keys on your keyboard. (On the real EK-LM3S811 board you use the potentiometer wheel for this.) You can also fire a missile to destroy the mines in the tunnel by pressing the USER push-button or the SPACE-bar on your keyboard.
|
|
|
|
Score accumulates for survival (at the rate of 30 points per second) and destroying the mines and the game lasts for only one ship. You can also have only one missile in flight at a time, so trying to fire a missile while it is already flying has no effect. Hitting the tunnel wall with the missile brings you no points.
|
|
|
|
The game has two types of mines with different behavior. In the original Luminary "Quickstart" application both types of mines behave the same, but the QP version demonstrates how state machines can elegantly handle differently behaving mines.
|
|
|
|
Mine type-1 is small, but can be destroyed by hitting any of its pixels with the missile. You earn 25 points for destroying a mine type- Mine type-2 is bigger, but is nastier in that the missile can destroy it only by hitting its center, not any of the "tentacles". Of course, the ship is vulnerable to the whole mine. You earn 45 points for destroying a mine type 2.
|
|
|
|
When your crash the ship, either by hitting a wall or a mine, the game ends and displays the flashing "Game Over" text as well as your final score (<b>game over</b> mode). After 5 seconds of flashing, the "Game Over" screen changes back to the <b>demo mode</b>, where the game waits to be started again.
|
|
|
|
Additionally the application contains a <b>screen saver</b> because the OLED display of the original EK-LM3S811 board has burn-in characteristics similar to a CRT. The screen saver only becomes active if 20 seconds elapse in the demo mode without starting the game (i.e., the screen saver never appears during game play). The screen saver is a simple random-pixel-type, rather than the "Game of Life" algorithm used in the original Luminary "Quickstart" application.
|
|
|
|
After a minute of running the screen saver, the display turns blank and only the "Push Button" text flashes from time to time at random positions on the screen.
|
|
|
|
\section S23 Running the Game on the EK-LM3S811 Board
|
|
The "Fly 'n' Shoot" application code for the EK-LM3S811 kit with the IAR toolset is located in `<qp>\qpc\examples\arm-cm\vanilla\iar\game_ek-lm3s811\`, where `<qp>` denotes the destination folder you chose to extract QP/C into. The following screen shot shows the relevant fragment of the QP/C directory tree in the Windows Explorer:
|
|
|
|
|
|
|
|
If you purchased the EK-LM3S811 kit from Quantum Leaps (see <a href="http://www.state-machine.com/qp_box ">"QP/QM Training in a Box"</a>), the "Fly 'n' Shoot" example is pre-programmed into the board and you can play the game as soon as you connect the board to a USB port. However, if you have the original board from Texas Instruments, you need to program the game image into the board yourself, which you can do through the free KickStart edition of the IAR EWARM toolset, as described below.
|
|
|
|
\anchor F2s4
|
|
|
|
|
|
To download the IAR EWARM toolset, visit <a href="http://www.iar.com/en/Service-Center/Downloads/">IAR Download Center</a> and click on the latest version of the ARM toolset. For the free KickStart version, choose the "Size-limited license", and follow the download and installation instructions.
|
|
|
|
\note It is strongly recommended to install the IAR EWARM toolset into the directory without embedded spaces or parentheses, e.g., `C:\tools\iar\arm_6.60`. Avoiding special characters in the path names simplifies Makefiles and build scripts.
|
|
|
|
To program the "Fly 'n' Shoot" game to the flash memory of the EK-LM3S811 board, you first connect the board to your PC with the USB cable provided in the kit and make sure that the Power LED is on (see \ref F2s4 "Figure 2-2"). Next, you need to launch the IAR Embedded Workbench and open the workspace <b>game.eww</b> located in `<qp>\examples\arm-cm\vanilla\iar\game_ek-lm3s811\` directory.
|
|
|
|
\anchor F2s5
|
|
|
|
|
|
\note The IAR Embedded Workbench environment allows you to experiment with the "Fly 'n' Shoot" code. However, if you want to edit the code, you need to <b>un-check the "read-only" property</b> of the `.c` files. This is because these files have been generated automatically as read-only by the <a href="http://www.state-machine.com/qm "><b>free QM™ graphical modeling tool</b></a>.
|
|
|
|
Previous Step: \ref tutorial1 \n
|
|
Next Step: \ref tutorial3
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
/**
|
|
\page tutorial3 Step 3: Compiling the Example Code
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps, LLC.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial2 \n
|
|
Next Step: \ref tutorial4
|
|
|
|
This step describes how to compile the "Fly 'n' Shoot" application code on your machine.
|
|
|
|
\section S31 Compiling the Code on Windows with MinGW
|
|
|
|
The source code for the "Fly 'n' Shoot" for Windows with the MinGW GNU C/C++ compiler is located in the directory `<qp>\qpc\examples\win32\mingw\game-gui\`, where `<qp>` denotes the destination folder you chose to extract QP/C into. The following screen shot shows the game source code in the Windows Explorer:
|
|
|
|
|
|
|
|
If you have installed the <b>Qtools collection</b>, as described in \ref tutorial1, the GNU make utility and MinGW C/C++ toolset will be available, so you can easily re-compile the code from a Windows Command Prompt. Simply open the Command Prompt, change directory to `<qp>\qpc\examples\win32\mingw\game-gui\` and type <b>make</b>.
|
|
|
|
\note The `Makefile` for the project assumes that the environment variables <b>QPC</b> and <b>QTOOLS</b> are set up correctly and that the directory <b>%%QTOOLS%\\bin</b> has been added to the <b>PATH</b>, as described in section \ref tutorial1. The build will <b>fail</b> if the environment variables are not defined or defined incorrectly.
|
|
|
|
\note Also, building any QP/C application requires the <b>QP/C library</b> to be present in the port directory `<qp>\qpc\ports\win32\mingw\dbg` directory. This library is pre-compiled and provided in the QP/C Baseline Code. The upcoming section \ref tutorial4 explains how you can re-build the QP library yourself.
|
|
|
|
|
|
|
|
|
|
The command `make` without parameters builds the default <b>debug configuration</b>. You can also build the <b>release configuration</b> and the <b>spy configuration</b> by providing parameters to the `make` command, as summarized in the following table:
|
|
|
|
<CENTER>
|
|
Build Configuration | Command | Build sub-directory
|
|
------------------------------|------------------|---------------------
|
|
<b>Debug</b> (default) | `make` | `dbg\`
|
|
<b>Clean</b> the Debug build | `make clean` | `dbg\`
|
|
<b>Release</b> | `make CONF=rel` | `rel\`
|
|
<b>Clean</b> the Release build| `make CONF=rel clean` | `rel\`
|
|
<b>Spy</b> | `make CONF=spy` | `spy\`
|
|
<b>Clean</b> the Spy build | `make CONF=spy clean` | `spy\`
|
|
</CENTER>
|
|
|
|
\note The supported build configurations are as follows:
|
|
|
|
\note <b>Debug</b> - this configuration is built with full debugging information and minimal optimization. On an embedded CPU, when the QP framework finds no events to process, the framework busy-idles until there are new events to process.
|
|
|
|
\note <b>Release</b> - this configuration is built with no debugging information and high optimization. Single-stepping and debugging is effectively impossible due to the lack of symbolic information and optimized code, but the debugger can be used to download and start the executable. On an embedded CPU, when the QP framework finds no events to process, the framework puts the CPU to sleep until there are new events to process.
|
|
|
|
\note <b>Spy</b> - like the debug variant, this variant is built with full debugging information and minimal optimization. Additionally, it is build with the QP's <b>Q-SPY software tracing functionality</b> enabled. Typically an on-board serial port and the Q-Spy host application are used for sending and viewing trace data. Like the Debug configuration, on an embedded CPU the QP framework outputs the trace data to the host and/or busy-idles until there are new events to process.
|
|
|
|
\section S32 Compiling and Debugging the Code with Visual C++
|
|
|
|
The MinGW compiler allows you to re-build the code quickly from a Command Prompt, but it does not provide a convenient way of <b>debugging</b> your code on Windows.
|
|
|
|
In contrast, Microsoft Visual Studio provides an excellent debugger and a modern IDE for developing your code. To take advantage of these capabilities, the QP/C Baseline distribution includes the QP libraries and examples for the <b>free Visual C++ Express</b> edition. Specifically, the "Fly 'n' Shoot" example with Visual C++ is located in the directory `<qp>\qpc\examples\win32\vc\game-gui\`. The following screen shot shows the `game-gui.sln` solution opened in the Visual C++ 2012:
|
|
|
|
|
|
|
|
\note For more information on developing embedded code on Windows and the <b>dual targeting</b> technique, visit <a href="http://www.state-machine.com/win32 ">state-machine.com/win32</a>.
|
|
|
|
|
|
\section S33 Compiling the Code with IAR EWARM
|
|
|
|
The source code and complete IAR EWARM workspace <b>game.eww</b> for the "Fly 'n' Shoot" is located in the directory `<qp>\qpc\qpc\examples\arm-cm\vanilla\iar\game_ek-lm3s811\`, where `<qp>` denotes the destination folder you chose to extract QP/C into. The following screen shot shows the game source code in the Windows Explorer:
|
|
|
|
|
|
|
|
The IAR project supports the three build configurations: Debug, Release, and Spy. You select the build configuration through the drop-down list at the top of the Workspace panel in the upper-left corner of the screen shown above.
|
|
|
|
\note The IAR project file `game.ewp` for the project assumes that the environment variable <b>QPC</b> is set up correctly, as described in section \ref tutorial1. The build will <b>fail</b> if the environment variable is not defined or defined incorrectly.
|
|
|
|
\note Also, building any QP/C application requires the <b>QP/C library</b> to be present in the port directory `<qp>\qpc\ports\arm-cm\vanilla\iar\dbg` directory. This library is pre-compiled and provided in the QP/C Baseline Code. The upcoming section \ref tutorial4 explains how you can re-build the QP library yourself.
|
|
|
|
|
|
\section S34 Compiling the Code with Other Embedded Toolsets
|
|
|
|
For simplicity, this tutorial focuses only the IAR EWARM toolset. But in fact, the QP/C Baseline Code contains also versions of the "Fly 'n' Shoot" game for other embedded toolsets, such as <b>ARM/Keil MDK</b> with uVision4 IDE, and the <b>Sourcery CodeBench</b> GNU-based toolset and Eclipse-based IDE. Please explore the `<qp>\qpc\examples\arm-cm\` directory to find these examples. You can also visit the <a href="http://www.state-machine.com/downloads/index.php#QDK"><b>downloads section of the state-machine.com webiste</b></a> to find examples for other embedded processors and compilers.
|
|
|
|
Previous Step: \ref tutorial2 \n
|
|
Next Step: \ref tutorial4
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
/**
|
|
\page tutorial4 Step 4: Building the QP/C Libraries
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps, LLC.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial3 \n
|
|
Next Step: \ref tutorial5
|
|
|
|
While the QP/C Baseline Code provides many pre-compiled QP/C libraries, it is <b>highly recommended</b> that you re-build the QP libraries yourself on your machine. By doing this, you will avoid any potential mismatch between the compiler version used to build the QP library originally at Quantum Leaps and the one actually installed on your machine. Also, you need to re-build the QP library if you port QP to a different compiler or you need to change the QP configuration macros in any of the port header files `*_port.h`.
|
|
|
|
The QP libraries depend on the processor type, real-time kernel or operating system type and the compiler used. The libraries are located in the `<qp>\qpc\ports\` directory sub-tree, where `<qp>` denotes the destination folder you chose to extract QP/C into.
|
|
|
|
\note The QP/C framework is deployed as a set of fine-granularity static <b>libraries</b> that you link with your application code. This way, the heavy lifting of eliminating any unused QP code is performed automatically at link-time, because the linker pulls the modules from libraries only as long it needs to satisfy any outstanding references. This means that if your application does not use a certain QP feature, the linker won't pull the corresponding code for it from the library. This is in contrast to including QP/C source code directly in your application, because in this case the linker would take all the code.
|
|
|
|
|
|
\section S41 Building the QP/C Libraries on Windows with MinGW
|
|
|
|
The QP libraries for Windows with the MinGW GNU C/C++ compiler are located in the directory `<qp>\qpc\ports\win32\mingw\`. To build the QP library, simply open the Command Prompt, change directory to `<qp>\qpc\ports\win32\mingw\` and type <b>make</b>. The following screen shot shows the output from the QP/C library build:
|
|
|
|
|
|
|
|
The command `make` without parameters builds the default <b>debug configuration</b> of the QP/C library. You can also build the <b>release configuration</b> and the <b>spy configuration</b> by providing parameters to the `make` command, as summarized in the following table:
|
|
|
|
<CENTER>
|
|
Build Configuration | Command | Build sub-directory
|
|
------------------------------|------------------|---------------------
|
|
<b>Debug</b> (default) | `make` | `dbg\`
|
|
<b>Release</b> | `make CONF=rel` | `rel\`
|
|
<b>Spy</b> | `make CONF=spy` | `spy\`
|
|
</CENTER>
|
|
|
|
\note The supported build configurations are as follows:
|
|
|
|
\note <b>Debug</b> - this configuration is built with full debugging information and minimal optimization. On an embedded CPU, when the QP framework finds no events to process, the framework busy-idles until there are new events to process.
|
|
|
|
\note <b>Release</b> - this configuration is built with no debugging information and high optimization. Single-stepping and debugging is effectively impossible due to the lack of symbolic information and optimized code, but the debugger can be used to download and start the executable. On an embedded CPU, when the QP framework finds no events to process, the framework puts the CPU to sleep until there are new events to process.
|
|
|
|
\note <b>Spy</b> - like the debug variant, this variant is built with full debugging information and minimal optimization. Additionally, it is build with the QP's <b>Q-SPY software tracing functionality</b> enabled. Typically an on-board serial port and the Q-Spy host application are used for sending and viewing trace data. Like the Debug configuration, on an embedded CPU the QP framework outputs the trace data to the host and/or busy-idles until there are new events to process.
|
|
|
|
|
|
\section S42 Building the QP/C Libraries with Visual C++
|
|
|
|
\note The QP/C library build for Microsoft Visual C++ turned out to be difficult to automate in a script, which is the preferred way by Quantum Lepas. Instead, re-compiling the library requires launching the Visual Studio IDE and a manual build from there.
|
|
|
|
To build the QP/C libraries for Visual C++, launch the Microsoft Visual Studio IDE and open the solution <b>qp.sln</b> located in `<qp>\qpc\ports\win32\vc\`. The following screen shot shows the `qp.sln` solution opened in the Visual C++ 2012. Please note that you can select the <b>build configuration</b> from the drop-down combo-box at the top of the screen.
|
|
|
|
|
|
|
|
|
|
\section S43 Building the QP/C Libraries for IAR EWARM
|
|
|
|
The QP libraries for ARM Cortex-M with Vanilla cooperative kernel and the IAR EWARM compiler are located in the directory `<qp>\qpc\ports\arm-cm\vanilla\iar\`. To build the QP library for Cortex-M3, open the Command Prompt, change directory to `<qp>\qpc\ports\arm-cm\vanilla\iar\` and type <b>make_cortex-m3.bat</b>. The following screen shot shows the output from the QP/C library build:
|
|
|
|
|
|
|
|
The command `make_cortex-m3.bat` without parameters builds the default <b>debug configuration</b> of the QP/C library. You can also build the <b>release configuration</b> and the <b>spy configuration</b> by providing parameters to the `make` command, as summarized in the following table:
|
|
|
|
<CENTER>
|
|
Build Configuration | Command | Build sub-directory
|
|
----------------------------------|---------------------|---------------------
|
|
<b>Debug</b> build for Cortex-M3 | `make_cortex-m3` | `dbg\`
|
|
<b>Release</b> build for Cortex-M3| `make_cortex-m3 rel`| `rel\`
|
|
<b>Spy</b> build for Cortex-M3 | `make_cortex-m3 spy`| `spy\`
|
|
<b>Debug</b> build for Cortex-M4F | `make_cortex-m4f` | `dbg\`
|
|
<b>Release</b> build for Cortex-M4F| `make_cortex-m4f rel`| `rel\`
|
|
<b>Spy</b> build for Cortex-M4F | `make_cortex-m4f spy`| `spy\`
|
|
</CENTER>
|
|
|
|
Previous Step: \ref tutorial3 \n
|
|
Next Step: \ref tutorial5
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
|
|
/**
|
|
\page tutorial5 Step 5: QS Software Tracing for Testing and Debugging
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps, LLC.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial4 \n
|
|
Next Step: \ref tutorial6
|
|
|
|
|
|
Software tracing is a method for obtaining diagnostic information in a <b>live</b> environment without the need to stop the application, which would be required by a traditional single-step debugger. In a nutshell, software tracing is similar to peppering the code with `printf()` statements for logging and debugging, except that mature software tracing techniques are much more efficient, less intrusive, and more selective than the primitive `printf()`.
|
|
|
|
The QP/C™ framework contains the sophisticated software tracing system called <b>QS</b> (Quantum Spy). The QS trace data can be thorough enough to produce complete sequence diagrams and detailed state machine activity for all state machines in the system. You can selectively monitor all event exchanges, event queues, event pools, and time events because all these elements are controlled by the framework. Additionally, if you use one of the kernels built into QP (the Vanilla kernel or the preemptive QK kernel), you can obtain all the data available to a traditional RTOS as well, such as context switches and mutex activity
|
|
|
|
\anchor F5s1
|
|
|
|
|
|
All versions of "Fly 'n' Shoot" applications included in the QP/C Baseline Code are instrumented for software tracing. In the Debug and Release build configurations this tracing instrumentation is inactive, meaning that it is skipped by the compiler. However, in the <b>Spy configuration</b>, the instrumentation becomes active and generates software tracing data in a circular buffer, which is then transmitted to the host for visualization and storage.
|
|
|
|
|
|
\section S51 QS Software Tracing on Windows with Visual C++
|
|
|
|
In the "Fly 'n' Shoot" example for Windows with Visual C++ (see `<qp>\qpc\examples\win32\vc\game-gui\`), the QS tracing data is directly output to the Visual Studio debug console, as shown in the following screen shot:
|
|
|
|
\note To see the QS output, you need to switch to the <b>Spy</b> build configuration in the drop-down combo-box.
|
|
|
|
\anchor F5s2
|
|
|
|
|
|
\note To understand the output from the QSPY host application, please refer to the <a href="http://www.state-machine.com/doxygen/qspy/"><b>QSPY Reference Manual</b></a>.
|
|
|
|
\note The Spy build configuration on Windows includes the file `qspy.c`, which really belongs by the QSPY host application. To be able to find this file, the environment variable <b>QTOOLS</b> must be defined, as described in \ref tutorial1.
|
|
|
|
|
|
\section S52 QS Software Tracing on the EK-LM3S811 Board
|
|
|
|
To experience the QS software tracing from the real hardware, such as the EK-LM3S811 board, you must switch to the Spy build configuration in the IAR EWARM. You do this through the drop-down box in the "workspace" panel. Once you switch to the Spy configuration, you build and upload the code to the EK-LM3S811 board in the usual way (see \ref tutorial2).
|
|
|
|
You also you need to start the QSPY host application on your host machine that decompresses and visualizes the QS trace data. The Windows executable of the QSPY host application located in the directory `%%QTOOLS%\bin` directory, which should be on your PATH. The following screen shot shows the SPY host application running in a Windows console and collecting trace data from the EK-LM3S811 board:
|
|
|
|
|
|
|
|
|
|
|
|
As you can see in the screen shot above, you need to specify the COM port to the QSPY host application with the argument -cCOM2, which is the virtual COM port of the Stellaris board.
|
|
|
|
\note You need to <b>adjust the COM port</b> to the actual number to which this virtual port enumerates on your machine. The following screen shot shows how to find this number out in the Windows Device Manager:
|
|
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial4 \n
|
|
Next Step: \ref tutorial6
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All
|
|
Rights Reserved.\n http://www.state-machine.com */
|
|
|
|
|
|
|
|
/** \page tutorial6 Step 6: QM Graphical Modeling Tool
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps, LLC.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial5 \n
|
|
Next Step: \ref tutorial7
|
|
|
|
|
|
While the QP/C framework has been designed for manual coding of hierarchical state machines in C, the framework makes also an excellent target for automatic code generation, which is provided by the <a href="http://www.state-machine.com/qm "><b>modeling tool called QM™</b></a> (QP Modeler). QM™ is a <b>free</b>, cross-platform, graphical UML modeling tool for designing and implementing real-time embedded applications based on the QP active object 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.
|
|
|
|
|
|
\section S61 Downloading and Installing QM™
|
|
|
|
The <B>QM installer</B> is available for download from <A HREF="http://sourceforge.net/projects/qpc/files/QM/"><B>SourceForge.net</B></A>. On SourceForge choose the latest QM version folder and click on the installer for your operating system (this tutorial assumes Windows). The following screen shot shows the Windows QM installer, where you choose the destination folder for QM.
|
|
|
|
|
|
|
|
\note If you already have QM installed, it is highly recommended to uninstall it before installing a different version.
|
|
|
|
\section S62 Working with a Model
|
|
|
|
All versions of the "Fly 'n' Shoot" game contain the <b>game.qm</b> model file. To open this model, double-click on it in the Windows Explorer. Alternatively, you can launch the QM tool first and open the model through the <b>File|Open</b> menu. The following screen shot shows the <b>game.qm</b> model opened in the QM tool:
|
|
|
|
\note All versions of the game use actually a copy of the <b>same</b> model.
|
|
|
|
|
|
|
|
\note To learn more about the design of the "Fly 'n' Shoot" game, please refer to the the book \ref PSiCC2.
|
|
|
|
Previous Step: \ref tutorial5 \n
|
|
Next Step: \ref tutorial7
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All
|
|
Rights Reserved.\n http://www.state-machine.com */
|
|
|
|
|
|
|
|
/** \page tutorial7 Step 7: Creating Your Own QP/C Projects
|
|
|
|
<I>This QP/C Tutorial is adapted from Chapter 1 of \ref PSiCC2\n
|
|
by Miro Samek, founder and president of Quantum Leaps, LLC.</I>
|
|
|
|
|
|
|
|
Previous Step: \ref tutorial6
|
|
|
|
Perhaps the most important fact of life to remember is that in embedded systems nothing works until everything works. This means that you should always start with a <b>working</b> system and gradually evolve it, changing one thing at a time and making sure that it keeps working every step of the way.
|
|
|
|
Keeping this in mind, the provided QP/C application examples, such as the "Fly 'n' Shoot" game but also many others, allow you to get started with a working project rather than starting from scratch. You should also always try one of the provided example projects on the same evaluation board that it was designed for, before making any changes.
|
|
|
|
Only after convincing yourself that the example project works "as is", you can think about creating your own project. At this point, the easiest and recommended way is to copy the <b>existing working example</b> project folder (such as the "Fly 'n' Shoot" game) and rename it.
|
|
|
|
After copying the project folder, you still need to change the name of the project/workspace. The easiest and safest way to do this is to open the project/workspace in the corresponding IDE and use the <b>Save As...</b> option to save the project under a different name. You can do this also with the QM model file, which you can open in QM and "Save As" a different model.
|
|
|
|
\note By copying and re-naming an existing, working project, as opposed to creating a new one from scratch, you inherit the correct compiler and linker options an other project settings, which will help you get started much faster.
|
|
|
|
\section S71 Next Steps and Further Reading
|
|
|
|
This tutorial is intended to get the QP/C installed and running on your system as quickly as possible, but to work with QP/C effectively, you need to learn how to work with active objects and state machines. Below is a list of links to enable you to further your knowledge:
|
|
|
|
- <a href="http://sourceforge.net/p/qpc/discussion/668726 ">Free Support Forum for QP/QM</a>
|
|
- <a href="http://www.state-machine.com/psicc2">Companion page for the "Practical UML Statecharts in C/C++, Second Edition" book</a>
|
|
- <a href="http://www.state-machine.com/downloads">Code downloads summary</a>
|
|
- <a href="http://www.state-machine.com/resources/appnotes.php">QP Application Notes</a>
|
|
- <a href="http://www.state-machine.com/resources/articles.php">QP Articles</a>
|
|
- <a href="http://embeddedgurus.com/state-space">"State Space" Blog</a>
|
|
|
|
|
|
Previous Step: \ref tutorial6
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|
|
|
|
/**
|
|
\page derivation Encapsulation and Single Inheritance in C
|
|
|
|
Inheritance is the ability to derive new structures based on existing
|
|
structures in order to reuse and organize code. You can implement single
|
|
inheritance in C very simply by literally embedding the base structure as the
|
|
first member of the derived structure. For example, \ref FA1 "Figure 1"(a)
|
|
shows the structure ScoreEvt derived from the base structure QEvt by
|
|
embedding the QEvt instance as the first member of ScoreEvt. To make this
|
|
idiom better stand out, I always name the base structure member super.
|
|
|
|
\anchor FA1 \image html FA1.jpg "Figure 1 (a) Derivation of structures in C, (b) memory alignment, and (c) the UML class diagram."
|
|
|
|
As shown in \ref FA1 "Figure 1"(b), such nesting of structures always aligns
|
|
the data member super at the beginning of every instance of the derived
|
|
structure. In particular, this alignment lets you treat a pointer to the
|
|
derived ScoreEvt structure as a pointer to the QEvt base structure.
|
|
Consequently, you can always safely pass a pointer to ScoreEvt to any C
|
|
function that expects a pointer to QEvt. (To be strictly correct in C, you
|
|
should explicitly cast this pointer. In OOP such casting is called upcasting
|
|
and is always safe.) Therefore, all functions designed for the QEvt
|
|
structure are automatically available to the ScoreEvt structure as well as
|
|
other structures derived from QEvt. \ref FA1 "Figure 1"(c) shows the UML
|
|
class diagram depicting the inheritance relationship between ScoreEvt and
|
|
QEvt structures.
|
|
|
|
QP uses single inheritance quite extensively not just for derivation of events
|
|
with parameters, but also for derivation of state machines and active objects.
|
|
Of course, the C++ version of QP uses the native C++ support for class
|
|
inheritance rather than "derivation of structures".
|
|
|
|
|
|
Copyright © 2002-2013 Quantum Leaps, LLC. All Rights Reserved.\n
|
|
http://www.state-machine.com */
|