Protocol Specifications (in OPS XML Files)
An OpenCPI Protocol Specification (OPS), describes, in one or more XML files, the set of messages that may flow between the ports of components. They are described separately from the OCS XML file because they are used by both sides of a connection. In a connection between component ports, the specs of both ports, in their Port elements, refer to the same OPS.
The OPS describes the set of messages defined in the protocol, as well as some top level attributes for the protocol.
In special cases, the messages in a protocol are not specified individually but rather a set of summary attributes is specified. This indicates the basic behavior of the ports using the protocol. The information is called a protocol summary. When messages are specified, protocol summary attributes are inferred from the messages. If protocol summary attributes are present when messages are specified, they override the attributes inferred from the message specifications.
As an example, a set of messages of different lengths and different payload formats might be bounded (having a maximum length), or unbounded, depending on whether any message has no maximum length. This boundedness attribute is normally inferred from the set of messages. Another example is the smallest unit of data in any message. If all messages in a protocol deal only with 64 bit integers, then the smallest unit of data for all messages is 8 bytes. This minimum data granularity attribute is inferred from examining all the messages specified for the protocol.
A protocol summary is the set of all summary attributes, whether inferred from the messages specified for the protocol, overridden by explicit values, or given directly when messages are not specified. The summary attributes are used by the OpenCPI code generation tools and runtime environment to determine certain behaviors.
In OPS files, messages are called operations, and fields of messages are called arguments. This is terminology based on the Remote Procedure Call (RPC), or Remote Method Invocation (RMI), model of communications. However, this concept does not apply to OpenCPI inter-component communications, as all communications are simply unidirectional connections conveying messages.
The term opcode is used to represent a zero-origin ordinal of operations within a protocol. In the runtime environment, opcodes are used to indicate which operation of the protocol a given message represents. Thus if the opcode of a message is zero, then that message should be interpreted as the first operation in the protocol.
OPS files preferably carry the suffix -prot.xml, although -protocol.xml, _protocol.xml are also used.
Protocol Element as Top-level Element
The Protocol element is a top-level element in a separate file whose name (without the .xml suffix) is the value of the Protocol attribute in a port element in an OCS. It specifies a message protocol used at ports. The protocol will likely be reused across a variety of components and ports since it specifies how two components talk to each other. The Protocol element has Operation subelements to indicate the different message types that may flow out of or into data ports using this protocol.
A Protocol element may also use the <xi:include href='<file>'/> syntax as a child element, which allows the operations of one protocol to be included at that point in another protocol. I.e. the operations in the protocol file included are inserted into the protocol at the point in the sequence of operation elements where the xi:include element is placed. The xi:include element is usually placed first so that the opcodes of the included protocol remain the same in the new “derived” protocol. An example:
<protocol>
<xi:include href='base-proto'/>
<operation name='special_add_on'/>
</protocol>
Name Attribute of Protocol Elements
When the Protocol element is the top-level element in a file, the optional name attribute is defaulted from the name of the file, with any -prot, _prot, ‑protocol, _protocol, .xml suffixes removed. Since protocols are usually defined in separate files, the names are usually not present in the XML and are derived from the file name.
Protocol Summary Attributes
These attributes are normally inferred from Operation elements in the protocol and are rarely used explicitly. They may be used to override the inferred values or they may be specified in the absence of Operation elements altogether. The following table defines the protocol summary attributes normally inferred from examining Operation elements.
Name |
Type |
Description |
|
|
Size in bytes of smallest unit of data in any message |
|
|
All messages have this multiple of data values. I.e. if messages always of an even number of values, it is 2. |
|
|
Default buffer size for this protocol even if unbounded* |
|
|
Are there different size data values? |
|
|
Maximum number of data values in any message* |
|
|
Minimum allowable buffer size in bytes |
|
|
Minimum number of data values in any message |
|
|
Number of message types |
|
|
Do any messages have unbounded length? |
|
|
Can messages be different lengths? |
|
|
Are any messages zero length (have no arguments)? |
* these attributes have no inferred value if protocol is unbounded.
Operation Element of Protocol Elements
The term Operation is loosely associated with the analogous concept in RPC systems where the message is invoking an operation on a remote object. In the context of OpenCPI it simply describes one of the messages that is legal to send on a port with this protocol. It has two attributes and some number of argument child elements, which describe data fields in the message.
Name Attribute of Operation Elements
This string attribute is a case insensitive name of the operation/message within this protocol. It should be an appropriate identifier for programming languages.
Argument Child Element of Operation Elements
This child element indicates a data field in the message payload for the given operation. Its attributes are the same as a Property element and describe an argument with: Name, Type, StringLength, ArrayLength, SequenceLength, etc. If no argument elements are present under an Operation element, the operation defines messages with no data fields, referred to as a Zero Length Message. Argument elements are similar to member elements in property elements whose Type attribute is struct, but these arguments to an operation do not have to have bounded lengths. Here the StringLength attribute is not required for strings, and the SequenceLength attribute can be zero indicating no upper bound.
Protocol Specification (OPS) Examples
This protocol has one message type consisting of 1024 unsigned short values.
<Protocol>
<Operation Name="mess1">
<Argument Name="val" Type="uShort" ArrayLength="1k">
</Operation>
</Protocol>
Message Payloads on Data Ports
The message payload for each operation message has a serialized format as a sequence of bytes that, when used in software, are laid out in byte-addressed memory. For example, if the operation element in a protocol contains:
<argument name='a1' type='uchar'/>
<argument name='a2' type='ushort' arraylength='2'/>
<argument name='a3' type='ulonglong'/>
And the values of this payload are:
a1: 1, a2: {0x2345,0x6789}, a3: 0xfedcba9876543210
Then the byte sequence (with proper alignment, and encoded little-endian), would be:
Sequence # ► |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Contents (hex) |
01 |
x |
45 |
23 |
89 |
67 |
x |
x |
10 |
32 |
54 |
76 |
98 |
ba |
dc |
fe |
Argument |
a1 |
a2[0] |
a2[1] |
a3 |
||||||||||||
Contents |
1 |
0x2345 |
0x6789 |
0xfedcba9876543210 |
||||||||||||
This layout and these values are the same for all types of workers in all (little endian) environments and over all data paths. The x values are padding for alignment.
Every numeric type is aligned for its size. Structure types are aligned according to the largest alignment requirement of any of its members. Sequences are aligned according to the alignment requirement of their members and are preceded by a 32-bit unsigned value indicating the number of elements. If the alignment requirement of the sequence is greater than 32 bits, padding is added after the length to align the first element, even if there are zero elements. Padding inserted to achieve alignment may be any value.
The exception to this rule is when the message consists entirely of one sequence of fixed-length elements. In this case, the sequence length is implied by the overall message length at input and output ports and not by inserting a 32-bit unsigned value into the message buffer/structure. The message itself is the sequence and the number of elements in the sequence is derived from the length of the message supplied out-of-band by the OpenCPI data-plane.
For related information about message payloads on data ports that is specific to an authoring model, see the development guide for that authoring model.