qs_pkg.h

00001 //////////////////////////////////////////////////////////////////////////////
00002 // Product: QS/C++
00003 // Last Updated for Version: 4.0.00
00004 // Date of the Last Update:  Apr 07, 2008
00005 //
00006 //                    Q u a n t u m     L e a P s
00007 //                    ---------------------------
00008 //                    innovating embedded systems
00009 //
00010 // Copyright (C) 2002-2008 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 qs_pkg_h
00029 #define qs_pkg_h
00030 
00031 /// \file
00032 /// \ingroup qs
00033 /// \brief Internal (package scope) QS/C++ interface.
00034 
00035 #include "qs_port.h"                                                // QS port
00036 
00037 /// \brief QS ring buffer counter and offset type
00038 typedef uint16_t QSCtr;
00039 
00040 /// \brief Internal QS macro to insert an un-escaped byte into
00041 /// the QS buffer
00042 ////
00043 #define QS_INSERT_BYTE(b_) \
00044     QS_ring_[QS_head_++] = (b_); \
00045     if (QS_head_ == QS_end_) { \
00046         QS_head_ = (QSCtr)0; \
00047     } \
00048     ++QS_used_;
00049 
00050 /// \brief Internal QS macro to insert an escaped byte into the QS buffer
00051 #define QS_INSERT_ESC_BYTE(b_) \
00052     QS_chksum_ = (uint8_t)(QS_chksum_ + (b_)); \
00053     if (((b_) == QS_FRAME) || ((b_) == QS_ESC)) { \
00054         QS_INSERT_BYTE(QS_ESC) \
00055         QS_INSERT_BYTE((uint8_t)((b_) ^ QS_ESC_XOR)) \
00056     } \
00057     else { \
00058         QS_INSERT_BYTE(b_) \
00059     }
00060 
00061 /// \brief Internal QS macro to insert a escaped checksum byte into
00062 /// the QS buffer
00063 #define QS_INSERT_CHKSUM_BYTE() \
00064     QS_chksum_ = (uint8_t)~QS_chksum_; \
00065     if ((QS_chksum_ == QS_FRAME) || (QS_chksum_ == QS_ESC)) { \
00066         QS_INSERT_BYTE(QS_ESC) \
00067         QS_INSERT_BYTE((uint8_t)(QS_chksum_ ^ QS_ESC_XOR)) \
00068     } \
00069     else { \
00070         QS_INSERT_BYTE(QS_chksum_) \
00071     }
00072 
00073 
00074 /// \brief Frame character of the QS output protocol
00075 #define QS_FRAME    ((uint8_t)0x7E)
00076 
00077 /// \brief Escape character of the QS output protocol
00078 #define QS_ESC      ((uint8_t)0x7D)
00079 
00080 /// \brief Escape modifier of the QS output protocol
00081 ///
00082 /// The escaped byte is XOR-ed with the escape modifier before it is inserted
00083 /// into the QS buffer.
00084 #define QS_ESC_XOR  0x20
00085 
00086 #ifndef Q_ROM_BYTE
00087     /// \brief Macro to access a byte allocated in ROM
00088     ///
00089     /// Some compilers for Harvard-architecture MCUs, such as gcc for AVR, do
00090     /// not generate correct code for accessing data allocated in the program
00091     /// space (ROM). The workaround for such compilers is to explictly add
00092     /// assembly code to access each data element allocated in the program
00093     /// space. The macro Q_ROM_BYTE() retrieves a byte from the given ROM
00094     /// address.
00095     ///
00096     /// The Q_ROM_BYTE() macro should be defined for the compilers that
00097     /// cannot handle correctly data allocated in ROM (such as the gcc).
00098     /// If the macro is left undefined, the default definition simply returns
00099     /// the argument and lets the compiler generate the correct code.
00100     #define Q_ROM_BYTE(rom_var_)   (rom_var_)
00101 #endif
00102 
00103 //............................................................................
00104 extern uint8_t *QS_ring_;         ///< pointer to the start of the ring buffer
00105 extern QSCtr QS_end_;                ///< offset of the end of the ring buffer
00106 extern QSCtr QS_head_;         ///< offset to where next byte will be inserted
00107 extern QSCtr QS_tail_;       ///< offset of where next event will be extracted
00108 extern QSCtr QS_used_;       ///< number of bytes currently in the ring buffer
00109 extern uint8_t QS_seq_;                        ///< the record sequence number
00110 extern uint8_t QS_chksum_;             ///< the checksum of the current record
00111 extern uint8_t QS_full_;              ///< the ring buffer is temporarily full
00112 
00113 #endif                                                             // qs_pkg_h