Worker Descriptions in OWD XML Files
Each worker directory contains an XML file describing the worker and referencing the spec file typically located in the component library’s specs sub-directory. This XML file is referred to as the OpenCPI Worker Description (OWD). The generic aspects (common across authoring models) of these worker description files are described in this section. The OWD files also have aspects specific to different authoring models, which are described in the respective documents for each authoring model. Some authoring models allow multiple workers to be implemented in one worker directory. In these cases multiple OWDs may be in a single worker directory.
The worker description file adds non-default implementation information to the basic information found in the spec file. Each authoring model defines what the worker-specific information might be. An example would be the width of an FPGA data path for a port in the HDL model. All OWDs have as the top-level XML element an XYZWorker element, where XYZ is the authoring model of the worker.
If the worker has no non-default behavior, there is no need for an edited OWD. The framework (ocpidev) will generate a default one. This default OWD simply contains a reference to the spec file and specifies the authoring model and language. For example, if an RCC worker based on the spec file search-spec.xml only had default implementation attributes, the entire OWD file would be:
<RccWorker spec='search-spec'/>
This section describes aspects common to the OWDs for all authoring models. Further OWD content specific to authoring models is described in their respective documents.
The top level element must refer to an OCS by either:
indicating an OCS file by using the
specattribute (preferred)containing a
ComponentSpecchild element, thus not shared with any other OWD (rare)
Below is an example OWD for an HDL worker, that might be found in fastcore.hdl/fastcore.xml. The fastcore implementation of the core-spec specification is using the HDL authoring model. It references the component specification found in the core-spec.xml file, probably in the specs directory of the component library containing this worker:
<HdlWorker Spec='core-spec' Language='vhdl'
other_attributes=...
>
---other child elements---
</HdlWorker>
OWD files contain the information (metadata) that the OpenCPI build process and runtime environment need to know about the worker that is not in its source code.
A second, optional, XML file in a worker’s directory is its build file, named, e.g., fastcore-build.xml. These files are described in the Worker Build Configuration XML Files topic.
XML Attributes of the Top-level XYZWorker Element in the OWD
Name Attribute of the XYZWorker Element.
The Name attribute defaults to the name of the OWD XML file itself without the directory or extension and is normally omitted. The Name attribute of the component implementation is constrained to be an identifier in several contexts. It is sometimes called the worker name or implementation name.
Worker names may include both upper and lower case for stylistic or programming language purposes. The OpenCPI framework identifies workers in a case insensitive manner. There should not be two workers using the same authoring model in the same package namespace whose names differ in case.
The name of the implementation may be the same as the name of the OCS. It is not required to have a unique name for the OWD different from the spec, unless there are multiple implementations of one OCS that use the same authoring model. I.e. OWD names are implicitly scoped by authoring model.
Spec Attribute of the XYZWorker Element
This string attribute specifies the name of the file for the OCS for this worker. The ocpidev build command automatically place the specs subdirectory (in the component library’s directory), into the search path when these worker description files are processed. The spec files need only be referenced by their name and not any directory or pathname. If the spec file is outside the component library, it can be a relative or absolute pathname. The .xml suffix is assumed and not needed.
Language Attribute of the XYZWorker Element
This string attribute specifies the source code language used in this worker. The valid languages depends on the authoring model, and for each model there is a default language. Some authoring models have only one valid language in which case this attribute is not required.
Version Attribute of the XYZWorker Elements
This attribute has type UChar with a default value of zero if unspecified.
The language interface between workers and their environment (control and data) evolves, usually backward-compatibly. When there is an incompatible change, the worker interface version is incremented, allowing the tools and runtime environment to continue to support workers written to the older interface. Actual interface changes are described in the authoring model documents (e.g. RCC, HDL etc.).
The worker interfaces were updated incompatibly in OpenCPI release 1.5, to version 2, which means that workers written to the new version 2 interface (highly recommended) must explicitly set this attribute to 2. While most changes are specific to authoring models, a significant change to end-of-file indications and zero-length-message handling was made and is described in the End-of-File (EOF) Indications on Data Ports topic. New workers should be written to version 2, and older workers that undergo significant revisions should too. When the ocpidev create worker command creates new workers, it sets this attribute to the latest version.
ControlOperations Attribute of the XYZWorker Element
This attribute contains a comma-separated list of strings identifying the implemented control operations. For operations that are mandatory for the authoring model, they are assumed. The default implies a minimal implementation that only implements those operations required by the authoring model. The control operations are listed in the LifeCycle Control Operations topic. Control operations that are required by the authoring model do not need to be mentioned. When only mandatory operations are implemented, this attribute need not be specified.
OnlyPlatforms Attribute of the XYZWorker Element
This attribute can contain a list of platforms that are the only ones this worker should ever be built for. This should be used to indicate a permanent characteristic of the worker (source code): that it is known to not be buildable or workable except for these. A (rare) example would be if the code had platform-specific code for a certain set of platforms.
To temporarily and frequently change the list of platforms to build for, it is preferable to use this same attribute in the worker’s build configuration file since that simply indicates a temporary choice rather than a permanent characteristic of the worker’s source code.
ExcludePlatforms Attribute of the XYZWorker Element
This attribute can contain a list of platforms that this worker should never be built for. This should be used to indicate a permanent characteristic of the worker: that it is known to not be buildable or workable for these platforms.
To temporarily and frequently change the list of platforms to build for, use this same attribute in the worker’s build configuration file.
OnlyTargets Attribute of the XYZWorker Element
This attribute can contain a list of targets that are the only ones this worker should ever be built for. This should be used to indicate a permanent characteristic of the worker: that it is known to not be buildable or workable except for these. A (rare) example would be if the code had target-specific code for a certain set of platforms.
To temporarily and frequently change the list of targets to build for, use this same attribute in the worker’s build configuration file.
ExcludeTargets Attribute of the XYZWorker Element
This attribute can contain a list of targets that this worker should never be built for. This should be used to indicate a permanent characteristic of the worker: that it is known to not be buildable or workable for these.
To temporarily and frequently change the list of targets to build for, use this same attribute in the worker’s build configuration file.
SourceFiles Attribute of the XYZWorker Element
This attribute contains a list of subsidiary files that should also be compiled and linked together with the worker. For FPGA code, the files are guaranteed to be compiled before the worker source file is compiled so that VHDL entities in these files can be directly instantiated in the worker source code file without redundant component declarations. The list is space or comma separated.
Libraries Attribute of the XYZWorker Element
This attribute contains a list of primitive libraries that the worker requires when it is built. They represent libraries that are subject to the search rules for primitive libraries, which is, in order:
in the same project
exported from projects the current project explicitly depends on
exported by the ocpi.core project
If a library name is qualified by a project, then only the library in the indicated project is used. E.g. for the library named mylib in a project whose package id is myorg.myproj, by using:
libraries='myorg.myproj.mylib otherlib'
the mylib must be found in the myorg.myproj project, while the library otherlib will be found by searching as described above.
RCC primitive libraries are not yet supported.
IncludeDirs Attribute of the XYZWorker Element
This attribute contains a list of directories (via relative or absolute pathnames) that will be searched when including programming language files during building.
ComponentLibraries Attribute of the XYZWorker Element
This attribute contains a list a component libraries to be searched when building this worker. Component libraries are needed when this worker refers to others that are not in the same library. Most workers do not depend on any other components or component libraries, but one example is when the spec for a worker is in a different library.
Endian Attribute of the XYZWorker Element
This attribute specifies the endian behavior of the worker code. When workers are built, the build process may be run in three different modes to create three different types of binaries:
Little endian
Big endian
Dynamic endian based on an input supplied at runtime
The third way, dynamic, is generally not relevant for software since compilers only generate code for a specific assumed endianness. But it is relevant to the FPGA build process to support FPGA bitstreams that can operate in both modes. This OWD attribute specifies how the worker’s code will work in these three build scenarios, as specified by the ocpi_endian parameter which is present for all workers of all types. This attribute is rarely used. Most workers are either unaffected by endianness or are written for little endian.
Endian Attribute |
Description |
Neutral |
The worker code is unaffected by endian parameter settings and is correct regardless of the setting. This is the default value, and is generally correct for software workers. |
Little |
The worker code is unaffected by endian parameter settings and will only operate correctly in a little endian mode. |
Big |
The worker code is unaffected by endian parameter settings and will only operate correctly in a big endian mode. |
Static |
The worker code will respect the endian parameter when set to “little” or “big” and the resulting binaries will operate correctly according to the compile-time parameter setting. |
Dynamic |
Worker code will respect all three values of the
endian parameter. If the parameter is |
Property and SpecProperty Child Elements in the OWD
Properties specified in the component’s OCS indicate the external configuration interface for all implementations of the same spec. Properties specified in the worker’s OWD define additional worker-specific properties, beyond those in the OCS. The description of OCS property elements in the Property Element of ComponentSpec or Properties Elements topic applies when defining worker-specific properties in the OWD, with some additional attributes described below that are valid only in OWD properties.
The OWD can also provide additional attributes to properties already defined in the OCS. E.g. the OWD might make an OCS property writable that was not writable in the component spec. The accessibility added would result in the worker supporting a superset of what was required (promised) by the component spec.
While a component spec can only contain Property elements, a worker description can contain both Property and SpecProperty elements. The Property elements in the OWD introduce new worker-specific properties unrelated to those defined in the OCS. The SpecProperty elements add worker-specific attributes to the properties already defined in the OCS.
There are a number of OWD-only attributes in the next section. They generally apply to both Property and SpecProperty elements in the OWD. Property elements in the OWD support all the attributes supported by Property elements in the OCS, plus the OWD-only attributes below. These OWD property attributes are divided into three categories:
Attributes valid in both Property elements and SpecProperty elements
Attributes only valid in Property elements, not valid in SpecProperty elements
The subset of OCS property attributes that are allowed in SpecProperty elements.
Attributes Only Allowed in OWD Property and SpecProperty Elements
These attributes only exist in OWDs and never in OCSs and are allowed in both Property and SpecProperty elements.
SpecProperty elements can add OWD-only attributes to a property and augment the accessibility of the property, but cannot change the data type of the property.
Name Attribute for OWD Property or SpecProperty Elements
The Name attribute is the case insensitive name of the property. The Name attribute is used in SpecProperty elements to indicate which OCS property is being referenced. In the Property elements it indicates the name of the new worker-specific property, which must not be the same as any Property element in the OCS.
ReadSync and WriteSync for OWD Property/SpecProperty Elements
These Boolean attributes, defaulting to false, are used to indicate the properties that require the worker to be notified when they are read or written by control-software. The baseline behavior is that property accesses are directly made to property values in the worker, with no specific synchronization or notification implied. In this case the worker accesses these values as local memory locations. When these attributes are true, the worker is notified when the access is made by control software.
The exact mechanism used for such worker notification is specific to the authoring model and is described in those documents. Some authoring models may not implement or require this attribute, but where needed, this definition is valid.
ReadError/WriteError Attributes for OWD Property/SpecProperty Elements
These Boolean attributes, default is false, indicate properties that may return errors when read, ReadError, or written, WriteError. If a worker does not return errors and always succeeds when property values are read or written, then leaving these values false allows control-software to avoid any error checking. In some models and systems, error checking can carry significant overhead. Most workers simply accept new values using the default of false for this attribute.
The exact mechanism used for such worker error reporting is specific to the authoring model and is described in those documents.
Readback Attribute for OWD Property/SpecProperty Elements
This attribute specifies that the worker supports reading back values written to non-volatile properties that are either parameter, initial or writable. It is never necessary for normal operation since control-software always caches such values when written, and provides those cached values when control-software reads the value.
This option allows such values to be read back directly from the worker when control-software specifically requests an uncached read access, or when property values are being read directly from the worker and bypassing control-software altogether. An example of this is the ocpihdl utility for HDL/FPGA platforms (described in the HDL Development Guide) when a raw loaded bitstream is being examined directly.
Attributes Allowed in OWD Property, but not SpecProperty, Elements
These attributes are allowed in OWD Property elements, but are not allowed in SpecProperty elements.
Padding Attribute for OWD Property but not SpecProperty Elements
Padding properties (with their padding attribute being true), are those that only exist to force subsequent properties to proper alignment or offsets. No other accessibility attributes may be used with padding properties. The use case for this is when properties need to match a register map or data structure and may require exact offsets for each property. These padding properties are not accessible.
Attributes Allowed in OWD SpecProperty Elements
In addition to OWD-only attributes described above, these are the attributes available in SpecProperty elements that can be used to add accessibility or values beyond what is in the OCS. I.e. the OCS specifies what is guaranteed for applications that use this component. These attributes allow the worker to provide a superset of what is promised in the OCS.
SpecProperty elements can add OWD-only attributes to a property and augment the accessibility of the property, but cannot change the data type of the property.
Parameter Attribute for OWD SpecProperty Elements
This boolean attribute in a SpecProperty element is used to convert a property specified as initial in the OCS, to be a parameter property for this worker. The initial setting in the OCS allows the worker author to decide whether to implement it as a runtime property (i.e. initial) set at initialization time, or a parameter set at compile time. This attribute set to true makes the latter choice.
When a worker has initial (in the OCS) properties that are converted to be parameter in the OWD, it means that the worker must be built for specific values of such properties. This has three implications:
An application can only use the worker if the worker is built for a property value that matches what is requested as an “initial” value by the application.
Binary component libraries may have multiple binary built artifacts for the same worker, but with different combinations of parameter values.
The worker author must decide which combinations of parameter values to build, in order to make alternative settings of such parameters available.
This parameter feature allows workers to have compile time optimizations for certain parameter values, and also allow a single worker source code module to be optimized for different values at compile time. A different worker that accepts runtime values can still be used when no workers with compile-time values have been built with the value requested by the application.
Parameter property values are applied to the build process as expected: e.g. by preprocessor symbol definitions and initialized const values for software, generics for VHDL, and parameters for Verilog.
Writable Attribute for OWD SpecProperty Elements
This boolean attribute in a SpecProperty element is used to convert a property specified as initial or not writable at all in the OCS, to be a writable property for this worker. Thus it adds the possibility of dynamically changing the property value even if that is not what the spec promises.
Default Attribute for OWD SpecProperty Elements
The name of this attribute is default. In the SpecProperty element, this attribute is only valid for parameter properties (as set in the OCS) and when a value is not already specified in the OCS (via default or value attributes). It might be used when the worker author provides this default for the purposes of unit testing and then have build configurations where other values may be specified. See topic Worker Build Configuration XML Files for build configurations.
Value Attribute for OWD SpecProperty Elements
In the SpecProperty element, this attribute is only valid for parameter properties (as set in the OCS) that are defined as parameters in the OCS, but do not specify a fixed value there.
An example would be where a property is defined in the OCS as a parameter (and possibly a default value) with the expectation that workers would provide a worker-specific fixed value. This can be considered annotating the worker so that applications can get/read the static value associated with the worker. The OCS is essentially saying: all workers that implement this spec will supply a static value to the application.
Built-in Parameters of All Workers
OpenCPI automatically adds several parameter properties to all workers. The values of these parameters are usually set during the build process in various ways. Some of these parameters are set to values by the build process and are not intended to be set manually at all. Others may be set or overridden manually.
Each authoring model may also specify additional built-in parameters for all workers using that authoring model. The built-in parameters that apply to all authoring models are described below.
All built-in parameters use the ocpi_ prefix to avoid collisions with component and worker developers’ property names.
The ocpi_debug Built-in Parameter Property
This boolean parameter property indicates whether a debug build is being done. The default value is false. Setting this value to true indicates to worker source code that any debugging instrumentation or behavior should be enabled, at a potential cost of some resource usage and performance. This built-in parameter is always available, and should be used in worker code to enable things like extra logging or statistics keeping.
Setting this parameter to true will also in some cases enable some introspection or instrumentation capabilities of code that is in the OpenCPI infrastructure or is generated code used implicitly by the worker.
Properties can be defined with a debug attribute value of true, which indicates that those properties should only be present when the worker is built with this ocpi_debug parameter set to true.
These features allow debug behavior and debug properties to be permanently in the worker’s source code and OWD while only being enabled as required.
The ocpi_endian Built-in Parameter Property
[This feature is preliminary/untested, but mentioned here as a roadmap item]
This parameter property indicates to worker code which endian mode is being used when the worker is being compiled. Its type is an enumeration of three values:
little: The build is intended to generate binaries for little endian systems
big: The build is intended to generate binaries for big endian systems.
both: The build is intended to generate binaries that can be used in either little or big endian mode, selected at initialization time in the runtime environment.
Software authoring models normally set this mode implicitly as compilers generate binary code for a specific endianness based on the processor being targeted, e.g. little for x86 and ARM, big for PPC.
However some authoring models, such as HDL, can support all three compilation modes. The ability of a worker’s code to support various endian modes is specified in the worker’s endian attribute at the top level of its OWD.
Built-in Properties Associated with Ports
OpenCPI provides several properties that are associated with each port, all of which have the ocpi_ prefix and have the port name at the end of the name. Most built-in properties do not get listed when properties are dumped by ocpirun unless the -‑hidden option is specified to also dump these “hidden” properties. One useful one, for output ports, provides the runtime buffer size in bytes: ocpi_buffer_size_<port>.
Port Elements of XYZWorker Elements
Ports are how workers communicate with each other. They define message-oriented, data-plane communication. Each authoring model defines how workers receive/consume and send/produce messages to or from other workers. This is independent of whether workers are collocated in the same container or executing elsewhere.
Each authoring model may have attributes and elements of this Port element specific to that authoring model, but there are a number of aspects common to all worker descriptions that are described here. A Port element in a worker description matches the Port element in the component spec by name, and adds worker-specific information about how the worker implements the port.
Some authoring models may use different names for port elements in order to imply additional information, but the attributes described below apply in any case.
Name Attribute of Port Elements
This string attribute is required and must match one of the names of the port elements in the component spec. It normally indicates for which component port the worker is providing additional implementation-specific information. In some special cases, a worker may use this element to define additional ports beyond what is in the spec, but this behavior would be specific to an authoring model.
Protocol Summary Override Attributes of Port Elements
The OCS file on which the worker is based defines protocols for ports, and various protocol summary attributes are derived from the protocol. These attributes may be overridden where the protocol is defined (see the Protocol Summary Attributes topic), but they may also be overridden for a particular worker as attributes of the port element.
Care must be taken when doing such overrides since they may render a worker incompatible with other workers that implement the same spec. This could make unit testing of all such workers infeasible or difficult.