; $URL: http://subversion:8080/svn/gsc/trunk/drivers/LINUX/SIO4%20and%20SIO8/SIO4_Linux_2.x.x_GSC_DN/async/samples/stream/readme.txt $
; $Rev: 56283 $
; $Date: 2025-03-24 09:49:33 -0500 (Mon, 24 Mar 2025) $

SIO4: Asynchronous Protocol Library: Sample Application: examples documentation

CONTENT:

    PURPOSE

    OPERATING MODES

    COMMAND LINE OPTIONS: DATA TRANSFER OPTIONS
    COMMAND LINE OPTIONS: I/O BUFFER CONFIGURATION
    COMMAND LINE OPTIONS: READ OPTIONS
    COMMAND LINE OPTIONS: LOOPBACK OPERATION
    COMMAND LINE OPTIONS: MISC

    EXAMPLES



PURPOSE:

The purpose of the Asynchronous "stream" sample application is to demonstrate
streaming of serial data by use of a Tx thread and an Rx thread. The data
source is configurable and can be one of the following based on the indicated
command line argument.

1. -src0: NULL data, which fills a buffer with data values of zero.

2. -srci: An incrementing pattern from 0x00 through 0xFF, repeated through the
	source entire buffer.

3. -srcd: The serial channel receiver.

The data destination is also configurable and can be one of the following based
on the indicated command line argument.

1. -dst0: The bit bucket, in which case the data is discarded.

2. -dstb: A binary file (datast.bin).

3. -dsth: A hex file (datast.txt).

4. -dstd: The serial channel transmitter.



OPERATING MODES:

The application operates in one of two basic modes, based on the following
command line arguments.

1. -rx: In the Rx mode, the Rx thread acquires data and passes it off to the
	Tx thread. The data source is according to the above -srcX options. Once
	received by the Tx thread, the data is dispensed with it according to the
	above -dstX options. The Rx and Tx serial channels are specified on the
	command line. Any combination of channel numbers is supported. However,
	this mode does not support loopback operation.

2. -tx: In the Tx mode, the Tx thread acquires data and writes it to the serial
	channel for transmission. The data source is according to the above -srcX
	options, except for -srcd. The Rx thread, in turn, reads data from the
	receiver and dispensed with it according to the above -dstX options, except
	for -dstd. The Rx and Tx serial channels are specified on the command line.
	Any combination of channel numbers is supported. Loopback is supported if
	both Tx and Rx access the same serial channel, but it must be enabled on
	the command line (-lbX).



COMMAND LINE OPTIONS: DATA TRANSFER OPTIONS:

1. -bmdma: Read and write device data using Block Mode DMA. *

2. -dmdma: Read and write device data using Demand Mode DMA. *

3. -pio: Read and write device data using PIO. **

4. -rxio#: This option sets the I/O Timeout limit for data read requsts. ***

* These are always blocking calls as the driver has to wait for the DMA Done
	interrupt.

** This is a blocking call only when the I/O timeout is non-zero and the I/O
	call has to wait for more read data or write space.

*** Setting the Rx I/O Timeout to zero results in PIO based read requests
	becoming non-blocking requests. While read requests become non-blocking, it
	can also results in lower efficiency unless some other means is used to
	trigger the need for read requests.



COMMAND LINE OPTIONS: I/O BUFFER CONFIGURATION:

The application passes data around in preallocated buffers. The number and size
of these buffers is configurable from the command line. The application will
make use of as many buffers as necessary based on need.

1. -bufb#: This options specified the size of the buffers in Bytes.

2. -bufq#: This options specified the number of buffers.

3. -ser: This option serializes I/O operations. *

* This is done by setting the buffer quantity to one. The result is that the
	thread acquiring the source data completes its processing before the
	alternate thread begins processing of the destination data. This thread,
	too, completes its processing before the acquisition thread begins working
	on the next data block.



COMMAND LINE OPTIONS: READ OPTIONS:

