From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- .../RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html | 813 +++++++++++++++++++++ 1 file changed, 813 insertions(+) create mode 100644 docs/RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html (limited to 'docs/RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html') diff --git a/docs/RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html b/docs/RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html new file mode 100644 index 0000000..7f2075b --- /dev/null +++ b/docs/RTOS2/html/group__CMSIS__RTOS__KernelCtrl.html @@ -0,0 +1,813 @@ + + + + + +Kernel Information and Control +CMSIS-RTOS2: Kernel Information and Control + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS2 +  Version 2.1.3 +
+
Real-Time Operating System: API and RTX Reference Implementation
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Data Structures | +Enumerations | +Functions
+
+
Kernel Information and Control
CMSIS-RTOS API v2
+
+
+ +

Provides version/system information and starts/controls the RTOS Kernel. +More...

+ + + + + +

+Data Structures

struct  osVersion_t
 Version information. More...
 
+ + + + +

+Enumerations

enum  osKernelState_t {
+  osKernelInactive = 0, +
+  osKernelReady = 1, +
+  osKernelRunning = 2, +
+  osKernelLocked = 3, +
+  osKernelSuspended = 4, +
+  osKernelError = -1, +
+  osKernelReserved = 0x7FFFFFFFU +
+ }
 Kernel state. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

osStatus_t osKernelInitialize (void)
 Initialize the RTOS Kernel. More...
 
osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size)
 Get RTOS Kernel Information. More...
 
osKernelState_t osKernelGetState (void)
 Get the current RTOS Kernel state. More...
 
osStatus_t osKernelStart (void)
 Start the RTOS Kernel scheduler. More...
 
int32_t osKernelLock (void)
 Lock the RTOS Kernel scheduler. More...
 
int32_t osKernelUnlock (void)
 Unlock the RTOS Kernel scheduler. More...
 
int32_t osKernelRestoreLock (int32_t lock)
 Restore the RTOS Kernel scheduler lock state. More...
 
uint32_t osKernelSuspend (void)
 Suspend the RTOS Kernel scheduler. More...
 
void osKernelResume (uint32_t sleep_ticks)
 Resume the RTOS Kernel scheduler. More...
 
uint32_t osKernelGetTickCount (void)
 Get the RTOS kernel tick count. More...
 
uint32_t osKernelGetTickFreq (void)
 Get the RTOS kernel tick frequency. More...
 
uint32_t osKernelGetSysTimerCount (void)
 Get the RTOS kernel system timer count. More...
 
uint32_t osKernelGetSysTimerFreq (void)
 Get the RTOS kernel system timer frequency. More...
 
+

Description

+

The kernel Information and Control function group allows to:

+
    +
  • obtain information about the system and the underlying kernel.
    • +
  • obtain version information about the CMSIS-RTOS API.
    • +
  • initialize of the RTOS kernel for creating objects.
    • +
  • start the RTOS kernel and thread switching.
    • +
  • check the execution status of the RTOS kernel.
    • +
+
Note
The kernel information and control functions cannot be called from Interrupt Service Routines.
+
+The kernel initialization for RTX5 is documented in System Startup.
+

Code Example

+
/*----------------------------------------------------------------------------
+
* Application main thread
+
*---------------------------------------------------------------------------*/
+
void app_main (void *argument) {
+
+
// ...
+
for (;;) {}
+
}
+
+
int main (void) {
+
+
// System Initialization
+
SystemCoreClockUpdate();
+
#ifdef RTE_Compiler_EventRecorder
+
// Initialize and start Event Recorder
+
EventRecorderInitialize(EventRecordError, 1U);
+
#endif
+
// ...
+
+
osKernelInitialize(); // Initialize CMSIS-RTOS
+
osThreadNew(app_main, NULL, NULL); // Create application main thread
+
osKernelStart(); // Start thread execution
+
for (;;) {}
+
}
+

Data Structure Documentation

+ +
+
+ + + + +
struct osVersion_t
+
+

Identifies the underlying RTOS kernel and API version number. The version is represented in a combined decimal number in the format: major.minor.rev: mmnnnrrrr

+

Use osKernelGetInfo to retrieve the version numbers.

