RKH engine interface.This header file is directly included in RKH interface file, rkh.h. More...
Go to the source code of this file.
Macros | |
| #define | RKH_USE_TRC_SENDER |
| This macro is used to verify the sender object usage on post an event. More... | |
| #define | RKH_RELEASE rkh_version |
| This macro retrieves a pointer to string describing the RKH version. For example, "2.2.04". | |
| #define | RKH_VERSION(a, b, c) |
| This is the macro used to build an integer version code from the individual numbers that build up a version number. More... | |
| #define | RKH_ANY ((RKH_SIG_T)(-1)) |
| This macro is used to indicate the end of a transition table. | |
| #define | RKH_COMPLETION_EVENT (RKH_ANY - 1) |
| This macro is used to indicate the completion event. More... | |
| #define | RKH_SM_CREATION_EVENT (RKH_ANY - 2) |
| This macro is used to indicate the State Machine creation event. More... | |
| #define | RKH_LOWEST_PRIO (RKH_CFG_FWK_MAX_SMA - 1) |
| RKH allows up to RKH_CFG_FWK_MAX_SMA different priority levels (see rkhcfg.h). More... | |
| #define | RKH_DCLR_PTR_TYPE(type_, me_) extern type_ * const me_ |
| This macro declares a typed and external pointer to previously defined object. More... | |
| #define | RKH_TICK_RATE_MS ((RKH_TNT_T)(1000 / RKH_CFG_FWK_TICK_RATE_HZ)) |
| More... | |
| #define | RKH_CFGPORT_SMA_THREAD_EN RKH_ENABLED |
| If the RKH_CFGPORT_SMA_THREAD_EN is set to 1, each SMA (active object) has its own thread of execution. More... | |
| #define | RKH_CFGPORT_SMA_THREAD_DATA_EN RKH_ENABLED |
| If the RKH_CFGPORT_SMA_THREAD_EN and RKH_CFGPORT_SMA_THREAD_DATA_EN are set to 1, each SMA (active object) has its own thread of execution and its own object data. When enabling it, the option RKH_OSSIGNAL_TYPE must be defined. More... | |
| #define | RKH_CFGPORT_NATIVE_SCHEDULER_EN RKH_ENABLED |
| If the RKH_CFGPORT_NATIVE_SCHEDULER_EN is set to 1 then RKH will include the simple, cooperative, and nonpreemptive scheduler RKHS. When RKH_CFGPORT_NATIVE_SCHEDULER_EN is enabled RKH also will automatically define RKH_EQ_TYPE, and include rkh_sma_block(), rkh_sma_setReady(), rkh_sma_setUnready(), and assume the native priority scheme. More... | |
| #define | RKH_CFGPORT_NATIVE_EQUEUE_EN RKH_ENABLED |
| If the RKH_CFGPORT_NATIVE_EQUEUE_EN is set to 1 and the native event queue is enabled (see RKH_CFG_QUE_EN) then RKH will include its own implementation of rkh_sma_post_fifo(), rkh_sma_post_lifo(), and rkh_sma_get() functions. More... | |
| #define | RKH_CFGPORT_NATIVE_DYN_EVT_EN RKH_ENABLED |
| If the RKH_CFGPORT_NATIVE_DYN_EVT_EN is set to 1 and the native fixed-size memory block facility is enabled (see RKH_CFG_MP_EN) then RKH will include its own implementation of dynamic memory management. When RKH_CFGPORT_NATIVE_DYN_EVT_EN is enabled RKH also will provide the event pool manager implementation based on its native memory pool module. More... | |
| #define | RKH_CFGPORT_REENTRANT_EN RKH_ENABLED |
| If the RKH_CFGPORT_REENTRANT_EN is set to 1, the RKH event dispatch allows to be invoked from several threads of executions. Enable this only if the application is based on a multi-thread architecture. More... | |
| #define | RKH_CFGPORT_TRC_SIZEOF_PTR 32u |
| Specify the size of void pointer. The valid values [in bits] are 16 or 32. Default is 32. See RKH_TRC_SYM() macro. More... | |
| #define | RKH_CFGPORT_TRC_SIZEOF_FUN_PTR 32u |
| Specify the size of function pointer. The valid values [in bits] are 16 or 32. Default is 32. See RKH_TUSR_FUN() and RKH_TRC_FUN() macros. More... | |
| #define | RKH_CFGPORT_TRC_SIZEOF_TSTAMP 32u |
| Specify the number of bytes (size) used by the trace record timestamp. The valid values [in bits] are 8, 16 or 32. Default is 16. More... | |
| #define | RKH_CFGPORT_SMA_QSTO_EN RKH_ENABLED |
If the RKH_CFGPORT_SMA_QSTO_EN is set to 1 then RKH_SMA_ACTIVATE() macro invokes the rkh_sma_activate() function ignoring the external event queue storage argument, qs. More... | |
| #define | RKH_CFGPORT_SMA_STK_EN RKH_ENABLED |
If the RKH_CFGPORT_SMA_STK_EN is set to 0 then RKH_SMA_ACTIVATE() macro invokes the rkh_sma_activate() function ignoring the thread's stack related arguments, stks and stksize. More... | |
| #define | RKH_EQ_TYPE |
| Defines the data type of the event queue for active objects. The event queue can be implemented with a message queue of the RTOS/OS. But it is also possible to use the native RKH queue RKH_QUEUE_T type if the underlying RTOS/OS does not provide an adequate queue. More... | |
| #define | RKH_THREAD_TYPE |
Frequently, the active object has its own task processing loop that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued. The RKH_SMA_POST_FIFO() macro enqueues an event and signals the OS that an event has arrived. In this case, os_signal holds the OS object used to signal that an event has been queued. The data type RKH_THREAD_TYPE holds the thread handle associated with the active object. More... | |
| #define | RKH_OSSIGNAL_TYPE |
The os_signal member of RKH_SMA_T is necessary when the underlying OS does not provide an adequate queue facility, so the native RKH queue RKH_QUEUE_T must be used. In this case the RKH_OSSIGNAL_TYPE indicates an operating system specific primitive to efficiently block the native RKH event queue when the queue is empty. Frequently, the active object has its own task processing loop that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued. The RKH_SMA_POST_FIFO() macro enqueues an event and signals the OS that an event has arrived. In this case, os_signal holds the OS object used to signal that an event has been queued. More... | |
| #define | RKH_THREAD_STK_TYPE |
Data type to declare thread stack, which is only used when the underlying OS does not internally allocate the RAM storage to its threads, in this case must be enabled RKH_CFGPORT_SMA_STK_EN option in rkhport.h file. More... | |
| #define | RKH_TIME_MS(ms_) ((ms_) / RKH_TICK_RATE_MS) |
| It can be used to convert ticks to time. More... | |
| #define | RKH_TIME_SEC(s_) ((s_) * 1000u / RKH_TICK_RATE_MS) |
| It can be used to convert ticks to time. More... | |
| #define | RKH_TIME_MIN(m_) ((m_) * 60 * 1000u / RKH_TICK_RATE_MS) |
| It can be used to convert ticks to time. More... | |
| #define | RKH_DIS_INTERRUPT() |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. This allows RKH to protect critical code from being entered simultaneously. To hide the implementation method chosen by the processor, compiler, etc, RKH defines two macros to unconditionally disable and enable interrupts: RKH_DIS_INTERRUPT() and RKH_ENA_INTERRUPT() respectively. Obviously, they resides in rkhport.h file, which the user always need to provide. More... | |
| #define | RKH_ENA_INTERRUPT() |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. This allows RKH to protect critical code from being entered simultaneously. To hide the implementation method chosen by the processor, compiler, etc, RKH defines two macros to unconditionally disable and enable interrupts: RKH_DIS_INTERRUPT() and RKH_ENA_INTERRUPT() respectively. Obviously, they resides in rkhport.h file, which the user always need to provide. More... | |
| #define | RKH_CPUSR_TYPE |
| RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. More... | |
| #define | RKH_SR_ALLOC() RKH_CPUSR_TYPE sr = (RKH_CPUSR_TYPE)0 |
| RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. More... | |
| #define | RKH_ENTER_CRITICAL(dummy) |
| RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. More... | |
| #define | RKH_EXIT_CRITICAL(dummy) |
| RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. More... | |
Variables | |
| RKHROM char | noname [] |
| String representing the name of undefined object name. | |
Detailed Description
RKH engine interface.This header file is directly included in RKH interface file, rkh.h.
Definition in file rkhitl.h.
Macro Definition Documentation
◆ RKH_USE_TRC_SENDER
| #define RKH_USE_TRC_SENDER |
This macro is used to verify the sender object usage on post an event.
Specific definitions to the platform being used. Defines standard constants and macros. Application specific configuration options. Event data type and related macros.
The macros RKH_TIM_TICK(), RKH_SMA_POST_FIFO(), and RKH_SMA_POST_LIFO() takes an additional argument sender, which is a pointer to the sender object. This argument is actually only used when software tracing is enabled (macro RKH_USE_TRC_SENDER is defined). When software tracing is disabled, the macros RKH_TIM_TICK(), RKH_SMA_POST_FIFO(), and RKH_SMA_POST_LIFO() calls rkh_tmr_tick(), rkh_sma_post_fifo(), and rkh_sma_post_lifo() respectively without any arguments, so the overhead of passing this extra argument is entirely avoided.
◆ RKH_VERSION
| #define RKH_VERSION | ( | a, | |
| b, | |||
| c | |||
| ) |
This is the macro used to build an integer version code from the individual numbers that build up a version number.
For example, RKH_VERSION(2,2,04) expands to 0x2204. This macro is very useful when needs to compare the current version (RKH_VERSION_CODE) and a known checkpoint version at compile-time.
- Parameters
-
[in] a major revision [in] b minor revision [in] c release number
- Usage
- #if RKH_VERSION_CODE <= RKH_VERSION(1, 2, 03)...#else...#endif
◆ RKH_COMPLETION_EVENT
| #define RKH_COMPLETION_EVENT (RKH_ANY - 1) |
This macro is used to indicate the completion event.
A special kind of transition is a completion transition, which has an implicit trigger. The event that enables this trigger is called a completion event and it signifies that all behaviors associated with the source state of the completion transition have completed execution.
◆ RKH_SM_CREATION_EVENT
| #define RKH_SM_CREATION_EVENT (RKH_ANY - 2) |
This macro is used to indicate the State Machine creation event.
Upon creation, a State Machine will perform its initialization during which it executes an initial compound transition prompted by the creation, after which it enters a wait point, which is represented by a stable state configuration. It remains thus until an Event stored in its event pool is dispatched.
◆ RKH_LOWEST_PRIO
| #define RKH_LOWEST_PRIO (RKH_CFG_FWK_MAX_SMA - 1) |
RKH allows up to RKH_CFG_FWK_MAX_SMA different priority levels (see rkhcfg.h).
In RKH, a low-priority number corresponds to a high-priority level. Priority level zero (0) is thus the highest priority level. Priority RKH_LOWEST_PRIO (RKH_CFG_FWK_MAX_SMA - 1) is the lowest priority level.
◆ RKH_DCLR_PTR_TYPE
| #define RKH_DCLR_PTR_TYPE | ( | type_, | |
| me_ | |||
| ) | extern type_ * const me_ |
This macro declares a typed and external pointer to previously defined object.
- Parameters
-
[in] type_ Data type of the defined object. [in] me_ Pointer to previously defined object.
- See also
- RKH_SMA_DCLR_TYPE(), RKH_SM_DCLR_TYPE().
◆ RKH_TICK_RATE_MS
| #define RKH_TICK_RATE_MS ((RKH_TNT_T)(1000 / RKH_CFG_FWK_TICK_RATE_HZ)) |
It can be used to convert ticks to milliseconds. This format is more convenient and natural than ticks. This configuration constant is not used by RKH, it is just a value to allow an application to deal with time when using timer services. You can use the global constant RKH_CFG_FWK_TICK_RATE_HZ (see rkhcfg.h) to convert time to ticks using the macros like RKH_TIME_MS(), RKH_TIME_SEC(), and RKH_TIME_MIN().
◆ RKH_TIME_MS
| #define RKH_TIME_MS | ( | ms_ | ) | ((ms_) / RKH_TICK_RATE_MS) |
It can be used to convert ticks to time.
This format is more convenient and natural than ticks. You can use the global constant RKH_CFG_FWK_TICK_RATE_HZ (see rkhcfg.h) to convert time to ticks using the macros like RKH_TIME_MS(), RKH_TIME_SEC(), and RKH_TIME_MIN().
◆ RKH_TIME_SEC
| #define RKH_TIME_SEC | ( | s_ | ) | ((s_) * 1000u / RKH_TICK_RATE_MS) |
It can be used to convert ticks to time.
This format is more convenient and natural than ticks. You can use the global constant RKH_CFG_FWK_TICK_RATE_HZ (see rkhcfg.h) to convert time to ticks using the macros like RKH_TIME_MS(), RKH_TIME_SEC(), and RKH_TIME_MIN().
◆ RKH_TIME_MIN
| #define RKH_TIME_MIN | ( | m_ | ) | ((m_) * 60 * 1000u / RKH_TICK_RATE_MS) |
It can be used to convert ticks to time.
This format is more convenient and natural than ticks. You can use the global constant RKH_CFG_FWK_TICK_RATE_HZ (see rkhcfg.h) to convert time to ticks using the macros like RKH_TIME_MS(), RKH_TIME_SEC(), and RKH_TIME_MIN().
◆ RKH_DIS_INTERRUPT
| #define RKH_DIS_INTERRUPT | ( | ) |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. This allows RKH to protect critical code from being entered simultaneously. To hide the implementation method chosen by the processor, compiler, etc, RKH defines two macros to unconditionally disable and enable interrupts: RKH_DIS_INTERRUPT() and RKH_ENA_INTERRUPT() respectively. Obviously, they resides in rkhport.h file, which the user always need to provide.
Example for HCS08 CW6.3
Example for uC/OS-III and KSDK
◆ RKH_ENA_INTERRUPT
| #define RKH_ENA_INTERRUPT | ( | ) |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done. This allows RKH to protect critical code from being entered simultaneously. To hide the implementation method chosen by the processor, compiler, etc, RKH defines two macros to unconditionally disable and enable interrupts: RKH_DIS_INTERRUPT() and RKH_ENA_INTERRUPT() respectively. Obviously, they resides in rkhport.h file, which the user always need to provide.
Example for HCS08 CW6.3
Example for uC/OS-III and KSDK
◆ RKH_CPUSR_TYPE
| #define RKH_CPUSR_TYPE |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done.
This allows RKH to protect critical code from being entered simultaneously from either multiple SMAs or ISRs. Every processor generally provide instructions to disable/enable interrupts and the C compiler must have a mechanism to perform these operations directly from C. Some compilers will allows to insert in-line assembly language statements in the C source code. This makes it quite easy to insert processor instructions to enable and disable interrupts. Other compilers will actually contain language extensions to enable and disable interrupts directly from C. To hide the implementation method chosen by the compiler manufacturer, RKH defines two macros to disable and enable interrupts: RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL().
The RKH_ENTER_CRITICAL() macro saves the interrupt disable status onto the stack and then, disable interrupts. RKH_EXIT_CRITICAL() would simply be implemented by restoring the interrupt status from the stack. Using this scheme, if it's called a RKH service with either interrupts enabled or disabled then, the status would be preserved across the call. If calls a RKH service with interrupts disabled, is potentially extending the interrupt latency of application. The application can use RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL() to also protect critical sections of code. As a general rule, should always call RKH services with interrupts enabled!.
- Note
- These macros are internal to RKH and the user application should not call it.
Example for x86, VC2008, and win32 single thread:
Example for uC/OS-III and KSDK
◆ RKH_SR_ALLOC
| #define RKH_SR_ALLOC | ( | ) | RKH_CPUSR_TYPE sr = (RKH_CPUSR_TYPE)0 |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done.
This allows RKH to protect critical code from being entered simultaneously from either multiple SMAs or ISRs. Every processor generally provide instructions to disable/enable interrupts and the C compiler must have a mechanism to perform these operations directly from C. Some compilers will allows to insert in-line assembly language statements in the C source code. This makes it quite easy to insert processor instructions to enable and disable interrupts. Other compilers will actually contain language extensions to enable and disable interrupts directly from C. To hide the implementation method chosen by the compiler manufacturer, RKH defines two macros to disable and enable interrupts: RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL().
The RKH_ENTER_CRITICAL() macro saves the interrupt disable status onto the stack and then, disable interrupts. RKH_EXIT_CRITICAL() would simply be implemented by restoring the interrupt status from the stack. Using this scheme, if it's called a RKH service with either interrupts enabled or disabled then, the status would be preserved across the call. If calls a RKH service with interrupts disabled, is potentially extending the interrupt latency of application. The application can use RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL() to also protect critical sections of code. As a general rule, should always call RKH services with interrupts enabled!.
- Note
- These macros are internal to RKH and the user application should not call it.
Example for x86, VC2008, and win32 single thread:
Example for uC/OS-III and KSDK
◆ RKH_ENTER_CRITICAL
| #define RKH_ENTER_CRITICAL | ( | dummy | ) |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done.
This allows RKH to protect critical code from being entered simultaneously from either multiple SMAs or ISRs. Every processor generally provide instructions to disable/enable interrupts and the C compiler must have a mechanism to perform these operations directly from C. Some compilers will allows to insert in-line assembly language statements in the C source code. This makes it quite easy to insert processor instructions to enable and disable interrupts. Other compilers will actually contain language extensions to enable and disable interrupts directly from C. To hide the implementation method chosen by the compiler manufacturer, RKH defines two macros to disable and enable interrupts: RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL().
The RKH_ENTER_CRITICAL() macro saves the interrupt disable status onto the stack and then, disable interrupts. RKH_EXIT_CRITICAL() would simply be implemented by restoring the interrupt status from the stack. Using this scheme, if it's called a RKH service with either interrupts enabled or disabled then, the status would be preserved across the call. If calls a RKH service with interrupts disabled, is potentially extending the interrupt latency of application. The application can use RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL() to also protect critical sections of code. As a general rule, should always call RKH services with interrupts enabled!.
- Note
- These macros are internal to RKH and the user application should not call it.
Example for x86, VC2008, and win32 single thread:
Example for uC/OS-III and KSDK
◆ RKH_EXIT_CRITICAL
| #define RKH_EXIT_CRITICAL | ( | dummy | ) |
RKH need to disable interrupts in order to access critical sections of code, and re-enable interrupts when done.
This allows RKH to protect critical code from being entered simultaneously from either multiple SMAs or ISRs. Every processor generally provide instructions to disable/enable interrupts and the C compiler must have a mechanism to perform these operations directly from C. Some compilers will allows to insert in-line assembly language statements in the C source code. This makes it quite easy to insert processor instructions to enable and disable interrupts. Other compilers will actually contain language extensions to enable and disable interrupts directly from C. To hide the implementation method chosen by the compiler manufacturer, RKH defines two macros to disable and enable interrupts: RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL().
The RKH_ENTER_CRITICAL() macro saves the interrupt disable status onto the stack and then, disable interrupts. RKH_EXIT_CRITICAL() would simply be implemented by restoring the interrupt status from the stack. Using this scheme, if it's called a RKH service with either interrupts enabled or disabled then, the status would be preserved across the call. If calls a RKH service with interrupts disabled, is potentially extending the interrupt latency of application. The application can use RKH_ENTER_CRITICAL() and RKH_EXIT_CRITICAL() to also protect critical sections of code. As a general rule, should always call RKH services with interrupts enabled!.
- Note
- These macros are internal to RKH and the user application should not call it.
Example for x86, VC2008, and win32 single thread:
Example for uC/OS-III and KSDK
◆ RKH_EQ_TYPE
| #define RKH_EQ_TYPE |
Defines the data type of the event queue for active objects. The event queue can be implemented with a message queue of the RTOS/OS. But it is also possible to use the native RKH queue RKH_QUEUE_T type if the underlying RTOS/OS does not provide an adequate queue.
Example for using the native queue
◆ RKH_THREAD_TYPE
| #define RKH_THREAD_TYPE |
Frequently, the active object has its own task processing loop that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued. The RKH_SMA_POST_FIFO() macro enqueues an event and signals the OS that an event has arrived. In this case, os_signal holds the OS object used to signal that an event has been queued. The data type RKH_THREAD_TYPE holds the thread handle associated with the active object.
Example for using the uCOS/II, FreeRTOS, Linux (Posix) and Win32
◆ RKH_OSSIGNAL_TYPE
| #define RKH_OSSIGNAL_TYPE |
The os_signal member of RKH_SMA_T is necessary when the underlying OS does not provide an adequate queue facility, so the native RKH queue RKH_QUEUE_T must be used. In this case the RKH_OSSIGNAL_TYPE indicates an operating system specific primitive to efficiently block the native RKH event queue when the queue is empty. Frequently, the active object has its own task processing loop that waits for the signal to be posted, and when it is, loops to remove and process all events that are currently queued. The RKH_SMA_POST_FIFO() macro enqueues an event and signals the OS that an event has arrived. In this case, os_signal holds the OS object used to signal that an event has been queued.
Example for using the Linux (Posix) and Win32
◆ RKH_THREAD_STK_TYPE
| #define RKH_THREAD_STK_TYPE |
Data type to declare thread stack, which is only used when the underlying OS does not internally allocate the RAM storage to its threads, in this case must be enabled RKH_CFGPORT_SMA_STK_EN option in rkhport.h file.
Example
