CMSIS++ is a portable, vendor-independent hardware abstraction layer intended for C++/C embedded applications, designed with special consideration for the industry standard Arm Cortex-M processor series.
The original Arm/Keil name stands for Cortex Microcontroller Software Interface Standard, and the CMSIS++ design inherits the good things from Arm CMSIS, but goes one step further and ventures into the world of C++; as such, CMSIS++ is not a C++ wrapper running on top of the Arm CMSIS APIs, but a set of newly designed C++ APIs, with C APIs supported as wrappers on top of the native C++ APIs.
The first iteration of CMSIS++ was a direct rewrite in C++ of Arm CMSIS, but later most of the definitions were adjusted to match the POSIX IEEE Std 1003.1, 2013 Edition and the ISO/IEC 14882:2011 (E) – Programming Language C++ standards.
As such, CMSIS++ RTOS API is no longer a wrapper over Keil RTX (as Arm CMSIS unfortunately was), but a wrapper over standard threads and synchronisation objects.
Although fully written in C++, the CMSIS++ RTOS API, initially implemented on top of the FreeRTOS scheduler, and accessible via the C wrapper, was the first non-Keil RTOS that passed the recently released CMSIS RTOS validation suite.
There are many components in the original CMSIS, but the major ones that benefit from C++ are RTOS and Drivers. Since everything revolves around the RTOS API, the C++ RTOS API was the first CMSIS++ API defined and is presented here in more detail.
Under the CMSIS++ RTOS APIs umbrella there are actually several interfaces, two in C++, two in C and one internal, in C++. The relationships between them is presented below:
This is the native RTOS interface, implemented in C++, and providing access to the entire RTOS functionality.
The classes are grouped under the os::rtos namespace, and, to access them, C++ applications need to include the <cmsis-plus/rtos/os.h> header.
Objects can be instantiated from native classes in the usual C++ way, and can be allocated statically, dynamically on the caller stack or dynamically on the heap.
Inspired by the POSIX threads usage model, all CMSIS++ native objects can be instantiated in two ways:
For example, to create a thread with default settings, only the pointer to the thread function and a pointer to the function arguments need to be specified, while a thread with custom settings can also have a custom priority, a static stack, and possibly other custom settings.
Here is a short example with a thread that counts 5 seconds and quits:
#include <cmsis-plus/rtos/os.h> #include <cmsis-plus/diag/trace.h> using namespace os; // Define the thread function. // Native threads can have only one pointer parameter. void* func(void* args) { for (int i = 0; i < 5; i++). { trace::printf("%d sec\n", i); // Sleep for one second. rtos::sysclock::sleep_for(rtos::clock_systick::frequency_hz); } return nullptr; } // In CMSIS++, os_main() is called from main() // after initialising and starting the scheduler. int os_main(int argc, char* argv[]) { // Create a new native thread, with pointer to function and no arguments. // The thread is automatically destroyed at the end of the os_main() function. rtos::thread th { func }; // Wait for the thread to terminate. th.join(); trace::puts("done."); return 0; }
The native CMSIS++ thread is basically a POSIX thread, with some additional functionality.
Similarly, synchronisation objects can be created with the usual C++ approach; for example a piece of code that uses a mutex to protects a counter looks like this:
#include <cmsis-plus/rtos/os.h> // Protected resource (a counter). typedef struct { int count; } resource_t; // Alloc the resource statically. resource_t resource; // Define a native mutex to protect the resource. rtos::mutex mx; void count(void) { mx.lock(); // Not much here, real applications are more complicated. resource.count++; mx.unlock(); }
The CMSIS++ ISO C++ Threads API is an accurate implementation of the ISO C++ 11 standard threads specifications.
With the ISO standard threads defined as wrappers over POSIX threads, and with the CMSIS++ native threads functionally compatible with POSIX threads, the implementation of the CMSIS++ ISO threads was quite straightforward.
The classes are grouped under the os::estd namespace, and, to access them, C++ applications have to include headers from the cmsis-plus/estd folder, like <cmsis-plus/estd/thread>. The namespace std:: and the standard header names (like <thread>) could not be used, to avoid clashes with system definitions when building CMSIS++ applications on POSIX host systems. The e in estd stands for embedded, so the namespace is dedicated to embedded standard definitions.
A similar example using the standard C++ threads:
#include <cmsis-plus/estd/thread> #include <cmsis-plus/estd/chrono> #include <cmsis-plus/diag/trace.h> using namespace os; using namespace os::estd; // Use the embedded version of 'std::'. // Define the thread function. // Thanks to the magic of C++ tuples, standard threads // can have any number of arguments, of any type. void* func(int max_count, const char* msg) { for (int i = 0; i < max_count; i++). { trace::printf("%d sec, %s\n", i, msg); // Sleep for one second. <chrono> is very convenient, // notice the duration syntax. this_thread::sleep_for (1s); } return nullptr; } // In CMSIS++, os_main() is called from main() // after initialising and starting the scheduler. int os_main(int argc, char* argv[]) { // Create a new standard thread, and pass two arguments. // The thread is automatically destroyed at the end of the os_main() function. thread th { func, 5, "bing" }; // Wait for the thread to terminate. th.join(); trace::puts("done."); return 0; }
Most of the goodies of the C++ 11 standard can be used, for example RAII mutex locks, condition variables, lambdas:
#include <cmsis-plus/estd/mutex> #include <cmsis-plus/estd/condition_variable> using namespace os; using namespace os::estd; // Protected resource (a counter and a limit). typedef struct { int count; int limit; } resource_t; // Alloc the resource statically. resource_t resource { 0, 10 }; // Define a standard mutex to protect the resource. mutex mx; // Define a condition variable to notify listeners and detect limits. condition_variable cv; // Increment count and notify possible listeners. void count(void) { unique_lock<mutex> lck(mx); // Enter the locked region. resource.count++; cv.notify_one(); // No need to explicitly unlock, done automatically. } // Return only when count reaches the limit. void wait_for_limit() { unique_lock<mutex> lck(mx); // Enter the locked region. cv.wait(lck, []{ return (res.count >= res.limit); } ); }
Although fully written in C++, CMSIS++ also provides a C API, to be used by C applications. Yes, that's correct, plain C applications can use CMSIS++ without any problems. Only that function names are a bit longer and some of the C++ magic (like running the constructors and the destructors) needs to be done by hand, but otherwise the entire functionality is available.
The C API is defined in the <cmsis-plus/rtos/os-c-api.h> header.
The same simple example that counts 5 seconds and quits, in C would look like:
#include <cmsis-plus/rtos/os-c-api.h> #include <cmsis-plus/diag/trace.h> // Define the thread function. // Native threads can have only one pointer parameter. void* func(void* args) { for (int i = 0; i < 5; i++). { trace_printf("%d sec\n", i); // Sleep for one second. os_sysclock_sleep_for(OS_INTEGER_SYSTICK_FREQUENCY_HZ); } return NULL; } // In CMSIS++, os_main() is called from main() // after initialising and starting the scheduler. int os_main(int argc, char* argv[]) { // Manually allocate space for the thread. os_thread_t th; // Initialise a new native thread, with function and no arguments. os_thread_create(&th, NULL, func, NULL, NULL); // Wait for the thread to terminate. os_thread_join(&th, NULL); // Manually destroy the thread. os_thread_destroy(&th); trace_puts("done."); return 0; }
Even more, the CMSIS++ C wrapper also implements the original Arm CMSIS API. This is a full and accurate implementation, since this API already passed the Arm CMSIS RTOS validation test.
To access this API, include the <cmsis_os.h> header provided in the CMSIS++ package.
#include <cmsis_os.h> #include <cmsis-plus/diag/trace.h> // Define the thread function. // Arm CMSIS threads can have only one pointer parameter. void func(void* args) { for (int i = 0; i < 5; i++). { trace_printf("%d sec\n", i); // Sleep for one second. osDelay(osKernelSysTickFrequency); } // Arm CMSIS threads can return, but there is // no way to know when this happens. } // The unusual way of defining a thread, specific to CMSIS RTOS API. // It looks like a function, but it is not, it is a macro that defines // some internal structures. osThreadDef(func, 0, 1, 0); // In CMSIS++, os_main() is called from main() // after initialising and starting the scheduler. int os_main(int argc, char* argv[]) { // Initialise a new Arm CMSIS thread, with function and no arguments. osThreadCreate(osThread(func), NULL); // Since Arm CMSIS has no mechanism to wait for a thread to terminate, // a more complicated synchronisation scheme must be used. // In this test just sleep for a little longer. osDelay(6 * osKernelSysTickFrequency); trace_puts("done."); return 0; }
The entire CMSIS++ RTOS interface is fully documented in the separate site, available in the project web:
In addition to the RTOS APIs, CMSIS++ also includes:
CMSIS++ is still a young project, and many things need to be addressed, but the core component, the RTOS API, is pretty well defined and awaiting for comments.
For now it may not be perfect (as it tries to be), but it definitely provides a more standard set of primitives, closer to POSIX, and a wider set of APIs, covering both C++ and C applications; at the same time it does its best to preserve compatibility with the original Arm CMSIS APIs.
Any contributions to improve CMSIS++ will be highly appreciated.
CMSIS++ is an open source project, maintained by Liviu Ionescu.
The main source of information for CMSIS++ is the project web.
The Git repositories and all public releases are available from GitHub.
For questions and discussions, please use the CMSIS++ section of the GNU Arm Eclipse forum.
For bugs and feature requests, please use the GitHub issues.
I welcome this idea. I may come with comments on architecture and/or design, once I look through (and possibly try) the specification and code.
For now I have remarks on licence. I think LGPL is not suitable for embedded systems. Most of Cortex-M software is delivered as a firmware of a product, and application dedicated to a specific hardware. Therefore providing object code brings no much benefit.
From my viewpoint the best would be to use the same licence of original CMSIS. However, if you feel that C++ CMSIS source itself should be copylefted, I would suggest GPL with linkage exception. Example of such licence: http://ecos.sourceware.org/license-overview.html.
Regards
Ilija