UltraGrid/quad

README for the Master Linux Software Development Kit
====================================================


Table of Contents
-----------------

 1. Introduction
 2. Products supported
 3. Identifying your board
 4. Changes in this version
 5. Installation
 6. Capturing an MPEG-2 transport stream over DVB ASI or SMPTE 310M
 7. Playing an MPEG-2 transport stream over DVB ASI or SMPTE 310M
 8. Capturing 4:2:2 component digital video over SMPTE 259M-C
 9. Playing 4:2:2 component digital video over SMPTE 259M-C
10. Driver limitations and known bugs


 1. Introduction
----------------

This file is part of Linear Systems Ltd.'s Master Linux
Software Development Kit. This kit includes kernel modules
and several example programs. It is intended for
Linux kernel 2.6.x, and has been tested under Fedora 8
with kernel 2.6.24.

Additional documentation is in the doc directory.
The latest version of this kit is available at <http://www.linsys.ca/>.
For technical support, or to report bugs or errors in the documentation,
contact <support@linsys.ca>.


 2. Products supported
----------------------

This SDK supports the following products:

	DVB Master Send
	DVB Master II Send
	DVB Master Receive (Rev. 3 board or higher only, see limitations below)
	DVB Master II Receive
	DVB Master FD
	DVB Master FD-U
	DVB Master FD-B
	DVB Master III Tx
	DVB Master III Rx
	DVB Master LP
	DVB Master Q/i
	SDI Master
	MultiMaster SDI-T / MultiMaster A/S
	MultiMaster SDI-R / MultiMaster S/A
	DVB Master Dual In
	ATSC Master II FD
	SDI Master LP
	DVB Master Q/o
	DVB Master Q/io
	DVB Master Q/i LP
	DVB Master Quad-2in2out
	SDI Master Q/o
	SDI Master Q/i
	DVB Master Quad-1in3out PCIe
	DVB Master Quad-3in1out PCIe
	HD-SDI Master Q/i PCIe


 3. Identifying your board
--------------------------

Both the DVB Master Send and DVB Master II Send are marked
"DVB-ASI TRANSMITTER". The DVB Master II Send should have a
small 8-pin chip labelled "Tx#", where # is the firmware version.

Similarly, both the DVB Master Receive and DVB Master II Receive
are marked "DVB-ASI RECEIVER". The DVB Master II Receive should have
a small 8-pin chip labelled "Rx#", where # is the firmware version.

The DVB Master FD is marked "DVB Master FD".
The standard PID filtering version should have a small 8-pin chip
labelled "FDPF##", where ## is the firmware version.
The PID monitoring version should have
a small 8-pin chip labelled "FDPM##", where ## is the firmware version.

The firmware version of all boards is also added to the kernel log
when each board is detected by the driver.
This log is viewable with the "dmesg" command.

In all cases, the board revision is marked on the board itself
as "REV #".


 4. Changes in this version
---------------------------

See NEWS for user-visible changes.


 5. Installation
----------------

For complete installation instructions, read INSTALL.


 6. Capturing an MPEG-2 transport stream over DVB ASI or SMPTE 310M
-------------------------------------------------------------------

Connect a DVB ASI or SMPTE 310M source to your board's receive port
with a 75 ohm cable.
If there is a carrier detect LED on the receiver,
it should light up.

Assuming that you are using the first receive port
discovered in the machine, view its configuration with

	asicfg /dev/asirx0

Other interfaces may be viewed by providing the appropriate device file name.

By default, the interface should be synchronizing on 188-byte packets.
If you want to capture 204-byte packets, change the mode by typing

	asicfg -m2 /dev/asirx0

as root.
Use

	asicfg -h

to view information about other options.

Run the rxtest program by typing

	rxtest -s1 /dev/asirx0 test.ts

to copy data from the first receiver to a file called test.ts and
display status messages every second.
If you receive an error message, make sure you have read permission
on the device file. Press Ctrl+C to quit rxtest.


 7. Playing an MPEG-2 transport stream over DVB ASI or SMPTE 310M
-----------------------------------------------------------------

Connect a DVB ASI or SMPTE 310M receiver to your board's transmit port
with a 75 ohm cable.

If you have a board which can bypass the system and forward a
received stream directly to the transmit port, you will have to
disable the bypass. Assuming this is the first board detected by
the dvbm.ko driver, view the bypass mode with

	mastercfg dvbm 0

Other boards may be viewed by providing the appropriate device number.

This feature is enabled by default, which will discard any data
transmitted from the system. Disable the bypass by typing

	mastercfg -b1 dvbm 0

as root.

Assuming that you are using the first transmit port
discovered in the machine, view its configuration with

	asicfg /dev/asitx0

Other interfaces may be viewed by providing the appropriate device file name.

By default, the interface assumes 188-byte packets.
If you want to play a stream with 204-byte packets,
change the mode by typing

	asicfg -m1 /dev/asitx0

as root.
Use

	asicfg -h

to view information about other options.

Use

	txcfg /dev/asitx0

and select "Show transmitter capabilities"
to view the capabilities of this interface.
This information will be needed to correctly set the transmit bitrate
for DVB ASI.

For SMPTE 310M, a transport stream file may be transmitted with

	txtest /dev/asitx0 < test.ts

If you don't have a file, it is possible to transmit a stream
of MPEG-2 null packets with

	mknull | txtest /dev/asitx0

