QP/C  8.0.0
Real-Time Embedded Framework
Loading...
Searching...
No Matches
Structure Viewpoint

Purpose and ScopeInteraction Viewpoint

Structure Viewpoint elaborates the base classes and interfaces identified in the architecture Context Viewpoint with their design details and structural static relationships. The Structure Design Viewpoint also provides examples of using the QP/C Framework classes in QP/C Applications and is used to address the following concerns:

  • packages and classes
  • interfaces
  • functionality and responsibilities
  • data structures
  • control flow
  • concurrency and parallelism
  • resource management

The model kind used to illustrate the Structure Viewpoint is the UML class diagram shown in Figure SDS-CLS (static view). It depicts base classes comprising QP/C Framework and their specializations in the QP/C Application shown at the bottom of Figure SDS-CLS.

Figure SDS-CLS: Core classes in QP/C Framework and their relation to QP/C Application.

Sub-Layer View

The Sub-Layer View view in the Structure Viewpoint focuses on the internal layering of the QP/C Framework, which has the following objectives:

  • promote modularity.
  • separation of concerns into passive and active elements.
  • enable QP/C Application to use of only the passive layer without pulling in any of the Active Object layer.

SDS_QP_QEP

SDS_QP_QEP : QEP Event Processor
Description
QEP Event Processor sub-layer of QP/C Framework (see Figure SDS-CLS [10]) implements Events and passive State Machines.
Note
QEP Event Processor is intentionally separated out to allow QP/C Applications to directly use just the passive state machines (without Active Objects). QP/C Applications that use just the QEP Event Processor can still benefit from the QM modeling tool↑ , which can generate code that requires only passive state machines.
Backward Traceability
Forward Traceability

SDS_QP_QF

SDS_QP_QF : QF Active Object Framework
Description
QF Active Object Framework sub-layer of QP/C Framework (see Figure SDS-CLS [20]) implements Active Objects and Time Events.
Note
QF Active Object Framework requires the QEP Event Processor to provide events and implement the state machine behavior of Active Objects.
Backward Traceability
Forward Traceability

Class View

The Class View in the Structure Viewpoint focuses on the following key design concerns:

  • describing the logical structure and organization of the system, including the identification of classes and their relationships.
  • defining the QP/C Framework base classes that are the basis for derivation of QP/C Applications from the framework.
  • describing the responsibilities of each class to achieve high cohesion within a class and loose coupling among classes.
  • defining the inheritance hierarchies and polymorphic behavior to promote reuse and flexibility.
  • ensuring data encapsulation within classes to maintain safety, integrity, and security.

SDS_QP_QEvt

SDS_QP_QEvt : QEvt event class.
Description
The QEvt class (see Figure SDS-CLS [11]) represents both immutable and mutable events in QP/C Framework. It can be instantiated directly (concrete class), in which case it represents events without parameters. QP/C Applications can also inherit and extend QEvt to add custom event parameters.
Attention
Event parameters must be included in the event instance directly. Therefore, the QEvt sublcasses are restricted to have both "standard layout" and be "trivially copyable". In QP/C this means that QEvt sublcasses should:
  • contain NO pointers (including NO virtual pointer); The only exception is passing an opaque pointer to Active Object intended as the recipient of future events.
Event Attributes
The QEvt class has the following data attributes:
  • event signal of type QSignal with compile-time configurable dynamic range
  • event reference counter with dynamic range 0 .. (2 * QF_MAX_ACTIVE). For mutable events, the reference counter stores the number of outstanding references to that event instance. For immutable events, the reference counter is fixed at 1.
  • event tag with two fileds:
    • bits 4-7 store the event pool ID of the event (for dynamic events) and fixed at 0 for immutable events.
    • bits 0-3 implement the Safety Function described below:
Safety Function
The QEvt class implements the Duplicate Inverse Storage technique for data integrity self-monitoring of the volatile QEvt::refCtr_ reference counter attribute. For memory efficiency, only 4 least-significant bits 0:3 of the reference counter are monitoried in bits 0:3 of the QEvt::evtTag_ attribute.
Backward Traceability
  • SRS_QP_EVT_00 : QP/C Framework shall provide Event abstraction to QP/C Application
  • SRS_QP_EVT_20 : Each event instance shall contain the event Signal
  • SRS_QP_EVT_30 : QP/C Framework shall allow Application to create event instances with Parameters defined by the Application
  • SRS_QP_EVT_31 : Event abstraction may contain other data items for internal event management inside QP/C Framework
Forward Traceability

SDS_QP_QAsm

SDS_QP_QAsm : QAsm Abstract state machine class.
Description
The QAsm class (see Figure SDS-CLS [12]) is the abstract base class (ABC) for all state machines in QP/C Framework. The QAsm class specifies the abstract state machine interface.
State Machine Interface
The state machine interface defined in the QAsm class consists of:
  • init() operation executes the top-most initial transition. It must be executed only once.
  • dispatch() operation dispatches a given even to the state machine for RTC processing. It must be executed for every event.
  • isIn() (is in-state) operation returns 'true' if the state machine is-in the given state. Note that being "in-a-state" means also being in all the superstates of that state.
