GitHub/qpcpp
1
0
Fork 0
mirror of https://github.com/QuantumLeaps/qpcpp.git synced 2025-01-14 05:42:57 +08:00
Code Issues Projects Releases Wiki Activity
qpcpp/doxygen/exa_rtos.dox
QL 2f4bc75bb1 6.0.4
2018-01-10 18:26:05 -05:00

419 lines
18 KiB
Plaintext
Raw Blame History

namespace QP {
/*##########################################################################*/
/*! @page exa_rtos Examples for Third-Party RTOS
The main purpose of integrating QP/C++ with conventional RTOSes is to enable you to incorporate various communication stacks (TCP/IP, USB, CAN, etc.) as well as other middleware, which requires the ability to **block** the task code. Currently the following 3rd-party RTOSes are supported:
- @subpage exa_embos (directory <span class="img folder">examples/embos/</span>)
- @subpage exa_freertos (directory <span class="img folder">examples/freertos/</span>)
- @subpage exa_threadx (directory <span class="img folder">examples/threadx/</span>)
- @subpage exa_ti-rtos (directory <span class="img folder">examples/ti-rtos/</span>)
- @subpage exa_ucos-ii (directory <span class="img folder">examples/ucos-ii/</span>)
@note
You do **not** need to use a third-party RTOS just to achieve preemptive multitasking with QP/C++. The framework contains a selection of built-in real-time kernels, such as the cooperative @ref qv "QV kernel", the preemptive non-blocking @ref qk "QK kernel", and the preemptive, dual-mode, blocking @ref qxk "QXK kernel". Specifically, the QXK kernel has been designed specifically for mixing event-driven active objects with traditional **blocking code**, such as commercial middleware (TCP/IP stacks, UDP stacks, embedded file systems, etc.) or legacy software.
@next{exa_embos examples}
*/
/*##########################################################################*/
/*! @page exa_embos embOS
@htmlonly
<script src="preview.js" type="text/javascript"></script>
@endhtmlonly
The QP/C++ examples for SEGGER embOS are as follows:
- ARM Cortex-M
- @subpage embos_dpp_stm32f429-discovery (Cortex-M4F) <a class="preview board" href="bd_STM32F4-Discovery.jpg" title="STM32F4-Discovery">STM32F4-Discovery</a><br>(IAR EWARM toolset)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{embos_dpp_stm32f429-discovery}
*/
/*##########################################################################*/
/*! @page embos_dpp_stm32f429-discovery DPP on STM32F4-Discovery
The @ref dpp "DPP example" for embOS on STM32F4-Discovery board is located directory <span class="img folder">examples/embos/arm-cm/dpp_stm32f429-discovery</span>.
@image html bd_STM32F4-Discovery.jpg STM32F4-Discovery board
The sub-directory <span class="img folder">iar</span> contains the workspace and project file that you can open in IAR EWARM IDE.
After you load the DPP example into the STM32F4-Discovery board, the application should start blinking the 4 on-board LEDs. You can press the User button (blue) to PAUSE the philosophers for as long as the button is depressed. The philosophers resume dining when you release the User button. (In the PAUSED state the Table active object stops granting permissions to eat, so eventually all philosophers end in the "hungry" state.)
------------------------------------------------------------------------------
@section embos_dpp_stm32f429-discovery_qs QS Software Tracing
The DPP example for embOS on STM32F4-Discovery board provides the "Spy" build configuration, which outputs the QS (Quantum Spy) software tracing data through USART2. To get the data out of the board, you need to connect the TTL/RS232 converter as follows:
<center>
STM32F4-Discovery | TTL/RS232 Converter
-------------------|:------------------------
PA2 | TX
PA3 | RX (currently not used)
VDD | VCC
GND | GND
</center>
@image html bd_STM32F4-Discovery_RS232.jpg STM32F4-Discovery board connected to RS232 level shifter
The output is generated at 115200 baud rate.
Here is an example invocation of the QSPY host application to receive the QS data from STM32F4-Discovery:
@verbatim
qspy -cCOM1
@endverbatim
The actual COM port number might be different on your Windows machine. Please check the Device Manager to find the COM port number.
@next{exa_freertos examples}
*/
/*##########################################################################*/
/*! @page exa_freertos FreeRTOS
@htmlonly
<script src="preview.js" type="text/javascript"></script>
@endhtmlonly
The QP/C examples for FreeRTOS are as follows:
- ARM Cortex-M
- @subpage freertos_dpp_ek-tm4c123gxl (Cortex-M4F) <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a><br>(ARM-KEIL, GNU-ARM and IAR EWARM toolchains)
- @subpage freertos_dpp_stm32f746g-disco (Cortex-M7) <a class="preview board" href="bd_STM32F746G-Disco.jpg" title="STM32F746G-Discovery"></a><br>(ARM-KEIL, GNU-ARM and IAR EWARM toolchains)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_os examples}
*/
/*##########################################################################*/
/*! @page freertos_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board
@ref dpp "DPP example" for @ref freertos "FreeRTOS" on Texas Instruments TivaC123GXL MCU (Cortex-M4F) with the following toolchains:
- ARM-Keil
- GNU-ARM
- IAR-ARM
Demonstrated features:
- Multiple Active Objects
- Regular "kernel-aware" ISR with "FromISR" APIs
+ `QF::TICK_X_FROM_ISR()`
+ `QF::PUBLISH_FROM_ISR()`
+ `Q_NEW_FROM_ISR()`
+ `QActive::POST_FROM_ISR()`
- Hi-priority "kernel-unaware" ISR
- `vApplicationTickHook()`
- QP/Spy output over the virtual COM port (Spy build configuration)
- QP/Spy input over the virtual COM port (bi-directional Spy) (Spy build configuration)
@next{freertos_dpp_stm32f746g-disco examples}
*/
/*##########################################################################*/
/*! @page freertos_dpp_stm32f746g-disco DPP on STM32F746G-Discovery
@image html bd_STM32F746G-Disco.jpg STM32F746G-Discovery
@ref dpp "DPP example" for @ref freertos "FreeRTOS" on STM32F746G-Discovery MCU (Cortex-M7) with the following toolchains:
- ARM-Keil
- GNU-ARM
- IAR-ARM
Demonstrated features:
- Multiple Active Objects
- Regular "kernel-aware" ISR with "FromISR" APIs
+ `QF::TICK_X_FROM_ISR()`
+ `QF::PUBLISH_FROM_ISR()`
+ `Q_NEW_FROM_ISR()`
+ `QActive::POST_FROM_ISR()`
- Hi-priority "kernel-unaware" ISR
- `vApplicationTickHook()`
- QP/Spy output over the virtual COM port (Spy build configuration)
- QP/Spy input over the virtual COM port (bi-directional Spy) (Spy build configuration)
@next{exa_threadx examples}
*/
/*##########################################################################*/
/*! @page exa_threadx ThreadX
The QP/C++ examples for ThreadX (Express Logic) are as follows:
- @subpage threadx_dpp_stm32f429-discovery <a class="preview board" href="bd_STM32F4-Discovery.jpg" title="STM32F4-Discovery">STM32F4-Discovery</a><br>(IAR EWARM toolset)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_ti-rtos examples}
*/
/*##########################################################################*/
/*! @page threadx_dpp_stm32f429-discovery DPP on STM32F4-Discovery
The @ref dpp "DPP example" for ThreadX on STM32F4-Discovery board is located directory <span class="img folder">examples/threadx/arm-cm/dpp_stm32f429-discovery</span>.
@image html bd_STM32F4-Discovery.jpg STM32F4-Discovery board
The sub-directory <span class="img folder">iar</span> contains the workspace and project file that you can open in IAR EWARM IDE.
@attention
Due to the limitations of the ThreadX library for Windows, the DPP example can only instantiate one `Philo[0]` active object.
After you load the DPP example into the STM32F4-Discovery board, the application should start blinking the 4 on-board LEDs. You can press the User button (blue) to PAUSE the philosophers for as long as the button is depressed. The philosophers resume dining when you release the User button. (In the PAUSED state the Table active object stops granting permissions to eat, so eventually all philosophers end in the "hungry" state.)
------------------------------------------------------------------------------
@section threadx_dpp_stm32f429-discovery_qs QS Software Tracing
The DPP example for ThreadX on STM32F4-Discovery board provides the "Spy" build configuration, which outputs the QS (Quantum Spy) software tracing data through USART2. To get the data out of the board, you need to connect the TTL/RS232 converter as follows:
<center>
STM32F4-Discovery | TTL/RS232 Converter
-------------------|:------------------------
PA2 | TX
PA3 | RX (currently not used)
VDD | VCC
GND | GND
</center>
@image html bd_STM32F4-Discovery_RS232.jpg STM32F4-Discovery board connected to RS232 level shifter
The output is generated at 115200 baud rate.
Here is an example invocation of the QSPY host application to receive the QS data from STM32F4-Discovery:
@verbatim
qspy -cCOM1
@endverbatim
The actual COM port number might be different on your Windows machine. Please check the Device Manager to find the COM port number.
@next{exa_ti-rtos examples}
*/
/*##########################################################################*/
/*! @page exa_ti-rtos TI-RTOS
@htmlonly
<script src="preview.js" type="text/javascript"></script>
@endhtmlonly
The QP/C++ examples for TI-RTOS are as follows:
- ARM Cortex-M
- @subpage ti-rtos_dpp_ek-tm4c123gxl (Cortex-M4F) <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a><br>(TI-CCS and IAR EWARM toolsets)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_ucos-ii examples}
*/
/*##########################################################################*/
/*! @page ti-rtos_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
The @ref dpp "DPP example" for TI-RTOS on EK-TM4C123GXL board is located directory <span class="img folder">examples/ti-rtos/arm-cm/dpp_ek-tm4c123gxl</span>.
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board
@attention
The TI-RTOS requires its own tooling (XDCTOOLS) and is too big to fit into the <span class="img folder">3rd_party/</span> directory in the QP/C++ distribution. Therefore, you need to **download and install TI-RTOS** on your machine before you can build any examples (preferably in the default location <span class="img folder">C:/TI</span>). Please refer to the TI Application Note "TI-RTOS for TivaC Getting Started Guide" (Literature Number: <a href="http://www.ti.com/lit/ug/spruhu5d/spruhu5d.pdf" target="_blank" class="extern">SPRUHU5D</a>) for more information.
The sub-directory <span class="img folder">ccs</span> contains the project files that you can **import** into the TI CCS IDE.
The sub-directory <span class="img folder">iar</span> contains the workspace and project file that you can open in IAR EWARM IDE.
After you load the DPP example into the EK-TM4C123GXL board, the application should start blinking the on-board three-color LED (located below the Reset button). You can press the SW1 button (lower-left corner) to PAUSE the philosophers for as long as the button is depressed. The philosophers resume dining when you release the User button. (In the PAUSED state the Table active object stops granting permissions to eat, so eventually all philosophers end in the "hungry" state.)
------------------------------------------------------------------------------
@section ti-rtos_main main.cpp for TI-RTOS
The `main.cpp` for TI-RTOS is actually identical as for the built-in QV/QK/QXK kernels. In particular, you do **not need to provide stack space** to active objects, because they execute in the context of lightweight TI-RTOS Swis (Software Interrupts), which don't need private stacks.
@code{cpp}
int main() {
static QP::QEvt const *tableQueueSto[N_PHILO];
static QP::QEvt const *philoQueueSto[N_PHILO][N_PHILO];
static QP::QSubscrList subscrSto[DPP::MAX_PUB_SIG];
static QF_MPOOL_EL(DPP::TableEvt) smlPoolSto[2*N_PHILO];
QP::QF::init(); // initialize the framework and the underlying RT kernel
DPP::BSP::init(); // initialize the BSP
QP::QF::psInit(subscrSto, Q_DIM(subscrSto)); // init publish-subscribe
// initialize event pools...
QP::QF::poolInit(smlPoolSto,
sizeof(smlPoolSto), sizeof(smlPoolSto[0]));
// start the active objects...
for (uint8_t n = 0U; n < N_PHILO; ++n) {
DPP::AO_Philo[n]->start((uint_fast8_t)(n + 1U),
philoQueueSto[n], Q_DIM(philoQueueSto[n]),
[1] (void *)0, 0U); // no stack
}
DPP::AO_Table->start((uint_fast8_t)(N_PHILO + 1U),
tableQueueSto, Q_DIM(tableQueueSto),
[2] (void *)0, 0U); // no stack
return QP::QF::run(); // run the QF application
}
@endcode
<ul class="tag">
<li><span class="tag">1-2</span> You don't provide the per-active object stack at startup;
</li>
</ul>
------------------------------------------------------------------------------
@section ti-rtos_bsp BSP for TI-RTOS
@note
TI-RTOS is configured specifically for the DPP application by means of the configuration file `dpp.cfg`, which is included in the <span class="img folder">ccs/</span> and <span class="img folder">iar/</span> directories. This file is processed in the custom build step for TI-RTOS.
The highlights of the Board Support Package (BSP) for TI-RTOS are explained below:
@code{cpp}
// TI-RTOS callback functions ================================================
[1] extern "C" {
// Clock function to service the QP clock tick ...............................
[2] static void clk0Fxn(UArg arg0) {
~ ~ ~
[3] QP::QF::TICK_X(0U, &l_SysTick_Handler); // process time events for rate 0
// Perform the debouncing of buttons...
~ ~ ~
if (tmp != 0U) { // debounced SW1 state changed?
if (buttons.depressed == 0U) { // is SW1 depressed?
static QP::QEvt const pauseEvt = { DPP::PAUSE_SIG, 0U, 0U};
[4] QP::QF::PUBLISH(&pauseEvt, &l_SysTick_Handler);
}
else { // the button is released
static QP::QEvt const serveEvt = { DPP::SERVE_SIG, 0U, 0U};
QP::QF::PUBLISH(&serveEvt, &l_SysTick_Handler);
}
}
}
// Idle callback (see dpp.cfg) ...............................................
[5] void myIdleFunc() {
~ ~ ~
#ifdef NDEBUG
// Put the CPU and peripherals to the low-power mode.
// you might need to customize the clock management for your application,
// see the datasheet for your particular Cortex-M3 MCU.
//
__asm (" WFI"); // Wait-For-Interrupt
#endif
}
} // extern "C"
// namespace QP **************************************************************
namespace QP {
// QF callbacks ==============================================================
[6] void QF::onStartup(void) {
[7] static Clock_Struct clk0Struct;
Clock_Params clkParams;
[8] Clock_Params_init(&clkParams);
[9] clkParams.startFlag = TRUE;
[10] clkParams.period = 1000U/DPP::BSP::TICKS_PER_SEC;
// Construct a periodic Clock Instance
[11] Clock_construct(&clk0Struct, &clk0Fxn, clkParams.period, &clkParams);
}
~ ~ ~
} // namespace QP
@endcode
<ul class="tag">
<li><span class="tag">1</span> The TI-RTOS callback functions are defined as `extern "C"`;
</li>
<li><span class="tag">2</span> The function `clk0Fxn()` provides the TI-RTOS clock service (configured later in step [11]);
</li>
<li><span class="tag">3</span> The TI-RTOS clock function calls the QP::QF::TICK_X() service to process the QP time events;
</li>
<li><span class="tag">4</span> The TI-RTOS clock function might post or publish events to active objects;
</li>
<li><span class="tag">5</span> The TI-RTOS is configured (in the `dpp.cfg` file) to call the `myIdle()` function from the TI-RTOS idle loop; In the Release build configuration this function can put the CPU into a low-power sleep mode. In the Spy build configuration, the idle callback can perform QS software tracing output to the host.
</li>
<li><span class="tag">6</span> The QP::QF::onStartup() function configures and starts interrupts. Here the function also configures and starts TI-RTOS clock service;
</li>
<li><span class="tag">7</span> The TI-RTOS `Clock_Struct` is allocated statically;
</li>
<li><span class="tag">8</span> The Clock Parameters are initialized to default;
</li>
<li><span class="tag">9</span> The Clock service is started;
</li>
<li><span class="tag">10</span> The Clock period is set to fire the desired number of times per second (`BSP::TICKS_PER_SEC`). <span class="highlight">NOTE: The system clock rate in microseconds is configured in the TI-RTOS configuration file `dpp.cfg`</span>;
</li>
<li><span class="tag">11</span> The Clock service is constructed in the statically allocated memory;
</li>
</ul>
@note
Currently, the BSP does not demonstrate the QS (Q-SPY) tracing. Demonstrating the QS tracing for this example is planned in the future.
@next{exa_ucos-ii examples}
*/
/*##########################################################################*/
/*! @page exa_ucos-ii uC/OS-II
@htmlonly
<script src="preview.js" type="text/javascript"></script>
@endhtmlonly
The QP/C++ examples for uC/OS-II are as follows:
- ARM Cortex-M
- @subpage ucos-ii_dpp_ek-tm4c123gxl (Cortex-M4F) <a class="preview board" href="bd_EK-TM4C123GXL.jpg" title="EK-TM4C123GXL"></a><br>(ARM-KEIL and IAR EWARM toolsets)
- @subpage ucos-ii_dpp_nucleo-l152re (Cortex-M3) <a class="preview board" href="bd_nucleo-l152re.jpg" title="NUCLEO-L152RE"></a><br>(ARM-KEIL and IAR EWARM toolsets)
@note
You can hover the mouse cursor over the <span class="board"></span>&nbsp;&nbsp; icon in the list below to see the picture of the board.
@next{exa_os examples}
*/
/*##########################################################################*/
/*! @page ucos-ii_dpp_ek-tm4c123gxl DPP on EK-TM4C123GXL
@image html bd_EK-TM4C123GXL.jpg EK-TM4C123GXL board
DPP example for Texas Instruments TivaC123GXL MCU (Cortex-M4F) and IAR EWARM toolsets.
@image html under_construction.jpg
@next{exa_os examples}
*/
/*##########################################################################*/
/*! @page ucos-ii_dpp_nucleo-l152re DPP on NUCLEO-L152RE
@image html bd_nucleo-l152re.jpg NUCLEO-L152RE board
DPP example for Texas Instruments STM32 L152RET6 MCU (Cortex-M3) and IAR EWARM toolsets.
@image html under_construction.jpg
@next{exa_os examples}
*/
} // namespace QP
Reference in New Issue View Git Blame Copy Permalink