CMSIS RTOS v2 projects - confusion about headers: cmsis_os.h or cmsis_os2.h ?

NickO · ‎2025-10-02

Hi

In the past 6 months, I created a project for an STM32H755. For middleware, I selected CMSIS RTOS v2 (using FreeRTOS underneath).

I noted that the header file is cmsis_os.h, which at first seemed wrong. I (maybe naively) asked the "AI", and with it's usual confident tone, suggested I change them (however, this is hard to maintain if you change your .ioc file).

Looking at past posts on these forums, and inside cmsis_os.h, I confirmed that cmsis_os2.h is indeed included within it (despite the AI not finding this).

So, I challenged the "AI", stating what I had found. Of course, in it's somewhat complimentary way, it agreed with me, but still insisted that if I am using entirely v2 APIs, I should change the headers.

Of course, such responses derive from human content written elsewhere, and I fear it may not backed by actual facts. I have left the headers as they are for now. I have a bad feeling about changing them as ST might have reasons to do things the way they have.

So, is it good practise (or a bad idea) to change all #include "cmsis_os.h" to "cmsis_os2.h" ?

Khaled_DHIF · ‎2025-10-02

Hello @NickO ,

In recent and upcoming versions of STM32CubeMX, "#include cmsis_os2.h" is now used directly for CMSIS-RTOS v2 projects.

For older projects or STM32 families, cmsis_os.h is still common and remains fully compatible, as it internally includes the newer cmsis_os2.h.
For new projects, simply follow the header file generated by CubeMX—use cmsis_os2.h if that’s what is provided.
Both headers are valid, but cmsis_os2.h is becoming the new standard for CMSIS-RTOS v2 development.

Kind regards,

DHIF Khaled

Please mark my answer as best by clicking on the “Accept as solution" button if it fully answered your question. This will help other users find this solution faster.

View solution in original post

Andrew Neil · ‎2025-10-02

@NickO wrote:
I noted that the header file is cmsis_os.h, which at first seemed wrong.

Was this actually causing any problems, or is this just a semantic concern about the name?

A complex system that works is invariably found to have evolved from a simple system that worked.
A complex system designed from scratch never works and cannot be patched up to make it work.

NickO · ‎2025-10-02

No problems. It's more a safety issue for me, and knowing why things are the way they are.

On the one hand, I don't want to accidentally mix v1 and v2 APIs if that might cause a problem (which is sometimes suggested).
Equally, I don't feel informed enough to change the headers just because some AI robot says I should.

Andrew Neil · ‎2025-10-02

It's not uncommon for stuff like this to include backwards compatibility with previous versions.

If it doesn't cause any problems, I'd leave it.

I don't think that the name "cmsis_os.h" necessarily implies any specific version?

A complex system that works is invariably found to have evolved from a simple system that worked.
A complex system designed from scratch never works and cannot be patched up to make it work.

NickO · ‎2025-10-02

Agreed. I intend to leave it unless there is some official guidance that says I should change it (to prevent myself or future developers using an old API that leads to unpredictable problems).

As cmsis_os2.h does imply a version of course, there are forum posts out there complaining the issue I raised is due to a bug (accompanied by strange "workarounds" which all make me nervous). All this seeds doubt and uncertainty, not helped by the AI of course, but I suspect ST know what they are doing and it's entirely intentional.

Thank you for responding.

Andrew Neil · ‎2025-10-02

@NickO wrote:
I suspect ST know what they are doing and it's entirely intentional.

You would hope so ...

Also, as it's an ARM thing, it might be worth asking ARM:

https://community.arm.com/support-forums/f/operating-systems-forum

A complex system that works is invariably found to have evolved from a simple system that worked.
A complex system designed from scratch never works and cannot be patched up to make it work.

Jessica_Alleen · ‎2025-10-02

From my experience, it's usually safer not to change the headers manually unless there is an official note in the documentation. Since cmsis_os.h already includes cmsis_os2.h, it looks like ST made this intentional for backward compatibility. Unless you see real conflicts or errors, leaving it as is should avoid unnecessary issues.

Andrew Neil · ‎2025-10-02

@Jessica_Alleen wrote:
it looks like ST made this intentional

Could even have been ARM ...

A complex system that works is invariably found to have evolved from a simple system that worked.
A complex system designed from scratch never works and cannot be patched up to make it work.

Pavel A. · ‎2025-10-02

Hi,

cmsis_os2.h is for Version 2 of the CMSIS-RTOS API. File cmsis_os.h is for version 1.

Version 2 is *not* a drop-in replacement of v.2, so if you have code written for v.1 and want to upgrade to v.2, you have to review and fix incompatibilities. AI usually are great for this task, but yours seems to be broken :(

If you are new to the CMISIS RTOS, you may want to start with version 2 - or bypass the wrappers and directly work with FreeRTOS. After all, it is not so horrible as some say. If the AI robot makes trouble, you can find real live humans here.

Khaled_DHIF · ‎2025-10-02

Hello @NickO ,

In recent and upcoming versions of STM32CubeMX, "#include cmsis_os2.h" is now used directly for CMSIS-RTOS v2 projects.

For older projects or STM32 families, cmsis_os.h is still common and remains fully compatible, as it internally includes the newer cmsis_os2.h.
For new projects, simply follow the header file generated by CubeMX—use cmsis_os2.h if that’s what is provided.
Both headers are valid, but cmsis_os2.h is becoming the new standard for CMSIS-RTOS v2 development.

Kind regards,

DHIF Khaled

Please mark my answer as best by clicking on the “Accept as solution" button if it fully answered your question. This will help other users find this solution faster.