3. The main() Function and the qpn_port.h Header File

This QP-nano Tutorial is adapted from Chapter 1 of Practical UML Statecharts in C/C++, Second Edition
by Miro Samek, the founder and president of Quantum Leaps, LLC.

Prev: 2. Let's Play
Next: 4. Designing an Event-Driven Application

Perhaps the best place to start the explanation of the "Fly 'n' Shoot" application code is the main() function, located in the file main.c. Unless indicated otherwise in this Tutorial, you can browse the code either in the DOS version, or the Cortex-M3 version, because the application source code is identical in both.

3. The main() Function and the qpn_port.h Header File

Listing 3-1 shows the main.c source file for the “Fly ‘n’ Shoot” application, which contains the main() function along with some important data structures required by QP-nano.

Note:

To explain code listings, I place numbers in parentheses at the interesting lines in the left margin of the listing. I then use these labels in the left margin of the explanation section that immediately follows the listing. Occasionally, to unambiguously refer to a line of a particular listing from sections of text other than the explanation section, I use the full reference consisting of the listing number followed by the label. For example, Listing 3-1(21) refers to the label (21) in Listing 3-1

Listing 3-1 The file main.c of the "Fly 'n' Shoot" game application.

 (1) #include "qpn_port.h"                                       /* QP-nano port */
 (2) #include "bsp.h"                             /* Board Support Package (BSP) */
 (3) #include "game.h"                                  /* application interface */

     /*..........................................................................*/
 (4) static QEvent l_tunnelQueue[GAME_MINES_MAX + 4];
 (5) static QEvent l_shipQueue[2];
 (6) static QEvent l_missileQueue[2];

     /* QF_active[] array defines all active object control blocks --------------*/
 (7) QActiveCB const Q_ROM Q_ROM_VAR QF_active[] = {
 (8)     { (QActive *)0,           (QEvent *)0,    0                     },
 (9)     { (QActive *)&AO_tunnel,  l_tunnelQueue,  Q_DIM(l_tunnelQueue)  },
(10)     { (QActive *)&AO_ship,    l_shipQueue,    Q_DIM(l_shipQueue)    },
(11)     { (QActive *)&AO_missile, l_missileQueue, Q_DIM(l_missileQueue) }
     };

     /* make sure that the QF_active[] array matches QF_MAX_ACTIVE in qpn_port.h */
(12) Q_ASSERT_COMPILE(QF_MAX_ACTIVE == Q_DIM(QF_active) - 1);

     /*..........................................................................*/
     void main (void) {
(13)     Tunnel_ctor ();
(14)     Ship_ctor   ();
(15)     Missile_ctor(GAME_MISSILE_SPEED_X);

(16)     BSP_init();                                     /* initialize the board */

(17)     QF_run();                                /* transfer control to QF-nano */
     }

• (1) Every application C-file that uses QP-nano must include the qpn_port.h header file. This header file contains the specific adaptation of QP-nano to the given processor and compiler, which is called a port. The QP port is typically located in the application directory.

• (2) The bsp.h header file contains the interface to the Board Support Package and is located in the application directory.

• (3) The game.h header file contains the declarations of events and other facilities shared among the components of the "Fly 'n' Shoot" game. This header file is located in the application directory.

• (4-6) The application must provide storage for the event queues of all active objects used in the application. In QP-nano the storage is provided at compile time through the statically allocated arrays of events. Events are represented as instances of the QEvent structure declared in the <qpn>\include\qepn.h header file, included from qpn_port.h. Each event queue of an active object can have a different length and you need to decide this length based on your knowledge of the application. Please refer to Chapters 6 and 7 in Practical UML Statecharts in C/C++, Second Edition for the discussion of sizing event queues.

• (7) Every QP-nano application must provide the constant array QF_active[], which defines all active object control blocks in the application. The control block QActiveCB structure groups together: (1) the pointer to the corresponding active object instance, (2) the pointer to the event queue buffer of the active object, and (3) the length of the queue buffer.

In QP-nano, I use every opportunity to place data in ROM rather than in the precious RAM. The QActiveCB structure contains data elements known at compile time, so that these elements can be placed in ROMas opposed to placing them in the active object structure (RAM). That way, I save anywhere from 10 to 80 bytes of RAM, depending on the number of active objects and the pointer size of the target CPU. The Q_ROM macro is necessary on some CPU architecture to enforce placement of constant objects, such as the QF_active[] array, in ROM. On Harvard architecture CPUs (such as 8051 or AVR), the code and data spaces are separate and are accessed through different CPU instructions. The const keyword is not sufficient to place data in ROM, and various compilers often provide specific extended keywords to designate the code space for placing constant data, such as the "__code" extended keyword in the IAR 8051 compiler. The macro Q_ROM hides such non-standard extensions. If you don't define Q_ROM in qepn_port.h, it will be defined to nothing in the qepn.h platform-independent header file. The Q_ROM_VAR macro defines the compiler-specific directive for accessing a constant object in ROM. Many compilers for 8-bit MCUs provide different size pointers for accessing objects in various memories. Constant objects allocated in ROM often mandate the use of specific-size pointers (e.g., far pointers) to get access to ROM objects. The macro Q_ROM_VAR specifies the kind of the pointer to be used to access the ROM objects. An example of valid Q_ROM_VAR macro definition is: __far (Freescale HC(S)08 compiler).

