5 A GRAPHICAL COMMAND INTERFACE TO DRIVERS

lcudrvTk is a Tcl/Tk [5] based utility for accessing VLT device drivers at command level.

It allows direct access to device drivers without passing intermediate software layers. This means that there are no checks whether commands are allowed in a certain context. Even commands which might damage connected devices (motors etc.) are not inhibited.

Normally, when you intend to give I/O commands like open, close or ioctl interactively and directly to the driver, you have to do a lot of typing work from the VxWorks shell. lcudrvTk does effectively the same, but all your drivers with their corresponding command- and error-codes are available in menus, so that almost nothing has to be typed. Since all codes are presented by their literals, they need normally not to be looked up in a manual.

5.2 Starting from the Command Line

lcudrvTk is started by giving its name in a terminal window, possibly with the option `-v' for `verbose':

The terminal window will still be used as standard-output, but inputs to the VxWorks shell via the terminal are not possible.

5.3 The Configuration File for lcudrvTk

It is read once immediately after start-up. The configuration file must have the name

and it is searched in the current directory or in the config subdirectories of the standard VLT areas (MODROOT, INTROOT, VLTROOT). [1]

The contents of a configuration file in the current directory has therefore priority over possible files in the other directories.

If a configuration-file is found then it is processed, otherwise a default configuration is used.

The contents of this file consists of several lines, each beginning with an uppercase keyword:

LCU pollux set the default LCU name to `pollux'
DRIVER mcon add `mcon' to the Drivers menu
DRIVER ampl add `ampl' to the Drivers menu
DRIVER tim add `tim' to the Drivers menu

Also "DRIVER lqs" can be added, although lqs (LCU Q-Server) is not a hardware driver in that sense. But the lqs module provides at least a useful Tools menu.

5.4 The Control Panel

A short help text is displayed in the box at the bottom when the mouse pointer is located on a specific element.

5.4.1 Buttons and Entries

· < > - - Operations on the command history buffer for the `Shell Cmd' entry

· Device and Argument - name of the device and the argument used when an item in the 'Commands' or 'Tools' menu is clicked. See the corresponding menu description in section 5.4.2 for more information.

· VxWorks - a menu of the most frequently used VxWorks shell commands

5.4.2 The Menu Bar

Several actions can be initiated by selecting an item of the available menus. Some of them have always the same contents, others are generated dynamically dependent an other selections.

For convenience the menus can be 'teared off' and placed anywhere on the screen to have them constantly available. This is especially useful for the Tools and Commands menus. ¹

Almost all items in the File menu pop up a file selection box, where a filename can be selected, with which one of the following actions can be performed:

· Load Server: Load necessary server code to the target (see section 5.8)

· Begin/End/Exec Macro: Record or execute sequences of actions (see section 5.5)

· Exec Script: The selected file is executed as a script under the LCU's VxWorks shell

· Load Binary: The selected file is loaded and linked as a binary object module into the LCU

· Write:`Argument' bytes from the selected file are written to `Device' through the write function

· Read: `Argument' bytes are read from `Device' to the selected file through the read function

The Drivers menu is generated from the configuration file contents (see section 5.3). Every time a new driver is selected, the menus for Tools, Commands and Errors are re-generated for this driver. Also the entry fields will be setup accordingly.

The Tools menu contains all tool-functions which are defined for the driver. These are normal functions which are included in the driver's object module and are normally (but not necessarily) only used for test-purposes, e.g. to display status information. They can take up to one argument, de

pending on the functions declaration either the device name from the `Device' entry, its unit number (e.g. 2 for `/xxx2') or a general argument from the `Argument' entry. See section 5.6 concerning how this menu is generated and section 5.7.1 for which kind of argument is applied.

The Commands menu is a cascaded menu of commands available for the driver. If one of them is selected then a corresponding ioctl control command is send to the LCU, applying the device stated in the `Device' entry and an optional argument stated in the `Argument' entry. Some of the commands require arguments, some not. Refer to the corresponding user-manual to determine the number and format of argument for a specific command.²
As an exception, the first item sends the contents of the `Shell Cmd' entry directly to the LCU.
See section 5.6 concerning how this menu is generated.
If the VxWorks shell refuses to execute a command and outputs an error message like "unknown symbol", then maybe the server code is not loaded. See section 5.8.

The Errors menu gives a list of errors defined for the selected driver. No actions are connected to this menu, it serves only to look up a returned error-code. ³
See section 5.6 concerning how this menu is generated.

The Help item pops up a window with the VLT manual page browser, where informations about all VLT functions are available.

5.5 Recording and Executing Macros

· Begin Macro - Pops up a file selection box. The name of a file must be given where the macro shall be recorded in.

· End Macro - Closes the opened file. The macro can now be (re)executed.

· Exec Script - Macros are normal VxWorks shell scripts, and can therefore be executed with this item. It pops up a file selection box for a specific macro/script-file. Exec Macro can only execute the last recorded macro.

Every action initiated and sent to the LCU between Begin Macro and End Macro is recorded.The macro feature can therefore be useful to create setup-scripts for devices.

If lcudrvTk is not logged in to a LCU, the actions performed are only recorded as macro, otherwise they are also executed immediately.

5.6 Where lcudrvTk gets the Menu Information from

7 All information about a driver is obtained from its interface header files.

Every time a new driver named xxx is selected from the Drivers menu, its header files are parsed `on the fly' to get the required information, namely:

