mirror of
https://github.com/QuantumLeaps/qpcpp.git
synced 2025-01-28 06:02:56 +08:00
314 lines
12 KiB
Plaintext
314 lines
12 KiB
Plaintext
/*! @page api API Reference
|
||
@nav_next{deprecated}
|
||
|
||
@section api_qep QEP (Hierarchical State Machines)
|
||
QEP is a universal, UML-compliant event processor that enables developers to code UML state machines in highly readable ANSI-C, in which every state machine element is mapped to code precisely, unambiguously, and exactly once (traceability). QEP fully supports hierarchical state nesting, which is the fundamental mechanism for reusing behavior across many states instead of repeating the same actions and transitions over and over again.
|
||
|
||
|
||
@subsection api_qep_hsm Hierarchical State Machines
|
||
- QHsm class
|
||
- QHsm::QHsm()
|
||
- QHsm::init()
|
||
- QHsm::dispatch()
|
||
- QHsm::isIn()
|
||
- QHsm::state()
|
||
- QHsm::top()
|
||
- QMsm class
|
||
- QMsm::QMsm()
|
||
- QMsm::isInState()
|
||
- QMsm::stateObj()
|
||
- Q_STATE_CAST()
|
||
|
||
|
||
@section api_qf QF (Active Object Framework)
|
||
QF is a portable, event-driven, real-time framework for execution of active objects (concurrent state machines) specifically designed for real-time embedded (RTE) systems.
|
||
|
||
|
||
@subsection api_qf_act Active Objects
|
||
- QActive class
|
||
- QActive::QActive()
|
||
- QActive::start()
|
||
- %QActive:: POST()
|
||
- %QActive:: POST_X()
|
||
- QActive::postLIFO()
|
||
- QActive::defer()
|
||
- QActive::recall()
|
||
- QActive::flushDeferred()
|
||
- QActive::stop()
|
||
- QMActive class
|
||
- QMActive::QMActive()
|
||
|
||
|
||
@subsection api_qf_ps Publish-Subscribe
|
||
- ::QSubscrList (Subscriber List struct)
|
||
- QActive::psInit()
|
||
- %QF:: PUBLISH()
|
||
- QActive::subscribe()
|
||
- QActive::unsubscribe()
|
||
- QActive::unsubscribeAll()
|
||
|
||
|
||
@subsection api_qf_evt Event Management
|
||
- QEvt class
|
||
- Q_NEW()
|
||
- Q_NEW_X()
|
||
- Q_NEW_REF()
|
||
- Q_DELETE_REF()
|
||
- QF::gc()
|
||
- Q_EVT_CAST()
|
||
|
||
|
||
@subsection api_qf_time Time Events
|
||
- QTimeEvt class
|
||
- QTimeEvt::QTimeEvt()
|
||
- QTimeEvt::armX()
|
||
- QTimeEvt::disarm()
|
||
- QTimeEvt::rearm()
|
||
- QTimeEvt::currCtr()
|
||
- QTicker active object
|
||
- %QF:: TICK()
|
||
- %QF:: TICK_X()
|
||
|
||
|
||
@subsection api_qf_queue Event Queues (raw thread-safe)
|
||
- QEQueue class
|
||
- QEQueue::init()
|
||
- QEQueue::post()
|
||
- QEQueue::postLIFO()
|
||
- QEQueue::get()
|
||
- QEQueue::getNFree()
|
||
- QEQueue::getNMin()
|
||
- QEQueue::isEmpty()
|
||
- QEQueueCtr()
|
||
|
||
|
||
@subsection api_qf_mem Memory Pools
|
||
- QMPool class
|
||
- QMPool::init()
|
||
- QMPool::get()
|
||
- QMPool::put()
|
||
|
||
|
||
@section api_qs QS ("Quantum Spy" Software Tracing)
|
||
QS is a software tracing system that enables developers to monitor live event-driven QP applications with minimal target system resources and without stopping or significantly slowing down the code. QS is an ideal tool for testing, troubleshooting, and optimizing QP applications. QS can even be used to support acceptance testing in product manufacturing.
|
||
|
||
|
||
@subsection api_qs_ini QS Initialization and Control
|
||
- QS_INIT()
|
||
- QS::initBuf()
|
||
- QS::getByte()
|
||
- QS::getBlock()
|
||
- QS::onStartup()
|
||
- QS::onCleanup()
|
||
- QS::onFlush()
|
||
- QS::onGetTime()
|
||
|
||
|
||
@subsection api_qs_rx QS Receive-Channel (QS-RX)
|
||
- QS::rxInitBuf()
|
||
- QS::rxPut()
|
||
- QS::rxParse()
|
||
- QS::onCommand()
|
||
|
||
|
||
@subsection api_qs_filter QS Filters
|
||
- QS_GLB_FILTER()
|
||
- QS_LOC_FILTER()
|
||
- QS_FILTER_AP_OBJ()
|
||
|
||
|
||
@subsection api_qs_dict QS Dictionaries
|
||
- QS_SIG_DICTIONARY()
|
||
- QS_OBJ_DICTIONARY()
|
||
- QS_OBJ_ARR_DICTIONARY()
|
||
- QS_FUN_DICTIONARY()
|
||
- QS_USR_DICTIONARY()
|
||
|
||
|
||
@subsection api_qs_user QS Application-Specific Records
|
||
- ::QS_USER enumeration
|
||
- QS_BEGIN_ID()
|
||
- QS_END()
|
||
- QS_U8() / QS_I8()
|
||
- QS_U16() / QS_I16()
|
||
- QS_U32() / QS_I32()
|
||
- QS_U32_HEX()
|
||
- QS_STR()
|
||
- QS_MEM()
|
||
|
||
|
||
@section api_qv QV (Cooperative Kernel)
|
||
QV is a simple **cooperative** kernel (previously called "Vanilla" kernel). This kernel executes active objects one at a time, with priority-based scheduling performed before processing of each event. Due to naturally short duration of event processing in state machines, the simple QV kernel is often adequate for many real-time systems.
|
||
|
||
The QV scheduler is engaged after every RTC step of any active object to choose the next active object to execute. The QV scheduler always chooses the highest-priority active object that has any events in its event queue. The QV scheduler then extracts the next event from this queue and dispatches it to the state machine associated with the active object. The state machine runs to completion, after which the QV scheduler runs and the cycle repeats.
|
||
|
||
Please note that because the state machines always return to the QV scheduler after each RTC step, a single stack can be used to process all state machines (memory-friendly architecture).
|
||
|
||
The QV scheduler can also very easily detect when all event queues are empty, at which point it can call the idle callback to let the application put the CPU and peripherals to a low-power sleep mode (power-friendly architecture).
|
||
|
||
Given the simplicity, portability, and low-resource consumption, the QV scheduler is very attractive. It allows you to partition the problem into active objects and execute these active objects orderly. The task-level response of this scheduler is the longest RTC step in the whole system, but because event-driven active objects don’t block, the RTC steps tend to be very short (typically just a few microseconds). Also, often you can break up longer RTC steps into shorter pieces, by posting an event to self and returning (“Reminder” state pattern). The self-posted event then triggers the continuation of longer processing.
|
||
|
||
|
||
@subsection api_qv_init Kernel Initialization and Control
|
||
- QV_INIT()
|
||
- <a href="qv_8c.html#a779a1bc9482e2d489dc87751cd100fdb"><b>QF_run()</b></a>
|
||
- QV::onIdle()
|
||
- QV_CPU_SLEEP()
|
||
|
||
|
||
@section api_qk QK (Preemptive Run-to-Completion Kernel)
|
||
QK is a tiny **preemptive**, priority-based, non-blocking kernel designed specifically for executing active objects. QK runs active objects in the same way as prioritized interrupt controller (such as NVIC in ARM Cortex-M) runs interrupts using the single stack. Active objects process their events in run-to-completion (RTC) fashion and remove themselves from the call stack, the same way as nested interrupts remove themselves from the stack upon completion. At the same time high-priority active objects can preempt lower-priority active objects, just like interrupts can preempt each other under a prioritized interrupt controller. QK meets all the requirement of the Rate Monotonic Scheduling (a.k.a. Rate Monotonic Analysis RMA) and can be used in hard real-time systems.
|
||
|
||
|
||
@subsection api_qk_ctrl Kernel Initialization and Control
|
||
- QK_INIT()
|
||
- <a href="qk_8c.html#a779a1bc9482e2d489dc87751cd100fdb"><b>QF_run()</b></a>
|
||
- QK::onIdle()
|
||
- QK::schedLock()
|
||
- QK::schedUnlock()
|
||
|
||
|
||
@subsection api_qk_isr Interrupt Management
|
||
- QK_ISR_ENTRY()
|
||
- QK_ISR_EXIT()
|
||
|
||
|
||
@section api_qxk QXK (Preemptive Dual-Mode Run-to-Completion/Blocking RTOS Kernel)
|
||
QXK is a small, preemptive, priority-based, dual-mode **blocking** kernel that executes active objects like the @ref qk "QK kernel", but can also execute traditional __blocking__ threads (extended threads). In this respect, QXK behaves exactly as a conventional __RTOS__ (Real-Time Operating System). QXK 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.
|
||
|
||
|
||
@subsection api_qxk_ctrl Kernel Initialization and Control
|
||
- QXK_INIT()
|
||
- <a href="qxk_8c.html#a779a1bc9482e2d489dc87751cd100fdb"><b>QF_run()</b></a>
|
||
- QXK::onIdle()
|
||
- QXK::schedLock()
|
||
- QXK::schedUnlock()
|
||
|
||
|
||
@subsection api_qxk_isr Interrupt Management
|
||
- QXK_ISR_ENTRY()
|
||
- QXK_ISR_EXIT()
|
||
|
||
|
||
@subsection api_qxk_xthr Extended Thread Management
|
||
- QXThread class
|
||
- QXThread::QXThread()
|
||
- QXThread::start()
|
||
- QXThread::delay()
|
||
- QXThread::delayCancel()
|
||
- QXThread::queueGet()
|
||
- Q_XTHREAD_CAST()
|
||
- QXK_current()
|
||
- QXK_TLS()
|
||
|
||
|
||
@subsection api_qxk_sema Semaphores
|
||
- QXSemaphore class (Semaphore Control Block)
|
||
- QXSemaphore::init()
|
||
- QXSemaphore::wait()
|
||
- QXSemaphore::tryWait()
|
||
- QXSemaphore::signal()
|
||
|
||
|
||
@subsection api_qxk_mutex Mutexes
|
||
- QXMutex class (Mutex Control Block)
|
||
- QXMutex::init()
|
||
- QXMutex::lock()
|
||
- QXMutex::tryLock()
|
||
- QXMutex::unlock()
|
||
|
||
|
||
@subsection api_qxk_queue Message Queues
|
||
- %QXThread:: POST()
|
||
- %QXThread:: POST_X()
|
||
- QXThread::queueGet() - waiting (blocking) on message queue
|
||
|
||
|
||
@subsection api_qxk_mem Memory Pools
|
||
- QMPool class
|
||
- QMPool::init()
|
||
- QMPool::get()
|
||
- QMPool::put()
|
||
|
||
<br>
|
||
@nav_next{deprecated}
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @page deprecated Deprecated APIs
|
||
|
||
__The following QP/C++ APIs are now deprecated:__
|
||
*/
|
||
|
||
/*##########################################################################*/
|
||
/*! @namespace QP
|
||
@brief QP/C++ framework
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @namespace QP::QF
|
||
@brief hierarchical event processor and active object framework
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @namespace QP::QS
|
||
@brief "QP/Spy" software tracing (target-resident components)
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @namespace QP::QV
|
||
@brief cooperative, non-preemptive kernel
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @namespace QP::QK
|
||
@brief preemptive, non-blocking kernel
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @namespace QP::QXK
|
||
@brief preemptive, dual-mode (non-blocking / blocking) kernel
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir include
|
||
@brief Platform-independent QP™/C++ API
|
||
|
||
@attention
|
||
The QP™/C++ <span class="img folder">include</span> directory needs to be added to the compiler's include path in the applications using QP™/C++.
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src
|
||
@brief Platform-independent QP™/C++ source code
|
||
|
||
Files from this directory need to be added to the project, to build the QP™/C++ framework from source code.
|
||
|
||
@attention
|
||
The QP™/C++ <span class="img folder">src</span> directory needs to be added to the compiler's include path in the applications that build QP™/C++ framework from sources (as opposed to using QP as a pre-built library).
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src/qf
|
||
@brief Platform-independent implementation of the QEP and QF components.
|
||
|
||
@note
|
||
Typically, files in this directory need to be added to the application build, but some QP ports might not need all the files in this directory. For example, a QP port to a 3rd-party RTOS kernel might be using a message queue of the RTOS instead of the native QP event queue, in which case the file qf_actq.cpp would not be needed and should be excluded from the build.
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src/qv
|
||
@brief Platform-independent implementation of the @ref srs_qv built-in kernel.
|
||
|
||
@attention
|
||
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qv kernel.
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src/qk
|
||
@brief Platform-independent implementation of the @ref srs_qk built-in kernel.
|
||
|
||
@attention
|
||
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qk kernel.
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src/qxk
|
||
@brief Platform-independent implementation of the @ref srs_qxk built-in kernel.
|
||
|
||
@attention
|
||
Files in this directory need to be included in the QP application build only if the application uses the @ref srs_qxk kernel.
|
||
*/
|
||
/*##########################################################################*/
|
||
/*! @dir src/qs
|
||
@brief Platform-independent implementation of the @ref qs component (software tracing).
|
||
*/
|