• (8) The first entry (QF_active[0]) corresponds to active object priority of zero, which is reserved for the idle task and cannot be used for any active object.

• (9-11) The QF_active[] entries starting from one define the active object control blocks in the order of their relative priorities. The maximum number of active objects in QP-nano cannot exceed 8.

Note:

The order or the active object control blocks in the QF_active[] array defines the priorities of active objects. This is the only place in the code where you assign active object priorities.

• (12) This compile-time assertion (see Chapter 6 in Practical UML Statecharts in C/C++, Second Edition) ensures that the dimension of the QF_active[] array matches the number of active objects QF_MAX_ACTIVE defined in the qpn_port.h header file.

In QP-nano, QF_MAX_ACTIVE denotes the exact number of active objects used in the application, as opposed to the full-version QP, where QF_MAX_ACTIVE denotes just the configurable maximum number of active objects.

Note:

All active objects in QP-nano must be defined at compile time. This means that all active objects exist from the beginning and cannot be started (or stopped) later, as it is possible in the full-version QP.

The macro QF_MAX_ACTIVE must be defined in qpn_port.h header file, because QP-nano uses the macro to optimize the internal algorithms based on the number of active objects. The compile-time assertion in line (12) makes sure that the configured number of active objects indeed matches exactly the number of active object control blocks defined in the QF_active[] array.

• (13-15) The main() function must first explicitly calls all active object constructors.

• (16) The board support package (BSP) is initialized.

• (17) At this point, you have initialized all components and have provided to the QF-nano framework all the information it needs to manage your application. The last thing you must do is to call the function QF_run() to pass the control to the QF-nano framework.

Overall, the application startup is much simpler in QP-nano than in full-version QP. Neither event pools, nor publish-subscribe lists are supported, so you don't need to initialize them. You also don't start active objects explicitly. The QF-nano framework starts all active objects defined in the QF_active[] array automatically just after it gets control in QF_run().

The qpn_port.h header file

The qpn_port.h header file defines the QP-nano port and all configuration parameters for the particular application. Unlike in the full-version QP, QP-nano ports are typically defined at the application level. Typically also, the whole QP-nano port consists of just the qpn_port.h header file. Listing 3-2 shows the complete qpn_port.h file for the DOS version of the “Fly ‘n’ Shoot” game.

Listing 3-2 The qpn_port.h header file for the “Fly ‘n’ Shoot” game.

     #ifndef qpn_port_h
     #define qpn_port_h

 (1) #define Q_PARAM_SIZE            4
 (2) #define QF_TIMEEVT_CTR_SIZE     2
 (3) #define Q_NFSM

     /* maximum # active objects--must match EXACTLY the QF_active[] definition  */
 (4) #define QF_MAX_ACTIVE           3

                                      /* interrupt locking policy for task level */
 (5) #define QF_INT_LOCK()           disable()
 (6) #define QF_INT_UNLOCK()         enable()

     /* Exact-width types (WG14/N843 C99 Standard) for Turbo C++/large model     */
 (7) typedef signed   char  int8_t;
     typedef signed   int   int16_t;
     typedef signed   long  int32_t;
     typedef unsigned char  uint8_t;
     typedef unsigned int   uint16_t;
     typedef unsigned long  uint32_t;

     #include <dos.h>                                                 /* DOS API */
     #undef outportb /*don't use the macro because it has a bug in Turbo C++ 1.01*/

 (8) #include "qepn.h"              /* QEP-nano platform-independent header file */
 (9) #include "qfn.h"                /* QF-nano platform-independent header file */

     #endif                                                        /* qpn_port_h */

• (1) The macro Q_PARAM_SIZE defines the size (in bytes) of the scalar event parameter. The allowed values are 0 (no parameter), 1, 2, or 4 bytes. If you don't define this macro in qpn_port.h, the default of 0 (no parameter) will be assumed.

• (2) The macro QF_TIMEEVT_CTR_SIZE defines the size (in bytes) of the time event down-counter. The allowed values are 0 (no time events), 1, 2, or 4 bytes. If you don't define this macro in qpn_port.h, the default of 0 (no time events) will be assumed.

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

• (4) You must define the QF_MAX_ACTIVE macro as the exact number of active objects used in the application. The provided value must be between 1 and 8 and must be consistent with the definition of the QF_active[] array (see Listing 3-1(12)).

• (5-6) The macros QF_INT_LOCK()/QF_INT_UNLOCK() define the task-level interrupt locking policy for QP-nano. I discuss QP-nano critical section in Chapter 12 of Practical UML Statecharts in C/C++, Second Edition.

• (7) Just like the full-version QP, QP-nano uses a subset of the C99-standard exact-with integer types. The legacy Turbo C++ 1.01 compiler, which I'm using here, is a pre-standard compiler and does not provide the <stdint.h> header file. In this case I just typedef the six exact-width integer types used in QP-nano.

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

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

Note:

The qpn_port.h header file in Listing 3-2 implicitly configures QP-nano to use the built-in cooperative "vanilla" kernel. The other alternative, which is the preemptive QK-nano kernel, is configured automatically when you include the qkn.h QK-nano interface in the qpn_port.h header file.

Prev: 2. Let's Play
Next: 4. Designing an Event-Driven Application

Copyright © 2002-2008 Quantum Leaps, LLC. All Rights Reserved.
http://www.quantum-leaps.com

---