EPICS V4 Protocol
Proposal
Jeff Hill







Background
Motivation
Requirements
Some Choices
Data Types
Protocol
Next steps
Summary
An HTML document describing the
proposed protocol has existed for some
time
 On the EPICS wiki, but wasn't widely
viewed
 With this talk I am hoping for a wider
audience, and some additional
opportunity to receive feedback

Background

Implement put, get, and subscribe for
runtime defined types (RDTs)
1. Programming language – design time
defined - data structures
 Fixed during Client side tool’s design and
development
2. Configuration - run time defined - data types
 Types defined by an ASCII protocol and or GUIs
 Instances loaded via ASCII protocol and or GUIs
Motivation – Runtime Defined
Types

Loose coupling between runtime defined
types of client side tools and services
◦ Service type can be superset of the clients type
 Requires runtime introspection of types
◦ The flexibility to develop project, site, and
discipline specific extensions
 Interoperating with general purpose components
 w/o delays waiting for a new release of core
software

Loose coupling doesn’t mean un-typed
Motivation – Runtime Defined
Types
Server
Record
Device
Support
Request
RDT
Request
RDT
Request
Response
ServerServer
RDT
RDT
Response
RDT
Response
RDT
Motivation – Recursive Services

Put Request
◦ Gateway
{ value < rightAscension, declination > { time-stamp},
request-modifiers { db { process-passive } , synch-event-id } }
◦ Server
{ value < rightAscension, declination > { time-stamp},
request-modifiers { db { process-passive } , synch-event-id } }
◦ Record
{ value < rightAscension, declination > { time-stamp},
request-modifiers < db { process-passive } , synch-event-id }
}
◦ Device Support
{ value < rightAscension, declination > { time-stamp},
request-modifiers { synch-event-id } }
Motivation – Recursive Services,
Examples

Subscribe Request
◦ Gateway subscribe request
{ request-modifiers { event-spec, max-rate, dead-band, filterexpression } }
◦ Server subscribe request
{ request-modifiers { event-spec, max-rate, dead-band, filterexpression } }
◦ Record subscribe request
{ request-modifiers { event-spec, max-rate, dead-band, filterexpression } }
◦ Device Support subscribe Request
{ request-modifiers { event-spec, max-rate, dead-band, filterexpression } }

Each layer has multiple clients, single entity below
◦ Generalize N subscription request modifiers in scope
 To a less specific superset subscription request modifier
◦ Install new, timely removal of preexisting, subscription
Motivation – Recursive Services,
Examples

