Including csolution/cproject examples in Packs

[willlordarm]

Example applications are currently included in packs and referenced using the <examples> element in the .pdsc file. An environment attribute is used to specify which toolchain/IDE the example is designed for e.g.

<project>
  <environment name="uv" folder="./ARM" load="ARM/Blinky.uvproj"/>
  <environment name="iar" folder="./IAR" load="IAR/Blinky.ewarm" />
</project>

Source

As far as I can see the environment name attribute is a string, meaning that uv, iar etc are used as conventions rather than part of a fixed taxonomy.

Pack vendors should be encouraged to specify their examples as csolution/cproject in future. To do so we should establish a convention for the environment name (could be csolution or cmsis) and the behaviour we expect (e.g. these will be ignored in uVision).

[ReinhardKeil]

A potential way would be, however we should wait here until we have implementations. No real extension needed as this feature is already there.

<project>
  <environment name="csolution" folder="./ARM" load="ARM/Blinky.csolution.yml"/>
  <environment name="cprj" folder="./IAR" load="IAR/Blinky.cprj" />
</project>

[willlordarm]

Thanks @ReinhardKeil. Would existing implementations (MDK, IAR etc) simply ignore any name attributes that are not relevant to them?

[jkrech]

That's the conceptual idea, that tools scan for environment name attribute to identify examples to be supported. Alternatively tools may scan through all environment tags and rely on project file extension to see whether or not the format can be "imported"/"converted" by a tool, even if it is not the primary format.

[ReinhardKeil]

Yes that should be the case. If they don't it's a bug.

[fred-r]

Did not we say also that a layer is way to deliver a preconfigured project ?

So should we say that:

1. example is to deliver "non configured projects"
2. layer can be used to deliver a partial project (really a layer) or a fully preconfigured project ?

[jkrech]

I am not sure where the confusion started. In my view an "example" is a fully specified, fully configured solution/project that builds out of the box and is targeted to a specific board. A layer to me is always a partial, incomplete project which needs to be referenced by a project which will add the "missing" bits locally or via referencing additional layers. The components included in a layer are pre-configured for a limited set of use-cases/configured capabilities. The configuration options in the layer can still be tailored and modified for a project. A board layer is special in the sense that it is specific to a board and aims to cover all software aspects which are board specific.

[fred-r]

My bad, I am not clear enough.

I agree that layers are incomplete preconfigured projects to be used in an application.

But if you look at the proposal here: https://github.com/ReinhardKeil/IoT_App/blob/main/ProposedStructure/Proposals.md#changes-to-the-pdsc-file

The pdsc "container" for layers can also contain projects:

The <csolution> element could also contain different types with:

cproject a generic example projects
cimage a pre-build image that should be added to a csolution
clayer a software layer

[jkrech]

@fred-r thanks for clarifying your concern. @ReinhardKeil what exactly is your definition of a "generic example project" and how is it different from an example described in the section of the pdsc rather than .

My reading of the proposal is, that cproject is the next higher level of abstraction compared to a layer. As a user you could chose from a list of cprojects for the active target+build-type of the loaded csolution to be added to the solution. E.g. I could imagine a cproject covering a ready to build Secure Firmware Image for a certain board could be copied directly to my solution.

[tcsunhao]

For single project example, it is not difficult to image that including could be like

<project>
  <environment name="csolution" folder="./ARM" load="ARM/Blinky.csolution.yml"/>
</project>

What about multi-project example? A csolution may contain 2 projects which is the index.

[ReinhardKeil]

I have used the term "generic example" to describe projects that can be targeted to a specific board by using a "board" layer.

[tcsunhao]

I see proposal Add element to *.PDSC format, it gives a way to include projects/images/softwarelayers in pdsc file for tools to index and use. I am not sure whether it helps on this topic Or maybe it is because I don't know how to use them for the time being.

Our request is that we need to provided configured/prepared example data in pdsc with csolution for each example as we are doing it today(with name="uv", name="iar"), so that our IDE and tool can get all data for each example straightly to work/build.

