[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

TABLE OF CONTENTS

serial.device/AbortIO
serial.device/BeginIO
serial.device/CloseDevice
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_BREAK
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_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/SDCMD_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("serial.device", unit, ioRequest, flags)
       D0                  A0              D0    A1         D1

	BYTE OpenDevice(STRPTR, ULONG, struct IOExtSer *, ULONG);

   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, use the serial.device/SDCMD_SETPARAMS command.
	This feature should also be specified at inital OpenDevice() time.

   INPUTS
       "serial.device"	- 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 default 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,
			   and zeroed (with the exeptions as noted)!
       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, a timeout "feature" is enabled.
	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.   This code can force a specified device to try and
	expunge.  Of course, if the device is in use nothing will happen:

	#include "exec/types.h"
	#include "exec/execbase.h"
	#include "proto/exec.h"

	void FlushDevice(char *);
	extern struct ExecBase *SysBase;

	void main()
	{
		FlushDevice("serial.device");	/* or parallel.device */
	}

	/*
	 * Attempts to flush the named device out of memory.
	 * If it fails, no status is returned; examination of
	 * the problem will reveal that information has no
	 * valid use after the Permit().
	 */
	void FlushDevice(name)
	char  *name;
	{
	struct Device *result;

	    Forbid();
	    if( result=(struct Device *)FindName(&SysBase->DeviceList,name) )
		RemDevice(result);
	    Permit();
	}


   SEE ALSO
	serial.device/CloseDevice
	serial.device/SDCMD_SETPARAMS
	devices/serial.h


serial.device/SDCMD_BREAK                             serial.device/SDCMD_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. For the built-in port,
       This is accomplished by setting the UARTBRK bit of regisrer 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/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.  The buffer may be any multiple of
	64 bytes.
    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.
   10. 7WIRE (CTS/RTS) handshake is bi-directional.  The external side
	is expected to drop CTS several character times before the external
	buffer is full.  The Amiga will drop RTS several character times
	before the Amiga's buffer is full.


   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




[Back to Amiga Developer Docs]