IQapture API Software Architecture
Published by
DTV-MD-0118
Version 0.2
1/31/2007
DIRECTV PROPRIETARY II
This document contains proprietary information and except
with written permission of DIRECTV such information shall not
be published and this document shall not be duplicated or
distributed, in whole or part.
DIRECTV Proprietary II
IQapture
Version
Date
0.1
0.2
8/1/2006
1/31/2007
DIRECTV Proprietary II
Version 0.2
REVISION HISTORY
Affected
sections
N/A
N/A
2
Reason for change
Initial Release
Updated to reflect current software
architecture
1/31/2007
DTV-MD-0118
IQapture
Table Of Contents
1
Introduction ________________________________________________________ 6
1.1
Purpose ______________________________________________________________ 6
1.2
Definitions and Acromyns _______________________________________________ 6
1.3
Applicable Documents __________________________________________________ 8
DIRECTV Referenced Documents ______________________________________ 8
Other Referenced Documents __________________________________________ 8
2
Overview___________________________________________________________ 9
2.1
3
Functional Requirements ____________________________________________ 10
3.1
4
Functions Performed __________________________________________________ 10
Software Design and Architecture ________________Error! Bookmark not defined.
4.1
5
Functional Overview ___________________________________________________ 9
PCI vs. PC/104 _______________________________________________________ 11
FPGA and Peripheral Device Configuration Description___________________ 16
5.1
FPGA_______________________________________________________________ 16
Configuration and Initialization ________________________________________ 16
Register Configuration _______________________________________________ 16
Power Up conditions ________________________________________________ 16
5.2
Demodulator (CX24126) _______________________________________________ 16
Communication and Control __________________________________________ 16
DPR LLF Loading Registers ___________________Error! Bookmark not defined.
Fixed Registers (or Direct Access Registers) _______Error! Bookmark not defined.
Serial bus read and write command structure ______Error! Bookmark not defined.
Register Configurations _______________________Error! Bookmark not defined.
Power Up Conditions _________________________Error! Bookmark not defined.
Resets _____________________________________Error! Bookmark not defined.
Demodulator I2C Control ______________________Error! Bookmark not defined.
Microcontroller Firmware Upload _______________Error! Bookmark not defined.
System Clocks ______________________________Error! Bookmark not defined.
PLL configuration ___________________________Error! Bookmark not defined.
Tuner configuration __________________________Error! Bookmark not defined.
LNB Configuration __________________________Error! Bookmark not defined.
MPEG output data configuration ________________Error! Bookmark not defined.
System Mode Select __________________________Error! Bookmark not defined.
Board Information ___________________________Error! Bookmark not defined.
Detailed Register Map ________________________Error! Bookmark not defined.
5.3
LNB (LNBH21) ______________________________________________________ 16
Communication and Control __________________________________________ 16
Serial bus read and write command structure _____________________________ 17
DIRECTV Proprietary II
Version 0.2
3
1/31/2007
DTV-MD-0118
IQapture
Register Configurations ______________________________________________
Power-On Conditions ________________________________________________
Tone Generator _____________________________________________________
Operation Settings __________________________________________________
Detailed Register Map _______________________________________________
5.4
PLL (AD9511) _______________________________________________________ 17
Communication and Control __________________________________________
Serial bus read and write command structure _____________________________
Register Configurations ______________________________________________
Power Up Conditions ________________________________________________
Power Down Modes _________________________________________________
Chip power down or sleep mode _______________________________________
PLL Power down ___________________________________________________
Distribution power down _____________________________________________
individual clock output power down ____________________________________
Individual circuit block power down ____________________________________
Reset Modes _______________________________________________________
Soft Reset _________________________________________________________
Detailed Register Map _______________________________________________
5.5
6
17
17
17
17
17
17
17
18
18
18
18
18
18
18
18
18
18
18
DDR2 _______________________________________________________________ 18
Open Issues _______________________________________________________ 19
DIRECTV Proprietary II
Version 0.2
4
1/31/2007
DTV-MD-0118
IQapture
Table of Figures
Figure 2-1 Receiver Module System Block Diagram .........Error! Bookmark not defined.
List of Tables
Table 1-1 Glossary and Acronyms __________________________________________ 6
Table 1-2 DIRECTV Referenced Documents __________________________________ 8
Table 1-3 Other Referenced Documents ______________________________________ 8
DIRECTV Proprietary II
Version 0.2
5
1/31/2007
DTV-MD-0118
IQapture
1
1.1
INTRODUCTION
Purpose
This API Specification Document provides detailed functional specifications for the
IQapture software API.
It is intended to be a reference for software engineers for the product.
It includes all information required for product application, design of the receiver and
analysis applications and parameters necessary to interface to the software.
1.2
Definitions and Acromyns
Some of these terms and abbreviations are used in this document:
Table 1-1 Glossary and Acronyms
Term
APG
BARP
BFAP
CA
Callback
CAM
CAMC
CGMS
CWP
DBS
DES
DIP
DIRECTV®
DVI
DVR
FEC
Definition
Advanced Program Guide. DIRECTV’s new generation of the electronic
program guide.
Broadcast Address Resolution Protocol
Broadcast File Announcement Protocol
Conditional Access
Data call, transmitted over telecommunications lines from the subscriber
receiver module to the CAMC. This is a repoting mechanism for impulse payper-view purchases.
Conditial Access Module. Usually referred to as the access card or smart card.
A removable, electronic subassembly providing conditional access control of
the subscriber terminal. The CA system equipment (smart card) needed in the
Integrated Receiver Decoder to control a subscriber's service channel
authorization and decryption.
Conditional Access Management Center.
Copy Guard Management System. Scheme to allow control of digital recording.
Control word packet. Information packet the Verifier uses to determine if it
should produce a control word allowing video (or audio, in the case of audio
only services) decryption.
Direct broadcast satellite. A satellite operating in accordance with International
Telecommunications Union and Federal Communications Commission
regulations for high power broadcasting from space to individual consumers.
Data Encryption Standard
Description information parcel. Data parcel, used in the program guide,
containing an event's description.
Trademarked name of the DIRECTV Group. The DBS system developed by
Hughes that supports digital television broadcast and extensive pay-per-view
capabilities.
Digital Visual Interface
Digital Video Recorder: records a digital signal to a hard disk or similar storage
Forward Error Correction
DIRECTV Proprietary II
Version 0.2
6
1/31/2007
DTV-MD-0118
IQapture
HDCP
IP
IR
IRD
LHCP
LNB
LO
MPT
NDS
NTSC
NV
ODU
PCM
PPV
Program
RF
RHCP
S/P DIF
SCID
STB
UHF
VHF
VME
VP
High-bandwidth Digital Content Protection
Internet Protocol
Infrared
Integrated Receiver Decoder. The indoor portion of the subscriber terminal
which performs functions of transmission channel tuning, service channel
selection, demodulation, demultiplexing, decryption (under control of the
CAM), analog signal output and subscriber interface.
Left Hand Circular Polarization
Low Noise Block down converter. Portion of ODU that receives the satellite
signal (12.2-12.7 GHz) and converts the signal into Lband (950-2025 MHz).
Local Oscillator stable frequency source
Multipacket Transport
News Digital Systems, Inc. The existing provider of conditional access and
security services for the DBS system.
National Television Systems Committee. Standardization body that developed
the Analog Terrestrial formats.
Non Volatile
Outdoor Unit. The system that provides signal reception and down conversion.
Pulse Code Modulation
Pay-Per-View
A time-contiguous segment of a service channel with start and end times
selected by a service provider. Programs do not overlap.
Radio Frequency
Right Hand Circular Polarization
Sony Phillips Digital Interface. Interface to transmit digital data to the digital
processor. Commonly used as an optical Dolby Digital connector.
Service Channel Identifier
Set-top Box
Ultra High Frequency
Very High Frequency
Versa Module Europa – A standard interface for equipment rack
Vertical Polarization
DIRECTV Proprietary II
Version 0.2
7
1/31/2007
DTV-MD-0118
IQapture
1.3
Applicable Documents
The documents listed below constitute a portion of this document to the degree specified
herein. Whenever conflicts exist between this document and a referenced document, the
contents of this document supercede that of the referenced document. The latest version
of each specification shall be used unless otherwise noted by DIRECTV.
DIRECTV Referenced Documents
Table 1-2 DIRECTV Referenced Documents
REF
Doc Title
Control #:
D-1.
DIRECTV LABELING REQUIREMENTS
D-2.
A3 CAPTURE CARD REQUIREMENTS
DTV-MD-0070
D-3.
IQAPTURE API SPECIFICATION
DTV-MD-0106
D-4.
IQAPTURE FPGA SPECIFICATION
DTV-MD-0117
Other Referenced Documents
Table 1-3 Other Referenced Documents
Ref
Doc Title
Control #:
O-1.
PC/104 Specification version 2.5, November 2003
O-2.
PCI Specification version 2.2, December 18, 1998
O-3.
Conexant., CX24126 Advanced Modulation DVB-S2
Demodulator and FEC Decoder Data Sheet
O-4.
Conexant., CX24118A Advanced Modulation Tuner
Data Sheet
O-5.
ST Micro, LNBH21 LNB Controller Data Sheet
O-6.
Analog Devices, AD9511 PLL and Clock Buffer Data
Sheet
DIRECTV Proprietary II
Version 0.2
8
1/31/2007
DTV-MD-0118
IQapture
2
2.1
Overview
Functional Overview
The IQapture card is a PCI and PC/104 signal capture card for the capture of satellite
transmissions. It features a high-speed analog-to-digital converter (ADC) as well as a
satellite demodulator compatible with DirecTV’s satellite broadcasts from A3 and DVBS2 down to the “legacy” DirecTV standard. This document describes the Application
Programming Interface (API) for the IQapture driver.
The IQapture driver is developed for the Windows operating system. Every effort is
made to ensure easy portability between the two operating systems. The driver is
developed using Microsoft’s Driver Development Kit (DDK) using the Kernel Mode
Driver Framework (KMDF), and is written to support Windows 2000, Windows XP and
2003 Server.
The driver takes the form of two parts: a kernel driver and a software library that provides
the API specified in this document. This is done because drivers are typically accessed
through ioctl() calls, which are somewhat less user-friendly than a typical procedural or
object-oriented software API. The driver can be used without the software library
through direct use of ioctl() calls, but as these may change over the course of driver
revisions, developers are highly encouraged to use the library. The details of accessing
the driver through ioctl() may remain less documented than the higher-level API used in
the library.
DIRECTV Proprietary II
Version 0.2
9
1/31/2007
DTV-MD-0118
IQapture
3
3.1
Functional Requirements
Functions Performed
The API serves as an abstraction layer between the low-level hardware interface to the
card and the higher-level software interface for the user’s application. Through the use of
function calls that expose the core functionality of the device, the application
programmer will be able to configure the IQapture card to capture data, change channels,
control satellite receiver equipment, and perform calibration and self-testing. The
application programmer will also be able to obtain running statistics on the card such as
estimated signal strength, decoded bit error rate, decoded frame error rate and similar
metrics.
The IQapture API exposes all of the functionality of the Conexant-provided Phantom
driver for the CX24126 demodulator IC as well as interfaces for its own functions, such
as analog data capture.
The driver must abstract low-level functions that end users would not reasonably expect
to have to program, such as I2C instructions, FTM messages, PLL configurations and the
like. However, access will be given to the low-level functions (such as I2C bus access
and the like) where it is appropriate.
The outer API must mask the inner workings of the driver and provide an interface to the
user that is consistent over time and intuitive to use.
DIRECTV Proprietary II
Version 0.2
10
1/31/2007
DTV-MD-0118
IQapture
4
4.1
System-Specific Details
PCI vs. PC/104
The PCI bus is an intelligent “plug-and-play” style bus with a 32 or 64-bit data and
address bus. PC/104 is a physical refactoring of the ISA bus, which is a basic 8 or 16-bit,
non-intelligent bus. The IQapture card makes use of a significant number of internal
registers, all of which can be directly accessed through PCI, but since the PC/104 device
needs to take up only a small amount of the I/O space, PC/104 I/O is accomplished
through the use of a paged addressing scheme (detailed in the FPGA architecture
document).
The Technologic Systems embedded PC for which the IQapture card was designed
supports only a modified, non-standard PC/104 interface. To enable 16-bit I/O on a
single pin header, several standard pins on the eight-bit connector have been replaced
with data and address pins, notably the DMA pins. Presumably, this is also because the
Technologic Systems computer (an ARM machine) does not have emulation of the
standard IBM PC DMA controllers necessary to support such DMA lines in the first
place. In any case, in PC/104 mode, the IQapture card does not support DMA transfers
and must be manually pumped for data through standard data transfers.
Since the drivers are currently only developed for the Windows operating system, and
PC/104 is not used on Windows, it is up to the user of the device in PC/104 mode to port
the driver over to the target operating system (presumably Linux). Every effort is made
to make the driver portable across operating systems with a minimum of trouble, but this
is not totally guaranteed.
DIRECTV Proprietary II
Version 0.2
11
1/31/2007
DTV-MD-0118
IQapture
5
5.1
General Architecture
User / Kernel separation
The kernel-mode driver exposes an interface to the user land that attempts to provide all
the functionality of the card without exposing enough of the internals of the FPGA or
allowing errant or malicious driver commands to cause a security risk.
As an example, the DMA engine could easily be programmed by a malicious user to
transfer large amounts of private data from other applications held in physical memory to
the card’s DDR memory space and then to the user’s application program if the DMA
engine was allowed to be manually controlled by the user. Instead, the driver takes an
address and a length for the user’s data buffer, verifies that the entire area pointed to by
the address/length pair is valid and belongs to the user, and programs the DMA engine to
perform the appropriate transfer. This has the added benefit of reducing the load on the
user, though the process is even further abstracted by the user-mode library provided with
the kernel-mode driver.
It is a necessity that some complex functionality be made available to enable forward
compatibility with unexpected operating modes. Wherever this is necessary (e.g. I2C
communications), simplified interfaces to the functionality are made available through
the user-mode library. Continuing with the I2C example, it is a possibility that custom
commands may need to be sent over the I2C bus (this is of particular use in debugging the
hardware). To reduce the amount of code present in the kernel driver (code which must
be more scrupulously audited because of the inherent risk to system stability and
security), only the low-level I2C interface is presented to user land. The caller of the
kernel driver must send individual I2C communication structures representing the action
to take. The user-mode library exposes this function to the user for situations where it is
absolutely necessary, but also presents many layers of higher-level functions; these range
from simple message send and receive functions to even simpler demodulator and FTM
control actions.
Under no circumstances will user-mode programs be allowed to access arbitrary areas of
memory in the FPGA’s memory map; this even carries over to the onboard DDR, whose
access functions must take only offsets from the base address of the DDR and must check
the boundaries closely before accessing.
The interfaces to which the kernel-mode driver must provide access are:
All three I2C interfaces
The SPI interface
The PCI DMA controller
The internal DMA controller
The FPGA’s register file
Demodulated data and analog data FIFOs
Access to the built-in self test
Access to the onboard DDR2 SDRAM
DIRECTV Proprietary II
Version 0.2
12
1/31/2007
DTV-MD-0118
IQapture
6
6.1
Interfaces
I2 C
The kernel driver must provide methods to access all three of the I2C interfaces. The
accessors must be able to send and receive bytes and ACK signals, as well as produce
start and stop conditions on the bus. The accessors allow the user to select the bus on
which the card will send or receive data. The user library provides higher-level
functionality, such as facilities for sending and receiving complete messages from an
addressed device on the bus.
Currently, two I2C methods of communication are exposed by the user library: A simple
read/write method, where the address of the device is supplied along with a starting
register address, and the data is written byte by byte; and a detailed “sequence” wherein
the user specifies the start and stop conditions as well as transmission, reception and
sleep periods; pausing and restarting transactions (e.g. to read a length byte and then read
<length> bytes after without terminating the transaction) is also possible.
There are 3 I2C busses on the card. Bus 0 hosts the CX24126 demodulator; bus 1 hosts
the FTM microcontroller and the LNB voltage controller; and bus 2 hosts the slower
devices, namely the temperature sensor, the EEPROM and the DDR SPD EEPROM.
The device addresses are as follows, sorted by bus:
Bus 0:
Demod: 0x0A
Bus 1:
LNB controller: 0x10
FTM microcontroller: 0xA0
Bus 2:
Temperature sensor: 0x30
DDR SPD: 0xA0
EEPROM: 0xA3 (low 64k), 0xA7 (high 64k)
6.2
SPI
The kernel driver must provide methods to access the SPI interface. Only the PLL is
connected to the SPI interface at present, so no chip select or addressing capabilities are
required (or, indeed, provided on the FPGA). Furthermore, the SPI data transfer can be
limited to the format required by the AD9511 PLL, which is a 16-bit command followed
by 1, 2, 3 or 4 bytes of data (read or written). Therefore, only a read and write command
with a 2-byte command and a 4-byte operand are provided. The user-space library
presents these functions as PLL access functions, as well as abstracting them to the
higher-level power-down and frequency selection functions.
DIRECTV Proprietary II
Version 0.2
13
1/31/2007
DTV-MD-0118
IQapture
6.3
PCI DMA controller
The PCI DMA controller has the potential to be one of the most insecure elements in the
system. The user must only be allowed to supply a pointer into their own virtual address
space and a buffer length to the function, which shall then be transformed into a scattergather list for the PCI DMA controller. The kernel driver must check the address and
length of the buffer to ensure that all of the space indicated belongs to the user. The
accessor must also be provided an offset into the DDR’s address space (which must be
checked for validity), and the length must be verified for the DDR space as well. The
user-mode library will provide similar interfaces to allow the user to copy out all or part
of the demodulated buffer to the user’s buffers; such functionality will also restrict the
retrieval size to that specified by the capture buffer.
6.4
Internal DMA controller
The internal DMA controller must be programmed to transfer data out of the demodulator
and ADC FIFOs and into the DDR buffer. It should not be set to write to other areas of
the card. The kernel-mode library will accept a base address and length within the DDR
as well as the FIFO to read from as arguments for the configuration functions. The
library will simplify this interface further, taking only a buffer length argument for the
ADC capture buffer (using the leftover space as demodulated data capture space).
6.5
Register file
Most of the registers in the register file act as controls for the various previouslymentioned interfaces. Other registers (status registers, etc) will be readable through the
driver calls, but not writeable. Any functions that require writes to the register file should
be part of their own group, such as I2C and SPI.
6.6
FIFOs
The demodulated and I/Q data FIFOs will need to be probed via software for FPGA
testing purposes. Reading and writing to these FIFOs is not inherently dangerous, but it
is not of much use to the general user; these interfaces will be directly accessible via
ioctls but will not be exported from the API library.
6.7
Built-in self test
The FPGA will have a built-in self test function activated by a single register in the
register file. There will be a call in the kernel-mode driver to activate the test, then wait
for it to complete and return the status of the card. This call will also perform various
other functional tests, such as simple call-response tests on various external peripherals.
A function will be exported from the API library to call this.
DIRECTV Proprietary II
Version 0.2
14
1/31/2007
DTV-MD-0118
IQapture
6.8
DDR SDRAM
Similar to the FIFOs, software will need to be able to directly write into and read out of
the DDR for testing purposes. Again, this functionality will be exposed only though
ioctls, and will not be generally available from the API library.
DIRECTV Proprietary II
Version 0.2
15
1/31/2007
DTV-MD-0118
IQapture
7
FPGA and Peripheral Device Configuration Description
The following is preliminary information from the FPGA team on the detailed
configuration of some of the devices on the FPGA. It is out of date, but will be updated
and finished when the FPGA specification is complete.
7.1
FPGA
Configuration and Initialization
Upon initialization of the user library, the I2C and SPI controllers are initialized. The
DDR module’s SPD EEPROM is read and the row/column/bank values are programmed
into the FPGA’s registers. The interrupt enable on the Wishbone/PCI bridge is initialized
to allow pass-through of internal interrupts to the PCI bus. The interrupt mask is then
programmed with the enable bits of all currently handled interrupts.
Register Configuration
The FPGA’s internal registers are documented in the FPGA specification (DTV-MD0117).
Power Up conditions
At PCI reset, all internal registers are reset to default conditions (generally zero; where
significant or where not zero, the default conditions are noted in the register definitions).
7.2
Demodulator (CX24126)
Communication and Control
Demodulator control is handled by Conexant’s Phantom library. The user library
supplies the Phantom library with function pointers to send and receive I2C data; the
Phantom library performs all initialization and communication tasks with the
demodulator. All demodulator-related API calls are wrappers around Phantom
functionality (occasionally with some extra functionality, particularly for the LNB
voltage).
7.3
LNB (LNBH21)
Communication and Control
The LNB controller is controlled through I2C bus 1. It is at address 0x10 and has a single
register which is not addressed.
DIRECTV Proprietary II
Version 0.2
16
1/31/2007
DTV-MD-0118
IQapture
Serial bus read and write command structure
The LNB controller, as mentioned above, has only a single register and does not take a
register address at the beginning of its transaction.
Register Configurations
Power-On Conditions
The I2C interface is automatically reset on power on. All bits of the System Register are
set to 0 at power-on.
Tone Generator
Tone generator can be controlled using either the I2C interface by setting the Tone
Enable (TEN) bit of the System Register or by dedicated pin that allows DiSeqC
encoding. In the latter case DSQIN pin would be connected to the demod chip, and the
TEN bit of the system register would be set would be set to low. Refer to page 5 and 7 of
the LNBH21 data sheet.
Operation Settings
Add the notes on register settings for different operations.
Detailed Register Map
LNBH21 has one register called System Register (SR). For detailed register bit map and
field description refer to page 7 and 8 of the .
7.4
PLL (AD9511)
Communication and Control
The AD95 11 PLL device has a serial communication port used to access the
configuration registers. Refer to page 41 of the data sheet.
Serial bus read and write command structure
The AD9511 uses an SPI-compatible serial programming interface. Refer to pages 41-44
of the AD9511 datasheet.
DIRECTV Proprietary II
Version 0.2
17
1/31/2007
DTV-MD-0118
IQapture
Register Configurations
Power Up Conditions
Refer to pages 39-40 of the datasheet.
Power Down Modes
Refer to pages 39-40 of the datasheet.
Chip power down or sleep mode
PLL Power down
Distribution power down
individual clock output power down
Individual circuit block power down
Reset Modes
Refer to page 40.
Soft Reset
This is by writing to register 00h[5]=1b. This bit is not self clearing, it needs to be set to
0b for the operation of the part to continue. See page 40 of the datasheet.
Detailed Register Map
See pages 45-53 of the AD9511 datasheet.
7.5
DDR2
DIRECTV Proprietary II
Version 0.2
18
1/31/2007
DTV-MD-0118
IQapture
8
1.
2.
3.
Open Issues
More information on what DiSEqC functions need to be abstracted is
necessary.
Data structures are not yet specified in this document, but are coming very
soon.
Function parameters are not yet fleshed out in this document, but are also
coming soon.
4.
DIRECTV Proprietary II
Version 0.2
19
1/31/2007
DTV-MD-0118