1. -rxb#: This option specifies the number of bytes to request with each read
	call. This upper limit is the size of the I/O buffers (-bufs#)

2. -rxaf#: This option specifies the value for the Rx FIFO Almost Full setting.
	This cannot exceed the size of the Rx FIFO.

3. -rxafirq: This option specifies that I/O read requests must wait for the Rx
	FIFO Almost Full interrupt before proceeding.

Using these options may dictate use of real time processing. See -rtpri below.



COMMAND LINE OPTIONS: LOOPBACK OPERATION:

1. -lbd: This option disabled the use of loopback operation.

2. -lbe: This option selects External Loopback operation, when possible.

3. -lbi: This option selects Internal Loopback operation, when possible.

Loopback operation is available Tx mode (-tx) when the transmitter and receiver
are on the same serial channel.



COMMAND LINE OPTIONS: MISC:

1. -br#: This option is used to specify the desired bit rate.

2. -dce: This option selects the DCE cable signal configuration. *

3. -dte: This option selects the DTE cable signal configuration. *

4. -f: This option specifies that some operations are to proceed even if an
	error is encountered.

5. -log: This option specifies that various operations are to be timed and
	logged, and that the logged data is to be reported when operations are
	finished.

6. -rtpri#: This option specifies that Real Time thread scheduling be selected.
	The argument number specifies the percentage of the maximum supported Real
	Time priority to select.

7. -srcms#: This option enables the use of a delay between acquisition of
	consecutive source data blocks. The delay is specified in milliseconds.

8. -s#: This option specifies the number of seconds that the application is to
	spend acquiring source data.

9. -s: This option specifies that buffer statistics be reported before the
	applications ends.

10. -v: This option selects verbose processing. This includes reporting applied
	setting to the screen and expanding on logged activities.

* If not specified, then DCE is selected for the transmitter and DTE for the
	receiver.



EXAMPLES:


1. Basic Rx Mode

With only this one command line argument the application's Rx thread acquires
NULL data buffers (zero filled buffers) and passes them to the Tx thread, which
then discards the data. This example simply shows how quickly the application
can pass around data buffers.

./stream -rx


2. Transmit an Incrementing Pattern

This is similar to the above example. Here, however, the source data is an
incrementing pattern. Also, the Tx thread writes the data to the SIO4, which
transmits it out the cable interface.

./stream -rx -srci -dstd


3. Save an Incrementing Pattern to Disk

This is nearly identical to the above example, except that the Tx thread saves
the incrementing pattern to a hex encoded text file.

./stream -rx -srci -dsth


4. Basic Tx Mode

With only this one command line argument the application's Tx thread acquires
NULL data buffers (zero filled buffers) and writes them to the SIO4, which
transmits the data out the cable interface. The Rx thread is poised to receive
data. Without an attached device providing data, and without selecting
loopback mode, the Rx thread will not collect any data. If any were collected,
it would be discarded

./stream -tx


5. Simple Tx Mode

This is similar to the above example. Here, however, the transmitted data is an
incrementing patter, which is written to the SIO4. Since the External Loopback
option is selected, the transmitted data is picked up by the receiver and
gathered by the Rx thread. From there, the data is discarded.

./stream -tx -srci -lbe


6. Save an Incrementing Pattern to Disk

This is nearly identical to the above example, except that the Tx thread saves
the incrementing pattern to a hex encoded text file.

./stream -tx -srci -lbe -dsth


7. Read Data on One Channel Then Re-transmit It On Another Channel

This operation can only be accomplished in Rx mode (-rx).

./stream -rx -srcd -dstd 0 1


8. Transmit A Fixed Size Block At Fixed Intervals

This can be accomplished with either of the below command lines.

./stream -rx -srci -bufb64 -srcms1000 -dstd
./stream -tx -srci -bufb64 -srcms1000


9. Read Data When The Rx FIFO is Almost Full

This is done by setting the Rx FIFO Almost Full level to a desired level, then
enabling use of the Rx FIFO Almost Full interrupt.

./stream -tx -srci -lbe -rxaf32704 -bufb64 -rxafirq


10. Operate At A Very Low Bitrate

This can be done in either Rx or Tx mode.

./stream -rx -srci -dsth -br9600


11. Vary The Buffer Size And Quantity

This may be needed for varying circumstances, but it can help to increase
buffering of source data.

./stream -rx -bufb65536 -bufq1024


12. Force DCE/DTE Selection

The application normally selects DCE/DTE automatically, but it can be specified
manually.

./stream -rx -srci -dstd -dce


13. Select Demand Mode DMA

Each SIO4 only has two DMA engines, so PIO may be required in many cases. The
application does support selection of the DMA options when circumstances
permit.

./stream -rx -bmdma -srci -dstd


14. Serialize Tx/Rx Operations

When necessary, Tx/Rx operations can be serialized. This is accomplished by
restricting operation to the use of a single buffer. This way, the Tx/Rx
threads must wait for the other to complete before continuing.

./stream -rx -bufb64 -ser -srci -dstd


15. Report Operation Timing

The application can record the timing of I/O operations (i.e., -srcd and
-dstd). The log includes the time that the operation began as well as how long
the operation took to complete. When enabled, the activity log is posted to
the screen before the application ends.

./streen -rx -dstd -log


16. Verbose Output

If verbose output is selected, the application dumps all Asynchronous settings
to the screen before starting operations. It also expands on the activities
logged, when logging is enabled.

./rx -srci -dstd -v

