From 87f5e4b699719f755b5f7da51df8e9a91ce62d2d Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Fri, 12 Dec 2025 11:01:31 -0600 Subject: [PATCH] Various fixes to the new-notes files --- documentation/Makefile | 2 ++ documentation/new-notes/PR-624.md | 3 ++ documentation/new-notes/PR-626.md | 2 +- documentation/new-notes/PR-628.md | 2 +- documentation/new-notes/PR-636.md | 6 ++-- documentation/new-notes/PR-651.md | 6 ++-- documentation/new-notes/PR-688.md | 6 ++-- documentation/new-notes/PR-744.md | 19 +++++++----- modules/libcom/src/as/ACF-Language.md | 43 ++++++++++++++------------- 9 files changed, 50 insertions(+), 39 deletions(-) diff --git a/documentation/Makefile b/documentation/Makefile index d0ea3a273..69285bec8 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -13,6 +13,8 @@ DOXYGEN ?= doxygen include $(TOP)/documentation/Makefile.headers +HTMLS += ReleaseChecklist.html + HEADER_MD_FILES = $(foreach t, $(HEADER_TYPES), \ $(addsuffix _h.md, $($t_HEADERS))) API_RST_FILES = $(addsuffix -api.rst, $(HEADER_TYPES)) diff --git a/documentation/new-notes/PR-624.md b/documentation/new-notes/PR-624.md index 946b7bd24..390d0a04a 100644 --- a/documentation/new-notes/PR-624.md +++ b/documentation/new-notes/PR-624.md @@ -136,3 +136,6 @@ without breaking those IOCs or requiring their parser to be modified. This change **does not require any modifications to existing ACF files or downstream tools** -- all legacy syntax remains valid, and the new standardized grammar provides a robust foundation for future extensions. + +A full EBNF grammar for the new syntax can be found in the +[IOC Access Security](ACF-Language.md) document added to this release. diff --git a/documentation/new-notes/PR-626.md b/documentation/new-notes/PR-626.md index 2df0a077d..9e697f0e7 100644 --- a/documentation/new-notes/PR-626.md +++ b/documentation/new-notes/PR-626.md @@ -1,4 +1,4 @@ -*** Add `dbglob` to replace `dbgrep` +### Add `dbglob` to replace `dbgrep` A new IOC shell command, `dbglob` has been added, with `dbgrep` becoming an alias of this new function, with the intent of deprecating it in a diff --git a/documentation/new-notes/PR-628.md b/documentation/new-notes/PR-628.md index 8f2ae55eb..fde84abca 100644 --- a/documentation/new-notes/PR-628.md +++ b/documentation/new-notes/PR-628.md @@ -30,4 +30,4 @@ the starting point for documentation on all release changes. Detailed instructions on creating new entries are provided in a `README.txt` file in the `documentation/new-notes` directory. The release-time process that generates a new `RELEASE-.md` file is -described in the `documentation/ReleaseChecklist.html` file. +described in the developers' [Release Checklist](ReleaseChecklist.md). diff --git a/documentation/new-notes/PR-636.md b/documentation/new-notes/PR-636.md index 79ecd2248..fe4004e42 100644 --- a/documentation/new-notes/PR-636.md +++ b/documentation/new-notes/PR-636.md @@ -1,6 +1,6 @@ -### Add support for EPICS_DB_INCLUDE_PATH to dbLoadTemplate +### Add support for `EPICS_DB_INCLUDE_PATH` to `dbLoadTemplate` GitHub [PR #636](https://github.com/epics-base/epics-base/pull/636) -Allow finding the substitution file using path in `EPICS_DB_INCLUDE_PATH` or -an additional parameter to `dbLoadTemplate`. +Allow finding the substitution file through a path in `EPICS_DB_INCLUDE_PATH` or +an additional parameter to the iocsh `dbLoadTemplate` command. diff --git a/documentation/new-notes/PR-651.md b/documentation/new-notes/PR-651.md index 019dc07d7..0a61bde1a 100644 --- a/documentation/new-notes/PR-651.md +++ b/documentation/new-notes/PR-651.md @@ -1,12 +1,12 @@ ### Documentation Updates -The reference documentation for the [event](eventRecord.html) record type +The reference documentation for the [event](eventRecord.md) record type has been updated to cover the use of named events which were added in Base 3.14.12.3 and 3.15.1. Documentation for CALC expression evaluation has been updated for format enhancements and to add some missing operators. The best documentation for these expressions can be found in the -[postfix.h](postfix_h.html) header in libCom, but both the -[calc](calcRecord.html) and [calcout](calcoutRecord.html) record reference +[postfix.h](postfix_h.md) header in libCom, but both the +[calc](calcRecord.md) and [calcout](calcoutRecord.md) record reference pages also cover the infix expressions supported. diff --git a/documentation/new-notes/PR-688.md b/documentation/new-notes/PR-688.md index f36ef1de8..b52abfecc 100644 --- a/documentation/new-notes/PR-688.md +++ b/documentation/new-notes/PR-688.md @@ -1,6 +1,6 @@ ### `dfanout` improvements -The dfanout record now has invalid output handling with the usual fields -`IVOA` and `IVOV` just like other output records. +The [dfanout](dfanoutRecord.md) record now has invalid output handling with the usual fields +`IVOA` and `IVOV` just like many other output record types. -The number of output links has been increased from 8 to 16. +The number of output links has also been increased from 8 to 16. diff --git a/documentation/new-notes/PR-744.md b/documentation/new-notes/PR-744.md index 27dcbfadd..7add631bc 100644 --- a/documentation/new-notes/PR-744.md +++ b/documentation/new-notes/PR-744.md @@ -1,12 +1,17 @@ -### Avoid early expiration of timers on non-RTOS +### Avoid early expiration of timers on non-RTOS IOCs -Previously, the epicsTimer code rounded down user requested delays by subtracting one half -of the sleep "quantum". -On RTEMS and vxWorks, this allowed periodic timers which expired on every tick. -However, this also resulted in -timers expiring slightly [earlier than requested](https://github.com/epics-base/epics-base/issues/106). +Previously the epicsTimer code rounded down user requested delays +by subtracting one half of the sleep "quantum". +On RTEMS and vxWorks, +this allowed periodic timers which expired on every tick. +However this also resulted in timers expiring slightly +[earlier than requested](https://github.com/epics-base/epics-base/issues/106). With [PR 744](https://github.com/epics-base/epics-base/pull/744) rounding is only done for RTEMS and vxWorks, which still have tick timers. -This effects several facilities which use epicsTimer, including record delays. eg. `calcout.ODLY` becomes more [accurate](https://github.com/epics-base/epics-base/issues/106#issuecomment-1260232765). +This affects several facilities which use epicsTimer, +including record delays. +For example, `calcout.ODLY` becomes more +[accurate](https://github.com/epics-base/epics-base/issues/106#issuecomment-1260232765) +on non-RTOS IOCs. diff --git a/modules/libcom/src/as/ACF-Language.md b/modules/libcom/src/as/ACF-Language.md index 10a1458d4..393aad80f 100644 --- a/modules/libcom/src/as/ACF-Language.md +++ b/modules/libcom/src/as/ACF-Language.md @@ -1,9 +1,11 @@ -# ACF Syntax Forward Compatibility +# IOC Access Security + +## ACF Syntax Forward Compatibility EPICS 7.0.10 modified the Access Security Configuration File (ACF) parser to -**standardize the ACF grammar for forward compatibility**. +standardize the ACF grammar for forward compatibility. It did not change the syntax that was accepted by earlier versions of the parser, -so **existing access security configuration files will not need to be modified.** +so existing access security configuration files would not need to be modified. All ACF definitions will adhere to a consistent syntax format, which will allow future additions to the access security language without breaking existing configurations. @@ -124,22 +126,21 @@ the parser will report a syntax error. - Thus new elements can be added to ACF files in new EPICS releases without breaking older clients that loads those files. -In summary, **ACF forward compatibility** -means that from EPICS 7.0.10 onward, +In summary, ACF forward compatibility means that from EPICS 7.0.10 onward, any new access security features will use this established syntax. The parser will recognize new group types or rule options using the same `(...) { ... }` convention, ensuring they can be used in files loaded by IOCs running EPICS 7.0.10 or later without being rejected by those IOCs or requiring their parser to be modified. -This change **does not require any modifications to existing ACF files -or downstream tools** -- all legacy syntax remains valid, +This change does not require any modifications to existing ACF files -- +all legacy syntax remains valid, and the new standardized grammar provides a robust foundation for future extensions. --- -# Full Language Specification for Access Security Configuration Files +## Full Language Specification for Access Security Configuration Files -## Lexical tokens +### Lexical tokens **Ignored stuff** @@ -201,9 +202,9 @@ and the new standardized grammar provides a robust foundation for future extensi --- -## Grammar +### Grammar -### Top level +#### Top level ```ebnf acf-file ::= asconfig ; @@ -217,7 +218,7 @@ asconfig-item ::= | generic-top-level-item ; ``` -#### UAG / HAG groups +##### UAG / HAG groups ```ebnf uag-def ::= "UAG" uag-head [ uag-body ] ; @@ -239,7 +240,7 @@ hag-body ::= "{" hag-host-list "}" ; hag-host-list ::= STRING { "," STRING } ; ``` -#### ASG (access security group) +##### ASG (access security group) ```ebnf asg-def ::= "ASG" asg-head [ asg-body ] ; @@ -253,13 +254,13 @@ asg-body-item ::= | rule-config ; ``` -##### INP config +###### INP config ```ebnf inp-config ::= INP(link) "(" STRING ")" ;` ``` -##### RULE config +###### RULE config ```ebnf rule-config ::= "RULE" rule-head [ rule-body ] ; @@ -291,11 +292,11 @@ rule-uag-list ::= STRING { "," STRING } ; rule-hag-list ::= STRING { "," STRING } ;` ``` -#### Generic / future-proof syntax +##### Generic / future-proof syntax These are the "catch-all" constructs that are **parsed** but currently **ignored** semantically. -##### Keyword classes +###### Keyword classes These are parser-level categories used inside generic constructs: @@ -312,7 +313,7 @@ non-rule-keyword ::= | INP(link) ; (* INPA..INPU *) ``` -##### Generic head (argument list) +###### Generic head (argument list) ```ebnf generic-head ::= @@ -329,7 +330,7 @@ generic-element ::= | FLOAT ; ``` -##### Generic blocks +###### Generic blocks ```ebnf generic-block ::= @@ -345,7 +346,7 @@ generic-block-elem ::= generic-block-elem-name ::= keyword | STRING ; ``` -##### Generic top-level items +###### Generic top-level items These are "unknown" top-level constructs, all of which are parsed and then ignored with a warning. @@ -363,7 +364,7 @@ generic-list-block ::= "{" generic-element "}" "{" generic-list "}" ; ``` -##### Generic blocks inside RULE bodies +###### Generic blocks inside RULE bodies These are the "future predicates" in a RULE's body; they cause the RULE to be disabled with a warning, but they **must** still parse.