EPICS Record Support Marty Kraimer APS 1999Ph 514

EPICS Record Support Marty Kraimer APS 1999/Ph 514: Record Support 1

EPICS u Record Support u u u Implementation steps u u Implements a Record Type Plugs into database common environment Prepare a Database Definition (. dbd) file Create a C source file which implements semantics Start with existing support!!! Documentation u u u App Dev Guide - Chapters 3 and 8 make. Base. App example - xxx. Record base/src/rec 1999/Ph 514: Record Support 2

Database Definition File - dbd u EPICS Syntax recordtype(<recordtype>) { include “db. Common. dbd” field(<fieldname>, <fieldtype>) { <fieldattributes> }. . . } u Example recordtype(example) { include “db. Common. dbd” field(PREC, DBF_DOUBLE) { prompt(“Display Precision”) prompt. Group(GUI_DISPLAY) } field(VAL, DBF_DOUBLE) } 1999/Ph 514: Record Support 3

dbd - cont. u u <recordtype> Should be alphanumeric starting with letter <fieldname> u u EPICS Should be alphanumeric starting with letter For now length is limited to four characters In dbd file this should be upper case. It is converted to lower case in include file. <fieldtype> DBF_STRING DBF_CHAR DBF_UCHAR DBF_SHORT DBF_USHORT DBF_LONG DBF_ULONG DBF_FLOAT DBF_DOUBLE DBF_ENUM DBF_MENU DBF_DEVICE DBF_INLINK DBF_OUTLINK DBF_FWDLINK DBF_NOACCESS 1999/Ph 514: Record Support 4

dbd - cont u EPICS <fieldattributes> u u u asl : access security level u ASL 1 - Fields seldom modified - default u ASL 0 - Fields meant to be modified initial : initial value prompt : string for Database Configuration promptgroup : Should DCT allow field to be configured? Many groups but no DCT distinguishes between groups. special: Special handling on put u Several values u SPC_MOD, SPC_DBADDR, SPC_NOMOD pp : process passive record on put? interest : interest level used by dbpr base : DECIMAL (default) or HEX size : For DBF_STRING extra : For DBF_NOACCESS menu : For DBF_MENU. 1999/Ph 514: Record Support 5

String Field u DBF_STRING fields u u EPICS Fixed length null terminated strings Channel access support max of 40 characters Arrays of character strings are possible Example field(VAL, DBF_STRING) { size(40) prompt(“value”) promptgroup(GUI_DISPLAY) } 1999/Ph 514: Record Support 6

Numeric Fields u DBF_CHAR, … , DBF_DOUBLE u u EPICS Standard C datatypes Note that DBF_CHAR, DBF_UCHAR problem All attributes except size, extra, menu meaningful Arrays u dbd file must define special(SPC_DBADDR) Record support must implement cvt_dbaddr, get_array_info, put_array_info u No support by Database Configuration Tools. u 1999/Ph 514: Record Support 7

Enumerated Fields u EPICS DBF_ENUM u Record Support provides choices and index See bi. Record, mbbi. Record, etc Actual field type is unsigned short u Record support MUST implement u u u get_enum_str put_enum_str get_enum_strs 1999/Ph 514: Record Support 8

Menu Fields u EPICS DBF_MENU menu(<menuname>) { choice(<choicename>, ”<choicevalue>“) … } … recordtype(<recordtype>) { field(<fieldname>, DBF_MENU) { menu(<menuname>) } u Example menu(menu. Yes. No) { choice(menu. Yes. No, ”NO”) choice(menu. Yes. No, ”YES”) } … field(PINI, DBF_MENU) { … menu(menu. Yes. No) } 1999/Ph 514: Record Support 9

Device Field u u EPICS DBF_DEVICE u Database Common Field - DTYP u u Related to device definitions Has associated INP or OUT field u Device Support must be provided Example device(ai, CONSTANT, dev. Ai. Soft, ”Soft Channel”) device(ai, CONSTANT, dev. Ai. Soft. Raw, ”Raw Soft Channel”) 1999/Ph 514: Record Support 10

link Fields u DBF_INLINK, DBF_OUTLINK u Not INP or OUT u u u Constant link - Just initialization PV_LINK becomes DB_LINK or CA_LINK INP or OUT and Device Support u u EPICS device definitions determine choices Associated with choice is bus type Gory details in link. h DBF_FWDLINK u u references another record which is processed if it is passive. FLNK u u u In db. Common record support calls rec. Gbl. Fwd. Link Other DBF_FWDLINKs can be defined u Call db. Scan. Fwd. Link NOT rec. Gbl. Fwd. Link 1999/Ph 514: Record Support 11

Generated Include Files u EPICS db. To. Menu. H u u Code should use generated files. menu. Yes. No. h typedef enum { menu. Yes. No. NO, menu. Yes. No. YES } menu. Yes. No; u db. To. Record. Type. H u u Code MUST use generated files Include code to compute field sizes, offsets typedef struct ai. Record { char name[29]; … } #define ai. Record. NAME 0 … #ifdef GEN_SIZE_OFFSET int ai. Record. Size. Offset(db. Record. Type *p) { … } u Only record support and associated device support is allowed to use the include files. 1999/Ph 514: Record Support 12

Record Support Routines u u EPICS Provide Execution Semantics Defined via RSET - Record Support Entry Table /* Create RSET - Record Support Entry Table #define report NULL #define initialize NULL static long init_record(); static long process(); … struct rset <recordtype>RSET = { RSETNUMBER, report, initialize, init_record, process, … }; 1999/Ph 514: Record Support 13

Record Support Routines - Summary u Report, Initialization, Processing u u u EPICS report initialize init_record process Support for Channel/ Database Access u u u special cvt_dbaddr get_array_info put_array_info get_units get_precision get_enum_str put_enum_str get_enum_strs get_graphic_double get_control_double get_alarm_double 1999/Ph 514: Record Support 14

Report, Initialization, Processing u report(void *precord) u u u Nothing calls this. Normally not implemented initialize(void) u u u Called once before first call to init_record Not normally needed init_record(void *precord, int pass) u u Normally implemented Called twice u u u EPICS pass 0 - Can do anything except access other records. For example storage for arrays should be allocated during pass 0. pass 1 - Finish initialization and also call associated device support initialization process u u VERY IMPORTANT Implements record semantics 1999/Ph 514: Record Support 15

init_record example EPICS /* assume val is double *val */ typedef struct xxxdset { long number, DEVSUPFUN report; DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; DEVSUPFUN read; } xxxdset; static long init_record(void *prec, int pass) { xxxarray. Record *paf = (xxxarray. Record *)prec; xxxdest *pdset = (xxxdset *)paf->dset; if(pass==0) { if(paf->nelm<0) paf->nelm = 1; paf->val = (double *)calloc( paf->nelm, sizeof(double)); return(0); } /* Must have dset defined */ if(!pdset !! (pdset->number< 5) || !pdest->read ) { epics. Printf(“%s no or invalid dsetn”, paf->name); return(0); } (*pdset->init_record)(paf); return(0); } 1999/Ph 514: Record Support 16

process overview u process is called if u u EPICS Decision was made to process the record Record not active (PACT FALSE) Record is enabled (DISV !=DISA) process with device support must u set record active (PACT TRUE) u Perform I/O Check for record specific alarms Raise database monitors Request processing of forward links Set PACT FALSE and return u u 1999/Ph 514: Record Support 17

process overview continued u EPICS For asynchronous devices. u Asynchronous start u u Initiate I/O. Determine a method for again calling process when operation completes Return leaving PACT TRUE. Asynchronous completion u Call process as follows: db. Scan. Lock(precord); *(prset->process)(precord); db. Scan. Unlock(precord); u process completes record processing u Complete I/O Check for record specific alarms Raise database monitors Request processing of forward links Set PACT FALSE u return u u 1999/Ph 514: Record Support 18

process example EPICS static long process(void *prec, int pass) { xxxarray. Record *paf = (xxxarray. Record *)prec; xxxdest *pdset = (xxxdset *)paf->dset; unsigned char pact = paf->pact; unsigned short monitor_mask; /* Must have dset defined */ if(!pdset !! (pdset->number< 5) || !pdest->read ) { /*set pact true so process will not be called*/ paf->pact = TRUE; return(0); } (*pdset->read)(paf); /*return if beginning of asyn processing */ if(!pact && paf->pact) return(0); paf->pact = TRUE; alarm(paf); /*sample monitor code */ monitor_mask = rec. Gbl. Reset. Alarms(paf); monitor_mask |= (DBE_LOG|DBE_VALUE) db_post_events(paf, paf->val, monitor_mask); rec. Gbl. Fwd. Link(paf); paf->pact = FALSE return(0); } 1999/Ph 514: Record Support 19

alarm and monitors u alarms u rec. Gbl. Set. Sevr(void *prec, <alarm_status>, <alarm_severity>) Status and severity values defined in alarm. h u Must prevent alarm storms on numeric values u u u EPICS value fluctuating around alarm limit See Application Developer’s guide for algorithm process must call rec. Gbl. Reset. Alarms after all alarms have been raised and before calling rec. Gbl. Fwd. Link. Also, if possible, before raising monitors u db_post_event(void *prec, void *pfield, monitor_mask) u Call for all fields that change as a result of record processing Support value change hysteresis when possible. Look at ai. Record for an example u u 1999/Ph 514: Record Support 20

Routines with a DBADDR argument u u EPICS Called by database/channel access Call db. Get. Field. Index to find out which field. int field. Index; field. Index = db. Get. Field. Index(pdbaddr); if(field. Index == ai. Record. VAL). . . u DBADDR typedef struct db. Addr{ db. Common *precord; void *pfield; void *pfld. Des; void *as. Pvt; long no_elements; short field_type; short field_size; short special; short dbr_field_type; }DBADDR; 1999/Ph 514: Record Support 21

Record Support Routines - Cont. u special(DBADDR *pdbaddr, int after) u Called if special defined in dbd file u u u Called before and after field is modified. db. Get. Field. Index(pdbaddr) pdbaddr->special u u u EPICS The special type as defined in. dbd file. Must include file special. h cvt_dbaddr(DBADDR *pdbaddr) u u u Called by database library when DB/CA connects to field. Called if special(SPC_DBADDR) specified Following fields of DBADDR can be changed no_elements field_type field_size special dbr_type 1999/Ph 514: Record Support 22

Record Support Routines - Cont. u EPICS Array Routines u u Called if cvt_dbaddr sets no_elements > 1 get_array_info(DBADDR *pdbaddr, long *no_elements, long *offset) u Called when database access gets an array Must set no_elements u Can set offset if field is circular buffer u u put_array_info( DBADDR *pdbaddr, long n. New) Called after database access has written array 1999/Ph 514: Record Support 23

Record Support Routines - Cont. u EPICS Units/Precision u get_units(DBADDR *pdbaddr, char *punits) CA has MAX_UNITS_SIZE 8 u get_precision(DBADDR *pdbaddr, long *precision) Problems with only precision. u Enumerated Values u u u get_enum_str(DBADDR *pdbaddr, char *p) put_enum_str(DBADDR *pdbaddr, char *p) get_enum_strs(DBADDR *pdbaddr, dbr_enum. Strs *p) CA has limit of 16 choices, 26 characters in each choice u Graphic/ Control/ Alarm Limits u u u get_graphic_double(DBADDR *pdbaddr, struct dbr_gr. Double *p) get_control_double(DBADDR *pdbaddr, struct dbr_ctrl. Double *p) get_alarm_double(DBADDR *pdbaddr, struct dbr_al. Double *p) 1999/Ph 514: Record Support 24

Global Record Support Routines EPICS u All start with rec. Gbl u Intended for record/device support but also called by other code Reporting Errors Deprecated - Use epics. Printf instead u u Alarm Processing u u u Limits u u rec. Gbl. Set. Sevr(void *precord, short newstat, short newsevr) rec. Gbl. Reset. Alarms(void *precord); Defaults for fields record support doesn’t know how to handle Channel Access client often not happy Graphics, Control, Alarm limits rec. Gbl. Init. Constant. Link For use on link fields with a constant value. Only works on numeric values!! 1999/Ph 514: Record Support 25

Global Record Support Routines continued u EPICS rec. Gbl. Get. Time. Stamp record support should call this each time record completes processing. u rec. Gbl. Fwd. Link Must be called with pact true and all other processing complete 1999/Ph 514: Record Support 26

Database Access Routines for Record Support u u EPICS When in context of process use db. Get. Link, db. Put. Link information u db. Get. Pdb. Addr. From. Link gets address of DBADDR. u db. Get. Rset gets address of Record Support Entry table u db. Is. Link. Connected Is link connected? 1999/Ph 514: Record Support 27