Applies To:
  • CitectSCADA 5.41
Summary:
Until now, the only means available to perform (Citect level) driver debugging has been the Citect Kernel "debug" command which may be used to display data transmitted to and from an I/O Device. This required each Citect driver to have specific code added to enable such a trace. 

Solution:
The Driver Trace Utility is a Citect Kernel extension which can be used to display the actual commands and other information issued to a driver by Citect. The primary objective of having this extension is to assist in the debugging of drivers, an example being the investigation of the failure of a driver to fully initialise. This trace utility is implemented in Citect itself, and is thus available regardless of what trace code has been implemented in any particular driver.

INI Parameters

The INI parameters associated with the Driver Trace Utility reside in the [Debug] section of the CITECT.INI file, and are as follows:

DriverTrace=[OFF | CMDS | VER[BOSE] | PORT]

where:

OFF - Turns the DriverTrace off.
CMDS

- Turns the DriverTrace on, but does not display the contents of thepDcb->Buffer. Note: specific driver commands must be enabled with theDriverTraceMask INI parameter (or associated Kernel command).
VER[BOSE]

- Turns the DriverTrace on, and includes the contents of the pDcb->Buffer in the display. Note: specific driver commands must be enabled with the DriverTraceMask INI parameter (or associated Kernel command).

 

The default is OFF.

DriverTracePORT=<name> - allows traces to be limited to a particular driver port. DriverTracePORT=* will trace all ports. The default is all ports.

Note: PORT option is not supported prior to version 5.50.

DriverTraceMask=<mask>

where:

<mask> is a 4 byte hexadecimal number which is a bit mask used to either include or exclude driver commands from the DriverTrace. The driver commands and their values are as follows:

Command Bit Position Number
CTDRV_INIT 00000001 0
CTDRV_OPEN 00000002 1
CTDRV_INIT_CHANNEL 00000004 2
CTDRV_INIT_UNIT 00000008 3
CTDRV_READ 00000010 4
CTDRV_WRITE 00000020 5
CTDRV_CONVERT 00000040 6
CTDRV_CANCEL 00000080 7
CTDRV_CPU 00000100 8
CTDRV_DATABASE 00000200 9
CTDRV_STOP_UNIT 00000400 10
CTDRV_STOP_CHANNEL 00000800 11
CTDRV_CLOSE 00001000 12
CTDRV_FORMAT 00002000 13
CTDRV_STATS 00004000 14
CTDRV_DEBUG 00008000 15
CTDRV_INFO 00010000 16
CTDRV_STATUS_UNIT 00020000 17
CTDRV_INIT_CARD 00040000 18
CTDRV_UPDATE_INFO 00080000 19
CTDRV_UI_READ 00100000 20
CTDRV_UI_WRITE 00200000 21
CTDRV_EXIT 00400000 22
CTDRV_LINE_STATUS 00800000 23
CTDRV_SEND_BREAK 01000000 24
CTDRV_REINIT_CHANNEL 02000000 25
CTDRV_SET_PARAM 04000000 26
CTDRV_GET_PARAM 08000000 27
CTDRV_OPEN_PORT 10000000 28
CTDRV_CLOSE_PORT 20000000 29
CTDRV_STATUS_DISCONNECT 40000000 30

 

Thus the <mask> used to include only the CTDRV_OPEN, CTDRV_INIT_UNIT and CTDRV_READ commands would be: 0000001A. The default <mask> is FFFFFFFF.

DriverTraceElements=<num_elements>

where:

<num_elements> is the maximum number of pDcb->Buffer elements to be displayed. This value will be limited by the value of pDcb->Point.UnitCount. The default is 256. This parameter can be used to limit the printouts for drivers with large blocking values.

For example:


[Debug]
DriverTracePort=Port01
DriverTrace=Ver
Note: Setting the port (and other) limitations first eliminates initial logging of all ports and possible higher CPU burst.

 

Kernel Commands

The new Kernel command associated with the Driver Trace Utility is:

DRIVERTRACE [OFF | CMDS | VER[BOSE] | PORT=Y | MASK=XXXXXXXX]

where:

BLANK - returns the drivertrace settings
OFF - Turns the DriverTrace off.
CMDS

- Turns the DriverTrace on, but does not display the contents of thepDcb->Buffer. Note: specific driver commands must be enabled with theDriverTraceMask INI parameter (or associated Kernel command).
VER[BOSE]

- Turns the DriverTrace on, and includes the contents of the pDcb->Buffer in the display. Note: specific driver commands must be enabled with the DriverTraceMask INI parameter (or associated Kernel command).
PORT=<name> - allows traces to be limited to a particular driver port. PORT=* will trace all ports.

Note: PORT option is not supported prior to version 5.50.
MASK=XXXXXXXX  - sets the DriverTrace mask as described in section 2.1.

For example:


Drivertrace Port=Port01
Drivertrace Ver
Note: Setting the port (and other) limitations first eliminates initial logging of all ports and possible higher CPU burst.

 

Keyboard Hot-Keys

The following hot-keys are available with the Driver Trace utility:

CTRL-Q - log trace output to the Citect Kernel window as well as the SYSLOG.DAT file.
CTRL-S - log trace output to the SYSLOG.DAT file only.

 

The default behaviour is to log trace output to both the Citect Kernel window and the SYSLOG.DAT file.

Displayed Fields

The following fields are displayed by the Driver Trace utility in the Citect Kernel Main window and are written to the SYSLOG.DAT file:

DCB Address   

  The lower 5 digits of the hex address of the DCB are displayed.

System Time   

  in hh:mm:ss:msec format based on the PC system start time.

Driver Command   

  the driver command (pDcb->Command) number and name.

Port Name   

  the port name

