📄 tylib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/tyLib.html - generated by refgen from tyLib.c --> <title> tyLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>tyLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>tyLib</strong> - tty driver support library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./tyLib.html#tyDevInit">tyDevInit</a>( )</b> - initialize the tty device descriptor<br><b><a href="./tyLib.html#tyDevRemove">tyDevRemove</a>( )</b> - remove the tty device descriptor<br><b><a href="./tyLib.html#tyAbortFuncSet">tyAbortFuncSet</a>( )</b> - set the abort function<br><b><a href="./tyLib.html#tyAbortSet">tyAbortSet</a>( )</b> - change the abort character<br><b><a href="./tyLib.html#tyBackspaceSet">tyBackspaceSet</a>( )</b> - change the backspace character<br><b><a href="./tyLib.html#tyDeleteLineSet">tyDeleteLineSet</a>( )</b> - change the line-delete character<br><b><a href="./tyLib.html#tyEOFSet">tyEOFSet</a>( )</b> - change the end-of-file character<br><b><a href="./tyLib.html#tyMonitorTrapSet">tyMonitorTrapSet</a>( )</b> - change the trap-to-monitor character<br><b><a href="./tyLib.html#tyIoctl">tyIoctl</a>( )</b> - handle device control requests<br><b><a href="./tyLib.html#tyWrite">tyWrite</a>( )</b> - do a task-level write for a tty device<br><b><a href="./tyLib.html#tyRead">tyRead</a>( )</b> - do a task-level read for a tty device<br><b><a href="./tyLib.html#tyITx">tyITx</a>( )</b> - interrupt-level output<br><b><a href="./tyLib.html#tyIRd">tyIRd</a>( )</b> - interrupt-level input<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library provides routines used to implement drivers for serialdevices. It provides all the necessary device-independent functions of anormal serial channel, including:<p><ul><li></li>ring buffering of input and output<li></li>raw mode<li></li>optional line mode with backspace and line-delete functions<li></li>optional processing of X-on/X-off<li></li>optional RETURN/LINEFEED conversion<li></li>optional echoing of input characters<li></li>optional stripping of the parity bit from 8-bit input<li></li>optional special characters for shell abort and system restart<p></ul><p>Most of the routines in this library are called only by device drivers.Functions that normally might be called by an application orinteractive user are the routines to set special characters, <b>ty...Set( )</b>.<p></blockquote><h4>USE IN SERIAL DEVICE DRIVERS</h4><blockquote><p>Each device that uses <b><a href="./tyLib.html#top">tyLib</a></b> is described by a data structure of type <b>TY_DEV</b>.This structure begins with an I/O system device header so that it can be addeddirectly to the I/O system's device list. A driver calls <b><a href="./tyLib.html#tyDevInit">tyDevInit</a>( )</b> toinitialize a <b>TY_DEV</b> structure for a specific device and then calls <b><a href="./iosLib.html#iosDevAdd">iosDevAdd</a>( )</b>to add the device to the I/O system.<p>The call to <b><a href="./tyLib.html#tyDevInit">tyDevInit</a>( )</b> takes three parameters: the pointer to the <b>TY_DEV</b>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 becalled when characters are added for output and the transmitter is idle. Thereafter, the driver can call the following routines to perform theusual device functions:<dl><dt><b><a href="./tyLib.html#tyRead">tyRead</a>( )</b><dd>user read request to get characters that have been input<dt><b><a href="./tyLib.html#tyWrite">tyWrite</a>( )</b><dd>user write request to put characters to be output<dt><b><a href="./tyLib.html#tyIoctl">tyIoctl</a>( )</b><dd>user I/O control request<dt><b><a href="./tyLib.html#tyIRd">tyIRd</a>( )</b><dd>interrupt-level routine to get an input character<dt><b><a href="./tyLib.html#tyITx">tyITx</a>( )</b><dd>interrupt-level routine to deliver the next output character</dl>Thus, <b><a href="./tyLib.html#tyRead">tyRead</a>( )</b>, <b><a href="./tyLib.html#tyWrite">tyWrite</a>( )</b>, and <b><a href="./tyLib.html#tyIoctl">tyIoctl</a>( )</b> are called from the driver's read,write, and I/O control functions. The routines <b><a href="./tyLib.html#tyIRd">tyIRd</a>( )</b> and <b><a href="./tyLib.html#tyITx">tyITx</a>( )</b> are calledfrom the driver's interrupt handler in response to receive and transmitinterrupts, respectively.<p>Examples of using <b><a href="./tyLib.html#top">tyLib</a></b> in a driver can be found in the source file(s) included by <b>tyCoDrv</b>. Source files are located in src/drv/serial.<p></blockquote><h4>TTY OPTIONS</h4><blockquote><p>A full range of options affects the behavior of tty devices. Theseoptions are selected by setting bits in the device option word using theFIOSETOPTIONS function in the <b><a href="./ioLib.html#ioctl">ioctl</a>( )</b> routine (see "I/O Control Functions"below for more information). The following is a list of availableoptions. The options are defined in the header file <b>ioLib.h</b>.<p><dl><dt><b>`OPT_LINE</b>'<dd>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 byteof input from the device is immediately available to readers, and the input isnot modified except as directed by other options below. In line mode, inputfrom the device is not available to readers until a NEWLINE character isreceived, and the input may be modified by backspace, line-delete, andend-of-file special characters.<dt><b>`OPT_ECHO</b>'<dd>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 wellas the input ring. If the output ring is full, the echoing is lost withoutaffecting the input.<dt><b>`OPT_CRMOD</b>'<dd>C language conventions use the NEWLINE character as the line terminatoron both input and output. Most terminals, however, supply a RETURN characterwhen the return key is hit, and require both a RETURN and a LINEFEED characterto advance the output line. This option enables the appropriate translation:NEWLINEs are substituted for input RETURN characters, and NEWLINEs in theoutput file are automatically turned into a RETURN-LINEFEED sequence.<dt><b>`OPT_TANDEM</b>'<dd>Causes the driver to generate and respond to the special flow controlcharacters CTRL-Q and CTRL-S in what is commonly known as X-on/X-off protocol. Receiptof a CTRL-S input character will suspend output to that channel. Subsequent receiptof a CTRL-Q will resume the output. Also, when the VxWorks input buffer is almostfull, 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 otherside to resume transmission.<dt><b>`OPT_7_BIT</b>'<dd>Strips the most significant bit from all bytes input from the device.<dt><b>`OPT_MON_TRAP</b>'<dd>Enables the special monitor trap character, by default CTRL-X. When this characteris received and this option is enabled, VxWorks will trap to the ROM residentmonitor program. Note that this is quite drastic. All normal VxWorksfunctioning is suspended, and the computer system is entirely controlled by themonitor. Depending on the particular monitor, it may or may not be possible torestart VxWorks from the point of interruption. The default monitor trapcharacter can be changed by calling <b><a href="./tyLib.html#tyMonitorTrapSet">tyMonitorTrapSet</a>( )</b>.<dt><b>`OPT_ABORT</b>'<dd>Enables the special shell abort character, by default CTRL-C. When this characteris received and this option is enabled, the VxWorks shell is restarted. This isuseful for freeing a shell stuck in an unfriendly routine, such as one caught inan infinite loop or one that has taken an unavailable semaphore. For moreinformation, see the<i>VxWorks Programmer's Guide: Shell. </i><dt><b>`OPT_TERMINAL</b>'<dd>This is not a separate option bit. It is the value of the option wordwith all the above bits set.<dt><b>`OPT_RAW</b>'<dd>This is not a separate option bit. It is the value of the option word withnone of the above bits set.<p>I/O CONTROL FUNCTIONSThe tty devices respond to the following <b><a href="./ioLib.html#ioctl">ioctl</a>( )</b> functions. The functionsare defined in the header <b>ioLib.h</b>.<p><dt><b>`FIOGETNAME</b>'<dd>Gets the file name of the file descriptor and copies it to the buffer referenced to by <i>nameBuf</i>:<pre> status = ioctl (fd, FIOGETNAME, &nameBuf);</pre>This function is common to all file descriptors for all devices.</dl><dl><dt><b>FIOSETOPTIONS</b>, <b>FIOOPTIONS</b><dd>Sets the device option word to the specified argument. For example, the call:<pre> status = ioctl (fd, FIOOPTIONS, OPT_TERMINAL); status = ioctl (fd, FIOSETOPTIONS, OPT_TERMINAL);</pre>enables all the tty options described above, putting the device in a "normal"terminal mode. If the line protocol (<b>OPT_LINE</b>) is changed, the inputbuffer is flushed. The various options are described in <b>ioLib.h</b>.<dt><b>FIOGETOPTIONS</b><dd>Returns the current device option word:<pre> options = ioctl (fd, FIOGETOPTIONS, 0);</pre><dt><b>FIONREAD</b><dd>Copies to <i>nBytesUnread</i> the number of bytes available to be read in thedevice's input buffer:<pre> status = ioctl (fd, FIONREAD, &nBytesUnread);</pre>In line mode (<b>OPT_LINE</b> set), the FIONREAD function actually returns the numberof characters available plus the number of lines in the buffer. Thus, if fivelines of just NEWLINEs were in the input buffer, it would return the value 10(5 characters + 5 lines).<dt><b>FIONWRITE</b><dd>Copies to <i>nBytes</i> the number of bytes queued to be output in the device'soutput buffer:<pre> status = ioctl (fd, FIONWRITE, &nBytes);</pre><dt><b>FIOFLUSH</b><dd>Discards all the bytes currently in both the input and the output buffers:<pre> status = ioctl (fd, FIOFLUSH, 0);</pre><dt><b>FIOWFLUSH</b><dd>Discards all the bytes currently in the output buffer:<pre> status = ioctl (fd, FIOWFLUSH, 0);</pre><dt><b>FIORFLUSH</b><dd>Discards all the bytes currently in the input buffers:<pre> status = ioctl (fd, FIORFLUSH, 0);</pre><dt><b>FIOCANCEL</b><dd>Cancels a read or write. A task blocked on a read or write may bereleased by a second task using this <b><a href="./ioLib.html#ioctl">ioctl</a>( )</b> call. For example, atask doing a read can set a watchdog timer before attempting the read;the auxiliary task would wait on a semaphore. The watchdog routinecan give the semaphore to the auxiliary task, which would then use thefollowing call on the appropriate file descriptor:<pre> status = ioctl (fd, FIOCANCEL, 0);</pre><dt><b>FIOBAUDRATE</b><dd>Sets the baud rate of the device to the specified argument. For example, thecall:<pre> status = ioctl (fd, FIOBAUDRATE, 9600);</pre>Sets the device to operate at 9600 baud. This request has no meaning on apseudo terminal.<dt><b>FIOISATTY</b><dd>Returns TRUE for a tty device:<pre> status = ioctl (fd, FIOISATTY, 0);</pre><dt><b>FIOPROTOHOOK</b><dd>Adds a protocol hook function to be called for each input character.<i>pfunction</i> is a pointer to the protocol hook routine which takes twoarguments of type <i>int</i> and returns values of type STATUS (TRUE orFALSE). The first argument passed is set by the user via the FIOPROTOARGfunction. The second argument is the input character. If no furtherprocessing of the character is required by the calling routine (the inputroutine of the driver), the protocol hook routine <i>pFunction</i> shouldreturn TRUE. Otherwise, it should return FALSE:<pre> status = ioctl (fd, FIOPROTOHOOK, pFunction);</pre><dt><b>FIOPROTOARG</b><dd>Sets the first argument to be passed to the protocol hook routine set byFIOPROTOHOOK function:<pre> status = ioctl (fd, FIOPROTOARG, arg);</pre><dt><b>FIORBUFSET</b><dd>Changes the size of the receive-side buffer to <i>size</i>:<pre> status = ioctl (fd, FIORBUFSET, size);</pre><dt><b>FIOWBUFSET</b><dd>Changes the size of the send-side buffer to <i>size</i>:<pre> status = ioctl (fd, FIOWBUFSET, size);</pre></dl>Any other <b><a href="./ioLib.html#ioctl">ioctl</a>( )</b> request will return an error and set the status to<b>S_ioLib_UNKNOWN_REQUEST</b>.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>tyLib.h</b>, <b>ioLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./ioLib.html#top">ioLib</a></b>, <b><a href="./iosLib.html#top">iosLib</a></b>, <b>tyCoDrv</b>,<i>VxWorks Programmer's Guide: I/O System </i><hr><a name="tyDevInit"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>tyDevInit( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>tyDevInit( )</strong> - initialize the tty device descriptor</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>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 */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine initializes a tty device descriptor according to thespecified parameters. The initialization includes allocating read andwrite buffers of the specified sizes from the memory pool,and initializing their respective buffer descriptors.The semaphores are initialized and the write semaphore is givento enable writers. Also, the transmitter start-up routine pointer is setto the specified routine. All other fields in the descriptor are zeroed.<p>This routine should be called only by serial drivers.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, orERROR if there is not enough memory to allocate data structures.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./tyLib.html#top">tyLib</a></b><hr><a name="tyDevRemove"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -