From 7bd3e7aa2e2483bc4a2878742504fac2651487b0 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Fri, 21 Feb 2025 17:45:00 -0600 Subject: [PATCH 001/446] Update version numbers and submodules after release --- configure/CONFIG_BASE_VERSION | 7 ++----- configure/CONFIG_CA_VERSION | 4 ++-- configure/CONFIG_DATABASE_VERSION | 4 ++-- configure/CONFIG_LIBCOM_VERSION | 4 ++-- documentation/RELEASE_NOTES.md | 8 ++++++++ modules/normativeTypes | 2 +- modules/pvAccess | 2 +- modules/pvData | 2 +- modules/pvDatabase | 2 +- modules/pva2pva | 2 +- modules/pvaClient | 2 +- 11 files changed, 22 insertions(+), 17 deletions(-) diff --git a/configure/CONFIG_BASE_VERSION b/configure/CONFIG_BASE_VERSION index 86319c0323..eeb5778242 100644 --- a/configure/CONFIG_BASE_VERSION +++ b/configure/CONFIG_BASE_VERSION @@ -52,11 +52,11 @@ EPICS_MODIFICATION = 9 # EPICS_PATCH_LEVEL must be a number (win32 resource file requirement) # Not included in the official EPICS version number if zero -EPICS_PATCH_LEVEL = 0 +EPICS_PATCH_LEVEL = 1 # Immediately after an official release the EPICS_PATCH_LEVEL is incremented # and the -DEV suffix is added (similar to the Maven -SNAPSHOT versions) -EPICS_DEV_SNAPSHOT= +EPICS_DEV_SNAPSHOT=-DEV # No changes should be needed below here @@ -71,6 +71,3 @@ endif EPICS_SHORT_VERSION=$(EPICS_VERSION).$(EPICS_REVISION).$(EPICS_MODIFICATION)$(EPICS_PATCH_VSTRING) EPICS_VERSION_NUMBER=$(EPICS_SHORT_VERSION)$(EPICS_DEV_SNAPSHOT)$(EPICS_SITE_VSTRING) EPICS_VERSION_STRING="EPICS Version $(EPICS_VERSION_NUMBER)" - -# Provide this in case anyone is still using the old name -COMMIT_DATE="-no-date-" diff --git a/configure/CONFIG_CA_VERSION b/configure/CONFIG_CA_VERSION index 905f0d5904..770e1965f9 100644 --- a/configure/CONFIG_CA_VERSION +++ b/configure/CONFIG_CA_VERSION @@ -2,11 +2,11 @@ EPICS_CA_MAJOR_VERSION = 4 EPICS_CA_MINOR_VERSION = 14 -EPICS_CA_MAINTENANCE_VERSION = 5 +EPICS_CA_MAINTENANCE_VERSION = 6 # Development flag, set to zero for release versions -EPICS_CA_DEVELOPMENT_FLAG = 0 +EPICS_CA_DEVELOPMENT_FLAG = 1 # Immediately after a release the MAINTENANCE_VERSION # will be incremented and the DEVELOPMENT_FLAG set to 1 diff --git a/configure/CONFIG_DATABASE_VERSION b/configure/CONFIG_DATABASE_VERSION index 546c631102..5c5eae1eef 100644 --- a/configure/CONFIG_DATABASE_VERSION +++ b/configure/CONFIG_DATABASE_VERSION @@ -2,11 +2,11 @@ EPICS_DATABASE_MAJOR_VERSION = 3 EPICS_DATABASE_MINOR_VERSION = 24 -EPICS_DATABASE_MAINTENANCE_VERSION = 0 +EPICS_DATABASE_MAINTENANCE_VERSION = 1 # Development flag, set to zero for release versions -EPICS_DATABASE_DEVELOPMENT_FLAG = 0 +EPICS_DATABASE_DEVELOPMENT_FLAG = 1 # Immediately after a release the MAINTENANCE_VERSION # will be incremented and the DEVELOPMENT_FLAG set to 1 diff --git a/configure/CONFIG_LIBCOM_VERSION b/configure/CONFIG_LIBCOM_VERSION index d1546a9658..7f14874898 100644 --- a/configure/CONFIG_LIBCOM_VERSION +++ b/configure/CONFIG_LIBCOM_VERSION @@ -2,11 +2,11 @@ EPICS_LIBCOM_MAJOR_VERSION = 3 EPICS_LIBCOM_MINOR_VERSION = 24 -EPICS_LIBCOM_MAINTENANCE_VERSION = 0 +EPICS_LIBCOM_MAINTENANCE_VERSION = 1 # Development flag, set to zero for release versions -EPICS_LIBCOM_DEVELOPMENT_FLAG = 0 +EPICS_LIBCOM_DEVELOPMENT_FLAG = 1 # Immediately after a release the MAINTENANCE_VERSION # will be incremented and the DEVELOPMENT_FLAG set to 1 diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index e201d79e61..732c986548 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -12,6 +12,14 @@ The external PVA submodules each have their own individual release notes files. However the entries describing changes included in those submodules since EPICS 7.0.5 have now been copied into the appropriate place of this file. +__This version of EPICS has not been released yet.__ + +## Changes made on the 7.0 branch since 7.0.9 + +__Add new items below here__ + +----- + ## EPICS Release 7.0.9 ### Core documentation published at ReadTheDocs diff --git a/modules/normativeTypes b/modules/normativeTypes index 1250a3c236..7a2d264f2c 160000 --- a/modules/normativeTypes +++ b/modules/normativeTypes @@ -1 +1 @@ -Subproject commit 1250a3c236f0aa92e0b5bd73647fd71d8a09360d +Subproject commit 7a2d264f2cb107bfd10adb23bc2b73d8323a79e4 diff --git a/modules/pvAccess b/modules/pvAccess index 96061ca1cc..dafb6aad31 160000 --- a/modules/pvAccess +++ b/modules/pvAccess @@ -1 +1 @@ -Subproject commit 96061ca1cc6d0e101b0033635396a8e6b6add68c +Subproject commit dafb6aad31a99f8d825a1f77aa919c82bb28e0cf diff --git a/modules/pvData b/modules/pvData index 0ef8a36172..1c5f75bcd6 160000 --- a/modules/pvData +++ b/modules/pvData @@ -1 +1 @@ -Subproject commit 0ef8a361721bc4972743a9c9a0112f441ba36b0f +Subproject commit 1c5f75bcd6c387f5913076027e54cf7312b25643 diff --git a/modules/pvDatabase b/modules/pvDatabase index 8cf550ff57..073d2acafc 160000 --- a/modules/pvDatabase +++ b/modules/pvDatabase @@ -1 +1 @@ -Subproject commit 8cf550ff57ab8b573a95af2e9602643b8af98110 +Subproject commit 073d2acafc7109178d319109ad435131a80fed0e diff --git a/modules/pva2pva b/modules/pva2pva index 3a08da445b..8fa231352d 160000 --- a/modules/pva2pva +++ b/modules/pva2pva @@ -1 +1 @@ -Subproject commit 3a08da445b46e2e7029406d24425cdd3dfd7da24 +Subproject commit 8fa231352dac32c08734eb04cf4b12e76895a261 diff --git a/modules/pvaClient b/modules/pvaClient index a34876e36a..09cf317521 160000 --- a/modules/pvaClient +++ b/modules/pvaClient @@ -1 +1 @@ -Subproject commit a34876e36a56c9de9b172d6a83a9439bb330783d +Subproject commit 09cf317521bfa172e3e00a5631bf0c70b88157ba From 131578124b2e5baf7cb1d6b8fd3e2a7b75001fe7 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Fri, 21 Feb 2025 09:58:43 +0100 Subject: [PATCH 002/446] ci: drop AppVeyor builds on VS2010/VS2012 --- .appveyor.yml | 7 ------- .appveyor/epics-base-7.yml | 7 ------- 2 files changed, 14 deletions(-) diff --git a/.appveyor.yml b/.appveyor.yml index cf65349060..7632b32c4e 100644 --- a/.appveyor.yml +++ b/.appveyor.yml @@ -52,8 +52,6 @@ environment: APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017 - CMP: vs2015 - CMP: vs2013 - - CMP: vs2012 - - CMP: vs2010 - CMP: gcc APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019 # TODO: static linking w/ readline isn't working. Bypass auto-detect @@ -67,11 +65,6 @@ platform: # Matrix configuration: exclude sets of jobs matrix: exclude: - # VS2012 and older installs don't have the 64 bit compiler - - platform: x64 - CMP: vs2012 - - platform: x64 - CMP: vs2010 # Exclude more jobs to reduce build time # Skip 32-bit for "middle-aged" compilers - platform: x86 diff --git a/.appveyor/epics-base-7.yml b/.appveyor/epics-base-7.yml index 218577c281..8616544e90 100644 --- a/.appveyor/epics-base-7.yml +++ b/.appveyor/epics-base-7.yml @@ -59,8 +59,6 @@ environment: APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017 - CMP: vs2015 - CMP: vs2013 - - CMP: vs2012 - - CMP: vs2010 - CMP: gcc APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019 # TODO: static linking w/ readline isn't working. Bypass auto-detect @@ -74,11 +72,6 @@ platform: # Matrix configuration: exclude sets of jobs matrix: exclude: - # VS2012 and older installs don't have the 64 bit compiler - - platform: x64 - CMP: vs2012 - - platform: x64 - CMP: vs2010 # Exclude more jobs to reduce build time # Skip 32-bit for "middle-aged" compilers - platform: x86 From 43e75e3901d82f2c985ecff364dec70b6cee6af0 Mon Sep 17 00:00:00 2001 From: Dirk Zimoch Date: Tue, 27 Aug 2024 11:52:25 +0200 Subject: [PATCH 003/446] decorate functions that do not return --- modules/ca/src/client/acctst.c | 4 +--- modules/ca/src/client/caDiagnostics.h | 3 ++- modules/libcom/src/flex/flexdef.h | 6 +++--- modules/libcom/src/misc/cantProceed.h | 3 ++- modules/libcom/src/misc/epicsExit.h | 4 +++- modules/libcom/src/misc/epicsUnitTest.h | 3 ++- modules/libcom/src/osi/compiler/clang/compilerSpecific.h | 5 +++++ modules/libcom/src/osi/compiler/gcc/compilerSpecific.h | 5 +++++ modules/libcom/src/osi/compiler/msvc/compilerSpecific.h | 5 +++++ modules/libcom/src/osi/compilerDependencies.h | 4 ++++ modules/libcom/src/osi/epicsThread.h | 1 + modules/libcom/src/yacc/defs.h | 2 +- 12 files changed, 34 insertions(+), 11 deletions(-) diff --git a/modules/ca/src/client/acctst.c b/modules/ca/src/client/acctst.c index 44cc0673a6..101da24c11 100644 --- a/modules/ca/src/client/acctst.c +++ b/modules/ca/src/client/acctst.c @@ -3396,7 +3396,7 @@ void verifyContextRundownChanStillExist ( showProgressEnd ( interestLevel ); } -int acctst ( const char * pName, unsigned interestLevel, unsigned channelCount, +void acctst ( const char * pName, unsigned interestLevel, unsigned channelCount, unsigned repetitionCount, enum ca_preemptive_callback_select select ) { chid chan; @@ -3549,8 +3549,6 @@ int acctst ( const char * pName, unsigned interestLevel, unsigned channelCount, printf ( "\nTest Complete\n" ); epicsExit ( EXIT_SUCCESS ); - - return 0; } diff --git a/modules/ca/src/client/caDiagnostics.h b/modules/ca/src/client/caDiagnostics.h index 5bf1755bc3..019913e1c9 100644 --- a/modules/ca/src/client/caDiagnostics.h +++ b/modules/ca/src/client/caDiagnostics.h @@ -20,7 +20,8 @@ extern "C" { enum appendNumberFlag {appendNumber, dontAppendNumber}; int catime ( const char *channelName, unsigned channelCount, enum appendNumberFlag appNF ); -int acctst ( const char *pname, unsigned logggingInterestLevel, +EPICS_NORETURN +void acctst ( const char *pname, unsigned logggingInterestLevel, unsigned channelCount, unsigned repetitionCount, enum ca_preemptive_callback_select select ); diff --git a/modules/libcom/src/flex/flexdef.h b/modules/libcom/src/flex/flexdef.h index dd6123da28..e0822f3675 100644 --- a/modules/libcom/src/flex/flexdef.h +++ b/modules/libcom/src/flex/flexdef.h @@ -696,16 +696,16 @@ extern void dataend (void); extern void flexerror (char[]) NORETURN; /* report a fatal error message and terminate */ -extern void flexfatal (char[]); +extern void flexfatal (char[]) NORETURN; /* return current time */ extern char *flex_gettime(); /* report an error message formatted with one integer argument */ -extern void lerrif (char[], int); +extern void lerrif (char[], int) NORETURN; /* report an error message formatted with one string argument */ -extern void lerrsf (char[], char[]); +extern void lerrsf (char[], char[]) NORETURN; /* spit out a "# line" statement */ extern void line_directive_out (FILE*); diff --git a/modules/libcom/src/misc/cantProceed.h b/modules/libcom/src/misc/cantProceed.h index f9559b14ce..2150ead3f2 100644 --- a/modules/libcom/src/misc/cantProceed.h +++ b/modules/libcom/src/misc/cantProceed.h @@ -43,7 +43,8 @@ extern "C" { * \param errorMessage A printf-style error message describing the error. * \param ... Any parameters required for the error message. */ -LIBCOM_API void cantProceed( +LIBCOM_API EPICS_NORETURN +void cantProceed( EPICS_PRINTF_FMT(const char *errorMessage), ... ) EPICS_PRINTF_STYLE(1,2); diff --git a/modules/libcom/src/misc/epicsExit.h b/modules/libcom/src/misc/epicsExit.h index 304094e8dc..4a837e977f 100644 --- a/modules/libcom/src/misc/epicsExit.h +++ b/modules/libcom/src/misc/epicsExit.h @@ -23,6 +23,7 @@ #ifndef epicsExith #define epicsExith #include +#include "compilerDependencies.h" #ifdef __cplusplus extern "C" { @@ -38,7 +39,8 @@ typedef void (*epicsExitFunc)(void *arg); * \brief Calls epicsExitCallAtExits(), then the OS exit() routine. * \param status Passed to exit() */ -LIBCOM_API void epicsExit(int status); +LIBCOM_API EPICS_NORETURN +void epicsExit(int status); /** * \brief Arrange to call epicsExit() later from a low priority thread. * diff --git a/modules/libcom/src/misc/epicsUnitTest.h b/modules/libcom/src/misc/epicsUnitTest.h index eea53335ff..1f51eeeb2c 100644 --- a/modules/libcom/src/misc/epicsUnitTest.h +++ b/modules/libcom/src/misc/epicsUnitTest.h @@ -223,7 +223,8 @@ LIBCOM_API void testTodoEnd(void); * \param fmt A printf-style format string giving the reason for stopping. * \param ... Any parameters required for the format string. */ -LIBCOM_API void testAbort(EPICS_PRINTF_FMT(const char *fmt), ...) +LIBCOM_API EPICS_NORETURN +void testAbort(EPICS_PRINTF_FMT(const char *fmt), ...) EPICS_PRINTF_STYLE(1, 2); /** @} */ diff --git a/modules/libcom/src/osi/compiler/clang/compilerSpecific.h b/modules/libcom/src/osi/compiler/clang/compilerSpecific.h index 6bba842eeb..bf2474a556 100644 --- a/modules/libcom/src/osi/compiler/clang/compilerSpecific.h +++ b/modules/libcom/src/osi/compiler/clang/compilerSpecific.h @@ -58,4 +58,9 @@ */ #define EPICS_UNUSED __attribute__((unused)) +/* + * No return marker + */ +#define EPICS_NORETURN __attribute__((noreturn)) + #endif /* ifndef compilerSpecific_h */ diff --git a/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h b/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h index d56d32212d..47d06780f0 100644 --- a/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h +++ b/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h @@ -57,4 +57,9 @@ */ #define EPICS_UNUSED __attribute__((unused)) +/* + * No return marker + */ +#define EPICS_NORETURN __attribute__((noreturn)) + #endif /* ifndef compilerSpecific_h */ diff --git a/modules/libcom/src/osi/compiler/msvc/compilerSpecific.h b/modules/libcom/src/osi/compiler/msvc/compilerSpecific.h index 631da4f385..8e274fcaec 100644 --- a/modules/libcom/src/osi/compiler/msvc/compilerSpecific.h +++ b/modules/libcom/src/osi/compiler/msvc/compilerSpecific.h @@ -51,4 +51,9 @@ # define EPICS_PRINTF_FMT(a) _Printf_format_string_ a #endif +/* + * No return marker + */ +#define EPICS_NORETURN __declspec(noreturn) + #endif /* ifndef compilerSpecific_h */ diff --git a/modules/libcom/src/osi/compilerDependencies.h b/modules/libcom/src/osi/compilerDependencies.h index dc574c44a4..55762ee207 100644 --- a/modules/libcom/src/osi/compilerDependencies.h +++ b/modules/libcom/src/osi/compilerDependencies.h @@ -52,6 +52,10 @@ # define EPICS_UNUSED #endif +#ifndef EPICS_NORETURN +# define EPICS_NORETURN +#endif + #ifndef EPICS_FUNCTION #if (defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901)) || (defined(__cplusplus) && __cplusplus>=201103L) # define EPICS_FUNCTION __func__ diff --git a/modules/libcom/src/osi/epicsThread.h b/modules/libcom/src/osi/epicsThread.h index c8035685b1..fcd96e5747 100644 --- a/modules/libcom/src/osi/epicsThread.h +++ b/modules/libcom/src/osi/epicsThread.h @@ -437,6 +437,7 @@ class LIBCOM_API epicsThread { epicsThread ( const epicsThread & ); epicsThread & operator = ( const epicsThread & ); friend void epicsThreadCallEntryPoint ( void * ); + EPICS_NORETURN void printLastChanceExceptionMessage ( const char * pExceptionTypeName, const char * pExceptionContext ); diff --git a/modules/libcom/src/yacc/defs.h b/modules/libcom/src/yacc/defs.h index 516eea6800..8906150cea 100644 --- a/modules/libcom/src/yacc/defs.h +++ b/modules/libcom/src/yacc/defs.h @@ -297,7 +297,7 @@ extern void tokenized_start(char *s) NORETURN; extern void retyped_warning(char *s); extern void reprec_warning(char *s); extern void revalued_warning(char *s); -extern void terminal_start(char *s); +extern void terminal_start(char *s) NORETURN; extern void restarted_warning(void); extern void no_grammar(void) NORETURN; extern void terminal_lhs(int s_lineno) NORETURN; From 78f263f3590184ae23e5a21609889f53012a60b2 Mon Sep 17 00:00:00 2001 From: Ralph Lange Date: Wed, 5 Mar 2025 16:55:32 +0100 Subject: [PATCH 004/446] Update GitHub Actions build configuration (#609) * ci: bump GHA ubuntu jobs (22->24, 20->22) * ci: add GHA job for CentOS-7 on self-managed Docker * ci: add jobs for CentOS-8 and Rocky-9 on GHA-managed Docker --- .github/workflows/ci-scripts-build.yml | 162 +++++++++++++++---------- 1 file changed, 100 insertions(+), 62 deletions(-) diff --git a/.github/workflows/ci-scripts-build.yml b/.github/workflows/ci-scripts-build.yml index f7c53909c4..d26291526f 100644 --- a/.github/workflows/ci-scripts-build.yml +++ b/.github/workflows/ci-scripts-build.yml @@ -50,9 +50,9 @@ jobs: matrix: # Job names also name artifacts, character limitations apply include: - - os: ubuntu-22.04 - cmp: gcc-12 - name: "Ub-22 gcc-12 c++20 Werror" + - os: ubuntu-24.04 + cmp: gcc + name: "Ub-24 gcc-13 c++20 Werror" # Turn all warnings into errors, # except for those we could not fix (yet). # Remove respective -Wno-error=... flag once it is fixed. @@ -73,79 +73,79 @@ jobs: -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3' CMD_LDFLAGS=-Wl,-z,relro" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default cross: "windows-x64-mingw" - name: "Ub-20 gcc + MinGW" + name: "Ub-22 gcc + MinGW" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: static cross: "windows-x64-mingw" - name: "Ub-20 gcc + MinGW, static" + name: "Ub-22 gcc + MinGW, static" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: static extra: "CMD_CXXFLAGS=-std=c++11" - name: "Ub-20 gcc C++11, static" + name: "Ub-22 gcc C++11, static" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: static extra: "CMD_CFLAGS=-funsigned-char CMD_CXXFLAGS=-funsigned-char" - name: "Ub-20 gcc unsigned char" + name: "Ub-22 gcc unsigned char" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: clang configuration: default - name: "Ub-20 clang" + name: "Ub-22 clang" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: clang configuration: default extra: "CMD_CXXFLAGS=-std=c++11" - name: "Ub-20 clang C++11" + name: "Ub-22 clang C++11" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default cross: "RTEMS-pc686-qemu@5" - name: "Ub-20 gcc + RT-5.1 pc686" + name: "Ub-22 gcc + RT-5.1 pc686" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default cross: "RTEMS-beatnik@5" test: NO - name: "Ub-20 gcc + RT-5.1 beatnik" + name: "Ub-22 gcc + RT-5.1 beatnik" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default cross: "RTEMS-xilinx_zynq_a9_qemu@5" test: NO - name: "Ub-20 gcc + RT-5.1 xilinx_zynq_a9_qemu" + name: "Ub-22 gcc + RT-5.1 xilinx_zynq_a9_qemu" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default cross: "RTEMS-uC5282@5" test: NO - name: "Ub-20 gcc + RT-5.1 uC5282" + name: "Ub-22 gcc + RT-5.1 uC5282" - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default - name: "Ub-20 gcc + RT-4.10" + name: "Ub-22 gcc + RT-4.10" cross: "RTEMS-pc386-qemu@4.10" test: NO - - os: ubuntu-20.04 + - os: ubuntu-22.04 cmp: gcc configuration: default - name: "Ub-20 gcc + RT-4.9" + name: "Ub-22 gcc + RT-4.9" cross: "RTEMS-pc386-qemu@4.9" - os: macos-latest @@ -239,10 +239,15 @@ jobs: matrix: # Job names also name artifacts, character limitations apply include: - #- name: "CentOS-7" - # image: centos:7 - # cmp: gcc - # configuration: default + - name: "CentOS-8" + image: centos:8 + cmp: gcc + configuration: default + + - name: "Rocky-9" + image: rockylinux:9 + cmp: gcc + configuration: default - name: "Fedora-33" image: fedora:33 @@ -255,47 +260,29 @@ jobs: configuration: default steps: - - name: "Build newer Git" - # actions/checkout@v2 wants git >=2.18 - # centos:7 has 1.8 - if: matrix.image=='centos:7' + - name: "Fix repo URLs on CentOS-8" + # centos:8 is frozen, repos are in the vault + if: matrix.image=='centos:8' run: | - yum -y install curl make gcc curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-ExtUtils-MakeMaker - curl https://mirrors.edge.kernel.org/pub/software/scm/git/git-2.29.0.tar.gz | tar -xz - cd git-* - make -j2 prefix=/usr/local all - make prefix=/usr/local install - cd .. - rm -rf git-* - type -a git - git --version + sed -i -e "s|mirrorlist=|#mirrorlist=|" \ + -e "s|#baseurl=http://mirror|baseurl=http://vault|" \ + /etc/yum.repos.d/CentOS-Linux-{BaseOS,AppStream,Extras,Plus}.repo - name: "Redhat setup" run: | - dnfyum() { - dnf -y "$@" || yum -y "$@" - return $? - } - dnfyum install python3 gdb make perl gcc-c++ glibc-devel readline-devel ncurses-devel perl-devel perl-Test-Simple - git --version || dnfyum install git - # rather than just bite the bullet and link python3 -> python, - # people would rather just break all existing scripts... - [ -e /usr/bin/python ] || ln -sf python3 /usr/bin/python - python --version + dnf -y install python3 gdb make perl gcc-c++ glibc-devel readline-devel ncurses-devel perl-devel perl-Test-Simple + git --version || dnf -y install git + python3 --version - uses: actions/checkout@v4 with: submodules: true - name: Automatic core dumper analysis uses: mdavidsaver/ci-core-dumper@master - if: matrix.image!='centos:7' - - name: Automatic core dumper analysis - uses: mdavidsaver/ci-core-dumper@node16 - if: matrix.image=='centos:7' - name: Prepare and compile dependencies - run: python .ci/cue.py prepare + run: python3 .ci/cue.py prepare - name: Build main module - run: python .ci/cue.py build + run: python3 .ci/cue.py build - name: Run main module tests - run: python .ci/cue.py -T 20M test + run: python3 .ci/cue.py -T 20M test - name: Upload tapfiles Artifact if: ${{ always() }} uses: actions/upload-artifact@v4 @@ -305,4 +292,55 @@ jobs: if-no-files-found: ignore - name: Collect and show test results if: ${{ always() }} - run: python .ci/cue.py -T 5M test-results + run: python3 .ci/cue.py -T 5M test-results + + build-docker: + name: Docker CentOS-7 + runs-on: ubuntu-latest + env: + CMP: gcc + BCFG: default + + steps: + - uses: actions/checkout@v4 + with: + submodules: true + + - name: Run... + run: | + env > env.list + cat < runit.sh + #!/bin/sh + set -e -x + cd /io + id + + sed -i s/mirror.centos.org/vault.centos.org/g /etc/yum.repos.d/*.repo + sed -i s/^#.*baseurl=http/baseurl=http/g /etc/yum.repos.d/*.repo + sed -i s/^mirrorlist=http/#mirrorlist=http/g /etc/yum.repos.d/*.repo + yum -y install epel-release + yum -y install \ + curl make gcc curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-ExtUtils-MakeMaker \ + python3 gdb make perl gcc-c++ glibc-devel readline-devel ncurses-devel perl-devel perl-Test-Simple \ + libevent-devel sudo re2c + [ -e /usr/bin/python ] || ln -sf /usr/bin/python3 /usr/bin/python + + # fake out cue.py + ln -s /bin/true /usr/bin/apt-get + + # quiet warnings spam from perl + export LANG=C + + python --version + python .ci/cue.py prepare + python .ci/cue.py build + python .ci/cue.py -T 15M test + python .ci/cue.py test-results + EOF + chmod +x runit.sh + docker run --rm --quiet \ + --pull=always \ + --env-file env.list \ + -v `pwd`:/io \ + centos:7 \ + /io/runit.sh From ee1a49045a96eb780a8a7744b0951f67ee87e158 Mon Sep 17 00:00:00 2001 From: Dirk Zimoch Date: Wed, 26 Feb 2025 16:39:02 +0100 Subject: [PATCH 005/446] support CROSS_COMPILER_RUNTESTS_ARCHS other than RTEMS --- modules/database/test/ioc/db/Makefile | 4 ++-- modules/database/test/std/filters/Makefile | 4 ++-- modules/database/test/std/link/Makefile | 4 ++-- modules/database/test/std/rec/Makefile | 4 ++-- modules/libcom/test/Makefile | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/modules/database/test/ioc/db/Makefile b/modules/database/test/ioc/db/Makefile index 4395c291e1..369bac9d77 100644 --- a/modules/database/test/ioc/db/Makefile +++ b/modules/database/test/ioc/db/Makefile @@ -208,8 +208,8 @@ TESTSPEC_RTEMS = dbTestHarness.boot; epicsRunDbTests TESTSCRIPTS_HOST += $(TESTS:%=%.t) ifneq ($(filter $(T_A),$(CROSS_COMPILER_RUNTEST_ARCHS)),) -TESTPROD_RTEMS = $(TESTPROD_HOST) -TESTSCRIPTS_RTEMS += $(TESTS:%=%.t) +TESTPROD += $(TESTPROD_HOST) +TESTSCRIPTS += $(TESTS:%=%.t) endif include $(TOP)/configure/RULES diff --git a/modules/database/test/std/filters/Makefile b/modules/database/test/std/filters/Makefile index 2576ce46d8..e078b37276 100644 --- a/modules/database/test/std/filters/Makefile +++ b/modules/database/test/std/filters/Makefile @@ -81,8 +81,8 @@ TESTSPEC_RTEMS = filterTestHarness.boot; epicsRunFilterTests TESTSCRIPTS_HOST += $(TESTS:%=%.t) ifneq ($(filter $(T_A),$(CROSS_COMPILER_RUNTEST_ARCHS)),) -TESTPROD_RTEMS = $(TESTPROD_HOST) -TESTSCRIPTS_RTEMS += $(TESTS:%=%.t) +TESTPROD += $(TESTPROD_HOST) +TESTSCRIPTS += $(TESTS:%=%.t) endif include $(TOP)/configure/RULES diff --git a/modules/database/test/std/link/Makefile b/modules/database/test/std/link/Makefile index fca0899667..e4410d76e0 100644 --- a/modules/database/test/std/link/Makefile +++ b/modules/database/test/std/link/Makefile @@ -57,8 +57,8 @@ TESTSPEC_RTEMS = linkTestHarness.boot; epicsRunLinkTests TESTSCRIPTS_HOST += $(TESTS:%=%.t) ifneq ($(filter $(T_A),$(CROSS_COMPILER_RUNTEST_ARCHS)),) - TESTPROD = $(TESTPROD_HOST) - TESTSCRIPTS_RTEMS += $(TESTS:%=%.t) + TESTPROD += $(TESTPROD_HOST) + TESTSCRIPTS += $(TESTS:%=%.t) endif include $(TOP)/configure/RULES diff --git a/modules/database/test/std/rec/Makefile b/modules/database/test/std/rec/Makefile index ebc4ac3d09..377e747e02 100644 --- a/modules/database/test/std/rec/Makefile +++ b/modules/database/test/std/rec/Makefile @@ -251,8 +251,8 @@ TESTSPEC_RTEMS = recordTestHarness.boot; epicsRunRecordTests TESTSCRIPTS_HOST += $(TESTS:%=%.t) ifneq ($(filter $(T_A),$(CROSS_COMPILER_RUNTEST_ARCHS)),) -TESTPROD_RTEMS = $(TESTPROD_HOST) -TESTSCRIPTS_RTEMS += $(TESTS:%=%.t) +TESTPROD += $(TESTPROD_HOST) +TESTSCRIPTS += $(TESTS:%=%.t) endif include $(TOP)/configure/RULES diff --git a/modules/libcom/test/Makefile b/modules/libcom/test/Makefile index a3893661f2..195f97dc1a 100644 --- a/modules/libcom/test/Makefile +++ b/modules/libcom/test/Makefile @@ -295,7 +295,7 @@ TESTSPEC_RTEMS = libComTestHarness.boot; epicsRunLibComTests TESTSCRIPTS_HOST += $(TESTS:%=%.t) ifneq ($(filter $(T_A),$(CROSS_COMPILER_RUNTEST_ARCHS)),) -TESTPROD = $(TESTPROD_HOST) +TESTPROD += $(TESTPROD_HOST) TESTSCRIPTS += $(filter-out epicsUnitTestTest.t, $(TESTS:%=%.t)) endif From 13d6ca598cca495b2e559e808392ed22265c57e3 Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Wed, 5 Feb 2025 09:26:46 -0800 Subject: [PATCH 006/446] initHookRegister() make idempotent and MustSucceed --- modules/libcom/src/iocsh/initHooks.c | 18 +++++++++++++----- modules/libcom/src/iocsh/initHooks.h | 6 +++++- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/modules/libcom/src/iocsh/initHooks.c b/modules/libcom/src/iocsh/initHooks.c index 90b1de2c52..2def0e2d49 100644 --- a/modules/libcom/src/iocsh/initHooks.c +++ b/modules/libcom/src/iocsh/initHooks.c @@ -21,6 +21,7 @@ #include "ellLib.h" #include "epicsMutex.h" #include "epicsThread.h" +#include "cantProceed.h" #include "initHooks.h" @@ -52,19 +53,26 @@ static void initHookInit(void) int initHookRegister(initHookFunction func) { initHookLink *newHook; + ELLNODE *cur; if (!func) return 0; initHookInit(); - newHook = (initHookLink *)malloc(sizeof(initHookLink)); - if (!newHook) { - printf("Cannot malloc a new initHookLink\n"); - return -1; + epicsMutexMustLock(listLock); + + for(cur = ellFirst(&functionList); cur; cur = ellNext(cur)) { + const initHookLink *fn = CONTAINER(cur, initHookLink, node); + if(fn->func==func) { + /* silently ignore duplicate */ + epicsMutexUnlock(listLock); + return 0; + } } + + newHook = (initHookLink *)mallocMustSucceed(sizeof(initHookLink), "initHookRegister"); newHook->func = func; - epicsMutexMustLock(listLock); ellAdd(&functionList, &newHook->node); epicsMutexUnlock(listLock); return 0; diff --git a/modules/libcom/src/iocsh/initHooks.h b/modules/libcom/src/iocsh/initHooks.h index 573817f6b8..57a1cc1fcc 100644 --- a/modules/libcom/src/iocsh/initHooks.h +++ b/modules/libcom/src/iocsh/initHooks.h @@ -163,7 +163,11 @@ typedef void (*initHookFunction)(initHookState state); * * Registers \p func for initHook notifications * \param func Pointer to application's notification function. - * \return 0 if Ok, -1 on error (memory allocation failure). + * \return Always zero. (before UNRELEASED could return -1 on allocation failure) + * + * \since UNRELEASED initHookRegister is idempotent. + * Previously, repeated registrations would result + * in duplicate calls to the hook function. */ LIBCOM_API int initHookRegister(initHookFunction func); From 9f788996dcb8eb4eea6d36831a79e8d2edf29638 Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Thu, 23 Feb 2023 11:06:55 -0800 Subject: [PATCH 007/446] db: lock record for db_create_read_log() and dbChannelGetField() since 27fe3e4468ec62d4d17f775c4aced939a666ba36 db_create_read_log() accesses record fields. remove now redundant db_create_read_log() calls. --- modules/database/src/ioc/db/dbChannel.c | 12 ++++++++ modules/database/src/ioc/db/dbChannel.h | 4 +++ modules/database/src/ioc/db/dbUnitTest.c | 29 ++------------------ modules/database/src/ioc/db/db_access.c | 13 +++++++++ modules/database/src/ioc/rsrv/camessage.c | 26 ------------------ modules/database/test/ioc/db/dbChArrTest.cpp | 8 ++++-- 6 files changed, 37 insertions(+), 55 deletions(-) diff --git a/modules/database/src/ioc/db/dbChannel.c b/modules/database/src/ioc/db/dbChannel.c index fd682c93ed..ad05315801 100644 --- a/modules/database/src/ioc/db/dbChannel.c +++ b/modules/database/src/ioc/db/dbChannel.c @@ -635,9 +635,21 @@ long dbChannelGetField(dbChannel *chan, short dbrType, void *pbuffer, { dbCommon *precord = chan->addr.precord; long status = 0; + unsigned char local_fl = 0; dbScanLock(precord); + if (!pfl && (ellCount(&chan->pre_chain) || ellCount(&chan->post_chain))) { + pfl = db_create_read_log(chan); + if (pfl) { + local_fl = 1; + pfl = dbChannelRunPreChain(chan, pfl); + pfl = dbChannelRunPostChain(chan, pfl); + } + } status = dbChannelGet(chan, dbrType, pbuffer, options, nRequest, pfl); + if (local_fl) { + db_delete_field_log(pfl); + } dbScanUnlock(precord); return status; } diff --git a/modules/database/src/ioc/db/dbChannel.h b/modules/database/src/ioc/db/dbChannel.h index d4cb9e9bc3..4bfdd6bc31 100644 --- a/modules/database/src/ioc/db/dbChannel.h +++ b/modules/database/src/ioc/db/dbChannel.h @@ -511,6 +511,10 @@ DBCORE_API long dbChannelGet(dbChannel *chan, short type, * \param[in,out] nRequest Pointer to the element count. * \param[in] pfl Pointer to a db_field_log or NULL. * \returns 0, or an error status value. + * + * \since UNRELEASED If pfl is NULL and chan has filters, db_create_read_log() will be called + * internally to create a temporary db_field_log which is passed to dbChannelGet() + * then deallocated. */ DBCORE_API long dbChannelGetField(dbChannel *chan, short type, void *pbuffer, long *options, long *nRequest, void *pfl); diff --git a/modules/database/src/ioc/db/dbUnitTest.c b/modules/database/src/ioc/db/dbUnitTest.c index 5ac710f487..671763636b 100644 --- a/modules/database/src/ioc/db/dbUnitTest.c +++ b/modules/database/src/ioc/db/dbUnitTest.c @@ -202,7 +202,6 @@ void testdbGetFieldEqual(const char* pv, int dbrType, ...) void testdbVGetFieldEqual(const char* pv, short dbrType, va_list ap) { dbChannel *chan = dbChannelCreate(pv); - db_field_log *pfl = NULL; long nReq = 1; union anybuf pod; long status = S_dbLib_recNotFound; @@ -212,18 +211,7 @@ void testdbVGetFieldEqual(const char* pv, short dbrType, va_list ap) goto done; } - if(ellCount(&chan->filters)) { - pfl = db_create_read_log(chan); - if (!pfl) { - testFail("can't db_create_read_log w/ %s", pv); - goto done; - } - - pfl = dbChannelRunPreChain(chan, pfl); - pfl = dbChannelRunPostChain(chan, pfl); - } - - status = dbChannelGetField(chan, dbrType, pod.bytes, NULL, &nReq, pfl); + status = dbChannelGetField(chan, dbrType, pod.bytes, NULL, &nReq, NULL); if (status) { testFail("dbGetField(\"%s\", %d, ...) -> %#lx (%s)", pv, dbrType, status, errSymMsg(status)); goto done; @@ -261,7 +249,6 @@ void testdbVGetFieldEqual(const char* pv, short dbrType, va_list ap) } done: - db_delete_field_log(pfl); if(chan) dbChannelDelete(chan); } @@ -288,7 +275,6 @@ void testdbPutArrFieldOk(const char* pv, short dbrType, unsigned long count, con void testdbGetArrFieldEqual(const char* pv, short dbfType, long nRequest, unsigned long cnt, const void *pbufraw) { dbChannel *chan = dbChannelCreate(pv); - db_field_log *pfl = NULL; const long vSize = dbValueSize(dbfType); const long nStore = vSize * nRequest; long status = S_dbLib_recNotFound; @@ -300,24 +286,13 @@ void testdbGetArrFieldEqual(const char* pv, short dbfType, long nRequest, unsign goto done; } - if(ellCount(&chan->filters)) { - pfl = db_create_read_log(chan); - if (!pfl) { - testFail("can't db_create_read_log w/ %s", pv); - goto done; - } - - pfl = dbChannelRunPreChain(chan, pfl); - pfl = dbChannelRunPostChain(chan, pfl); - } - gbuf = gstore = malloc(nStore); if(!gbuf && nStore!=0) { /* note that malloc(0) is allowed to return NULL on success */ testFail("Allocation failed esize=%ld total=%ld", vSize, nStore); return; } - status = dbChannelGetField(chan, dbfType, gbuf, NULL, &nRequest, pfl); + status = dbChannelGetField(chan, dbfType, gbuf, NULL, &nRequest, NULL); if (status) { testFail("dbGetField(\"%s\", %d, ...) -> %#lx", pv, dbfType, status); diff --git a/modules/database/src/ioc/db/db_access.c b/modules/database/src/ioc/db/db_access.c index 0943315cf0..cf83ec8a08 100644 --- a/modules/database/src/ioc/db/db_access.c +++ b/modules/database/src/ioc/db/db_access.c @@ -148,6 +148,7 @@ int dbChannel_get_count( long options; long i; long zero = 0; + unsigned char local_fl = 0; /* The order of the DBR* elements in the "newSt" structures below is * very important and must correspond to the order of processing @@ -156,6 +157,16 @@ int dbChannel_get_count( dbScanLock(dbChannelRecord(chan)); + /* If filters are involved in a read, create field log and run filters */ + if (!pfl && (ellCount(&chan->pre_chain) || ellCount(&chan->post_chain))) { + pfl = db_create_read_log(chan); + if (pfl) { + local_fl = 1; + pfl = dbChannelRunPreChain(chan, pfl); + pfl = dbChannelRunPostChain(chan, pfl); + } + } + switch(buffer_type) { case(oldDBR_STRING): status = dbChannelGet(chan, DBR_STRING, pbuffer, &zero, nRequest, pfl); @@ -800,6 +811,8 @@ int dbChannel_get_count( dbScanUnlock(dbChannelRecord(chan)); + if (local_fl) db_delete_field_log(pfl); + if (status) return -1; return 0; } diff --git a/modules/database/src/ioc/rsrv/camessage.c b/modules/database/src/ioc/rsrv/camessage.c index 81cb36a87f..36844d1624 100644 --- a/modules/database/src/ioc/rsrv/camessage.c +++ b/modules/database/src/ioc/rsrv/camessage.c @@ -493,7 +493,6 @@ static void read_reply ( void *pArg, struct dbChannel *dbch, const int readAccess = asCheckGet ( pciu->asClientPVT ); int status; int autosize; - int local_fl = 0; long item_count; ca_uint32_t payload_size; dbAddr *paddr=&dbch->addr; @@ -535,21 +534,9 @@ static void read_reply ( void *pArg, struct dbChannel *dbch, return; } - /* If filters are involved in a read, create field log and run filters */ - if (!pfl && (ellCount(&dbch->pre_chain) || ellCount(&dbch->post_chain))) { - pfl = db_create_read_log(dbch); - if (pfl) { - local_fl = 1; - pfl = dbChannelRunPreChain(dbch, pfl); - pfl = dbChannelRunPostChain(dbch, pfl); - } - } - status = dbChannel_get_count ( dbch, pevext->msg.m_dataType, pPayload, &item_count, pfl); - if (local_fl) db_delete_field_log(pfl); - if ( status < 0 ) { /* Clients recv the status of the operation directly to the * event/put/get callback. (from CA_V41()) @@ -616,7 +603,6 @@ static int read_action ( caHdrLargeArray *mp, void *pPayloadIn, struct client *p ca_uint32_t payloadSize; void *pPayload; int status; - int local_fl = 0; db_field_log *pfl = NULL; if ( ! pciu ) { @@ -655,21 +641,9 @@ static int read_action ( caHdrLargeArray *mp, void *pPayloadIn, struct client *p return RSRV_OK; } - /* If filters are involved in a read, create field log and run filters */ - if (ellCount(&pciu->dbch->pre_chain) || ellCount(&pciu->dbch->post_chain)) { - pfl = db_create_read_log(pciu->dbch); - if (pfl) { - local_fl = 1; - pfl = dbChannelRunPreChain(pciu->dbch, pfl); - pfl = dbChannelRunPostChain(pciu->dbch, pfl); - } - } - status = dbChannel_get ( pciu->dbch, mp->m_dataType, pPayload, mp->m_count, pfl ); - if (local_fl) db_delete_field_log(pfl); - if ( status < 0 ) { send_err ( mp, ECA_GETFAIL, pClient, RECORD_NAME ( pciu->dbch ) ); SEND_UNLOCK ( pClient ); diff --git a/modules/database/test/ioc/db/dbChArrTest.cpp b/modules/database/test/ioc/db/dbChArrTest.cpp index 96870d2126..1560f72a65 100644 --- a/modules/database/test/ioc/db/dbChArrTest.cpp +++ b/modules/database/test/ioc/db/dbChArrTest.cpp @@ -130,9 +130,11 @@ static void check(short dbr_type) { off = Offset; req = 10; \ memset(buf, 0, sizeof(buf)); \ (void) dbPutField(&offaddr, DBR_LONG, &off, 1); \ + dbScanLock(dbChannelRecord(pch)); \ pfl = db_create_read_log(pch); \ testOk(pfl && pfl->type == dbfl_type_ref, "Valid pfl, type = ref"); \ - testOk(!dbChannelGetField(pch, DBR_LONG, buf, NULL, &req, pfl), "Got Field value"); \ + testOk(!dbChannelGet(pch, DBR_LONG, buf, NULL, &req, pfl), "Got Field value"); \ + dbScanUnlock(dbChannelRecord(pch)); \ testOk(req == Size, "Got %ld elements (expected %d)", req, Size); \ if (!testOk(!memcmp(buf, Expected, sizeof(Expected)), "Data correct")) \ for (i=0; itype = dbfl_type_ref; \ pfl->field_type = DBF_CHAR; \ @@ -181,7 +184,8 @@ static void check(short dbr_type) { pfl->no_elements = 26; \ pfl->dtor = freeArray; \ pfl->u.r.field = epicsStrDup("abcdefghijklmnopqrsstuvwxyz"); \ - testOk(!dbChannelGetField(pch, DBR_LONG, buf, NULL, &req, pfl), "Got Field value"); \ + testOk(!dbChannelGet(pch, DBR_LONG, buf, NULL, &req, pfl), "Got Field value"); \ + dbScanUnlock(dbChannelRecord(pch)); \ testOk(req == Size, "Got %ld elements (expected %d)", req, Size); \ if (!testOk(!memcmp(buf, Expected, sizeof(Expected)), "Data correct")) \ for (i=0; i Date: Mon, 9 Jan 2023 11:46:17 -0800 Subject: [PATCH 008/446] Avoid initMainThread() except on vxworks Move isOkToBlock tracking to osdThread. Targets except vxworks can store this flag in epicsThreadOSD. Continue to use TLS w/ vxWorks. Note that setting of isOkToBlock for "main" thread becomes lazy. --- modules/libcom/src/osi/epicsThread.cpp | 35 ------------------- modules/libcom/src/osi/os/Linux/osdThread.h | 1 + .../libcom/src/osi/os/RTEMS-score/osdThread.c | 32 +++++++++++++++-- modules/libcom/src/osi/os/WIN32/osdThread.c | 16 +++++++++ modules/libcom/src/osi/os/posix/osdThread.c | 15 ++++++++ modules/libcom/src/osi/os/posix/osdThread.h | 1 + modules/libcom/src/osi/os/vxWorks/osdThread.c | 30 +++++++++++++++- 7 files changed, 91 insertions(+), 39 deletions(-) diff --git a/modules/libcom/src/osi/epicsThread.cpp b/modules/libcom/src/osi/epicsThread.cpp index b1273fd551..5de8fd99b7 100644 --- a/modules/libcom/src/osi/epicsThread.cpp +++ b/modules/libcom/src/osi/epicsThread.cpp @@ -339,32 +339,6 @@ void epicsThread :: show ( unsigned level ) const throw () } extern "C" { - static epicsThreadOnceId okToBlockOnce = EPICS_THREAD_ONCE_INIT; - epicsThreadPrivateId okToBlockPrivate; - static const int okToBlockNo = 0; - static const int okToBlockYes = 1; - - static void epicsThreadOnceIdInit(void *) - { - okToBlockPrivate = epicsThreadPrivateCreate(); - } - - int epicsStdCall epicsThreadIsOkToBlock(void) - { - const int *pokToBlock; - epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL); - pokToBlock = (int *) epicsThreadPrivateGet(okToBlockPrivate); - return (pokToBlock ? *pokToBlock : 0); - } - - void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock) - { - const int *pokToBlock; - epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL); - pokToBlock = (isOkToBlock) ? &okToBlockYes : &okToBlockNo; - epicsThreadPrivateSet(okToBlockPrivate, (void *)pokToBlock); - } - epicsThreadId epicsStdCall epicsThreadMustCreate ( const char *name, unsigned int priority, unsigned int stackSize, EPICSTHREADFUNC funptr,void *parm) @@ -375,12 +349,3 @@ extern "C" { return id; } } // extern "C" - -static epicsThreadId initMainThread(void) { - epicsThreadId main = epicsThreadGetIdSelf(); - epicsThreadSetOkToBlock(1); - return main; -} - -// Ensure the main thread gets a unique ID and allows blocking I/O -epicsThreadId epicsThreadMainId = initMainThread(); diff --git a/modules/libcom/src/osi/os/Linux/osdThread.h b/modules/libcom/src/osi/os/Linux/osdThread.h index 4bf7f29a67..a691b7ad6d 100644 --- a/modules/libcom/src/osi/os/Linux/osdThread.h +++ b/modules/libcom/src/osi/os/Linux/osdThread.h @@ -37,6 +37,7 @@ typedef struct epicsThreadOSD { int isRealTimeScheduled; int isOnThreadList; int isRunning; + int isOkToBlock; unsigned int osiPriority; int joinable; char name[1]; /* actually larger */ diff --git a/modules/libcom/src/osi/os/RTEMS-score/osdThread.c b/modules/libcom/src/osi/os/RTEMS-score/osdThread.c index e34717a365..abae0d20a8 100644 --- a/modules/libcom/src/osi/os/RTEMS-score/osdThread.c +++ b/modules/libcom/src/osi/os/RTEMS-score/osdThread.c @@ -55,6 +55,7 @@ struct taskVar { int refcnt; int joinable; int isRunning; + int isOkToBlock; EPICSTHREADFUNC funptr; void *parm; unsigned int threadVariableCapacity; @@ -219,7 +220,7 @@ void epicsThreadExitMain (void) static rtems_status_code setThreadInfo(rtems_id tid, const char *name, EPICSTHREADFUNC funptr, - void *parm, int joinable) + void *parm, int joinable, int isOkToBlock) { struct taskVar *v; uint32_t note; @@ -235,6 +236,7 @@ setThreadInfo(rtems_id tid, const char *name, EPICSTHREADFUNC funptr, v->threadVariableCapacity = 0; v->threadVariables = NULL; v->isRunning = 1; + v->isOkToBlock = isOkToBlock; if (joinable) { char c[3] = {0,0,0}; strncpy(c, v->name, 3); @@ -284,7 +286,7 @@ epicsThreadInit (void) epicsMutexOsdPrepare(&taskVarMutex); epicsMutexOsdPrepare(&onceMutex); rtems_task_ident (RTEMS_SELF, 0, &tid); - if(setThreadInfo (tid, "_main_", NULL, NULL, 0) != RTEMS_SUCCESSFUL) + if(setThreadInfo (tid, "_main_", NULL, NULL, 0, 1) != RTEMS_SUCCESSFUL) cantProceed("epicsThreadInit() unable to setup _main_"); osdThreadHooksRunMain((epicsThreadId)tid); initialized = 1; @@ -338,7 +340,7 @@ epicsThreadCreateOpt ( name, rtems_status_text(sc)); return 0; } - sc = setThreadInfo (tid, name, funptr, parm, opts->joinable); + sc = setThreadInfo (tid, name, funptr, parm, opts->joinable, 0); if (sc != RTEMS_SUCCESSFUL) { errlogPrintf ("epicsThreadCreate create failure during setup for %s: %s\n", name, rtems_status_text(sc)); @@ -870,3 +872,27 @@ LIBCOM_API int epicsThreadGetCPUs(void) return 1; #endif } + + +int epicsStdCall epicsThreadIsOkToBlock(void) +{ + uint32_t note = 0; + struct taskVar *v; + + rtems_task_get_note (RTEMS_SELF, RTEMS_NOTEPAD_TASKVAR, ¬e); + v = (void *)note; + + return v && v->isOkToBlock; +} + +void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock) +{ + uint32_t note = 0; + struct taskVar *v; + + rtems_task_get_note (RTEMS_SELF, RTEMS_NOTEPAD_TASKVAR, ¬e); + v = (void *)note; + + if(v) + v->isOkToBlock = !!isOkToBlock; +} diff --git a/modules/libcom/src/osi/os/WIN32/osdThread.c b/modules/libcom/src/osi/os/WIN32/osdThread.c index d055b9bd95..d95c9971b0 100644 --- a/modules/libcom/src/osi/os/WIN32/osdThread.c +++ b/modules/libcom/src/osi/os/WIN32/osdThread.c @@ -103,6 +103,7 @@ typedef struct epicsThreadOSD { char isSuspended; int joinable; int isRunning; + int isOkToBlock; HANDLE timer; /* waitable timer */ } win32ThreadParam; @@ -586,6 +587,7 @@ static win32ThreadParam * epicsThreadImplicitCreate ( void ) pParm->handle = handle; pParm->id = id; + pParm->isOkToBlock = 1; win32ThreadPriority = GetThreadPriority ( pParm->handle ); assert ( win32ThreadPriority != THREAD_PRIORITY_ERROR_RETURN ); pParm->epicsPriority = epicsThreadGetOsiPriorityValue ( win32ThreadPriority ); @@ -1224,3 +1226,17 @@ void testPriorityMapping () return 0; } #endif + +int epicsStdCall epicsThreadIsOkToBlock(void) +{ + struct epicsThreadOSD *pthreadInfo = epicsThreadGetIdSelf(); + + return(pthreadInfo->isOkToBlock); +} + +void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock) +{ + struct epicsThreadOSD *pthreadInfo = epicsThreadGetIdSelf(); + + pthreadInfo->isOkToBlock = !!isOkToBlock; +} diff --git a/modules/libcom/src/osi/os/posix/osdThread.c b/modules/libcom/src/osi/os/posix/osdThread.c index e9ea2dfbc0..db043dff65 100644 --- a/modules/libcom/src/osi/os/posix/osdThread.c +++ b/modules/libcom/src/osi/os/posix/osdThread.c @@ -665,6 +665,7 @@ static epicsThreadOSD *createImplicit(void) assert(pthreadInfo); pthreadInfo->tid = tid; pthreadInfo->osiPriority = 0; + pthreadInfo->isOkToBlock = 1; #if defined(_POSIX_THREAD_PRIORITY_SCHEDULING) && _POSIX_THREAD_PRIORITY_SCHEDULING > 0 if(pthread_getschedparam(tid,&pthreadInfo->schedPolicy,&pthreadInfo->schedParam) == 0) { @@ -1085,3 +1086,17 @@ LIBCOM_API int epicsThreadGetCPUs(void) #endif return 1; } + +int epicsStdCall epicsThreadIsOkToBlock(void) +{ + epicsThreadOSD *pthreadInfo = epicsThreadGetIdSelf(); + + return(pthreadInfo->isOkToBlock); +} + +void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock) +{ + epicsThreadOSD *pthreadInfo = epicsThreadGetIdSelf(); + + pthreadInfo->isOkToBlock = !!isOkToBlock; +} diff --git a/modules/libcom/src/osi/os/posix/osdThread.h b/modules/libcom/src/osi/os/posix/osdThread.h index ea49030a32..ceb72fb1f6 100644 --- a/modules/libcom/src/osi/os/posix/osdThread.h +++ b/modules/libcom/src/osi/os/posix/osdThread.h @@ -35,6 +35,7 @@ typedef struct epicsThreadOSD { int isRealTimeScheduled; int isOnThreadList; int isRunning; + int isOkToBlock; unsigned int osiPriority; int joinable; char name[1]; /* actually larger */ diff --git a/modules/libcom/src/osi/os/vxWorks/osdThread.c b/modules/libcom/src/osi/os/vxWorks/osdThread.c index c7cc2f5eb8..59e576cebd 100644 --- a/modules/libcom/src/osi/os/vxWorks/osdThread.c +++ b/modules/libcom/src/osi/os/vxWorks/osdThread.c @@ -127,7 +127,8 @@ static void epicsThreadInit(void) taskIdListSize = ID_LIST_CHUNK; atRebootRegister(); ALLOT_JOIN(0); - done = 1; + done = 1; /* avoids recursive call */ + epicsThreadSetOkToBlock(1); } lock = 0; } @@ -577,3 +578,30 @@ LIBCOM_API int epicsThreadGetCPUs(void) { return 1; } + + +static epicsThreadOnceId okToBlockOnce = EPICS_THREAD_ONCE_INIT; +static epicsThreadPrivateId okToBlockPrivate; +static const int okToBlockNo = 0; +static const int okToBlockYes = 1; + +static void epicsThreadOnceIdInit(void *not_used) +{ + okToBlockPrivate = epicsThreadPrivateCreate(); +} + +int epicsStdCall epicsThreadIsOkToBlock(void) +{ + const int *pokToBlock; + epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL); + pokToBlock = (int *) epicsThreadPrivateGet(okToBlockPrivate); + return (pokToBlock ? *pokToBlock : 0); +} + +void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock) +{ + const int *pokToBlock; + epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL); + pokToBlock = (isOkToBlock) ? &okToBlockYes : &okToBlockNo; + epicsThreadPrivateSet(okToBlockPrivate, (void *)pokToBlock); +} From a4bc0db6e61162d929b9f4c9f6137c95171ca8ae Mon Sep 17 00:00:00 2001 From: Michael Davidsaver Date: Fri, 27 Dec 2024 18:18:37 -0800 Subject: [PATCH 009/446] dbCa CP link updates set PUTF/RPRO --- modules/database/src/ioc/db/dbCa.c | 56 ++++++------------- modules/database/src/ioc/db/dbCaPvt.h | 1 + modules/database/src/ioc/db/db_access.c | 14 +++++ .../database/src/ioc/db/db_access_routines.h | 6 +- 4 files changed, 38 insertions(+), 39 deletions(-) diff --git a/modules/database/src/ioc/db/dbCa.c b/modules/database/src/ioc/db/dbCa.c index 42fe374a85..98a38d4276 100644 --- a/modules/database/src/ioc/db/dbCa.c +++ b/modules/database/src/ioc/db/dbCa.c @@ -115,10 +115,9 @@ static int dbca_chan_count; * During link modification or IOC shutdown the pca->plink pointer (guarded by caLink.lock) * is used as a flag to indicate that a link is no longer active. * - * References to the struct caLink are owned by the dbCaTask, and any scanOnceCallback() - * which is in progress. + * References to the struct caLink are owned by the dbCaTask. * - * The libca and scanOnceCallback callbacks take no action if pca->plink==NULL. + * The libca callbacks take no action if pca->plink==NULL. * * dbCaPutLinkCallback causes an additional complication because * when dbCaRemoveLink is called the callback may not have occured. @@ -788,38 +787,6 @@ static long doLocked(struct link *plink, dbLinkUserCallback rtn, void *priv) return status; } -static void scanComplete(void *raw, dbCommon *prec) -{ - caLink *pca = raw; - epicsMutexMustLock(pca->lock); - if(!pca->plink) { - /* IOC shutdown or link re-targeted. Do nothing. */ - } else if(pca->scanningOnce==0) { - errlogPrintf("dbCa.c complete callback w/ scanningOnce==0\n"); - } else if(--pca->scanningOnce){ - /* another scan is queued */ - if(scanOnceCallback(prec, scanComplete, raw)) { - errlogPrintf("dbCa.c failed to re-queue scanOnce\n"); - } else - caLinkInc(pca); - } - epicsMutexUnlock(pca->lock); - caLinkDec(pca); -} - -/* must be called with pca->lock held */ -static void scanLinkOnce(dbCommon *prec, caLink *pca) { - if(pca->scanningOnce==0) { - if(scanOnceCallback(prec, scanComplete, pca)) { - errlogPrintf("dbCa.c failed to queue scanOnce\n"); - } else - caLinkInc(pca); - } - if(pca->scanningOnce<5) - pca->scanningOnce++; - /* else too many scans queued */ -} - static lset dbCa_lset = { 0, 1, /* not Constant, Volatile */ NULL, dbCaRemoveLink, @@ -856,7 +823,9 @@ static void connectionCallback(struct connection_handler_args arg) if (precord && ((ppv_link->pvlMask & pvlOptCP) || ((ppv_link->pvlMask & pvlOptCPP) && precord->scan == 0))) - scanLinkOnce(precord, pca); + { + link_action |= CA_DBPROCESS; + } goto done; } pca->hasReadAccess = ca_read_access(arg.chid); @@ -988,7 +957,9 @@ static void eventCallback(struct event_handler_args arg) if ((ppv_link->pvlMask & pvlOptCP) || ((ppv_link->pvlMask & pvlOptCPP) && precord->scan == 0)) - scanLinkOnce(precord, pca); + { + addAction(pca, CA_DBPROCESS); + } } done: epicsMutexUnlock(pca->lock); @@ -1061,7 +1032,9 @@ static void accessRightsCallback(struct access_rights_handler_args arg) if (precord && ((ppv_link->pvlMask & pvlOptCP) || ((ppv_link->pvlMask & pvlOptCPP) && precord->scan == 0))) - scanLinkOnce(precord, pca); + { + addAction(pca, CA_DBPROCESS); + } done: epicsMutexUnlock(pca->lock); } @@ -1273,6 +1246,13 @@ static void dbCaTask(void *arg) printLinks(pca); } } + if (link_action & CA_DBPROCESS) { + dbCommon *prec; + epicsMutexMustLock(pca->lock); + prec = pca->plink->precord; + epicsMutexUnlock(pca->lock); + db_process(prec); + } } SEVCHK(ca_flush_io(), "dbCaTask"); } diff --git a/modules/database/src/ioc/db/dbCaPvt.h b/modules/database/src/ioc/db/dbCaPvt.h index 6c1d902ca7..1ee0745e04 100644 --- a/modules/database/src/ioc/db/dbCaPvt.h +++ b/modules/database/src/ioc/db/dbCaPvt.h @@ -31,6 +31,7 @@ #define CA_MONITOR_STRING 0x20 #define CA_GET_ATTRIBUTES 0x40 #define CA_SYNC 0x1000 +#define CA_DBPROCESS 0x2000 /* write type */ #define CA_PUT 0x1 #define CA_PUT_CALLBACK 0x2 diff --git a/modules/database/src/ioc/db/db_access.c b/modules/database/src/ioc/db/db_access.c index cf83ec8a08..62e8ffe3c0 100644 --- a/modules/database/src/ioc/db/db_access.c +++ b/modules/database/src/ioc/db/db_access.c @@ -1042,3 +1042,17 @@ int db_put_process(processNotify *ppn, notifyPutType type, ppn->status = notifyError; return 1; } + +void db_process(struct dbCommon *prec) +{ + if (prec->pact) { + if (dbAccessDebugPUTF && prec->tpro) + printf("%s: dbPutField to Active '%s', setting RPRO=1\n", + epicsThreadGetNameSelf(), prec->name); + prec->rpro = TRUE; + } else { + /* indicate that dbPutField called dbProcess */ + prec->putf = TRUE; + (void)dbProcess(prec); + } +} diff --git a/modules/database/src/ioc/db/db_access_routines.h b/modules/database/src/ioc/db/db_access_routines.h index ee2f07940a..1871b93434 100644 --- a/modules/database/src/ioc/db/db_access_routines.h +++ b/modules/database/src/ioc/db/db_access_routines.h @@ -22,6 +22,8 @@ extern "C" { #include "dbCoreAPI.h" +struct dbCommon; + DBCORE_API extern struct dbBase *pdbbase; DBCORE_API extern volatile int interruptAccept; @@ -36,7 +38,9 @@ DBCORE_API int dbChannel_put(struct dbChannel *chan, int src_type, const void *psrc, long no_elements); DBCORE_API int dbChannel_get_count(struct dbChannel *chan, int buffer_type, void *pbuffer, long *nRequest, void *pfl); - +#ifdef EPICS_DBCA_PRIVATE_API +DBCORE_API void db_process(struct dbCommon *prec); +#endif #ifdef __cplusplus } From bcc6cb96ae461623b16ae699b83704e5dc5349e2 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Mon, 3 Feb 2025 12:00:08 -0600 Subject: [PATCH 010/446] Added dbServerStats() API for iocStats and similar --- modules/database/src/ioc/db/dbServer.c | 20 ++++++++++++++++++++ modules/database/src/ioc/db/dbServer.h | 15 ++++++++++++--- 2 files changed, 32 insertions(+), 3 deletions(-) diff --git a/modules/database/src/ioc/db/dbServer.c b/modules/database/src/ioc/db/dbServer.c index d39b345e0d..58a6435738 100644 --- a/modules/database/src/ioc/db/dbServer.c +++ b/modules/database/src/ioc/db/dbServer.c @@ -127,6 +127,26 @@ int dbServerClient(char *pBuf, size_t bufSize) return -1; } +int dbServerStats(const char *name, unsigned *channels, unsigned *clients) +{ + dbServer *psrv = (dbServer *)ellFirst(&serverList); + + if (state != running || !psrv) + return -1; + + while (psrv) { + if (strcmp(name, psrv->name) == 0) { + if (!psrv->stats) + return -1; + + psrv->stats(channels, clients); + return 0; + } + psrv = (dbServer *)ellNext(&psrv->node); + } + return -1; +} + #define STARTSTOP(routine, method, newState) \ void routine(void) \ { \ diff --git a/modules/database/src/ioc/db/dbServer.h b/modules/database/src/ioc/db/dbServer.h index 3261660606..d816311dd1 100644 --- a/modules/database/src/ioc/db/dbServer.h +++ b/modules/database/src/ioc/db/dbServer.h @@ -17,9 +17,6 @@ * the dbServer interface provides allow the IOC to start, pause and stop * the servers together, and to provide status and debugging information * to the IOC user/developer through a common set of commands. - * - * @todo No API is provided yet for calling stats() methods. - * Nothing in the IOC calls dbStopServers(), not sure where it should go. */ #ifndef INC_dbServer_H @@ -145,6 +142,18 @@ DBCORE_API void dbsr(unsigned level); */ DBCORE_API int dbServerClient(char *pBuf, size_t bufSize); +/** @brief Fetch statistics from named server. + * + * This is an API for iocStats and similar to fetch the number of channels + * and clients connected to the named server layer. + * @param name Server name + * @param channels Where to return the channel count + * @param clients Where to return the client count + * @returns 0 on success; -1 if IOC isn't running, no such named server, + * or that server doesn't implement the stats method. + */ +DBCORE_API int dbServerStats(const char *name, unsigned *channels, unsigned *clients); + /** @brief Initialize all registered servers. * * Calls all dbServer::init() methods. From fd86f0ff04360900e7b90cafce09085448d8e6ea Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Mon, 3 Feb 2025 12:54:26 -0600 Subject: [PATCH 011/446] Unit tests for dbServerStats() --- modules/database/src/ioc/db/dbServer.c | 2 +- modules/database/test/ioc/db/dbServerTest.c | 12 ++++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/modules/database/src/ioc/db/dbServer.c b/modules/database/src/ioc/db/dbServer.c index 58a6435738..f08eec8283 100644 --- a/modules/database/src/ioc/db/dbServer.c +++ b/modules/database/src/ioc/db/dbServer.c @@ -131,7 +131,7 @@ int dbServerStats(const char *name, unsigned *channels, unsigned *clients) { dbServer *psrv = (dbServer *)ellFirst(&serverList); - if (state != running || !psrv) + if (!name || state != running || !psrv) return -1; while (psrv) { diff --git a/modules/database/test/ioc/db/dbServerTest.c b/modules/database/test/ioc/db/dbServerTest.c index 99640a619c..9379d9fb1b 100644 --- a/modules/database/test/ioc/db/dbServerTest.c +++ b/modules/database/test/ioc/db/dbServerTest.c @@ -40,6 +40,8 @@ void oneReport(unsigned level) void oneStats(unsigned *channels, unsigned *clients) { oneState = STATS_CALLED; + *channels = 2; + *clients = 1; } int oneClient(char *pbuf, size_t len) @@ -128,8 +130,9 @@ MAIN(dbServerTest) char name[16]; char *theName = "The One"; int status; + unsigned ch=0, cl=0; - testPlan(25); + testPlan(29); /* Prove that we handle substring names properly */ epicsEnvSet("EPICS_IOC_IGNORE_SERVERS", "none ones"); @@ -163,7 +166,12 @@ MAIN(dbServerTest) testDiag("Checking server methods called"); dbsr(0); - testOk(oneState == REPORT_CALLED, "dbsr called report()"); + testOk(oneState == REPORT_CALLED, "dbsr called one::report()"); + testOk(dbServerStats("none", &ch, &cl) != 0, "Stats: unknown name rejected"); + testOk(dbServerStats("no-routines", &ch, &cl) != 0, "Stats: no-routine rejected"); + testOk(dbServerStats("one", &ch, &cl) == 0 && oneState == STATS_CALLED, + "dbServerStats('one') called one::stats()"); + testOk(ch == 2 && cl == 1, "Stats: counts returned as expected"); oneSim = NULL; name[0] = 0; From 90f97a7037ecffb32544755355dacbf7239301ce Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Mon, 3 Feb 2025 13:35:49 -0600 Subject: [PATCH 012/446] Release notes; HAS_DBSERVER_STATS in dbServer.h --- documentation/RELEASE_NOTES.md | 7 +++++++ modules/database/src/ioc/db/dbServer.h | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index 732c986548..1b0f0e6b78 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -18,6 +18,13 @@ __This version of EPICS has not been released yet.__ __Add new items below here__ +### New `dbServerStats()` API for iocStats + +A new routine provides the ability to request channel and client counts from +name server layers that implement the `stats()` method. A preprocessor macro +`HAS_DBSERVER_STATS` macro is defined in the `dbServer.h` header file to +simplify code that needs to support older versions of Base as well. + ----- ## EPICS Release 7.0.9 diff --git a/modules/database/src/ioc/db/dbServer.h b/modules/database/src/ioc/db/dbServer.h index d816311dd1..86c3f7d82b 100644 --- a/modules/database/src/ioc/db/dbServer.h +++ b/modules/database/src/ioc/db/dbServer.h @@ -142,6 +142,11 @@ DBCORE_API void dbsr(unsigned level); */ DBCORE_API int dbServerClient(char *pBuf, size_t bufSize); +/** @brief CPP Macro indicating the dbServerStats() routine exists. + * @since UNRELEASED + */ +#define HAS_DBSERVER_STATS + /** @brief Fetch statistics from named server. * * This is an API for iocStats and similar to fetch the number of channels @@ -151,6 +156,8 @@ DBCORE_API int dbServerClient(char *pBuf, size_t bufSize); * @param clients Where to return the client count * @returns 0 on success; -1 if IOC isn't running, no such named server, * or that server doesn't implement the stats method. + * + * @since UNRELEASED */ DBCORE_API int dbServerStats(const char *name, unsigned *channels, unsigned *clients); From 72f3e75c8de5eaf44ee6e13ea37040024cc476cd Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 18 Feb 2025 14:20:14 -0600 Subject: [PATCH 013/446] Add summary stat's calculation --- documentation/RELEASE_NOTES.md | 3 ++- modules/database/src/ioc/db/dbServer.c | 22 ++++++++++++++++++--- modules/database/src/ioc/db/dbServer.h | 6 ++++-- modules/database/test/ioc/db/dbServerTest.c | 18 +++++++++++++---- 4 files changed, 39 insertions(+), 10 deletions(-) diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index 1b0f0e6b78..387c4191b2 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -21,7 +21,8 @@ __Add new items below here__ ### New `dbServerStats()` API for iocStats A new routine provides the ability to request channel and client counts from -name server layers that implement the `stats()` method. A preprocessor macro +named server layers that implement the `stats()` method, or to get a summary +of the counts from all registered server layers. A preprocessor macro `HAS_DBSERVER_STATS` macro is defined in the `dbServer.h` header file to simplify code that needs to support older versions of Base as well. diff --git a/modules/database/src/ioc/db/dbServer.c b/modules/database/src/ioc/db/dbServer.c index f08eec8283..c4e5f55c31 100644 --- a/modules/database/src/ioc/db/dbServer.c +++ b/modules/database/src/ioc/db/dbServer.c @@ -130,11 +130,23 @@ int dbServerClient(char *pBuf, size_t bufSize) int dbServerStats(const char *name, unsigned *channels, unsigned *clients) { dbServer *psrv = (dbServer *)ellFirst(&serverList); + unsigned tch, tcl; - if (!name || state != running || !psrv) + if (state != running || !psrv) return -1; - while (psrv) { + for (tch = 0, tcl = 0; psrv; + psrv = (dbServer *)ellNext(&psrv->node)) { + if (!name) { + if (psrv->stats) { + unsigned lch, lcl; + + psrv->stats(&lch, &lcl); + tch += lch; + tcl += lcl; + } + continue; + } if (strcmp(name, psrv->name) == 0) { if (!psrv->stats) return -1; @@ -142,7 +154,11 @@ int dbServerStats(const char *name, unsigned *channels, unsigned *clients) psrv->stats(channels, clients); return 0; } - psrv = (dbServer *)ellNext(&psrv->node); + } + if (!name) { + if (channels) *channels = tch; + if (clients) *clients = tcl; + return 0; } return -1; } diff --git a/modules/database/src/ioc/db/dbServer.h b/modules/database/src/ioc/db/dbServer.h index 86c3f7d82b..9b16c3b3d7 100644 --- a/modules/database/src/ioc/db/dbServer.h +++ b/modules/database/src/ioc/db/dbServer.h @@ -151,9 +151,11 @@ DBCORE_API int dbServerClient(char *pBuf, size_t bufSize); * * This is an API for iocStats and similar to fetch the number of channels * and clients connected to the named server layer. + * If the name given is NULL the statistics returned are the totals for + * all the registered server layers. * @param name Server name - * @param channels Where to return the channel count - * @param clients Where to return the client count + * @param channels NULL, or where to return the channel count + * @param clients NULL or where to return the client count * @returns 0 on success; -1 if IOC isn't running, no such named server, * or that server doesn't implement the stats method. * diff --git a/modules/database/test/ioc/db/dbServerTest.c b/modules/database/test/ioc/db/dbServerTest.c index 9379d9fb1b..97e547deb7 100644 --- a/modules/database/test/ioc/db/dbServerTest.c +++ b/modules/database/test/ioc/db/dbServerTest.c @@ -40,8 +40,8 @@ void oneReport(unsigned level) void oneStats(unsigned *channels, unsigned *clients) { oneState = STATS_CALLED; - *channels = 2; - *clients = 1; + if (channels) *channels = 2; + if (clients) *clients = 1; } int oneClient(char *pbuf, size_t len) @@ -132,7 +132,7 @@ MAIN(dbServerTest) int status; unsigned ch=0, cl=0; - testPlan(29); + testPlan(32); /* Prove that we handle substring names properly */ epicsEnvSet("EPICS_IOC_IGNORE_SERVERS", "none ones"); @@ -167,12 +167,22 @@ MAIN(dbServerTest) testDiag("Checking server methods called"); dbsr(0); testOk(oneState == REPORT_CALLED, "dbsr called one::report()"); + + testDiag("Checking stats functionality"); testOk(dbServerStats("none", &ch, &cl) != 0, "Stats: unknown name rejected"); testOk(dbServerStats("no-routines", &ch, &cl) != 0, "Stats: no-routine rejected"); testOk(dbServerStats("one", &ch, &cl) == 0 && oneState == STATS_CALLED, "dbServerStats('one') called one::stats()"); - testOk(ch == 2 && cl == 1, "Stats: counts returned as expected"); + testOk(ch == 2 && cl == 1, "Stats: ch==%d, cl==%d (expected 2, 1)", ch, cl); + + ch = 10; cl = 10; oneState = NOTHING_CALLED; + testOk(dbServerStats(NULL, NULL, &cl) == 0 && oneState == STATS_CALLED, + "dbServerStats(NULL, &cl) called one::stats()"); + testOk(dbServerStats(NULL, &ch, NULL) == 0 && oneState == STATS_CALLED, + "dbServerStats(NULL, &ch) called one::stats()"); + testOk(ch == 2 && cl == 1, "Stats: ch==%d, cl==%d (expected 2, 1)", ch, cl); + testDiag("Checking client identification"); oneSim = NULL; name[0] = 0; status = dbServerClient(name, sizeof(name)); From 350570134e9b3e0964efe10e4afe2525acdb007f Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Wed, 26 Feb 2025 13:29:08 -0600 Subject: [PATCH 014/446] Changed dbServerStats() to count the server layers called --- modules/database/src/ioc/db/dbServer.c | 41 ++++++++------------- modules/database/src/ioc/db/dbServer.h | 21 ++++++----- modules/database/test/ioc/db/dbServerTest.c | 21 ++++++++--- 3 files changed, 42 insertions(+), 41 deletions(-) diff --git a/modules/database/src/ioc/db/dbServer.c b/modules/database/src/ioc/db/dbServer.c index c4e5f55c31..527fb97ca6 100644 --- a/modules/database/src/ioc/db/dbServer.c +++ b/modules/database/src/ioc/db/dbServer.c @@ -130,37 +130,26 @@ int dbServerClient(char *pBuf, size_t bufSize) int dbServerStats(const char *name, unsigned *channels, unsigned *clients) { dbServer *psrv = (dbServer *)ellFirst(&serverList); - unsigned tch, tcl; - if (state != running || !psrv) return -1; - for (tch = 0, tcl = 0; psrv; - psrv = (dbServer *)ellNext(&psrv->node)) { - if (!name) { - if (psrv->stats) { - unsigned lch, lcl; - - psrv->stats(&lch, &lcl); - tch += lch; - tcl += lcl; - } - continue; - } - if (strcmp(name, psrv->name) == 0) { - if (!psrv->stats) - return -1; - - psrv->stats(channels, clients); - return 0; + unsigned tch = 0, tcl = 0, nmatch = 0; + for (; psrv; psrv = (dbServer *)ellNext(&psrv->node)) { + if (psrv->stats && + (!name || strcmp(name, psrv->name) == 0)) { + unsigned lch = 0, lcl = 0; + + psrv->stats(&lch, &lcl); + tch += lch; + tcl += lcl; + nmatch++; + if (name) + break; /* No duplicate names in serverList */ } } - if (!name) { - if (channels) *channels = tch; - if (clients) *clients = tcl; - return 0; - } - return -1; + if (channels) *channels = tch; + if (clients) *clients = tcl; + return nmatch; } #define STARTSTOP(routine, method, newState) \ diff --git a/modules/database/src/ioc/db/dbServer.h b/modules/database/src/ioc/db/dbServer.h index 9b16c3b3d7..2083a705af 100644 --- a/modules/database/src/ioc/db/dbServer.h +++ b/modules/database/src/ioc/db/dbServer.h @@ -56,8 +56,8 @@ typedef struct dbServer { /** @brief Get number of channels and clients currently connected. * - * @param channels NULL or pointer for returning channel count. - * @param clients NULL or pointer for returning client count. + * @param channels @c NULL or pointer for returning channel count. + * @param clients @c NULL or pointer for returning client count. */ void (* stats) (unsigned *channels, unsigned *clients); @@ -147,21 +147,24 @@ DBCORE_API int dbServerClient(char *pBuf, size_t bufSize); */ #define HAS_DBSERVER_STATS -/** @brief Fetch statistics from named server. +/** @brief Fetch statistics from server layers. * * This is an API for iocStats and similar to fetch the number of channels - * and clients connected to the named server layer. - * If the name given is NULL the statistics returned are the totals for - * all the registered server layers. + * and clients connected to the registered server layers. + * If the name given is NULL the statistics returned are the totals from + * all registered server layers, otherwise just from the named server. * @param name Server name * @param channels NULL, or where to return the channel count * @param clients NULL or where to return the client count - * @returns 0 on success; -1 if IOC isn't running, no such named server, - * or that server doesn't implement the stats method. + * @returns -1 if the IOC isn't running or no servers are registered, without + * writing to the statistics variables. Otherwise it writes to the statistics + * variables and returns the number of dbServer::stats() methods called, + * 0 if a named server wasn't found or doesn't have a stats() method. * * @since UNRELEASED */ -DBCORE_API int dbServerStats(const char *name, unsigned *channels, unsigned *clients); +DBCORE_API int dbServerStats(const char *name, unsigned *channels, + unsigned *clients); /** @brief Initialize all registered servers. * diff --git a/modules/database/test/ioc/db/dbServerTest.c b/modules/database/test/ioc/db/dbServerTest.c index 97e547deb7..db4ba59d11 100644 --- a/modules/database/test/ioc/db/dbServerTest.c +++ b/modules/database/test/ioc/db/dbServerTest.c @@ -132,7 +132,7 @@ MAIN(dbServerTest) int status; unsigned ch=0, cl=0; - testPlan(32); + testPlan(35); /* Prove that we handle substring names properly */ epicsEnvSet("EPICS_IOC_IGNORE_SERVERS", "none ones"); @@ -154,6 +154,9 @@ MAIN(dbServerTest) testDiag("Registering dbServer 'disabled'"); testOk(dbRegisterServer(&disabled) == 0, "Registration accepted"); + testOk(dbServerStats("one", &ch, &cl) == -1 && oneState == NOTHING_CALLED, + "dbServerStats returns error before IOC running"); + testDiag("Changing server state"); dbInitServers(); testOk(oneState == INIT_CALLED, "dbInitServers"); @@ -169,16 +172,19 @@ MAIN(dbServerTest) testOk(oneState == REPORT_CALLED, "dbsr called one::report()"); testDiag("Checking stats functionality"); - testOk(dbServerStats("none", &ch, &cl) != 0, "Stats: unknown name rejected"); - testOk(dbServerStats("no-routines", &ch, &cl) != 0, "Stats: no-routine rejected"); - testOk(dbServerStats("one", &ch, &cl) == 0 && oneState == STATS_CALLED, + testOk(dbServerStats("none", &ch, &cl) == 0, "Stats: unknown name ignored"); + testOk(dbServerStats("one", &ch, &cl) == 1 && oneState == STATS_CALLED, "dbServerStats('one') called one::stats()"); testOk(ch == 2 && cl == 1, "Stats: ch==%d, cl==%d (expected 2, 1)", ch, cl); + testOk(dbServerStats("no-routines", &ch, &cl) == 0, + "dbServerStats('no-routines') layer not counted"); + testOk(ch == 0 && cl == 0, "Stats: ch==%d, cl==%d (expected 0, 0)", ch, cl); + ch = 10; cl = 10; oneState = NOTHING_CALLED; - testOk(dbServerStats(NULL, NULL, &cl) == 0 && oneState == STATS_CALLED, + testOk(dbServerStats(NULL, NULL, &cl) == 1 && oneState == STATS_CALLED, "dbServerStats(NULL, &cl) called one::stats()"); - testOk(dbServerStats(NULL, &ch, NULL) == 0 && oneState == STATS_CALLED, + testOk(dbServerStats(NULL, &ch, NULL) == 1 && oneState == STATS_CALLED, "dbServerStats(NULL, &ch) called one::stats()"); testOk(ch == 2 && cl == 1, "Stats: ch==%d, cl==%d (expected 2, 1)", ch, cl); @@ -206,6 +212,9 @@ MAIN(dbServerTest) status = dbServerClient(name, sizeof(name)); testOk(oneState != CLIENT_CALLED_KNOWN, "No call to client() when paused"); + testOk(dbServerStats("one", &ch, &cl) == -1 && oneState != STATS_CALLED, + "No call to stats() when paused"); + dbStopServers(); testOk(oneState == STOP_CALLED, "dbStopServers"); testOk(dbUnregisterServer(&toolate) != 0, "No unreg' if not reg'ed"); From b97a35fec87ae9186026d8df118f990e7d24f814 Mon Sep 17 00:00:00 2001 From: Dirk Zimoch Date: Wed, 12 Mar 2025 12:07:34 +0100 Subject: [PATCH 015/446] Don't use __attribute__((noreturn)) on VxWorks VxWorks does not mark abort() or exit() as noreturn. Thus, functions declared noreturn which end in a call to those functions cause a compiler warning on vxWorks. --- modules/libcom/src/osi/compiler/gcc/compilerSpecific.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h b/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h index 47d06780f0..42723b97c1 100644 --- a/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h +++ b/modules/libcom/src/osi/compiler/gcc/compilerSpecific.h @@ -60,6 +60,9 @@ /* * No return marker */ +#ifndef vxWorks +// VxWorks does not mark abort() or exit() noreturn! #define EPICS_NORETURN __attribute__((noreturn)) +#endif #endif /* ifndef compilerSpecific_h */ From c75ad2673e55d6e5db2b4d138a8ae65c865ba36a Mon Sep 17 00:00:00 2001 From: Dirk Zimoch Date: Sat, 8 Feb 2025 23:08:19 +0100 Subject: [PATCH 016/446] no longer need extern "C" { } around epicsExport macros --- documentation/RELEASE_NOTES.md | 5 + modules/database/test/std/rec/Makefile | 28 ++++ .../database/test/std/rec/epicsExportTest.c | 146 ++++++++++++++++++ .../database/test/std/rec/epicsExportTest.db | 24 +++ .../database/test/std/rec/epicsExportTest.dbd | 16 ++ .../test/std/rec/epicsExportTestMain.c | 95 ++++++++++++ .../test/std/rec/epicsExportTestxx.cpp | 2 + modules/libcom/src/misc/epicsExport.h | 33 ++-- 8 files changed, 340 insertions(+), 9 deletions(-) create mode 100644 modules/database/test/std/rec/epicsExportTest.c create mode 100644 modules/database/test/std/rec/epicsExportTest.db create mode 100644 modules/database/test/std/rec/epicsExportTest.dbd create mode 100644 modules/database/test/std/rec/epicsExportTestMain.c create mode 100644 modules/database/test/std/rec/epicsExportTestxx.cpp diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index 387c4191b2..0435a1cc69 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -18,6 +18,11 @@ __This version of EPICS has not been released yet.__ __Add new items below here__ +### epicsExport simplifications + +`epicsExportAddress()`, `epicsExportRegistrar()` and `epicsRegisterFunction()` +no longer require to be wrapped in `extern "C" { }` in C++ code. + ### New `dbServerStats()` API for iocStats A new routine provides the ability to request channel and client counts from diff --git a/modules/database/test/std/rec/Makefile b/modules/database/test/std/rec/Makefile index 377e747e02..d6aaf44d37 100644 --- a/modules/database/test/std/rec/Makefile +++ b/modules/database/test/std/rec/Makefile @@ -221,6 +221,34 @@ testHarness_SRCS += linkFilterTest.c TESTFILES += ../linkFilterTest.db TESTS += linkFilterTest +TARGETS += $(COMMON_DIR)/epicsExportTestIoc.dbd +DBDDEPENDS_FILES += epicsExportTestIoc.dbd$(DEP) +epicsExportTestIoc_DBD += base.dbd +epicsExportTestIoc_DBD += epicsExportTest.dbd +TESTFILES += $(COMMON_DIR)/epicsExportTestIoc.dbd ../epicsExportTest.db + +TESTLIBRARY += epicsExportTestLib +epicsExportTestLib_SRCS += epicsExportTest.c +epicsExportTestLib_LIBS += dbCore Com + +TESTPROD_HOST += epicsExportTest +TESTS += epicsExportTest +TARGETS += epicsExportTest$(OBJ) +epicsExportTest_SRCS += epicsExportTestMain.c +epicsExportTest_SRCS += epicsExportTestIoc_registerRecordDeviceDriver.cpp +epicsExportTest_LIBS = epicsExportTestLib + +TESTLIBRARY += epicsExportTestxxLib +epicsExportTestxxLib_SRCS += epicsExportTestxx.cpp +epicsExportTestxxLib_LIBS += dbCore Com + +TESTPROD_HOST += epicsExportTestxx +TESTS += epicsExportTestxx +TARGETS += epicsExportTestxx$(OBJ) +epicsExportTestxx_SRCS += epicsExportTestMain.c +epicsExportTestxx_SRCS += epicsExportTestIoc_registerRecordDeviceDriver.cpp +epicsExportTestxx_LIBS = epicsExportTestxxLib + # These are compile-time tests, no need to link or run TARGETS += dbHeaderTest$(OBJ) TARGET_SRCS += dbHeaderTest.cpp diff --git a/modules/database/test/std/rec/epicsExportTest.c b/modules/database/test/std/rec/epicsExportTest.c new file mode 100644 index 0000000000..aaa3f22151 --- /dev/null +++ b/modules/database/test/std/rec/epicsExportTest.c @@ -0,0 +1,146 @@ +/*************************************************************************\ +* Copyright (c) 2025 Dirk Zimoch +* SPDX-License-Identifier: EPICS +* EPICS BASE is distributed subject to a Software License Agreement found +* in file LICENSE that is included with this distribution. +\*************************************************************************/ + +/* Compile and link test for epicsExport.h +* +* Test if macros eppicsExportAddr, epicsExportRegistrar and epicsRegisterFunction +* expand to valid C and C++ code, in the latter case regardless if +* wrapped with extern "C" {} or not. +* Also test that those macros have the intended effect in both cases. +* +* This file is compiled directly as C +* and included from epicsExportTestxx.cpp as C++ +*/ + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +int i1, i2; +volatile int v1=10, v2=20; +const int c1=100, c2=200; + +static long myReadLongin(struct dbCommon* prec) +{ + struct longinRecord* pli = +#ifdef __cplusplus + reinterpret_cast(prec); +#else + (struct longinRecord*)prec; +#endif + pli->val=5; + return 0; +} + +/* Also test cast from user-specific const mydset to dset */ +const struct mydset { + long number; + long (*report)(int); + long (*init)(int); + long (*init_record)(struct dbCommon*); + long (*get_ioint_info)(int, struct dbCommon*, IOSCANPVT*); + long (*process)(struct dbCommon*); + long (*something_else)(struct dbCommon*); +} dset1 = { + 6, + NULL, + NULL, + NULL, + NULL, + myReadLongin, + NULL +}, dset2 = { + 6, + NULL, + NULL, + NULL, + NULL, + myReadLongin, + NULL +}; + +static void registrar1() { + i1++; + testPass("registrar1 executed"); +} + +static void registrar2() { + i2++; + testPass("registrar2 executed"); +} + +/* Also test cast from int(*)() to REGISTRAR */ +static int registrar3() { + i1++; + testPass("registrar3 executed"); + return 0; +} + +static int registrar4() { + i2++; + testPass("registrar4 executed"); + return 0; +} + +/* Test both, native (potentially C++) and extern "C" functions */ +static long aSubInit1(aSubRecord* prec) { + *(epicsInt32*)prec->a = 1; + return 0; +} + +static long aSubProc1(aSubRecord* prec) { + *(epicsInt32*)prec->b = 2; + return 0; +} + +#ifdef __cplusplus +extern "C" { +#endif +static long aSubInit2(aSubRecord* prec) { + *(epicsInt32*)prec->a = 3; + return 0; +} +static long aSubProc2(aSubRecord* prec) { + *(epicsInt32*)prec->b = 4; + return 0; +} +#ifdef __cplusplus +} +#endif + +/* Test without wrapping */ +epicsExportAddress(int, i1); +epicsExportAddress(int, v1); +epicsExportAddress(int, c1); +epicsExportAddress(dset, dset1); +epicsExportRegistrar(registrar1); +epicsExportRegistrar(registrar3); +epicsRegisterFunction(aSubInit1); +epicsRegisterFunction(aSubProc1); + +/* In C++ test wrapped in extern "C" {} */ +#ifdef __cplusplus +extern "C" { +#endif +epicsExportAddress(int, i2); +epicsExportAddress(int, v2); +epicsExportAddress(int, c2); +epicsExportAddress(dset, dset2); +epicsExportRegistrar(registrar2); +epicsExportRegistrar(registrar4); +epicsRegisterFunction(aSubInit2); +epicsRegisterFunction(aSubProc2); + +#ifdef __cplusplus +} +#endif diff --git a/modules/database/test/std/rec/epicsExportTest.db b/modules/database/test/std/rec/epicsExportTest.db new file mode 100644 index 0000000000..8aa297b554 --- /dev/null +++ b/modules/database/test/std/rec/epicsExportTest.db @@ -0,0 +1,24 @@ +record(longin, "li1") { + field(DTYP, "dset1") + field(VAL, "-1") +} +record(longin, "li2") { + field(DTYP, "dset2") + field(VAL, "-2") +} +record(aSub, "asub1") { + field(FTA, "LONG") + field(FTB, "LONG") + field(INPA, "-1") + field(INPB, "-2") + field(INAM, "aSubInit1") + field(SNAM, "aSubProc1") +} +record(aSub, "asub2") { + field(FTA, "LONG") + field(FTB, "LONG") + field(INPA, "-3") + field(INPB, "-4") + field(INAM, "aSubInit2") + field(SNAM, "aSubProc2") +} diff --git a/modules/database/test/std/rec/epicsExportTest.dbd b/modules/database/test/std/rec/epicsExportTest.dbd new file mode 100644 index 0000000000..fc9ee2f6d6 --- /dev/null +++ b/modules/database/test/std/rec/epicsExportTest.dbd @@ -0,0 +1,16 @@ +variable(i1,int) +variable(i2,int) +variable(v1,int) +variable(v2,int) +variable(c1,int) +variable(c2,int) +device(longin, CONSTANT, dset1, "dset1") +device(longin, CONSTANT, dset2, "dset2") +registrar(registrar1) +registrar(registrar2) +registrar(registrar3) +registrar(registrar4) +function(aSubInit1) +function(aSubProc1) +function(aSubInit2) +function(aSubProc2) diff --git a/modules/database/test/std/rec/epicsExportTestMain.c b/modules/database/test/std/rec/epicsExportTestMain.c new file mode 100644 index 0000000000..2f6d11f1e6 --- /dev/null +++ b/modules/database/test/std/rec/epicsExportTestMain.c @@ -0,0 +1,95 @@ +/*************************************************************************\ +* Copyright (c) 2025 Dirk Zimoch +* SPDX-License-Identifier: EPICS +* EPICS BASE is distributed subject to a Software License Agreement found +* in file LICENSE that is included with this distribution. +\*************************************************************************/ + +/* Compile and link test for epicsExport.h +* +*/ + +#include +#include +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" +#endif +int epicsExportTestIoc_registerRecordDeviceDriver(struct dbBase *); + +static int* testVarEquals(const char* name, int expected) +{ + const iocshVarDef *var; + int *p; + + var = iocshFindVariable(name); + if (!var) { + testFail("Cannot access variable %s", name); + return NULL; + } + if (var->type != iocshArgInt) { + testFail("Variable %s has wrong type", name); + return NULL; + } + p = (int*)(var->pval); + testOk(*p == expected, "Variable %s == %d", name, expected); + return p; +} + +MAIN(epicsExportTest) +{ + int *p1, *p2; + + testPlan(31); + testdbPrepare(); + testdbReadDatabase("epicsExportTestIoc.dbd", 0, 0); + testOk(epicsExportTestIoc_registerRecordDeviceDriver(pdbbase)==0, "registerRecordDeviceDriver"); + + testDiag("Testing if dsets and functions are found"); + testdbReadDatabase("epicsExportTest.db", 0, 0); + testIocInitOk(); + + testDiag("Testing if dsets work correctly"); + testdbGetFieldEqual("li1", DBF_LONG, -1); + testdbGetFieldEqual("li2", DBF_LONG, -2); + testdbPutFieldOk("li1.PROC", DBF_LONG, 1); + testdbPutFieldOk("li2.PROC", DBF_LONG, 1); + testdbGetFieldEqual("li1", DBF_LONG, 5); + testdbGetFieldEqual("li2", DBF_LONG, 5); + + testDiag("Testing if functions work correctly"); + testdbGetFieldEqual("asub1.A", DBF_LONG, 1); + testdbGetFieldEqual("asub1.B", DBF_LONG, -2); + testdbGetFieldEqual("asub2.A", DBF_LONG, 3); + testdbGetFieldEqual("asub2.B", DBF_LONG, -4); + testdbPutFieldOk("asub1.PROC", DBF_LONG, 1); + testdbPutFieldOk("asub2.PROC", DBF_LONG, 1); + testdbGetFieldEqual("asub1.A", DBF_LONG, 1); + testdbGetFieldEqual("asub1.B", DBF_LONG, 2); + testdbGetFieldEqual("asub2.A", DBF_LONG, 3); + testdbGetFieldEqual("asub2.B", DBF_LONG, 4); + + testDiag("Testing if variable access works"); + p1 = testVarEquals("i1", 2); + p2 = testVarEquals("i2", 2); + testVarEquals("v1", 10); + testVarEquals("v2", 20); + testVarEquals("c1", 100); + testVarEquals("c2", 200); + + if (p1 && p2) { + testDiag("Testing if variables are accessible from iocsh"); + testOk(iocshCmd("var i1,4") == 0, "Setting i1 = 4 in iocsh"); + testOk(iocshCmd("var i2,5") == 0, "Setting i2 = 5 in iocsh"); + testOk(*p1==4, "Variable i1 == 4"); + testOk(*p2==5, "Variable i2 == 5"); + } + + testIocShutdownOk(); + testdbCleanup(); + return testDone(); +} diff --git a/modules/database/test/std/rec/epicsExportTestxx.cpp b/modules/database/test/std/rec/epicsExportTestxx.cpp new file mode 100644 index 0000000000..3bb1628ce5 --- /dev/null +++ b/modules/database/test/std/rec/epicsExportTestxx.cpp @@ -0,0 +1,2 @@ +// just compile as c++ +#include "epicsExportTest.c" diff --git a/modules/libcom/src/misc/epicsExport.h b/modules/libcom/src/misc/epicsExport.h index 7c084a602f..356d62b394 100644 --- a/modules/libcom/src/misc/epicsExport.h +++ b/modules/libcom/src/misc/epicsExport.h @@ -41,6 +41,10 @@ extern "C" { typedef void (*REGISTRAR)(void); +#ifdef __cplusplus +} +#endif + #define EPICS_EXPORT_POBJ(typ, obj) pvar_ ## typ ## _ ## obj #define EPICS_EXPORT_PFUNC(fun) EPICS_EXPORT_POBJ(func, fun) @@ -75,12 +79,16 @@ typedef void (*REGISTRAR)(void); * * \param typ Object's data type. * \param obj Object's name. - * - * \note C++ code needs to wrap with @code extern "C" { } @endcode */ +#ifdef __cplusplus +#define epicsExportAddress(typ, obj) \ + extern "C" { epicsShareExtern typ *EPICS_EXPORT_POBJ(typ,obj); } \ + epicsShareDef typ *EPICS_EXPORT_POBJ(typ, obj) = (typ *) (char *) &obj +#else #define epicsExportAddress(typ, obj) \ epicsShareExtern typ *EPICS_EXPORT_POBJ(typ,obj); \ epicsShareDef typ *EPICS_EXPORT_POBJ(typ, obj) = (typ *) (char *) &obj +#endif /** \brief Declare a registrar function for exporting. * @@ -94,11 +102,15 @@ typedef void (*REGISTRAR)(void); \endcode * * \param fun Registrar function's name. - * - * \note C++ code needs to wrap with @code extern "C" { } @endcode */ +#ifdef __cplusplus +#define epicsExportRegistrar(fun) \ + extern "C" { extern epicsShareFunc REGISTRAR EPICS_EXPORT_PFUNC(fun); } \ + REGISTRAR EPICS_EXPORT_PFUNC(fun) = reinterpret_cast(&fun) +#else #define epicsExportRegistrar(fun) \ epicsShareFunc REGISTRAR EPICS_EXPORT_PFUNC(fun) = (REGISTRAR) &fun +#endif /** \brief Declare and register a function for exporting. * @@ -111,18 +123,21 @@ typedef void (*REGISTRAR)(void); \endcode * * \param fun Function's name - * - * \note C++ code needs to wrap with @code extern "C" { } @endcode */ +#ifdef __cplusplus +#define epicsRegisterFunction(fun) \ + static void register_func_ ## fun(void) \ + { \ + registryFunctionAdd(#fun, reinterpret_cast(fun)); \ + } \ + epicsExportRegistrar(register_func_ ## fun) +#else #define epicsRegisterFunction(fun) \ static void register_func_ ## fun(void) \ { \ registryFunctionAdd(#fun, (REGISTRYFUNCTION) fun); \ } \ epicsExportRegistrar(register_func_ ## fun) - -#ifdef __cplusplus -} #endif #endif /* INC_epicsExport_H */ From fc5d3c9a5c41bccc454a0227fbcf76bdc84e4055 Mon Sep 17 00:00:00 2001 From: JJL772 Date: Thu, 13 Jun 2024 16:37:43 -0400 Subject: [PATCH 017/446] Disable extraneous WIN32 declarations when including windows.h in epicsAtomicOSD.h --- .../libcom/src/osi/os/WIN32/epicsAtomicOSD.h | 57 +++++++++++++------ 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h b/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h index 6a9f4484ee..46a4a85aa7 100644 --- a/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h +++ b/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h @@ -19,27 +19,50 @@ #define EPICS_ATOMIC_OS_NAME "WIN32" -#ifdef VC_EXTRALEAN -# define VC_EXTRALEAN_DETECTED_epicsAtomicOSD_h -#else -# define VC_EXTRALEAN -#endif +/* Disable extra declarations that we don't need here (i.e. winsock1, rpc, etc.) */ +#pragma push_macro("WIN32_LEAN_AND_MEAN") +#undef WIN32_LEAN_AND_MEAN +#define WIN32_LEAN_AND_MEAN -#ifdef STRICT -# define STRICT_DETECTED_epicsAtomicOSD_h -#else -# define STRICT -#endif +#pragma push_macro("STRICT") +#undef STRICT +#define STRICT -#include "windows.h" +/* Disable min/max macros from windows.h. These macros can cause issues with headers such as that declare or use std::min/max */ +#pragma push_macro("NOMINMAX") +#undef NOMINMAX +#define NOMINMAX -#ifndef VC_EXTRALEAN_DETECTED_epicsAtomicOSD_h -# undef VC_EXTRALEAN -#endif +/* Disable 'service controller' includes */ +#pragma push_macro("NOSERVICE") +#undef NOSERVICE +#define NOSERVICE -#ifndef STRICT_DETECTED_epicsAtomicOSD_h -# undef STRICT -#endif +/* Disable 'input management engine' includes */ +#pragma push_macro("NOIME") +#undef NOIME +#define NOIME + +/* Disable 'modem configuration extensions' includes */ +#pragma push_macro("NOMCX") +#undef NOMCX +#define NOMCX + +/* Disable GDI includes */ +#pragma push_macro("NOGDI") +#undef NOGDI +#define NOGDI + +#include "windows.h" + +/* Restore previous macro values */ +#pragma pop_macro("WIN32_LEAN_AND_MEAN") +#pragma pop_macro("STRICT") +#pragma pop_macro("NOMINMAX") +#pragma pop_macro("NOSERVICE") +#pragma pop_macro("NOIME") +#pragma pop_macro("NOMCX") +#pragma pop_macro("NOGDI") #if defined ( _WIN64 ) # define MS_ATOMIC_64 From 9fac52fa58075d5220749466c3794710b66d0426 Mon Sep 17 00:00:00 2001 From: JJL772 Date: Fri, 21 Jun 2024 17:28:23 -0700 Subject: [PATCH 018/446] Add a release note for the windows.h epicsAtomicOSD change --- documentation/RELEASE_NOTES.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/documentation/RELEASE_NOTES.md b/documentation/RELEASE_NOTES.md index 0435a1cc69..82b9a921e7 100644 --- a/documentation/RELEASE_NOTES.md +++ b/documentation/RELEASE_NOTES.md @@ -18,6 +18,14 @@ __This version of EPICS has not been released yet.__ __Add new items below here__ +### Reduce symbol and macro pollution from epicsAtomic.h on WIN32 + +`epicsAtomic.h` no longer pulls in as many unneeded declarations and macros from +`windows.h`. Prior to this change, including `epicsAtomic.h` at the wrong time +could result in unexpected compiler errors. Due to the nature of `windows.h`, +some unneeded declarations are still pulled in, however the number is greatly reduced. +Code that needs these declarations should explicitly include `windows.h` before `epicsAtomic.h`. + ### epicsExport simplifications `epicsExportAddress()`, `epicsExportRegistrar()` and `epicsRegisterFunction()` From 6ea6ae633b9ea1d97fe5a2c7eabcc2de2c6be4e0 Mon Sep 17 00:00:00 2001 From: Jeremy Lorelli Date: Sat, 15 Feb 2025 13:05:02 -0800 Subject: [PATCH 019/446] Define NOCRYPT, NOSOUND and NOKANJI before including windows.h --- .../libcom/src/osi/os/WIN32/epicsAtomicOSD.h | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h b/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h index 46a4a85aa7..a1221deb71 100644 --- a/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h +++ b/modules/libcom/src/osi/os/WIN32/epicsAtomicOSD.h @@ -53,6 +53,21 @@ #undef NOGDI #define NOGDI +/* Disable crypto stuff */ +#pragma push_macro("NOCRYPT") +#undef NOCRYPT +#define NOCRYPT + +/* Disable sound driver routines */ +#pragma push_macro("NOSOUND") +#undef NOSOUND +#define NOSOUND + +/* Disable Kanji writing system support */ +#pragma push_macro("NOKANJI") +#undef NOKANJI +#define NOKANJI + #include "windows.h" /* Restore previous macro values */ @@ -63,6 +78,9 @@ #pragma pop_macro("NOIME") #pragma pop_macro("NOMCX") #pragma pop_macro("NOGDI") +#pragma pop_macro("NOCRYPT") +#pragma pop_macro("NOSOUND") +#pragma pop_macro("NOKANJI") #if defined ( _WIN64 ) # define MS_ATOMIC_64 From e4ebc014011c8c1ae98a5de6d15c2aed76885e70 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Wed, 26 Feb 2025 20:15:06 -0600 Subject: [PATCH 020/446] Fix EPICS::PodXHtml and generate section links Overrides an internal method in Pod::Simple::XHTML that appends a section sign which links to this section. --- src/tools/EPICS/PodXHtml.pm | 23 +++++++++++++++++++++-- src/tools/style.css | 5 +++++ 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/src/tools/EPICS/PodXHtml.pm b/src/tools/EPICS/PodXHtml.pm index d392129889..3a5e645024 100644 --- a/src/tools/EPICS/PodXHtml.pm +++ b/src/tools/EPICS/PodXHtml.pm @@ -7,8 +7,8 @@ use base 'Pod::Simple::XHTML'; BEGIN { if ($Pod::Simple::XHTML::VERSION < '3.16') { - # encode_entities() wasn't a method, add it - our *encode_entities = sub { + # Add encode_entities() as a method + sub encode_entities { my ($self, $str) = @_; my %entities = ( q{>} => 'gt', @@ -37,4 +37,23 @@ sub resolve_pod_page_link { return $ret; } +sub _end_head { + my $h = delete $_[0]{in_head}; + + my $add = $_[0]->html_h_level; + $add = 1 unless defined $add; + $h += $add - 1; + + my $id = $_[0]->idify($_[0]{htext}); + my $text = $_[0]{scratch}; + my $hid = qq{}; + my $link = qq{ §}; + $_[0]{'scratch'} = $_[0]->backlink && ($h - $add == 0) + # backlinks enabled && =head1 + ? qq{$hid$text $link} + : qq{$hid$text $link}; + $_[0]->emit; + push @{ $_[0]{'to_index'} }, [$h, $id, delete $_[0]{'htext'}]; +} + 1; diff --git a/src/tools/style.css b/src/tools/style.css index 09647403b3..06df90945c 100644 --- a/src/tools/style.css +++ b/src/tools/style.css @@ -69,6 +69,11 @@ A[href="#POD_ERRORS"] { color: #FF0000; } +A.sect { + color: #99ccff; + vertical-align: super; +} + TD { margin: 0; padding: 0; From 0c75f1fe99a0984397b927645215c4dae365ad3f Mon Sep 17 00:00:00 2001 From: Minijackson Date: Mon, 20 Jan 2025 13:44:09 +0100 Subject: [PATCH 021/446] import CAref function and return codes reference to doxygen comments Import all function documentations, return code reference into the header files, as doc comments, in the hopes of moving the CAref.html manual to docs.epics-controls.org, which will be done in a later PR. Also added doc comments to some other low-hanging fruits, for example when plain comments where near, or when it was obvious to do so. --- documentation/Makefile | 7 +- documentation/ca-API.rst | 7 + documentation/index.rst | 1 + modules/ca/src/client/cadef.h | 1555 +++++++++++++++++++++++---- modules/ca/src/client/caerr.h | 71 ++ modules/ca/src/client/caeventmask.h | 44 +- modules/ca/src/client/db_access.h | 39 +- 7 files changed, 1484 insertions(+), 240 deletions(-) create mode 100644 documentation/ca-API.rst diff --git a/documentation/Makefile b/documentation/Makefile index 8f509757cd..ee7ff29a48 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -65,6 +65,11 @@ libcom_HEADERS += yajl_common libcom_HEADERS += yajl_gen libcom_HEADERS += yajl_parse +ca_HEADERS += cadef +ca_HEADERS += caerr +ca_HEADERS += caeventmask +ca_HEADERS += db_access + database_HEADERS += chfPlugin database_HEADERS += dbChannel database_HEADERS += dbCommon @@ -128,7 +133,7 @@ menu_HEADERS += menuScan menu_HEADERS += menuSimm menu_HEADERS += menuYesNo -HEADER_TYPES = libcom database record menu +HEADER_TYPES = libcom ca database record menu HEADER_MD_FILES = $(foreach t, $(HEADER_TYPES), \ $(addsuffix _h.md, $($t_HEADERS))) diff --git a/documentation/ca-API.rst b/documentation/ca-API.rst new file mode 100644 index 0000000000..0f24288d3e --- /dev/null +++ b/documentation/ca-API.rst @@ -0,0 +1,7 @@ +Channel Access C/C++ APIs +========================= + +.. toctree:: + :maxdepth: 1 + :caption: CA Header Files + diff --git a/documentation/index.rst b/documentation/index.rst index 9f7ebfa354..0bed60cc3a 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -25,6 +25,7 @@ EPICS Base Documentation :caption: C/C++ Headers libcom-api + ca-api database-api record-api menu-api diff --git a/modules/ca/src/client/cadef.h b/modules/ca/src/client/cadef.h index 12861c3845..32de6a8fe1 100644 --- a/modules/ca/src/client/cadef.h +++ b/modules/ca/src/client/cadef.h @@ -7,6 +7,7 @@ * EPICS BASE is distributed subject to a Software License Agreement found * in file LICENSE that is included with this distribution. \*************************************************************************/ + /* * * L O S A L A M O S @@ -21,6 +22,11 @@ * */ +/** \file cadef.h + * + * \brief Channel Access library. + */ + #ifndef INC_cadef_H #define INC_cadef_H @@ -43,29 +49,34 @@ extern "C" { #endif +/** \brief Channel identifier. */ typedef struct oldChannelNotify *chid; +/** \brief Channel identifier. */ typedef chid chanId; /* for when the structures field name is "chid" */ typedef long chtype; typedef struct oldSubscription *evid; typedef double ca_real; -/* arguments passed to user connection handlers */ +/** \brief Arguments passed to user connection handlers. */ struct connection_handler_args { - chanId chid; /* channel id */ - long op; /* one of CA_OP_CONN_UP or CA_OP_CONN_DOWN */ + chanId chid; /**< channel id */ + long op; /**< one of ::CA_OP_CONN_UP or ::CA_OP_CONN_DOWN */ }; typedef void caCh (struct connection_handler_args args); +/** \brief Access rights. + */ typedef struct ca_access_rights { - unsigned read_access:1; - unsigned write_access:1; + unsigned read_access:1; /**< Read access. */ + unsigned write_access:1; /**< Write access. */ } caar; -/* arguments passed to user access rights handlers */ +/** \brief Arguments passed to user access rights handlers + */ struct access_rights_handler_args { - chanId chid; /* channel id */ - caar ar; /* new access rights state */ + chanId chid; /**< Channel id. */ + caar ar; /**< New access rights state. */ }; typedef void caArh (struct access_rights_handler_args args); @@ -73,8 +84,7 @@ typedef void caArh (struct access_rights_handler_args args); /* The conversion routine to call for each type */ #define VALID_TYPE(TYPE) (((unsigned short)TYPE)<=LAST_BUFFER_TYPE) -/* - * Arguments passed to event handlers and get/put call back handlers. +/** \brief Arguments passed to event handlers and get/put call back handlers. * * The status field below is the CA ECA_XXX status of the requested * operation which is saved from when the operation was attempted in the @@ -83,32 +93,46 @@ typedef void caArh (struct access_rights_handler_args args); * and the requested operation can not be assumed to be successful. */ typedef struct event_handler_args { - void *usr; /* user argument supplied with request */ - chanId chid; /* channel id */ - long type; /* the type of the item returned */ - long count; /* the element count of the item returned */ - const void *dbr; /* a pointer to the item returned */ - int status; /* ECA_XXX status of the requested op from the server */ + void *usr; /**< User argument supplied with request. */ + chanId chid; /**< Channel id. */ + long type; /**< The type of the item returned. */ + long count; /**< The element count of the item returned. */ + const void *dbr; /**< A pointer to the item returned. */ + int status; /**< `ECA_XXXX` status of the requested op from the server. */ } evargs; typedef void caEventCallBackFunc (struct event_handler_args); +/** \brief A built-in subscription update callback handler + * for debugging purposes that prints diagnostics to standard out. + * + * # Examples + * + * ```c + * void ca_test_event (); + * status = ca_create_subscription ( type, chid, ca_test_event, NULL, NULL ); + * SEVCHK ( status, .... ); + * ``` + * + * \sa ca_create_subscription() + */ LIBCA_API void epicsStdCall ca_test_event ( struct event_handler_args ); -/* arguments passed to user exception handlers */ +/** \brief Arguments passed to user exception handlers. + */ struct exception_handler_args { - void *usr; /* user argument supplied when installed */ - chanId chid; /* channel id (may be nill) */ - long type; /* type requested */ - long count; /* count requested */ - void *addr; /* user's address to write results of CA_OP_GET */ - long stat; /* channel access ECA_XXXX status code */ - long op; /* CA_OP_GET, CA_OP_PUT, ..., CA_OP_OTHER */ - const char *ctx; /* a character string containing context info */ - const char *pFile; /* source file name (may be NULL) */ - unsigned lineNo; /* source file line number (may be zero) */ + void *usr; /**< User argument supplied when installed */ + chanId chid; /**< Channel id (may be null) */ + long type; /**< Type requested */ + long count; /**< Count requested */ + void *addr; /**< User's address to write results of ::CA_OP_GET */ + long stat; /**< Channel access ECA_XXXX status code */ + long op; /**< ::CA_OP_GET, ::CA_OP_PUT, ..., ::CA_OP_OTHER */ + const char *ctx; /**< A character string containing context info */ + const char *pFile; /**< Source file name (may be NULL) */ + unsigned lineNo; /**< Source file line number (may be zero) */ }; typedef unsigned CA_SYNC_GID; @@ -116,24 +140,54 @@ typedef unsigned CA_SYNC_GID; /* * External OP codes for CA operations */ + +/** \brief GET Channel Access operation. */ #define CA_OP_GET 0 +/** \brief PUT Channel Access operation. */ #define CA_OP_PUT 1 +/** \brief CREATE_CHANNEL Channel Access operation. */ #define CA_OP_CREATE_CHANNEL 2 +/** \brief ADD_EVENT Channel Access operation. */ #define CA_OP_ADD_EVENT 3 +/** \brief CLEAR_EVENT Channel Access operation. */ #define CA_OP_CLEAR_EVENT 4 +/** \brief Other Channel Access operation. */ #define CA_OP_OTHER 5 -/* - * used with connection_handler_args +/** \brief Connection up Channel Access operation. + * + * Used with connection_handler_args */ #define CA_OP_CONN_UP 6 + +/** \brief Connection down Channel Access operation. + * + * Used with connection_handler_args + */ #define CA_OP_CONN_DOWN 7 -/* deprecated */ +/** \brief SEARCH Channel Access operation. + * + * \deprecated + */ #define CA_OP_SEARCH 2 -/* - * provides efficient test and display of channel access errors +/** \brief Provides efficient test and display of channel access errors. + * + * SEVCHK() is a macro envelope around ca_signal() which only calls + * ca_signal() if the supplied error code indicates an unsuccessful + * operation. SEVCHK() is the recommended error handler for simple applications + * which do not wish to write code testing the status returned from each + * channel access call. + * + * # Examples + * + * ```c + * status = ca_context_create (...); + * SEVCHK ( status, "Unable to create a CA client context" ); + * ``` + * + * \sa ca_signal(). */ #define SEVCHK(CA_ERROR_CODE, MESSAGE_STRING) \ { \ @@ -146,25 +200,85 @@ typedef unsigned CA_SYNC_GID; __LINE__); \ } +/** \brief The channel's native type when disconnected. */ +#define TYPENOTCONN (-1) -#define TYPENOTCONN (-1) /* the channel's native type when disconnected */ +/** \brief Return the native type in the server of the process variable. + * + * \param[in] chan Channel identifier. + * \returns The data type code will be a member of the set of `DBF_XXXX` in `db_access.h`. + * The constant TYPENOTCONN is returned if the channel is disconnected. + */ LIBCA_API short epicsStdCall ca_field_type (chid chan); + +/** \brief Return the maximum array element count in the server for the specified IO channel. + * + * \param[in] chan Channel identifier. + * \returns The maximum array element count in the server. + * An element count of zero is returned if the channel is disconnected. + */ LIBCA_API unsigned long epicsStdCall ca_element_count (chid chan); + +/** \brief Return the name provided when the supplied channel id was created. + * + * \param[in] chan Channel identifier. + * \returns The channel name. + * The string returned is valid as long as the channel specified exists. + */ LIBCA_API const char * epicsStdCall ca_name (chid chan); + +/** \brief Set a user private void pointer variable retained + * with each channel for use at the users discretion. + * + * \param[in] chan Channel identifier. + * \param[in] puser user private void pointer + */ LIBCA_API void epicsStdCall ca_set_puser (chid chan, void *puser); + +/** \brief Return a user private void pointer variable + * retained with each channel for use at the users discretion. + * + * \param[in] chan Channel identifier. + * \returns User private pointer + */ LIBCA_API void * epicsStdCall ca_puser (chid chan); + +/** \brief Returns whether the client currently has read access + * to the specified channel. + * + * \param[in] chan Channel identifier. + * \returns Boolean true if the client currently has read access to the specified channel + * and boolean false otherwise. + */ LIBCA_API unsigned epicsStdCall ca_read_access (chid chan); + +/** \brief Returns whether the client currently has write access + * to the specified channel. + * + * \param[in] chan Channel identifier. + * \returns Boolean true if the client currently has write access to the specified channel + * and boolean false otherwise + */ LIBCA_API unsigned epicsStdCall ca_write_access (chid chan); -/* - * cs_ - `channel state' +/** \brief Channel state + */ +enum channel_state { + /// valid chid, IOC not found or unavailable + cs_never_conn, + /// valid chid, IOC was found, but unavailable (previously connected to server) + cs_prev_conn, + /// valid chid, IOC was found, still available + cs_conn, + /// channel deleted by user + cs_closed +}; + +/** \brief Returns an enumerated type indicating the current state of the specified IO channel. * - * cs_never_conn valid chid, IOC not found - * cs_prev_conn valid chid, IOC was found, but unavailable - * cs_conn valid chid, IOC was found, still available - * cs_closed channel deleted by user + * \param[in] chan Channel identifier. + * \returns the connection state. */ -enum channel_state {cs_never_conn, cs_prev_conn, cs_conn, cs_closed}; LIBCA_API enum channel_state epicsStdCall ca_state (chid chan); /************************************************************************/ @@ -172,19 +286,121 @@ LIBCA_API enum channel_state epicsStdCall ca_state (chid chan); /* */ /* Must be called once before calling any of the other routines */ /************************************************************************/ + +/** \brief Initialize a Channel Access task. + * + * \deprecated Use ca_context_create() instead. + */ LIBCA_API int epicsStdCall ca_task_initialize (void); + enum ca_preemptive_callback_select { ca_disable_preemptive_callback, ca_enable_preemptive_callback }; + +/** \brief Create a Channel Access context. + * + * This function, or ca_attach_context(), should be called once from each + * thread prior to making any of the other Channel Access calls. If one of the + * above is not called before making other CA calls then a non-preemptive + * context is created by default, and future attempts to create a preemptive + * context for the current threads will fail. + * + * If ::ca_disable_preemptive_callback is specified then additional threads are + * *not* allowed to join the CA context using ca_attach_context() because + * allowing other threads to join implies that CA callbacks will be called + * preemptively from more than one thread. + * + * \param[in] select + * \parblock + * This argument specifies if preemptive invocation of callback + * functions is allowed. If so your callback functions might be called + * when the thread that calls this routine is not executing in the CA + * client library. There are two implications to consider. + * + * First, if preemptive callback mode is enabled the developer must + * provide mutual exclusion protection for his data structures. In this + * mode it's possible for two threads to touch the application's data + * structures at once: this might be the initializing thread (the + * thread that called ca_context_create()) and also a private thread + * created by the CA client library for the purpose of receiving + * network messages and calling callbacks. It might be prudent for + * developers who are unfamiliar with mutual exclusion locking in a + * multi-threaded environment to specify + * ::ca_disable_preemptive_callback. + * + * Second, if preemptive callback mode is enabled the application is no + * longer burdened with the necessity of periodically polling the CA + * client library in order that it might take care of its background + * activities. If ca_enable_preemptive_callback is specified then CA + * client background activities, such as connection management, will + * proceed even if the thread that calls this routine is not executing + * in the CA client library. Furthermore, in preemptive callback mode + * callbacks might be called with less latency because the library is + * not required to wait until the initializing thread (the thread that + * called ca_context_create()) is executing within the CA client library. + * \endparblock + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_ALLOCMEM - Failed, unable to allocate space in pool + * \returns ::ECA_NOTTHREADED - Current thread is already a member of a non-preemptive callback CA context (possibly created implicitly) + * + * \sa ca_context_destroy() + */ LIBCA_API int epicsStdCall ca_context_create (enum ca_preemptive_callback_select select); -LIBCA_API void epicsStdCall ca_detach_context (); + +/** \brief Detach from any CA context currently attached to the calling thread. + * + * This does *not* cleanup or shutdown any currently attached CA context (for + * that use ca_context_destroy()). + * + * \sa ca_current_context(), ca_attach_context(), ca_context_create(), ca_context_destroy() + */ +LIBCA_API void epicsStdCall ca_detach_context (); /************************************************************************/ /* Remove CA facility from your task */ /* */ /* Normally called automatically at task exit */ /************************************************************************/ + +/** \brief Exit a Channel Access task. + * + * \deprecated Use ca_context_destroy() instead. + */ LIBCA_API int epicsStdCall ca_task_exit (void); + +/** \brief Destroy a Channel Access context. + * + * Shut down the calling thread's channel access client context and free + * any resources allocated. Detach the calling thread from any CA client + * context. + * + * Any user-created threads that have attached themselves to the CA context + * must stop using it prior to its being destroyed. A program running in an + * IOC context must delete all of its channels prior to calling + * ca_context_destroy() to avoid a crash. + * + * A CA client application that calls epicsExit() *must* install an EPICS + * exit handler that calls ca_context_destroy() only *after* first + * calling ca_context_create(). This will guarantee that the EPICS exit + * handlers get called in the correct order. + * + * On many OS that execute programs in a process based environment the + * resources used by the client library such as sockets and allocated + * memory are automatically released by the system when the process exits + * and ca_context_destroy() hasn't been called, but on light weight + * systems such as vxWorks or RTEMS no cleanup occurs unless the + * application calls ca_context_destroy(). + * + * \note This operation blocks until any user callbacks for any channel + * created in the current context have run to completion. If callbacks take + * a lock (mutex) then it is the user's responsibility to ensure that this + * lock is not held when ca_clear_context() is called, otherwise a + * deadlock may ensue. (See also ca_clear_channel() and + * ca_clear_subscription().) + * + * \sa ca_context_create() + */ LIBCA_API void epicsStdCall ca_context_destroy (void); typedef unsigned capri; @@ -196,17 +412,102 @@ typedef unsigned capri; #define CA_PRIORITY_ARCHIVE 20 #define CA_PRIORITY_OPI 0 -/* - * ca_create_channel () - * - * pChanName R channel name string - * pConnStateCallback R address of connection state change - * callback function - * pUserPrivate R placed in the channel's user private field - * o can be fetched later by ca_puser(CHID) - * o passed as void * arg to *pConnectCallback above - * priority R priority level in the server 0 - 100 - * pChanID RW channel id written here +/** \brief Create a Channel Access channel. + * + * This function creates a CA channel. The CA client library will attempt + * to establish and maintain a virtual circuit between the caller's + * application and a named process variable in a CA server. Each call to + * ca_create_channel() allocates resources in the CA client library and + * potentially also a CA server. The function ca_clear_channel() is used + * to release these resources. If successful, the routine writes a channel + * identifier into the user's variable of type "chid". This identifier + * can be used with any channel access call that operates on a channel. + * + * The circuit may be initially connected or disconnected depending on the + * state of the network and the location of the channel. A channel will + * only enter a connected state after the server's address is determined, + * and only if channel access successfully establishes a virtual circuit + * through the network to the server. Channel access routines that send a + * request to a server will return ::ECA_DISCONNCHID if the channel is + * currently disconnected. + * + * There are two ways to obtain asynchronous notification when a channel + * enters a connected state. + * + * - The first and simplest method requires that you call ca_pend_io(), + * and wait for successful completion, prior to using a channel that + * was created specifying a null connection callback function pointer. + * - The second method requires that you register a connection handler by + * supplying a valid connection callback function pointer. This + * connection handler is called whenever the connection state of the + * channel changes. If you have installed a connection handler then + * ca_pend_io() will *not* block waiting for the channel to enter a + * connected state. + * + * The function ca_state(CHID) can be used to test the connection state of + * a channel. Valid connections may be isolated from invalid ones with this + * function if ca_pend_io() times out. + * + * Due to the inherently transient nature of network connections the order + * of connection callbacks relative to the order that ca_create_channel() + * calls are made by the application can't be guaranteed, and application + * programs may need to be prepared for a connected channel to enter a + * disconnected state at any time. + * + * # Example + * + * See `caExample.c` in the example application created by `makeBaseApp.pl`. + * + * \param[in] pChanName A nil terminated process variable name string. + * \parblock + * EPICS process control * function block database variable names are of the + * form `.`. If the field name and the period + * separator are omitted then the `VAL` field is implicit. For example + * `RFHV01` and `RFHV01.VAL` reference the same EPICS process control function + * block database variable. + * \endparblock + * + * \param[in] pConnStateCallback address of connection state change callback function + * \parblock + * Optional pointer to the user's callback function to be run when the + * connection state changes. Casual users of channel access may decide + * to set this field to null or 0 if they do not need to have a + * callback function run in response to each connection state change + * event. + * + * A connection_handler_args structure is passed *by value* to the user's + * connection callback function. The `op` field will be set by the CA + * client library to ::CA_OP_CONN_UP when the channel connects, and to + * ::CA_OP_CONN_DOWN when the channel disconnects. See ca_puser() + * if the `pUserPrivate` argument is required in your callback handler. + * \endparblock + * + * \param[in] pUserPrivate The value of this void pointer argument is retained in storage + * associated with the specified channel. + * Casual users of channel access may wish to set this field to null or 0. + * Can be fetched later by ca_puser(CHID). + * passed as `void *` arg to `*pConnStateCallback` above + * + * \param[in] priority The priority level for dispatch within the server or + * network with 0 specifying the lowest dispatch priority and 99 the highest. + * This parameter currently does not impact dispatch priorities within the + * client, but this might change in the future. The abstract priority range + * specified is mapped into an operating system specific range of priorities + * within the server. This parameter is ignored if the server is running on a + * network or operating system that does not have native support for + * prioritized delivery or execution respectively. Specifying many different + * priorities within the same program can increase resource consumption in the + * client and the server because an independent virtual circuit, and associated + * data structures, is created for each priority that is used on a particular + * server. + * + * \param[inout] pChanID The user supplied channel identifier storage is overwritten + * with a channel identifier if this routine is successful. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_STRTOBIG - Unusually large string + * \returns ::ECA_ALLOCMEM - Unable to allocate memory */ LIBCA_API int epicsStdCall ca_create_channel ( @@ -229,38 +530,112 @@ LIBCA_API int epicsStdCall ca_change_connection_event caCh * pfunc ); -/* - * ca_replace_access_rights_event () +/** \brief Install or replace the access rights state change callback handler + * for the specified channel. * - * chan R channel identifier - * pfunc R address of access rights call-back function + * The callback handler is called in the following situations. + * + * - whenever CA connects the channel immediately before the channel's + * connection handler is called + * - whenever CA disconnects the channel immediately after the channel's + * disconnect callback is called + * - once immediately after installation if the channel is connected. + * - whenever the access rights state of a connected channel changes + * + * When a channel is created no access rights handler is installed. + * + * \param[in] chan Channel identifier. + * \param[in] pfunc Pointer to a user supplied callback function. + * A null pointer uninstalls the current handler. + * An access_rights_handler_args structure is passed *by value* to the supplied callback handler. + * + * \returns ::ECA_NORMAL - Normal successful completion */ LIBCA_API int epicsStdCall ca_replace_access_rights_event ( chid chan, caArh *pfunc ); -/* - * ca_add_exception_event () - * - * replace the default exception handler - * - * pfunc R address of exception call-back function - * pArg R copy of this pointer passed to exception - * call-back function - */ typedef void caExceptionHandler (struct exception_handler_args); + +/** \brief Replace the currently installed CA context global exception handler callback. + * + * When an error occurs in the server asynchronous to the clients thread then + * information about this type of error is passed from the server to the client + * in an exception message. When the client receives this exception message an + * exception handler callback is called. The default exception handler prints a + * diagnostic message on the client's standard out and terminates execution if + * the error condition is severe. + * + * Note that certain fields in struct exception_handler_args are not + * applicable in the context of some error messages. For instance, a failed get + * will supply the address in the client task where the returned value was + * requested to be written. For other failed operations the value of the addr + * field should not be used. + * + * # Example + * + * ```c + * void ca_exception_handler ( + * struct exception_handler_args args) + * { + * char buf[512]; + * char *pName; + * + * if ( args.chid ) { + * pName = ca_name ( args.chid ); + * } + * else { + * pName = "?"; + * } + * sprintf ( buf, + * "%s - with request chan=%s op=%d data type=%s count=%d", + * args.ctx, pName, args.op, dbr_type_to_text ( args.type ), args.count ); + * ca_signal ( args.stat, buf ); + * } + * ca_add_exception_event ( ca_exception_handler , 0 ); + * ``` + * + * \param[in] pfunc Pointer to a user callback function to be executed when exceptions occur. + * Passing a null value causes the default exception handler to be reinstalled. + * An exception_handler_args structure is passed by value to the user's callback function. + * Currently, the `op` field can be one of ::CA_OP_GET, ::CA_OP_PUT, + * ::CA_OP_CREATE_CHANNEL, ::CA_OP_ADD_EVENT, ::CA_OP_CLEAR_EVENT, + * or ::CA_OP_OTHER. + * + * \param[in] pArg Pointer sized variable retained and passed back to user function above. + * + * \returns ::ECA_NORMAL - Normal successful completion + */ LIBCA_API int epicsStdCall ca_add_exception_event ( caExceptionHandler *pfunc, void *pArg ); -/* - * ca_clear_channel() - * - deallocate resources reserved for a channel +/** \brief Shutdown and reclaim resources associated with a channel created by ca_create_channel(). + * + * All remote operation requests such as the above are accumulated + * (buffered) and not forwarded to the IOC until one of ca_flush_io(), + * ca_pend_io(), ca_pend_event(), or ca_sg_block() are called. This + * allows several requests to be efficiently sent over the network in one + * message. + * + * Clearing a channel does not cause its disconnect handler to be called, + * but clearing a channel does shutdown and reclaim any channel state + * change event subscriptions (monitors) registered with the channel. + * + * Note: This operation blocks until any user callbacks for this channel + * have run to completion. If callbacks take a lock (mutex) then it is the + * user's responsibility to ensure that this lock is not held when + * ca_clear_channel() is called, otherwise a deadlock may ensue. * - * chanId R channel ID + * \sa ca_clear_subscription() + * + * \param[in] chanId Identifies the channel to delete. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID */ LIBCA_API int epicsStdCall ca_clear_channel ( @@ -293,22 +668,108 @@ ca_array_put(DBR_STRING, 1u, chan, (const dbr_string_t *) (pValue)) #define ca_rput(chan,pValue) \ ca_array_put(DBR_FLOAT, 1u, chan, (const dbr_float_t *) pValue) -/* - * ca_put() +/** \brief Write a scalar value to a process variable. + * + * See ca_array_put(). + * + * \param[in] type The external type of the supplied value to be written. + * Conversion will occur if this does not match the native type. Specify one + * from the set of `DBR_XXXX` in `db_access.h` * - * type R data type from db_access.h - * chan R channel identifier - * pValue R new channel value copied from this location + * \param[in] chan Channel identifier. + * + * \param[in] pValue Pointer to a value or array of values provided by the application + * to be written to the channel. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_NOWTACCESS - Write access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ #define ca_put(type, chan, pValue) ca_array_put (type, 1u, chan, pValue) -/* - * ca_array_put() +/** \brief Write a scalar or array value to a process variable. * - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pValue R new channel value copied from this location + * When ca_put() or ca_array_put() are invoked the client will receive + * no response unless the request can not be fulfilled in the server. If + * unsuccessful an exception handler is run on the client side. + * + * When ca_put_callback() or ca_array_put_callback() are invoked the + * user supplied asynchronous callback is called only after the initiated + * write operation, and all actions resulting from the initiating write + * operation, complete. The arguments to the user supplied callback function + * are declared in the structure event_handler_args and include the pointer + * sized user argument supplied when ca_array_put_callback() is called. + * + * If unsuccessful the callback function is invoked indicating failure + * status. + * + * If the channel disconnects before a put callback request can be + * completed, then the client's callback function is called with failure + * status, but this does not guarantee that the server did not receive and + * process the request before the disconnect. If a connection is lost and + * then resumed outstanding ca put requests are not automatically reissued + * following reconnect. + * + * All of these functions return ::ECA_DISCONN if the channel is currently + * disconnected. + * + * All put requests are accumulated (buffered) and not forwarded to the IOC + * until one of ca_flush_io(), ca_pend_io(), ca_pend_event(), or + * ca_sg_block() are called. This allows several requests to be + * efficiently combined into one message. + * + * # Description (IOC Database Specific) + * + * A CA put request causes the record to process if the record's SCAN + * field is set to passive, and the field being written has its process + * passive attribute set to true. If such a record is already processing + * when a put request is initiated the specified field is written + * immediately, and the record is scheduled to process again as soon as it + * finishes processing. Earlier instances of multiple put requests + * initiated while the record is being processing may be discarded, but the + * last put request initiated is always written and processed. + * + * A CA put *callback* request causes the record to process if the + * record's SCAN field is set to passive, and the field being written has + * its process passive attribute set to true. For such a record, the + * user's put callback function is not called until after the record, and + * any records that the record links to, finish processing. If such a + * record is already processing when a put *callback* request is initiated + * the put *callback* request is postponed until the record, and any + * records it links to, finish processing. + * + * If the record's SCAN field is not set to passive, or the field being + * written has its process passive attribute set to false then the CA put + * or CA put *callback* request cause the specified field to be immediately + * written, but they do not cause the record to be processed. + * + * \sa ca_flush_io(), ca_pend_event(), ca_sg_array_put() + * + * \param[in] type The external type of the supplied value to be written. + * Conversion will occur if this does not match the native type. Specify one + * from the set of `DBR_XXXX` in `db_access.h` + * + * \param[in] count Element count to be written to the specified channel. + * This must match the array pointed to by pValue. + * + * \param[in] chanId Channel identifier. + * + * \param[in] pValue Pointer to a value or array of values provided by the application + * to be written to the channel. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_NOWTACCESS - Write access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ LIBCA_API int epicsStdCall ca_array_put ( @@ -318,22 +779,36 @@ LIBCA_API int epicsStdCall ca_array_put const void * pValue ); -/* - * ca_array_put_callback() +/** \brief Asynchronously write a scalar or array value to a process variable. * - * This routine functions identically to the original ca put request - * with the addition of a callback to the user supplied function - * after recod processing completes in the IOC. The arguments - * to the user supplied callback function are declared in - * the structure event_handler_args and include the pointer - * sized user argument supplied when ca_array_put_callback() is called. + * See ca_array_put(). * - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pValue R new channel value copied from this location - * pFunc R pointer to call-back function - * pArg R copy of this pointer passed to pFunc + * \param[in] type The external type of the supplied value to be written. + * Conversion will occur if this does not match the native type. Specify one + * from the set of `DBR_XXXX` in `db_access.h` + * + * \param[in] count Element count to be written to the specified channel. + * This must match the array pointed to by pValue. + * + * \param[in] chanId Channel identifier. + * + * \param[in] pValue Pointer to a value or array of values provided by the application + * to be written to the channel. + * + * \param[in] pFunc Pointer to a user supplied callback function to be run + * when the requested operation completes. + * + * \param[in] pArg Pointer sized variable retained + * and then passed back to user supplied function above. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_NOWTACCESS - Write access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ LIBCA_API int epicsStdCall ca_array_put_callback ( @@ -345,6 +820,34 @@ LIBCA_API int epicsStdCall ca_array_put_callback void * pArg ); +/** \brief Asynchronously write a scalar value to a process variable. + * + * See ca_array_put(). + * + * \param[in] type The external type of the supplied value to be written. + * Conversion will occur if this does not match the native type. Specify one + * from the set of `DBR_XXXX` in `db_access.h` + * + * \param[in] chan Channel identifier. + * + * \param[in] pValue Pointer to a value or array of values provided by the application + * to be written to the channel. + * + * \param[in] pFunc Pointer to a user supplied callback function to be run + * when the requested operation completes. + * + * \param[in] pArg Pointer sized variable retained + * and then passed back to user supplied function above. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_NOWTACCESS - Write access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected + */ #define ca_put_callback(type, chan, pValue, pFunc, pArg) \ ca_array_put_callback(type, 1u, chan, pValue, pFunc, pArg) @@ -375,22 +878,88 @@ ca_array_get(DBR_STRING, 1u, chan, (dbr_string_t *)(pValue)) #define ca_rget(chan, pValue) \ ca_array_get(DBR_FLOAT, 1u, chan, (dbr_float_t *)(pValue)) -/* - * ca_rget() +/** \brief Read a scalar value from a process variable. * - * type R data type from db_access.h - * chan R channel identifier - * pValue W channel value copied to this location + * See ca_array_get(). + * + * \param[in] type The external type of the user variable to return the value into. + * Conversion will occur if this does not match the native type. + * Specify one from the set of DBR_XXXX in db_access.h + * + * \param[in] chan Channel identifier. + * + * \param[out] pValue Pointer to an application supplied buffer + * where the current value of the channel is to be written. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_GETFAIL - A local database get failed + * \returns ::ECA_NORDACCESS - Read access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ #define ca_get(type, chan, pValue) ca_array_get(type, 1u, chan, pValue) -/* - * ca_array_get() +/** \brief Read a scalar or array value from a process variable. * - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pValue W channel value copied to this location + * When ca_get() or ca_array_get() are invoked the returned channel + * value can't be assumed to be stable in the application supplied buffer + * until after ECA_NORMAL is returned from ca_pend_io(). If a connection + * is lost outstanding ca get requests are not automatically reissued + * following reconnect. + * + * When ca_get_callback() or ca_array_get_callback() are invoked a + * value is read from the channel and then the user's callback is invoked + * with a pointer to the retrieved value. Note that ca_pend_io() will not + * block for the delivery of values requested by ca_get_callback(). If + * the channel disconnects before a ca_get_callback() request can be + * completed, then the client's callback function is called with failure + * status. + * + * All of these functions return ::ECA_DISCONN if the channel is currently + * disconnected. + * + * All get requests are accumulated (buffered) and not forwarded to the IOC + * until one of ca_flush_io(), ca_pend_io(), ca_pend_event(), or + * ca_sg_block() are called. This allows several requests to be + * efficiently sent over the network in one message. + * + * ## Description (IOC Database Specific) + * + * A CA get or CA get callback request causes the record's field to be + * read immediately independent of whether the record is currently being + * processed or not. There is currently no mechanism in place to cause a + * record to be processed when a CA get request is initiated. + * + * # Example + * + * See `caExample.c` in the example application created by `makeBaseApp.pl`. + * + * \sa ca_pend_io(), ca_pend_event(), ca_sg_array_get() + * + * \param[in] type The external type of the user variable to return the value into. + * Conversion will occur if this does not match the native type. + * Specify one from the set of DBR_XXXX in db_access.h + * + * \param[in] count Element count to be read from the specified channel. + * Must match the array pointed to by pValue. + * For ca_array_get_callback() a count of zero means use the current element count from the server. + * + * \param[in] chanId Channel identifier. + * + * \param[out] pValue Pointer to an application supplied buffer + * where the current value of the channel is to be written. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_GETFAIL - A local database get failed + * \returns ::ECA_NORDACCESS - Read access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ LIBCA_API int epicsStdCall ca_array_get ( @@ -431,25 +1000,62 @@ ca_array_get_callback (DBR_STRING, 1u, chan, pFunc, pArg) #define ca_rget_callback(chan, pFunc, pArg)\ ca_array_get_callback (DBR_FLOAT, 1u, chan, pFunc, pArg) -/* - * ca_get_callback() +/** \brief Asynchronously read a scalar value from a process variable. * - * type R data type from db_access.h - * chan R channel identifier - * pFunc R pointer to call-back function - * pArg R copy of this pointer passed to pFunc + * See ca_array_get(). + * + * \param[in] type The external type of the user variable to return the value into. + * Conversion will occur if this does not match the native type. + * Specify one from the set of DBR_XXXX in db_access.h + * + * \param[in] chan Channel identifier. + * + * \param[in] pFunc Pointer to a user supplied callback function to be run + * when the requested operation completes. + * + * \param[in] pArg Pointer sized variable retained + * and then passed back to user supplied callback function above. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_GETFAIL - A local database get failed + * \returns ::ECA_NORDACCESS - Read access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ #define ca_get_callback(type, chan, pFunc, pArg)\ ca_array_get_callback (type, 1u, chan, pFunc, pArg) -/* - * ca_array_get_callback() +/** \brief Asynchronously read a scalar or array value from a process variable. * - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pFunc R pointer to call-back function - * pArg R copy of this pointer passed to pFunc + * See ca_array_get(). + * + * \param[in] type The external type of the user variable to return the value into. + * Conversion will occur if this does not match the native type. + * Specify one from the set of DBR_XXXX in db_access.h + * + * \param[in] count Element count to be read from the specified channel. + * Must match the array pointed to by pValue. + * For ca_array_get_callback() a count of zero means use the current element count from the server. + * + * \param[in] chanId Channel identifier. + * + * \param[in] pFunc Pointer to a user supplied callback function to be run + * when the requested operation completes. + * + * \param[in] pArg Pointer sized variable retained + * and then passed back to user supplied callback function above. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_GETFAIL - A local database get failed + * \returns ::ECA_NORDACCESS - Read access denied + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_DISCONN - Channel is disconnected */ LIBCA_API int epicsStdCall ca_array_get_callback ( @@ -470,16 +1076,97 @@ LIBCA_API int epicsStdCall ca_array_get_callback /* */ /************************************************************************/ -/* - * ca_create_subscription () - * - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * mask R event mask - one of {DBE_VALUE, DBE_ALARM, DBE_LOG} - * pFunc R pointer to call-back function - * pArg R copy of this pointer passed to pFunc - * pEventID W event id written at specified address +/** \brief Register a state change subscription and specify a callback function + * to be invoked whenever the process variable undergoes significant state + * changes. + * + * A significant change can be a change in the process variable's + * value, alarm status, or alarm severity. In the process control function + * block database the deadband field determines the magnitude of a + * significant change for the process variable's value. Each call to this + * function consumes resources in the client library and potentially a CA + * server until one of ca_clear_channel() or ca_clear_subscription() is + * called. + * + * Subscriptions may be installed or canceled against both connected and + * disconnected channels. The specified pFunc is called once immediately + * after the subscription is installed with the process variable's current + * state if the process variable is connected. Otherwise, the specified + * pFunc is called immediately after establishing a connection (or + * reconnection) with the process variable. The specified pFunc is + * called immediately with the process variable's current state from + * within ca_create_subscription() if the client and the process variable + * share the same address space. + * + * If a subscription is installed on a channel in a disconnected state then + * the requested count will be set to the native maximum element count of + * the channel if the requested count is larger. + * + * All subscription requests such as the above are accumulated (buffered) + * and not forwarded to the IOC until one of ca_flush_io(), + * ca_pend_io(), ca_pend_event(), or ca_sg_block() are called. This + * allows several requests to be efficiently sent over the network in one + * message. + * + * If at any time after subscribing, read access to the specified process + * variable is lost, then the callback will be invoked immediately + * indicating that read access was lost via the status argument. When read + * access is restored normal event processing will resume starting always + * with at least one update indicating the current state of the channel. + * + * A better name for this function might have been ca_subscribe(). + * + * # Example + * + * See `caMonitor.c` in the example application created by `makeBaseApp.pl`. + * + * \sa ca_pend_event(), ca_flush_io() + * + * \param[in] type The type of value presented to the callback function. + * Conversion will occur if it does not match native type. + * Specify one from the set of `DBR_XXXX` in `db_access.h` + * + * \param[in] count The element count to be read from the specified channel. + * A count of zero means use the current element count from the server, + * effectively resulting in a variable size array subscription. + * + * \param[in] chanId Channel identifier. + * + * \param[in] mask + * \parblock + * A mask with bits set for each of the event trigger types requested. + * The event trigger mask must be a *bitwise or* of one or more of the + * following constants. + * + * - ::DBE_VALUE - Trigger events when the channel value exceeds the + * monitor dead band + * - ::DBE_ARCHIVE (or ::DBE_LOG) - Trigger events when the channel value + * exceeds the archival dead band + * - ::DBE_ALARM - Trigger events when the channel alarm state changes + * - ::DBE_PROPERTY - Trigger events when a channel property changes. + * + * For functions above that do not include a trigger specification, + * events will be triggered when there are significant changes in the + * channel's value or when there are changes in the channel's alarm + * state. This is the same as `DBE_VALUE | DBE_ALARM`. + * \endparblock + * + * \param[in] pFunc Pointer to a user supplied callback function to be invoked + * with each subscription update. + * + * \param[in] pArg Pointer sized variable retained and passed back + * to user callback function + * + * \param[out] pEventID This is a pointer to user supplied event id which is overwritten + * if successful. + * This event id can later be used to clear a specific event. + * This option may be omitted by passing a null pointer. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_ALLOCMEM - Unable to allocate memory + * \returns ::ECA_ADDFAIL - A local database event add failed */ LIBCA_API int epicsStdCall ca_create_subscription ( @@ -497,10 +1184,26 @@ LIBCA_API int epicsStdCall ca_create_subscription /* whenever significant changes occur to a channel */ /* */ /************************************************************************/ -/* - * ca_clear_subscription() + +/** \brief Cancel a subscription. + * + * All cancel-subscription requests such as the above are accumulated + * (buffered) and not forwarded to the server until one of ca_flush_io(), + * ca_pend_io(), ca_pend_event(), or ca_sg_block() are called. This + * allows several requests to be efficiently sent together in one message. + * + * \note This operation blocks until any user callbacks for this channel + * have run to completion. If callbacks take a lock (mutex) then it is the + * user's responsibility to ensure that this lock is not held when + * ca_clear_subscription() is called, otherwise a deadlock may ensue. + * (See also ca_clear_channel().) * - * eventID R event id + * \sa ca_create_subscription() + * + * \param[in] eventID Event id returned by ca_create_subscription(). + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADCHID - Corrupted CHID */ LIBCA_API int epicsStdCall ca_clear_subscription ( @@ -556,48 +1259,142 @@ LIBCA_API chid epicsStdCall ca_evid_to_chid ( evid id ); /* without processing. */ /************************************************************************/ -/* - * ca_pend_event() +/** \brief Flush the send buffer + * and process CA background activity for `timeout` seconds. + * + * The ca_pend_event() function will *not* return before the specified + * timeout expires and all unfinished channel access labor has been + * processed, and unlike ca_pend_io() returning from the + * function does *not* indicate anything about the status of pending IO + * requests. + * + * Both ca_pend_event() and ca_poll() return ::ECA_TIMEOUT when + * successful. This behavior probably isn\'t intuitive, but it is preserved + * to insure backwards compatibility. * - * timeout R wait for this delay in seconds + * See also "Thread Safety and Preemptive Callback to User Code" + * from the Channel Access reference manual. + * + * \sa ca_poll() + * + * \param[in] timeout The duration to block in this routine in seconds. + * A timeout of zero seconds blocks forever. + * + * \returns ::ECA_TIMEOUT - The operation timed out + * \returns ::ECA_EVDISALLOW - Function inappropriate for use within a callback handler */ LIBCA_API int epicsStdCall ca_pend_event (ca_real timeout); -#define ca_poll() ca_pend_event(1e-12) -/* - * ca_pend_io() +/** \brief Flush the send buffer + * and process any outstanding CA background activity. * - * timeout R wait for this delay in seconds but return early - * if all get requests (or search requests with null - * connection handler pointer have completed) + * See ca_pend_event(). + * + * \returns ::ECA_TIMEOUT - The operation timed out + * \returns ::ECA_EVDISALLOW - Function inappropriate for use within a callback * handler + */ +#define ca_poll() ca_pend_event(1e-12) + +/** \brief Flushes the send buffer and then blocks + * until outstanding ca_get() requests complete, + * and until channels created specifying null connection handler function pointers + * connect for the first time. + * + * - If ::ECA_NORMAL is returned then it can be safely assumed that all + * outstanding ca_get() requests have completed + * successfully and channels created specifying null connection handler + * function pointers have connected for the first time. + * - If ::ECA_TIMEOUT is returned then it must be assumed for all previous + * ca_get() requests and properly qualified first time + * channel connects have failed. + * + * If ::ECA_TIMEOUT is returned then get requests may be reissued followed by + * a subsequent call to ca_pend_io(). Specifically, the function will + * block only for outstanding ca_get() requests issued, and + * also any channels created specifying a null connection handler function + * pointer, after the last call to ca_pend_io() or ca client context + * creation whichever is later. Note that + * ca_create_channel() requests generally should + * not be reissued for the same process variable unless + * ca_clear_channel() is called first. + * + * If no ca_get() or connection state change events are + * outstanding then ca_pend_io() will flush the send buffer and return + * immediately *without processing any outstanding channel access + * background activities*. + * + * The delay specified to ca_pend_io() should take into account worst + * case network delays such as Ethernet collision exponential back off + * until retransmission delays which can be quite long on overloaded + * networks. + * + * Unlike ca_pend_event(), this routine will not + * process CA's background activities if none of the selected IO requests + * are pending. + * + * \sa ca_get(), ca_create_channel(), ca_test_io() + * + * \param[in] timeout Specifies the time out interval. + * A `timeout` interval of zero specifies forever. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_TIMEOUT - Selected IO requests didn't complete before specified timeout + * \returns ::ECA_EVDISALLOW - Function inappropriate for use within an event handler */ LIBCA_API int epicsStdCall ca_pend_io (ca_real timeout); /* calls ca_pend_io() if early is true otherwise ca_pend_event() is called */ LIBCA_API int epicsStdCall ca_pend (ca_real timeout, int early); -/* - * ca_test_io() +/** \brief Test to see if all ca_get() requests are complete + * and channels created specifying a null connection callback function pointer are connected. * - * returns TRUE when get requests (or search requests with null - * connection handler pointer) are outstanding + * It will report the status of outstanding ca_get() requests issued, and + * channels created specifying a null connection callback function pointer, + * after the last call to ca_pend_io() or CA context initialization whichever + * is later. + * + * \sa ca_pend_io() + * + * \returns ::ECA_IODONE - All IO operations completed + * \returns ::ECA_IOINPROGRESS - IO operations still in progress */ LIBCA_API int epicsStdCall ca_test_io (void); /************************************************************************/ /* Send out all outstanding messages in the send queue */ /************************************************************************/ -/* - * ca_flush_io() + +/** \brief Flush outstanding IO requests to the server. + * + * This routine might be useful to users who need to flush requests prior to + * performing client side labor in parallel with labor performed in the server. + * + * Outstanding requests are also sent whenever the buffer which holds them + * becomes full. + * + * \returns ::ECA_NORMAL - Normal successful completion */ LIBCA_API int epicsStdCall ca_flush_io (void); - -/* - * ca_signal() +/** \brief Provide the error message character string associated with the supplied channel access error code + * and the supplied error context to diagnostics. * - * errorCode R status returned from channel access function - * pCtxStr R context string included with error print out + * If the error code indicates an unsuccessful operation a stack dump is + * printed, if this capability is available on the local operating system, and + * execution is terminated. + * + * \note SEVCHK() is the recommended error handler for simple applications + * which do not wish to write code testing the status returned from each + * channel access call. + * + * If the application only wishes to print the message associated with an error + * code or test the severity of an error there are also functions provided for + * this purpose. + * + * \param[in] errorCode The status returned from a channel access function. + * \param[in] pCtxStr A null terminated character string to supply + * as error context to diagnostics. */ LIBCA_API void epicsStdCall ca_signal ( @@ -632,37 +1429,86 @@ LIBCA_API void epicsStdCall ca_signal_with_file_and_lineno LIBCA_API void epicsStdCall ca_signal_formated (long ca_status, const char *pfilenm, int lineno, const char *pFormat, ...); -/* - * ca_host_name_function() +/** \brief Return a character string which contains the name of the host + * to which a channel is currently connected. * - * channel R channel identifier + * \warning This function is _not_ thread safe. + * See ca_get_host_name() for a thread safe version. * - * !!!! this function is _not_ thread safe !!!! + * \param[in] channel Channel identifier. + * \returns The process variable server's host name. + * If the channel is disconnected the string `` is returned. */ LIBCA_API const char * epicsStdCall ca_host_name (chid channel); -/* thread safe version */ + +/** \brief Return a character string which contains the name of the host + * to which a channel is currently connected. + * + * \param[in] pChan Channel identifier. + * \param[out] pBuf Where to write the process variable server's host name. + * If the channel is disconnected the string `` is returned. + * \param[out] bufLength The size of the pBuf buffer. + * \returns The effective size of the written host name. + */ LIBCA_API unsigned epicsStdCall ca_get_host_name ( chid pChan, char *pBuf, unsigned bufLength ); -/* - * CA_ADD_FD_REGISTRATION +/** \brief Call their function with their argument whenever + * a new fd is added or removed. * - * call their function with their argument whenever - * a new fd is added or removed - * (for use with a manager of the select system call under UNIX) + * For use with a manager of the select system call under UNIX. * * if (opened) then fd was created * if (!opened) then fd was deleted - * */ typedef void CAFDHANDLER (void *parg, int fd, int opened); -/* - * ca_add_fd_registration() - * - * pHandler R pointer to function which is to be called - * when an fd is created or deleted - * pArg R argument passed to above function +/** \brief For use with the services provided by a file descriptor manager + * (IO multiplexor) such as "fdmgr.c". + * + * A file descriptor manager is often needed when two file descriptor IO + * intensive libraries such as the EPICS channel access client library and the + * X window system client library must coexist in the same UNIX process. This + * function allows an application code to be notified whenever the CA client + * library places a new file descriptor into service and whenever the CA client + * library removes a file descriptor from service. Specifying pHandler=NULL + * disables file descriptor registration (this is the default). + * + * # Example + * + * ```c + * int s; + * static struct myStruct aStruct; + * + * void fdReg ( struct myStruct *pStruct, int fd, int opened ) + * { + * if ( opened ) printf ( "fd %d was opened\n", fd ); + * else printf ( "fd %d was closed\n", fd ); + * } + * s = ca_add_fd_registration ( fdReg, & aStruct ); + * SEVCHK ( s, NULL ); + * ``` + * + * # Comments + * + * When using this function it is advisable to call it only once prior to + * calling any other CA function, or once just after creating the CA context + * (if you create the context explicitly). Use of this interface can improve + * latency slightly in applications that use non preemptive callback mode at + * the expense of some additional runtime overhead when compared to the + * alternative which is just polling ca_pend_event() periodically. It would + * probably not be appropriate to use this function with preemptive callback + * mode. Starting with R3.14 this function is implemented in a special backward + * compatibility mode. if ca_add_fd_registration() is called, a single pseudo + * UDP fd is created which CA pokes whenever something significant happens. Xt + * and others can watch this fd so that backwards compatibility is preserved, + * and so that they will not need to use preemptive callback mode but they will + * nevertheless get the lowest latency response to the arrival of CA messages. + * + * \param[in] pHandler Pointer to a user supplied C function returning null with the above arguments. + * \param[in] pArg User supplied pointer sized variable passed to the above function. + * + * \returns ::ECA_NORMAL - Normal successful completion */ LIBCA_API int epicsStdCall ca_add_fd_registration ( @@ -681,64 +1527,174 @@ LIBCA_API int epicsStdCall ca_add_fd_registration * block for IO completion within any one of the groups as needed. */ -/* - * ca_sg_create() +/** \brief Create a synchronous group and return an identifier for it. + * + * A synchronous group can be used to guarantee that a set of channel access + * requests have completed. Once a synchronous group has been created then + * channel access get and put requests may be issued within it using + * ca_sg_array_get() and ca_sg_array_put() respectively. The routines + * ca_sg_block() and ca_sg_test() can be used to block for and test for + * completion respectively. The routine ca_sg_reset() is used to discard + * knowledge of old requests which have timed out and in all likelihood will + * never be satisfied. * - * create a sync group + * Any number of asynchronous groups can have application requested operations + * outstanding within them at any given time. * - * pgid W pointer to sync group id that will be written + * # Examples + * + * ```c + * CA_SYNC_GID gid; + * status = ca_sg_create ( &gid ); + * SEVCHK ( status, Sync group create failed ); + * ``` + * + * \sa ca_sg_delete(), ca_sg_block(), ca_sg_test(), ca_sg_reset(), + * ca_sg_array_put(), ca_sg_array_get() + * + * \param[out] pgid Pointer to a user supplied CA_SYNC_GID + * that will be written. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_ALLOCMEM - Failed, unable to allocate memory */ LIBCA_API int epicsStdCall ca_sg_create (CA_SYNC_GID * pgid); -/* - * ca_sg_delete() +/** \brief Deletes a synchronous group. * - * delete a sync group + * # Examples * - * gid R sync group id + * ```c + * CA_SYNC_GID gid; + * status = ca_sg_delete ( gid ); + * SEVCHK ( status, Sync group delete failed ); + * ``` + * + * \sa ca_sg_create() + * + * \param[in] gid Identifier of the synchronous group to be deleted. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group */ LIBCA_API int epicsStdCall ca_sg_delete (const CA_SYNC_GID gid); -/* - * ca_sg_block() - * - * block for IO performed within a sync group to complete - * - * gid R sync group id - * timeout R wait for this duration prior to timing out - * and returning ECA_TIMEOUT +/** \brief Flushes the send buffer + * and then waits until outstanding requests complete + * or the specified time out expires. + * + * At this time outstanding requests include calls to ca_sg_array_get() and + * calls to ca_sg_array_put(). If ECA_TIMEOUT is returned then failure must be + * assumed for all outstanding queries. Operations can be reissued followed by + * another ca_sg_block(). This routine will only block on outstanding queries + * issued after the last call to ca_sg_block(), ca_sg_reset(), or + * ca_sg_create() whichever occurs later in time. If no queries are outstanding + * then ca_sg_block() will return immediately without processing any pending + * channel access activities. + * + * Values written into your program's variables by a channel access synchronous + * group request should not be referenced by your program until ECA_NORMAL has + * been received from ca_sg_block(). This routine will process pending channel + * access background activity while it is waiting. + * + * # Examples + * + * ```c + * CA_SYNC_GID gid; + * status = ca_sg_block(gid, 0.0); + * SEVCHK(status, Sync group block failed); + * ``` + * + * \sa ca_sg_test(), ca_sg_reset() + * + * \param[in] gid Identifier of the synchronous group. + * \param[in] timeout The duration to block in this routine in seconds. + * A timeout of zero seconds blocks forever. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_TIMEOUT - The operation timed out + * \returns ::ECA_EVDISALLOW - Function inappropriate for use within an event handler + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group */ LIBCA_API int epicsStdCall ca_sg_block (const CA_SYNC_GID gid, ca_real timeout); -/* - * ca_sg_test() +/** \brief Test to see if all requests made within a synchronous group have completed. * - * test for sync group IO operations in progress + * # Examples * - * gid R sync group id + * ```c + * CA_SYNC_GID gid; + * status = ca_sg_test ( gid ); + * ``` + * + * \param[in] gid Identifier of the synchronous group. * - * returns one of ECA_BADSYNCGRP, ECA_IOINPROGRESS, ECA_IODONE + * \returns ::ECA_IODONE - IO operations completed + * \returns ::ECA_IOINPROGRESS - Some IO operations still in progress + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group */ LIBCA_API int epicsStdCall ca_sg_test (const CA_SYNC_GID gid); -/* - * ca_sg_reset +/** \brief Reset the number of outstanding requests within the specified synchronous group to zero. * - * gid R sync group id + * So that ca_sg_test() will return ::ECA_IODONE and ca_sg_block() will not + * block unless additional subsequent requests are made. + * + * # Examples + * + * ```c + * CA_SYNC_GID gid; + * status = ca_sg_reset(gid); + * ``` + * + * \param[in] gid Identifier of the synchronous group. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group */ LIBCA_API int epicsStdCall ca_sg_reset(const CA_SYNC_GID gid); -/* - * ca_sg_array_get() + +/** \brief Read an array of values from a channel + * and increment the outstanding request count of a synchronous group. * - * initiate a get within a sync group - * (essentially a ca_array_get() with a sync group specified) + * The ca_sg_get() and ca_sg_array_get() functionality is implemented using + * ca_array_get_callback(). * - * gid R sync group id - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pValue W channel value copied to this location + * The values written into your program's variables by ca_sg_get() or + * ca_sg_array_get() should not be referenced by your program until + * ::ECA_NORMAL has been received from ca_sg_block(), or until ca_sg_test() + * returns ::ECA_IODONE. + * + * All remote operation requests such as the above are accumulated (buffered) + * and not forwarded to the server until one of ca_flush_io(), ca_pend_io(), + * ca_pend_event(), or ca_sg_block() are called. This allows several requests + * to be efficiently sent in one message. + * + * If a connection is lost and then resumed outstanding gets are not reissued. + * + * \sa ca_sg_get(), ca_pend_io(), ca_flush_io(), ca_get_callback() + * + * \param[in] gid Identifier of the synchronous group. + * + * \param[in] type External type of returned value. + * Conversion will occur if this does not match native type. + * Specify one from the set of `DBR_XXXX` in `db_access.h`. + * + * \param[in] count Element count to be read from the specified channel. + * It must match the array pointed to by `pValue`. + * + * \param[in] chan Channel identifier. + * + * \param[out] pValue Pointer to application supplied buffer + * that is to contain the value or array of values to be returned. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_GETFAIL - A local database get failed */ LIBCA_API int epicsStdCall ca_sg_array_get ( @@ -749,20 +1705,68 @@ LIBCA_API int epicsStdCall ca_sg_array_get void *pValue ); +/** \brief Read a value from a channel + * and increment the outstanding request count of a synchronous group. + * + * See ca_sg_array_get() + * + * \param[in] gid Identifier of the synchronous group. + * + * \param[in] type External type of returned value. + * Conversion will occur if this does not match native type. + * Specify one from the set of `DBR_XXXX` in `db_access.h`. + * + * \param[in] chan Channel identifier. + * + * \param[out] pValue Pointer to application supplied buffer + * that is to contain the value or array of values to be returned. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_GETFAIL - A local database get failed + */ #define ca_sg_get(gid, type, chan, pValue) \ ca_sg_array_get (gid, type, 1u, chan, pValue) -/* - * ca_sg_array_put() +/** \brief Write an array of values to a channel + * and increment the outstanding request count of a synchronous group. * - * initiate a put within a sync group - * (essentially a ca_array_put() with a sync group specified) + * The ca_sg_put() and ca_sg_array_put() functionality is implemented using + * ca_array_put_callback(). * - * gid R sync group id - * type R data type from db_access.h - * count R array element count - * chan R channel identifier - * pValue R new channel value copied from this location + * All remote operation requests such as the above are accumulated (buffered) + * and not forwarded to the server until one of ca_flush_io(), ca_pend_io(), + * ca_pend_event(), or ca_sg_block() are called. This allows several requests + * to be efficiently sent in one message. + * + * If a connection is lost and then resumed outstanding puts are not reissued. + * + * \sa ca_sg_get(), ca_flush_io() + * + * \param[in] gid Identifier of the synchronous group. + * + * \param[in] type The type of supplied value. + * Conversion will occur if it does not match the native type. + * Specify one from the set of `DBR_XXXX` in `db_access.h`. + * + * \param[in] count Element count to be written to the specified channel. + * Must match the array pointed to by `pValue`. + * + * \param[in] chan Channel identifier. + * + * \param[out] pValue A pointer to an application supplied buffer + * containing the value or array of values returned. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_PUTFAIL - A local database put failed */ LIBCA_API int epicsStdCall ca_sg_array_put ( @@ -773,6 +1777,30 @@ LIBCA_API int epicsStdCall ca_sg_array_put const void *pValue ); +/** \brief Write a value to a channel + * and increment the outstanding request count of a synchronous group. + * + * See ca_sg_array_get(). + * + * \param[in] gid Identifier of the synchronous group. + * + * \param[in] type The type of supplied value. + * Conversion will occur if it does not match the native type. + * Specify one from the set of `DBR_XXXX` in `db_access.h`. + * + * \param[in] chan Channel identifier. + * + * \param[out] pValue A pointer to an application supplied buffer + * containing the value or array of values returned. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_BADSYNCGRP - Invalid synchronous group + * \returns ::ECA_BADCHID - Corrupted CHID + * \returns ::ECA_BADTYPE - Invalid DBR_XXXX type + * \returns ::ECA_BADCOUNT - Requested count larger than native element count + * \returns ::ECA_STRTOBIG - Unusually large string supplied + * \returns ::ECA_PUTFAIL - A local database put failed + */ #define ca_sg_put(gid, type, chan, pValue) \ ca_sg_array_put (gid, type, 1u, chan, pValue) @@ -785,9 +1813,15 @@ ca_sg_array_put (gid, type, 1u, chan, pValue) */ LIBCA_API int epicsStdCall ca_sg_stat (CA_SYNC_GID gid); +/** \brief Dumps the specified dbr data type to standard out. + * + * \param[in] type The data type + * (from the `DBR_XXXX` set described in `db_access.h`). + * \param[in] count The array element count + * \param[in] pbuffer A pointer to data of the specified count and number. + */ LIBCA_API void epicsStdCall ca_dump_dbr (chtype type, unsigned count, const void * pbuffer); - /* * ca_v42_ok() * @@ -814,12 +1848,32 @@ LIBCA_API const char * epicsStdCall ca_version (void); * text output goes * * use two ifdef's for trad C compatibility - * - * ca_printf_func R pointer to new function called when - * CA prints an error message */ #ifndef CA_DONT_INCLUDE_STDARGH typedef int caPrintfFunc (const char *pformat, va_list args); + +/** \brief Replace the default handler for formatted diagnostic message output. + * + * The default handler uses fprintf to send messages to 'stderr'. + * + * \param[in] ca_printf_func A pointer to a user supplied callback handler + * to be invoked when CA prints diagnostic messages. + * Installing a null pointer will cause the default callback handler to be reinstalled. + * + * # Examples + * + * ```c + * int my_printf ( char *pformat, va_list args ) { + * int status; + * status = vfprintf( stderr, pformat, args); + * return status; + * } + * status = ca_replace_printf_handler ( my_printf ); + * SEVCHK ( status, "failed to install my printf handler" ); + * ``` + * + * \returns ::ECA_NORMAL - Normal successful completion + */ LIBCA_API int epicsStdCall ca_replace_printf_handler ( caPrintfFunc *ca_printf_func ); @@ -836,16 +1890,57 @@ LIBCA_API unsigned epicsStdCall ca_search_attempts (chid chan); LIBCA_API double epicsStdCall ca_beacon_period (chid chan); LIBCA_API double epicsStdCall ca_receive_watchdog_delay (chid chan); -/* - * used when an auxiliary thread needs to join a CA client context started +/** \brief Returns a pointer to the current thread's CA context. + * + * If none then null is returned. + * + * Used when an auxiliary thread needs to join a CA client context started * by another thread + * + * \sa ca_attach_context(), ca_detach_context(), ca_context_create(), ca_context_destroy() */ LIBCA_API struct ca_client_context * epicsStdCall ca_current_context (); -LIBCA_API int epicsStdCall ca_attach_context ( struct ca_client_context * context ); +/** \brief The calling thread becomes a member of the specified CA context. + * + * If ca_disable_preemptive_callback is specified when ca_context_create() is + * called (or if ca_task_initialize() is called) then additional threads are + * *not* allowed to join the CA context because allowing other threads to join + * implies that CA callbacks will be called preemptively from more than one + * thread. + * + * \sa ca_current_context(), ca_detach_context(), ca_context_create(), ca_context_destroy() + * + * \param[in] context A pointer to the CA context to join with. + * + * \returns ::ECA_NORMAL - Normal successful completion + * \returns ::ECA_NOTTHREADED - Context is not preemptive so cannot be joined + * \returns ::ECA_ISATTACHED - Thread already attached to a CA context + */ +LIBCA_API int epicsStdCall ca_attach_context ( struct ca_client_context * context ); +/** \brief Prints information about the client context. + * + * Including, at higher interest levels, status for each channel. Lacking a CA + * context pointer, ca_client_status() prints information about the calling + * threads CA context. + * + * \param[in] level The interest level. + * Increasing level produces increasing detail. + */ LIBCA_API int epicsStdCall ca_client_status ( unsigned level ); -LIBCA_API int epicsStdCall ca_context_status ( struct ca_client_context *, unsigned level ); + +/** \brief Prints information about the client context. + * + * Including, at higher interest levels, status for each channel. Lacking a CA + * context pointer, ca_client_status() prints information about the calling + * threads CA context. + * + * \param[in] context A pointer to the CA context to examine. + * \param[in] level The interest level. + * Increasing level produces increasing detail. + */ +LIBCA_API int epicsStdCall ca_context_status ( struct ca_client_context *context, unsigned level ); /* * deprecated @@ -857,15 +1952,39 @@ ca_build_and_connect(NAME, XXXXX, ZZZZZZ, CHIDPTR, YYYYY, 0, 0) LIBCA_API int epicsStdCall ca_build_and_connect ( const char *pChanName, chtype, unsigned long, chid * pChanID, void *, caCh * pFunc, void * pArg ); + +/** \brief Search for a channel over Channel Access. + * + * \deprecated Use ca_create_channel() instead. + */ #define ca_search(pChanName, pChanID)\ ca_search_and_connect (pChanName, pChanID, 0, 0) + +/** \brief Search and connect to a channel over Channel Access. + * + * \deprecated Use ca_create_channel() instead. + */ LIBCA_API int epicsStdCall ca_search_and_connect ( const char * pChanName, chid * pChanID, caCh *pFunc, void * pArg ); + LIBCA_API int epicsStdCall ca_channel_status (epicsThreadId tid); + +/** \brief Cancel a subscription. + * + * \deprecated Use ca_clear_subscription() instead. + */ LIBCA_API int epicsStdCall ca_clear_event ( evid eventID ); + +/** \brief Register a state change subscription and specify a callback function + * to be invoked whenever the process variable undergoes significant state + * changes. + * + * \deprecated Use ca_create_subscription() instead. + */ #define ca_add_event(type,chan,pFunc,pArg,pEventID)\ ca_add_array_event(type,1u,chan,pFunc,pArg,0.0,0.0,0.0,pEventID) + #define ca_add_delta_event(TYPE,CHID,ENTRY,ARG,DELTA,EVID)\ ca_add_array_event(TYPE,1,CHID,ENTRY,ARG,DELTA,DELTA,0.0,EVID) #define ca_add_general_event(TYPE,CHID,ENTRY,ARG,P_DELTA,N_DELTA,TO,EVID)\ diff --git a/modules/ca/src/client/caerr.h b/modules/ca/src/client/caerr.h index bc6f654d15..95df2cebc3 100644 --- a/modules/ca/src/client/caerr.h +++ b/modules/ca/src/client/caerr.h @@ -19,6 +19,10 @@ * */ +/** \file caerr.h + * + * \brief Channel access error definitions. + */ #ifndef INC_caerr_H #define INC_caerr_H @@ -75,72 +79,139 @@ * servers on earlier releases that communicate with current clients * might still generate exceptions with these error constants */ + +/// Normal successful completion #define ECA_NORMAL DEFMSG(CA_K_SUCCESS, 0) /* success */ +/// Maximum simultaneous IOC connections exceeded #define ECA_MAXIOC DEFMSG(CA_K_ERROR, 1) /* defunct */ +/// Unknown internet host #define ECA_UKNHOST DEFMSG(CA_K_ERROR, 2) /* defunct */ +/// Unknown internet service #define ECA_UKNSERV DEFMSG(CA_K_ERROR, 3) /* defunct */ +/// Unable to allocate a new socket #define ECA_SOCK DEFMSG(CA_K_ERROR, 4) /* defunct */ +/// Unable to connect to internet host or service #define ECA_CONN DEFMSG(CA_K_WARNING, 5) /* defunct */ +/// Unable to allocate additional dynamic memory #define ECA_ALLOCMEM DEFMSG(CA_K_WARNING, 6) +/// Unknown IO channel #define ECA_UKNCHAN DEFMSG(CA_K_WARNING, 7) /* defunct */ +/// ECA_UKNFIELD - Record field specified inappropriate for channel specified #define ECA_UKNFIELD DEFMSG(CA_K_WARNING, 8) /* defunct */ +/// The requested data transfer is greater than available memory or EPICS_CA_MAX_ARRAY_BYTES #define ECA_TOLARGE DEFMSG(CA_K_WARNING, 9) +/// User specified timeout on IO operation expired #define ECA_TIMEOUT DEFMSG(CA_K_WARNING, 10) +/// Sorry, that feature is planned but not supported at this time #define ECA_NOSUPPORT DEFMSG(CA_K_WARNING, 11) /* defunct */ +/// The supplied string is unusually large #define ECA_STRTOBIG DEFMSG(CA_K_WARNING, 12) /* defunct */ +/// The request was ignored because the specified channel is disconnected #define ECA_DISCONNCHID DEFMSG(CA_K_ERROR, 13) /* defunct */ +/// The data type specifed is invalid #define ECA_BADTYPE DEFMSG(CA_K_ERROR, 14) +/// Remote Channel not found #define ECA_CHIDNOTFND DEFMSG(CA_K_INFO, 15) /* defunct */ +/// Unable to locate all user specified channels #define ECA_CHIDRETRY DEFMSG(CA_K_INFO, 16) /* defunct */ +/// Channel Access Internal Failure #define ECA_INTERNAL DEFMSG(CA_K_FATAL, 17) +/// The requested local DB operation failed #define ECA_DBLCLFAIL DEFMSG(CA_K_WARNING, 18) /* defunct */ +/// Channel read request failed #define ECA_GETFAIL DEFMSG(CA_K_WARNING, 19) +/// Channel write request failed #define ECA_PUTFAIL DEFMSG(CA_K_WARNING, 20) +/// Channel subscription request failed #define ECA_ADDFAIL DEFMSG(CA_K_WARNING, 21) /* defunct */ +/// Invalid element count requested #define ECA_BADCOUNT DEFMSG(CA_K_WARNING, 22) +/// Invalid string #define ECA_BADSTR DEFMSG(CA_K_ERROR, 23) +/// Virtual circuit disconnect #define ECA_DISCONN DEFMSG(CA_K_WARNING, 24) +/// Identical process variable names on multiple servers #define ECA_DBLCHNL DEFMSG(CA_K_WARNING, 25) +/// Request inappropriate within subscription (monitor) update callback #define ECA_EVDISALLOW DEFMSG(CA_K_ERROR, 26) +/// Database value get for that channel failed during channel search #define ECA_BUILDGET DEFMSG(CA_K_WARNING, 27) /* defunct */ +/// Unable to initialize without the vxWorks VX_FP_TASK task option set #define ECA_NEEDSFP DEFMSG(CA_K_WARNING, 28) /* defunct */ +/// Event queue overflow has prevented first pass event after event add #define ECA_OVEVFAIL DEFMSG(CA_K_WARNING, 29) /* defunct */ +/// Bad event subscription (monitor) identifier #define ECA_BADMONID DEFMSG(CA_K_ERROR, 30) +/// Remote channel has new network address #define ECA_NEWADDR DEFMSG(CA_K_WARNING, 31) /* defunct */ +/// New or resumed network connection #define ECA_NEWCONN DEFMSG(CA_K_INFO, 32) /* defunct */ +/// Specified task isnt a member of a CA context #define ECA_NOCACTX DEFMSG(CA_K_WARNING, 33) /* defunct */ +/// Attempt to use defunct CA feature failed #define ECA_DEFUNCT DEFMSG(CA_K_FATAL, 34) /* defunct */ +/// The supplied string is empty #define ECA_EMPTYSTR DEFMSG(CA_K_WARNING, 35) /* defunct */ +/// Unable to spawn the CA repeater thread- auto reconnect will fail #define ECA_NOREPEATER DEFMSG(CA_K_WARNING, 36) /* defunct */ +/// No channel id match for search reply- search reply ignored #define ECA_NOCHANMSG DEFMSG(CA_K_WARNING, 37) /* defunct */ +/// Reseting dead connection- will try to reconnect #define ECA_DLCKREST DEFMSG(CA_K_WARNING, 38) /* defunct */ +/// Server (IOC) has fallen behind or is not responding- still waiting #define ECA_SERVBEHIND DEFMSG(CA_K_WARNING, 39) /* defunct */ +/// No internet interface with broadcast available #define ECA_NOCAST DEFMSG(CA_K_WARNING, 40) /* defunct */ +/// Invalid event selection mask #define ECA_BADMASK DEFMSG(CA_K_ERROR, 41) +/// IO operations have completed #define ECA_IODONE DEFMSG(CA_K_INFO, 42) +/// IO operations are in progress #define ECA_IOINPROGRESS DEFMSG(CA_K_INFO, 43) +/// Invalid synchronous group identifier #define ECA_BADSYNCGRP DEFMSG(CA_K_ERROR, 44) +/// Put callback timed out #define ECA_PUTCBINPROG DEFMSG(CA_K_ERROR, 45) +/// Read access denied #define ECA_NORDACCESS DEFMSG(CA_K_WARNING, 46) +/// Write access denied #define ECA_NOWTACCESS DEFMSG(CA_K_WARNING, 47) +/// Requested feature is no longer supported #define ECA_ANACHRONISM DEFMSG(CA_K_ERROR, 48) +/// Empty PV search address list #define ECA_NOSEARCHADDR DEFMSG(CA_K_WARNING, 49) +/// No reasonable data conversion between client and server types #define ECA_NOCONVERT DEFMSG(CA_K_WARNING, 50) +/// Invalid channel identifier #define ECA_BADCHID DEFMSG(CA_K_ERROR, 51) +/// Invalid function pointer #define ECA_BADFUNCPTR DEFMSG(CA_K_ERROR, 52) +/// Thread is already attached to a client context #define ECA_ISATTACHED DEFMSG(CA_K_WARNING, 53) +/// Not supported by attached service #define ECA_UNAVAILINSERV DEFMSG(CA_K_WARNING, 54) +/// User destroyed channel #define ECA_CHANDESTROY DEFMSG(CA_K_WARNING, 55) +/// Invalid channel priority #define ECA_BADPRIORITY DEFMSG(CA_K_ERROR, 56) +/// Preemptive callback not enabled - additional threads may not join context #define ECA_NOTTHREADED DEFMSG(CA_K_ERROR, 57) +/// Client's protocol revision does not support transfers exceeding 16k bytes #define ECA_16KARRAYCLIENT DEFMSG(CA_K_WARNING, 58) +/// Virtual circuit connection sequence aborted #define ECA_CONNSEQTMO DEFMSG(CA_K_WARNING, 59) +/// Virtual circuit unresponsive #define ECA_UNRESPTMO DEFMSG(CA_K_WARNING, 60) #ifdef __cplusplus extern "C" { #endif +/** \brief Return a message character string corresponding to a user specified CA status code. + * + * \param[in] ca_status A CA status code. + * \returns The corresponding error message string. + */ LIBCA_API const char * epicsStdCall ca_message(long ca_status); LIBCA_API extern const char * ca_message_text []; diff --git a/modules/ca/src/client/caeventmask.h b/modules/ca/src/client/caeventmask.h index 949f2743b4..adf298ea9d 100644 --- a/modules/ca/src/client/caeventmask.h +++ b/modules/ca/src/client/caeventmask.h @@ -8,37 +8,43 @@ * in file LICENSE that is included with this distribution. \*************************************************************************/ +/** \file caeventmask.h + * + * \brief Event selections + */ + #ifndef INCLcaeventmaskh #define INCLcaeventmaskh /* - event selections (If any more than 8 of these are needed then update the select field in the event_block struct in db_event.c from unsigned char to unsigned short) + */ - - DBE_VALUE - Trigger an event when a significant change in the channel's value - occurs. Relies on the monitor deadband field under DCT. - - DBE_ARCHIVE (DBE_LOG) - Trigger an event when an archive significant change in the channel's - value occurs. Relies on the archiver monitor deadband field under DCT. - - DBE_ALARM - Trigger an event when the alarm state changes - - DBE_PROPERTY - Trigger an event when a property change (control limit, graphical - limit, status string, enum string ...) occurs. - -*/ - +/** \brief Trigger an event when a significant change in the channel's value occurs. + * + * Relies on the monitor deadband field under DCT. + */ #define DBE_VALUE (1<<0) + +/** \brief Trigger an event when an archive significant change in the channel's value occurs. + * + * Relies on the archiver monitor deadband field under DCT. + */ #define DBE_ARCHIVE (1<<1) + +/** \brief Same as ::DBE_ARCHIVE. + */ #define DBE_LOG DBE_ARCHIVE + +/** \brief Trigger an event when the alarm state changes. + */ #define DBE_ALARM (1<<2) + +/** \brief Trigger an event when a property change occurs. + * (control limit, graphical limit, status string, enum string ...) + */ #define DBE_PROPERTY (1<<3) #endif diff --git a/modules/ca/src/client/db_access.h b/modules/ca/src/client/db_access.h index cca17a512b..0fd9c56915 100644 --- a/modules/ca/src/client/db_access.h +++ b/modules/ca/src/client/db_access.h @@ -516,13 +516,40 @@ struct dbr_ctrl_double{ dbr_double_t value; /* current value */ }; +/** \brief Returns the size in bytes for a `DBR_XXXX` type with `COUNT` elements. + * + * If the DBR type is a structure then the value field is the last field in the + * structure. If `COUNT` is greater than one then `COUNT-1` elements are + * appended to the end of the structure so that they can be addressed as an + * array through a pointer to the value field. + * + * \sa dbr_size, dbr_value_size + * + * \param[in] TYPE The data type. + * \param[in] COUNT The element count. + * \returns The size in bytes of the specified type + * with the specified number of elements. + */ #define dbr_size_n(TYPE,COUNT)\ ((unsigned)((COUNT)<0?dbr_size[TYPE]:dbr_size[TYPE]+((COUNT)-1)*dbr_value_size[TYPE])) -/* size for each type - array indexed by the DBR_ type code */ +/** \brief Size in bytes for each `DBR_XXXX` type. + * + * Array indexed by the `DBR_XXXX` type code. + * + * \sa dbr_size_n() + */ LIBCA_API extern const unsigned short dbr_size[]; -/* size for each type's value - array indexed by the DBR_ type code */ +/** \brief Size in bytes for each type's value. + * + * Array indexed by the `DBR_XXXX` type code. + * + * If the type is a structure the size of the value field is returned otherwise + * the size of the type is returned. + * + * \sa dbr_size_n() + */ LIBCA_API extern const unsigned short dbr_value_size[]; #ifndef db_accessHFORdb_accessC @@ -685,6 +712,14 @@ union db_access_val{ break; \ } +/** \brief Returns a constant null terminated string + * corresponding to the specified dbr type. + * + * \param[in] type The data type code. + * A member of the set of `DBR_XXXX` in `db_access.h`. + * + * \returns The const string corresponding to the `DBR_XXXX` type. + */ #define dbr_type_to_text(type) \ ( ((type) >= 0 && (type) < dbr_text_dim) ? \ dbr_text[(type)] : dbr_text_invalid ) From 6fc6304f19648fe5b45f6a7ec7fec02714e10a2c Mon Sep 17 00:00:00 2001 From: Minijackson Date: Tue, 28 Jan 2025 09:04:36 +0100 Subject: [PATCH 022/446] docs(cadef): group CA operations together --- modules/ca/src/client/cadef.h | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/modules/ca/src/client/cadef.h b/modules/ca/src/client/cadef.h index 32de6a8fe1..e7ab45cbe8 100644 --- a/modules/ca/src/client/cadef.h +++ b/modules/ca/src/client/cadef.h @@ -141,6 +141,11 @@ typedef unsigned CA_SYNC_GID; * External OP codes for CA operations */ +/** + * \name Channel Access operations + * @{ + */ + /** \brief GET Channel Access operation. */ #define CA_OP_GET 0 /** \brief PUT Channel Access operation. */ @@ -172,6 +177,8 @@ typedef unsigned CA_SYNC_GID; */ #define CA_OP_SEARCH 2 +/** @} */ + /** \brief Provides efficient test and display of channel access errors. * * SEVCHK() is a macro envelope around ca_signal() which only calls From cad535a9569c412e4f89338cfd90e996272a6be8 Mon Sep 17 00:00:00 2001 From: Minijackson Date: Fri, 24 Jan 2025 10:28:10 +0100 Subject: [PATCH 023/446] docs: include msi cli reference, use Sphinx cli features This enables referring to e.g. {option}`msi -o` in the documentation, and it will link to the correct location --- documentation/index.rst | 6 + modules/database/src/ioc/dbtemplate/msi.md | 184 +++++++++++---------- 2 files changed, 105 insertions(+), 85 deletions(-) diff --git a/documentation/index.rst b/documentation/index.rst index 0bed60cc3a..d71beedd95 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -20,6 +20,12 @@ EPICS Base Documentation ComponentReference +.. toctree:: + :titlesonly: + :caption: Command Line Reference + + msi + .. toctree:: :maxdepth: 1 :caption: C/C++ Headers diff --git a/modules/database/src/ioc/dbtemplate/msi.md b/modules/database/src/ioc/dbtemplate/msi.md index bbe5273ef0..649683f8e0 100644 --- a/modules/database/src/ioc/dbtemplate/msi.md +++ b/modules/database/src/ioc/dbtemplate/msi.md @@ -1,5 +1,8 @@ # msi: Macro Substitution and Include Tool +``` {program} msi +``` + (msitool)= ## Introduction @@ -18,7 +21,9 @@ substitution files accepted by the EPICS IOC's dbLoadTemplate command. ## Command Syntax -`msi -V -g -o outfile -I dir -M subs -S subfile template` +``` bash +msi -V -g -o outfile -I dir -M subs -S subfile template +``` All parameters are optional. The -o, -I, -M, and -S switches may be separated from their associated value string by spaces if desired. @@ -26,80 +31,89 @@ Output will be written to stdout unless the -o option is given. Switches have the following meanings: -- **-V** - - Verbose warnings; if this parameter is specified then any undefined - macro discovered in the template file which does not have an - associated default value is considered an error. An error message is - generated, and when msi terminates it will do so with an exit status - of 2. -- **-g** - - When this flag is given all macros defined in a substitution file - will have global scope and thus their values will persist until a - new value is given for this macro. This flag is provided for - backwards compatibility as this was the behavior of previous - versions of msi, but it does not follow common scoping rules and is - discouraged. -- **-o _file_** - - Output will be written to the specifed file rather than to the - standard output. -- **-I _dir_** - - This parameter, which may be repeated or contain a colon-separated - (or semi-colon separated on Windows) list of directory paths, - specifies a search path for include commands. For example: - - msi -I /home/mrk/examples:. -I.. template - - specifies that all named files should be searched for in the following locations, - in the order given: - - 1. /home/mrk/examples - 2. . (the current directory) - 3. .. (the parent of the current directory) - - Note that relative path searching is handled as - - $ cat foo.substitutions - file rel/path/bar.template { - # contents - } - $ msi -I . -I /some/path foo.substitutions - - which will try to find `bar.template` at the path `./rel/path/` followed by - `/some/path/rel/path`. - - -- **-M _substitutions_** +::: {option} -V +Verbose warnings; if this parameter is specified then any undefined +macro discovered in the template file which does not have an +associated default value is considered an error. An error message is +generated, and when msi terminates it will do so with an exit status +of 2. +::: + +::: {option} -g +When this flag is given all macros defined in a substitution file +will have global scope and thus their values will persist until a +new value is given for this macro. This flag is provided for +backwards compatibility as this was the behavior of previous +versions of msi, but it does not follow common scoping rules and is +discouraged. +::: + +::: {option} -o +Output will be written to the specifed \ rather than to the +standard output. +::: + +::: {option} -I +This parameter, which may be repeated or contain a colon-separated +(or semi-colon separated on Windows) list of directory paths, +specifies a search path for include commands. For example: + +``` bash +msi -I /home/mrk/examples:. -I.. template +``` + +specifies that all named files should be searched for in the following locations, +in the order given: + +1. `/home/mrk/examples` +2. `.` (the current directory) +3. `..` (the parent of the current directory) + +Note that relative path searching is handled as + + $ cat foo.substitutions + file rel/path/bar.template { + # contents + } + $ msi -I . -I /some/path foo.substitutions - This parameter specifies macro values for the template instance. - Multiple macro values can be specified in one substitution - parameter, or in multiple -M parameters. For example: +which will try to find `bar.template` at the path `./rel/path/` followed by +`/some/path/rel/path`. +::: - msi -M "a=aval,b=bval" -Mc=cval template +::: {option} -M +This parameter specifies macro values for the template instance. +Multiple macro values can be specified in one substitution +parameter, or in multiple -M parameters. For example: - specifies that in the template file each occurrence of: +``` bash +msi -M "a=aval,b=bval" -Mc=cval template +``` - - `$(a)` or `${a}` is replaced by _aval_ - - `$(b)` or `${b}` is replaced by _bval_ - - `$(c)` or `${c}` is replaced by _cval_ +specifies that in the template file each occurrence of: -- **-S _subfile_** +- `$(a)` or `${a}` is replaced by _aval_ +- `$(b)` or `${b}` is replaced by _bval_ +- `$(c)` or `${c}` is replaced by _cval_ +::: - The substitution file. See below for format. -- **_template_** +::: {option} -S +The substitution file. See below for format. +::: - The input file. If no file is specified then input is taken from - stdin, i.e. msi can be used as a filter. See below for a description - of commands that can be embedded in the template file. +::: {option}