Subscribe Response
◦ Device support subscription update
{ value { time-stamp, LANSCE { beam-gate-state } >
◦ Record support subscription update
{ value { time-stamp, alarm-status,
LANSCE { beam-gate-state } >

Need both situations
◦ Generic clients work despite presence of
LANSCE beam-gate-state
◦ LANSCE specific clients benefit from presence
of beam-gate-state
Motivation – Recursive Services,
Examples
All functionality available with legacy
protocol available in new protocol
 Both legacy and new protocol engines coresident during, indefinite length,
transition period

◦ At large sites a staged transition must be
possible
◦ At some sites it might be optimistic to assume
that a transition will ever occur
Requirements – Backward
Compatibility

RDTs – a set of properties on the wire
◦ Their names
◦ Their transport order (can be hierarchical)
◦ Their transport primitive types

Topology learned from snap-ins at
runtime
◦ From the client side tool
◦ From service snap-in
Requirements – Runtime Defined
Types

Asynchronous request response behavior
◦ i.e. multiple simultaneous requests
Binary (not string) transport of binary
values
 Description of User defined types

◦ Can be communicated just once, and does not
accompany every instance of the data
Requirements - Efficiency
Two’s complement signed integers
 IEEE floating point
 Support for types used by 64 bit CPUs

◦ Will need disciplined conversion when larger
types are converted to smaller ones
 Data Access library takes care of this
◦ And, or software emulation on 32bit systems
Requirements - Obvious

Data elements are not naturally aligned
◦ Allows for more compact protocol
◦ Natural alignment doesn’t help that much
 When host, network octet order don’t match
 When TCP hands off data on any octet boundary
◦ Can cause double copying to occur

Network byte order for multi-octet
primitive types
◦ Somewhat arbitrary choice – we currently use
big-endian
Some Choices

Implemented as Services
◦ Channel name resolution
◦ Authentication
◦ Server diagnostics

Benefits
◦ Well defined boundaries allow
 Multiple implementations and authors
 Site, project, culturally specific implementations
Some Choices
Externally Visible Data Types
Mnemonic
Wire Encoding
Identifier
reserved
0
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
Container
See PTSD below
9
reserved
9 - 256
Data Types – Public
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
PTSD
property transport sequence definition
PTS
property transport sequence (variable, conforming to PTSD)
DSD
dimension sequence description
DBD
dimension bounds definition
ADB
array dimension bound
Data Types – Protocol Private
UINTN - 1 Octet
Data Type
OCTET
Bit 7, msb
Bits 7 - 0
0
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
0
Bits 8-15 of
unsigned integer
value
OCTET
Data Types – UINTN, 1 or 2 Octets
Data Type
msb
Bits 7 - 0
1
Bits 0-7 of
unsigned integer
value
1
Bits 8-15 of
unsigned integer
value
OCTET
1
Bits 16-23 of
unsigned integer
value
...
1
...
0
Bits N*8-N*9-1 of
unsigned integer
value
OCTET
OCTET
OCTET N
Data Types – UINTN, N Octets
STRING
Data Type
Purpose
UINTN
the number of UTF-8 tokens
OCTET sequence
UTF-8 encoded character string sequence (no nil termination)
Data Types – String, UTF-8
Data Type
UINTN
Data Type
UINTN
N X DBD
UINTN
Scalar Dimension Sequence
Purpose
Specifies that the data is scalar
Array Dimension Sequence
Purpose
Specifies the number of property bounds
definitions for array data
sequence of N property bounds definitions
0
Value
N, not zero
Sender defined
Dimension Bound Definition, Variable Bound
Data Type
Purpose
Value
Bound Type
1, variable bound
Data Type
UINTN
ADB
Data Type
UINTN
UINTN
Value
Dimension Bound Definition, Fixed Bound
Purpose
Value
Bound Type
0, fixed bound
Array dimension bound
Sender defined
Array Dimension Bound
Purpose
First element index
Element count
Value
Sender defined
Sender defined
Data Types – Dimension Sequence
Definition, Dimension Bound Definition
Property Transport Sequence Definition
Data Type
Purpose
UINTN
Number of properties in sequence
N Property transport definitions
See below
Data Type
UINTN
UINTN
DSD
Data Type
UINTN
UINTN
DSD
PSD
Property Transport Definition - Atomic
Purpose
Value
Property Id
Sender defined
Data Type Identifier
Sender defined, not 9
Dimension sequence description
Sender defined
Property Transport Definition - Container
Purpose
Value
Property Id
Sender defined
Data Type Identifier
9
Dimension sequence description
Sender defined
Property transport sequence definition
Sender defined
Data Types – Property Transport
Sequence Definition
Packed binary
 Not naturally aligned
 As specified, PTSD

Property Transport Sequence
Initiate
Define, expunge
channel
 Swap channel Ids
 Define, Expunge
Property Id
 Swap Property Ids
 Define, Expunge
Property Transport
Sequence
 Swap property
transport sequence
definition id



IO Requests
◦ Write, unacknowledged
◦
◦
◦
◦
Write, acknowledged
Read
Subscribe
Invoke
 Command / response
◦ Cancel

Server verify
Protocol – Summary
Data Type
Purpose
Value
UINT16
Reserved for future use
0
UINT16
Reserved for future use
0
UINT16
protocol minor revision
number
15
UINT32
magic number
0x5b43415d == '[' 'C' 'A' ']'
UNIT32
A sequence number
incrementing with each
successive message for
data-grams. Clients use this
zero when it’s a virtual
sequence number to detect
circuit, and otherwise the
duplicates and out of order
sequence number
delivery.
Reserved for future use
with virtual circuits.
Protocol – Initiate
Define Channel Request
Data Type
Purpose
Value
UINTN
Directive
1
UINTN
Channel Identifier
Sender defined
UINTN
Property Transport Sequence Definition Identifier
PTS
Channel Name, priority, …
Sender defined
Expunge Channel Request
Data Type
Purpose
Value
UINTN
Directive
2
UINTN
Channel Identifier
Sender defined
Protocol – Define, Expunge
Channel
Swap Channel Identifiers Request
Data Type
Purpose
Value
UINTN
Directive
3
UINTN
Request identifier
Sender defined
UINTN
Channel Identifier one
Sender defined
UINTN
Channel Identifier two
Sender defined
Swap Channel Identifiers Successful Response
Data Type
UINTN
Purpose
Request identifier
Value
Client defined
Protocol – Swap Channel
Identifiers
Define Property Request
Data Type
Purpose
Value
UINTN
Directive
4
UINTN
Property identifier
Sender defined
STRING
Property name
Sender defined
Expunge Property Request
Data Type
Purpose
Value
UINTN
Directive
5
UINTN
Property Identifier
Sender defined
Channel name, optionally includes property hierarchy path
Protocol – Define Property
Swap Property Identifiers Request
Data Type
Purpose
Value
UINTN
Directive
6
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
Protocol – Swap Property
Identifiers
Define Property Transport Sequence Request
Data Type
Purpose
Value
UINTN
Directive
7
UINTN
Property sequence identifier
Sender defined
PTSD
Property transport sequence definition
Sender defined
Expunge Property Transport Sequence Request
Data Type
Purpose
Value
UINTN
Directive
8
UINTN
Property transport sequence definition identifier
Sender defined
Protocol – Define, Expunge
Property Transport Sequence
Data Type
UINTN
UINTN
UINTN
UINTN
Swap Property Transport Sequence Identifiers Request
Purpose
Value
9
Directive
Request identifier
Sender defined
Property Transport Sequence Identifier one Sender defined
Property Transport Sequence Identifier two Sender defined
Swap Property Transport Sequence Identifiers Successful Response
Data Type
Purpose
Value
UINTN
Request identifier
Client defined
Protocol - Swap Property Transport
Sequence Identifiers Request
Channel Write Request – Unacknowledged
Data Type
Purpose
Value
UINTN
Directive
10
UNINT
Channel identifier
Sender defined
UINTN
Property transport sequence definition identifier, payload
Sender defined
PTS
Property payload to be written
Sender defined
Protocol – Write, Unacknowledged
Channel Write Request – With Acknowledge
Data Type
Purpose
Value
UINTN
Directive
11
UINTN
Request identifier
Sender defined
UNINT
Channel identifier
Sender defined
UINTN
Property transport sequence definition identifier, payload
Sender defined
PTS
Property payload to be written, including request modifiers
Sender defined
Channel Write Successful Response
Data Type
Purpose
Value
UINTN
Request identifier
Client defined
Protocol – Write, Acknowledged
Data Type
UINTN
UINTN
UINTN
UINTN
UINTN
PTS
Channel Read or Subscribe Request
Purpose
Value
12 (rd), 13 (sub)
Sender defined
Sender defined
Sender defined
Sender defined
Sender defined
Directive
Request identifier
Channel identifier
Property transport sequence definition identifier, request payload
Property transport sequence definition identifier, response payload
Request modifiers payload
Channel Read or Subscribe Successful Response
Data Type
Purpose
Value
UINTN
Request identifier
Client defined
PTS
Response property payload, read
Client formatted, server defined
Protocol - Channel Read or
Subscribe
Channel Generic Invoke Request
Data Type
Purpose
Value
UINTN
Directive
14
UINTN
Request identifier
Sender defined
UINTN
Channel identifier
Sender defined
UINTN
Property transport sequence definition
identifier, request payload
Sender defined
UINTN
Property transport sequence definition
identifier, response payload
Sender defined
PTS
Request property payload
Sender defined
Channel Generic Invoke Successful Response
Data Type
Purpose
Value
UINTN
Request identifier
Client defined
PTS
Response property payload
Client formatted, server defined
Protocol – Generic Invoke
Server Verify Request
Data Type
Purpose
Value
UINTN
Directive
16
UINTN
Request identifier
Sender defined
UINTN
Property transport sequence definition identifier,
Sender defined
response payload
Circuit Verify Successful Response
Data Type
Purpose
Value
OBJID
Request identifier
Client defined
PTS
Server status parameters
Client formatted, server defined
Protocol – Server Verify

Perhaps we form a working group
◦ Finalize list of our unique motivations,
requirements
◦ Design / review protocol definition

Write protocol libraries – we have the
expertise
Next Steps