Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Known gaps

✅ Verified · no code on this page · docs-verify

The badge reports the whole docs-verify suite, not this chapter alone.

Divergences between what spvirit does and what an EPICS user would expect, found while writing this book and confirmed by running the code. Each one is documented where it bites, in the relevant chapter; this page collects them so you can scan the list before you spend an afternoon on one.

The list records current behaviour. It does not commit to fixing any item.

1. .db refuses record types that EPICS Base has

Given this file:

record(ai, "GAP:OK") {
  field(VAL, "1.0")
}
record(longin, "GAP:LONGIN") {
  field(VAL, "7")
}
record(mbbo, "GAP:MBBO") {
  field(ZRST, "Off")
  field(ONST, "On")
}
$ spserver --db-file gap_test.db
Error: "DB load error: record 'GAP:LONGIN' of type 'longin' is not yet supported by the .db loader; create it through the host API instead"

The whole load aborts at the first unsupported record, and none of the three records is served.

The cause is that to_record in spvirit-server/src/db.rs has no construction for mbbi/mbbo (which RecordType::from_db_name recognises) or for longin/longout (which it does not), and the typed loader turns either case into an error naming the record and its type. A .db file written for a real IOC that contains any of these four types therefore does not load.

To work around it, create those four types through the handle API (Pv::longin, Pv::mbbo, …). See Record types. The gap is also covered in Serving a .db file.

2. spput delivers a rejected write twice

A write a validator rejects reaches the server's on_put twice; an accepted write reaches it once. When the full EPICS-Base-style PUT flow fails, spput falls back to the simple flow without saying so (spvirit-tools/src/bin/spvirit_put.rs:241-249). Any on_put with a side effect (a log line, a counter, a hardware poke) therefore runs twice for exactly the writes you were trying to refuse.

Pass --no-flow-fallback, and write callbacks to be idempotent. See spput and Reacting to writes.

3. ADEL is parsed and exposed but not applied

MDEL gates monitor posts (should_post_update, spvirit-server/src/simple_store.rs:644). ADEL, the archive deadband, is read out of the .db file and readable as a field, and no posting logic consults it. A .db that relies on ADEL behaves as though it were absent.

4. Wire PUT is refused for generic structures

The Generic arm of RecordInstance::apply_put_fields (spvirit-server/src/apply.rs:710) has no wire PUT path, so a client PUT to a generic record is answered with a PUT error (no wire PUT path for this record type) and the record is left as it was. NtTable and NtEnum are wired. NtNdArray is wired for its metadata fields (codec, sizes, uniqueId, dimension, …), but the union-shaped image value a client sends is not applied. Write a generic record, or an NTNDArray image, server-side with store.put_nt().

5. The builder has no longin/longout

PvaServerBuilder covers fifteen record constructors and omits these two, which both the Rust handle API (Pv::longin, Pv::longout) and the Python module do have. Combined with gap 1, the builder and .db are the only two routes that cannot produce a longin. The matrix is on Record types.

6. CANCEL_REQUEST is unimplemented

The server answers PVA command CANCEL_REQUEST with "CANCEL_REQUEST command is not supported" (spvirit-server/src/handler.rs:2492). ACL_CHANGE, MESSAGE, MULTIPLE_DATA, ORIGIN_TAG and commands 14 and 16 likewise return errors. Clients that cancel a request rather than destroying the channel will see the error; the common clients do not.

7. Large values are sent as one frame, never segmented

spvirit reassembles segmented messages it receives (SegmentReassembler in spvirit-codec/src/segment.rs:34, driven by the client transport and the server handler), but it never emits them. encode_header (spvirit-codec/src/spvirit_encode.rs:98; the flag bits are written in push_header, :71-89) never sets the segmentation bits, and no encode path splits a payload, so a 4 MB NTNDArray goes out as a single PVA frame with a four-byte payload length where EPICS Base would split it. Clients that accept large unsegmented frames (pvxs, p4p, PVAJava) read it fine; a client that enforces a maximum frame size will not. Tracked as roadmap item 6 in Current State and Roadmap.

Gateway (M1): partial feature set

spgateway in M1 resolves, reads, writes and monitors PVs across networks. It enforces readOnly, pvlist and ACF access control, and serves a Prometheus /metrics endpoint (x-spvirit.metrics or --metrics). Audit, hot reload and rate limiting are not wired. The divergences below are deliberate for this milestone and are documented in full on the spgateway page.

Representation. The proxy round-trips through spvirit's decoded value model, which does not carry every PVAccess shape losslessly. An array-of-structure value (e.g. an NTNDArray dimension) is proxied as an index-keyed structure rather than a true array; union/any fields degrade; non-finite floats (NaN/Inf) become JSON null on the put path; and deeply nested structure IDs are best-effort.

Resolution. Only the first token of a client's addrlist is used. A p4p config with autoaddrlist:false plus an explicit unicast addrlist performs the unicast search, but also emits a subnet broadcast alongside the unicast probe; the underlying spvirit-client search branch cannot be changed from the gateway. Malformed addrlist/interface entries degrade silently rather than erroring.

Control plane. names() (what a downstream pvlist sees) reports only the names this gateway has already claimed, not a true fan-out of each upstream's pvlist. Upstream servers are found by per-name search (the client resolution cache remembers each PV's server address), and there is no per-client list of upstream server addresses to enumerate. rpc forwarding is not implemented: there is no general client RPC entry point yet, so an RPC to the gateway returns "gateway RPC forwarding is not implemented in M1".

Operations. The x-spvirit audit, hot-reload and rate-limit blocks are parsed and validated but not consumed. The metrics block and the per-server negativeCache block are consumed. The per-server acf-client field is parsed and validated against the clients[] list, but never consulted at runtime. Ctrl-C shutdown is immediate: outstanding requests are hard-cancelled rather than drained gracefully.

What is not on this list

Behaviour that is deliberate and merely surprising lives in the chapters, not here. Each of these is a gotcha on its own page:

  • mbbi refuses client writes. It is deliberately read-only over the wire in spvirit, where EPICS Base allows VAL writes to input records; drive it with pv.set(index).
  • spget accepts exactly one PV name.
  • spsine prints nothing on success.
  • discover and off suppress enumeration but not discovery.
  • spget's value column is a display rendering, not the wire value.

The full engineering picture — everything above plus the internal to-do list — is in Current State and Roadmap.