1. Writing EPICS Drivers
(and Device Support)
Dirk Zimoch, 2007

2. Contents Writing EPICS Drivers Introduction A simple example driver
Tips and tricks
Example device support
Multi-threading
I/O Intr
Dirk Zimoch, 2007

3. Introduction
Dirk Zimoch, 2007

4. Required knowledge about EPICS
Writing EPICS Drivers
Required knowledge about EPICS
Records and fields
Standard records (ai, ao, mbbi, stringout, …)
Probably specialized records (motor, …)
Record processing
Scan methods (periodic, I/O Intr, …)
Links that cause processing (PP links, CP links, forward links)
Channel Access clients (medm, caget, …)
These are topics of a basic EPICS training
See also: IOC Application Developper's Guide.
Dirk Zimoch, 2007

5. Required knowledge about programming
Writing EPICS Drivers
Required knowledge about programming C
Variable flavours (global, local, static, volatile)
struct, union, array [], typedef, enum
Memory allocation (malloc, calloc) and pointers
Pointers to functions
Macros (#define) and conditional compilation (#ifdef)
Data structures
Integer representations (2's complement, hex, byte order)
Bit fields (masking, shifting, …)
Linked lists
Dirk Zimoch, 2007

6. Important knowledge about hardware I/O
Writing EPICS Drivers
Important knowledge about hardware I/O
I/O registers
Side effects of reading and writing
Fifo registers
Busses
VME address spaces A16, A24, A32
Memory mapped access
Out-of-order execution / pipelining
Interrupts
Interrupt levels and vectors
Interrupt handlers
Dirk Zimoch, 2007

7. Driver and Device support
Dirk Zimoch, 2007

8. What is an EPICS driver? Writing EPICS Drivers
Software interface between EPICS records and hardware (or 3rd party software)
Usually split in 2 parts for better maintainability
Device support
Interfaces to records
Does not care about hardware
Files: devXXX.c, XXX.dbd
Driver
Does low-level hardware (register) access
Does not care about records
Files: drvXXX.c, drvXXX.h, (sometimes XXX.dbd)
Dirk Zimoch, 2007

9. Layers: Record - Device Support – Driver - Hardware
Writing EPICS Drivers
Layers: Record - Device Support – Driver - Hardware
Does not know about drivers
Record
Records
Device support
function table
Record specific s
devXXX.c
Device Support
The "glue"
Driver API functions
Driver specific
drvXXX.h
Does not know about records
Driver
drvXXX.c
Register access
Hardware specific
Hardware
Dirk Zimoch, 2007

10. Splitting functionality: device support vs. driver
Writing EPICS Drivers
Splitting functionality: device support vs. driver
Device support is the "glue" between record and driver
Parses INP or OUT link
Reads / writes / initializes record fields
Calls driver API functions
Driver does the real work
Initializes the hardware
Creates work thread if necessary
Register access
Interrupt handling
Resource handling (semaphores, etc)
Dirk Zimoch, 2007

11. A simple example driver
Dirk Zimoch, 2007

12. In this chapter Writing EPICS Drivers Example hardware "myDac"
Interface (API) in drvMyDac.h
Implementation in drvMyDac.c
Configuration function
open() function
I/O funtions
Report function
Register to EPICS with drvMyDac.dbd
Registering variables
Registering functions
Dirk Zimoch, 2007

13. Example: 8 channel DAC Writing EPICS Drivers
The card is a VME board in A16 address space
One DAC "card" has 8 "signals".
Each signal is 16 bit (0x0000 = -10 V, 0xFFFF = +10 V)
The 8 signals are registers at offsets 0x10, 0x12, 0x14, 0x16
It is possible to read back the current register setting.
The card does not use interrupts.
The card has an identifier at offset 0x00
String: "MYDAC"+nullbyte
Dirk Zimoch, 2007

14. How to start? Writing EPICS Drivers
Decide what the driver should be able to do
Define one function for each functionality of the hardware
Don't think about records at this time
Think of "cards" or "boards", "signals" and functionality
Model a "card" as a structure
It contains hardware register address, internal states, etc…
Define a function which returns a pointer to this structure (like open() for a file)
Other functions take this "handle" as an argument
Define a configuration function to initialize one "card"
Dirk Zimoch, 2007

15. What to put into the header file
Writing EPICS Drivers
What to put into the header file
This file defines the interface to the driver
All public (API) driver functions
Maybe error codes if used as return values
Typedefs for used function parameters
This file does not contain implementation details
No card structure details
No internal functions (e.g. interrupt handler)
No macros etc. used only internally in driver
No register layout
Dirk Zimoch, 2007

16. Example drvMyDac.h file
Writing EPICS Drivers
Example drvMyDac.h file
#ifndef drvMyDac_h
#define drvMyDac_h
#include <devLib.h>
/* Initialize the card (called from startup script) */
int myDacConfigure (int cardnumber, unsigned int vmeAddress);
/* Define a type for the card handle */
typedef struct myDacCard myDacCard;
/* Get card handle from card number */
myDacCard* myDacOpen (int cardnumber);
/* Set and read back values */
int myDacSet (myDacCard* card, int signal, epicsUInt16 value);
int myDacGet (myDacCard* card, int signal, epicsUInt16* pvalue);
#endif
Configuration for one card
Type definition for card handle (no details)
Get handle for card
Public driver functions
What can the card do?
Dirk Zimoch, 2007

17. What to avoid Writing EPICS Drivers
Do not use void* for driver handle.
This allows the compiler to warn about wrong arguments.
Do not define the card handle structure in the header file.
This is an implementation detail and not of interest to the user.
Do not list internal functions in the header file.
Interrupt handlers etc. are implementation details.
Do not define the register layout in the header file.
You don't want anyone else but the driver to access registers.
Dirk Zimoch, 2007

18. Implementing the driver (part 1)
Writing EPICS Drivers
Implementing the driver (part 1)
Define "card" structure.
Contains at least register base address.
May contain thread ID, semaphores, etc.
Build a container of "cards" (linked list).
Define macros for register access.
Mark all registers volatile.
This prevents the compiler from "optimizing" and reordering register access.
Avoid global variables whenever possible.
At least use static for any private global variable.
Prefix every non-static global variable with driver name.
Dirk Zimoch, 2007

19. Includes, card structure and macros in devMyDac.c
Writing EPICS Drivers
Includes, card structure and macros in devMyDac.c
#include <stdio.h>
#include <string.h>
#include <devLib.h>
#include <drvSup.h>
#include <epicsExport.h>
#include "drvMyDac.h"
/* linked list of card structures */
struct myDacCard {
myDacCard *next;
int cardnumber;
int vmeAddress;
char* baseaddress; };
static myDacCard *firstCard = NULL;
/* 8 DACs (16 bit) at offset 0x10 and following */
#define DAC(card,signal) ((volatile epicsUInt16*)(card->baseaddress+0x10))[signal]
/* Other internally used macros */
#define VME_SIZE 0x100
/* Debugging switch */
int myDacDebug = 0;
epicsExportAddress (int, myDacDebug);
EPICS headers
Define card structure here (as linked list element)
Make private global variables static
Macros for register access
Use compiler independent volatile type
Must be non-static and exported to EPICS.
Prefix it properly.
Dirk Zimoch, 2007

20. What to avoid Writing EPICS Drivers
Do not use a structure to map registers.
Structures are compiler dependent.
Compiler may insert pad bytes to align elements.
Compiler may reorder elements to "optimize" access.
Use macros to calculate address offset.
Do not use compiler dependent data types for registers.
Not all compilers use 2 bytes for unsigned short.
Use compiler independent types like epicsUInt16 instead.
Do not use global variables to store any card details.
You may have more than one card. Make a list of structures.
Dirk Zimoch, 2007

21. Implementing the driver (part 2)
Writing EPICS Drivers
Implementing the driver (part 2)
Configuration function
Configure one and only one card per function call.
Give each card an individual id (number or string).
Do not use auto-numbering of cards.
This avoids problems when you have to remove a card (temporarily)
open() function
Return a card handle from a card id
Input/Output functions
Report function
(Interrupt handler)
Dirk Zimoch, 2007

22. What to do in the configuration function
Writing EPICS Drivers
What to do in the configuration function
Check parameters for sanity.
Calculate local (memory mapped) address of registers.
Check if the hardware is installed.
Create "card" structure.
Allocate memory.
Fill in values.
Put into linked list.
Give good error messages if anything goes wrong.
Don't forget driver name and parameters in error message.
Write error messages to stderr, not to stdout.
Dirk Zimoch, 2007

23. Example configuration function in drvMyDac.c
Writing EPICS Drivers
Example configuration function in drvMyDac.c
/* The configure function is called from the startup script */
int myDacConfigure (int cardnumber, unsigned int vmeAddress) {
long status;
volatile void* baseaddress;
char id[6];
myDacCard **pcard;
/* Check card number for sanity */
if (cardnumber < 0) {
fprintf (stderr, "myDacConfigure: cardnumber %d must be > 0\n",
cardnumber);
return S_dev_noDevice; }
/* Find end of card list and check for duplicates */
for (pcard = &firstCard; *pcard; pcard=&(*pcard)->next) {
if ((*pcard)->cardnumber == cardnumber) {
fprintf (stderr, "myDacConfigure: cardnumber %d already in use\n",
return S_dev_identifyOverlap;
Check all parametes
Write clear error messages to stderr
Return error codes (from devLib.h or drvMyDac.h)
Check for duplicate configuration
Remember: now *pcard points to the end of the list
Dirk Zimoch, 2007

24. Configuration function continued
Writing EPICS Drivers
Configuration function continued
/* Check vmeAddress for sanity */
if (vmeAddress % VME_SIZE != 0) {
fprintf (stderr, "myDacConfigure: "
"vmeAddress 0x%04x must be a multiple of 0x%x\n",
vmeAddress, VME_SIZE);
return S_dev_badA16; }
/* Translate vme to local address and check for overlap */
status = devRegisterAddress ("myDac", atVMEA16,
vmeAddress, VME_SIZE, &baseaddress);
if (status) {
"cannot register vmeAddress 0x%04x\n",
vmeAddress);
return status;
More parameter checks
Use devRegisterAddress (from devLib.h) to register VME address and to translate to local memory mapped address.
This fails if the address overlaps with another registered address.
Dirk Zimoch, 2007

25. Configuration function continued
Writing EPICS Drivers
Configuration function continued
Check that hardware is installed before using it.
/* Check that correct hardware is installed */
status = (devReadProbe (2, (char*) baseaddress, id)
|| devReadProbe (2, (char*) baseaddress+2, id+2)
|| devReadProbe (2, (char*) baseaddress+4, id+4));
if (status) {
fprintf (stderr, "myDacConfigure: "
"no card found at vmeAddress 0x%04x (local:%p)\n",
vmeAddress, baseaddress);
return status; }
if (strcmp(id, "MYDAC") != 0) {
"card at vmeAddress 0x%04x (local:%p) is not a MYDAC\n",
return S_dev_wrongDevice;
Use devReadProbe (from devLib.h) to access hardware safely.
If hardware is not installed, it does not crash but just fails.
Check that you have really the hardware you expect
Dirk Zimoch, 2007

26. Configuration function finished
Writing EPICS Drivers
Configuration function finished
/* Create new card structure */
*pcard = malloc (sizeof (myDacCard));
if (!*pcard) {
fprintf (stderr, "myDacConfigure: "
"out of memory\n");
return S_dev_noMemory; }
(*pcard)->next = NULL;
(*pcard)->cardnumber = cardnumber;
(*pcard)->baseaddress = baseaddress;
return 0;
Allocate card structure (malloc or calloc)
Remember? *pcard points to end of list
Success
Fill card structure with values
Dirk Zimoch, 2007

27. What to avoid Writing EPICS Drivers
Do not use other parameter types than int or char*.
double does not work on vxWorks shell on PPC architecture
Other types are not supported by iocsh.
Do not use too many parameters.
vxWorks supports only 10 parameters for shell functions.
Do not crash if card is absent.
Check card before use.
Do not give meaningless messages like "driver init failed".
The user needs information. What failed where and why?
Provide driver/function name, failing parameter and error reason.
Dirk Zimoch, 2007

28. Hardware registers Writing EPICS Drivers
A hardware register is not just a variable!
Write or read access may have side effects on the hardware.
Reading may get a different value than the last written one.
FIFO registers provide different values every time they are read, giving sequential access to an array through a scalar.
Reading or writing in pieces (e.g. low and high 16bit word to a 32bit register) may be invalid, may have unexpected effects, or may require a certain order.
Always use volatile to access registers
This tells the compiler not to try "optimization" on hardware registers.
Dirk Zimoch, 2007

29. What to do in the API functions
Writing EPICS Drivers
What to do in the API functions
Open
Check card id (number or string)
Find card in list of configured cards.
Return pointer to card structure (handle) or NULL.
I/O functions
Check handle for validity.
Read or write registers.
Return error code on failure or 0 on success.
No need to print error messages here (device support should do that)
Put in switchable debug messages.
Dirk Zimoch, 2007

30. Example API functions Writing EPICS Drivers
Translate card id to handle
myDacCard* myDacOpen (int cardnumber) {
myDacCard* card;
for (card = firstCard; card; card = card->next)
if (card->cardnumber == cardnumber) return card;
return NULL; }
int myDacSet (myDacCard* card, int signal, epicsUInt16 value)
if (!card)
return S_dev_noDevice;
if (signal < 0 || signal > 7)
return S_dev_badSignalNumber;
if (myDacDebug>0)
printf("myDacSet card %d signal = %x\n",
card->cardnumber, signal, &DAC(card, signal), (unsigned int)value);
DAC (card, signal) = value;
return 0;
Use handle in all other functions
Check handle for NULL
Check other parameters
Return error codes on failure.
Switchable debug message
Success
Access registers
Dirk Zimoch, 2007

31. Example API functions continued
Writing EPICS Drivers
Example API functions continued
int myDacGet (myDacCard* card, int signal, epicsUInt16* pvalue) {
if (!card)
return S_dev_noDevice;
if (signal < 0 || signal > 7)
return S_dev_badSignalNumber;
*pvalue = DAC(card, signal);
if (myDacDebug>1)
printf ("myDacGet card %d signal = %x\n",
card->cardnumber, signal, &DAC(card, signal), (unsigned int)*pvalue);
return 0; }
Never forget the checks.
Stability is more important than speed.
Dirk Zimoch, 2007

32. What to avoid Writing EPICS Drivers
Do not translate card id to structure in each API function call.
Get card handle once and use it in all other API functions.
Do not use card when configuration failed.
When configuration fails return NULL from open() call.
Check for NULL in all other functions.
Do not assume anything about records.
Do not use function names like write_ao().
The driver only cares about the features of the hardware.
Records are the business of device support.
Dirk Zimoch, 2007

33. Reporting hardware and driver status
Writing EPICS Drivers
Reporting hardware and driver status
Write a report function.
Print driver and register information to stdout.
Provide multiple levels of detail.
In lowest level (0) print only one line per card.
In higher levels print more details about configuration, registers, etc.
Register report function to EPICS.
Create a driver support structure.
Fill in a pointer to report function.
Export driver support structure to EPICS.
Dirk Zimoch, 2007

34. Example report function
Writing EPICS Drivers
Example report function
long myDacReport (int detail) {
myDacCard *card;
for (card = firstCard; card; card = card->next) {
printf (" card %d at address %p\n",
card->cardnumber, card->baseaddress);
if (detail >= 1) {
int signal;
unsigned short value;
for (signal = 0; signal < 4; signal++) {
value = DAC (card, signal);
printf(" DAC %d = 0x%04x = %+8.4f V\n",
signal, value, value*20.0/0xffff-10.0); }
return 0;
drvet myDac = { 2,
myDacReport,
NULL };
epicsExportAddress (drvet, myDac);
Print card information in any detail level
Print register contents only for higher detail level
Driver support structure contains report function
Export driver support structure function to EPICS
Dirk Zimoch, 2007

35. Report function call Writing EPICS Drivers
The dbior shell function calls driver report functions.
Example:
dbior Driver: myDac card
dbior "myDac",1 Driver: myDac card DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V DAC = 0x0000 = V
Dirk Zimoch, 2007

36. Exporting variables and functions to EPICS
Writing EPICS Drivers
Exporting variables and functions to EPICS
VxWorks shell can access C functions and variables directly
Other architectures must run iocsh
Shell must know about functions, variables, driver support
Export variables and driver support from C
epicsExportAddress (int, myDacDebug);
epicsExportAddress (drvet, myDac);
Much more complicated for functions
Write parameter description
Write wrapper function
Write registrar function
Very ugly and error-prone
Dirk Zimoch, 2007

37. Wrapper and registrar for shell functions
Writing EPICS Drivers
Wrapper and registrar for shell functions
Parameter description
#include <iocsh.h>
static const iocshArg myDacConfigureArg0 = { "cardNumber", iocshArgInt };
static const iocshArg myDacConfigureArg1 = { "vmeA16Address", iocshArgInt };
static const iocshArg * const myDacConfigureArgs[] = {
&myDacConfigureArg0,
&myDacConfigureArg1 };
static const iocshFuncDef myDacConfigureDef =
{ "myDacConfigure", 2, myDacConfigureArgs };
static void myDacConfigureFunc (const iocshArgBuf *args) {
myDacConfigure (args[0].ival, args[1].ival); }
static void myDacRegister ()
iocshRegister (&myDacConfigureDef, myDacConfigureFunc);
/* iocshRegister (other shell functions) */
epicsExportRegistrar (myDacRegister);
Array of all parameters
Parameter count
for each function
Function description
Wrapper function
Unwrap parameters
Real function call
Register functions to iocsh
Export registrar to EPICS
Dirk Zimoch, 2007

38. Importing variables and functions to EPICS
Writing EPICS Drivers
Importing variables and functions to EPICS
Make exported C variables and functions known to EPICS
Write MyDac.dbd file with references to exported entities
Driver support structure
driver(myDac)
Variables
variable(myDacDebug, int)
Registrar
registrar(myDacRegister)
Coming soon: Device support
device(…)
Dirk Zimoch, 2007

39. From Dirk's Code Kitchen
Tips and Tricks
From Dirk's Code Kitchen
Dirk Zimoch, 2007

40. A bit more safety / paranoia
Writing EPICS Drivers
A bit more safety / paranoia
Even if card != NULL, it may be invalid
E.g. user calls myDacGet() with cardnumber instead of handle.
Accessing wrong hardware address is bad.
A cheap way to check the card handle is a "magic number"
Add magic number to card structure.
Insert magic number when card is configured.
Check magic number in every API function.
A good magic number is CRC checksum of driver name
echo -n myDac | cksum
Dirk Zimoch, 2007

41. Example usage of magic numbers
Writing EPICS Drivers
Example usage of magic numbers
#define MYMAGIC U /* crc("myDac") */
struct myDacCard {
epicsUInt32 magic;
myDacCard *next;
int cardnumber;
int vmeAddress;
volatile char* baseaddress; };
int myDacConfigure (int cardnumber, unsigned int vmeAddress) { …
(*pcard)->magic = MYMAGIC;
(*pcard)->next = NULL;
(*pcard)->cardnumber = cardnumber;
(*pcard)->baseaddress = baseaddress;
return 0; }
int myDacSet (myDac* card, int signal, epicsUInt16 value)
if (!card) return S_dev_noDevice;
if (card->magic != MYMAGIC) return S_dev_wrongDevice;
Store magic number in card structure.
Initialize magic number in configure function.
Check magic number in every call.
Dirk Zimoch, 2007

42. Simulation Mode Writing EPICS Drivers
EPICS does not support VME on Unix (or Windows)
devRegisterAddress() fails on softioc
devReadProbe() fails on softioc
Implement "simulation mode" on Unix for driver test
Work on allocated memory instead of registers #ifdef UNIX /* UNIX has no VME. Use a simulation for tests */ #include <malloc.h> #define devRegisterAddress(name, type, addr, size, pbase) \ ((*(pbase)=memalign (0x10000, size))? \ strncpy ((void*)*(pbase), "MYDAC", size), 0 : S_dev_noMemory) #define devReadProbe (size, ptr, buff) \ (memcpy (buff, (void*)ptr, size), 0) #endif
Dirk Zimoch, 2007

43. Example (synchronous) device support
Dirk Zimoch, 2007

44. In this chapter Writing EPICS Drivers Device support structure
Record initialization
Parse INP/OUT link
Connect to driver
Fill record private data structure
Initialize record from hardware
Read or write (record processing)
Transfer data between record and driver
Linear scaling
Dirk Zimoch, 2007

45. How to start? Writing EPICS Drivers
Decide what record types to support
Write one device support for each record type
Find out what record expects in device support
See record reference manual / record source code
Unfortunately no header file defines the device support
Choose synchronous or asynchronous support
If driver never blocks: synchronous
e.g. register access
If driver may block or driver has callback functions: asynchronous
e.g. field bus access
Maybe "I/O Intr" support if possible
Dirk Zimoch, 2007

46. The device support structure
Writing EPICS Drivers
The device support structure
One device support structure for each supported record type.
Contains pointers to device support functions.
Depends on record type.
Usually: struct { long number; /* of functions below */ DEVSUPFUN report; DEVSUPFUN init; DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; DEVSUPFUN read_or_write; }
Additional functions for some record types (see record reference manual)
Dirk Zimoch, 2007

47. Typical device support functions
Writing EPICS Drivers
Typical device support functions
report (can be NULL)
Report function similar to driver report function, but per record type
init (can be NULL)
Initialization of device support per record type
init_record
Initialization of device support per record
get_ioint_info (can be NULL)
For records scanned in "I/O Intr" mode
read or write (depending on record type)
Actual I/O during record processing
Dirk Zimoch, 2007

48. Example: synchronous ao support for myDac
Writing EPICS Drivers
Example: synchronous ao support for myDac
Device support structure of ao:
Additional function special_linconv.
struct { long number; /* must be 6 */ DEVSUPFUN report; /* can be NULL */ DEVSUPFUN init; /* can be NULL */ DEVSUPFUN init_record; DEVSUPFUN get_ioint_info; /* can be NULL */ DEVSUPFUN write; DEVSUPFUN special_linconv; }
Implement 3 functions
long myDacInitRecordAo(aoRecord *record)
long myDacWriteAo(aoRecord *record)
long myDacSpecialLinconvAo(aoRecord *record, int after)
Store record private data in record->dpvt.
Dirk Zimoch, 2007

49. Analog out device support (includes, private data)
Writing EPICS Drivers
Analog out device support (includes, private data)
#include <stdio.h>
#include <stdlib.h>
#include <devSup.h>
#include <recGbl.h>
#include <alarm.h>
#include <aoRecord.h>
#include <epicsExport.h>
#include "drvMyDac.h"
typedef struct {
myDacCard* card;
int signal;
} myDacAoPrivate;
Include header(s) of supported record type(s)
Include driver header
Store record specific data (e.g. driver handle) in private structure
Dirk Zimoch, 2007

50. Analog out device support (device support structure)
Writing EPICS Drivers
Analog out device support (device support structure)
Implement at least 3 functions for ai/ao:
init_record
read/write
special_linconv
long myDacInitRecordAo (aoRecord *record);
long myDacWriteAo (aoRecord *record);
long myDacSpecialLinconvAo (aoRecord *record, int after);
struct {
long number;
DEVSUPFUN report;
DEVSUPFUN init;
DEVSUPFUN init_record;
DEVSUPFUN get_ioint_info;
DEVSUPFUN write;
DEVSUPFUN special_linconv;
} myDacAo = { 6,
NULL,
myDacInitRecordAo,
myDacWriteAo,
myDacSpecialLinconvAo };
epicsExportAddress(dset, myDacAo);
Put functions into device support structure.
Use NULL for unimplemented functions.
Export device support structure to EPICS.
Dirk Zimoch, 2007

51. Importing device support to EPICS
Writing EPICS Drivers
Importing device support to EPICS
Make exported device supports known to EPICS
Add one line for each supported record type to MyDac.dbd: device (ao, VME_IO, myDacAo, "MyDac")
device support structure
Name used in DTYP field of record
record type
link type
record (ao, "$(name)") { field (DTYP, "MyDac") field (OUT, "#C$(card) S$(signal)") …
Dirk Zimoch, 2007

52. Analog out device support (init_record part 1)
Writing EPICS Drivers
Analog out device support (init_record part 1)
long myDacInitRecordAo (aoRecord *record) {
myDacAoPrivate *priv;
epicsUInt16 initval;
myDacCard* card;
int signal;
if (record->out.type != VME_IO) {
errlogSevPrintf (errlogFatal,
"myDacInitRecordAo %s: illegal OUT link type\n", record->name);
return -1; }
card = myDacOpen (record->out.value.vmeio.card);
if (!card) {
"myDacInitRecordAo %s: invalid card number %d\n", record->name, record->out.value.vmeio.card);
return S_dev_noDevice;
Check INP/OUT link type.
Get link parameters
Get handle to driver
Dirk Zimoch, 2007

53. Analog out device support (init_record part 2)
Writing EPICS Drivers
Analog out device support (init_record part 2)
signal = record->out.value.vmeio.signal;
if (signal < 0 || signal >= 8) {
errlogSevPrintf (errlogFatal,
"myDacInitRecordAo %s: invalid signal number %d\n",
record->name, signal);
return S_dev_badSignalNumber; }
priv = (myDacAoPrivate*) malloc (sizeof (myDacAoPrivate));
if (!priv) {
"myDacInitRecordAo %s: out of memory\n", record->name);
return S_dev_noMemory;
priv->card = card;
priv->signal = signal;
record->dpvt = priv;
myDacSpecialLinconvAo (record, TRUE);
myDacGet (card, signal, &initval);
record->rval = initval;
return 0;
Get more link parameters
Allocate private data
Fill private data and store in dpvt
Return 0 (OK) or error status
Initialize record fields
Dirk Zimoch, 2007

54. Analog out device support (write)
Writing EPICS Drivers
Analog out device support (write)
long myDacWriteAo (aoRecord *record) {
myDacAoPrivate *priv = (myDacAoPrivate*) record->dpvt;
int status;
if (!priv) {
recGblSetSevr (record, UDF_ALARM, INVALID_ALARM);
errlogSevPrintf (errlogFatal,
"myDrvWriteAo %s: record not initialized correctly\n",
record->name);
return -1; }
status = myDacSet (priv->card, priv->signal, record->rval);
if (status) {
"myDrvWriteAo %s: myDacSet failed: error code 0x%x\n",
record->name, status);
recGblSetSevr (record, WRITE_ALARM, INVALID_ALARM);
return status;
Get private data back from dpvt
Check for proper initialization
Call driver function
Return 0 or error status
Dirk Zimoch, 2007

55. Analog out device support (special_linconv)
Writing EPICS Drivers
Analog out device support (special_linconv)
long myDacSpecialLinconvAo (aoRecord *record, int after) {
if (after) {
record->eslo = (record->eguf - record->egul)/0xFFFF;
record->eoff = record->egul; }
return 0;
Initialize linear scaling. This DAC uses range 0x0000 to 0xFFFF
Only required for ao and ai records
ao record calculates RVAL = (VAL - EOFF) / ESLO ai records calculates VAL = RVAL * ESLO + EOFF
User provides:
EGUL (should map to minimal raw value, e.g. 0x0000)
EGUF (should map to maximal raw value, e.g. 0xFFFF)
Dirk Zimoch, 2007

56. I/O Intr
Dirk Zimoch, 2007

57. What is I/O Intr? Writing EPICS Drivers It is a record scanning mode.
The record is scanned whenever the driver has new data.
Its an easy way to implement fast (>10 Hz) or irregular scanning.
Can be triggered from driver thread or from interrupt level.
Dirk Zimoch, 2007

58. How to set up I/O Intr scanning?
Writing EPICS Drivers
How to set up I/O Intr scanning?
Create one IOSCANPVT structure (from dbScan.h) for each source of “new data events” (e.g. interrupt) of the driver.
Implement get_ioint_info() in device support
The record calls this function whenever SCAN is set to “I/O Intr”.
The function should get the IOSCANPVT from the driver.
It calls scanIoInit(IOSCANPVT *) to register with the “new data event”
The driver calls scanIoRequest(IOSCANPVT *) whenever it has new data.
The record processes and reads the value.
Dirk Zimoch, 2007

59. Differences to normal scanning
Writing EPICS Drivers
Differences to normal scanning
Normally the record asks the driver to start I/O.
Here the driver does I/O first, then processes the record.
The driver should store the data where the record can find it.
Many record can be triggered from one event source.
E.g. 32 bi records bound to an digital I/O card.
This may increase performance when hardware access is costly.
Dirk Zimoch, 2007

60. Asynchronous Device Support
Dirk Zimoch, 2007

61. About asynchronous support
Writing EPICS Drivers
About asynchronous support
When to use?
If hardware access is slow or may block.
Examples: Fields busses (serial, GPIB, …)
What is the problem?
Record processing must not block.
Solution: Asynchronous device support
Driver starts a “work thread” that can block.
Device support starts driver action with non-blocking function.
Driver calls back when I/O is complete.
Dirk Zimoch, 2007

62. Asynchronous read or write function in detail
Writing EPICS Drivers
Asynchronous read or write function in detail
The read or write function calls driver to start I/O.
Then it sets the PACT (processing active) field and returns.
The record now knows that I/O is still in progress and pauses.
The IOC continues with other records.
Driver thread requests to process record again when ready.
Read or write function is called a second time with PACT=1.
The function transfers values from driver to record and returns.
Record processing completes (forward link, monitors, etc).
Dirk Zimoch, 2007

63. Example asynchronous ai read function
Writing EPICS Drivers
Example asynchronous ai read function
Get private data back from dpvt
long slowDeviceReadAi (aiRecord *record) {
slowDeviceAiPrivate* priv = (slowDeviceAiPrivate*) record->dpvt;
if (!priv) {
/* error handling: record not initialized */ return -1; }
if (record->pact == 0) {
driverStartRead(priv->card, priv->signal, &slowDeviceFinishedAi, record);
record->pact = 1;
return 0;
if (priv->status != 0) {
errlogSevPrintf(errlogFatal,
"myDriver %s: driver read failed: error code 0x%x\n",
record->name, priv->status);
recGblSetSevr(record, READ_ALARM, INVALID_ALARM);
return priv->status;
record->rval = priv->value;
Driver will call back when finished
Call non-blocking driver function to start I/O
first call
Tell record to wait and return
second call
Handle error status of driver
Get data from driver (see next slide)
Dirk Zimoch, 2007

64. Asynchronous finish function
Writing EPICS Drivers
Asynchronous finish function
void slowDeviceFinished (dbCommon* record, int status, epicsInt16 value) { slowDevicePrivate* priv = (slowDevicePrivate*) record->dpvt;
private->status = status;
private->value = value;
callbackRequestProcessCallback (&priv->cb, record->prio, record); }
Store value and result where record can find it.
Request record processing in one of the three callback threads.
Dirk Zimoch, 2007

65. Multi-threading issues
Dirk Zimoch, 2007

66. Threads used in EPICS Writing EPICS Drivers
Many parts of the EPICS software work in parallel. (In vxWorks, threads are called tasks.)
E.g. each SCAN type runs in a separate thread
High priority thread for ".1 second" scanning
Low priority thread for "10 second" scanning
Lowest priority for "Passive" scanning as the result of a caput.
Additional threads for callbacks, timeouts, channel access, …
Many threads may execute the same function at the same time
E.g. two records with the same driver and different scan rates.
The CPU can switch from one thread to another at any time.
Dirk Zimoch, 2007

67. The re-entrancy problem
Writing EPICS Drivers
The re-entrancy problem
Functions must be re-entrant.
Bad example: char* numToString (int number) { static char buffer[20]; sprintf (buffer, "%d", number); return buffer; }
What's bad?
Thread 1 calls numToString(12345).
Some time after sprintf() the CPU switches to thread 2.
Thread 2 calls numToString(42).
Some time after sprintf() the CPU switches to thread 1.
Thread 1 uses the function result and reads "42"
Dirk Zimoch, 2007

68. Making code re-entrant
Writing EPICS Drivers
Making code re-entrant
Never return a pointer to static memory.
Never call such a function.
Nobody would do that? System functions that do:
char *ether_ntoa (const struct ether_addr *addr)
char *asctime (const struct tm *tm)
struct tm *localtime (const time_t *timep)
char *strerror (int errnum)
Use functions where the caller provides the buffer
char *ether_ntoa_r (const struct ether_addr *addr, char *buf)
char *asctime_r (const struct tm *tm, char *buf)
struct tm *localtime_r (const time_t *timep, struct tm *result)
int strerror_r (int errnum, char *buf, size_t n)
Dirk Zimoch, 2007

69. Non-atomic operations on global resources
Writing EPICS Drivers
Non-atomic operations on global resources
Non-atomic operations may be interrupted by an other thread.
If the other thread accesses the same global resource it may get inconsistent data.
Example:
time
thread 1: paint_wall (green)
thread 2: look_at_wall()
thread 1 starts paining
thread 1 is interrupted
thread 1 has finished
Dirk Zimoch, 2007

70. What are global resources?
Writing EPICS Drivers
What are global resources?
Global variables
Static variables
Heap objects
Hardware registers
Files
Directories
Sockets
Anything for that you have only a pointer or handle
Dirk Zimoch, 2007

71. What are non-atomic operations?
Writing EPICS Drivers
What are non-atomic operations?
read-modify-write:
if (p == NULL) p = …
if (! file_exists(filename)) { fopen (filename, "w"); … }
flags |= 1;
reg &= mask;
counter++;
sequential read/write:
strcpy (globalstring, s);
globalstruct.a = a; globalstruct.b = b;
addressregister = adr; val = valueregister;
element->next = previous->next; previous->next = element;
Dirk Zimoch, 2007

72. What is thread-safe? Writing EPICS Drivers Local variables errno
Everything on the stack is thread specific.
errno
Even though it looks like a global variable, it is thread specific.
Single threaded context
startup script
functions called from iocInit
driver and record initialization
Resources used only by one thread
Resources used only in interrupt handler
Dirk Zimoch, 2007

73. How to make non-atomic operations safe?
Writing EPICS Drivers
How to make non-atomic operations safe?
Disable interrupts.
Only interrupts can cause unexpected thread switch.
This is very brute.
Do this only for VERY SHORT times.
Use mutual exclusion semaphores.
Use operating system independent wrapper (epicsMutex).
Be careful to prevent deadlocks: Two different threads must never take two different semaphores in reverse order.
Lock resources as short as possible.
Dirk Zimoch, 2007