+
+ + + + + + + +
Data Fields
+uint32_t +api +API version (major.minor.rev: mmnnnrrrr dec).
+uint32_t +kernel +Kernel version (major.minor.rev: mmnnnrrrr dec).
+ +
+
+

Enumeration Type Documentation

+ +
+
+ + + + +
enum osKernelState_t
+
+

State of the kernel as retrieved by osKernelGetState. In case osKernelGetState fails or if it is called from an ISR, it will return osKernelError, otherwise it returns the kernel state.

+ + + + + + + + +
Enumerator
osKernelInactive  +

Inactive.

+

The kernel is not ready yet. osKernelInitialize needs to be executed successfully.

+
osKernelReady  +

Ready.

+

The kernel is not yet running. osKernelStart transfers the kernel to the running state.

+
osKernelRunning  +

Running.

+

The kernel is initialized and running.

+
osKernelLocked  +

Locked.

+

The kernel was locked with osKernelLock. The functions osKernelUnlock or osKernelRestoreLock unlocks it.

+
osKernelSuspended  +

Suspended.

+

The kernel was suspended using osKernelSuspend. The function osKernelResume returns to normal operation.

+
osKernelError  +

Error.

+

An error occurred.

+
osKernelReserved  +

Prevents enum down-size compiler optimization.

+

Reserved.

+
+ +
+
+

Function Documentation

+ +
+
+ + + + + + + + +
osStatus_t osKernelInitialize (void )
+
+
Returns
status code that indicates the execution status of the function.
+

The function osKernelInitialize initializes the RTOS Kernel. Before it is successfully executed, only the functions osKernelGetInfo and osKernelGetState may be called.

+

Possible osStatus_t return values:

+
    +
  • osOK in case of success.
    • +
  • osError if an unspecific error occurred.
    • +
  • osErrorISR if called from an Interrupt Service Routine.
    • +
  • osErrorNoMemory if no memory could be reserved for the operation.
    • +
+
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "RTE_Components.h"
+
#include CMSIS_device_header
+
#include "cmsis_os2.h"
+
+
/*----------------------------------------------------------------------------
+
* Application main thread
+
*---------------------------------------------------------------------------*/
+
void app_main (void *argument) {
+
+
// ...
+
for (;;) {}
+
}
+
+
int main (void) {
+
+
// System Initialization
+
SystemCoreClockUpdate();
+
// ...
+
+
osKernelInitialize(); // Initialize CMSIS-RTOS
+
osThreadNew(app_main, NULL, NULL); // Create application main thread
+
osKernelStart(); // Start thread execution
+
for (;;) {}
+
}
+
+
+
+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
osStatus_t osKernelGetInfo (osVersion_t * version,
char * id_buf,
uint32_t id_size 
)
+
+
Parameters
+ + + + +
[out]versionpointer to buffer for retrieving version information.
[out]id_bufpointer to buffer for retrieving kernel identification string.
[in]id_sizesize of buffer for kernel identification string.
+
+
+
Returns
status code that indicates the execution status of the function.
+

The function osKernelGetInfo retrieves the API and kernel version of the underlying RTOS kernel and a human readable identifier string for the kernel. It can be safely called before the RTOS is initialized or started (call to osKernelInitialize or osKernelStart).

+

Possible osStatus_t return values:

+
    +
  • osOK in case of success.
    • +
  • osError if an unspecific error occurred.
    • +
+
Note
This function may be called from Interrupt Service Routines.
+

Code Example

