EPICS V4 PV Gateway Requirements

EPICS V4 Working Group, Working Draft, 05-Jun-2014

Latest version:
requirements.html
This version:
requirements_20140605.html
Previous versions:
requirements_20140602.html
requirements_20140527.html
Editors:
Ralph Lange, ITER International Organization

Purpose and Scope of this Document

This document is gathering all requirements for the "EPICS V4 PV Gateway" component. This component proxies connections to PVs, possibly across network boundaries.

This document is mainly targeted to software architects, developers, and testers.

Status of this Document

This document is used to collect the requirements. It is not complete, and is intended to be a background for informed discussion and decision.

Once finalized and approved, this document will serve as input for specification, design, and test.

Table of Contents

Requirements Identification

The component identifier of the PV Gateway is 'PVGW'. The requirement identifiers are formatted as

PVGW-REQ-<req-category>-<req-number>

The requirement categories used in this document are:

Requirement Category ID
Functional F
External Interface I
Other O

General Description

Similar to the Channel Access Gateway component in EPICS V3, the PV Gateway component in EPICS V4 ("Gateway") will be an application embedding a server and a client of the network protocol(s) used, namely Channel Access (V3) and/or pvAccess (V4).

Its main function is to proxy connections, possibly across IP network boundaries.

This is done to shield the servers (IOCs) on the client side of the Gateway, by moving the tasks of resolving channel names and fanning out data updates to clients to the Gateway, which is expected to run on a machine with more resources and better network connection.

In this document, the clients of the Gateway will be referred to as "external", while the servers (e.g., IOCs) that the Gateway connects to on behalf of its external clients will be called "internal". This is solely done to clearly distinguish between the two sides of the Gateway.

Outline Design

The Gateway's server side listens to name resolution requests from external clients. If it finds the requested channel in its lists of active channels, it immediately replies. Else it forwards the request to the internal servers (or a different configured name server) and waits for the result before replying.

If a channel is valid, the Gateway opens the connection to the internal server, and acts on behalf of the external client.

For multiple external clients subscribing to the same channel in the same way, the Gateway keeps a single connection to the internal server, and fans out data updates from that connection to the external clients.

Functional Requirements

EPICS Network Protocol Requirements

PVGW-REQ-F-001 pvAccess Client

The Gateway should be able to connect to internal servers using the pvAccess network protocol of EPICS V4.

PVGW-REQ-F-002 pvAccess Server

The Gateway should provide channels on the external network by means of the pvAccess network protocol of EPICS V4.

PVGW-REQ-F-003 Configurable pvAccess Server

It should be possible to configure if the pvAccess server (PVGW-REQ-F-002) is started. This configuration should be defined at start-up, and is not required to be changeable at runtime.

PVGW-REQ-F-004 Redundant pvAccess Server Operation

It should be possible to run multiple Gateways with identical configuration in parallel, to allow failover and load balancing. This mode should not require special configuration on the external clients.

PVGW-REQ-F-011 Channel Access Client

The Gateway should be able to connect to internal servers using the Channel Access network protocol of EPICS V3.

PVGW-REQ-F-012 Channel Access Server

The Gateway should provide channels on the external network by means of the Channel Access network protocol of EPICS V3.

PVGW-REQ-F-013 Configurable Channel Access Server

It should be possible to configure if the Channel Access server (PVGW-REQ-F-012) is started. This configuration should be defined at start-up, and is not required to be changeable at runtime.

PVGW-REQ-F-021 Configurable Server Side Network Binding

On machines with multiple network interfaces, the Gateway should allow configuration of the network interfaces that its server(s) bind to. This configuration should be defined at start-up, and is not required to be changeable at runtime.

Data Flow Engine Requirements

PVGW-REQ-F-101 Full pvData Support

The Gateway should support transport of all pvData structures without restrictions. No legal pvData type should require recompilation or restart of the Gateway.

PVGW-REQ-F-102 Full Normative Type Support

The Gateway should support transport of all Normative Type (NT) structures without restrictions. it must not depend on specific properties of any NT.

PVGW-REQ-F-111 Low Latency for Large Structures/Arrays

The Gateway should add minimal latency when forwarding large structures or arrays. Sending data to the external clients should start immediately, and not require data structures to be received completely.

PVGW-REQ-F-112 Quality-of-Service Mechanisms

The Gateway should implement mechanisms to avoid negative effects of connections with large structures and arrays on connections to other PVs on the same internal server.

