CMSIS RTOSv2 API: migration path from cmsis_os.h to cmsis_os2.h about cmsis_5

[ReinhardKeil]

This is actually possible. You can use both API's at the same time in one project and migrate overtime to API2. You just need to select both CMSIS:RTOS:Keil RTX5 and CMSIS:RTOS2:Keil RTX5 in the project.

We will explain this better in the documentation

[ilg-ul]

You can use both API's at the same time

I did not try this in a project, but visually inspecting the header files does not confirm your statement, it looks like you use functions with the same name but with different prototypes in the two headers, which, in a language without namespaces, like C, is not possible.

for example, in RTOSv1 you have:

osStatus osThreadYield (void);

and in RTOSv2 you have:

osStatus_t osThreadYield (void);

with osStatus completely different from osStatus_t.

ideally, for an easy migration, you should be able to include both headers in a file, work on the changes, and remove the legacy header when ready, but with different prototypes, the compiler should complain.

the second choice would be to be able to include the old header in one file and the new header in another file, but having functions with the same name in the two implementations will make the linker complain.

I'm afraid your design does not provide a convenient migration path from cmsis_os.h to cmsis_os2.h.

the label DONE attached to this ticket is not accurate.

[RobertRostohar]

with osStatus completely different from osStatus_t

Not completely different:
osStatus is defined as int32_t and osStatus_t as enum.

This allows mixing old and new API if needed during migration.

[ilg-ul]

did you manage to include both versions in the same project?

[RobertRostohar]

Yes,. a simple example which shows just compilation (no functionality):

#include "cmsis_os.h"

static osStatus    Status0;     // Old API
static osStatus_t  Status;      // New API

void test (void) {

  Status  = osThreadYield();
  Status0 = osThreadYield();
  switch (Status0) {            // Old API
    case osOK:
    case osEventSignal:
    case osEventMessage:
    case osEventMail:
    case osEventTimeout:
    case osErrorOS:
    case osErrorTimeoutResource:
    case osErrorResource:
    case osErrorParameter:
    case osErrorNoMemory:
    case osErrorISR:
    case osErrorISRRecursive:
    case osErrorPriority:
    case osErrorValue:
      break;
    default:
      break;
  }
  switch (Status) {             // New API
    case osOK:
    case osError:
    case osErrorTimeout:
    case osErrorResource:
    case osErrorParameter:
    case osErrorNoMemory:
    case osErrorISR:
      break;
    default:
      break;
  }
}

[ilg-ul]

sorry, but I'm not able to follow you. how can you have two version of the osThreadYield() function in the same project, one from v1 and one from v2?

[RobertRostohar]

Function and it's implementation is the same (V2) however it can be used with V1 user code.

[ilg-ul]

Function and it's implementation is the same

are you sure? how can it be the same if each version returns different values? for example the v1 version returns 0x82 if called from an ISR, and the v2 version returns -6 in the same case.

or, in my case, I have a C wrapper that defines all v1 functions on top of CMSIS++, and apparently I have to add a separate wrapper for the v2 functions; I don't see how it can be the same if functions with the same name behave differently in the two versions.

[RobertRostohar]

osErrorISR is defined in cmsis_o2.h as -6. Updated cmsis_os.h does not define it at all when using it in V2 environment. While osErrorISR value has changed between implementations the user code which uses the define should have no issues unless the value was used directly as a number.

Updated cmsis_os.h only defines incompatible values (osEventXxx) and maps different names (ex: osErrorOS vs osError). This insures the compatibility for majority of cases. There are however minor incompatibilities (ex: V2 implementation will return osErrorParameter when V1 returned osErrorValue).

Compatibility module handles the incompatible functions (Create, functions that returned osEvent …)

[ilg-ul]

While osErrorISR value has changed between implementations the user code which uses the define should have no issues unless the value was used directly as a number.

hmmm...

in #1 we had a dispute on priority numbers, and you justified the design by the need to preserve compatibility with binary libraries.

now I debate your new solution exactly with your own arguments: how can you use binary libraries based on v1 in a project migrated to v2?

[RobertRostohar]

#1 was about binary compatibility between different implementations for the same API version.

There is no binary compatibility between V1 and V2 project. Code needs to be recompiled when migrating.

[ilg-ul]

For completeness, I think that mandating for binary compatibility between different implementations for the same API version is too limiting and should be avoided; source code compatibility should be enough and binary distributions should be accompanied by a source file to be compiled with the actual implementation header.

[ReinhardKeil]

we have verified that migration works in practice and the process is described here:
http://arm-software.github.io/CMSIS_5/RTOS2/html/os2MigrationGuide.html#MigL2

CMSIS-RTOS1 was not binary compatible and we never claimed that as every implementation could have a different cmsis_os.h.

[ilg-ul]

ok, if you handled all details, it should be ok.

[ReinhardKeil]

no further activity