pvxs/documentation/ioc.rst

IOC Integration

#include <pvxs/iochooks.h>
namespace pvxs { namespace namespace ioc { ... } }

The separate pvxsIoc library exists to run a PVXS server as part of an IOC. See also includepvxs.

IOC Integration respects the $PVXS_LOG as well as the $EPICS_PVA* environment variables. Changes to this environment variable are possible prior to calling *_registerRecordDeviceDriver(pdbbase).

IOC shell

The pvxsIoc library adds several IOC shell functions which apply to all PVs served by the Integrated PVA server.

PVXS Server Report. Shows information about server configuration (level==0) or about connected clients (level>0). Indirectly calls pvxs::server::Source::show.

PVXS Server List. Lists attached Sources and PV names. Indirectly calls pvxs::server::Source::onList.

Print information about module versions, target, and toolchain. May be requested when reporting a bug.

Adding custom PVs to Server

pvxs::ioc::server

QSRV 2

Beginning with PVXS 1.2.0 the functionality of QSRV is replicated in the pvxsIoc library. Currently this feature preview is considered alpha level, with missing functionality. In addition to linking in libpvxsIoc, users must opt in at runtime by setting $PVXS_QSRV_ENABLE=YES before iocInit(). :

epicsEnvSet("PVXS_QSRV_ENABLE", "YES")
iocInit()

Functionality

The features of QSRV are divided into three broad categories.

• Single PV access
• Group PV access
• PVA Links

IOC Shell

IOC Shell commands specific to database integration.

Group PV information. At detail level 0, lists Group names. Pattern restricts listing to only matching names.

Load Group definitions from a separate JSON file. (as opposed to info(Q:group, {...}) in a .db file) See groupjson.

Single PV

When QSRV is enabled, access to individual/single PVs in the global process database is automatic and equivalent to the access provided by the Channel Access server in the IOC (aka. RSRV).

So caget pv:name and pvxget pv:name should be functionally equivalent.

Beginning with 1.2.3, long string detection is automatic in some cases. eg. .NAME and .INP. In some situations adding a $ suffix is still necessary when addressing a DBF_STRING or DBF_*LINK field to make it visible as a PVA string. It will not be necessary for clients to interpret a char[] as a "long string". :

# eg.
pvget some:record.NAME$
pvget some:record.INP$

An info(Q:form, "...") may be used to set the display.form PVA meta-data hint which is used by some OPI clients. :

record(longin, "my:bits") {
    field(VAL, "0x1234")
    info(Q:form, "Hex") # hint to clients to render as hexadecimal
}

or: :

record(waveform, "my:long:string") {
    field(FTVL, "CHAR")
    field(NELM, "1024")
    info(Q:form, "String") # hint to QSRV to expose char[] as string
}

Currently supported format hints are:

• Default
• String
• Binary
• Decimal
• Hex
• Exponential
• Engineering

Group PV

qgroup

Access Security

QSRV will enforce an optional access control policy file (.acf) loaded by asSetFilename(). This policy is applied to Single PVs just as RSRV does for Channel Access. With Group PVs, restrictions are not defined for the group, but rather for the individual member records. The same policy applies whether record is accessed individually, or through a group.

Policy application differs from CA (RSRV) in several ways:

Client hostname is always the numeric IP address. HAG() entries must either contained numeric IP addresses, or that asCheckClientIP=1 flag must be set to translate hostnames into IPs on ACF file load (effects CA server as well). This prevents clients from trivially forging "hostname". In additional to client usernames UAG() definitions may contained items beginning with role/ which are matched against the list of local systems groups of which the client username is a member. Username to group lookup is done locally by QSRV, and depends on IOC host authentication configuration. Note that this is still based on the client provided username string. :

UAG(special) {
    someone, "role/op"
}

The "special" UAG() will match CA or PVA clients with the username "someone". It will also match a PVA client if the "special" account exists locally, and is a member of the "op" group (supported on POSIX targets and Windows).

PVAccess Links

TODO...