Skip to content

Architecture Decision Records

Jump to bottom
github-actions edited this page Nov 10, 2021 · 2 revisions

ADR 1: Record architecture decisions

Date: 2020-05-19

Status

Accepted

Context

We need to record the architectural decisions made on this project.

Decision

We will use Architecture Decision Records, as described by Michael Nygard.

Consequences

See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.

ADR 2: Use CMSIS-Pack for component distribution

Date: 2020-12-08

Status

Accepted

Context

We need to be able to pack and distribute software components under their sources and pre-compiled binary. The technology selected must also manage dependencies between components and ideally offer some support for configuring an individual component.

The component descriptor must be human readable (text-based) but may benefit from tools to generate/update it.

How popular a solution is, in terms of available package and community engagement is also a critical aspect as it directly impacts the efforts we will need to put in to achieve a viable adoption level.

The solution chosen must be developed in an open source and open governance model.

We do not mandate a pack registry. If one comes with the pack architecture it must allow for additional registry to fetch from.

It is intentionally left to the downstream distribution maintainers (Zephyr/Mbed) to manage compatibility of the components.

We evaluated some of the major solution currently available on the market:

  • Conan.io

    Using it for cortex-m class target is a stretch1 of the tool. The integration with the build system(s) requires changes in to the tool itself2 (which is not desired) provided that we do not have control over the technology.

  • CMSIS-Pack

    Mostly used within Keil uVision, this solution is already used by silicon partners to distribute some parts of their SDK. Although it is based on XML and requires tools to efficiently maintain it, it does provide all the necessary features. The CMSIS-Pack index counts 640 unique packages. Excluding device specific packages4 leaves around 70 packages, around 10 of which are nRF_packages and 37 are published either on http://www.keil.com/pack/ or https://github.com/MDK-Packs/Pack.

  • Yotta

    Yotta is a serious contender to CMSIS-Pack in terms of offered featured and available components. The dependency architecture and strategy is already well defined. Based on JSON it is easy to create, and maintain. CLI tools already exist, rendering the user experience rather fluid. A previous attempt at using Yotta in Mbed OS faced strong rejection mostly due to regular breakage in the ecosystem. It seems that those issues were not much due to problem in the tool itself but rather to bad practice around the semver rules. Yotta is not actively maintained. Yotta counts 314 unique packages (excluding the test packages test1, test2, …). Excluding the device specific packages leaves around 200 middleware and external peripheral drivers3.

  • lbuild

    Even though it presents some really interesting features around code generation and code configuration it does not have enough effective adoption to become a serious contender since it would mean starting the adoption process from scratch.

