Message Protocol

This section specifies the message protocol used to communicate with cam-service. The primary goal of the protocol is to allow critical applications to initialize and send stream events to be monitored.

libcam in this project provides an implementation of this protocol relevant to critical applications allowing them to easily integrate with the CAM project.

All multi-byte values are transmitted as big-endian. All bitmap values have bit 0 defined as the least significant bit.

Reserved fields are not assumed to have any specific value.

About the timestamp fields:
  • The protocol does not assume or enforce an epoch.

  • The timestamps must come from clocks synchronized between participants (cam-service, cam-tool and critical applications).

About the Universally Unique Identifier (UUID) fields:
  • UUIDs are 16-byte long fields representing the 128-bit UUID in binary format.

  • The protocol does not enforce any UUID variant. cam-service uses the UUID as a whole opaque data value and does not process the sub-fields of the UUID.

About the handler fields:
  • To avoid having to transmit 128-bit UUIDs on each message, a 32-bit handler is used once a stream is established with the Stream Initialization Message.

  • Handlers are valid only on the connection the stream was initialized.

  • The protocol assumes the handler is an opaque data and does not enforce how they are created. Any obfuscation or non-guessable mechanism must be defined by cam-service.

Message Header

The message header contains a number of fields and is present at the beginning of each message.

Field

Size (in bytes)

Description

Protocol version - major

1

0x01 for this specification

Protocol version - minor

1

0x00 for this specification

Message size

2

Unsigned integer, the whole message size includes the header size

Message ID

2

· Unsigned integer
· Message IDs are per message direction (to and from cam-service)
· Different for each message type, see details in each message
description
· 0 is not a valid message ID

Reserved

2

Stream Initialization Message

Application requests the creation of a new monitoring stream. cam-service will allocate the required resources and load the configuration it has which matches the UUID received. If the stream initialization in cam-service succeeds, cam-service will return a 32-bit handler for critical applications to use in further messages. After the initialization, the stream is in halt mode. Before the monitoring starts, applications must “start” the stream using the Stream Start Message

Critical Application to cam-service

Field

Size (in bytes)

Description

Message Header

8

Message ID = 1

Timestamp

8

Unsigned integer, message timestamp

UUID

16

Stream UUID

cam-service to Critical Application

Field

Size (in bytes)

Description

Message Header

8

Message ID = 1

Timestamp

8

Unsigned integer, message timestamp

UUID

16

Stream UUID, same as the UUID from the stream that requested the initialization

Status

2

Unsigned integer,
0 - Success,
1 - Service is out of resources,
2 - Service has no configuration for the requested UUID

Reserved

2

Handler

4

Unsigned integer, identifies the stream

Stream Start Message

Application starts the stream monitoring by sending a stream start message. The stream handler must match an initialized stream which is currently in “halt” mode.

The start message serves two purposes:

  • Decouple the initialization from the starting of the monitoring allowing an application to take as long as it needs in the initialization phase (which is assumed as non-critical). It is only after the “start” message that cam-service will start to monitor events.

  • Together with the Stream Stop Message, the stream start message allows a stream to be started/stopped multiple times without the application having to disconnect.

Critical Application to cam-service

Field

Size (in bytes)

Description

Message Header

8

Message ID = 2

Timestamp

8

Unsigned integer, message timestamp

Handler

4

Unsigned integer, identifies the stream

Reserved

4

Stream Stop Message

Application indicates to cam-service that the stream identified by the stream handler must be stopped. No further stream events are going to be sent to cam-service. cam-service must ensure all watchdogs related to this stream are stopped.

Critical Application to cam-service

Field

Size (in bytes)

Description

Message Header

8

Message ID = 3

Timestamp

8

Unsigned integer, message timestamp

Handler

4

Unsigned integer, identifies the stream

Reserved

4

Stream Event Message

Application sends stream events identified by the stream handler to the cam-service.

Critical Application to cam-service

Field

Size (in bytes)

Description

Message Header

8

Message ID = 4

Timestamp

8

Unsigned integer, message timestamp

Handler

4

Unsigned integer, identifies the stream

Sequence ID

4

Unsigned integer, identifies the event sequence

Event ID

2

Unsigned integer, identifies the event within the stream

Reserved

6

Stream Deploy Message

The stream deploy message is used to send CAM Stream Deployment (CSD) files.

This support is mainly used for convenience as it allows updating the CSD files in the same subsystem the cam-service is running without the need of a re-deployment of the all images or even without having to reboot the systems. This may impact security and safety aspects of the system hence this message should not be enabled in production and should be limited to development life cycles only.

In order to transfer a full deployment file, the sender (deployment application) may send multiple ‘chunks’ of the file using multiple invocations of this message.

Deployment Application to cam-service

Field

Size (in bytes)

Description

Message Header

8

Message ID = 5

Timestamp

8

Unsigned integer, message timestamp

UUID

16

Stream UUID

Attributes

2

Bitmap,
Bit [0] - Overwrite previous file
Bit [15:1] - Reserved

File size in bytes

2

Unsigned integer, The actual maximum data file size is implementation
specific

Reserved

1

Chunk ID

1

Unsigned integer starts from 0. Used to control the number of chunks sent when the file is sent via multiple parts

Chunk size

2

· Allowed to be zero for the first chunk (when ‘chunk ID’ is zero)
· Maximum chunk size is implementation specific
· Chunk size is allowed to be different for each invocation of this message

Chunk data

<variable>

cam-service to Deployment Application

Field

Size (in bytes)

Description

Message Header

8

Message ID = 4

Timestamp

8

Unsigned integer, message timestamp

UUID

16

Stream UUID, same as the UUID from the stream that requested the deployment

Status

1

0x00 - Success
0x01 - Deployment message is disable. Examples include production mode where the deployment files are deployed directly as part of the firmware
0x02 - Failed to write chunk. Cam-service failed to write the data. Examples include:
· Storage I/O error
· Out of space
0x03 - Deployment file already exists for this stream UUID.
· When the Cam Deploy Message from the application to cam-service indicates the file can be overwritten, this error can still happen when multiple deployments are detected as happening at the same time
0x04 - Invalid file size. Examples include:
· File size is zero
· File size is bigger than the maximum allowed
· File size is smaller than expected
0x05 - Invalid chunk order
0x06 - Invalid chunk size. Examples include:
· The chunk size is 0
· The chunk size exceeds the maximum allowed size
· Mismatch between the message size and the chunk size
0x07 - Exceeded maximum number of deployment sessions. This is returned by cam-service when it is unable to start new deployment sessions due to resource limitations. The number of deployment sessions is implementation specific.

For any non-success status, the deployment process is cancelled and any data received by the cam-service is discarded

Reserved

7