qevent.h

00001 //////////////////////////////////////////////////////////////////////////////
00002 // Product: QEP/C++ platform-independent public interface
00003 // Last Updated for Version: 4.1.04
00004 // Date of the Last Update:  Mar 15, 2010
00005 //
00006 //                    Q u a n t u m     L e a P s
00007 //                    ---------------------------
00008 //                    innovating embedded systems
00009 //
00010 // Copyright (C) 2002-2010 Quantum Leaps, LLC. All rights reserved.
00011 //
00012 // This software may be distributed and modified under the terms of the GNU
00013 // General Public License version 2 (GPL) as published by the Free Software
00014 // Foundation and appearing in the file GPL.TXT included in the packaging of
00015 // this file. Please note that GPL Section 2[b] requires that all works based
00016 // on this software must also be made publicly available under the terms of
00017 // the GPL ("Copyleft").
00018 //
00019 // Alternatively, this software may be distributed and modified under the
00020 // terms of Quantum Leaps commercial licenses, which expressly supersede
00021 // the GPL and are specifically designed for licensees interested in
00022 // retaining the proprietary status of their code.
00023 //
00024 // Contact information:
00025 // Quantum Leaps Web site:  http://www.quantum-leaps.com
00026 // e-mail:                  info@quantum-leaps.com
00027 //////////////////////////////////////////////////////////////////////////////
00028 #ifndef qevent_h
00029 #define qevent_h
00030 
00031 /// \file
00032 /// \ingroup qep qf qk
00033 /// \brief QEvent class and basic macros used by all QP components.
00034 ///
00035 /// This header file must be included, perhaps indirectly, in all modules
00036 /// (*.cpp files) that use any component of QP/C++ (such as QEP, QF, or QK).
00037 
00038 //////////////////////////////////////////////////////////////////////////////
00039 /// \brief The current QP version number
00040 ///
00041 /// \return version of the QP as a hex constant constant 0xXYZZ, where X is
00042 /// a 1-digit major version number, Y is a 1-digit minor version number, and
00043 /// ZZ is a 2-digit release number.
00044 #define QP_VERSION      0x4104
00045 
00046 #ifndef Q_ROM
00047     /// \brief Macro to specify compiler-specific directive for placing a
00048     /// constant object in ROM.
00049     ///
00050     /// Many compilers for Harvard-architecture MCUs provide non-stanard
00051     /// extensions to support placement of objects in different memories.
00052     /// In order to conserve the precious RAM, QP uses the Q_ROM macro for
00053     /// all constant objects that can be allocated in ROM.
00054     ///
00055     /// To override the following empty definition, you need to define the
00056     /// Q_ROM macro in the qep_port.h header file. Some examples of valid
00057     /// Q_ROM macro definitions are: __code (IAR 8051 compiler), code (Keil
00058     /// Cx51 compiler), PROGMEM (gcc for AVR), __flash (IAR for AVR).
00059     #define Q_ROM
00060 #endif
00061 #ifndef Q_ROM_VAR            // if NOT defined, provide the default definition
00062     /// \brief Macro to specify compiler-specific directive for accessing a
00063     /// constant object in ROM.
00064     ///
00065     /// Many compilers for MCUs provide different size pointers for
00066     /// accessing objects in various memories. Constant objects allocated
00067     /// in ROM (see #Q_ROM macro) often mandate the use of specific-size
00068     /// pointers (e.g., far pointers) to get access to ROM objects. The
00069     /// macro Q_ROM_VAR specifies the kind of the pointer to be used to access
00070     /// the ROM objects.
00071     ///
00072     /// To override the following empty definition, you need to define the
00073     /// Q_ROM_VAR macro in the qep_port.h header file. An example of valid
00074     /// Q_ROM_VAR macro definition is: __far (Freescale HC(S)08 compiler).
00075     #define Q_ROM_VAR
00076 #endif
00077 #ifndef Q_ROM_BYTE
00078     /// \brief Macro to access a byte allocated in ROM
00079     ///
00080     /// Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do
00081     /// not generate correct code for accessing data allocated in the program
00082     /// space (ROM). The workaround for such compilers is to explictly add
00083     /// assembly code to access each data element allocated in the program
00084     /// space. The macro Q_ROM_BYTE() retrieves a byte from the given ROM
00085     /// address.
00086     ///
00087     /// The Q_ROM_BYTE() macro should be defined for the compilers that
00088     /// cannot handle correctly data allocated in ROM (such as the gcc).
00089     /// If the macro is left undefined, the default definition simply returns
00090     /// the argument and lets the compiler generate the correct code.
00091     #define Q_ROM_BYTE(rom_var_)   (rom_var_)
00092 #endif
00093 
00094 #ifndef Q_SIGNAL_SIZE
00095     /// \brief The size (in bytes) of the signal of an event. Valid values:
00096     /// 1, 2, or 4; default 1
00097     ///
00098     /// This macro can be defined in the QEP port file (qep_port.h) to
00099     /// configure the ::QSignal type. When the macro is not defined, the
00100     /// default of 1 byte is chosen.
00101     #define Q_SIGNAL_SIZE 1
00102 #endif
00103 #if (Q_SIGNAL_SIZE == 1)
00104     /// \brief QSignal represents the signal of an event.
00105     ///
00106     /// The relationship between an event and a signal is as follows. A signal
00107     /// in UML is the specification of an asynchronous stimulus that triggers
00108     /// reactions [<A HREF="http://www.omg.org/docs/ptc/03-08-02.pdf">UML
00109     /// document ptc/03-08-02</A>], and as such is an essential part of an
00110     /// event. (The signal conveys the type of the occurrence-what happened?)
00111     /// However, an event can also contain additional quantitative information
00112     /// about the occurrence in form of event parameters. Please refer to the
00113     /// document
00114     /// <A HREF="http://www.quantum-leaps.com/devzone/Recipe_IntroHSM.pdf">
00115     /// Brief Introduction to UML State Machines</A>) for more information
00116     /// about state machine concepts.
00117     typedef uint8_t QSignal;
00118 #elif (Q_SIGNAL_SIZE == 2)
00119     typedef uint16_t QSignal;
00120 #elif (Q_SIGNAL_SIZE == 4)
00121     typedef uint32_t QSignal;
00122 #else
00123     #error "Q_SIGNAL_SIZE defined incorrectly, expected 1, 2, or 4"
00124 #endif
00125 
00126 //////////////////////////////////////////////////////////////////////////////
00127 /// \brief QEvent base class.
00128 ///
00129 /// QEvent represents events without parameters and serves as the base class
00130 /// for derivation of events with parameters.
00131 ///
00132 /// \note All data members of the QEvent class must remain public to keep it
00133 /// an AGGREGATE. Therefore, the attribute QEvent::dynamic_ cannot be
00134 /// declared private.
00135 ///
00136 /// The following example illustrates how to add an event parameter by
00137 /// inheriting from the QEvent class.
00138 /// \include qep_qevent.cpp
00139 struct QEvent {
00140     QSignal sig;                             ///< signal of the event instance
00141     uint8_t dynamic_;  ///< attributes of a dynamic event (0 for static event)
00142 };
00143 
00144 //////////////////////////////////////////////////////////////////////////////
00145 /// helper macro to calculate static dimension of a 1-dim array \a array_
00146 #define Q_DIM(array_) (sizeof(array_) / sizeof(array_[0]))
00147 
00148 #endif                                                             // qevent_h