Introduction

Scope

This document outlines best practice for those writing and developing OpenCPI components, workers and primitives. This best practice covers the structure and low-level implementation details of components and primitives, and essentially specifies the recommended subset of what is possible based on the reference documentation.

It is assumed the reader is familiar with OpenCPI and the terms OpenCPI uses, as this document does not define these. For readers that are unfamiliar with OpenCPI referring to the Acronyms and Definitions documentation of OpenCPI may be useful.

Terminology

In this document the word “must” (or “must not”) indicates a rule where compliance is mandatory to meet these guidelines. If an exception is required then this must be documented, in the very least by a comment in the source code.

In this document the word “should” (or “should not”) indicates a strong preference which a best practice implementation will be met wherever possible.

In this document the word “encouraged” indicates a default preference to be followed in the absence of any other requirement.

All code snippets are formatted as this example

Any code snippets in block upper case, such as EXAMPLE, are place holder names and in real applications will be switched for their correct value (e.g. for year YYYY would be replaced with 2019).

This version of this best practice document is consistent with the OpenCPI release as specified in the header of this document. It is revised when necessary for new releases.

When writing components and primitives, labeling your code in README files and/or comments, to convey the range of OpenCPI releases it is known to be compatible with, is encouraged. An example of such a label is opencpi-x.y.z where opencpi-x.y.z is the release of OpenCPI your project is known to be compatible with.