V4 CA Protocol Specification

From EPICSWIKI
Revision as of 20:22, 26 October 2005 by AndrewJohnson (talk | contribs) (Converted from Jeff's HTML source)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

EPICS Channel Access Protocol Specification

EPICS Version: 4

Channel Access Protocol Version: 4.15

Author: Jeff Hill

LA-UR-05-8238

Data Types

  • All multi-octet primitive types are transmitted in little endian byte order.
  • All signed integers use two's complement arithmetic.
  • All floating point numbers shall comply with IEEE floating point standards.
Externally Visible Data Types
Mnemonic Data Type Identifier
reserved
INT8 8 bit signed integer 1
INT16 16 bit signed integer 2
INT32 32 bit signed integer 3
INT64 64 bit signed integer 4
FLOAT32 32 bit IEEE floating point 5
FLOAT64 64 bit IEEE floating point 6
FLOAT128 128 bit IEEE floating point 7

STRING

UTF-8 encoded character string 8

PSD

property sequence description 9
reserved 10 - 128
Protocol Private Data Types
Mnemonic Data Type
UINT8 8 bit unsigned integer
UNIT16 16 bit unsigned integer
UINT32 32 bit unsigned integer
UINT64 64 bit unsigned integer

UINTN

variable length unsigned integer

PTD

property transport definition

DSD

dimension sequence description

DBD

dimension bounds definition

ADB

array dimension bound

UINTN, Variable Length Unsigned Integer

The octets below are in little endian order (least significant bits are transmitted before most significant bits).

UINTN - 1 octet
Data Type Bit 7, msb Bits 7 - 0
OCTET Bits 0-7 of unsigned integer value
UINTN - 2 octets
Data Type Bit 7, msb Bits 7 - 0
OCTET 1 Bits 0-7 of unsigned integer value
OCTET Bits 8-15 of unsigned integer value
UINTN - 3 octets
Data Type Bit 7, msb Bits 7 - 0
OCTET 1 Bits 0-7 of unsigned integer value
OCTET 1 Bits 8-15 of unsigned integer value
OCTET Bits 16-23 of unsigned integer value

After 3 octets, the same pattern repeats.

UINTN - N octets
Data Type msb Bits 7 - 0
OCTET 1 Bits 0-7 of unsigned integer value
OCTET 1 Bits 8-15 of unsigned integer value
OCTET 1 Bits 16-23 of unsigned integer value
... 1 ...
OCTET N Bits N*8-N*9-1 of unsigned integer value

STRING, UTF-8 Encoded Character String

STRING
Data Type Purpose
UINTN the number of UTF-8 tokens
OCTET sequence UTF-8 encoded character string sequence

Nill (zero) termination is not included in the string.

PSD, Property Sequence Description

This data type is used to describe a packed sequence of property values, a property sequence (PS), that might be encapsulated within a subsequent message on the same circuit, or in the same datagram. The order that the properties are described in the sequence is exactly the same as the order that the properties will be pushed onto the wire.

Container Property Transport Sequence Description
Data Type Purpose
UINTN Number of properties in sequence
N Property transport definitions See below

PTD, Property Transport Definition

If the dimension field is zero then property bounds definitions are not included, and the property transported has a scalar representation.

Property Transport Definition - Atomic
Data Type Purpose Value
UINTN Property Id Sender defined
UINTN Data Type Identifier Sender defined, not 9
DSD Dimension sequence description Sender defined
Property Transport Definition - Container
Data Type Purpose Value
UINTN Property Id Sender defined
UINTN Data Type Identifier 9
DSD Dimension sequence description Sender defined
PSD Property sequence description Sender defined

DSD, Dimension Sequence Description

Scalar Dimension Sequence
Data Type Purpose Value
UINTN Specifies that the data is scalar
Array Dimension Sequence
Data Type Purpose Value
UINTN Specifies the number of property bounds definitions for array data N, not zero
N X DBD sequence of N property bounds definitions Sender defined

DBD, Dimension Bounds Definition

Property Bounds Definition, Fixed Bound
Data Type Purpose Value
UINTN Bound Type 0, fixed bound
ADB Array dimension bound Sender defined
Property Bounds Definition, Variable Bound
Data Type Purpose Value
UINTN Bound Type 1, variable bound
Packaging of arrays on the wire

If the bound type is fixed, then the dimension does not accompany the array data on the wire. If the bound type is variable then any variable dimension information immediately precedes the data on the wire. The order that any dynamic dimensions are described in the dimension sequence description (DSD) is exactly the same order that any dynamic array dimension bound (ADB) will be pushed on to the wire prior to pushing the array data sequence on to the wire.

ADB, Array Dimension Bound

Array Dimension Bound
Data Type Purpose Value
UINTN First element index Sender defined
UINTN Element count Sender defined

Property Hierarchy Path

<property hierarchy path> := <optional white space> . <optional white space> <property name> <optional white space> [ <property hierarchy path> ]

A "." character is employed to separate components of the property hierarchy path. Should the user need to include the "." in a channel name, they can escape the "." character with a back slash "\" character.

Channel

A channel is defined to be a virtual communication path from a client application to a communication receptacle in a service. The communication receptacle is either a process variable or a message passing interface.

Channel Names

Flat (hierarchy challenged) tools like caGet will need to access a property deeply embedded in the property hierarchy as a simple PV.

Therefore, channel names will have the following format.

<communication receptacle name> [ <property hierarchy path> ]

This syntax may clash with the current state of the version 4 database design.

Message Transport

The protocol is designed for transport via a full duplex octet stream circuit such as is offered by TCP/IP. Clients initiate circuits with servers. All clients and servers initiating a new outgoing octet stream circuit must insert, prior to any other message, a CA Protocol Initiate message. Certain requests (see documentation for each request) will also be suitable for datagram transport such as is offered by UDP/IP. The CA Protocol Initiate message must be the first message in any CA protocol datagram prior to any other message in the datagram.

The protocol is asynchronous, and therefore multiple requests can be outstanding (waiting for a response) at the same time. It is expected that quality implementations will combine several messages together into one network frame.

CA Protocol Initiate

This message overlays a similar purposed message employed by previous versions of the protocol thereby retaining potential for client and server libraries to, at runtime, choose between dispatch tables suitable to different protocol revisions. This allows client and server libraries to communicate with multiple peers using both the EPICS version 3 and the EPICS version 4 protocols.

There is no response to this message.

CA Protocol Initiate
Data Type Purpose Value
UINT16 reserved
UINT16 reserved
UINT16 requested server dispatch priority where 0 is the lowest priority (executes last) and 255 is the highest priority (executes first), all other values are reserved
clients servers
0 - 255
UINT16 protocol minor revision number 15
UINT32 magic number 0x5b43415d == '[' 'C' 'A' ']'
UNIT32

Reserved for virtual circuits.

A sequence number incrementing with each successive message for datagrams. Clients use this sequence number to detect duplicates and out of order delivery.

circuit datagram
sequence number

The dispatch priority protocol element is relevant only when a client initiates communication with a server. Servers do not request a dispatch priority within its client, and should set this field to zero.

Request / Response Protocol

Request Messages

Request messages are transmitted only by clients. Servers do not transmit request messages. There are two request message forms depending on whether a response is possible, or not.

Request Message - Response is Possible
Data Type Purpose Value
UINTN Request identifier client defined
OBJID Request identifier client defined, 0 - 31 reserved
OCTETS Request payload request dependent
Request Message - No Response
Data Type Purpose Value
UINTN Request identifier client defined
OCTETS Request payload request dependent

Response Messages

Response messages are transmitted only by servers. Clients do not transmit response messages.

Solicited Response Messages

Success Response
Data Type Purpose Value
UINTN request identifier request defined
OCTETS response payload request dependent

Unsolicited, or Indirectly Solicited, Response Messages

Exception Response

This indirectly solicited response is sent when a request fails in the server.

Exception Response
Data Type Purpose Value
UINTN Request identifier
UINTN Exception identifier failure dependent, see below
STRING Failure context message failure dependent
UINTN Copy of request message length N, request defined, but zero if failure not caused by a request
N OCTETS Copy of request message request defined
Exception Identifier
Status Value Definition Severity
Insufficient memory to complete request Warning
1 Invalid request identifier Fatal
2 Invalid channel name Warning
3 Invalid channel identifier Fatal
4 Invalid property identifier Fatal
5 Invalid property transport sequence identifier Fatal
...
Server Status Beacon

This request is sent by a server to announce periodically its presence, and availability, on the network. This request might be sent over a virtual circuit, or in a datagram. There is no response. The property transport sequence might be predefined at compile time. It is used to identify the server address (including possibly a TCP port) of the sender, and other (possibly site specific) server state variables.

Server Status Beacon
Data Type Purpose Value
UINTN Request identifier 1
UINTN Property sequence identifier Sender Defined
PS Server status parameters Sender Defined

Protocol Encapsulation

Data Type Purpose Value
UINTN Directive
UINTN Encoding TBD, but to include an unmodified encoding and at least one standard type of compression encoding
UINTN Length N, compressed protocol sequence length
N OCTETS Encapsulated protocol octet sequence Sender defined, format determined by encoding

The maximum size of an encapsulation probably needs to be specified.

Compression will be useful only when fast computers communicate or relatively slow links.

Define Channel

The client defines a channel in the server for its future use. There is no response unless the request is invalid, or cant be completed.

If at any time a communication endpoint to which a channel is bound ceases to exist, the server must send an Invalid channel identifier exception responses to all of the appropriate clients indicating that their channel is attached to a defunct resource. After receiving the Invalid channel identifier exception the client library is no-longer required to close the relevant channel with the server.

Define Channel Request
Data Type Purpose Value
UINTN Directive 1
UINTN Channel Identifier Sender defined
STRING Channel Name Sender defined

Expunge Channel

The client must expunge any channel from the server that will no-longer be used.

Expunge Channel Request
Data Type Purpose Value
UINTN Directive
UINTN Channel Identifier Sender defined

Swap Channel Identifiers

Commands the server to assign the process variable associated with channel identifier one to channel underived two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

Swap Channel Identifiers Request
Data Type Purpose Value
UINTN Directive
UINTN Request identifier Sender defined
UINTN Channel Identifier one Sender defined
UINTN Channel Identifier two Sender defined
Swap Channel Identifiers Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined

Define Property

The client defines a property in the server for its future use. There is no response unless the request is invalid, or cant be completed. Commonly used properties, especially those used by datagram services, will be predefined thereby avoiding any need to define the property before it is used.

Define Property Request
Data Type Purpose Value
UINTN Directive 2
UINTN Property identifier Sender defined
STRING Property name Sender defined

Expunge Property

The client must expunge any property from the server that will no-longer be used.

Expunge Property Request
Data Type Purpose Value
UINTN Directive
UINTN Property Identifier Sender defined

Swap Property Identifiers

Commands the server to assign the property associated with property identifier one to property underived two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

Swap Property Identifiers Request
Data Type Purpose Value
UINTN Directive
UINTN Request identifier Sender defined
UINTN Property Identifier one Sender defined
UINTN Property Identifier two Sender defined
Swap Property Identifiers Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined

Define Property Transport Sequence

The client defines a property transport sequence in the server for its future use. A property transport sequence exactly describes a stream of octets that will express a sequence of properties in the primitive type and dimension selected by the client. There is no response unless the request is invalid, or cant be completed.

Commonly used property transport sequences, especially those used by datagram services, might be predefined thereby avoiding any need to define the property transport sequence before it is used.

Define Property Transport Sequence Request
Data Type Purpose Value
UINTN Directive 3
UINTN Property sequence identifier Sender defined
PSD Property sequence description, see above Sender defined

Expunge Property Transport Sequence

The client must expunge any property transport sequence from the server that will no-longer be used.

Expunge Property Transport Sequence Request
Data Type Purpose Value
UINTN Directive
UINTN Property Transport Sequence Identifier Sender defined

Swap Property Transport Sequence Identifiers

Commands the server to assign the property transport sequence associated with property identifier one to property transport sequence identifier two and visa-versa. This functionality allows implementmplementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

Swap Property Identifiers Request
Data Type Purpose Value
UINTN Directive
UINTN Request identifier Sender defined
UINTN Property Transport Sequence Identifier one Sender defined
UINTN Property Transport Sequence Identifier two Sender defined
Swap Property Transport Sequence Identifiers Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined

Define IO Request Modifier

Define an IO request modifier. There is no response unless the request is invalid, or cant be completed.

The client must cancel any request trigger specification in the server that will no-longer be used.

Define Request Trigger Specification Request
Data Type Purpose Value
UINTN Directive 4
UINTN IO request modifier identifier Sender defined, see below
STRING <IO Request Modifier Expression> Sender defined, see below
IO request modifier identifier
Value Purpose
IO Type Synchronization Type
write unsynchronized write
read unsynchronized read
command unsynchronized command
subscribe first update is an unsynchronized read followed by updates for every state change
1 - 32 reserved
N > 32 client library assigned

IO Request Modifier Expression

<IO Request Modifier Expression> :=
    <Property Match Expression> <IO Request Attribute List>

<Property Match Expression> :=
    [(] [ [<Property Match Expression>] <Boolean Operator> ] <Property Match Specification> [)]

<IO Request Attribute List> :=
{
    <IO Request Attribute> [ <IO Request Attribute List> ]
}

<IO Request Attribute> :=
{
   <Subscription Modifier>,
   <Minimum Period Spec>,
   <Maximum Period Spec>,
   <Minimum Percent Change Between Updates Spec>,
   
<Property Match Expression> :=
  <Property Name> <Comparison Operator>
    { <Property Name>, <Channel Name>, <Constant Expression> }

Here are some examples of IO modifier expressions. Parenthesis may be used to enforce order of operations.

(beamGate == 4 ) && ! ( bpm32.beamGate == 7)

beamGate == 4 && triggerTimeOffset ( 3 sec )

beamGate == 4 && eventQueueLength ( 1 ) maxPeriod ( 4 sec )

eventQueueLength ( 1 ) propertyPath ( limits )

eventQueueLength ( 1 ) propertyPath ( xAxisMotor.limits )

Minimum and Maximum Period (applicable only to subscriptions)
timeSpec := <real number> 
maxPeriod ( timeSpec )

minPeriod ( timeSpec )
Minimum Percent Change Between Updates (applicable only to subscriptions)
minPercentChange ( <real number> )
Time Based Extraction Criteria (applicable only to subscriptions)
beginTime ( timeSpec )

endTime ( timeSpec )
Maximum Event Queue Length (applicable only to subscriptions)
eventQueueLength ( <integer number> )
Trigger Time Offset (applicable only to subscriptions)
triggerTimeOffset ( timeSpec )
Property Path
propertyPath ( <property hierarchy path> )

Attributes controlling queueing versus caching behavior of read and writes are probably specified here. Needs more thought.

Attributes controlling process passive and maximize severity (or their future functional equivalents) are probably specified here. Needs more thought.

Expunge IO Request Modifier

The client must expunge any IO request modifier from the server that will no-longer be used.

Expunge IO Request Modifier
Data Type Purpose Value
UINTN Directive
UINTN IO request modifier identifier Sender defined

Swap IO Request Modifier Identifiers

Commands the server to assign the trigger specification associated with property identifier one to trigger intensifier two and visa-versa. This functionality allows implementation to dynamically adjust frequently used objects to use smaller integer identifiers, and therefore smaller on-the-wire representations.

Swap Property Identifiers Request
Data Type Purpose Value
UINTN Directive
UINTN Request identifier Sender defined
UINTN IO request modifier identifier one Sender defined
UINTN IO request modifier identifier two Sender defined
Swap Trigger Identifiers Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined

Channel Write Without Response

The client writes a property transport sequence to a process variable in the service. There is no response unless the request is invalid, or cant be completed.

Channel Write Request
Data Type Purpose Value
UINTN Directive 5
UNINT Channel identifier Sender defined
UINTN Property sequence identifier of payload Sender defined
UINTN IO request modifier identifier Sender defined
PS Property payload to be written Sender defined

Channel Write With Response

The client writes a property transport sequence to a process variable in the service. There is always a response. A successful response indicates that the request, and all side effects, have completed. An unsuccessful response is an exception response (see above). It indicates that the request could not be completed in entirety, and that the internal state of the channel has not been modified.

Channel Write Request
Data Type Purpose Value
UINTN Directive 6
UINTN Request identifier Sender defined
UINTN Channel identifier Sender defined
UINTN Property sequence identifier of payload Sender defined
UINTN IO request modifier identifier Sender defined
PS Property payload to be written Sender defined
Channel Write Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined

Channel Read or Subscribe

The client reads a property transport sequence from a process variable in the service. If the request identifier is 7, there is only one response. Otherwise, if the request identifier is 8, a subscription is created and multiple responses are expected. A successful response includes the specified property transport sequence identifying the current state of the channel when the request was executed by the server. An unsuccessful response is an exception response (see above).

Channel Read or Subscribe Request
Data Type Purpose Value
UINTN Directive 7 or 8
UINTN Request identifier Sender defined
UINTN Channel identifier Sender defined
UINTN Property sequence identifier of response payload Sender defined
UINTN IO request modifier identifier Sender defined
Channel Read or Subscribe Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined
PS Property payload read Client formatted, server defined

Channel Command

The client sends a command to a message passing interface in the service. A request in the form of a property transport sequence is sent to the message passing interface in the service, and the message passing interface responds with another property transport sequence.

Data Type Purpose Value
UINTN Directive 9
UINTN Request identifier Sender defined
UINTN Channel identifier Sender defined
UINTN Request property sequence payload identifier Sender defined
UINTN Response property sequence payload identifier Sender defined
UINTN IO request modifier identifier Sender defined
PS Request property payload Sender defined
Channel Read or Subscribe Successful Response
Data Type Purpose Value
UINTN Request identifier Client defined
PS Response property payload Client formatted, server defined

Cancel Request

Cancel a request in progress. There is no response.

Cancel Previous Request
Data Type Purpose Value
UINTN Directive 10
UINTN Request identifier identifier of the request to be canceled

Server Verify

Verify that the server is responsive.

This request might also be accepted to by a datagram server. Typically, a response is mandatory, but a datagram server must never respond to any request of this type in a datagram sent to a broadcast or multicast address.

The property transport sequence is used to identify the condition of the server, and other (possibly site specific) server state variables.

Server Verify Request
Data Type Purpose Value
UINTN Directive 11
UINTN Request identifier Sender defined
UINTN Property sequence identifier Sender defined
Circuit Verify Successful Response
Data Type Purpose Value
OBJID Request identifier Client defined
PS Server status parameters Client formatted, server defined

Design Notes

  1. A fundamental choice of this design was that all identifiers are assigned by the client. This tends to make state change logic simpler in the client library and, since the server's identifier need not be returned in a response to the client, there will also be less TCP return pipe traffic during setup.

The server might continue to have only one hash table keyed by an {object id, client id} pair. Hopefully, the bucket use distribution for this table can be managed to be reasonably uniform. This type of keying probably slightly increases hashing and distribution overhead so, alternatively, there could be one hash table in the server for each client, contingent possibly on upgraded memory management for the hash table implementation. There is a chance that a request to define a channel will be sent to a server that does not have the named communication receptacle. In that situation the server will send the client an exception, and respond to any subsequent requests specifying a bogus channel identifier with an exception message. The unfortunate drawback to this approach will be the opportunity for a client to briefly think that it is connected when it isn't. We are currently ensuring that disconnect notification arrives within NNN seconds so perhaps brief windows of uncertainty are not unreasonable. Also, this window of uncertainty would exist prior to arrival of the first monitor update so any client that watches the magnitude of a channel should remain in a safe state.

  1. The flow-control functionality in previous versions of the CA protocol was probably only relevant to GUI applications. It is superseded in this version of the protocol by capabilities allowing clients to set the subscription event queue length?
  2. Server beacons are used to efficiently inform multiple clients about server state of health while using minimum bandwidth. Multicasts/broadcasts are typically the lowest bandwidth consuming option when sending one message to multiple clients. Server beacons are used to A) inform clients when a newly accessible IOC joins the network, and B) periodically communicate tangible indication of responsiveness to clients with idle TCP circuits.

