EPICS V4 Protocol Proposal

EPICS V4 Protocol EPICS V4 Protocol ProposalProposal

Jeff Hill

SummarySummary

BackgroundMotivationRequirementsSome ChoicesData TypesProtocolNext steps

BackgroundBackground

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

Motivation – Runtime Defined Motivation – Runtime Defined TypesTypes

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 Motivation – Runtime Defined TypesTypes

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

softwareLoose coupling doesn’t mean un-typed

ServerServer

Motivation – Recursive ServicesMotivation – Recursive Services

Request RDT

Response RDT

Request RDT

Response RDT

Response RDT

Request RDT

Server

Record

Device Support

Motivation – Recursive Services, Motivation – Recursive Services, ExamplesExamples

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 } }


Subscribe Request◦ Gateway subscribe request

{ request-modifiers { event-spec, max-rate, dead-band, filter-expression } }

◦ Server subscribe request{ request-modifiers { event-spec, max-rate, dead-band, filter-

expression } }◦ Record subscribe request

{ request-modifiers { event-spec, max-rate, dead-band, filter-expression } }

◦ Device Support subscribe Request{ request-modifiers { event-spec, max-rate, dead-band, filter-

expression } }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


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

Requirements – Backward Requirements – Backward CompatibilityCompatibility

All functionality available with legacy protocol available in new protocol

Both legacy and new protocol engines co-resident 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 – Runtime Defined Requirements – Runtime Defined TypesTypes

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 - EfficiencyRequirements - Efficiency

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 - ObviousRequirements - Obvious

Two’s complement signed integersIEEE floating pointSupport 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

Some ChoicesSome Choices

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 ChoicesSome Choices

Implemented as Services◦Channel name resolution◦Authentication◦Server diagnostics

Benefits◦Well defined boundaries allow

Multiple implementations and authors Site, project, culturally specific implementations

Data Types – PublicData Types – Public

Externally Visible Data Types

Mnemonic Wire Encoding Identifier

reserved 0

INT8 8 bit signed integer 1




FLOAT32 32 bit IEEE floating point 5



STRING UTF-8 encoded character string 8

Container See PTSD below 9

reserved 9 - 256

Data Types – Protocol PrivateData Types – Protocol Private

Protocol Private Data Types

Mnemonic Data Type

UINT8 8 bit unsigned integer

UNIT16 16 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 – UINTN, 1 or 2 OctetsData Types – UINTN, 1 or 2 Octets

UINTN - 1 Octet

Data Type Bit 7, msb Bits 7 - 0

OCTET 0Bits 0-7 of unsigned integer value

UINTN - 2 Octets

Data Type Bit 7, msb Bits 7 - 0



Data Types – UINTN, N OctetsData Types – UINTN, N Octets

Data Type msb Bits 7 - 0




... 1 ...

OCTET N 0Bits N*8-N*9-1 of unsigned integer value

Data Types – String, UTF-8Data Types – String, UTF-8

STRING

Data Type Purpose

UINTN the number of UTF-8 tokens

OCTET sequence UTF-8 encoded character string sequence (no nil termination)

Data Types – Dimension Sequence Data Types – Dimension Sequence Definition, Dimension Bound DefinitionDefinition, Dimension Bound Definition

Scalar Dimension SequenceData Type Purpose Value

UINTN Specifies that the data is scalar 0

Array Dimension SequenceData Type Purpose Value

UINTNSpecifies the number of property bounds definitions for array data

N, not zero

N X DBD sequence of N property bounds definitions Sender defined

Dimension Bound Definition, Fixed BoundData Type Purpose Value

UINTN Bound Type 0, fixed boundADB Array dimension bound Sender defined

Dimension Bound Definition, Variable BoundData Type Purpose Value

UINTN Bound Type 1, variable bound

Array Dimension BoundData Type Purpose Value

UINTN First element index Sender definedUINTN Element count Sender defined

Data Types – Property Transport Data Types – Property Transport Sequence DefinitionSequence Definition

Property Transport Sequence DefinitionData Type Purpose

UINTN Number of properties in sequenceN Property transport definitions See below

Property Transport Definition - AtomicData Type Purpose Value

UINTN Property Id Sender definedUINTN Data Type Identifier Sender defined, not 9DSD Dimension sequence description Sender defined

Property Transport Definition - ContainerData Type Purpose Value

