Instructions for iocAdmin users Last Updated 12/05/2012 -------------------------------- The iocAdmin package contains databases and libraries to add ioc administration PVs (including STARTTOD (ioc start time), TOD (time-of-day that updates every second), SYSRESET (ioc restart command), access security PVs, etc) to an ioc application. This package includes general time records and IOC stats (devIocStats) - see README_devIocStats for detail. iocAdmin also provides access.db, a database template defining records for device attributes that are common across many IOC applications. See I-5 below for more detail. I - Adding the iocAdmin package to your IOC application: ------------------------------------------------------- (1) Add IOCADMIN to configure/RELEASE and clean/rebuild configure: IOCADMIN=/afs/slac/g/lcls/epics/modules/iocAdmin/iocAdmin-R (2) Link the iocAdmin libraries into your app by adding to App/src/Makefile: _LIBS += devIocStats (3) Add the following .dbd files to App/src/Makefile or to App/src/Include.dbd: _DBD += iocAdmin.dbd (4) Install the iocAdmin database and create iocRelease.db by adding to App/Db/Makefile: DB_INSTALLS += $(IOCADMIN)/db/iocAdminVxWorks.db (VxWorks IOCs) DB_INSTALLS += $(IOCADMIN)/db/iocAdminRTEMS.db (RTEMS IOCs) DB_INSTALLS += $(IOCADMIN)/db/iocAdminSoft.db (soft IOCs) DB_INSTALLS += $(IOCADMIN)/db/access.db (if required by next step) DB_INSTALLS += $(IOCADMIN)/db/iocAdminScanMon.db (optional - ONLY if SCAN monitoring is required) IOCRELEASE_DB += iocRelease.db NOTE: The iocRelease database assumes that each module used by the application has a line in configure/RELEASE as follows: _MODULE_VERION = - It also assumes that modules are not specified in any file included by configure/RELEASE. (5) For each device, or device attribute, used by higher-level software (ie, feedback), an ACCESS mode and FBCK state soft mbbo records are required and used by the higher-level software to determine proper configuration and display. Both records must be saved and restored across IOC restart. Currently, devices requiring these records include beamline devices (ie, BPMs, bunch length monitors, toroids, faraday cups, PMTs, wire-scanners, collimators, power meters, gun RF, klystrons, cavities, and magnets). These records may be required per device channel or device attribute instead of per device, depending on the needs of the higher-level software. The ACCESS record has state names of Online, Maintenance, Checkout, and Offline and is set by operations. It is not meant to be used by Channel Access Security or for the actual device state which is set using a different record name by the IOC itself. See iocAdmin/Db/access.doc for requirements and discussion of the ACCESS record. The FBCK record has state names of Off, On, and Unavailable. "Unavailable" indicates the device is not used by any feedback loop and this value is set by operations. "On" is set when ANY feedback loop is using the device, and "Off" is set when ALL feedback loops are NOT using the device. "Off" requires feedback loops to know about each other or some sort of feedback loop management. To create this record, make sure access.db template file is installed (see the previous the step) and include access.db in your device substitutions file for every device as follows: file access.db { pattern { DEV } { } } See iocAdmin/Db/access.doc for requirements and discussion. II - Adding iocAdmin to your IOC startup file: ----------------------------------------------- (1) Add the following environment variables to st.cmd: All IOCs (must be less than 40 characters): epicsEnvSet("ENGINEER","") epicsEnvSet("LOCATION","") Soft IOCs only (can be longer than 40 characters): epicsEnvSet("STARTUP","/usr/local/lcls/epics/iocCommon/") epicsEnvSet("ST_CMD","startup.cmd") (2) Add iocAdmin database to st.cmd (before iocInit): VxWorks IOCs only: dbLoadRecords("db/iocAdminVxWorks.db", "IOC=") RTEMS IOCs only: dbLoadRecords("db/iocAdminRTEMS.db", "IOC=") Soft IOCs only: dbLoadRecords("db/iocAdminSoft.db", "IOC=") (3) Add iocRelease database to st.cmd (before iocInit): dbLoadRecords("db/iocRelease.db", "IOC=") (4) If SCAN monitoring is required (most IOCs do not require these records - discuss with Kukhee Kim first): dbLoadRecords("db/iocAdminScanMon.db", "IOC=") III - Adding iocAdmin to CA Clients: ------------------------------------ (1) Channel Watcher: (1a) Alarm Limits - Macros are not provided for IOC health alarm limits in iocAdmin.db. Alarm limits must be added to the channel watcher configuration file instead. The IOC channel access security state should also be added. Use this template to create the .cwConfig file: RTEMS and VxWorks IOCs only: $(IOCADMIN)/restore/iocAdmin.cwConfig Soft IOCs only: $(IOCADMIN)/restore/iocAdminSoft.cwConfig (1b) IOC Startup Counter - :START_CNT keeps a count of the number of times the ioc has started up. In order for it to work properly, the record must be saved and restored across ioc startup. It is included in the above templates. (1c) Device-Specific Records - For every device instantiating the access.db database, add these lines to the channel watcher configuration file: ACCESS /LOG FBCK /LOG (2) EDM: (2a) For a new version of iocAdmin, copy or merge required display files from $(IOCADMIN)/display to $EDM/misc. (2b) IOC Display - Choose the correct machine area for the IOC and add the ioc to the proper network EDM displays: $EDM/lcls/ntwk__main.edl $EDM/lcls/ntwk__iocstatus.edl Use the proper related display depending on the type of IOC: ioc_rtems_acsw - RTEMS IOC using an AC switch to power cycle. ioc_rtems_crat - RTEMS IOC using the crate interface to power cycle. ioc_rtems_none - RTEMS IOC without a crate interface or AC switch. ioc_rtems_nosupport - RTEMS IOC with a unsupported crate interface ioc_rtems_camac_4crat, ioc_rtems_camac_5crat, ioc_rtems_camac_6crat, or ioc_rtems_camac_crat - RTEMS IOC with camac crate(s). ioc_soft - Soft IOC Set the "ioc" macro to the ioc database name. (2c) Device-Specific Display - For each device instantiating the access.db database, add choice or menu buttons for ACCESS and FBCK on the device single-unit diagnostic display and/or subsystem display showing the device status. (3) Channel Archiver - for each IOC, consider adding some or all of the following records to Channel Archiver: All IOCs: :CA_CLNT_CNT :CA_CONN_CNT :FD_FREE :START_CNT RTEMS and VxWorks IOCs only: :MEM_FREE :MEM_BLK_FREE :SYS_MBUF_FREE :RAM_WS_FREE :IOC_CPU_LOAD :IFI_ERR_CNT :IFO_ERR_CNT :CLUST_1_0_2 :CLUST_1_1_2 (4) Alarm Handler - add logic for the IOC heartbeat (that creates the HEARTBEATSUM record) to the ALH soft IOC (via email to Judy Rock). Add the IOC to the "NETWORK" subgroup for all applicable machine areas with the following PVs and include them in :STATSUMY on the ALH soft IOC: All IOCs: :CA_CLNT_CNT :CA_CONN_CNT :SUSP_TASK_CNT :FD_FREE :IOC_CPU_LOAD :HEARTBEATSUM (from the ALH soft IOC) :GTIM_ERR_CNT RTEMS and VxWorks IOCs only: :MEM_FREE :MEM_BLK_FREE :RAM_WS_FREE