RTDL Driver Design Review

1
RTDL Driver Design Review
Johnny Tang (BNL) SNS Global Controls
2
Outline

• RTDL Driver Design Requirements
• RTDL Board VME Memory Map and Register Bit
  Assignments
• RTDL Driver Design Block Diagram
• RTDL Driver - rtdlDrv
• Initialization
• Default Mode
• Device Names
• IOCTL Functions
• Concurrency Control
• Interrupt Handling
• Read/Write Functions
• Parameter ID Table
• RTDL EPICS Interface
• New Customized Record vs. Record Template
• EPICS Device Support
• RTDL Documentations
• Summary Current Status

3
RTDL Driver Design Requirements

• Compatible with SNS ADE
• Provide Board Configuration Status Access
  Routines
• Support RTDL Board Functionalities
• Compliant with Wind River Coding Conventions
• VxWorks naming conventions (routines, variables,
  constants, macros, types, structure and error
  status codes)
• Unique status codes assigned for each error
• Subroutines must be preceded by a comment block
  containing the purpose of the subroutine
• Parameterize base address, interrupt number
  vector

4
RTDL VME Memory Map and Bit Assignments

• SNS RTDL Master has one Encoder module (v105s)
  and and many (up to 128) RTDL dual channel input
  modules (v106s) or up to 32 eight channel input
  modules (v206)
• SNS RTDL driver was developed against v105 and
  v106 while v206 and Utility modules were not
  available at the time

5
V105 Registers

• Address Description
• Base Addr 64 (40H) Command Register (R/W)
• Base Addr 66 (42H) Status Register (R)
• Base Addr 68 (44H) Interrupt Vector Register
  (7-0) (R/W)

6
V105 Register Bit Assignments

• Command Register bit 0 gt Reset
• bit 1 gt External Trigger On/Off
• bit 2 gt Go Init Done/not done
• bit 3 gt Interrupt Enable/Disable
• bit 4 gt Undefined
• bit 5-7gt INTCD(1..3) interrupt level
• bit8-15gt Undefined
•  Status Register bit 0 gt NO Reply
  Error
• bit 1 gt INITDONE/ERROR
• bit 4 gt RTDLACT Transmitter Active
• bit 8-15 gt IDCODE(0..7) (only important if
  NoReply Error)
•  
• Interrupt Vector Register bit 7-0 gt
  Vector

7
V105 Parameter ID Codes SRAM

• Address Contents
• Base Addr 256 (100H) Parameter ID Code 1
• Base Addr 257 (101H) Parameter ID Code 2
• Base Addr 258 (102H) Parameter ID Code 3
• .
• .
• Base Addr (256 n) Parameter ID Code n
• Base Addr (256 n 1) 00H
• .
• .
• Base Addr 511 (1FFH) End of RAM Space

8
V106 Registers

• Address Description
• Base Addr 64 (40H) Command Register CH1
• Base Addr 66 (42H) Command Register CH2
• Base Addr 68 (44H) VME Data Register CH1
  (15-0)
• Base Addr 70 (46H) VME Data Register CH1
  (23-16)
• Base Addr 72 (48H) VME Data Register CH2
  (15-0)
• Base Addr 74 (4AH) VME Data Register CH2
  (23-16)
• Base Addr 76 (4CH) Device Data Register CH1
  (15-0)
• Base Addr 78 (4EH) Device Data Register CH1
  (23-16)
• Base Addr 80 (50H) Device Data Register CH2
  (15-0)
• Base Addr 82 (52H) Device Data Register CH2
  (23-16)
• Base Addr 84 (54H) Interrupt Vector Register
  (7-0)
• Base Addr 86 (56H) Status/Interrupt Status
  Register CH1 (15-0)
• Base Addr 88 (58H) Status/Interrupt Status
  Register CH2 (15-0)

9
V106 Register Bit Assignments

• Command Register bit 0 gt Reset
• bit 1 gt Mode (VME/Device)
• bit 2 gt Halt/Load (VME Data)
• bit 3 gt Interrupt Enable
• bit 4 gt Go
• bit 5-7 gt INTerrupt CoDe (1..3) Interrupt
  level
• bit 8-15 gt Undefined
• Status register bit 0 gt Link Status
• bit 1 gt CRC Error Status
• bit 2 gt Frame Error Status
• bit 3 gt Link Interrupt Status
• bit 4 gt CRC Interrupt
  Status
• bit 5 gt Frame Interrupt Status
• bit 6-7 gt Undefined
• bit 8-15 gt Parameter ID
•  Interrupt Vector Register bit 7-0 gt
  Vector

10
RTDL Driver Design Block Diagram
Application
RTDL IOC Startup Script
EPICS Support Layer
write()
close()
read()
ioctl()
open()
ioLib
iosDrvInstall()
iosLib
iosDevAddl()
rtdlDrv()
rtdlWrite()
rtdlClose()
rtdlRead()
rtdlIoctl()
rtdlDevCreate()
rtdlOpen()
rtdlDrv
RTDL P2 Bus
11
RTDL Driver rtdlDrv.c - Initialization

• Initialization
• rtdlDrv() must be called to install the driver
  in the VxWorks I/O system.
• rtdlDevCreate() must then be called to
  initialize and install each device (v105 or v106)
• After installing the driver and creating the
  devices the following functions are available
  open(),close(),ioctl(),read(),write() through the
  VxWorks I/O system.
• These routines may be called from an IOC startup
  script before EPICS software is loaded
• Install RTDL driver
• int rtdlDrv(void)
• Create each RTDL input/encoder device
• int rtdlDevCreate(deviceName, baseAddress,
  moduleType, intNumber, intLevel)
• char deviceName Name of RTDL device
• int baseAddress Base address of board on VME
  bus
• unsigned int moduleType Type of module (0
  v106 module, 1 v105 module)
• unsigned char intNumber interrupt number for
  board
• unsigned char intLevel interrupt level for
  board

12
RTDL Driver rtdlDrv.c Default Mode

• Default Mode
• When new input channel devices are installed,
  the driver will not affect the state of the input
  channels. Ioctl functions are provided which can
  be used to determine the current state.
• When new encoder devices are installed, the
  driver reads an indication on the encoder board
  to see if initialization is necessary. If the
  board had been previously initialized, the driver
  does not affect the state of the board. If
  initialization is necessary, the encoder module
  will be configured as follows
• Interrupts are enabled.
• Encoder GO bit is set.

13
RTDL Driver rtdlDrv.c Device Names

• Device Names
• A device can be defined as either an encoder
  module or an input module. Each module within the
  system will have a unique device name. The driver
  supports arbitrary names. However, it is
  recommended that, for ease of use, device names
  reflect the function or position of the device in
  the system.
• For example,
• rtdlDevCreate /dev/rtdlE, 0x200, 1, 0x1a, 3
  Create a device for v105 RTDL Encoder
• rtdlDevCreate /dev/rtdlIA, 0xfe00, 0, 0x1b, 3
  Create a device for 1st RTDL Input
• rtdlDevCreate /dev/rtdlIB, 0xfe00, 0, 0x1c, 3
  Create a device for 2nd RTDL Input
• Extended naming will be used when using open()
  to access a specific channel on an input module.
  E.g. if the name of the input device is
  "/dev/rtdlB", the name of channel 1 is
  "/dev/rtdlB/1", and the name of channel 2 is
  "/dev/rtdlB/2".
• E.g. the C command
• fd fopen("/dev/rtdlA/1")
• will open a device for Real Time Data Link input
  module A which is used to read channel 1.

14
RTDL Driver rtdlDrv.c IOCTL Function List