Unit Name   

  the I/O device name

Debug Level   

  the debug level (only displayed with the CTDRV_DEBUG command)

Unit Type   

  the unit type (pDcb->Point.UnitType) (only displayed with some driver commands)

Unit Address   

- the unit address (pDcb->Point.UnitAddress) (only displayed with some driver commands)

Unit Count   

  the unit count (pDcb->Point.UnitCount) (only displayed with some driver commands)

Raw Type   

  the raw type (pDcb->Point.RawType) (only displayed with read and write commands: CTDRV_READ, CTDRV_UI_READ, CTDRV_WRITE, CTDRV_UI_WRITE)

Elapsed Time   

  the time in milliseconds taken by the driver to process the DCB.

Driver Error   

  the driver error code (pDcb->ErrDriver) (only displayed with some driver commands).

DCB Buffer   

  the contents of pDcb->Buffer which are format displayed dependent on the pDcb->Point.RawType of the data, except for RDT_DIGITAL data which is displayed as hex bytes. The contents of pDcb->Buffer are only displayed with the driver read and write commands (CTDRV_READ, CTDRV_UI_READ, CTDRV_WRITE, CTDRV_UI_WRITE).

Sample Output

A sample output from the Driver Trace utility is shown below:

  1. -> 2FD44 46.030 Cmd: 00 CTDRV_INIT ,UNITEL
  2. <-2FD44 46.030 Cmd: 00 CTDRV_INIT ErrDriver 0 (0x0) and took 0ms
  3. -> 2FD44 46.031 Cmd: 16 CTDRV_INFO ,UNITEL
  4. <-2FD44 46.031 Cmd: 16 CTDRV_INFO ErrDriver 0 (0x0) and took 0ms
  5. .....
  6. -> 90D95 23.924 Cmd: 04 CTDRV_READ ,UNITEL, Port: Port1, Unit: IODevice
  7. | 90D95 23.924 UnitType: 0 (0x0), UnitAddr: 0 (0x0), UnitCount: 4, RawType: INTEGER
  8. <+90D95 24.043 Cmd: 04 CTDRV_READ ErrDriver 0 (0x0) and took 118ms
  9. <+90D95 24.043 UnitType: 0 (0x0), UnitAddr: 0 (0x0), UnitCount: 4, RawType: INTEGER
  10. <+90D95 24.043 000: 78 34 90 69
  11. -> 2FE14 24.425 Cmd: 09 CTDRV_DATABASE ,UNITEL, Port: Port1, Unit: IODevice
  12. | 2FE14 24.425 UnitType: 0 (0x0), UnitAddr: 0 (0x0), UnitCount: 4
  13. <-2FE14 24.425 bit_size=16 maxread=12 maxwrite=4 ErrDriver 0 (0x0)
  14. -> A0D95 24.425 Cmd: 04 CTDRV_READ ,UNITEL, Port: Port1, Unit: IODevice
  15. | A0D95 24.425 UnitType: 0 (0x0), UnitAddr: 0 (0x0), UnitCount: 4, RawType: INTEGER
  16. <+A0D95 24.524 Cmd: 04 CTDRV_READ ErrDriver 0 (0x0) and took 98ms
  17. <+A0D95 24.524 UnitType: 0 (0x0), UnitAddr: 0 (0x0), UnitCount: 4, RawType: INTEGER
  18. <+A0D95 24.524 000: 78 34 90 69
  19. -> 2FEBC 31.920 Cmd: 10 CTDRV_STOP_UNIT ,UNITEL, Port: Port1, Unit: IODevice
  20. <-2FEBC 31.920 Cmd: 10 CTDRV_STOP_UNIT ErrDriver 0 (0x0) and took 0ms
  21. -> 2FEBC 31.920 Cmd: 11 CTDRV_STOP_CHANNEL,UNITEL, Port: Port1, Unit: N/A
  22. <-2FEBC 31.920 Cmd: 11 CTDRV_STOP_CHANNEL ErrDriver 0 (0x0) and took 0ms
  23. -> 2FEBC 31.920 Cmd: 12 CTDRV_CLOSE ,UNITEL
  24. <-2FEBC 31.920 Cmd: 12 CTDRV_CLOSE ErrDriver 0 (0x0) and took 0ms
  25. -> 2FEBC 31.920 Cmd: 22 CTDRV_EXIT ,UNITEL
  26. <-2FEBC 31.920 Cmd: 22 CTDRV_EXIT ErrDriver 0 (0x0) and took 0ms

Notes

The first 2 columns are :

- Message direction, '>' in, '<' back and lower 5 hex digits of the DCB request and 
- Time is seconds and milliseconds
- Numbers  e.g., "18 (0x12)" are the decimal then the same hexidecimal value

Message direction indicators

-> To driver
|  Extra info going into the driver call
<- Returned in serial time, Reply() or action done during call
<+ Returned asynchronously, i.e. Reply() occurred after the command

Not all commands require the Reply() function to be used.

Due to the asynchronous nature of driver requests, it is quite possible several CTDRV_READ commands will be issued before a Reply(). Thus in some instances, the '<' trace will NOT be immediately below the request.

The DCB address can be used to match up a reply with the original request when significant time delay occurs.

The '<' time - ElapsedTime +/- 1 will equal the timestamp on the original request.

Due to the CPU overheads when tracing calls to the driver, the user must be careful not to let the CPU usage go to 100%.

When tracing lots of tags, it makes no sense to have data streaming in the kernel window; this consumes lots of CPU; disable this with the CNTRL S character and let the trace only go to the syslog.dat file. Alternatively, use the CITECT.INI file parameters to enable the trace and don’t display the Kernel window at all.

 
Keywords:
 

Attachments