If you receive an error message, make sure you have write permission
on the device file. Press Ctrl+C to quit mknull.

The remainder of this section applies to DVB ASI only.

Your DVB ASI board uses a set of "stuffing parameters"
to scale its transmit bitrate relative to its reference frequency.
Use

	calcstuff <desired_bitrate_in_bps> <packet_size_in_bytes>

to calculate recommended stuffing parameters.
This will display several sets of stuffing parameters,
divided into three groups.
The "without finetuning" group should be used with
older boards which do not support bitrate finetuning.
The "finetuning" group should be used with
boards which support bitrate finetuning.
Bitrate finetuning provides more precise bitrate control,
but typically higher network jitter.
The "interleaved finetuning" group should be used with
boards which support interleaved bitrate finetuning.
Interleaved bitrate finetuning MAY provide
less network jitter than bitrate finetuning.

Within each group, there are two or three sets of stuffing parameters.
Each set will provide the same bitrate and network jitter,
but different spacing between packets.
Some equipment may be sensitive to this.
The "burst mode" set of stuffing parameters transmits each packet in a
continuous burst, with long gaps between packets.
An alternative set of stuffing parameters transmits
the stream with a gap between each byte.
Interfaces which support large interbyte stuffing values
can use the "large ib" stuffing parameters
displayed for extremely low bitrates.

Suppose we wish to transmit a stream of 188-byte packets
at 19392658.46 bps (the ATSC rate).
With interleaved finetuning, calcstuff provides
the following stuffing parameters:

	ib = 10, ip = 33, normal_ip = 2, big_ip = 169,
		il_normal = 1, il_big = 14

If you have a transport stream file, transmit it with

	txtest /dev/asitx0 10 33 2 169 1 14 < test.ts

If you don't have a file, it is possible to transmit a stream
of MPEG-2 null packets with

	mknull | txtest /dev/asitx0 10 33 2 169 1 14

If you receive an error message, make sure you have write permission
on the device file. Press Ctrl+C to quit mknull.


 8. Capturing 4:2:2 component digital video over SMPTE 259M-C
-------------------------------------------------------------

Connect a SMPTE 259M-C source to your board's receive port
with a 75 ohm cable.
If there is a carrier detect LED on the receiver,
it should light up.

Assuming that you are using the first receive port
discovered in the machine, view its configuration with

	sdicfg /dev/sdirx0

Other interfaces may be viewed by providing the appropriate device file name.

By default, the interface should be capturing with 10-bit precision
and packing four 10-bit words into every five bytes.
If you want to capture with 8-bit precision, change the mode by typing

	sdicfg -m0 /dev/sdirx0

as root.
Use

	sdicfg -h

to view information about other options.

Capture one second of video to a file called test.sdi by typing

	capture -n1 /dev/sdirx0 > test.sdi

If you receive an error message, make sure you have read permission
on the device file. Capturing longer segments to disk
without overrunning the driver's buffers will probably require
a disk array.


 9. Playing 4:2:2 component digital video over SMPTE 259M-C
-----------------------------------------------------------

Connect a SMPTE 259M-C receiver to your board's transmit port
with a 75 ohm cable.

Assuming that you are using the first transmit port
discovered in the machine, view its configuration with

	sdicfg /dev/sditx0

Other interfaces may be viewed by providing the appropriate device file name.

By default, the interface assumes 10-bit data with
four 10-bit words packed into every five bytes.
If you want to play 8-bit data, change the mode by typing

	sdicfg -m0 /dev/sditx0

as root.
Use

	sdicfg -h

to view information about other options.

If you have a video file, transmit it with

	playout /dev/sditx0 < test.sdi

Playing long files from disk without underrunning the driver's buffers
will probably require a disk array.

If you don't have a file, it is possible to transmit
a SMPTE EG 1 color bar pattern with

	eg1 | playout /dev/sditx0

If you receive an error message, make sure you have write permission
on the device file. Press Ctrl+C to quit eg1.

 10. Capturing 4:2:2 component digital video over SMPTE 274M
-------------------------------------------------------------

Connect a SMPTE 274M source to your board's receive port
with a 75 ohm cable.
If there is a carrier detect LED on the receiver,
it should light up.

Assuming that you are using the first receive port
discovered in the machine, view its configuration with

	hdsdicfg /dev/sdirx0

Other interfaces may be viewed by providing the appropriate device file name.

By default, the interface should be capturing with 10-bit precision
and packing four 10-bit words into every five bytes.
If you want to capture raw data, change the mode by typing

	hdsdicfg -m0 /dev/sdirx0

as root.
Use

	hdsdicfg -h

to view information about other options.

Display the bitrate of the icoming stream by typing

	bitrate -s1 /dev/sdirx0

Capture video to a file called test.sdi by typing

	bitrate /dev/sdirx0 test.hdsdi

If you receive an error message, make sure you have read permission
on the device file. Capturing longer segments to disk
without overrunning the driver's buffers will probably require
a disk array.


11. Driver limitations and known bugs
-------------------------------------

Streaming data to or from disk requires a fast CPU and a fast disk.
The hdparm utility may be useful for benchmarking and optimizing disk access.

Rev. 2 DVB Master Receive boards frequently refuse to allow
the status register to be read at the start of the
interrupt service routine, effectively hanging the machine.
Contact your distributor to obtain a replacement board.