hdcp1x
Vitis Drivers API Documentation
|
This is the Xilinx HDCP device drivers. The Xilinx HDCP driver software is provided to allow for the integration of HDCP functionality into designs that make use of the DisplayPort and HDMI LogiCORE IP video interface cores. This software is distributed within the Xilinx SDK (Software Development Kit) and is tightly coupled with the SDK drivers for these interfaces. This appendix serves as a technical reference describing the architecture and functionality of HDCP driver software as well as providing guidelines for integrating it into a custom DisplayPort and/or HDMI system designs based on Xilinx programmable devices.
Platform Requirements The current platform requirements for the HDCP driver software are as follows:
Restrictions and Limitations The HDCP driver software has the following restrictions and limitations:
HDCP Driver Architecture
The architecture of the HDCP software driver can be divided into three distinct submodules.
Cipher Device
The cipher device is contained within the HDCP driver software and represents an instance of the HDCP cipher LogiCORE IP block within a system design. Given that the variants of this cipher core provide the same interface to the software, a single implementation of this submodule is used to drive all of them. In the few places where behaviors differ slightly between variants, this software adjusts at runtime based on the contents of a Type/ID register within the IP core.
The principal function of the cipher device submodule is to initialize, configure, and monitor the physical encryption cipher used within the HDCP application. As part of this, it provides an interface that allows the software to trigger the reading of the appropriate device key set from the custom key management solution that is attached to the cipher core.
The cipher device submodule is used by higher-level authentication state machines to run re-authentication requests, generate pseudo-random numbers, and enable/disable encryption on individual video streams passing through the cipher core.
It also provides a status output from the actual encryption process that can be used by the authentication state machines to monitor the correct operation of the HDCP function.
The interrupts generated by the cipher core are fully consumed within the HDCP software driver; the client software application needs only to register the cipher core interrupt with the associated vector within the appropriate interrupt controller of the system design. These interrupts are forwarded to the cipher submodule through an appropriate external API of the software driver (XHdcp1x_CipherIntrHandler).
The software driver source files that are associated with this submodule are as follows:
Port Device
The port device(s) that exists within the HDCP software driver represent the management and access to the HDCP register sets that are defined within the HDCP specifications. While the register sets are similar between HDMI and DisplayPort, they do differ, and as a result there are slightly different implementations of these port devices between the two. Regardless of the physical interface type, the transmit port device is always the master of the register set transactions and the receive port device is always the slave.
For transmit port devices, they provide the ability to read and write the HDCP register set that exists on their attached receive (slave) device. These transactions are always run to completion and are initiated solely by the corresponding transmit state machine and/or as part of a debug process if explicitly requested.
For receive port devices, they only provide access to the local HDCP register set; they cannot be used to read the register set from the attached transmit device. Local reads and writes of this register set are performed by the appropriate receive state machine (or debug process) and remote reads and writes can be performed by the transmit port (master) device.
Remote access (either read or write) to a subset of the register set generates notifications (for example, interrupts) to the device that are then in turn posted to the corresponding receive state machine for driving authentication and related procedures. The underlying implementation of the supported HDCP port device modules is completely dependent on the Xilinx BSP device driver for the corresponding video interface type. As a result, the client application software is required to provide the device handle of the video interface that the specific HDCP driver instance is bound to during initialization of the HDCP software driver.
For more information on the BSP Standalone driver, see the following documents:
The internals of the port device rely on the use of an adapter structure (a jump table) which maps the HDCP port device API into a protocol (DisplayPort/HDMI) and direction (RX/TX) specific function that implements the associated functionality. This adapter structure (XHdcp1x_PortPhyIfAdaptor) allows for the correct function to be determined and called at run-time based on the exact type of the HDCP interface in question. In some instances (specifically DisplayPort TX), there is no specific port device interrupt defined and, as such, the relevant interrupt(s) (HPD) must be forwarded to the port device submodule through an appropriate external API of the software driver (XHdcp1x_PortIntrHandler).
The software driver source files that are associated with this submodule are as follows:
Authentication State Machines
The transmit and receive authentication state machines contained within the driver software mirror those that are defined within the appropriate HDCP specifications. To facilitate integration and debugging, the names of the individual states are aligned with those defined within the specifications wherever possible.
The state machines are responsible for driving the authentication, encryption, and link monitoring processes as requested by the client application software.
The state machines co-ordinate the operation of the cipher, port device(s), and the physical video interface (HDMI or DisplayPort), and rely upon the proper programming and availability of HDCP device keys.
The state machines make use of a simple, OS-independent scheduler to allow for messages and requests to be posted to and from them. This requires the client application software to regularly call a poll function on each HDCP interface to ensure the timely servicing of these messages/requests.
The transmit state machine provides interfaces that allow for the client application software to request authentication, enable/disable the encryption of video streams, and monitor the progress/outcome of authentication and the ongoing integrity of the encrypted video data. The transmit state must be notified of changes in the physical state of the interface it is running over (either HDMI or DisplayPort) to ensure that any required re-authentication is performed without explicit intervention of the client software application. It fully supports downstream HDCP receivers and repeaters. For a detailed diagram of this state machine, see either figure 2-6 in the High-bandwidth Digital Content Protection System v1.3 Amendment for DisplayPort specification or figure 2-9 in the High-bandwidth Digital Content Protection System v1.4 specification. The transmit state definitions are contained within the XHdcp1x_StateType contained within the xhdcp1x_tx.c source file.
The receive state machine is much simpler than the transmit in that it is not entirely aware of the success/failure of the authentication process. It merely initiates the calculations required for authentication and makes the result available within its HDCP register set for examination by the transmitter. It allows for the client application software to explicitly enable/disable the HDCP capability of the underlying video interface and to query whether encrypted video is being received at any point in time. It also requires that it be notified of changes in the physical interface it is running over so that the appropriate side effects can be initiated. For a detailed diagram of this state machine, see either figure 2-7 in the the High-bandwidth Digital Content Protection System v1.3 Amendment for DisplayPort specification or figure 2-10 in the High-bandwidth Digital Content Protection System v1.4 specification. The receive state definitions are contained within the XHdcp1x_StateType contained within the xhdcp1x_rx.c source file.
Both the transmit and receive state machines make use of a link verification procedure to ensure that both ends of the encrypted link remain synchronized over time. This mechanism differs between DisplayPort and HDMI and is detailed in section 2.2.4 of the High-bandwidth Digital Content Protection System v1.3 Amendment for DisplayPort specification [Ref 1] and section 2.2.3 of the High-bandwidth Digital Content Protection System v1.4 specification respectively.
The software driver source files that are associated with this submodule are as follows:
Device Key Management
The device key management software and RTL/IP implementation interact with the HDCP software driver but are, in the strictest sense, outside of the scope of this driver. The Xilinx HDCP solution is designed such that each individual platform integrator is responsible for the security and storage of the HDCP device keys that are issued to them by DCP LLC. The physical interface between the LogiCORE IP HDCP Cipher Product Guide and the custom implemented key storage is described in the High-bandwidth Digital Content Protection System v1.3 Amendment for DisplayPort specification and the High-bandwidth Digital Content Protection System v1.4 specification.
Dependencies
The only dependencies between the HDCP driver software and the actual device key management implementation are, as follows:
HDCP Driver Porting Guide
The following system resources are required by the HDCP software driver software:
Integrating Into Your Application
The HDCP software driver can be integrated into any client software application, regardless of whether an operating system is used or not. This integration generally consists of a few simple steps.
It is important to note that the physical video interfaces over which HDCP is to be run must physically exist and be initialized prior to the initialization of the corresponding HDCP driver instance. If this is not the case, then the HDCP driver software will not work as designed. In addition, interrupts on the physical interface should not be enabled until after the corresponding HDCP driver instance has been initialized. While the successful operation of this driver relies on the use interrupts, there are no external interrupt callbacks to be registered specifically by the client software using the HDCP software driver. All of the HDCP-specific interrupts are fully consumed within the software driver and all the client software needs to do is properly complete integration using step 6, step 7, and step 8.
IMPORTANT: Virtually all of the exported API functions that do not query the state of the driver require a subsequent call to the poll function in order for the request to be fully serviced by the indicated driver instance. As a result, it is crucial that the interface be polled in a timely fashion subsequent to such an API call.
Debugging
The HDCP software driver software provides two different mechanisms for facilitating the integration and debug into client application software. These are:
To enable the runtime debug logging of the driver software, the client application can register a printf-style debug logging function with the driver using the appropriate API.
If this is done, then the authentication state machines log all state transitions and periodic status information, providing significant insight into their operation. The function that can be used to register this logging function is XHdcp1x_SetDebugLogMsg.
Note: This debug logging is enabled/disabled on the driver as a whole (as opposed to on a single interface at a time) and does not support priorities of any kind.
In addition to runtime logging, the client application can register a printf-style debug print function with the driver software. This registration permits the driver to perform a one-time dump of detailed status information related to a specific HDCP driver instance when triggered by the client application software. The relevant functions for this are:
The information displayed using the XHdcp1x_Info function includes details on the current/previous state, encryption status, driver/core version(s), as well as statistics detailing the operation of the authentication state machine (RX and TX) and as its corresponding cipher and port sub-modules. The format of the information displayed differs slightly based on whether the HDCP interface is in the receive or transmit direction
Receive Authentication
The CE register accesses associated with the receiver authentication should be as follows:
Note: Any step that requires the writing of multiple registers are "book ended" with the clearing and subsequent setting of the register update bit within the Control register.
Transmit Authentication
The CE register accesses associated with the transmitter authentication should be as follows:
Note: Any step that requires the writing of multiple registers are "book ended" with the clearing and subsequent setting of the register update bit within the Control register.
HDCP REPEATER
The HDCP Repeater functionality is implemented in the drivers. Here however, the user has to ensure that the right setup is available for the HDCP repeater drivers.
Requirements
Repeater State Machine for Transmitter
For the transmitter system, the repeater state machine has the following states:
For the receiver system, the repeater state machine has the following states:
Repeater Flow
|> Receiver <| |> User App <| |> Transmitter <|
-> AKSV Written to Receiver | Ro' written to upstream | ----> Trigger Downstream (Hdcp1x.Rx.Repeater DownstreamAuthCallBack) ----> Transmitter writes AKSV and An downstream | Transmitter reads back Ro' and completes first part of authentication | -----(No)---- Is Downstream Repeater? | | (Yes) | Read the downstream KSV | FIFO, calculate the SHA-1 | value and complete 2nd part | of authentication. | ------------> Setup the KSV FIFO for upstream. | Exchange Repeater <---------------------- Values (Hdcp1x.Tx. ExchangeRepeaterCallBack) Here Get the KSV FIFO and update it for the Receiver. | Assemble the <----- KSV List and calculate the SHA-1 value and write it to upstream. | Goto Authenticated state.
The Repeater authentication requires the presence of both RX and TX interfaces. The authentication begins when the upstream transmitter writes the An and AKSV to the RX interface. After completing the first part of authentication the Receiver calls the DownstremaAuthCallBack callback handler. This handler should be set in the user application and should post the authenticate event to the TX state machine. This will trigger the TX authentication process. The TX completes the first part of authentication, by writing the AKSV and An downstreama and then reading an comparing the downstream Ro' value. If the downstream device is also Repeater, then the TX waits for the READY bit to get set in the downstream and reads the KSV FIFO. The TX then commences the second part of the authentication, where it calculates the SHA-1 value V and compares it with the V' read from the downstream. If the SHA-1 value V matches with the V' value read from downstream, authentication is successful. Here the TX sets up a RepeaterExchange value which it populates with the KSV FIFO of the downstream and the depth and device count values read from downstream. At this point the KSV FIFO calls the ExchangeRepeaterCallBack, which needs to be set in the user application. Here the user application receives the KSV FIFO value, depth and device count from the TX of the downstream topology. The user applicaition needs to update these value and set them for the receiver. At this point the RX is expected to be in the WAIT-FOR-READY state. Here the user should post EVENT_DOWNSTREAMREADY to the RX state machine. Consequently, the RX state machine will calculate the SHA-1 value, update the device count and depth value and set the READY bit for the upstream transmitter device to read and complete the authentication.
If the authentication fails and the upstream device triggers the authentication again, then the entire authenitcation process is re-started.
HDCP (Repeater) Callback functions
Handler associated with each callback:
MODIFICATION HISTORY:
Ver Who Date Changes
1.00 fidus 07/16/15 Initial release. 2.00 als 09/30/15 Added EffectiveAddr argument to XHdcp1x_CfgInitialize. 2.10 MG 01/18/16 Added function XHdcp1x_IsEnabled. 2.20 MG 01/20/16 Added function XHdcp1x_GetHdcpCallback. 2.30 MG 02/25/16 Added function XHdcp1x_SetCallback and AuthenticatedCallback. 2.40 MG 01/29/16 Removed function XHdcp1x_GetHdcpCallback and added function XHdcp1x_ProcessAKsv 3.0 yas 02/13/16 Upgraded to support HDCP Repeater functionality. Added constants: XHDCP1X_RPTR_MAX_CASCADE and XHDCP1X_RPTR_MAX_DEVS_COUNT. Added enumeration type: XHdcp1x_RepeaterStateMachineHandlerType. Added typedef data type XHdcp1x_Ksv. Added structure XHdcp1x_RepeaterExchange. Updated core structure XHdcp1x_Tx, XHdcp1x_Rx and XHdcp1x for Repeater support. Added following functions: XHdcp1x_DownstreamReady, XHdcp1x_GetRepeaterInfo, XHdcp1x_SetCallBack, XHdcp1x_ReadDownstream. 4.0 yas 06/15/16 Added support for Cipher Blank Value and select. Extended support for Repeater functionality. 4.0 yas 08/16/16 Used UINTPTR instead of u32 for BaseAddress XHdcp1x_CfgInitialize 4.1 yas 11/10/16 Added function XHdcp1x_SetHdmiMode. 4.1 yas 08/03/17 Added flag IsAuthReqPending to the XHdcp1x_Tx data structure to track any pending authentication requests. 4.2 yas 08/13/18 Addded hdcp14_PropagateTopoErrUpstream flag to track topology failures and ready the topology for the repeater application to read. 4.3 yas 08/16/19 Added support for HDMI 2.1 Rx and Tx.