Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD1.3 / Text_Autodocs / serial.doc < prev next >

Wrap

Text File | 1992-09-12 | 20.2 KB | 537 lines

TABLE OF CONTENTS serial.device/AbortIO serial.device/BeginIO serial.device/CloseDevice serial.device/CMD_BREAK serial.device/CMD_CLEAR serial.device/CMD_FLUSH serial.device/CMD_READ serial.device/CMD_RESET serial.device/CMD_START serial.device/CMD_STOP serial.device/CMD_WRITE serial.device/OpenDevice serial.device/SDCMD_QUERY serial.device/SDCMD_SETPARAMS serial.device/AbortIO serial.device/AbortIO NAME AbortIO(ioRequest) -- abort an I/O request A1 FUNCTION This is an exec.library call. This function attempts to aborts a specified read or write request. If the request is active, it is stopped immediately. If the request is queued, it is painlessly removed. The request will be returned in the same way any completed request it. After AbortIO(), you must generally do a WaitIO(). INPUTS iORequest -- pointer to the IORequest Block that is to be aborted. RESULTS io_Error -- if the Abort succeded, then io_Error will be #IOERR_ABORTED (-2) and the request will be flagged as aborted (bit 5 of io_Flags is set). If the Abort failed, then the Error will be zero. BUGS Previous to version 34, the serial.device would often hang when aborting CTS/RTS handshake requests. This was the cause of the incorrect assumption that AbortIO() does not need to be followed by a wait for a reply (or a WaitIO()). serial.device/BeginIO serial.device/BeginIO NAME BeginIO(ioRequest),deviceNode -- start up an I/O process A1 A6 FUNCTION This is a direct function call to the device. It is intended for more advanced programmers. See exec's DoIO() and SendIO() for the normal method of calling devices. This function initiates a I/O request made to the serial device. Other than read or write, the functions are performed synchronously, and do not depend on any interrupt handling logic (or it's associated discontinuities), and hence should be performed as IO_QUICK. With some exceptions, reads and writes are merely initiated by BeginIO, and thusly return to the caller as begun, not completed. Completion is signalled via the standard ReplyMsg routine. Multiple requests are handled via FIFO queueing. One exception to this non-QUICK handling of reads and writes is for READS when: - IO_QUICK bit is set - There are no pending read requests - There is already enough data in the input buffer to satisfy this I/O Request immediately. In this case, the IO_QUICK flag is not cleared, and the request is completed by the time it returns to the caller. There is no ReplyMsg or signal bit activity in this case. INPUTS ioRequest -- pointer to an I/O Request Block of size io_ExtSerSize (see serial.i for size/definition), containing a valid command in io_Command to process, as well as the command's other required parameters. deviceNode -- pointer to the "serial.device", as found in the IO_DEVICE of the ioRequest. RESULTS io_Error -- if the BeginIO succeded, then Error will be null. If the BeginIO failed, then the Error will be non-zero. I/O errors won't be reported until the io completes. SEE ALSO devices/serial.h serial.device/CloseDevice serial.device/CloseDevice NAME CloseDevice -- close the serial port SYNOPSIS CloseDevice(deviceNode) A1 FUNCTION This is an exec call that terminates communication with the serial device. Upon closing, the device's input buffer is freed. Note that all IORequests MUST be complete before closing. If any are pending, your program must AbortIO() then WaitIO() to complete them. INPUTS deviceNode - pointer to the device node, set by Open SEE ALSO serial.device/OpenDevice serial.device/CMD_BREAK serial.device/CMD_BREAK NAME Break -- send a break signal over the serial line FUNCTION This command sends a break signal (serial line held low for an extended period) out the serial port. This is accom- plished by setting the UARTBRK bit of reg ADKCON. After a duration (user specifiable via setparams, default 250000 microseconds) the bit is reset and the signal discontinued. If the QUEUEDBRK bit of io_SerFlags is set in the io_Request block, the request is placed at the back of the write-request queue and executed in turn. If the QUEUEDBRK bit is not set, the break is started immediately, control returns to the caller, and the timer discontinues the signal after the duration is completed. Be aware that calling BREAK may affect other commands such as ABORT, FLUSH, STOP, START, etc... IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command SDCMD_BREAK io_Flags set/reset IO_QUICK per above description RESULTS Error -- if the Break succeded, then Error will be null. If the Break failed, then the Error will be non-zero. serial.device/CMD_CLEAR serial.device/CMD_CLEAR NAME Clear -- clear the serial port buffers FUNCTION This command resets the serial port's read buffer pointers. IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_CLEAR RESULTS Error -- If the Clear succeded, then io_Error will be null. If the Clear failed, then the io_Error will be non-zero. serial.device/CMD_FLUSH serial.device/CMD_FLUSH NAME Flush -- clear all queued I/O requests for the serial port FUNCTION This command purges the read and write request queues for the serial device. Flush will not affect active requests. IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_FLUSH RESULTS Error -- if the Flush succeded, then io_Error will be null. If the Flush failed, then the io_Error will be non-zero. serial.device/CMD_READ serial.device/CMD_READ NAME Read -- read input from serial port FUNCTION This command causes a stream of characters to be read in from the serial port buffer. The number of characters is specified in io_Length. The Query function can be used to check how many characters are currently waiting in the serial port buffer. If more characters are requested than are currently available, the ioRequest will be queued until it can be satisfied. The best way to handle reads is to first Query to get the number of characters currently in the buffer. Then post a read request for that number of characters (or the maximum size of your buffer). If zero characters are in the buffer, post a request for 1 character. When at least one is ready, the device will return it. Now start over with another Query. Before the program exits, it must be sure to AbortIO() then WaitIO() any outstanding ioRequests. IO REQUEST io_Message A mn_ReplyPort is required io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_READ io_Flags If the IOB_QUICK bit is set, read will try to complete the IO quickly io_Length number of characters to receive. io_Data pointer to buffer RESULTS Error -- if the Read succeded, then io_Error will be null. If the Read failed, then io_Error will be non-zero. io_Error will indicate problems such as parity mismatch, break, and buffer overrun. SEE ALSO serial.device/CMD_QUERY serial.device/SDCMD_SETPARAMS BUGS Having multiple outstanding read IORequests at any one time will probably fail. Old documentation mentioned a mode where io_Length was set to -1. If you want a NULL terminated read, use the io_TermArray instead. serial.device/CMD_RESET serial.device/CMD_RESET NAME Reset -- reinitializes the serial port FUNCTION This command resets the serial port to its freshly initialized condition. It aborts all I/O requests both queued and current, relinquishes the current buffer, obtains a new default sized buffer, and sets the port's flags and parameters to their boot-up time default values. The functions places the reset parameter values in the ioRequest block. IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_RESET RESULTS Error -- if the Reset succeded, then Error will be null. If the Reset failed, then the Error will be non-zero. serial.device/CMD_START serial.device/CMD_START NAME Start -- restart paused I/O over the serial port FUNCTION This function restarts all current I/O on the serial port by sending an xON to the "other side", and submitting a "logical xON" to "our side", if/when appropriate to current activity. IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_START RESULTS SEE ALSO serial.device/CMD_STOP serial.device/CMD_STOP serial.device/CMD_STOP NAME Stop -- pause all current I/O over the serial port FUNCTION This command halts all current I/O on the serial port by sending an xOFF to the "other side", and submitting a "logical xOFF" to "our side", if/when appropriate to current activity. IO REQUEST io_Message mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_STOP RESULTS SEE ALSO serial.device/CMD_START serial.device/CMD_WRITE serial.device/CMD_WRITE NAME Write -- send output to serial port FUNCTION This command causes a stream of characters to be written out the serial port. The number of characters is specified in io_Length, unless -1 is used, in which case output is sent until a null(0x00) is encountered. IO REQUEST io_Message must have mn_ReplyPort initialized io_Device set by OpenDevice io_Unit set by OpenDevice io_Command CMD_WRITE io_Flags Set IOF_QUICK to try quick I/O io_Length number of characters to transmit, or if set to -1 transmit until null encountered in buffer io_Data pointer to block of data to transmit RESULTS Error -- if the Write succeded, then io_Error will be null. If the Write failed, then the io_Error will be non-zero. SEE ALSO serial.device/SDCMD_SETPARAMS serial.device/OpenDevice serial.device/OpenDevice NAME OpenDevice -- Request an opening of the serial device. SYNOPSIS error = OpenDevice(SERIALNAME, unit, ioRequest, flags) D0 A0 D0 A1 D0 FUNCTION This is an exec call. Exec will search for the serial.device, and if found, will pass this call on to the device. Unless the shared-access bit (bit 5 of io_SerFlags) is set, exclusive use is granted and no other access to that unit is allowed until the owner closes it. All the serial-specific fields in the ioRequest are initialized to their most recent values (or the Preferences default, for the first time open). If support of 7-wire handshaking (i.e. RS232-C CTS/RTS protocol) is required, set the 7WIRE bit in io_SerFlags before opening the serial device. INPUTS SERIALNAME - pointer to literal string "serial.device" unit - Must be zero, or a user setable unit number. (This field is used by multiple port controllers) Zero specifies the built-in serial port. ioRequest - pointer to an ioRequest block of size io_ExtSerSize to be initialized by the serial.device. (see devices/serial.h for the definition) NOTE use of io_SerFlags (see FUNCTION above) IMPORTANT: The ioRequest block MUST be of size io_ExtSerSize ! flags - Must be zero for future compatibility RESULTS D0 - same as io_Error io_Error - If the Open succeded, then io_Error will be null. If the Open failed, then io_Error will be non-zero. io_Device - A pointer to whatever device will handle the calls for this unit. This pointer may be different depending on what unit is requested. BUGS If 7-wire handshaking is specified, this enables a timeout "feature". If the device holds off the computer for more than about 30-60 seconds, the device will return the write request with the error SerErr_TimerErr. Don't depend on this, however. If you want a timeout, set up the timer.device and wait for either timer, or serial IO to complete. On open, the serial.device allocates the misc.resource for the serial port. It does not return it until the serial.device is expunged from memory. It should return it when no more openers exist. SEE ALSO serial.device/CloseDevice devices/serial.h serial.device/SDCMD_QUERY serial.device/SDCMD_QUERY NAME Query -- query serial port/line status FUNCTION This command return the status of the serial port lines and registers. The number of unread bytes in the serial device's read buffer is shown in io_Actual. The break send & received flags are cleared by a query, and whenever a read IORequest is returned with a error in io_Error. IO REQUEST io_Message mn_ReplyPort initialized io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command SDCMD_QUERY RESULTS io_Status BIT ACTIVE FUNCTION LSB 0 --- reserved 1 --- reserved 2 high parallel "sel" on the A1000 On the A500 & A2000, "sel" is also connected to the serial port's "Ring Indicator". Be cautious when making cables. 3 low Data Set Ready 4 low Clear To Send 5 low Carrier Detect 6 low Ready To Send 7 low Data Terminal Ready MSB 8 high hardware overrun 9 high break sent (most recent output) 10 high break received (as latest input) 11 high transmit x-OFFed 12 high receive x-OFFed 13-15 --- reserved io_Actual set to count of unread input characters io_Error -- Query will always succeded. serial.device/SDCMD_SETPARAMS serial.device/SDCMD_SETPARAMS NAME SetParams -- change parameters for the serial port FUNCTION This command allows the caller to change parameters for the serial device. Except for xON-xOFF enable/disable, it will reject a setparams call if any reads or writes are active or pending. Note specifically: 1. Valid input for io_Baud is between 112 and 292000 baud inclusive; asynchronous i/o above 32KB (especially on a busy system) may be ambitious. 2. The EOFMODE and QUEUEDBRK bits of io_SerFlags can be set/reset in the io_Rqst block without a call to SetParams. The SHARED and 7WIRE bits of io_SerFlags can be used in OpenDevice calls. ALL OTHER PARAMETERS CAN ONLY BE CHANGED BY THE SetParams COMMAND. 3. RBufLen must be at least 64. 4. If not used, io_ExtFlags MUST be set to zero. 5. xON-xOFF is by default enabled. The XDISABLED bit is the only parameter that can be changed via a SetParams call while the device is active. Note that this will return the value SerErr_DevBusy in the io_Error field. xON/xOFF handshaking is inappropriate for certain binary transfer protocalls, such as Xmodem. The binary data might contain the xON (ASCII 17) and xOFF (ASCII 19) characters. 6. If trying to run MIDI, you should set the RAD_BOOGIE bit of io_SerFlags to eliminate unneeded overhead. Specifically, this skips checks for parity, x-OFF handling, character lengths other than 8 bits, and testing for a break signal. Setting RAD_BOOGIE will also set the XDISABLED bit. Note that writing data (that's already in MIDI format) at MIDI rates is easily accomplished. Using this driver alone for MIDI reads may, however, may not be reliable, due to MIDI timestamping requirements, and possibility of overruns in a busy multitasking and/or display intensive environment. 7. If you select mark or space parity (see io_ExtFlags in serial.h), this will cause the SERB_PARTY_ON bit to be set, and the setting of SERB_PARTY_ODD to be ignored. 8. For best results, set the RAD_BOOGIE flag whenever possible. See #6 for details. 9. Note that at this time parity is *not* calculated for the xON-xOFF characters. If you have a system that is picky about the parity of these, you must set your own xON-xOFF characters in io_CtlChar. IO REQUEST io_Message mn_ReplyPort initialized io_Device preset by OpenDevice io_Unit preset by OpenDevice io_Command SDCMD_SETPARAMS (0x0B) NOTE that the following fields are filled in by Open to reflect the serial device's current configuration. io_CtlChar a longword containing byte values for the xON,xOFF,INQ,ACK fields (respectively) (INQ/ACK not used at this time) io_RBufLen length in bytes of input buffer NOTE that any change in buffer size causes the current buffer to be deallocated and a new, correctly sized one to be allocated. Thusly, the CONTENTS OF THE OLD BUFFER ARE LOST. io_ExtFlags additional serial flags (bitdefs in devices/serial.h) mark & space parity may be specified here. io_Baud baud rate for reads AND writes. (See 1 above) io_BrkTime duration of break signal in MICROseconds io_TermArray ASCII descending-ordered 8-byte array of termination characters. If less than 8 chars used, fill out array w/lowest valid value. Terminators are checked only if EOFMODE bit of io_Serflags is set. (e.g. x512F040303030303 ) io_ReadLen number of bits in read word (1-8) not including parity io_WriteLen number of bits in write word (1-8) " " " io_StopBits number of stop bits (0, 1 or 2) io_SerFlags see devices/serial.h for bit equates, NOTE that x00 yields exclusive access, xON/OFF-enabled, no parity checking, 3-wire protocol and TermArray inactive. RESULTS Error -- if the SetParams succeded, then Error will be null. If the SetParams failed, then the Error will be non-zero. SEE ALSO exec/OpenDevice