• Supported IOCTL Functions
• RTDL_INPUT_SET_MODE RTDL_INPUT_GET_MODE
  RTDL_INPUT_SET_VME_DATA RTDL_INPUT_GET_VME_DATA
  RTDL_INPUT_GET_DEVICE_DATA RTDL_ENCODER_GET_STAT
  US RTDL_ENCODER_SET_TRIGGER RTDL_ENCODER_GET_TRI
  GGER RTDL_ENCODER_NO_REPLY_ERROR_COUNT
  RTDL_ENCODER_NO_REPLY_ERROR_ID
  RTDL_ENCODER_NO_CARRIER_ERROR_COUNT
  RTDL_INPUT_NO_LINK_ERROR_COUNT
  RTDL_INPUT_FRAME_ERROR_COUNT RTDL_INPUT_CRC_ERRO
  R_COUNT RTDL_ENCODER_ADD_CODE RTDL_ENCODER_DELET
  E_CODE RTDL_INPUT_GET_PARAMETER_ID
  RTDL_SET_RESET RTDL_GET_RESET
  RTDL_GET_BASE_ADDRESS RTDL_ENCODER_VERIFY_CODE

15
RTDL Driver rtdlDrv.c IOCTL Functions
16
RTDL Driver rtdlDrv.c IOCTL Functions
17
RTDL Driver rtdlDrv.c IOCTL Functions
18
RTDL Driver rtdlDrv.c IOCTL Functions
19
RTDL Driver rtdlDrv.c IOCTL Functions
20
RTDL Driver rtdlDrv.c IOCTL Functions
21
RTDL Driver rtdlDrv.c IOCTL Functions
22
RTDL Driver rtdlDrv.c IOCTL Functions
23
RTDL Driver rtdlDrv.c IOCTL Functions
24
RTDL Driver rtdlDrv.c IOCTL Functions
25
RTDL Driver rtdlDrv.c Concurrency Control

• Concurrency Control protect reading while
  writing
• A semaphore is used internally within the driver
  to control access to the read and write functions
  to one user at a time. If the semaphore is not
  available, the driver will wait until it does
  become available.

26
RTDL Driver rtdlDrv.c Interrupt Handling

• Interrupt Handling
• Interrupts are generated when the encoder module
  does not get a response from a particular input
  channel.
• The PARAMETER ID on the encoder module is read by
  the interrupt handler when a NO RESPONSE
  interrupt occurs in order to decipher which
  channel is at fault.
• Interrupts are generated on the input module when
  the carrier on the local serial link has not been
  detected for 2us, when a frame has been received
  with a data integrity (CRC) error, and when a
  frame error occurs.
• A count is kept of each type of error for each
  device. These are available through the ioctl
  functions.

27
RTDL Driver rtdlDrv.c Read/Write Functions

• Read/Write Functions
• The read and write functions of the driver are
  limited to reading and writing from the parameter
  ID table within the encoder module.

28
RTDL Driver rtdlDrv.c Parameter ID Table

• Parameter ID Table
• The encoder module has a special table which is
  used for configuration, known as the parameter ID
  table. In it is the parameter ID list which the
  encoder board will use to determine the sequence
  of transmission for the input channel values at
  each transmission event.
• The table can contain a list of up to 256
  entries. The table may be accessed using either
  the IOCTL functions RTDL_ENCODER_ADD_CODE, or
  RTDL_ENCODER_DELETE_CODE, or the driver's read or
  write functions if the user desires to read or
  insert a parameter list in one driver call. The
  beginning of the table is assigned to offset 0 of
  the read/write buffer used. It contains the
  following format
• MSB ..... Parameter ID ..... LSB
• Entry 0  ________________________
• . . . .
• . . . . . .
• Entry 255  ________________________
• where "Entry" is an 8-bit code for an input
  channel. The first zero entry in the list will
  cause the encoder to stop scanning the table for
  more entries

29
RTDL Driver rtdlDrv.c Encoder (v105) ISR
/

rtdlEncIntHandlerInterrupt handler for
interrupts generated by encoder module.

Notes

