VxWorks Reference Manual : Libraries
tyLib - tty driver support library
tyDevInit( ) - initialize the tty device descriptor
tyDevRemove( ) - remove the tty device descriptor
tyAbortFuncSet( ) - set the abort function
tyAbortSet( ) - change the abort character
tyBackspaceSet( ) - change the backspace character
tyDeleteLineSet( ) - change the line-delete character
tyEOFSet( ) - change the end-of-file character
tyMonitorTrapSet( ) - change the trap-to-monitor character
tyIoctl( ) - handle device control requests
tyWrite( ) - do a task-level write for a tty device
tyRead( ) - do a task-level read for a tty device
tyITx( ) - interrupt-level output
tyIRd( ) - interrupt-level input
This library provides routines used to implement drivers for serial devices. It provides all the necessary device-independent functions of a normal serial channel, including:
- ring buffering of input and output
- raw mode
- optional line mode with backspace and line-delete functions
- optional processing of X-on/X-off
- optional RETURN/LINEFEED conversion
- optional echoing of input characters
- optional stripping of the parity bit from 8-bit input
- optional special characters for shell abort and system restart
Most of the routines in this library are called only by device drivers. Functions that normally might be called by an application or interactive user are the routines to set special characters, ty...Set( ).
Each device that uses tyLib is described by a data structure of type TY_DEV. This structure begins with an I/O system device header so that it can be added directly to the I/O system's device list. A driver calls tyDevInit( ) to initialize a TY_DEV structure for a specific device and then calls iosDevAdd( ) to add the device to the I/O system.
The call to tyDevInit( ) takes three parameters: the pointer to the TY_DEV structure to initialize, the desired size of the read and write ring buffers, and the address of a transmitter start-up routine. This routine will be called when characters are added for output and the transmitter is idle. Thereafter, the driver can call the following routines to perform the usual device functions:
- tyRead( )
- user read request to get characters that have been input
- tyWrite( )
- user write request to put characters to be output
- tyIoctl( )
- user I/O control request
- tyIRd( )
- interrupt-level routine to get an input character
- tyITx( )
- interrupt-level routine to deliver the next output character
Thus, tyRead( ), tyWrite( ), and tyIoctl( ) are called from the driver's read, write, and I/O control functions. The routines tyIRd( ) and tyITx( ) are called from the driver's interrupt handler in response to receive and transmit interrupts, respectively.
Examples of using tyLib in a driver can be found in the source file(s) included by tyCoDrv. Source files are located in src/drv/serial.
A full range of options affects the behavior of tty devices. These options are selected by setting bits in the device option word using the FIOSETOPTIONS function in the ioctl( ) routine (see "I/O Control Functions" below for more information). The following is a list of available options. The options are defined in the header file ioLib.h.
- `OPT_LINE'
- Selects line mode. A tty device operates in one of two modes: raw mode (unbuffered) or line mode. Raw mode is the default. In raw mode, each byte of input from the device is immediately available to readers, and the input is not modified except as directed by other options below. In line mode, input from the device is not available to readers until a NEWLINE character is received, and the input may be modified by backspace, line-delete, and end-of-file special characters.
- `OPT_ECHO'
- Causes all input characters to be echoed to the output of the same channel. This is done simply by putting incoming characters in the output ring as well as the input ring. If the output ring is full, the echoing is lost without affecting the input.
- `OPT_CRMOD'
- C language conventions use the NEWLINE character as the line terminator on both input and output. Most terminals, however, supply a RETURN character when the return key is hit, and require both a RETURN and a LINEFEED character to advance the output line. This option enables the appropriate translation: NEWLINEs are substituted for input RETURN characters, and NEWLINEs in the output file are automatically turned into a RETURN-LINEFEED sequence.
- `OPT_TANDEM'
- Causes the driver to generate and respond to the special flow control characters CTRL-Q and CTRL-S in what is commonly known as X-on/X-off protocol. Receipt of a CTRL-S input character will suspend output to that channel. Subsequent receipt of a CTRL-Q will resume the output. Also, when the VxWorks input buffer is almost full, a CTRL-S will be output to signal the other side to suspend transmission. When the input buffer is almost empty, a CTRL-Q will be output to signal the other side to resume transmission.
- `OPT_7_BIT'
- Strips the most significant bit from all bytes input from the device.
- `OPT_MON_TRAP'
- Enables the special monitor trap character, by default CTRL-X. When this character is received and this option is enabled, VxWorks will trap to the ROM resident monitor program. Note that this is quite drastic. All normal VxWorks functioning is suspended, and the computer system is entirely controlled by the monitor. Depending on the particular monitor, it may or may not be possible to restart VxWorks from the point of interruption. The default monitor trap character can be changed by calling tyMonitorTrapSet( ).
- `OPT_ABORT'
- Enables the special shell abort character, by default CTRL-C. When this character is received and this option is enabled, the VxWorks shell is restarted. This is useful for freeing a shell stuck in an unfriendly routine, such as one caught in an infinite loop or one that has taken an unavailable semaphore. For more information, see the VxWorks Programmer's Guide: Shell.
- `OPT_TERMINAL'
- This is not a separate option bit. It is the value of the option word with all the above bits set.
- `OPT_RAW'
- This is not a separate option bit. It is the value of the option word with none of the above bits set.
I/O CONTROL FUNCTIONS The tty devices respond to the following ioctl( ) functions. The functions are defined in the header ioLib.h.
- `FIOGETNAME'
- Gets the file name of the file descriptor and copies it to the buffer referenced to by nameBuf:
status = ioctl (fd, FIOGETNAME, &nameBuf);This function is common to all file descriptors for all devices.
- FIOSETOPTIONS, FIOOPTIONS
- Sets the device option word to the specified argument. For example, the call:
status = ioctl (fd, FIOOPTIONS, OPT_TERMINAL); status = ioctl (fd, FIOSETOPTIONS, OPT_TERMINAL);enables all the tty options described above, putting the device in a "normal" terminal mode. If the line protocol (OPT_LINE) is changed, the input buffer is flushed. The various options are described in ioLib.h.
- FIOGETOPTIONS
- Returns the current device option word:
options = ioctl (fd, FIOGETOPTIONS, 0);- FIONREAD
- Copies to nBytesUnread the number of bytes available to be read in the device's input buffer:
status = ioctl (fd, FIONREAD, &nBytesUnread);In line mode (OPT_LINE set), the FIONREAD function actually returns the number of characters available plus the number of lines in the buffer. Thus, if five lines of just NEWLINEs were in the input buffer, it would return the value 10 (5 characters + 5 lines).
- FIONWRITE
- Copies to nBytes the number of bytes queued to be output in the device's output buffer:
status = ioctl (fd, FIONWRITE, &nBytes);- FIOFLUSH
- Discards all the bytes currently in both the input and the output buffers:
status = ioctl (fd, FIOFLUSH, 0);- FIOWFLUSH
- Discards all the bytes currently in the output buffer:
status = ioctl (fd, FIOWFLUSH, 0);- FIORFLUSH
- Discards all the bytes currently in the input buffers:
status = ioctl (fd, FIORFLUSH, 0);- FIOCANCEL
- Cancels a read or write. A task blocked on a read or write may be released by a second task using this ioctl( ) call. For example, a task doing a read can set a watchdog timer before attempting the read; the auxiliary task would wait on a semaphore. The watchdog routine can give the semaphore to the auxiliary task, which would then use the following call on the appropriate file descriptor:
status = ioctl (fd, FIOCANCEL, 0);- FIOBAUDRATE
- Sets the baud rate of the device to the specified argument. For example, the call:
status = ioctl (fd, FIOBAUDRATE, 9600);Sets the device to operate at 9600 baud. This request has no meaning on a pseudo terminal.
- FIOISATTY
- Returns TRUE for a tty device:
status = ioctl (fd, FIOISATTY, 0);- FIOPROTOHOOK
- Adds a protocol hook function to be called for each input character. pfunction is a pointer to the protocol hook routine which takes two arguments of type int and returns values of type STATUS (TRUE or FALSE). The first argument passed is set by the user via the FIOPROTOARG function. The second argument is the input character. If no further processing of the character is required by the calling routine (the input routine of the driver), the protocol hook routine pFunction should return TRUE. Otherwise, it should return FALSE:
status = ioctl (fd, FIOPROTOHOOK, pFunction);- FIOPROTOARG
- Sets the first argument to be passed to the protocol hook routine set by FIOPROTOHOOK function:
status = ioctl (fd, FIOPROTOARG, arg);- FIORBUFSET
- Changes the size of the receive-side buffer to size:
status = ioctl (fd, FIORBUFSET, size);- FIOWBUFSET
- Changes the size of the send-side buffer to size:
status = ioctl (fd, FIOWBUFSET, size);Any other ioctl( ) request will return an error and set the status to S_ioLib_UNKNOWN_REQUEST.
tyLib.h, ioLib.h
tyLib, ioLib, iosLib, tyCoDrv, VxWorks Programmer's Guide: I/O System
tyDevInit( ) - initialize the tty device descriptor
STATUS tyDevInit ( TY_DEV_ID pTyDev, /* ptr to tty dev descriptor to init */ int rdBufSize, /* size of read buffer in bytes */ int wrtBufSize, /* size of write buffer in bytes */ FUNCPTR txStartup /* device transmit start-up routine */ )
This routine initializes a tty device descriptor according to the specified parameters. The initialization includes allocating read and write buffers of the specified sizes from the memory pool, and initializing their respective buffer descriptors. The semaphores are initialized and the write semaphore is given to enable writers. Also, the transmitter start-up routine pointer is set to the specified routine. All other fields in the descriptor are zeroed.
This routine should be called only by serial drivers.
OK, or ERROR if there is not enough memory to allocate data structures.
tyDevRemove( ) - remove the tty device descriptor
STATUS tyDevRemove ( TY_DEV_ID pTyDev /* ptr to tty dev descriptor to remove */ )
This routine removes an existing tty device descriptor. It releases the read and write buffers and the descriptor data structure.
OK, or ERROR if expected data structures are not found
tyAbortFuncSet( ) - set the abort function
void tyAbortFuncSet ( FUNCPTR func /* routine to call when abort char received */ )
This routine sets the function that will be called when the abort character is received on a tty. There is only one global abort function, used for any tty on which OPT_ABORT is enabled. When the abort character is received from a tty with OPT_ABORT set, the function specified in func will be called, with no parameters, from interrupt level.
Setting an abort function of NULL will disable the abort function.
N/A
tyLib, tyAbortSet( )
tyAbortSet( ) - change the abort character
void tyAbortSet ( char ch /* char to be abort */ )
This routine sets the abort character to ch. The default abort character is CTRL-C.
Typing the abort character to any device whose OPT_ABORT option is set will cause the shell task to be killed and restarted. Note that the character set by this routine applies to all devices whose handlers use the standard tty package tyLib.
N/A
tyLib, tyAbortFuncSet( )
tyBackspaceSet( ) - change the backspace character
void tyBackspaceSet ( char ch /* char to be backspace */ )
This routine sets the backspace character to ch. The default backspace character is CTRL-H.
Typing the backspace character to any device operating in line protocol mode (OPT_LINE set) will cause the previous character typed to be deleted, up to the beginning of the current line. Note that the character set by this routine applies to all devices whose handlers use the standard tty package tyLib.
N/A
tyDeleteLineSet( ) - change the line-delete character
void tyDeleteLineSet ( char ch /* char to be line-delete */ )
This routine sets the line-delete character to ch. The default line-delete character is CTRL-U.
Typing the delete character to any device operating in line protocol mode (OPT_LINE set) will cause all characters in the current line to be deleted. Note that the character set by this routine applies to all devices whose handlers use the standard tty package tyLib.
N/A
tyEOFSet( ) - change the end-of-file character
void tyEOFSet ( char ch /* char to be EOF */ )
This routine sets the EOF character to ch. The default EOF character is CTRL-D.
Typing the EOF character to any device operating in line protocol mode (OPT_LINE set) will cause no character to be entered in the current line, but will cause the current line to be terminated (thus without a newline character). The line is made available to reading tasks. Thus, if the EOF character is the first character input on a line, a line length of zero characters is returned to the reader. This is the standard end-of-file indication on a read call. Note that the EOF character set by this routine will apply to all devices whose handlers use the standard tty package tyLib.
N/A
tyMonitorTrapSet( ) - change the trap-to-monitor character
void tyMonitorTrapSet ( char ch /* char to be monitor trap */ )
This routine sets the trap-to-monitor character to ch. The default trap-to-monitor character is CTRL-X.
Typing the trap-to-monitor character to any device whose OPT_MON_TRAP option is set will cause the resident ROM monitor to be entered, if one is present. Once the ROM monitor is entered, the normal multitasking system is halted.
Note that the trap-to-monitor character set by this routine will apply to all devices whose handlers use the standard tty package tyLib. Also note that not all systems have a monitor trap available.
N/A
tyIoctl( ) - handle device control requests
STATUS tyIoctl ( TY_DEV_ID pTyDev, /* ptr to device to control */ int request, /* request code */ int arg /* some argument */ )
This routine handles ioctl( ) requests for tty devices. The I/O control functions for tty devices are described in the manual entry for tyLib.
In line protocol mode (OPT_LINE option set), the FIONREAD function actually returns the number of characters available plus the number of lines in the buffer. Thus, if five lines consisting of just NEWLINEs were in the input buffer, the FIONREAD function would return the value ten (five characters + five lines).
OK or ERROR.
VARARGS2 - not all requests include an arg.
tyWrite( ) - do a task-level write for a tty device
int tyWrite ( TY_DEV_ID pTyDev, /* ptr to device structure */ char * buffer, /* buffer of data to write */ int nbytes /* number of bytes in buffer */ )
This routine handles the task-level portion of the tty handler's write function.
The number of bytes actually written to the device.
tyRead( ) - do a task-level read for a tty device
int tyRead ( TY_DEV_ID pTyDev, /* device to read */ char * buffer, /* buffer to read into */ int maxbytes /* maximum length of read */ )
This routine handles the task-level portion of the tty handler's read function. It reads into the buffer up to maxbytes available bytes.
This routine should only be called from serial device drivers.
The number of bytes actually read into the buffer.
tyITx( ) - interrupt-level output
STATUS tyITx ( TY_DEV_ID pTyDev, /* pointer to tty device descriptor */ char * pChar /* where to put character to be output */ )
This routine gets a single character to be output to a device. It looks at the ring buffer for pTyDev and gives the caller the next available character, if there is one. The character to be output is copied to pChar.
OK if there are more characters to send, or ERROR if there are no more characters.
tyIRd( ) - interrupt-level input
STATUS tyIRd ( TY_DEV_ID pTyDev, /* ptr to tty device descriptor */ char inchar /* character read */ )
This routine handles interrupt-level character input for tty devices. A device driver calls this routine when it has received a character. This routine adds the character to the ring buffer for the specified device, and gives a semaphore if a task is waiting for it.
This routine also handles all the special characters, as specified in the option word for the device, such as X-on, X-off, NEWLINE, or backspace.
OK, or ERROR if the ring buffer is full.