State Machine Attributes
  • current state (state variable): stores the current state of the state machhine.
  • temporary attribute: stores transition target during a state transition. Also used to implement the Safety Function described below.
Safety Function
In the stable state configuration (between the RTC steps) the subclasses of QAsm use the temporary attribute for the Duplicate Inverse Storage of the QAsm::state attribute.
Backward Traceability
  • SRS_QP_SM_00 : QP/C Framework shall provide support for hierarchical state machines both for Active Objects and for passive event-driven objects in the Application
  • SRS_QP_SM_10 : QP/C Framework shall support multiple and interchangeable State Machine Implementation Strategies
  • SRS_QP_SM_25 : All State Machine Implementation Strategies provided by QP/C Framework might supply a method for checking if a state machine is in a given state
Forward Traceability

SDS_QP_QHsm

SDS_QP_QHsm : QHsm State machine class.
Description
The QHsm class (see Figure SDS-CLS [13]) derived from QAsm implements the state machine interface init() and dispatch() according to the State Machine Implementation Strategy optimized for manual coding. QHsm provides support for hierarchical nesting of states, entry/exit actions, initial transitions, and transitions to history in any composite state. This class is designed for ease of manual coding, but it is also supported by the QM modeling and code-generation tool↑ .
Safety Function
The QHsm class implements the Fixed Loop Bound technique for all not explicitly terminated loops. This prevents malformed state machines specifications (from the QP/C Application layer) to "hang" or crash the event processor.
Backward Traceability
  • SRS_QP_SM_20 : QP/C Framework shall provide a State Machine Implementation Strategy optimized for "manual coding"
  • SRS_QP_SM_22 : All State Machine Implementation Strategies provided by QP/C Framework shall be bidirectionally traceable
  • SRS_QP_SM_23 : QP/C Framework shall ensure that the current event does not change and is accessible to the state machine implementation over the entire RTC step.
  • SRS_QP_SM_24 : All State Machine Implementation Strategies provided by QP/C shall allow Applications to easily access the instance variables associated with a given state machine object
  • SRS_QP_SM_30 : All State Machine Implementation Strategies provided by QP/C Framework shall support hierarchical state machines with features specified in the sub-requirements SRS_QP_SM_3x
  • SRS_QP_SM_31 : All State Machine Implementation Strategies provided by QP/C Framework shall support states capable of holding hierarchically nested substates
  • SRS_QP_SM_32 : All State Machine Implementation Strategies provided by QP/C Framework shall support entry actions to states
  • SRS_QP_SM_33 : All State Machine Implementation Strategies provided by QP/C Framework shall support exit actions from states
  • SRS_QP_SM_34 : All State Machine Implementation Strategies provided by QP/C Framework shall support nested initial transitions in composite states
  • SRS_QP_SM_35 : All State Machine Implementation Strategies provided by QP/C Framework shall support transitions between states at any level of nesting
  • SRS_QP_SM_36 : All State Machine Implementation Strategies provided by QP/C Framework shall support internal transitions in states
  • SRS_QP_SM_37 : All State Machine Implementation Strategies provided by QP/C Framework shall support guard conditions to be attached to regular and internal transitions
  • SRS_QP_SM_38 : All State Machine Implementation Strategies provided by QP/C Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object
  • SRS_QP_SM_39 : All State Machine Implementation Strategies provided by QP/C Framework should support transitions to history. Both shallow and deep histories shall be supported
  • SRS_QP_SM_40 : State Machine Implementation Strategies provided by QP/C Framework might supply the top-state
Forward Traceability

SDS_QP_QMsm