1) Interrupts can be generated
when the encoder module does not get a response
from a particular input channel. The
PARAMETER ID of the channel at fault is
stored and an error count is incremented.
2) The
interrupt status is cleared when the status
register is read (RORA). 3) The
interrupt handler will disable ENCODER module
interrupts and start a watchdog timer.
When this is exhausted a routine (rtdlEncWD) is
called to re- enable interrupts. This
prevents a continuous error condition from taking
over the system with continuous
interrupts.

/LOCAL
void rtdlEncWD( FAST RTDL_DEV_HEADER
pRtdlDevHeader ) / Reenable interrupts.
/ (pRtdlDevHeader-gtpCommandRegister)
ENC_INT_ENABLE LOCAL void rtdlEncIntHandler(FA
ST RTDL_DEV_HEADER pRtdlDevHeader) int
status / Disable interrupts. Will
re-enable when watchdog routine is called. /
(pRtdlDevHeader-gtpCommandRegister)
(ENC_INT_ENABLE) / Start a watchdog
timer which will call rest of routine (in
rtdlEncWD), later on (want .5 second delay). /
wdStart( pRtdlDevHeader-gtwatchdogId,
sysClkRateGet()gtgt1, (FUNCPTR)rtdlEncWD,
(int)pRtdlDevHeader ) / Clear interrupt
by reading status register of encoder module. /
status (pRtdlDevHeader-gtpStatusRegister)
if ( status ENC_NO_REPLY_INT )
pRtdlDevHeader-gtencNoReplyErrCount
pRtdlDevHeader-gtencNoReplyID status gtgt 8
return
30
RTDL Driver rtdlDrv.c Input (v106) ISR
/

rtdlInputInthandlerInterrupt handler for input
module.

Notes

1) On the input module interrupts are
generated because of FRAME errors, CRC
errors, or LINK not detected for 2 us.
2) Interrupt status
is cleared when status register is read (RORA).
3) The interrupt handler will disable
INPUT module interrupts and start a
watchdog timer. When this is exhausted a routine
(rtdlInpWD) is called to reenable
interrupts. This prevents a continuous error
condition from taking over the system
with continuous interrupts.
4) There is no way of determining
channel 1 or channel 2 at fault so
handler will check status of both channels.
5) Will check for
CRC and frame errors only when link is detected.