Note: The number of packages is highly influenced by how the packages are bundled (by family/subfamily or package hierarchy). Thus the number of devices supported is hard to evaluate and compare but can generally be considered large enough (yotta benefiting from mbed's large portability).

Decision

Considering the relative maturity, adoption, and the ability to contribute to these projects under an open source and open governance model, we've decided to use CMSIS-Pack as the starting point for Component specification.

The process of evolving CMSIS-Pack is strictly guided by approved User Stories​. Breaking backward compatibility is acceptable given a viable migration story is provided.

Consequences

As raised by partners during a previous meeting, there's room for improvement on CMSIS-Packs but nothing that cannot be addressed on upcoming iterations. The group acknowledges the risk that evolving CMSIS-Pack might be slower to address requirements that substantially deviate from today's concepts than starting from scratch​.

Partners and Arm parties specifically raised the following topics:

  • A system integrator may need a fix in a component and cannot wait for it to be upstreamed before shipping. A pack customisation model must be defined.
  • Authentication of component will become a serious concern as the ecosystem develops. We will need to define a strategy to address that.

Tools will need to be developed to ease the use of this technology. These will most probably need to evolve along with the specification in order to address feedback from the partners.

Ideally the technology (specification and tools) should go under an open-governance in order to ease contribution and accelerate its adoption.

Footnotes

1: https://github.com/conan-io/conan/issues/86#issuecomment-359483915 ↩︎ 2: https://github.com/conan-io/conan/pull/1494 ↩︎ 3: Extracted from mongodb's documents with db.modules.find({}, {"json.name": 1, _id: 0}).map((entry) => { return entry.json.name }).sort().filter((el,i,a) => {return i===a.indexOf(el) && !el.startsWith("test")}) and extra manual filtering to remove device specific packages. ↩︎ 4: Extracted from https://sadevicepacksprodus.blob.core.windows.net/idxfile/index.pidx. Excluding device specific packages by filtering out name ending with BSP and DFP plus some extra filtering to remove device from vendors such as HDSC or maxim that are not ending with those tags. ↩︎

ADR 3: Component source structure recommendations

Date: 2020-08-07

Status

Proposed

Context

Open-CMSIS-Pack encourages componentization of software with meaningful APIs. The componentization enables parallel development, maintenance and distribution of software components. These components can come from multiple vendors, therefore it is very useful to unify the structure of component source trees. In addition, unified source structure helps with,

  • Better maintenance of components
  • Easy navigation through source

Decision

The following directory structure is recommended for new Open-CMSIS-Pack components:

<component_name>
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── docs
├── examples
│   └── <example_name>
│       └── <example_name>.cpp
├── include
│   └── <component_name>
│       └── <component_name>.h
├── src
│   └── <component_name>.cpp
├── templates
│   └── <component_name>_template.cpp
└── tests
    └── <component_name>_test.cpp

Top level directory

Named after the component. It is recommended to use _ (underscore) as word separator instead of space(e.g., mbed_events).

Contribution

Contribution guidelines may be added to CONTRIBUTING.md. It may also specify the license under which contribution will be accepted.

License

Every component should contain license details. We recommend the following:

  • Single license

    The license text should be added to LICENSE.md. For example, to release a component under Apache 2.0, the full original Apache 2.0 license text should be in LICENSE.md.

  • Multiple licenses

    A LICENSE.md file with the following text:

    Unless specifically indicated otherwise in a file, files are licensed under
the Apache 2.0 license, as can be found in: LICENSE-apache-2.0.txt

    The full original Apache 2.0 license text in LICENSE-apache-2.0.txt.

    Each source header should start with copyright line, the SPDX identifier and the license header:

    Copyright (c) [First year]-[Last year], **Your Name or Company Here**
SPDX-License-Identifier: <License-name>
<License-header>

    In order to release the component under different license, update LICENSE.md with desired license details and add full license text to LICENSE-<license-name>.txt

  • Component with only binary

    A LICENSE.md file with the following text:

    Unless specifically indicated otherwise in a file, files are licensed under the Permissive Binary License, as can be found in LICENSE-permissive-binary-license-1.0.txt

    The full original Permissive Binary License 1.0 text in LICENSE-permissive-binary-license-1.0.txt.

Documentation

The README.md may contain brief introduction to the component and detailed documentation may be added under docs directory. Also, for components hosted on GitHub, this allows easily sharing the docs via GitHub pages, as GitHub pages can share either the root of a repo or its docs directory.

Examples

The examples directory may contain examples which demonstrate the use of the component. Each directory under examples should only contain one example. It is strongly recommended that examples are kept up-to-date and maintained such that they can be compiled and tested.

├── examples
│   └── example1
│   └── example2

Headers

All header files, including API header, should be added to include/<component_name> (e.g., include/mbed_events/mbed_events.h). This convention forces API consumers to add component name while including API headers which avoids header inclusion collisions (e.g., #include "mbed_events/mbed_events.h").

Sources

All source files should be added to the src directory.

Templates

Templates are application outlines which can act as a starting point for application developers. The only difference between examples and templates is that examples are complete and work out-of-the-box, whereas templates may not. If a component is providing a template then it should be added to the templates directory.

Tests

It's strongly recommended that every component contains at least unit test cases added in the tests directory.

Consequences

The component directory structure is recommended rather than enforced/mandated. Therefore it might be possible that existing components might not be migrated to the recommended directory structure. Due to the same reason, new components might not use the recommended directory structure.

ADR 4: Default Licenses for Open-CMSIS-Pack content

Date: 2020-11-24

Status

Accepted

Context

Open-CMSIS-Pack content (such as specs, code, etc) needs to be licensed properly so that it can be widely adopted. The default license shall be permissive to allow adoption for proprietary and commercial use, free from copy-left obligations.

A couple of well known Open Source Licenses have been taken into account:

Decision

By default all publicly published Open-CMSIS-Pack software is to be licensed under the Apache v2.0 license. However, Open-CMSIS-Pack may reuse software already licensed under another license, provided the license is permissive in nature and compatible with Apache v2.0. Documentation shipped alongside the code shall be licensed under the same license as the code.

Specifications are to be licensed under the Creative Commons CC-BY-SA 4.0 license (Creative Commons Attribution-ShareAlike 4.0 International Public License).

All contributions to software and documents are licensed by contributors under the same license model as the software/document itself (ie. inbound == outbound licensing).

Consequences

The Apache License 2.0 grants permissive use to everybody, including adoption for proprietary and commercial use. It does not contain any copy-left obligations.

The Creative Commons CC-BY-SA 4.0 permissive use to everybody, including adoption for proprietary and commercial use. It does not contain any copy-left obligations.

5. Extend Open-CMSIS-Pack for per component changelogs

Date: 2021-05-11

Status

Accepted

Context

Open-CMSIS-Pack specification supports recording changelogs as part of the releases section. Hence one cannot easily deduce which changes apply to which component(s).

Decision

Follow the approach already used for <conditions> in the current Pack Description using references:

  • add optional section <changelogs> on the top level of the format
  • add one or more child elements <changelog> to <changelogs> with attributes:
    • id (required) - a unique name which is used by components to associate itself with a changelog
    • name (required) - the relative path to the changelog file
    • type (optional) - mime-type of the changelog file, defaults to text/plain;charset=UTF-8
    • default (optional) - the default changelog is automatically associated with all components/apis, default to false
  • add optional attribute changelog to <component> element.
  • add optional attribute changelog to <api> element.
  • add optional attribute changelog to <bundle> element.

Consequences

  • Complexity of package description increases
  • the default mechanism allows to specify a single changelog for all components of a pack conveniently.
  • Validation tool is required to test:
    • for each <changelog> that name is specified, unique (within pdsc) and file exists
    • a maximum of one changelog has attribute default="true" set
    • for each <component> that attribute changelog unique ID exists (within pdsc)
    • for each <api> that attribute changelog unique ID exists (within pdsc)
    • for each <bundle> that attribute changelog unique ID exists (within pdsc)
  • Pack Manager requires extension
    • display changelog information per component
Clone this wiki locally