UINTN Property Id Sender definedUINTN Data Type Identifier 9DSD Dimension sequence description Sender definedPSD Property transport sequence definition Sender defined

Property Transport SequenceProperty Transport Sequence

Packed binary Not naturally alignedAs specified, PTSD

Protocol – SummaryProtocol – Summary

Initiate Define, expunge

channel Swap channel IdsDefine, Expunge

Property IdSwap Property IdsDefine, 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 – InitiateProtocol – Initiate

Data Type Purpose Value

UINT16 Reserved for future use 0

UINT16 Reserved for future use 0

UINT16protocol 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 sequence number to detect duplicates and out of order delivery.

Reserved for future use with virtual circuits.

zero when it’s a virtual circuit, and otherwise the sequence number

Protocol – Define, Expunge Protocol – Define, Expunge ChannelChannel

Define Channel Request


UINTN Directive 1

UINTN Channel Identifier Sender defined

UINTN Property Transport Sequence Definition Identifier

PTS Channel Name, priority, … Sender defined

Expunge Channel Request


UINTN Directive 2

UINTN Channel Identifier Sender defined

Protocol – Swap Channel Protocol – Swap Channel IdentifiersIdentifiers

Swap Channel Identifiers Request


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


UINTN Request identifier Client defined

Protocol – Define PropertyProtocol – Define Property

Define Property Request


UINTN Directive 4

UINTN Property identifier Sender defined

STRING Property name Sender defined

Expunge Property Request


UINTN Directive 5

UINTN Property Identifier Sender defined

Channel name, optionally includes property hierarchy path

Protocol – Swap Property Protocol – Swap Property IdentifiersIdentifiers

Swap Property Identifiers Request


UINTN Directive 6


UINTN Property Identifier one Sender defined

UINTN Property Identifier two Sender defined

Swap Property Identifiers Successful Response



Protocol – Define, Expunge Protocol – Define, Expunge Property Transport SequenceProperty Transport Sequence

Define Property Transport Sequence Request


UINTN Directive 7

UINTN Property sequence identifier Sender defined

PTSD Property transport sequence definition Sender defined

Expunge Property Transport Sequence Request


UINTN Directive 8

UINTN Property transport sequence definition identifier Sender defined

Protocol - Protocol - Swap Property Transport Swap Property Transport Sequence Identifiers RequestSequence Identifiers Request

Swap Property Transport Sequence Identifiers RequestData Type Purpose Value

UINTN Directive 9UINTN Request identifier Sender definedUINTN Property Transport Sequence Identifier one Sender definedUINTN Property Transport Sequence Identifier two Sender defined

Swap Property Transport Sequence Identifiers Successful Response



Protocol – Write, UnacknowledgedProtocol – Write, Unacknowledged

Channel Write Request – Unacknowledged


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, AcknowledgedProtocol – Write, Acknowledged

Channel Write Request – With Acknowledge


UINTN Directive 11


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



Protocol - Channel Read or Protocol - Channel Read or SubscribeSubscribe

Channel Read or Subscribe RequestData Type Purpose Value

UINTN Directive 12 (rd), 13 (sub)UINTN Request identifier Sender definedUINTN Channel identifier Sender definedUINTN Property transport sequence definition identifier, request payload Sender definedUINTN Property transport sequence definition identifier, response payload Sender definedPTS Request modifiers payload Sender defined

Channel Read or Subscribe Successful Response



PTS Response property payload, read Client formatted, server defined

Protocol – Generic InvokeProtocol – Generic Invoke

Channel Generic Invoke Request


UINTN Directive 14


UINTN Channel identifier Sender defined

UINTNProperty transport sequence definition identifier, request payload

Sender defined

UINTNProperty transport sequence definition identifier, response payload

Sender defined

PTS Request property payload Sender defined

Channel Generic Invoke Successful Response



PTS Response property payload Client formatted, server defined

Protocol – Server VerifyProtocol – Server Verify

Server Verify Request


UINTN Directive 16


UINTNProperty transport sequence definition identifier, response payload

Sender defined

Circuit Verify Successful Response


OBJID Request identifier Client defined

PTS Server status parameters Client formatted, server defined

Next StepsNext Steps

Perhaps we form a working group◦Finalize list of our unique motivations,

requirements◦Design / review protocol definition

Write protocol libraries – we have the expertise

Documents

EPICS V4 Protocol Proposal