+
void info (void) {
+
char infobuf[100];
+
osVersion_t osv;
+
osStatus_t status;
+
+
status = osKernelGetInfo(&osv, infobuf, sizeof(infobuf));
+
if(status == osOK) {
+
printf("Kernel Information: %s\r\n", infobuf);
+
printf("Kernel Version : %d\r\n", osv.kernel);
+
printf("Kernel API Version: %d\r\n", osv.api);
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
osKernelState_t osKernelGetState (void )
+
+
Returns
current RTOS Kernel state.
+

The function osKernelGetState returns the current state of the kernel and can be safely called before the RTOS is initialized or started (call to osKernelInitialize or osKernelStart). In case it fails it will return osKernelError, otherwise it returns the kernel state (refer to osKernelState_t for the list of kernel states).

+

Possible osKernelState_t return values:

+
    +
  • osKernelError if an unspecific error occurred.
    • +
  • the actual kernel state otherwise.
    • +
+
Note
This function may be called from Interrupt Service Routines.
+

Code Example

+
int main (void) {
+
// System Initialization
+
SystemCoreClockUpdate();
+
// ...
+
if(osKernelGetState() == osKernelInactive) { // Is the kernel initialized?
+
osKernelInitialize(); // Initialize CMSIS-RTOS kernel
+
}
+
;
+
}
+
+
+
+ +
+
+ + + + + + + + +
osStatus_t osKernelStart (void )
+
+
Returns
status code that indicates the execution status of the function.
+

The function osKernelStart starts the RTOS kernel and begins thread switching. It will not return to its calling function in case of success. Before it is successfully executed, only the functions osKernelGetInfo, osKernelGetState, and object creation functions (osXxxNew) may be called.

+

At least one initial thread should be created prior osKernelStart, see osThreadNew.

+

Possible osStatus_t return values:

+ +
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
int main (void) {
+
// System Initialization
+
SystemCoreClockUpdate();
+
// ...
+
if(osKernelGetState() == osKernelInactive) {
+
osKernelInitialize();
+
}
+
; // ... Start Threads
+
if (osKernelGetState() == osKernelReady) { // If kernel is ready to run...
+
osKernelStart(); // ... start thread execution
+
}
+
+
while(1); // only reached in case of error
+
}
+
+
+
+ +
+
+ + + + + + + + +
int32_t osKernelLock (void )
+
+
Returns
previous lock state (1 - locked, 0 - not locked, error code if negative).
+

The function osKernelLock allows to lock all task switches. It returns the previous value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

+

Possible osStatus_t return values:

+ +
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
int32_t state = osKernelLock();
+
// ... critical code
+
osKernelRestore(state);
+
+
+
+ +
+
+ + + + + + + + +
int32_t osKernelUnlock (void )
+
+
Returns
previous lock state (1 - locked, 0 - not locked, error code if negative).
+

The function osKernelUnlock resumes from osKernelLock. It returns the previous value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

+

Possible osStatus_t return values:

+ +
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
int32_t sl = osKernelLock();
+
// ... critical code
+
{
+
int32_t su = osKernelUnlock();
+
// ... uncritical code
+
osKernelRestoreLock(su);
+
}
+
// ... critical code
+
osKernelRestoreLock(sl);
+
+
+
+ +
+
+ + + + + + + + +
int32_t osKernelRestoreLock (int32_t lock)
+
+
Parameters
+ + +
[in]locklock state obtained by osKernelLock or osKernelUnlock.
+
+
+
Returns
new lock state (1 - locked, 0 - not locked, error code if negative).
+

The function osKernelRestoreLock restores the previous lock state after osKernelLock or osKernelUnlock.

+

The argument lock specifies the lock state as obtained by osKernelLock or osKernelUnlock.

+

The function returns the new value of the lock state (1 if it was locked, 0 if it was unlocked), or a negative number representing an error code otherwise (refer to osStatus_t).

+

Possible osStatus_t return values:

+ +
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
int32_t sl = osKernelLock();
+
// ... critical code
+
{
+
int32_t su = osKernelUnlock();
+
// ... uncritical code
+
osKernelRestoreLock(su);
+
}
+
// ... critical code
+
osKernelRestoreLock(sl);
+
+
+
+ +
+
+ + + + + + + + +
uint32_t osKernelSuspend (void )
+
+
Returns
time in ticks, for how long the system can sleep or power-down.
+

CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to derive timer intervals. The function osKernelSuspend suspends the RTX kernel scheduler and thus enables sleep modes.

+

The return value can be used to determine the amount of system ticks until the next tick-based kernel event will occure, i.e. a delayed thread becomed ready again. It is recommended to set up the low power timer to generate a wake-up interrupt based on this return value.

+
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
void osRtxIdleThread (void) {
+
/* The idle thread is running
+
when no other thread is ready
+
to run. */
+
unsigned int sleep;
+
+
for (;;) {
+
/* HERE: include optional user
+
code to be executed when no
+
task runs. */
+
sleep = osKernelSuspend(); /* Suspend RTX thread scheduler */
+
+
if (sleep) { /* How long can we sleep? */
+
/* "sleep" is in RTX Timer Ticks
+
which is 1ms in this
+
configuration */
+
+
/* Setup wake-up e.g. watchdog */
+
+
__WFE(); /* Enter Power-down mode */
+
+
/* After Wake-up */
+
sleep = tc; /* Adjust with cycles slept */
+
}
+
+
osKernelResume(sleep); /* Resume thread scheduler */
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
void osKernelResume (uint32_t sleep_ticks)
+
+
Parameters
+ + +
[in]sleep_tickstime in ticks for how long the system was in sleep or power-down mode.
+
+
+

CMSIS-RTOS provides extension for tick-less operation which is useful for applications that use extensively low-power modes where the SysTick timer is also disabled. To provide a time-tick in such power-saving modes a wake-up timer is used to derive timer intervals. The function osKernelResume enables the RTX kernel scheduler and thus wakes up the system from sleep mode.

+
Note
This function cannot be called from Interrupt Service Routines.
+

Code Example

+
void osRtxIdleThread (void) {
+
/* The idle thread is running
+
when no other thread is ready
+
to run. */
+
unsigned int sleep;
+
+
for (;;) {
+
/* HERE: include optional user
+
code to be executed when no
+
task runs. */
+
sleep = osKernelSuspend(); /* Suspend RTX thread scheduler */
+
+
if (sleep) { /* How long can we sleep? */
+
/* "sleep" is in RTX Timer Ticks
+
which is 1ms in this
+
configuration */
+
+
/* Setup wake-up e.g. watchdog */
+
+
__WFE(); /* Enter Power-down mode */
+
+
/* After Wake-up */
+
sleep = tc; /* Adjust with cycles slept */
+
}
+
+
osKernelResume(sleep); /* Resume thread scheduler */
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
uint32_t osKernelGetTickCount (void )
+
+
Returns
RTOS kernel current tick count.
+

The function osKernelGetTickCount returns the current RTOS kernel tick count.

+
Note
This function may be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os2.h"
+
+
void Thread_1 (void *arg) { // Thread function
+
uint32_t tick;
+
+
tick = osKernelGetTickCount(); // retrieve the number of system ticks
+
for (;;) {
+
tick += 1000; // delay 1000 ticks periodically
+
osDelayUntil(tick);
+
// ...
+
}
+
}
+

Due to the limited value range used for the tick count it may overflow during runtime, i.e. after 232 ticks which are roughly 49days @ 1ms. Typically one has not to take special care of this unless a monotonic counter is needed. For such a case an additional 64bit tick counter can be implemented as follows. The given example needs GetTick() called at least twice per tick overflow to work properly.

+

Code Example

+
uint64_t GetTick(void) {
+
static uint32_t tick_h = 0U;
+
static uint32_t tick_l = 0U;
+
uint32_t tick;
+
+
tick = osKernelGetTickCount();
+
if (tick < tick_l) {
+
tick_h++;
+
}
+
tick_l = tick;
+
+
return (((uint64_t)tick_h << 32) | tick_l);
+
}
+
+
+
+ +
+
+ + + + + + + + +
uint32_t osKernelGetTickFreq (void )
+
+
Returns
frequency of the kernel tick in hertz, i.e. kernel ticks per second.
+

The function osKernelGetTickFreq returns the frequency of the current RTOS kernel tick.

+
Note
This function may be called from Interrupt Service Routines.
+ +
+
+ +
+
+ + + + + + + + +
uint32_t osKernelGetSysTimerCount (void )
+
+
Returns
RTOS kernel current system timer count as 32-bit value.
+

The function osKernelGetSysTimerCount returns the current RTOS kernel system timer as a 32-bit value.

+
Note
This function may be called from Interrupt Service Routines.
+ +
+
+ +
+
+ + + + + + + + +
uint32_t osKernelGetSysTimerFreq (void )
+
+
Returns
frequency of the system timer in hertz, i.e. timer ticks per second.
+

The function osKernelGetSysTimerFreq returns the frequency of the current RTOS kernel system timer.

+
Note
This function may be called from Interrupt Service Routines.
+ +
+
+
+
+ + + + -- cgit