dptx: More documentation for Doxygen.

Signed-off-by: Andrei-Liviu Simion <andrei.simion@xilinx.com>

XilinxProcessorIPLib/drivers/dptx/examples/xdptx_example_common.h

@@ -57,6 +57,7 @@
 *******************************************************************************/
 
 #ifndef XDPTX_EXAMPLE_COMMON_H_
+/* Prevent circular inclusions by using protection macros. */
 #define XDPTX_EXAMPLE_COMMON_H_
 
 /******************************* Include Files ********************************/

XilinxProcessorIPLib/drivers/dptx/src/xdptx.c

@@ -63,16 +63,14 @@
 
 /**************************** Constant Definitions ****************************/
 
-/**
- * The maximum voltage swing and pre-emphasis level is 3.
- */
+/* The maximum voltage swing level is 3. */
 #define XDPTX_MAXIMUM_VS_LEVEL 3
+/* The maximum pre-emphasis level is 3. */
 #define XDPTX_MAXIMUM_PE_LEVEL 3
 
-/**
- * Error out if an AUX transactions exceeds these defer or timeout values.
- */
+/* Error out if an AUX request yields a defer reply more than 50 times. */
 #define XDPTX_AUX_MAX_DEFER_COUNT 50
+/* Error out if an AUX request times out more than 50 times awaiting a reply. */
 #define XDPTX_AUX_MAX_TIMEOUT_COUNT 50
 
 /****************************** Type Definitions ******************************/
@@ -94,10 +92,17 @@ typedef enum {
  * This typedef describes an AUX transaction.
  */
 typedef struct {
-	u16 CmdCode;
-	u8 NumBytes;
-	u32 Address;
-	u8 *Data;
+	u16 CmdCode;		/**< The AUX command code that specifies what
+					type of AUX transaction is taking
+					place. */
+	u8 NumBytes;		/**< The number of bytes that the AUX
+					transaction will perform work on. */
+	u32 Address;		/**< The AUX or I2C start address that the AUX
+					transaction will perform work on. */
+	u8 *Data;		/**< The data buffer that will store the data
+					read from AUX read transactions or the
+					data to write for AUX write
+					transactions. */
 } XDptx_AuxTransaction;
 
 /**************************** Function Prototypes *****************************/

XilinxProcessorIPLib/drivers/dptx/src/xdptx.h

@@ -35,7 +35,8 @@
  * @file xdptx.h
  *
  * The Xilinx DisplayPort transmitter (DPTX) driver. This driver supports the
- * Xilinx DisplayPort soft IP core in source (TX) mode.
+ * 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.
@@ -171,8 +172,9 @@
  *
 *******************************************************************************/
 
-#ifndef XDPTX_H_ /* Prevent circular inclusions */
-#define XDPTX_H_ /* by using protection macros. */
+#ifndef XDPTX_H_
+/* Prevent circular inclusions by using protection macros. */
+#define XDPTX_H_
 
 /******************************* Include Files ********************************/
 
@@ -306,13 +308,16 @@ typedef enum {
  */
 typedef struct {
 	XDptx_VideoMode	VideoMode;	/**< Enumerated key. */
-	u8 DmtId;			/**< Standard DMT ID number. */
+	u8 DmtId;			/**< Standard Display Monitor Timing
+						(DMT) ID number. */
 	u16 HResolution;		/**< Horizontal resolution. */
 	u16 VResolution;		/**< Vertical resolution. */
 	u32 PixelClkKhz;		/**< Pixel frequency (in KHz). */
 	u8 Scan;			/**< Interlaced/non-interlaced. */
-	u8 HSyncPolarity;		/**< Horizontal polarity. */
-	u8 VSyncPolarity;		/**< Vertical polarity. */
+	u8 HSyncPolarity;		/**< Horizontal synchronization
+						polarity. */
+	u8 VSyncPolarity;		/**< Vertical synchronization
+						polarity. */
 	u32 HFrontPorch;		/**< Horizontal front porch. */
 	u32 HSyncPulseWidth;		/**< Horizontal synchronization pulse
 						width. */
@@ -416,31 +421,55 @@ typedef struct {
  * video will be displayed.
  */
 typedef struct {
-	u32 HClkTotal;
-	u32 VClkTotal;
-	u32 HSyncPulseWidth;
-	u32 VSyncPulseWidth;
-	u32 HResolution;
-	u32 VResolution;
-	u32 HSyncPolarity;
-	u32 VSyncPolarity;
-	u32 HStart;
-	u32 VStart;
-	u32 VBackPorch;
-	u32 VFrontPorch;
-	u32 HBackPorch;
-	u32 HFrontPorch;
-	u32 Misc0;
-	u32 Misc1;
-	u32 MVid;
-	u32 NVid;
-	u32 TransferUnitSize;
-	u32 UserPixelWidth;
-	u32 DataPerLane;
-	u32 AvgBytesPerTU;
-	u32 InitWait;
-	u32 Interlaced;
-	u32 BitsPerColor;
+	u32 HClkTotal;			/**< Horizontal total time (in
+						pixels). */
+	u32 VClkTotal;			/**< Vertical total time (in pixels). */
+	u32 HSyncPulseWidth;		/**< Horizontal synchronization time (in
+						pixels). */
+	u32 VSyncPulseWidth;		/**< Vertical synchronization time (in
+						lines */
+	u32 HResolution;		/**< Horizontal resolution (in
+						pixels). */
+	u32 VResolution;		/**< Vertical resolution (in lines). */
+	u32 HSyncPolarity;		/**< Horizontal synchronization polarity
+						(0=positive/1=negative). */
+	u32 VSyncPolarity;		/**< Vertical synchronization polarity
+						(0=positive/1=negative). */
+	u32 HStart;			/**< Horizontal blank start (in
+						pixels). */
+	u32 VStart;			/**< Vertical blank start (in lines). */
+	u32 VBackPorch;			/**< Vertical back porch (in lines). */
+	u32 VFrontPorch;		/**< Vertical front porch (in lines). */
+	u32 HBackPorch;			/**< Horizontal back porch (in
+						pixels). */
+	u32 HFrontPorch;		/**< Horizontal front porch (in
+						pixels). */
+	u32 Misc0;			/**< Miscellaneous stream attributes 0
+						as specified by the DisplayPort
+						1.2 specification. */
+	u32 Misc1;			/**< Miscellaneous stream attributes 1
+						as specified by the DisplayPort
+						1.2 specification. */
+	u32 MVid;			/**< M value for the video stream. This
+						value is equal to the pixel
+						clock in KHz. */
+	u32 NVid;			/**< N value for the video stream. */
+	u32 TransferUnitSize;		/**< Size of the transfer unit in the
+						framing logic. */
+	u32 UserPixelWidth;		/**< The width of the user data input
+						port. */
+	u32 DataPerLane;		/**< Used to translate the number of
+						pixels per line to the native
+						internal 16-bit datapath. */
+	u32 AvgBytesPerTU;		/**< Average number of bytes per
+						transfer unit, scaled up by a
+						factor of 1000. */
+	u32 InitWait;			/**< Number of initial wait cycles at
+						the start of a new line by
+						the framing logic. */
+	u32 Interlaced;			/**< Input stream is interlaced. */
+	u32 BitsPerColor;		/**< Number of bits per color
+						component. */
 } XDptx_MainStreamAttributes;
 
 /******************************************************************************/

XilinxProcessorIPLib/drivers/dptx/src/xdptx_hw.h

@@ -50,8 +50,9 @@
  *
 *******************************************************************************/
 
-#ifndef XDPTX_HW_H_ /* Prevent circular inclusions */
-#define XDPTX_HW_H_ /* by using protection macros. */
+#ifndef XDPTX_HW_H_
+/* Prevent circular inclusions by using protection macros. */
+#define XDPTX_HW_H_
 
 /***************************** Include Files **********************************/
 

XilinxProcessorIPLib/drivers/dptx/src/xdptx_vidmodetable.c

@@ -57,7 +57,21 @@
 
 /**
  * This table contains the main stream attributes for various standard
- * resolutions.
+ * resolutions. Each entry is of the format:
+ * 1) XDPTX_VM_<HRES>x<VRES>_<REFRESH (HZ)>_P(_RB = Reduced Blanking)
+ * 2) Display Monitor Timing (DMT) ID
+ * 3) Horizontal resolution (pixels)
+ * 4) Vertical resolution (lines)
+ * 5) Pixel clock (KHz)
+ * 6) Scan (0=non-interlaced|1=interlaced)
+ * 7) Horizontal sync polarity (0=positive|1=negative)
+ * 8) Vertical sync polarity (0=positive|1=negative)
+ * 9) Horizontal front porch (pixels)
+ * 10) Horizontal sync time (pixels)
+ * 11) Horizontal back porch (pixels)
+ * 12) Vertical front porch (lines)
+ * 13) Vertical sync time (lines)
+ * 14) Vertical back porch (lines)
  */
 XDptx_DmtMode XDptx_DmtModes[] =
 {