CAPIDEV(4)

NAME
capidev - CAPI device driver for C4B

SYNOPSIS
device kcapimgr
device capidev

options CAPIDEV_LOG_LEVEL="1"

DESCRIPTION
The capidev pseudo device driver handles the interface between the kernel CAPI manager and user space CAPI applications. The starting point for these applications is the CAPI character device directory entry /dev/capi20. All valid operations on this character special file are translated into function calls to the CAPI manager. The results are sent back to the calling user space application. The CAPI device can be opened multiple times, so multiple CAPI applications may run concurrently.

capidev can be directly compiled into the kernel binary by specifying the configuration line of section SYNOPSIS in the kernel configuration file. But it is also possible to compile capidev as a separate kernel module and load it on demand or even at system startup. Compiling it as as separate kernel module is the preferred method.

  Options supported by the driver
The capidev driver supports the following compile time option.

Note: The option is also recognized when compiling the driver as a separate kernel loadable module.

CAPIDEV_LOG_LEVEL="1"
    If there is a problem with the driver or an application, it may be required to let the driver produce debugging output. There are currently five levels defined for the logging level of the capidev driver. When a string is to be printed within the driver code and the corresponding level of the print command is less than or equal to the currently active logging level, the output goes to the console (or wherever kernel output is configured to go to). Every line of output contains an isolated letter that resembles the logging level of the message. The following values may be set as the logging level. The default value is 1, so errors are always printed. The letter after the logging level is the letter that is inserted within log messages of the respective level.

    LOG_ALWAYS (0, A)
        Print out only messages that cannot be suppressed. But beware that this level suppresses regular error messages. So it is normally not useful to set the logging level to 0.

    LOG_ERROR (1, E)
        Print out messages about errors. These errors are not related to e.g. CAPI error result values. Instead misbehaviour of drivers or applications is normally signaled as an error. The logging level should always be 1 or higher.

    LOG_INFO (2, M)
        Print out informational messages (and also messages for lower levels). This level produces a little bit more output than setting only the LOG_ERROR level. It triggers the output of some informational messages.

    LOG_TRACE (3, T)
        Print out messages for the tracing level. This triggers some messages when a CAPI message is handled (or not) or an application is registered or released.

    LOG_DEBUG (4, D)
        Print out messages for the debugging level. If this level is set, all logging messages the driver can produce are enabled. This is normally used for debugging the driver, to see if it works correctly or where some error occurs.

    The logging level may also be set by the sysctl() system call. The capidev driver registers a sysctl variable named capi.capidev.loglevel. This variable may be modified at any time after loading the driver. This is normally the best way to change the logging level.

    If it is necessary to enable logging messages for the startup phase of the capidev driver, one can set the kernel environment variable capi.capidev.loglevel in the file /boot/loader.conf the same way as the sysctl variable.

    So it is normally never needed to directly compile in a special default logging level into the capidev driver module.

  Sysctl variables registered by the driver
Besides the logging level the capidev driver registers some other sysctl variables. All but the logging level are read-only, just the loging level may be modified.

capi.capidev.version
    The version number of the capidev driver module.

capi.capidev.loglevel
    The logging level variable was already mentioned before. It shows the current setting of the logging level and may be changed to produce more or less diagnostic output.

capi.capidev.apps_registered
    This variable shows the current number of user space CAPI applications registered at the CAPI manager through the capidev driver. Its value is always updated when a new application registers or another performs a capi20_release().

capi.capidev.open_file_descriptors
    Similar to the number of registered applications this variable counts the number of open file descriptors to the CAPI device /dev/capi20. Usually every registered CAPI application must open the CAPI device as the first operation. The CAPI registration is performed thereafter. So it is possible that the device is opened but no application is in fact registered. As a conclusion this value will always be greater than or equal to the number of registered applications.

  Supported kernel environment variables
The capidev driver supports the following kernel environment variables. Such variables are only accessible in kernel space. The command kenv provides a method to print and modify the current content of the kernel environment. The best way to persistently set a kernel environment variable to a specific value is to place variable assignments into the file /boot/loader.conf.

capi.capidev.loglevel="1"
    This variable initializes the logging level of the capidev driver on startup. The possible values are already mentioned in the paragraph Options supported by the driver.

capi.capidev.devowner
    When the /dev/capi20 device is created, capidev must provide a user id for the ownership of the device entry. By default the user id 0 for root is specified. If this kernel environment variable is set to a different numerical user id, this value will be used to set the owner of the device.

capi.capidev.devgroup
    Similar to the user id capidev must also specify a group id for the ownership of the device entry to create. This variable may be set to different group id than the default of 0 for wheel.

capi.capidev.devmode
    By default the /dev/capi20 device is created with read and write permissions for the owner and the group assigned to the device entry. This kernel environment variable may be set to a different numerical value. The value must computed just like the numerical permissions in a call to chmod.

  Using the IOCTL interface to C4B
