| |
|
|
|
7 REFERENCE lcudrv/lculog
7.1 lcudrv Errors Reference
The following list shows all common driver errors as defined in lcudrvPublic.h. If appropriate, they should be used in every driver instead of defining the same error-codes again.
lculog has no specific errors defined.· lcudrvERROR_ACCESS_CONFLICT
The open mode conflicts with the open modes of already existing channels or the requested action is not allowed with this open mode.
· lcudrvERROR_CHANNEL_NOT_OPEN
The requested channel is not open. Severe internal driver problem, e.g. corrupted DCT.
· lcudrvERROR_NO_CHANNEL
No more channel to a device is available or invalid channel number (obsolete, not used).
· lcudrvERROR_TIMEOUT
The call is timed-out because access to the device was pending for longer than the driver timeout parameter on a semaphore.
7.2 Functions Reference
The following sections contain - in alphabetical order - the manual pages for the functions and macros included in the programmatic interface of the modules:
#include "lcudrv.h"
int lcudrvCheckAccess(const lcudrvDCT_ENTRY *dct,
int maxChannels,
int channel,
int access,
lcudrvDEVICE_HEADER **header)
This function checks if the passed channel number is valid and
if the channel is open. Additionally it is checked whether the
access rights are sufficient for the open-mode of the channel.
If the access is confirmed then the pointer to the device header
(i.e. the top of the device descriptor) connected to the channel
is returned in the provided variable.
dct - pointer to the driver's DCT (Driver Channel Table)
maxChannels - maximum number of channels in driver's DCT
channel - channel number to check [0..maxChannels]
access - access rights to be checked with the open-mode,
binary or-ed combination of:
lcudrvOPEN_READONLY - read-only-mode access allowed
lcudrvOPEN_SHARED - shared-mode access allowed
lcudrvOPEN_EXCLUSIVE - exclusive access allowed
lcudrvOPEN_TEST - test access allowed
header <OUT> - Address of the device header connected to the channel
lcudrvOK - function terminated successfully
lcudrvERROR_INVALID_ARGUMENT - channel number out of range
lcudrvERROR_CHANNEL_NOT_OPEN - channel not opened
lcudrvERROR_ACCESS_CONFLICT - insufficient access rights
----- A code fragment from xxxIoctl(channel, command, argument) -----
xxxCOMMAND_DESCRIPTOR *cmd; // 'cmd->access' contains access rights
xxxDEVICE_DESCRIPTOR *device;
lcudrvDEVICE_HEADER *header;
...
status = lcudrvCheckAccess(xxxDCT,xxxMaxChannels,channel,cmd->access,&header);
if (status != lcudrvOK) return(status); // --> access is not allowed
device = (void *)header; // header-address is equal to descriptor-address
...
status = cmd->handler(device, argument); // exec command on this device
#include "lcudrv.h"
int lcudrvCheckChannel(const lcudrvDCT_ENTRY *dct,
int maxChannels,
int channel)
This function checks if the passed channel number is valid
and if the channel is open.
dct - pointer to the driver's DCT (Driver Channel Table)
maxChannels - maximum number of channels in driver's DCT
channel - channel number to check
lcudrvOK - function terminated successfully
lcudrvERROR_INVALID_ARGUMENT - channel number out of range
lcudrvERROR_CHANNEL_NOT_OPEN - channel not opened
lcudrvCheckDev,
lcudrvCheckDevDriver,
lcudrvCheckDevName,
lcudrvCheckDevBaseAddrA16,
lcudrvCheckDevBaseAddrA24,
lcudrvCheckDevProbe,
lcudrvCheckDevReturnOK
- Inline functions to check device installation parameters
#define DEV_PREFIX <device-name-prefix>
#define FNAME <device-install-function-name>
#include "lcudrvCheckDev.h"
int lcudrvCheckDevDriver(int driverNumber)
int lcudrvCheckDevName(const char *devName, int maxUnits, int *unit)
int lcudrvCheckDevBaseAddrA16(void *baseAddrA16, int simBytes,
char **localAddrA16)
int lcudrvCheckDevBaseAddrA24(void *baseAddrA24, int simBytes,
char **localAddrA24)
int lcudrvCheckDevProbe(void *probeAddr)
int lcudrvCheckDevReturnOK(const char *devName)
All these function shall be used from inside a device-specific
installation function (xxxDevCreate). They are declared as
"static __inline__" so that the code will be incorporated into the
caller. They log any errors using the functions of the lculog module.
lcudrvCheckDevDriver - checks if a driver is installed for that device.
The `driverNumber' is as returned by `iosDrvInstall'.
lcudrvCheckDevName - checks the device-name and returns the unit
number in `unit', e.g. `1' for "/xxx1". It must not be greater
or equal to `maxUnits'.
lcudrvCheckDevBaseAddrA16 - converts a VMEbus-address in the short
address space into a local address as seen from the CPU.
If `baseAddrA16' is 0xffffffff, then `simBytes' are allocated
in main memory rather than using the real device space.
lcudrvCheckDevBaseAddrA24 - converts a VMEbus-address in the standard
address space into a local address as seen from the CPU.
If `baseAddrA24' is 0xffffffff, then `simBytes' are allocated
in main memory rather than using the real device space.
lcudrvCheckDevProbe - checks if the given address is valid.
lcudrvCheckDevReturnOK - logs that device installation is OK and
always returns lcudrvOK.
All functions return lcudrvOK on success, or the appropriate error
code of the detected failure condition (lcudrvERROR_...).
As shown in SYNOPSIS, the macros `DEV_PREFIX' and `FNAME' must be
defined before including this header.
Unlike other files in `lcudrv', this requires the module `lculog',
not for loading, but for compilation of the drivers that use it.
The main purpose is to avoid code duplication in the device-specific
device installation functions.
#define DEV_PREFIX "/acro"
#define FNAME "acroDevCreate"
#include "lcudrvCheckDev.h"
int status;
status = lcudrvCheckDevName(devName, acroMaxDevices, &unit);
if (status != lcudrvOK)
return status;
status = lcudrvCheckDevBaseAddrA16(baseAddrA16, ... , &localBase);
if (status != lcudrvOK)
return status;
status = lcudrvCheckDevProbe(localBase);
if (status != lcudrvOK)
return status;
This routine performs the actions to close a channel to a driver.
dct - pointer to the driver's DCT (Driver Channel Table)
maxChannels - maximum number of channels in driver's DCT
channel - channel number to close
lcudrvOK - successful completion
lcudrvERROR_INVALID_ARGUMENT - channel number out of range
lcudrvERROR_CHANNEL_NOT_OPEN - channel not opened
lcudrvDevice,
lcudrvBCHG, lcudrvBCLR, lcudrvBSET, lcudrvBTST,
lcudrvGETB, lcudrvGETW, lcudrvGETL,
lcudrvPUTB, lcudrvPUTW, lcudrvPUTL
- Macros for direct hardware access
#include "lcudrvDevice.h"
void lcudrvBCHG(int bitNumber, volatile unsigned char *byteAddr)
void lcudrvBCLR(int bitNumber, volatile unsigned char *byteAddr)
void lcudrvBSET(int bitNumber, volatile unsigned char *byteAddr)
int lcudrvBTST(int bitNumber, volatile unsigned char *byteAddr)
unsigned char lcudrvGETB(volatile unsigned char *addr)
unsigned short lcudrvGETW(volatile unsigned short *addr)
unsigned long lcudrvGETL(volatile unsigned long *addr)
void lcudrvPUTB(volatile unsigned char *addr, unsigned char value)
void lcudrvPUTW(volatile unsigned short *addr, unsigned short value)
void lcudrvPUTL(volatile unsigned long *addr, unsigned long value)
lcudrvBCHG - Change a bit (0..7) at the specified location
lcudrvBCLR - Clear a bit (0..7) at the specified location
lcudrvBSET - Set a bit (0..7) at the specified location
lcudrvBTST - Test a bit (0..7) at the specified location
lcudrvGETB - Read a byte (8 bit) from the specified location
lcudrvGETW - Read a word (16 bit) from the specified location
lcudrvGETL - Read a longword (32 bit) from the specified location
lcudrvPUTB - Write a byte (8 bit) to the specified location
lcudrvPUTW - Write a word (16 bit) to the specified location
lcudrvPUTL - Write a longword (32 bit) to the specified location
The parameters for the macros will be casted to the shown types.
Therefore the compiler cannot check if correct types are passed.
lcudrvBCHG, lcudrvBCLR, lcudrvBSET have no return value;
lcudrvBTST returns the status of the tested bit (0 or 1);
lcudrvGETB, lcudrvGETW, lcudrvGETL return the requested value;
lcudrvPUTB, lcudrvPUTW, lcudrvPUTL have no return value;
Following compilation macros must be defined:
__GNUC__ - set by the GNU C compiler
CPU_FAMILY == MC680X0 - set by "vxWorks.h" upon the macro 'CPU'
The use of these macros can make code more efficient but less portable!
At present they can only be used with GNU-gcc and with 68K-CPUs.
lcudrvErrorGet - get error message string from an error code.
Returns a pointer to the string,
or NULL if `errorCode' is undefined.
lcudrvPrintError - print error message for an error code.
Prints the corresponding error-string to stdout,
or a special message if `errorCode' is undefined.
lcudrvErrorGet:
pointer to the string - if function terminated successfully
NULL - if `errorCode' is undefined.
lcudrvPrintError:
lcudrvOK - if function terminated successfully
lcudrvERROR - if `errorCode' is undefined.
Creates and initializes the Driver Channel Table (DCT) of a driver.
Memory for the table is allocated from the pool.
dct <OUT> - address of a pointer to the driver's DCT
maxChannels <IN> - maximum number of channels in driver's DCT
#include "lcudrv.h"
int lcudrvInitDevice(char *name,
int drvNumber,
struct lcudrvDEVICE_HEADER *header)
Installs a device and initializes the mandatory part (which is used by
lcudrv and VxWorks) of a Device Descriptor.
name - device name
drvNumber - driver number associated to the device
header - pointer to the lcudrv-header in the Device Descriptor
lcudrvOK - successful completion
lcudrvERROR_DEVICE_EXISTS - device exists already
lcudrvERROR_INVALID_DEVICE - device name invalid (too long)
The Device Descriptor may contain other device-specific fields which
are not initialized by this function.
#include "lcudrv.h"
int lcudrvOpen(lcudrvDEVICE_HEADER *device,
const char *remainder,
int mode,
lcudrvDCT_ENTRY *dct,
int maxChannels,
int *channel)
This routine performs the actions to open a channel to a driver.
When the routine returns with an error status then the calling driver
should reject the corresponding user open call.
device - pointer to the descriptor header of the requested device
remainder - remainder of the device name; should be blank
mode - open mode, specifiying the access to the device:
lcudrvOPEN_READONLY - implies no restriction
(channel is opened in any case)
lcudrvOPEN_SHARED - shared access to the device
(channel is opened if not already in exclusive mode)
lcudrvOPEN_EXCLUSIVE - exclusive access to the device
(channel is opened if not in exclusive or shared mode)
lcudrvOPEN_TEST - force access to the device
(channel is opened if not already in test mode)
dct - pointer to the driver's DCT (Driver Channel Table)
maxChannels - maximum number of channels in driver's DCT
channel - <OUT> channel number (> 0) if successful, else -1
lcudrvOK - successful completion
lcudrvERROR_INVALID_DEVICE - remainder not blank
lcudrvERROR_ACCESS_CONFLICT - open mode not consistent
lcudrvERROR_NO_MORE_CHANNEL - no more channel available
lcudrvERROR_INVALID_OPEN_MODE - open mode not defined
Tool to test whether the specified address exists. Useful to check
whether a device is installed at that VMEbus address.
address - address to be checked (by a read access)
'lcudrvTk' allows direct access to VLT device drivers at command level.
Available tools, commands and errors of the driver are collected from
its interface header files and arranged in menus for easy access.
It facilitates work as keyboard-typing is replaced by mouse-clicks,
the functionality, however, remains the same.
MENUBAR:
* File: File-related actions:
- Load Server: Load necessary server code to the target
- Load Binary: Load and link a binary object module
- Exec Script: Execute a script or macro under the LCU's shell
- Begin Macro: Every command sent is then stored in a file
- End Macro: End macro-recording and close the macro-file
- Exec Macro: Execute the most recent macro
- Write: Write 'argument' bytes from host-file to device
- Read: Read 'argument' bytes from device to host-file
- Quit
* Drivers: The available tools, commands and errors of the selected
driver will be read from the driver's header files.
The entry fields will be setup according to the driver.
The contents of this menu can be changed with the config-file.
* Tools: A menu of tools available for the driver.
Selection of a tool will send a line of the form
"<Tool> <DeviceName | UnitNumber | Argument-Entry>".
The applied argument depends on the tool's declaration:
- None if declared with "void"
- Device-entry as string if declared with "name"
- UnitNumber extracted from device-entry for "unit" or "axis"
- else general argument from the Argument-entry
* Commands: A cascaded menu of commands available for the driver.
Selection of a command will send a line of the form
"<Function> <Device>,<Command#>,<Argument>".
<Direct command> will send the 'Shell Cmd'-entry.
* Errors: A menu of errors defined for the selected driver.
No actions are connected to this menu.
* Help:
- Info: Show lcudrvTk's version
- Extended Help: Invokes the VLT man-page browser
For convenience the menus can be 'teared off' with the middle button
and placed anywhere on the screen.
ENTRIES:
The <Esc> key can be used to move the input-focus to the next entry.
* LCU Name: nodename of the target LCU.
* Device: name of the used device when an item in the
'Commands' or 'Tools' menu is clicked.
* Argument: dto., used argument(s).
Some of the commands and tools require arguments, some not.
Refer to the corresponding user-manual to determine the number
and format of argument for a specific command. 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
by reference thru 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.
* Shell Cmd: direct command to send to the VxWorks shell.
The keys <Enter> and Cursor <Up> <Down> have special bindings.
BUTTONS:
* LCU Login/out: Connect/disconnect to the LCU's shell via rlogin
* Trace on/off: Toggle trace logs on/off
* Debug on/off: Toggle debug logs on/off
* Cancel: Cancel a running shell command, restart the shell
* Reboot: Reset the system, connection will get lost
* Exec: Execute the given command under the VxWorks shell
* < > -: Operations on the command history buffer
lcudrvTk.config - Configuration file, contains driver list
Consists of several lines, each beginning with a keyword (upper case):
DRIVER <driver-name> (adds driver to the menu)
LCU <lcu-name> (use lcu-name as default)
File is searched in the directories given by the variable 'cfgPath':
1. The current dir
2. $MODROOT/config or ../config if MODROOT is undefined
3. $INTROOT/config
4. $VLTROOT/config
If not found then a default configuration is used.
lcudrvTkUtil - server code running on target
The file is not loaded automatically. If not already there (can be
checked with "moduleShow") then should be loaded explicitly with
the command "Load Server" from the File-menu.
File is searched in the directories given by the variable 'svrPath':
1. The current dir
2. $MODROOT/bin or ../bin if MODROOT is undefined
3. $INTROOT/vw/bin
4. $VLTROOT/vw/bin
If the selected driver is 'xxx' then the following files are needed:
xxx.h - Contains tools declarations
Tool-functions must begin with "xxx" and must be
declared with one parameter.
xxxCommands.h - Contains command number declarations
First level headings must begin with " * ",
Command-literals must begin with "#define xxxCMD_"
xxxErrors.h - Contains error number declarations
lcudrvPublic.h - Contains common error number declarations
Error-literals must begin with "#define xxxERROR_"
Files are searched in the directories given by the variable 'drvPath':
1. The current dir
2. $MODROOT/include or ../include if MODROOT is undefined
3. $INTROOT/vw/include
4. $VLTROOT/vw/include
It is required that the module 'lcudrvTkUtil' is loaded and linked
on the target-LCU. ioctl, write and read operations are performed
using the functions in this module.
The loading can be done with the 'ld' command from the VxWorks shell
or with lcudrvTk itself, using 'Load Server' or 'Load Binary' from
the file-menu.
lcudrvTkUtil(3),
panel(1) [for implementation]
VxWorks Reference Manual
LCU Driver Development Guide (Doc. No. VLT-MAN-ESO-17210-0375)
int lcudrvTkIoctl(char *devName, int req, int arg, ...)
int lcudrvTkWrite(char *devName, char *hostFileName, int nBytes)
int lcudrvTkRead(char *devName, char *hostFileName, int nBytes)
The functions in this file work together with lcudrvTk. They must be
loaded and linked on the target-LCU and are invoked by lcudrvTk, which
runs on the host-system, to issue commands to drivers.
lcudrvTkIoctl - Opens a channel to devName, issues an ioctl with
req and a pointer to arg(s), closes the channel.
argN are optional and appended to arg to form an array.
The pointer to this array is passed to ioctl.
lcudrvTkWrite - Reads hostFileName into memory, opens a channel to
devName and writes to it, closes the channel.
hostFileName must be NFS-mounted under the same name.
lcudrvTkRead - Opens a channel to devName, reads from it and writes
the data to hostFileName, closes the channel.
hostFileName will be CREATED!
hostFileName must be NFS-mounted under the same name.
lcudrvTkIoctl - The value placed in the arg-pointer by ioctl.
lcudrvTkWrite - The number of bytes written.
lcudrvTkRead - The number of bytes read.
The parameter passed to ioctl is always a pointer to the argument(s).
Ioctl-commands which require the argument passed by value do not work.
// #define lculogOPTION_NO_MACROS // to inhibit macro-expansion
#include "lculog.h"
void lculogVersion(void);
void
LCU_LOG_error("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
void
LCU_LOG_warning("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
void
LCU_LOG_log("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
void
LCU_LOG_trace("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
void
LCU_LOG_debug("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
void
LCU_LOG_intr("constant format string",
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
int
lculogMsg(const char * severity,
const char * fmtstr,
int arg1, int arg2, int arg3, int arg4, int arg5, int arg6);
int LCU_trace(void);
int LCU_debug(void);
int LCU_intr(void);
int lculogTask(void);
void lculogFdSet(int fd);
int lculogFdGet(void);
int lculogLog(void);
lculogVersion prints the module version to stdout.
The log-functions should be called according to the message-severity:
LCU_LOG_error - for severe errors when a function cannot be continued
LCU_LOG_warning - for critical conditions which may cause malfunctions
LCU_LOG_log - for normal informational messages
LCU_LOG_trace - for messages which traces the flow of a task
LCU_LOG_debug - for output of debugging information
LCU_LOG_intr - dto. inside periodic interrupt handlers
Input parameters are the same as for logMsg().
A severity indicator is prepended, a newline appended to the message.
The above function are normally macros, so they can be incorporated
into the callers code to reduce function-call overhead.
But the use of normal functions is also possible.
The selection which method to use is given with a macro definition
before including lculog.h (see SYNOPSIS).
Note: When using macros, the first parameter MUST be a string constant,
NOT a pointer to a string!
Hint: When a log was issued via a macro then the severity indicator is
shown in upper case (e.g. WARN), otherwise in lower case (warn).
All of these logging functions use a message-queue to a dedicated
logging task. Logging from interrupt-level is therefore allowed.
lculogMsg - called by the above macros/functions
lculogTask - code for an independent task. When it is spawned
then the VxWorks log-task is bypassed for lcu-logs.
lculogFdSet - set the channel number to output logs to.
Only on channel at a time is possible.
(Affects only lculogTask)
lculogFdGet - get the channel number to output logs to.
lculogLog - obsolete, replaced by lculogTask.
Some of the severity levels can be turned on or off individually by
setting a corresponding variable to TRUE resp. FALSE. Their default
values are shown below:
lculogDisTRACE - Disabled (enable only for test purposes)
lculogDisDEBUG - Disabled (enable only for test purposes)
lculogDisINTR - Disabled (enable only for test purposes)
lculogDisable - Enabled (controls all severities)
To switch some of the flags for test purposes on/off one can use:
LCU_trace - to toggle lculogDisTRACE on/off
LCU_debug - to toggle lculogDisDEBUG on/off
LCU_intr - to toggle lculogDisINTR on/off
LCU_trace, LCU_debug, LCU_intr return the new enable-state,
lculogMsg returns the same as logMsg (the number of bytes written),
lculogTask returns never or ERROR in case of an installation error,
all other functions have no return-value.
The format string must normally be a constant string.
Casting of arguments is necessary for other types than int.
Passing of pointers to volatile entities (e.g. local strings) does
not work as expected, because formatting is done in the context of
the logging-task! Pointers to static or global string are OK.
The following macros can be defined BEFORE including lculog.h:
lculogOPTION_MACROS - LCU_LOG_... are macros (default)
lculogOPTION_NO_MACROS - LCU_LOG_... are normal external functions
lculogOPTION_EXCLUDE_ALL - Calls to LCU_LOG_... will not be compiled
(this requires OPTION_MACROS)
lculogOPTION_EXCLUDE_DBG - LCU_LOG_trace/warning/intr are not compiled
(this requires OPTION_MACROS)
DEBUG - causes OPTION_EXCLUDE_DBG if not(!) defined
One problem when excluding log-calls from compilation:
If some variables are used only for the log-call then the compiler
will issue a warning ("unused variable")!
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|