In this version of the protocol hopefully beacons will be issued using multicast addresses thereby eliminating any need for the CA Repeater daemon. In this version of the protocol additional server state of health properties might be included in the beacon message.

  1. The current baseline is to not include messages in the CA protocol for authentication purposes. Instead, we prefer to use transport protocol facilities for coarse host based authentication, and integrate public domain kerberos libraries (or some other equivalent) for stronger forms of authentication including user based authentication.
  2. The current baseline is to employ subordinate properties to communicate the current state of the access rights for a channel.

Will access rights properties need to show up in multiple places in the property hierarchy in order that the access rights might vary depending on what properties are accessed? If so, then how can we provide a consistent interface for clients so that they always know where to find the access rights in the property hierarchy?

  1. Users will need to monitor the connection state of channels.

Within the protocol there is a channel disconnect exception designating a service disconnect. There might also be a transport circuit disconnect. The user will probably subscribe at the client programming interface for connection state change callbacks using the subscription mechanism. The client library will trap the appropriate exceptions and circuit disconnect state changes forwarding them as synthesized subscription update callbacks at the programming interface.

  1. The queueing versus caching behavior of write request sent to a channel will be modified by specifying a specialized IO request modifier with the write request.
  2. The EPICS function block database's process passive and maximize severity link attributes (or their future equivalents) will be manipulated by specifying a specialized IO request modifier.
  3. It will be necessary to introspect all of (or a subset of) the properties that are available in a channel. This will be accomplished by reading the propertyList property of the channel and requesting primitive type PSD or STRING.
  4. There will be situations where the client will prefer to create one channel, but index any part of the property hierarchy. This will be done by specifying the property path in a relevant IO request modifier.
  5. It will probably also be necessary to obtain a list of all of the communication receptacles in a server. This might be accomplished by sending a request / response command to a specialized PV. Wild cards could be specified in the request parameters and the channel list could be delivered in the response parameters.
  6. Within future EPICS systems a special property accompanying state change update notification payloads must efficiently indicate the type of state change that has occurred. For example, there are currently "default dead-band state change excursion", "archive dead-band state change excursion", and "alarm state change" state change identifying events. This information will be needed, for example, to improve the implementation of the CA gateway. Starting with version four of EPICS a PSD will define a special type for communicating this information, and a standard property name will be assigned for locating this information in a subscription update payload. This property will also be used in IO request modifiers to filter out state changes that might not be needed.
Retrieved from "https://wiki-ext.aps.anl.gov/epics/index.php?title=V4_CA_Protocol_Specification&oldid=570"