As mentioned before capidev implements the interface between the kernel CAPI manager and user space CAPI applications. An application may use this interface directly but, it is usually more convenient to use the (shared) library interface (see capi20(3)). The library libcapi20 does itself use the IOCTL interface of the CAPI device driver internally and provides a nicer function interface to CAPI applications.

If an application wants to use the IOCTL interface to CAPI the first operation is to open a new file descriptor to the CAPI character device /dev/capi20. This is not equivalent to the CAPI_REGISTER operation, but it is a necessary prerequisite. The resulting file descriptor will be used for all later CAPI operations.

All CAPI operations except for CAPI_PUT_MESSAGE, CAPI_GET_MESSAGE and CAPI_RELEASE are performed by IOCTL calls. This is true for CAPI_REGISTER, CAPI_GET_MANUFACTURER and all others.

The CAPI_RELEASE operation is special. It is simply performed by closing the file descriptor to the CAPI character device.

If a user process wants to register multiple CAPI applications, it must open the CAPI device multiple times and on every resulting file descriptor it must perform the CAPI_REGISTER IOCTL command.

As mentioned before the operations CAPI_PUT_MESSAGE and CAPI_GET_MESSAGE are not done by IOCTLs. CAPI_PUT_MESSAGE is performed by the write() system call. It is important that a CAPI message is always written in a single write() call. If the message is a Data-B3-Request, the data block must be written by the same call as the CAPI message it belongs to. This may be accomplished by copying the message and its data block into a combined buffer. But the most efficient way is to use the writev() function call. This function takes multiple data blocks as arguments but sends them within a single system call to the kernel.

Similarly the CAPI_GET_MESSAGE operation must be done by a single read() system call. The buffer specified must be large enough to hold at least a CAPI message and a Data-B3 block of the maximum length. A buffer size of 3KB will be sufficient (1KB maximum CAPI message size, 2KB maximum data block size). It is not supported to first read the message size word and thereafter the rest of the message. In each single read() system call a complete CAPI message is returned. If it does not fit into the buffer specified, the surplus bytes of the message are discarded, including the data block possibly belonging to the message.

  IOCTLs supported by the driver
All CAPI operations except CAPI_PUT_MESSAGE, CAPI_GET_MESSAGE and CAPI_RELEASE are performed through IOCTL system calls to the CAPI character device. The parameter structure and identifier definitions for them are located in the header file capi_bsd.h. The following paragraphs describe the IOCTLs supported by capidev.

C4BIOC_CAPI_REGISTER
    This IOCTL command is used to perform the CAPI operation CAPI_REGISTER. The corresponding parameter structure must be initialized with the application registration parameters according to the CAPI specification. On successful return the structure will contain the CAPI manager assigned application id.

C4BIOC_CAPI_GET_MANUFACTURER

C4BIOC_CAPI_GET_VERSION

C4BIOC_CAPI_GET_SERIAL_NUMBER

C4BIOC_CAPI_GET_PROFILE

C4BIOC_CAPI_GET_CTLR_DRIVER_INFO
    All the above IOCTL commands are used to get some information about installed controllers and about the CAPI manager. The parameter structures passed to the respective system call must be filled with the input parameters. On successful return the output fields of the structures are filled with the requested data. The semantics of the input and output parameters are the same as for the shared library interface (see capi20(3)) and for the kernel CAPI application interface (see kcapi(9)).

C4BIOC_CAPI_RESET_CTLR
    The input parameter structure for this IOCTL command is a little bit more complicated than for the other ones. The structure itself only contains the controller number, the number of data blocks to download and a pointer to an array. This array is held outside the structure and in this array there are even more pointers to the real data blocks. So the input for the reset operation is a rather deep tree structure compared to other IOCTL commands. But all data blocks specified in this tree are sent to the addressed controller.

    Usually this command is used to provide an active board with its firmware and configuration data.

ERRORS
All system calls to the CAPI character device return a direct function result value of 0 for success and -1 to indicate an error. In the later case the CAPI result value is stored into errno. The possible CAPI result values are defined in the CAPI specification as the parameters Info, Reason and ReasonB3 (see http://www.capi.org). Identifiers for them and some additional result values specific to the c4b implementation are defined in the header files capi_result.h and capi_bsd.h.

FILES

/dev/capi20
    The CAPI device directory entry.

SEE ALSO
capi20(3), c4b(4), kcapimgr(4), kcapi(9). CAPI Association e.V., Common ISDN API v2.0 4th Edition, June 2001, see http://www.capi.org.

HISTORY
The capidev pseudo device driver first appeared as an add-on to FreeBSD 4.6.

AUTHORS
This manual page and the CAPI device driver were written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
The capidev device driver should be tested on and ported if necessary to other flavours of BSD than FreeBSD, e.g. NetBSD or OpenBSD.