README

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 SMPTE 259M-C with SDI Master
 9. Playing SMPTE 259M-C with SDI Master
10. Capturing 4:2:2 component digital video over SDI
11. Capturing audio over SDI
12. Playing 4:2:2 component digital video over SDI
13. Playing audio over SDI
14. 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.18 or higher.

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
	DVB Master III Tx LP
	DVB Master III Rx LP
	QuadPort H/i
	VidPort SD/HD O
	VidPort SD/HD I

 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 SMPTE 259M-C with SDI Master
------------------------------------------

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 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 SMPTE 259M-C with SDI Master
----------------------------------------

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 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 SDI
----------------------------------------------------

This section applies to QuadPort and VidPort boards, not SDI Master.

Connect an SDI source to your board's receive port
with a 75 ohm cable.

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

	sdivideocfg /dev/sdivideorx0

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

By default, the interface should be capturing with 8-bit precision.
If you want to capture with 10-bit precision, change the mode by typing

	sdivideocfg -m1 /dev/sdivideorx0

as root.
Use

	sdivideocfg -h

to view information about other options.

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

	videocapture -n1 /dev/sdivideorx0 > test.raw

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.

You can also use FFmpeg, MPlayer, or VideoLAN to display the captured video.

Display 720p video with UYVY packing format with FFmpeg by typing

	ffplay -f rawvideo -s 1280x720 -pix_fmt uyvy422 /dev/sdivideorx0

Display 720p video with UYVY packing format with MPlayer by typing

	mplayer -demuxer rawvideo -rawvideo w=1280:h=720:format=uyvy:fps=60 /dev/sdivideorx0

Display 720p video with UYVY packing format with VideoLAN by typing

	vlc --demux rawvideo --rawvid-width 1280 --rawvid-height 720 --rawvid-chroma=UYVY --zoom 0.25 --rawvid-fps 60 /dev/sdivideorx0


11. Capturing audio over SDI
----------------------------

This section applies to QuadPort and VidPort boards, not SDI Master.

Connect an SDI source to your board's receive port
with a 75 ohm cable.

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

	sdiaudiocfg /dev/sdiaudiorx0

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

By default, the interface is set to capture 2-channel audio.
If you want to capture 8-channel audio, change the mode by typing

	sdiaudiocfg -c8 /dev/sdiaudiorx0

as root.
Use

	sdiaudiocfg -h

to view information about other options.

Capture one second of audio to a file called test.raw by typing

	audiocapture -n1 /dev/sdiaudiorx0 > test.raw

If you receive an error message, make sure you have read permission
on the device file.

Listen to 2 channel, 16-bit audio with 48000 Hz sample rate with MPlayer
by typing

	mplayer -demuxer rawaudio -rawaudio channels=2:rate=48000:samplesize=2 /dev/sdiaudiorx0

Listen to 2 channel, 16-bit audio with 48000 Hz sample rate with VideoLAN
by typing

	vlc --demux rawaud --rawaud-channels 2 --rawaud-samplerate 48000 --rawaud-fourcc s16l /dev/sdiaudiorx0

Display video and listen to audio with MPlayer by typing

	mplayer -demuxer rawvideo -rawvideo w=1280:h=720:format=uyvy:fps=60 /dev/sdivideorx0 -audio-demuxer rawaudio -rawaudio channels=2:rate=48000:samplesize=2 -audiofile /dev/sdiaudiorx0


12. Playing 4:2:2 component digital video over SDI
--------------------------------------------------

This section applies to VidPort boards, not SDI Master.

Connect an SDI 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

	sdivideocfg /dev/sdivideotx0

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

By default, the interface assumes 8-bit data.
If you want to play 10-bit data, change the mode by typing

	sdivideocfg -m1 /dev/sdivideotx0

as root.
Use

	sdivideocfg -h

to view information about other options.

If you have a video file, transmit it with

	videoplayout /dev/sdivideotx0 < test.raw

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

Transmit a compressed video file with FFmpeg by typing

	ffmpeg -y -i test.ts -f rawvideo -pix_fmt uyvy422 /dev/sdivideotx0

Transmit a compressed video file with MPlayer by typing

	mencoder -nosound -ovc raw -vf format=uyvy -of rawvideo -o /dev/sdivideotx0 test.ts

If you don't have a file, it is possible to transmit
a SMPTE RP219, BT 801, or EG 1 color bar pattern.
To transmit a RP219 color bar pattern

	rp219 | videoplayout /dev/sdivideotx0

Use

	rp219 -h

to view information about other options.

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


13. Playing audio over SDI
--------------------------

This section applies to VidPort boards, not SDI Master.

Connect an SDI 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

	sdiaudiocfg /dev/sdiaudiotx0

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

By default, the interface assumes 2-channel audio.
If you want to play 8-channel audio data, change the mode by typing

	sdiaudiocfg -c8 /dev/sdiaudiotx0

as root.
Use

	sdiaudiocfg -h

to view information about other options.

If you have an audio file, transmit it with

	audioplayout /dev/sdiaudiotx0 < test.raw

This process will block until video data is also provided;
this can be used to synchronize audio and video.

Transmit 2 channel, 16-bit audio with 48 kHz sampling rate
from a compressed audio file with FFmpeg by typing

	ffmpeg -y -i test.ts -f s16le -ar 48000 -ac 2 /dev/sdiaudiotx0

Transmit video and audio from a compressed file with FFmpeg by typing

	ffmpeg -y -i test.ts -f rawvideo -pix_fmt uyvy422 /dev/sdivideotx0 -f s16le /dev/sdiaudiotx0

If you don't have a file, it is possible to transmit
a SMPTE RP155 tone.
To transmit a RP155 tone

	rp155 | audioplayout /dev/sdiaudiotx0

Use

	rp155 -h

to view information about other options.

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


14. 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.