For an example, a csolution file is the final file containing all data to construct it. cproject file is not enough because it is without target data. So, vendor's tool like IDE needs to get an index to a csolution file for an example to load and construct example.

For a single project example, just a single csolution file is needed, it could be like

    <example name="hello_world" folder="demo_apps/hello_world" doc="readme.txt">
      <description>The HelloWorld demo prints the "Hello World" string to the terminal using the SDK UART drivers and repeat what user input. The purpose of this demo is to show how to use the UART, and to provide a simple project for debugging and further development.</description>
      <board name="FRDM-K64F" vendor="NXP" Dvendor="NXP:11"/>
      <project>
        <environment name="uv" load="mdk/hello_world.uvprojx"/>
        <environment name="iar"  load="iar/hello_world.ewp"/>
        <environment name="csolution" load="hello_world.csolution.yml"/>
      </project>
      <attributes/>
    </example>

For a multi-project example which share the same csolution file, like hello_world.csolution.yml contains hello_world_s.cproject.yml and hello_world_ns.cproject.yml Then in the "example" element which is for single project like hello_world_s, should we provide like?

    <example name="hello_world_s" folder="trustzone_examples/hello_world/cm33_core0/hello_world_s" doc="readme.txt">
      <description>The Hello World demo application provides a sanity check for the new SDK build environments and board bring up. This demo application also utilizes TrustZone, so it demonstrates basic techniques for TrustZone applications development. This is secure part of the application.</description>
      <board name="LPCXpresso55S69" vendor="NXP" Dvendor="NXP:11"/>
      <project>
        <environment name="uv" load="mdk/hello_world_s.uvprojx"/>
        <environment name="iar" load="iar/hello_world_s.ewp"/>
        <environment name="csolution" load="hello_world.csolution.yml" />  
      </project>
      <attributes/>
    </example>

The hello_world.csolution.yml containing 2 projects which is "load" in the single hello_world_s which means redundant data for hello_world_s. And a hello_world_s.cproject.yml is not enough because there is no target data inside it. Of course I believe our IDE can figure out hello_world_s out of hello_world.csolution.yml, but is it the recommended way?

[ReinhardKeil]

@tcsunhao I believe that #134 gives you the feature that you expect. We are in the process to create some examples so that we can demo it.

[jkrech]

@tcsunhao how about an option to specify an additional attribute in environment that specifies the context to be active after loading the solution? Would that be sufficient to help the IDE to activate the "right" project?

[tcsunhao]

@jkrech , I think inside hello_world.csolution.yml

  projects:
    - project: ./hello_world_ns/hello_world_ns.cproject.yml
    - project: ./hello_world_s/hello_world_s.cproject.yml

Our IDE can search to get the hello_world_s.cproject.yml related to example name="hello_world_s". However, I am waiting demos as @ReinhardKeil comment. Thanks.

[ReinhardKeil]

We have specified environment="cmsis" in https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_examples_pg.html#element_example_project_env. This allows to distribute csolution projects. It is used for example here: https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_examples_pg.html#element_example_project_env

But we take the point that the documentation about this could be clearer.

[jkrech]

Looking at recent packs from NXP, I see that "csolution" is used as <environment> name and not "cmsis". In light of that we should update the specification and replace "cmsis" with "csolution" to indicate an example project in the CMSIS solution project format.

[ReinhardKeil]

CMSIS6 is using on some places <environment name="cmsis"/>, for example here https://github.com/ARM-software/CMSIS-View/blob/main/ARM.CMSIS-View.pdsc#L126

I suggest:

• Add <environment name="csolution"/> making it identical to <environment name="cmsis"/>
• Future recommendation is to use <environment name="csolution">
• <environment name="cmsis"> should be deprecated over time.

Note: we could be perhaps more pragmatic as only CMSIS-View and CMSIS-Compiler pack contains <environment name="cmsis">. We can therefore replace this with <environment name="csolution">.

[jkrech]

We have been updating the examples in Arm Packs (CMSIS-View, CMSIS-Compiler) and fixed in the spec.