As described in section 5.3, the Drivers menu is generated from a special configuration file.

The header files are searched in the current directory or - according to the normal VLT standards - in the include subdirectories of the VLT areas (MODROOT, INTROOT, VLTROOT). [1]

5.7 Guidelines and Restrictions for Driver Header Files

If you don't intend to use lcudrvTk for your driver, you can skip this section. Otherwise:

7 lcudrvTk requires specific rules, which interface header files should follow!

The interface header files of a driver are parsed by lcudrvTk when that driver is selected. Therefore their contents should be arranged in a certain way in order not to confuse lcudrvTk when it is interpreting the information. These rules are `natural', no keywords are required.

5.7.1 lcudrvTk `s Rules for xxx.h

Each function declaration, which looks like the following examples, is regarded as a tool-function and therefore included in the menu:

· No commas between the parentheses (i.e. `void' or exactly one parameter)

· If (a part of) the name matches the strings `name' or `Name', then it indicates that this functions takes the device name string as parameter, which is therefore taken from the `Device' entry (see section 5.4.1).

· If (a part of) the name matches the strings `unit' or `axis', then it indicates that this functions takes the unit-number of the device as parameter, which is therefore derived from the `Device' entry (e.g. `/xxx2' yields a 2). Initial upper case letters are also allowed here (`Unit' or `Axis').

· any other contents of the formal parameter declaration indicates that this function does not act on a specific device and takes therefore the `Argument' entry as parameter.

Declarations not matching these rules are ignored and omitted from the Tools menu. That should be the case for the mandatory functions xxxDrv(...) and xxxDevCreate(...), which are also declared in this header file but are no tool-functions.

5.7.2 lcudrvTk `s Rules for xxxCommands.h

The driver command-literals are arranged in a cascaded menu. The first level menu represents command-groups, while the second level menus contain the commands included in each group. The levels are generated from command-group-comments and command-macro-definitions respectively.

/*
* Group 1 Commands
*/
#define xxxCMD_SOMETHING        127
#define xxxCMD_SOMETHING_ELSE   128

/*
* Group 2 Commands
*/
#define xxxCMD_READ_X     154
#define xxxCMD_WRITE_X    281

/*
** This is not a command-group, but any other kind of comment
*/
typedef struct { ... };   /* ignored */

The command-group-comments must begin with " * " (<space><asterisk><space>, no TABs!). All matching lines are appended to the first level menu.

The command-macro-definitions must begin with `#define xxxCMD_' (One <space> after define), the rest of the macro is appended to the second level menu of that group. The number (it must be a single number, no expression!) is stored internally and also shown in the menu.

Other comments in this file, which shall NOT be interpreted as command-group-comments, must not begin with ` * `, but for instance with `**', otherwise they would also be included in the menu. Other macro-definitions, which shall not be included in the menus, must not begin with the shown sequence.

5.7.3 lcudrvTk `s Rules for xxxErrors.h

The entries for the Errors menu are taken from xxxErrors.h and - additionally - from lcudrvPublic.h.

The driver error-literals are arranged in a dummy-menu only to have a list of possible error-codes.

Every macro-definition in this file, which begins with `#define xxxERROR_'⁴ (One <space> after define), is included in the menu. The number (it must be a single number, no expression!) is stored internally (but currently not used) and also shown in the menu.

Other macro-definitions, which shall not be included in the menus, must not begin with the shown sequence.

5.8 lcudrvTkUtil - The LCU Server Module for lcudrvTk

When sending an I/O command like ioctl (from the Commands menu), read or write, lcudrvTk expects that the functions contained in the VxWorks object module lcudrvTkUtil are loaded on the target LCU. This module is not loaded automatically when starting lcudrvTk. Instead it can be loaded during the LCU boot procedure by including the appropriate command in the boot-script.

Alternatively it can be loaded or re-loaded on the fly with the item `Load Server' in the File menu. The module is then searched in the current directory or - according to the normal VLT standards - in the bin subdirectories of the VLT areas (MODROOT, INTROOT, VLTROOT). [1]

This requires that the path-names to the root-areas are the same on the WS as seen from the LCU.

5.9 Known Problems

· There is no short help text for the menu-bar items. This should be added when the panel-editor supports menu-bars.

In some early Tk4 versions it might be necessary to use the middle mouse button to click in tear-off menus, since the left button does not work properly.

In some special cases the argument format cannot be handled by lcudrvTk, e.g. when an ioctl-command needs an argument by value and not by reference through a pointer, or complicated structs. However, structs can be passed in `binary' format as integers (up to 8) by specifying multiple arguments, which must then be separated by commas.

An automatic translation of error-codes into their literals is currently not implemented.

⁴

CCS and LCC require that error-macros begin with `xxxERR_'. For historical reasons all existing drivers do not obey this convention but use `xxxERROR_' instead. Maybe both will be supported by lcudrvTk.