Layers Interfaces

[fred-r]

Can you please elaborate a bit more about this element: https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/docs/Manual/Overview.md#layer-interface-defintions

This is quite new for me, can you clarify ? How is an interface specified ? Via components ? is there a link with the notion of API ?

[jkrech]

Hi Fred, at this point you can read this as list of abstract identifiers with a direction (consumed vs. provided) that a user has defined. The underlying task is identical to finding "compatible" components. This means we are looking for two component where on component implements/provides an API and another component which calls/consumes that API. At a layer level where there is multiple components things become a bit more complicated and a layer may have multiple APIs that it consumes and provides. In case we only allow pairing two layers, two layers are compatible if all consumed APIs are satisfied by the corresponding provided APIs. On top of this we are seeing a need for provided and consumed features that are not immediately covered by APIs. Did you take a look at https://github.com/MDK-Packs/CB_Lab4Layer where layers have been identified by names: App=AWS_MQTT_Demo Board=IMXRT1050-EVKB Module=WizFi360 Socket=WiFi RTOS=FreeRTOS Obviously this only works if the actual APIs being used e.g. for all RTOS layer implementations - in this case CMSIS-RTOS2. So in order for a tool to find "compatible" layers, we need to specify e.g. associated APIs. I am interested in hearing your ideas.

[fred-r]

Thanks Joachim. I am not very familiar with the concept of API already present in the spec: https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_apis_pg.html#element_api

Can we specify that we provide and consume API with the current spec ? I find only reference to Capiversion.

Maybe this is the first step I should take ?

Then Interfaces are "similar ideas" but at layer level ? So interfaces are in fact features (I would call it services ?) that a layer can:

• either provide
• or consume

How to declare it ?

And I am not sure it is so close to API. I mean an API is a service but also the way to provide it. Is the interface also defining the way to provide it ? I guess so, otherwise it becomes complicated to link compatible layers.

Thanks & Regards, Fred

[jkrech]

Let's take the example of CMSIS-Driver. These are public APIs specified as part of the ARM.CMSIS pack.

    <api Cclass="CMSIS Driver" Cgroup="USART" Capiversion="2.4.0" exclusive="0">
      <description>USART Driver API for Cortex-M</description>
      <files>
        <file category="doc" name="CMSIS/Documentation/Driver/html/group__usart__interface__gr.html" />
        <file category="header" name="CMSIS/Driver/Include/Driver_USART.h" />
      </files>
    </api>

The API header file Driver_USART.h is associated with the Cclass="CMSIS Driver" and Cgroup="USART" and the Capiversion="2.4.0".

Any component matching these attributes must implement this API. Therefore it does not even include this header file, but relies on the RTE system to add the include path to the matching version of the <api> from the pack specifying the public API.

If a component depends on a CMSIS compliant USART driver it adds <require Cclass="CMSIS" Cgroup="USART" Capi="2.4.0"> to its condition and RTE will search for a compatible component based on this information.

[fred-r]

I still have difficulties to understand how features rely to API.

A feature is something defined at layer level ? And it is associated to [1..N] APIs ? An API can be explicitly and API but maybe for people not using the it may be a Cclass/Cgroup/[Capiversion] combination ?

So

Layer ---> [1..N] provided interfaces --> [1..N] APIs ---> [1..N] consumed interfaces

And the tool looks for layers providing the consumed interfaces ? But as there is no central repository of interfaces then i guess the toll must go down to API level to make sure it is really matching ?

[jkrech]

Creating/maintaining a central repository of interfaces may be something we need to explore. Any ideas or existing examples we could learn from? Or do you believe going down to the API level will be sufficient?

[fred-r]

In fact, I wonder why the concept of provided and consumed interfaces should remain at layer level. Even a component can provide and consume an interface.

I agree that it might collide with the concept of API but to me it is different. The API would define "formally" what we provide (function names, parameters).

The interfaces would describe more a service. So we may say : I need an UART driver. This interface could be provided by a ST component or an NXP component or a CMSIS component. If the application is mutli-vendor compatible then it can adapt to ST API or NXP APi or CMSIS API. if not, then, if we want to indicate we need a precise API form then we can also precise the exact API we want.

What do you think ?

[fred-r]

Clarified by @ReinhardKeil : the interface concept is a HW notion, it does not imply the SW API.

[ReinhardKeil]

@fred-r the node interface: is no longer limited to *.clayer.yml. I did also improve the description https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/docs/Manual/YML-Input-Format.md#interface.

I suggest we open new issues to discuss it further.