QP/C++ Framework component shall support Time Events.
Description
Support for Time Events means that the QP/C++ Framework component shall provide a Time Event abstraction that behaves like other events in %QP, but is additionally equipped with the notion of time passage. The time passage consists of discrete steps (clock ticks).
Use Case
The basic usage model of the Time Events is as follows. An Active Object allocates and initializes one or more Time Event instances. When the Active Object needs to arrange for a timeout, it arms one of its time events to expire either just once (one-shot) or periodically. Each Time Event times out independently from the others, so a QP/C++ Application can make multiple parallel timeout requests (from the same or different Active Objects). When the QP/C++ Framework component service associated with the armed Time Events detects that the appropriate moment has arrived, it inserts the expiring Time Event instance directly into the recipient's event queue using the default FIFO policy with event delivery guarantee (SRS_QP_EDM_00). The recipient Active Object then processes the Time Event instance just like any other event.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall support up to 15 clock tick rates.
Description
Support for multiple clock tick rates means that the QP/C++ Framework component shall provide that many different ways of grouping Time Events and associating them with a given clock tick rate. The maximum number of clock tick rates supported by the QP/C++ Framework component shall be compile-time configurable with a maximum of 15.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall provide clock-tick processing operations for all supported clock rates that QP/C++ Application must call periodically to service the armed Time Events.
Description
The clock-tick processing operation shall update all armed Time Events associated with a given tick rate. The clock-tick processing operation must be callable from the interrupt level and also from the thread level (e.g., from an Active Object). Also, clock-tick processing operations for different tick rates must be allowed to preempt each other (e.g., higher clock tick rates might be serviced from interrupts while others are serviced from threads).
Use Case
QP/C++ Framework component can provide the clock-tick processing operation parameterized by the tick rate. For each tick rate, the QP/C++ Application must then invoke the corresponding clock-tick processing operation at the right period either from a time-tick ISR or from the thread level.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall provide Time Event initialization.
Description
The association between a Time Event and the event signal, recipient Active Object, and the tick rate shall be made only during initialization (e.g., via a constructor). It shall not be changed later during the lifetime of the Time Event.
QP/C++ Framework component shall allow a Time Event to be armed both for one-shot and periodic expiry.
Description
A Time Event shall provide a service to arm it to expire in a specified number of clock ticks of the associated clock tick rate (one-shot expiration). Additionally, the service shall allow specifying an interval for automatic re-arming the Time Event (periodic expiration). The special value zero (interval == 0) shall denote no periodic re-arming.
Arming an already armed Time Event shall be considered as a programming error, and the QP/C++ Framework component shall enter a safe state.
When the Timeout Expires, it gets directly posted (using the default FIFO policy with event delivery guarantee) into the event queue of the recipient Active Object. After posting, a one-shot time event gets automatically disarmed while a periodic time event (interval != 0) is automatically re-armed.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall allow a Time Event to be explicitly disarmed.
Description
A Time Event shall provide a service to disarm it. This service shall be available for Time Events armed for one-shot or periodic expiration. Disarming an already disarmed Time Event is fine and not considered an error.
Use Case
Due to the asynchronous nature of System Clock Tick, an Active Object sometimes cannot know whether a one-shot Time Event was automatically disarmed. Therefore, the disarm operation shall return the status of the Time Event. The return of 'true' shall mean that the Time Event was still armed. The return of 'false' means that the Time Event was not truly disarmed because it has already expired. The 'false' return is only possible for one-shot Time Events that have been automatically disarmed upon expiration. In this case, the 'false' return means that the Time Event has already been posted and should be expected in the recipient Active Object's event queue.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall allow a Time Event to be rearmed.
Description
A Time Event shall provide a service to rearm itself to expire in a specified number of clock ticks (of the associated tick rate). This service shall be available for Time Events armed for one-shot or periodic expiration. Reararming a Time Event that is disarmed is fine and not considered an error.
Use Case
The rearm service can be used to adjust the current period of a periodic time event or to prevent a one-shot time event from expiring (e.g., a watchdog Time Event). Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of a periodic time event.
Due to the asynchronous nature of System Clock Tick, an Active Object sometimes cannot know whether a one-shot Time Event was automatically rearmed. Therefore, the rearm operation shall return the status of the Time Event. Return 'true' shall mean that the Time Event was running as it was re-armed. The 'false' return means that the Time Event was not truly rearmed because it has already expired. The 'false' return is only possible for one-shot Time Events that have been automatically disarmed upon expiration. In this case, the 'false' return means that the Time Event has already been posted and should be expected in the Active Object's event queue.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall provide an operation to check whether any Time Events are armed for a given tick rate.
Description
The operation shall return 'true' if no Time Events are armed at the given tick rate and 'false' otherwise. Also, due to the asynchronous nature of the system clock tick, the operation shall be designed to run inside a critical section, thus preventing preemption.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall support low-power sleep modes.
Description
QP/C++ Framework component shall detect the idle condition of the system and provide a mechanism for QP/C++ Application to enter the desired sleep mode safely. "Entering a sleep mode safely" means that there should be no race conditions and situations where the system would enter a sleep mode with some events present in the Active Object event queues, and thus requiring processing.
Forward Traceability (truncated to 2 level(s))
