The Dining Philosophers Problem (DPP) example is described in the Application Note: Dining Philosophers Problem (DPP) Example↑.

Application Note: Dining Philosophers Problem (DPP) Example

The DPP example is an intermediate-level application with multiple active objects. It illustrates the following QP features:

multiple Active Objects (AOs), including an array of Philo AOs;
designing state machines in the QM modeling tool↑ and generating the code automatically (can also be done manually);
QHsm state machine implementation strategy (for Philo AOs)
QMsm state machine implementation strategy (for Table AO)
using multiple periodic time events;
using mutable events with parameters.
direct event posting to Active Objects.
publish-subscribe event delivery;
multiple build configurations;
QP/Spy software tracing;
initializing the QP framework;
starting multiple Active Objects; and
transferring control to QP to run the application.

DPP Versions

The DPP example is provided in many versions for various execution targets, including host computers and embedded boards. All of these DPP versions contain essentially the same state machine code and differ only in the Board Support Package (BSP).

<qp>                   // QP/C or QP/C++ installation directory
|
+---examples           // QP examples
|   |
|   +---posix-win32    // examples for the host (POSIX, Windows)
|   |   +---dpp                    // DPP for Windows, Linux, macOS <== TRY FIRST
|   |   +---dpp-comp               // DPP-component for Windows, Linux, macOS
|   |
|   +---arm-cm         // examples for ARM Cortex-M embedded boards
|   |   +---dpp_ek-tm4c123gxl      // DPP for EK-TM4C123GXL (Cortex-M4)
|   |   +---dpp_mbed-lpc1768       // DPP for mbed LPC1768 (Cortex-M4)
|   |   +---dpp_ek-tm4c123gxl      // DPP for EK-TM4C123GXL (Cortex-M4)
|   |   +---dpp_nucleo-c031c6      // DPP for STM32 NUCLEO-C031C6 (Cortex-M0+)
|   |   +---dpp_nucleo-f401re      // DPP for STM32 NUCLEO-F401RE (Cortex-M4)
|   |   +---dpp_nucleo-h743zi      // DPP for STM32 NUCLEO-H743ZI (Cortex-M7)
|   |   +---dpp_nucleo-l053r8      // DPP for STM32 NUCLEO-L053R8 (Cortex-M0+)
|   |   +---dpp_nucleo-l152re      // DPP for STM32 NUCLEO-L152RE (Cortex-M3)
|   |   +---dpp_nucleo-l552ze      // DPP for STM32 NUCLEO-L55ZE (Cortex-M33)
|   |   +---dpp_nucleo-u545re      // DPP for STM32 NUCLEO-U545RE (Cortex-M33)
|   |   +---dpp_stm32f4-discovery  // DPP for STM32F4-DISCO (Cortex-M4)
|   |
|   +---stm32cube      // examples for STM32Cube IDE
|   |   +---dpp_nucleo-u545re      // DPP for STM32 NUCLEO-U545RE (Cortex-M33)
|   |
|   +---arm-cr         // examples for ARM Cortex-R embedded boards
|   |   +---dpp_launchxl2-tms57012 // DPP for LAUNCHXL2-TMS57012 (Cortex-R4)
|   |
|   +---msp430         // examples for MSP430 embedded boards
|   |   +---dpp_msp-exp430f5529lp  // DPP for MSP-EXP430f5529LP (MSP430 extended)
|   |
|   +---embos          // examples for embOS RTOS (SEGGER)
|   |   +---dpp_nucleo-h743zi      // DPP for NUCLEO-H743ZI (Cortex-M7)
|   |
|   +---esp-idf        // examples for ESP IDF modified FreeRTOS (Espressif)
|   |   +---dpp_nucleo-h743zi      // DPP for NUCLEO-H743ZI (Cortex-M7)
|   |
|   +---freertos       // examples for FreeRTOS (Amazon Web Services)
|   |   +---dpp_ek-tm4c123gxl      // EK-TM4C123GXL (Cortex-M4)
|   |   +---dpp_nucleo-c031c6      // DPP for STM32 NUCLEO-C031C6 (Cortex-M0+)
|   |   +---dpp_ek-tm4c123gxl      // DPP for EK-TM4C123GXL (Cortex-M4)
|   |   +---dpp_nucleo-f401re      // DPP for STM32 NUCLEO-F401RE (Cortex-M4)
|   |   +---dpp_nucleo-h743zi      // DPP for STM32 NUCLEO-H743ZI (Cortex-M7)
|   |   +---dpp_nucleo-u545re      // DPP for STM32 NUCLEO-U545RE (Cortex-M33)
|   |   +---dpp_stm32f4-discovery  // DPP for STM32F4-DISCO (Cortex-M4)
|   |
|   +---zephyr         // examples for Zephyr RTOS (Linux Foundation)
|   |   +---dpp                    // DPP for all Zephyr-supported boards

