From 33f3145fccc8ca6e56bfbbd1f44456f1eaa7e5ae Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 25 Apr 2017 22:52:08 -0500 Subject: [PATCH] Updates to Release Notes and links.html --- documentation/RELEASE_NOTES.html | 223 +++++++++++++++++++++++-------- src/std/link/links.dbd.pod | 45 ++++--- 2 files changed, 194 insertions(+), 74 deletions(-) diff --git a/documentation/RELEASE_NOTES.html b/documentation/RELEASE_NOTES.html index 0da4a7b4f..8e5509782 100644 --- a/documentation/RELEASE_NOTES.html +++ b/documentation/RELEASE_NOTES.html @@ -26,37 +26,70 @@

Most Soft Channel input device support routines have supported fetching the timestamp through the INP link along with the input data. However before now there was no guarantee that the timestamp provided by a CA link came from the -same update as the data, since the two were read at separate times without -maintaining a lock on the CA input buffer. This shortcoming has been fixed as -part of the new link support code, which allows code using a link to pass a -subroutine to the link type to be run with the link locked. The subroutine may -make multiple requests for metadata from the link, but must not block.

- -

Device Support Address Type JSON_LINK

- -

Device support may be written to expect hardware addresses in the new -JSON_LINK address type. Addresses loaded from a database file will be -checked against the JSON rules, and a strict JSON representation of the result -is provided as a C string pointed to by link.value.json.string.

- -

Currently the device support is responsible for parsing the JSON text itself. -An event-driven JSON parser library has been included in libCom since Base-3.15, -YAJL (Yet Another JSON Library) -Version 1.012, documented -here.

+same update as the data, since the two were read from the CA input buffer at +separate times without maintaining a lock on that buffer in between. This +shortcoming could be fixed as a result of the new link support code, which +allows code using a link to pass a subroutine to the link type which will be run +with the link locked. The subroutine may make multiple requests for metadata +from the link, but must not block.

-

JSON Link Addressing

+

Extensible Link Types

-

FIXME text missing here...

+

A major new feature introduced with this release of EPICS Base is an +Extensible Link Type mechanism, also known as Link Support or JSON Link Types. +This addition permits new kinds of link I/O to be added to an IOC in a similar +manner to the other extension points already supported (e.g. record, device and +driver support).

-

Support routine changes

+

A new link type must implement two related APIs, one for parsing the JSON +string which provides the link address and the other which implements the link +operations that get called at run-time to perform I/O. The link type is built +into the IOC by providing a new link entry in a DBD file.

+ + +

New Link Types Added

+ +

This release contains two new JSON link types, const and +calc:

+ + + +

The new link types are documented in a +separate +document +.

+ + +

Device Support Addressing using JSON_LINK

+ +

The API to allow device support to use JSON addresses is currently +incomplete; developers are advised not to try creating device support that +specifies a JSON_LINK address type.

+ + +

Support Routine Modifications for Extensible Link Types

For link fields in external record types and soft device support to be able -to use the new JSON link types properly, the following changes are -necessary:

+to use the new link types properly, various changes are required to utilize the +new Link Support API as defined in the dbLink.h header file and outlined below. +The existing built-in Database and Channel Access link types have been altered +to implement the link APIs, so will work properly after these conversions:

-

FIXME text missing here...

-

Constant Link Values

-

Previously a constant link (i.e. a link that does not point to another PV, -either local or over Channel Access) has only been able to provide a numeric -value; any string found in a link field that was not recognized as a number was -treated as a PV name. In this release, constant links may contain string values, -arrays, or even arrays of strings. These are indicated by ...

+

Previously a constant link (i.e. a link that did not point to another PV, +either locally or over Channel Access) was only able to provide a single numeric +value to a record initialization; any string given in a link field that was not +recognized as a number was treated as a PV name. In this release, constant links +can be expressed using JSON array syntax and may provide array initialization of +values containing integers, doubles or strings. An array containing a single +string value can also be used to initialize scalar strings, so the stringin, +stringout, lsi (long string input), lso (long string output), printf, waveform, +subArray and aai (analog array input) record types and/or their soft device +supports have been modified to support this.

-

FIXME text missing here...

+

Some examples of constant array and string initialized records are:

+ +
+  record(stringin, "const:string") {
+    field(INP, ["Not-a-PV-name"])
+  }
+  record(waveform, "const:longs") {
+    field(FTVL, LONG)
+    field(NELM, 10)
+    field(INP, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+  }
+  record(aai, "const:doubles") {
+    field(FTVL, DOUBLE)
+    field(NELM, 10)
+    field(INP, [0, 1, 1.6e-19, 2.718, 3.141593])
+  }
+  record(aSub, "select") {
+    field(FTA, STRING)
+    field(NOA, 4)
+    field(INPA, ["Zero", "One", "Two", "Three"])
+    field(FTB, SHORT)
+    field(NOB, 1)
+    field(FTVA, STRING)
+    field(NOVA, 1)
+    field(SNAM, "select_asub")
+  }
+
+ +

Reminder: Link initialization with constant values normally only occurs at +record initialization time. The calcout and printf record types are the only +exceptions in the Base record types to this rule, so it is generally not useful +to change a const link value after iocInit.

Database Parsing of "Relaxed JSON" Values

A database file can now provide a "relaxed JSON" value for a database field value or an info tag. Only a few field types can currently accept such values, -but the capability is now available for use in other places in the future. If a -JSON-capable field is written to at run-time though only strictly compliant JSON -may be used (the dbStaticLib parser rewrites relaxed JSON values into strict -JSON before passing them to the datase for interpretation, where the strict -rules must be followed).

+but the capability is now available for use in other places in the future. When +writing to a JSON-capable field at run-time however, only strictly compliant +JSON may be used (the dbStaticLib parser rewrites relaxed JSON values into +strict JSON before passing them to the datase for interpretation, where the +strict rules must be followed).

"Relaxed JSON" was developed to maximize compatibility with the previous database parser rules and reduce the number of double-quotes that would be -needed using strict JSON syntax. The parser will also accept strict JSON, which -should be used when machine-generating database files. The differences are:

+needed for strict JSON syntax. The parser does accept strict JSON too though, +which should be used when machine-generating database files. The differences +are: