Section: User Commands (1)
Updated: April, 2005
Index
spd - a serial port server for C or Java clients.
spd is a non-threaded server that is based round the poll() function, which handles all events on TCP connections and serial ports. It's sole configuration requirements are to set the port it listens on and to define the serial ports it is allowed to provide access to. The port is defined via the command line -p option and defaults to 16001. Serial ports are defined in the spd.conf configuration file. See below for format and location. Socket handling uses the skt module. Poll list manipulation is managed by the fdlist module. Both are part of the libenviron.a package.
Every TCP/IP connection and every open serial port has a session control block. The purpose of the session is to associate entries in the poll list with their context information. The context for a TCP/IP connection is a reference to any serial port it may have opened. The context for a serial port session is contained in the control block referenced by its session. Each session is indexed by its file fd and records the type of file (TCP connection or PORT) it is related to. TCP sessions that have opened ports contain a reference to the PORT session. PORT sessions contain a reference to the associated serial port control block.
TCP connections are added to the poll list as they are accepted and removed from the list as they are closed. A TCP session is created when the connection is accepted and destroyed when it is closed. A TCP connection that has opened a serial port remains open as long as the port is in use and its session references the PORT session as long as the port is open. A TCP session exists longer than a PORT session and may open and close more than one port during its existence.
TCP sessions requesting a list of available ports, the server status or controlling the server, e.g. stopping it, never have an associated serial port.
When a serial port is opened a PORT session is created, its fd is added to the poll list and its reference is placed in the controlling TCP session. When the port is closed it is removed from the poll list, its PORT session is unlinked from the controlling TCP session and the PORT is then destroyed. The session for an open port references the port's control block.
There is a serial port control block associated with each serial port defined in the configuration file. Each control block exists for the whole life of the spd process. It holds the port context data and a pair of circular buffers to buffer the port's input and output data streams. Client commands that change the serial port settings record the changes in the control block, where they can be retrieved by an
spc status
command, and apply them directly to the port. All other commands merely change control block settings or move data to or from the buffers. All data transfers between the buffers and serial port take place asynchronously and independently of commands received from the client. As a result the query command is provided to allow the client to discover how full the buffers are. The Java sleep() method and C sp_sleep() function interfaces use this when waiting for transfers to complete. It is also available as the Java query() method or the C sp_query() function to client programs that implement their own flow control.
spd.conf The configuration file. It may be placed in /etc , /usr/local/etc , or the current directory at the time spd is started. Possible locations are searched in the order shown above.
Lines starting with a # are comments and ignored. Blank lines are ignored. The first two significant lines take the form:
devices=nn
maxmessage=llll
where nn is the number of serial ports defined below and llll is the biggest message that spd expects to send or receive. This value sets the size of the input and output buffers associated with each open serial port. The buffers are set to be twice the size of the biggest message.
Each serial port definition is a comma separated list of values. The last value is terminated by the newline that ends the definition. The fields are:
Field 1: The name used by spd to reference the port
Field 2: 'p', 'f' or 'l'. Map to a serial port, file or
software loopback.
Field 3: The absolute or relative name of the mapped device.
A software loopback will open the file but leave it
empty.
Field 4: 'Y' if the port is accessable.
'N' if it is not to be used.
Field 5: The default baud rate.
Field 6: The default number of data bits.
Field 7: Default parity.
'N' is none, 'E' is even, 'O' is odd.
Field 8: The default number of stop bits.
A port known as ttyS0 which is an active 9600b serial port using 8 data bits, no parity and one stop bit is:
ttyS0,p,/dev/ttyS0,Y,9600,8,N,1
The port shown below is sometimes used for testing and is known as testport. It is an active file mapped to testport.txt. The line parameters must be present and will be validated but are ignored:
testport,f,testport.txt,Y,9600,8,N,1
The port shown below is sometimes used for testing an interactive program and is known as echo. It is an active loopback that is mapped to the echo.txt. file. The line parameters must be present and will be validated but are ignored:
echo,l,echo.txt,Y,9600,8,N,1
The following was true as at Kernel 2.4.
When POLLIN events are enabled for an empty file a continuous series of POLLIN events are generated by the kernel, causing the event trap to retrieve a rapid series of null characters. Anything subsequently written to the file will not be retrieved. This affects the internal behavior of spd if a client accesses a port configured to access a file.
If the port is configured to access a serial connection POLLIN behaves as expected and a POLLIN event is only generated when a character arrives in the UART's buffer. The spurious POLLIN events are never seen.
As the spurious POLLIN events do not affect the external behavior of spd no attempt has been made to prevent them happening. The developer should note that they will appear in debugging output whenever a port that has been mapped to an empty file is opened or EOF is reached when a file is being read.
The main consequence of all this that, as most of the test
scripts are written to use file mapped ports, they write data to
the port and only retrieve it after closing and re-opening the
port. The other consequence is that the Java echo() method
and the C sp_echo function will both give erroneous
results if they are tested against a file mapped port. Test
against a port defined as loopback or use sptarget to
exercise them over a serial connection.
Port spd and spc to DOS/Windows. There are large differences between UNIX/Linux and DOS/Windows systems. The main problems are:
This document was created by man2html, using the
manual pages.
Time: 17:25:27 GMT, February 12, 2006