Remarks: The DPP version in the posix-win32 directory runs on the host computer and does not require any embedded hardware, and is the first one that you should try.

Remarks: There is also a DPP variant that implements the "Philosophers" as passive "Orthogonal Components" of the "Table" active object. That DPP version is located in <qp>/examples/posix-win32/dpp-comp

Build Configurations

The DPP example demonstrate multiple build configurations:

Debug — this configuration is built with full debugging information and minimal optimization. The QS trace instrumentation is disabled.
Release — this configuration is built with high optimization. Debugging at the source-code level is severely impaired due to the highly optimized code, but the debugger can be used to download and start the executable. The QS trace instrumentation is disabled.
Spy — like the debug variant, this variant is built with full debugging information and minimal optimization. Additionally, it is build with the QS trace instrumentation enabled. The on-board serial port and the Q-Spy host application are used for sending and viewing trace data.

Why do you need multiple build configurations?: The different phases of the embedded software life cycle pose different challenges. During the development and maintenance phase, for example, the emphasis is on the ease of debugging and verifying the correctness of the code, which requires lower levels of optimization and special instrumentation code. In contrast, for releasing the code in the final product, the emphasis is on small memory footprint, CPU efficiency, and low power consumption, which require high-level of optimization and removal of any code instrumentation. To address these conflicting objectives, the same source code is compiled into multiple build configurations that differ in the use of compiler options and activation of the code instrumentation.

DPP Code

The DPP example demonstrates the general structure of QP/C++ applications. Most of the code is identical for any deployment target. The only target-dependent part is the Board Support Package (BSP) implementation (the file bsp.cpp ). Here are the annotated files comprising the DPP example:

dpp               // DPP example
|   app.hpp       // Application interface (e.g., signals, events)
|   bsp.hpp       // Board Support Package interface
|   bsp.cpp       // Board Support Package implementation
|   main.cpp      // main function
|   philo.cpp     // Philosopher active object implementation
|   table.cpp     // Table active object implementation
|   qp_config.hpp // QP/C++ configuration

Remarks: In most cases, the files comprising the DPP application have been generated by the QM modeling tool↑ from the dpp.qm model file. However, if you don't intend to use QM, you can edit the code manually since you don't care that your changes would be lost when the code is regenerated.

The main Function

The file main.cpp shows the general steps to initialize and run the QP/C++ application.

#include "qpcpp.hpp"        // QP/C++ real-time event framework
#include "bsp.hpp"          // Board Support Package
 
//............................................................................
int main() {
    QP::QF::init();         // initialize the framework
    BSP::init();            // initialize the BSP
    return QP::QF::run();   // start AOs and run the framework
}

State Machines in philo.cpp and table.cpp

The Philo Active Object has a simple state machine depicted in the state diagram below. On the right, you can see the generated code for the state machine, with a very clear mapping of state machine elements to code.

State machine of the Philo Active Object

State machine of the Table Active Object

Remarks: The mapping between the state machine elements and code is specified in the State Dynamics Viewpoint of the Software Design Specification.

DPP on the Host (Console)

Building Blinky on Windows

Deafault Debug build configuration:

cd \qp\qpcp\examples\posix-win32\dpp
make

This assumes that the qpcpp framework exists in the directory \qp\qpcpp. Please check your installation and adjust the location as necessary.

Release build configuration:

cd \qp\qpcp\examples\posix-win32\dpp
make CONF=rel

Spy build configuration (with QP/Spy software tracing enabled):

cd \qp\qpcp\examples\posix-win32\dpp
make CONF=spy

Building Blinky on Linux or macOS

Deafault Debug build configuration:

cd ~/qp/qpcpp/examples/posix-win32/dpp
make

This assumes that the qpcpp framework exists in the directory ~/qp/qpcpp. Please check your installation and adjust the location as necessary.

Release build configuration:

cd ~/qp/qpcpp/examples/posix-win32/dpp
make CONF=rel

Spy build configuration (with QP/Spy software tracing enabled):

cd ~/qp/qpcpp/examples/posix-win32/dpp
make CONF=spy

DPP on the Embedded Targets

The DPP examples for various embedded boards are located in the @qpx/examples (see DPP Versions). For embedded targets, you have many more choices than on the host. The choices include:

the real-time kernel used in QP (QV, QK, QXK or 3rd-part RTOS)
the compiler toolchain and IDE used (e.g., GNU, KEIL, IAR, etc.)

Remarks: For embedded targets, the DPP code organization is similar to that of the Blinky on Embedded Targets.

Blinky"Fly 'n' Shoot" Game


QP/C++ 8.1.2 Real-Time Event Framework