From 249af540c694b8cca11aa8439e7f4816b34e7743 Mon Sep 17 00:00:00 2001 From: Andrei-Liviu Simion Date: Tue, 20 Jan 2015 13:45:28 -0800 Subject: [PATCH] dp: rx: Added file header documentation. Signed-off-by: Andrei-Liviu Simion --- XilinxProcessorIPLib/drivers/dp/src/xdp.h | 131 +++++------------- XilinxProcessorIPLib/drivers/dp/src/xdprx.c | 4 + XilinxProcessorIPLib/drivers/dp/src/xdprx.h | 48 +++++++ .../drivers/dp/src/xdprx_intr.c | 2 +- XilinxProcessorIPLib/drivers/dp/src/xdptx.h | 57 +------- 5 files changed, 85 insertions(+), 157 deletions(-) diff --git a/XilinxProcessorIPLib/drivers/dp/src/xdp.h b/XilinxProcessorIPLib/drivers/dp/src/xdp.h index 7e686f29..2ba31c86 100644 --- a/XilinxProcessorIPLib/drivers/dp/src/xdp.h +++ b/XilinxProcessorIPLib/drivers/dp/src/xdp.h @@ -34,9 +34,9 @@ * * @file xdp.h * - * The Xilinx DisplayPort transmitter (DPTX) driver. This driver supports the - * Xilinx DisplayPort soft IP core in source (TX) mode. This driver follows the - * DisplayPort 1.2a specification. + * The Xilinx DisplayPort transmitter (DP) driver. This driver supports the + * Xilinx DisplayPort soft IP core in both transmit/source (TX) and receive/sink + * (RX) modes of operation. * * The Xilinx DisplayPort soft IP supports the following features: * - 1, 2, or 4 lanes. @@ -73,94 +73,42 @@ * DisplayPort connection exists between the DisplayPort TX connector and * an RX device. It is serves as an interrupt request by the RX device. * - * Driver description - * - * The device driver enables higher-level software (e.g., an application) to - * configure and control a DisplayPort TX soft IP, communicate and control an - * RX device/sink monitor over the AUX channel, and to initialize and transmit - * data streams over the main link. - * - * This driver implements link layer functionality: a Link Policy Maker (LPM) - * and a Stream Policy Maker (SPM) as per the DisplayPort 1.2a specification. - * - The LPM manages the main link and is responsible for keeping the link - * synchronized. It will establish a link with a downstream RX device by - * undergoing a link training sequence which consists of: - * - Clock recovery: The clock needs to be recovered and PLLs need to be - * locked for all lanes. - * - Channel equalization: All lanes need to achieve channel equalization - * and and symbol lock, as well as for interlane alignment to take place. - * - The SPM manages transportation of an isochronous stream. That is, it will - * initialize and maintain a video stream, establish a virtual channel to a - * sink monitor, and transmit the stream. - * - * Using AUX transactions to read/write from/to the sink's DisplayPort - * Configuration Data (DPCD) address space, the LPM obtains the link - * capabilities, obtains link configuration and link and sink status, and - * configures and controls the link and sink. The main link is trained this way. - * - * I2C-over-AUX transactions are used to obtain the sink's Extended Display - * Identification Data (EDID) which give information on the display capabilities - * of the monitor. The SPM may use this information to determine what available - * screen resolutions and video timing are possible. - * * Device configuration * * The device can be configured in various ways during the FPGA implementation - * process. Configuration parameters are stored in the xdptx_g.c file which is + * process. Configuration parameters are stored in the xdp_g.c file which is * generated when compiling the board support package (BSP). A table is defined * where each entry contains configuration information for the DisplayPort * instances present in the system. This information includes parameters that - * are defined in the driver's data/dptx.tcl file such as the base address of - * the memory-mapped device and the maximum number of lanes, maximum link rate, - * and video interface that the DisplayPort instance supports, among others. + * are defined in the driver's data/dp.tcl file such as the base address of the + * memory-mapped device and the maximum number of lanes, maximum link rate, and + * video interface that the DisplayPort instance supports, among others. * - * Interrupt processing + * The DisplayPort core may be configured in both transmitter (TX) or receiver + * (RX) modes of operation. Depending on which mode of operation the hardware is + * configured for, the set of registers associated with the core will be + * different. * - * DisplayPort interrupts occur on the HPD signal line when the DisplayPort - * cable is connected/disconnected or when the RX device sends a pulse. The user - * hardware design must contain an interrupt controller which the DisplayPort - * TX instance's interrupt signal is connected to. The user application must - * enable interrupts in the system and set up the interrupt controller such that - * the XDptx_HpdInterruptHandler handler will service DisplayPort interrupts. - * When the XDptx_HpdInterruptHandler function is invoked, the handler will - * identify what type of DisplayPort interrupt has occurred, and will call - * either the HPD event handler function or the HPD pulse handler function, - * depending on whether a an HPD event on an HPD pulse event occurred. + * Driver description * - * The DisplayPort TX's XDPTX_INTERRUPT_STATUS register indicates the type of - * interrupt that has occured, and the XDptx_HpdInterruptHandler will use this - * information to decide which handler to call. An HPD event is identified if - * bit XDPTX_INTERRUPT_STATUS_HPD_EVENT_MASK is set, and an HPD pulse is - * identified from the XDPTX_INTERRUPT_STATUS_HPD_PULSE_DETECTED_MASK bit. + * The DisplayPort (DP) driver consists of functions, structures, and + * definitions: + * 1) Specific to the DisplayPort TX mode of operation. + * - Prefix: XDptx_* and XDPTX_* + * 2) Specific to the DisplayPort RX mode of operation. + * - Prefix: XDprx_* and XDPRX_* + * 3) Common to both DisplayPort modes of operation. + * - Prefix: XDp_* and XDP_* * - * The HPD event handler may be set up by using the XDptx_SetHpdEventHandler - * function and, for the HPD pulse handler, the XDptx_SetHpdPulseHandler - * function. - * - * Multi-stream transport (MST) mode - * - * The driver handles MST mode functionality, including sideband messaging, - * topology discovery, virtual channel payload ID table management, and - * directing streams to different sinks. - * - * MST testing has been done at all possible link rate/lane count/topology/ - * resolution/color depth combinations with each setting using following values: - * - Link rate: 1.62, 2.70, and 5.40Gbps per lane. - * - Lane count: 1, 2, and 4 lanes. - * - Number of sink displays: 1, 2, 3, and 4 sink displays in both a daisy-chain - * configuration and in a configuration using a combination of a 1-to-3 hub - * and daisy-chain. Each stream was using the same resolution. - * - Resolutions (60Hz): 640x480, 800x600, 1024x768, 1280x800, 1280x1024, - * 1360x768, 1400x1050, 1680x1050, 1920x1080, 1920x2160, and 3840x2160. - * - Color depths: 18, 24, 30, 36, and 48 bits per pixel. - * - * Audio - * - * The driver does not handle audio. For an example as to how to configure and - * transmit audio, examples/xdptx_audio_example.c illustrates the required - * sequence. The user will need to configure the audio source connected to the - * Displayport TX instance and set up the audio info frame as per user - * requirements. + * Depending on whether the DisplayPort core is configured for TX or RX mode of + * operation, the set of registers and required functionality will be entirely + * different. + * - A detailed description of the DisplayPort TX functionality and + * associated functions may be found in xdptx.h. xdptx_hw.h contains + * definitions of the TX register space. + * - A detailed description of the DisplayPort RX functionality and + * associated functions may be found in xdprx.h. xdprx_hw.h contains + * definitions of the RX register space. * * Asserts * @@ -170,23 +118,6 @@ * it is recommended that application developers leave asserts on during * development. * - * Limitations - * - * - For MST mode to correctly display, the current version of the driver - * requires that each of the DisplayPort TX streams be allocated without - * skipping streams (i.e. assign stream 1, stream 2, and stream 3 - problems - * were experienced if skipping stream 2 and assigning stream 4 instead). - * skipping monitors in a daisy chain is OK as long as they are assigned to - * streams in order. - * - In MST mode, the current version of the driver does not support removal of - * an allocated stream from the virtual channel payload ID table without - * clearing the entire table. - * - Some sideband messages have not been implemented in the current version of - * the driver for MST mode. Notably, reception of a CONNECTION_STATUS_NOTIFY - * sideband message. - * - The driver does not handle audio. See the audio example in the driver - * examples directory for the required sequence for enabling audio. - * * @note For a 5.4Gbps link rate, a high performance 7 series FPGA is * required with a speed grade of -2 or -3. * @@ -211,7 +142,7 @@ /****************************** Type Definitions ******************************/ /** - * This typedef contains configuration information for the DisplayPort TX core. + * This typedef contains configuration information for the DisplayPort core. */ typedef struct { u16 DeviceId; /**< Device instance ID. */ @@ -258,7 +189,7 @@ typedef struct { * used, the user may implement their own wait implementation using a hardware * timer (see example/) for better accuracy. * - * @param InstancePtr is a pointer to the XDptx instance. + * @param InstancePtr is a pointer to the XDp instance. * @param MicroSeconds is the number of microseconds to be passed to the * timer function. * diff --git a/XilinxProcessorIPLib/drivers/dp/src/xdprx.c b/XilinxProcessorIPLib/drivers/dp/src/xdprx.c index 9b49e726..c1d80571 100644 --- a/XilinxProcessorIPLib/drivers/dp/src/xdprx.c +++ b/XilinxProcessorIPLib/drivers/dp/src/xdprx.c @@ -34,6 +34,10 @@ * * @file xdprx.c * + * Contains a minimal set of functions for the XDprx driver that allow access + * to all of the DisplayPort RX core's functionality. See xdprx.h for a detailed + * description of the driver. + * * @note None. * * 
diff --git a/XilinxProcessorIPLib/drivers/dp/src/xdprx.h b/XilinxProcessorIPLib/drivers/dp/src/xdprx.h
index ed8609ec..1dd8cd6a 100644
--- a/XilinxProcessorIPLib/drivers/dp/src/xdprx.h
+++ b/XilinxProcessorIPLib/drivers/dp/src/xdprx.h
@@ -34,6 +34,54 @@
  *
  * @file xdprx.h
  *
+ * The Xilinx DisplayPort receiver (DPRX) driver. This driver supports the
+ * Xilinx DisplayPort soft IP core in receive (RX) mode.
+ *
+ * Driver description
+ *
+ * The device driver enables higher-level software (e.g., an application) to
+ * configure and control a DisplayPort RX soft IP.
+ *
+ * This driver gives applications the ability to configure the RX using various
+ * settings, handle and issue interrupts, and modify a subset of its DisplayPort
+ * Configuration Data (DPCD) fields.
+ *
+ * Interrupt processing
+ *
+ * The DisplayPort RX driver may generate a pulse on the hot-plug-detect (HPD)
+ * signal line using the XDprx_GenerateHpdInterrupt function. This allows the RX
+ * to send an interrupt to the upstream TX device, useful for signaling the TX
+ * that it needs to do some checks for changes in downstream devices or a loss
+ * of link training.
+ *
+ * For RX interrupt handling of HPD events or events that happen internal to the
+ * RX, the user hardware design must contain an interrupt controller which the
+ * DisplayPort RX instance's interrupt signal is connected to. The user
+ * application must enable interrupts in the system and set up the interrupt
+ * controller such that the XDprx_InterruptHandler handler will service
+ * interrupts. When the XDprx_InterruptHandler function is invoked, the handler
+ * will identify what type of interrupt has occurred, and will call the
+ * appropriate interrupt handler.
+ *
+ * The DisplayPort RX's XDPRX_INTERRUPT_CAUSE register indicates the type of
+ * interrupt that has occured, and the XDprx_InterruptHandler will use this
+ * information to decide which handler to call.
+ *
+ * The handlers are set up using the XDprx_SetIntr* functions.
+ *
+ * Specific interrupts may be enabled or disabled using the
+ * XDprx_InterruptEnable and XDprx_InterruptDisable functions.
+ *
+ * Multi-stream transport (MST) mode
+ *
+ * The DisplayPort RX driver does not support MST functionality in 2015.1.
+ *
+ * Audio
+ *
+ * The driver does not handle audio.
+ *
+ * @note	None.
+ *
  * 
  * MODIFICATION HISTORY:
  * 

diff --git a/XilinxProcessorIPLib/drivers/dp/src/xdprx_intr.c b/XilinxProcessorIPLib/drivers/dp/src/xdprx_intr.c
index d4ebff8a..5d8e94ed 100644
--- a/XilinxProcessorIPLib/drivers/dp/src/xdprx_intr.c
+++ b/XilinxProcessorIPLib/drivers/dp/src/xdprx_intr.c
@@ -75,7 +75,7 @@ void XDprx_InterruptHandler(XDprx *InstancePtr)
 		IntrTp1, IntrTp2, IntrTp3;
 
 	/* Determine what kind of interrupt(s) occurred.
-	 * Note: XDPRX_INTERRUPT_STATUS is an RC (read-clear) register. */
+	 * Note: XDPRX_INTERRUPT_CAUSE is an RC (read-clear) register. */
 	IntrStatus = XDprx_ReadReg(InstancePtr->Config.BaseAddr,
 							XDPRX_INTERRUPT_CAUSE);
 	IntrVmChange = (IntrStatus & 0x00001);
diff --git a/XilinxProcessorIPLib/drivers/dp/src/xdptx.h b/XilinxProcessorIPLib/drivers/dp/src/xdptx.h
index c0955f3f..1b9a692d 100644
--- a/XilinxProcessorIPLib/drivers/dp/src/xdptx.h
+++ b/XilinxProcessorIPLib/drivers/dp/src/xdptx.h
@@ -38,41 +38,6 @@
  * Xilinx DisplayPort soft IP core in source (TX) mode. This driver follows the
  * DisplayPort 1.2a specification.
  *
- * The Xilinx DisplayPort soft IP supports the following features:
- *	- 1, 2, or 4 lanes.
- *	- A link rate of 1.62, 2.70, or 5.40Gbps per lane.
- *	- 1, 2, or 4 pixel-wide video interfaces.
- *	- RGB and YCbCr color space.
- *	- Up to 16 bits per component.
- *	- Up to 4Kx2K monitor resolution.
- *	- Auto lane rate and width negotiation.
- *	- I2C over a 1Mb/s AUX channel.
- *	- Secondary channel audio support (2 channels).
- *	- 4 independent video multi-streams.
- *
- * The Xilinx DisplayPort soft IP does not support the following features:
- *	- The automated test feature.
- *	- Audio (3-8 channel).
- *	- FAUX.
- *	- Bridging function.
- *	- MST audio.
- *	- eDP optional features.
- *	- iDP.
- *	- GTC.
- *
- * DisplayPort overview
- *
- * A DisplayPort link consists of:
- *	- A unidirectional main link which is used to transport isochronous data
- *	  streams such as video and audio. The main link may use 1, 2, or 4
- *	  lanes at a link rate of 1.62, 2.70, or 5.40Gbps per lane. The link
- *	  needs to be trained prior to sending streams.
- *	- An auxiliary (AUX) channel is a 1MBps bidirectional channel used for
- *	  link training, link management, and device control.
- *	- A hot-plug-detect (HPD) signal line is used to determine whether a
- *	  DisplayPort connection exists between the DisplayPort TX connector and
- *	  an RX device. It is serves as an interrupt request by the RX device.
- *
  * Driver description
  *
  * The device driver enables higher-level software (e.g., an application) to
@@ -103,17 +68,6 @@
  * of the monitor. The SPM may use this information to determine what available
  * screen resolutions and video timing are possible.
  *
- * Device configuration
- *
- * The device can be configured in various ways during the FPGA implementation
- * process.  Configuration parameters are stored in the xdptx_g.c file which is
- * generated when compiling the board support package (BSP). A table is defined
- * where each entry contains configuration information for the DisplayPort
- * instances present in the system. This information includes parameters that
- * are defined in the driver's data/dptx.tcl file such as the base address of
- * the memory-mapped device and the maximum number of lanes, maximum link rate,
- * and video interface that the DisplayPort instance supports, among others.
- *
  * Interrupt processing
  *
  * DisplayPort interrupts occur on the HPD signal line when the DisplayPort
@@ -162,14 +116,6 @@
  * Displayport TX instance and set up the audio info frame as per user
  * requirements.
  *
- * Asserts
- *
- * Asserts are used within all Xilinx drivers to enforce constraints on argument
- * values. Asserts can be turned off on a system-wide basis by defining, at
- * compile time, the NDEBUG identifier.  By default, asserts are turned on and
- * it is recommended that application developers leave asserts on during
- * development.
- *
  * Limitations
  *
  * - For MST mode to correctly display, the current version of the driver
@@ -187,8 +133,7 @@
  * - The driver does not handle audio. See the audio example in the driver
  *   examples directory for the required sequence for enabling audio.
  *
- * @note	For a 5.4Gbps link rate, a high performance 7 series FPGA is
- *		required with a speed grade of -2 or -3.
+ * @note	None.
  *
  * 
  * MODIFICATION HISTORY: