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 --- docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html | 469 +++++++++++++++++++++ 1 file changed, 469 insertions(+) create mode 100644 docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html (limited to 'docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html') diff --git a/docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html b/docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html new file mode 100644 index 0000000..482b0b4 --- /dev/null +++ b/docs/RTOS/html/group__CMSIS__RTOS__KernelCtrl.html @@ -0,0 +1,469 @@ + + + + + +Kernel Information and Control +CMSIS-RTOS: Kernel Information and Control + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS +  Version 1.03 +
+
Real-Time Operating System: API and RTX Reference Implementation.
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+Macros | +Functions
+
+
Kernel Information and Control
CMSIS-RTOS API
+
+
+ +

Provide version/system information and start the RTOS Kernel. +More...

+ + + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define osFeature_MainThread   1
 main thread 1=main can be thread, 0=not available More...
 
#define osFeature_SysTick   1
 osKernelSysTick functions: 1=available, 0=not available More...
 
#define osCMSIS   0x10002
 API version (main [31:16] .sub [15:0]) More...
 
#define osCMSIS_KERNEL   0x10000
 RTOS identification and version (main [31:16] .sub [15:0]) More...
 
#define osKernelSystemId   "KERNEL V1.00"
 RTOS identification string. More...
 
#define osKernelSysTickFrequency   100000000
 The RTOS kernel system timer frequency in Hz. More...
 
#define osKernelSysTickMicroSec(microsec)   (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
 Convert a microseconds value to a RTOS kernel system timer value. More...
 
+ + + + + + + + + + + + + +

+Functions

osStatus osKernelInitialize (void)
 Initialize the RTOS Kernel for creating objects. More...
 
osStatus osKernelStart (void)
 Start the RTOS Kernel. More...
 
int32_t osKernelRunning (void)
 Check if the RTOS kernel is already started. More...
 
uint32_t osKernelSysTick (void)
 Get the RTOS kernel system timer counter. 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.
    • +
+

The function main is a special thread function that may be started at system initialization. In this case it has the initial priority osPriorityNormal.

+

When reaching main, it is necessary to:

+
    +
  1. Call osKernelInitialize() to initialize the CMSIS-RTOS Kernel
    2. +
  2. Setup device peripherals and create other RTOS objects using the os*Create functions.
    3. +
  3. Start the Kernel and begin thread switching by calling osKernelStart().
    4. +
+

Code Example

+
int main (void) {
+
osKernelInitialize (); // initialize CMSIS-RTOS
+
+
// initialize peripherals here
+
+
// create 'thread' functions that start executing,
+
// example: tid_name = osThreadCreate (osThread(name), NULL);
+
+
osKernelStart (); // start thread execution
+
}
+

Macro Definition Documentation

+ +
+
+ + + + +
#define osCMSIS   0x10002
+
+

Version information of the CMSIS-RTOS API whereby major version is in bits [31:16] and sub version in bits [15:0]. The value 0x10000 represents version 1.00.

+
Note
MUST REMAIN UNCHANGED: osCMSIS identifies the CMSIS-RTOS API version.
+ +
+
+ +
+
+ + + + +
#define osCMSIS_KERNEL   0x10000
+
+

Identifies the underlying RTOS kernel and version number. The actual name of that define depends on the RTOS Kernel used in the implementation. For example, osCMSIS_FreeRTOS identifies the FreeRTOS kernel and the value indicates the version number of that kernel whereby the major version is in bits [31:16] and sub version in bits [15:0]. The value 0x10000 represents version 1.00.

+
Note
CAN BE CHANGED: osCMSIS_KERNEL identifies the underlying RTOS kernel and version number.
+ +
+
+ +
+
+ + + + +
#define osFeature_MainThread   1
+
+

A CMSIS-RTOS implementation may support to start thread execution with the function 'main'.

+ +

CMSIS-RTOS RTX Setting: osFeature_MainThread is 1

+
Note
MUST REMAIN UNCHANGED: osFeature_xxx shall be consistent in every CMSIS-RTOS.
+ +
+
+ +
+
+ + + + +
#define osFeature_SysTick   1
+
+

A CMSIS-RTOS implementation may provide access to the RTOS kernel system timer.

+ +

CMSIS-RTOS RTX Setting: osFeature_SysTick is 1

+ +
+
+ +
+
+ + + + +
#define osKernelSystemId   "KERNEL V1.00"
+
+

Defines a string that identifies the underlying RTOS Kernel and provides version information. The length of that string is limited to 21 bytes. A valid identification string is for example, "FreeRTOS V1.00".

+
Note
MUST REMAIN UNCHANGED: osKernelSystemId shall be consistent in every CMSIS-RTOS.
+ +
+
+ +
+
+ + + + +
#define osKernelSysTickFrequency   100000000
+
+

Specifies the frequency of the Kernel SysTick timer in Hz. The value is typically use to scale a time value and is for example used in osKernelSysTickMicroSec.

+
See Also
osKernelSysTick
+
Note
Reflects the system timer setting and is typically defined in a configuration file.
+ +
+
+ +
+
+ + + + + + + + +
#define osKernelSysTickMicroSec( microsec)   (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
+
+

Allows you to scale a microsecond value to the frequency of the Kernel SysTick timer. This macro is typically used to check for short timeouts in polling loops.

+
See Also
osKernelSysTick
+
Parameters
+ + +
microsectime value in microseconds.
+
+
+
Returns
time value normalized to the osKernelSysTickFrequency
+ +
+
+

Function Documentation

+ +
+
+ + + + + + + + +
osStatus osKernelInitialize (void )
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osKernelInitialize shall be consistent in every CMSIS-RTOS.
+

Initialize of the RTOS Kernel to allow peripheral setup and creation of other RTOS objects with the functions:

+ +

The RTOS kernel does not start thread switching until the function osKernelStart is called.

+
Note
In case that the RTOS Kernel starts thread execution with the function main the function osKernelInitialize stops thread switching. This allows you to setup the system to a defined state before thread switching is resumed with osKernelStart.
+

Code Example

+
#include "cmsis_os.h"
+
+
int main (void) {
+
if (!osKernelRunning ()) { // if kernel is not running, initialize the kernel
+
if (osKernelInitialize () != osOK) { // check osStatus for other possible valid values
+
// exit with an error message
+
}
+
}
+
:
+
}
+
+
+
+ +
+
+ + + + + + + + +
int32_t osKernelRunning (void )
+
+
Note
MUST REMAIN UNCHANGED: osKernelRunning shall be consistent in every CMSIS-RTOS.
+
Returns
0 RTOS is not started, 1 RTOS is started.
+

Identifies if the RTOS kernel is started. For systems with the option to start the main function as a thread this allows you to identify that the RTOS kernel is already running.

+
Note
Interrupt Service Routines can call this function.
+

Code Example

+
#include "cmsis_os.h"
+
+
int main (void) { // program execution starts here
+
if (osKernelRunning ()) {
+
: // main is already a thread function
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
osStatus osKernelStart (void )
+
+
Returns
status code that indicates the execution status of the function.
+
Note
MUST REMAIN UNCHANGED: osKernelStart shall be consistent in every CMSIS-RTOS.
+

Start the RTOS Kernel and begin thread switching.

+
Note
When the CMSIS-RTOS starts thread execution with the function main this function resumes thread switching. The main thread will continue executing after osKernelStart.
+

Status and Error Codes
+

+
    +
  • osOK: the RTOS kernel has been successfully started.
    • +
  • osErrorISR: osKernelStart cannot be called from interrupt service routines.
    • +
+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
int main (void) {
+
if (osKernelInitialize () != osOK) { // check osStatus for other possible valid values
+
// exit with an error message
+
}
+
+
if (!osKernelRunning ()) { // is the kernel running ?
+
if (osKernelStart () != osOK) { // start the kernel
+
// kernel could not be started
+
}
+
}
+
}
+
+
+
+ +
+
+ + + + + + + + +
uint32_t osKernelSysTick (void )
+
+
Note
MUST REMAIN UNCHANGED: osKernelSysTick shall be consistent in every CMSIS-RTOS.
+
Returns
RTOS kernel system timer as 32-bit value
+

Get the value of the Kernel SysTick timer for time comparison. The value is a rolling 32-bit counter that is typically composed of the kernel system interrupt timer value and an counter that counts these interrupts.

+

This function allows the implementation of timeout checks. These are for example required when checking for a busy status in a device or peripheral initialization routine.

+
Note
Cannot be called from Interrupt Service Routines.
+

Code Example

+
#include "cmsis_os.h"
+
+
void SetupDevice (void) {
+
uint32_t tick;
+
+
tick = osKernelSysTick(); // get start value of the Kernel system tick
+
Device.Setup (); // initialize a device or peripheral
+
do { // poll device busy status for 100 microseconds
+
if (!Device.Busy) break; // check if device is correctly initialized
+
} while ((osKernelSysTick() - tick) < osKernelSysTickMicroSec(100));
+
if (Device.Busy) {
+
; // in case device still busy, signal error
+
}
+
// start interacting with device
+
}
+
+
+
+
+
+ + + + -- cgit