PVGW-REQ-F-121 Combine Sub-Structure Subscriptions

The Gateway should be able to combine external clients' subscriptions to different sub-structures of the same channel into one subscription to the internal server.

PVGW-REQ-F-122 Combine Request Configurations for Identical Subscriptions

The Gateway should be able to combine external clients' request configurations (pvRequest) for subscriptions to identical sub-structures of the same channel into one subscription to the internal server.

PVGW-REQ-F-131 Data Cache

The Gateway should be able to cache data, so that data for replies to get operations and initial updates on new subscriptions from external clients may be taken from the cache.

PVGW-REQ-F-132 Configurable Data Cache

Application of the "Data Cache" feature (PVGW-REQ-F-131) to get operations should be configurable, both globally and specifically on a channel name/regex base.

PVGW-REQ-F-141 Transparent Data Behavior

The Gateway should act completely transparent. When comparing a direct connection to a PV with a connection through the Gateway, order and contents of received data should be the same.

This does not apply to get operations, when data caching (PVGW-REQ-131) is enabled. In that case, the values returned from the cache may be different from the values in the internal server

PVGW-REQ-F-142 Transparent Out-of-Band Behavior

The Gateway should act transparent with respect to out-of-band behavior. When comparing a direct connection to a PV with a connection through the Gateway, out-of-band situations (e.g., connection loss, reconnection, non-existent PV) should produce the same exceptions in the same order.

PVGW-REQ-F-143 Transparent Timeout Behavior

The Gateway should act transparent with respect to timeouts. When comparing a direct connection to a PV with a connection through the Gateway, timeouts defined by the external client should be honored in the same way.

PVGW-REQ-F-151 Name Server

If the Gateway receives a name resolution request from an external client for a channel that it already serves, it should send an immediate positive reply to the request without querying the internal servers.

If the Gateway receives a name resolution request from an external client for a channel that it should serve, but lost connection to, it should send an immediate negative reply to the request without querying the internal servers.

If the Gateway receives a name resolution request from an external client for a channel that it was not able find recently (within a configurable interval), it should send an immediate negative reply to the request without querying the internal servers.

PVGW-REQ-F-161 Connection Cache

The Gateway should cache connections, i.e. keep the channel connection open with subscription disabled, for a configurable time after the last external client disconnected.

Authentication/Authorization Requirements

PVGW-REQ-F-201 Local AuthN/AuthZ

The Gateway should support a local layer of authentication and authorization, where authN/authZ for requests is decided possibly using an independent authN/authZ server, but without querying the internal server.

PVGW-REQ-F-202 Run-Time Configurable Local AuthN/AuthZ

The "Local AuthN/AuthZ" feature (PVGW-REQ-F-201) should be configurable at run-time. Activating a new configuration should not require a restart of the Gateway. Connections whose authZ does not change by the new configuration should not be affected.

PVGW-REQ-F-203 Proxy AuthN/AuthZ

The Gateway should support proxy authentication and authorization, where authorization for requests is decided by querying the internal server, using the credentials supplied by the external client.

PVGW-REQ-F-211 Transparent AuthZ Forwarding

The Gateway should transparently forward authorization changes on the internal connections to its external clients.

External Interface Requirements

PVGW-REQ-I-001 Statistics Data

The Gateway should provide statistical and performance data as pvData NT structures.

PVGW-REQ-I-002 Network Binding for Statistics Data

On machines with multiple network interfaces, the Gateway should allow configuration of the network interfaces that the statistics data (PVGW-REQ-I-001) server(s) bind to, independent from the equivalent setting of the data server(s) (PVGW-REQ-F-021). This configuration should be defined at start-up, and is not required to be changeable at runtime.

PVGW-REQ-I-011 Debugging Shell

The Gateway should provide a shell for debugging purposes, allowing to inspect its internal structures and lists, trace requests, set up debug log output filtered by channel or external client or internal server, etc.

Other Requirements

PVGW-REQ-O-001 Build Environment

The Gateway component should compile in a standard EPICS V4 build environment, using the standard EPICS V4 tools and compilers.

PVGW-REQ-O-002 Supported Platforms

The Gateway should be supported on all host type architectures/platforms officially supported by EPICS V4.

PVGW-REQ-O-003 SMP Support

The Gateway should be able to make use of SMP architectures, distributing load onto the available CPUs.


Ralph Lange, ITER International Organization.
2014-06-05