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.