SDS_QP_QMsm : QMsm State machine class.
Description
The QMsm class (Figure SDS-CLS [14]) derived from QAsm implements the state machine interface init() and dispatch() according to the State Machine Implementation Strategy optimized for automatic code generation. QMsm provides support for all hierarchical state machine features listed in SRS_QP_SM_20 and sub-requirements plus submachines and submachine states. This class is designed for automatic code generation, and requires the QM modeling and code-generation tool↑ .
Safety Function
The QMsm class implements the Fixed Loop Bound technique for all not explicitly terminated loops. This prevents malformed state machines specifications (from the QP/C Application layer) to "hang" or crash the event processor.
Backward Traceability
  • SRS_QP_SM_21 : QP/C Framework should provide a State Machine Implementation Strategy optimized for "automatic code generation"
  • SRS_QP_SM_22 : All State Machine Implementation Strategies provided by QP/C Framework shall be bidirectionally traceable
  • SRS_QP_SM_23 : QP/C Framework shall ensure that the current event does not change and is accessible to the state machine implementation over the entire RTC step.
  • SRS_QP_SM_24 : All State Machine Implementation Strategies provided by QP/C shall allow Applications to easily access the instance variables associated with a given state machine object
  • SRS_QP_SM_30 : All State Machine Implementation Strategies provided by QP/C Framework shall support hierarchical state machines with features specified in the sub-requirements SRS_QP_SM_3x
  • SRS_QP_SM_31 : All State Machine Implementation Strategies provided by QP/C Framework shall support states capable of holding hierarchically nested substates
  • SRS_QP_SM_32 : All State Machine Implementation Strategies provided by QP/C Framework shall support entry actions to states
  • SRS_QP_SM_33 : All State Machine Implementation Strategies provided by QP/C Framework shall support exit actions from states
  • SRS_QP_SM_34 : All State Machine Implementation Strategies provided by QP/C Framework shall support nested initial transitions in composite states
  • SRS_QP_SM_35 : All State Machine Implementation Strategies provided by QP/C Framework shall support transitions between states at any level of nesting
  • SRS_QP_SM_36 : All State Machine Implementation Strategies provided by QP/C Framework shall support internal transitions in states
  • SRS_QP_SM_37 : All State Machine Implementation Strategies provided by QP/C Framework shall support guard conditions to be attached to regular and internal transitions
  • SRS_QP_SM_38 : All State Machine Implementation Strategies provided by QP/C Framework shall support top-most initial transition that shall be explicitly triggered independently from instantiation of the state machine object
  • SRS_QP_SM_39 : All State Machine Implementation Strategies provided by QP/C Framework should support transitions to history. Both shallow and deep histories shall be supported
  • SRS_QP_SM_40 : State Machine Implementation Strategies provided by QP/C Framework might supply the top-state
Forward Traceability

SDS_QP_QActive

SDS_QP_QActive : QActive Active Object class.
Description
The QActive class (Figure SDS-CLS [23]) is a base class for derivation of concrete Active Objects in the QP/C Application. QActive inherits QAsm, which means that an Active Object in QP/C can be treated as a state machine with the standard interface. QActive implements this interface by delegating to the QHsm state machine implementation.
Active Object Priority
QActive owns the unique priority attribute, which must be in range 1..QF_MAX_ACTIVE, inclusive.

Event Queue
QActive owns the event-queue attribute, whose type depends on the underlying real-time kernel. Therefore, the event-queue type is compile-time configurable. When QP/C is used with one of the built-in kernels (QV, QK, QXK), the QActive event queue is configured to be QEQueue. However, when QP/C Framework runs on a 3rd-party RTOS, typically the RTOS' message queue is adapted as an event queue.

Remarks
The event queue for Active Objects requires multiple-write, but only single-read capability. Also, blocking the queue is only required when event-queue is empty but not when it is full. Finally, the Active Object queue in QP/C Framework passes only pointers to events. Standard RTOS message queues are significantly more complex than required by Active Objects because they typically allow multiple-write as well as multiple-read access and often support variable-length data (not only pointer-sized data). Usually message queues also allow blocking when the queue is empty and when the queue is full, and both types of blocking can be timed out. Naturally, all this extra functionality, which you don't really need in QP/C Framework, comes at an extra cost in CPU and memory usage.

Thread of Execution
QActive owns the execution thread attribute, whose type depends on the underlying real-time kernel. Therefore, the thread type is compile-time configurable. When QP/C is used with one of the built-in kernels (QV, QK, QXK), the QActive thread attribute isn't really needed and is used to hold MPU settings. However, when QP/C Framework runs on a 3rd-party RTOS, the QActive thread attribute holds the RTOS thread.

OS Object
The "operating system object" attribute is

Backward Traceability
  • SRS_QP_AO_00 : QP/C Framework shall provide the Active Object abstraction to QP/C Application
  • SRS_QP_AO_70 : Active Object abstraction shall provide support for state machines.
Forward Traceability

SDS_QP_QMctive

SDS_QP_QMctive : QMctive Active Object class.
Description
The QMActive class (Figure SDS-CLS [24]) derives from QActive base class, so it inherits all its properties. The only difference is that, QMActive implements the state machine interface by delegating to the QMsm state machine implementation.
Backward Traceability
  • SRS_QP_AO_00 : QP/C Framework shall provide the Active Object abstraction to QP/C Application
  • SRS_QP_AO_70 : Active Object abstraction shall provide support for state machines.
Forward Traceability

SDS_QP_QTimeEvt

SDS_QP_QTimeEvt : QTimeEvt time event class.
Description
The QActive class (Figure SDS-CLS [23]) is a base class for derivation of concrete Active Objects in the QP/C Application. QActive encapsulates the unique priority, event-queue, execution context, and state machine for the Active Object. QActive inherits QAsm, which means that an Active Object in QP/C can be treated as a state machine with the standard interface. QActive implements this interface by delegating to the QHsm state machine implementation.
Backward Traceability
Forward Traceability

Purpose and ScopeInteraction Viewpoint