readme.rst

Trusted Firmware binary repository
==================================

.. section-numbering::
    :suffix: .

.. contents::

This repository hosts redistributable binary components that are needed with
certain platform ports of trustedfirmware.org projects. All contributions to
this repository must follow the rules and process laid out below as well as
individual contribution guidelines of the respective project. License terms for
individual binaries are described in the accompanying ``release-notes.rst``.

Scope
-----

This repository is intended for cases where it's not possible to fully
open-source a trustedfirmware.org project platform port. Binary components
should be as minimal as possible, augmenting the more significant, open-source
part of the platform port. Binary components that contain all meaningful
functionality of a platform port and are merely linked into a boilerplate shell
of open-source code will not be accepted.

The trustedfirmware.org Technical Steering Committee or Governing Board will
decide whether to host binary components in this repository on a case by case
basis. Applications for inclusion can be sent to tsc@lists.trustedfirmware.org.

Binary components must always be associated with a specific platform port. No
generic code (i.e. any code outside the ``plat/<vendor>`` directory) may depend
on a binary component.

License
-------

All binary components must be accompanied by a distribution license. The license
should:

#. be irrevocable

#. be royalty-free

#. grant usage rights for both copyright and patents covering the binary

#. allow unlimited redistribution under the same terms

#. not restrict the ability to publish test results from the platform port

To simplify legal review and avoid potential concerns, we recommend that the
license should be as short and simple as possible. Special terms should be
limited to what is absolutely necessary. The `Permissive Binary License`_
adapted from the Arm Mbed project is a good example of a license that fulfills
these requirements, and contributors are welcome to reuse it for their binaries.
Reusing an already accepted license may greatly speed up and simplify the
acceptance process for a new binary.

When a binary is including third-party code (including open-source code) that is
covered by separate license terms, all those licenses must be compatible with
the distribution license.

Notices
-------

All license and copyright notices covering the binary (including for linked
third-party components) must be listed or linked to in the release notes. For
licenses that are included in the `SPDX license list`_, please link to the
appropriate SPDX license page rather than uploading a copy of the license to the
binary repository.

Release Notes
-------------

All binary components must be clearly versioned and accompanied by a release
notes document that lists the following (updated for each version):

#. version

#. release date

#. distribution license

#. full list of license and copyright notices for (all parts of) the binary
   (can be put into a separate file and linked from release notes if desired)

#. supported silicon

#. changes since the last version

#. errata, known issues

#. commit hash of the open-source trustedfirmware.org project it was tested with

See the `example release notes`_ for suggestions on how to format these notes.

Support
-------

As interfaces in open-source trustedfirmware.org projects change and get
deprecated, it may not be possible to keep a platform port functional without
updating the binary components it depends on. Contributors of binary components
are expected to maintain them together with their platform ports and release
updates as necessary. A binary component that no longer works with current
builds of the open-source project and is not being kept up to date may be
removed. Likewise, new binary component updates need to be tested with the
latest version of the open-source platform port (and the latter needs to be
updated if necessary) before they can be accepted.

Directory Structure
-------------------

This repository contains binaries, license files and release notes. Release
notes must always be placed in the same directory as the binary file(s) they
apply to and should be called ``release-notes.rst``. Directories should be
scoped by vendor and platform if necessary (e.g. a binary pertaining to a single
platform should be placed under ``vendorname/platformname`` whereas a binary
that can support multiple SoCs of a vendor can be placed directly under
``vendorname``). Vendor-specific licenses should be placed in the ``licenses/``
subdirectory of a vendor directory and referenced from the ``release-notes.rst``
files of the binaries they apply to.

Example layout::

 - readme.rst
 - licenses/
   - permissive-binary-license.txt
 - vendorA/
   - licenses/
     - vendor-specific-license.txt
   - commonBinaryX/
     - fileA.bin
     - fileB.hex
     - release-notes.rst
   - platformA1/
     - fileC.bin
     - release-notes.rst
   - platformA2
     - binaryY/
       - fileD.bin
       - release-notes.rst
     - binaryZ/
       - fileE.elf
       - fileF.bin
       - release-notes.rst

.. _Permissive Binary License: licenses/permissive-binary-license.txt
.. _SPDX license list: https://spdx.org/licenses/
.. _example release notes: example-release-notes.rst