/LOCAL
void rtdlInpWD( FAST RTDL_DEV_HEADER
pRtdlDevHeader ) / Reenable interrupts.
/ (pRtdlDevHeader-gtpCommandChan1Register)
INP_INT_ENABLE (pRtdlDevHeader-gtpCommand
Chan2Register) INP_INT_ENABLE LOCAL void
rtdlInputIntHandler(FAST RTDL_DEV_HEADER
pRtdlDevHeader) int status/
volatile UINT16 pWord/ / Disable
interrupts. Will re-enable when watchdog routine
is called. / (pRtdlDevHeader-gtpCommandChan1
Register) (INP_INT_ENABLE)
(pRtdlDevHeader-gtpCommandChan2Register)
(INP_INT_ENABLE) / Start a watchdog
timer which will call rest of routine (in
rtdlInpWD), later on (want .5 second delay). /
wdStart( pRtdlDevHeader-gtwatchdogId,
sysClkRateGet()ltlt1, (FUNCPTR)rtdlInpWD,
(int)pRtdlDevHeader )
31
RTDL Driver rtdlDrv.c Input (v106) ISR
cont
/ Clear interrupt by reading status
register of input module for channel 1.
Check status bits for errors. / status
(pRtdlDevHeader-gtpStatusChan1Register)
if( status INP_LINK_INT_STATUS )
pRtdlDevHeader-gtinpLinkErrCount0 /
Increment Input module LINK NOT DETECTED error
count. / else / Check for these
only if link is detected. / if( status
INP_FRAME_INT_STATUS ) pRtdlDevHeader-gtinp
FrameErrCount0 / Increment Input module
FRAME error count. / if( status
INP_CRC_INT_STATUS ) pRtdlDevHeader-gtinpCr
cErrCount0 / Increment Input module CRC
error count. / / Clear interrupt
by reading status register of input module for
channel 2. Check status bits for errors.
/ status (pRtdlDevHeader-gtpStatusChan2Reg
ister) if( status INP_LINK_INT_STATUS )
pRtdlDevHeader-gtinpLinkErrCount1
/ Increment Input module LINK NOT DETECTED error
count. / else / Check for these
only if link is detected. / if( status
INP_FRAME_INT_STATUS ) pRtdlDevHeader-gtinp
FrameErrCount1 / Increment Input module
FRAME error count. / if( status
INP_CRC_INT_STATUS ) pRtdlDevHeader-gtinpCr
cErrCount1 / Increment Input module CRC
error count. / return
32
RTDL Driver rtdlDrv.c IOCTL
RTDL_INPUT_SET_VME_DATA
case RTDL_INPUT_SET_VME_DATA / Write
to VME data register for the given input
channel (not valid for encoder module).
arg should contain the desired VME data. /
if( pRtdlOpenData-gtpRtdlDevHeader-gtmodule_type
RTDL_INPUT_MODULE ) / Write VME
data to the appropriate input channel. /
/ Place the channel in VME mode and halt input
module loading of data until write to VME
DATA register is complete. /
(pRtdlOpenData-gtpCommandRegister) (
INP_HALT_LOAD) / Now write the
placeholders out to the registers /
(pRtdlOpenData-gtpVmeDataHigh) (UINT8)(arg gtgt
16) (pRtdlOpenData-gtpVmeDataLow)
(UINT16)(arg 0xffff) / Now allow
Input module to load new data. /
(pRtdlOpenData-gtpCommandRegister)
(INP_HALT_LOAD) status OK
else / Can't do this to
encoder module. / errnoSet(EINVAL)
status ERROR break
33
RTDL EPICS Interface

• New Customized Record vs. Record Template
• Bi/Bo to configure/control command and status
  registers
• Li/Lo to Read/Write RTDL VME data
• Ai to Read RTDL Device data
• Waveform to Read Parameter ID List in SRAM
• A New Customized Record may replace all records
  above, clean, but
• More maintenance work when upgrading EPICS system
• A template with a group of records is flexible
  and suitable for a prototype hardware device
• It will have more records for each device

34
RTDL EPICS Interface Device Support

• Device Support
• EPICS Device Support for RTDL Input
  Moduledevice(stringin,INST_IO,devStringinRtdlInpu
  t,"RtdlInput")device(longin,INST_IO,devLiRtdlInpu
  t,"RtdlInput")device(longout,INST_IO,devLoRtdlInp
  ut,"RtdlInput")device(bi,INST_IO,devBiRtdlInput,"
  RtdlInput")device(bo,INST_IO,devBoRtdlInput,"Rtdl
  Input") EPICS Device Support for RTDL Encoder
  Moduledevice(stringin,INST_IO,devStringinRtdlEnco
  der,"RtdlEncoder")device(longin,INST_IO,devLiRtdl
  Encoder,"RtdlEncoder")device(bi,INST_IO,devBiRtdl
  Encoder,"RtdlEncoder")device(bo,INST_IO,devBoRtdl
  Encoder,"RtdlEncoder")

35
RTDL EPICS Interface Test Application
36
RTDL Master IOC Configuration
37
RTDL Software Documentations

• http//www.sns.bnl.gov/epics/timing has the
  following documents
• RTDL Driver Manual
• RTDL EPICS Device and Driver Support
• RTDL Specification
• Source Code is available in SNS CVS repository at
  ORNL

38
Summary

• RTDL Software Driver is ready for its application
  use
• A waveform support will be developed to display
  Parameter ID list (currently use d command _at_
  console)
• An ai support shall be developed if analog device
  input is supported on v206
• Upgrading current driver to support v206
• Integration with Utility module and VME-SG2 GPS
  interface module