trabiodrv(4)

NAME
trabiodrv - device driver for digital I/O devices of TRAB board.

SYNOPSIS
#include <linux/trabio.h>

DESCRIPTION
The driver consists of three distinct parts each controlling its own I/O devices. The parts are as follows:

DIP switch
    There is a 4 bit DIP switch on the TRAB board. The driver provides a simple polling interface to this input device. The following two methods are provided to read the current status:
    (a) Character device interface using /dev/dip_switch as the name. Each read() call returns exactly 1 byte of data with the current status of the switches in the lower 4 bits. Switch 1 status is encoded in bit 0, switch 2 - in bit 1 ... switch 4 - in bit 3.
    (b) /proc filesystem interface using /proc/driver/dip_switch as the name. Reading from this file returns one line of text, each dip switch bit encoded as ASCII '0' or '1', separated by blanks, terminated by newline. The string is ASCII representation of the value returned by the read() call of the /dev/dip_switch i.e. reading the '0x4' from device results the output string "0 1 0 0" to be read from /proc/driver/dip_switch.

Digital Inputs, interrupt driven
    There are six inputs using interrupt capable GPIO pins:
    * 4 x Keys
    * stop position contact
    * fill level sensor
    Two interfaces are provided:
    (a) Character device interface using two device nodes: /dev/digital_in and /dev/key_in as names. They have different minor numbers (see below) so unrelated processes can operate independently.
    For each read() system call the /dev/digital_in device returns exactly 1 byte of data with the current status of the stop position contact and the fill level sensor encoded in the 2 low order bits. The stop position contact is encoded in the bit 1 and the fill level sensor in bit 0. It is possible to use select() or poll() in the application to wait for any status change of these inputs.
    For each read() system call the /dev/key_in device returns exactly 1 byte of data with the current status of the 4 keys in the low order bits (1 = pressed). It is possible to use select() or poll() in the application to wait for any status change of the keys.
    (b) /proc filesystem interface using /proc/driver/digital_in and /proc/driver/key_in as names. Reading from /proc/driver/digital_in returns one line of text, each switch encoded as ASCII '0' or '1', separated by blanks, terminated by newline. Reading from /proc/driver/key_in returns one line of text, each key encoded as ASCII '0' (not pressed) or '1' (pressed), separated by blanks, terminated by newline.

Digital outputs
    There are six output pins:
    * motor control
    * status LED
    * 4 x keyboard LED
    Two interfaces are provided:
    (a) Character device interface using two devices /dev/digital_out and /dev/key_out as names. The device nodes have two separate minor numbers (see below) so that unrelated processes can operate independently.
    Each write() system call to the /dev/digital_out device uses only the first byte of data, and drops all additional characters. The least significant bit (bit 0) of the byte is interpreted as the state of the status LED to be set (0 - off, 1 - on). Bit 1 of the byte is nterpreted as the state of the motor control. The current state is latched. When booting, all switches are turned off (reset).
    For each read() system call the /dev/digital_out returns one byte of data with the current status of the motor control and status LED encoded in low order bits. The motor control is encoded in bit 1 and the status LED in bit 0.
    Each write() system call the /dev/key_out device shall uses only the first byte of data, and drops all additional characters. The 4 low order bits (1 = on) are used to control the keyboard LEDs. The current state is latched. When booting, all LEDs are set to off.
    (b) /proc filesystem interface using /proc/driver/digital_out and /proc/driver/key_out as names. Writing a line of text to /proc/driver/digital_out sets or resets the motor control and status LED bits. The line must have the form M N\n, with M and N '0' or '1'; other data format is rejected by the driver (discarded). Writing a line of text to /proc/driver/key_out turns on or off the keyboard LEDs. The line must have the form R S T U, with R,S,T and U are '0' or '1'; other data format is rejected by the driver. Reading from /proc/driver/digital_out or /proc/driver/key_out returns the current state of the corresponding port pins.

The device nodes have the major number of 242 and minor numbers are constructed as follows:
   Name                 Minor number
   ---------------      ------------
   /dev/dip_switch      0
   /dev/digital_in      1
   /dev/key_in          2
   /dev/key_out         3
   /dev/digital_out     4

FUNCTIONS
In general, the trabiodrv driver's functions behave as used with other drivers. A function return value of (-1) indicates an error, in which case an appropriate error code can be found in errno.
The trabiodrv driver supports the following driver calls:

open()
    The minor number of the device node indicates the I/O device (see above).
    Error codes:
    ENXIO - no I/O device correspond to this minor number.

close()
    Error codes:
    none

read()
    Error codes:
    ENOMEM - size of the provided buffer is less than 1 byte.
    EINTR - the call was interrupted by a signal.

write()
    The write() function is only implemented for the /dev/key_out and /dev/digital_out devices. For the other devices it always returns (-1) with errno set to ENOSYS.
    Error codes:
    EINVAL - the size argument is less than 1 (zero).

ioctl()
    The ioctl() is not supported by the trabiodrv driver. On any attempt to issue a non-standard (not one of FIOCLEX, FIONCLEX or FIONBIO) IOCTL command, (-1) will be returned with errno set to ENOTTY.

poll()
    The poll() function implemented by the trabiodrv driver lets the application wait for an event to occur on the file descriptor corresponding to the open path to a I/O device. The function is implemented for all the I/O devices.

    For the /dev/dip_switchdevice, poll() always returns (POLLIN | POLLRDNORM) without blocking, which means that the device is ready for reading.

    For the /dev/key_out and /dev/digital_out devices, poll() always returns (POLLIN | POLLRDNORM | POLLWRNORM | POLLOUT) without blocking, which means that the device is always ready for reading and writing.
    For the /dev/key_in and /dev/digital_in devices, poll() returns (POLLIN | POLLRDNORM) when one of the events defined in the section DESCRIPTION above happens. For these devices, poll() (and select()) may block. To clear the indication of an event, the application has to call the read() function of the device.