From 653c4624dd4e25a05afe8297edc6018e1c8dcb1d Mon Sep 17 00:00:00 2001
From: Andrei-Liviu Simion <andrei.simion@xilinx.com>
Date: Tue, 29 Jul 2014 14:36:14 -0700
Subject: [PATCH] dptx: Added an audio example.

The user needs to implement Dptx_ConfigureAudioSrc and Dptx_AudioSendInfoFrame
as these functions are application-specific.

Signed-off-by: Andrei-Liviu Simion <andrei.simion@xilinx.com>
---
 .../drivers/dptx/examples/index.html          |   1 +
 .../drivers/dptx/examples/readme.txt          |  22 +-
 .../dptx/examples/xdptx_audio_example.c       | 262 ++++++++++++++++++
 .../dptx/examples/xdptx_example_common.h      |   3 +
 .../dptx/examples/xdptx_intr_example.c        |   4 -
 .../dptx/examples/xdptx_poll_example.c        |   4 -
 .../dptx/examples/xdptx_selftest_example.c    |   4 -
 .../dptx/examples/xdptx_timer_example.c       |   4 -
 XilinxProcessorIPLib/drivers/dptx/src/xdptx.h |  14 +-
 9 files changed, 296 insertions(+), 22 deletions(-)
 create mode 100644 XilinxProcessorIPLib/drivers/dptx/examples/xdptx_audio_example.c

diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/index.html b/XilinxProcessorIPLib/drivers/dptx/examples/index.html
index b2e4baaa..0a79dcc3 100755
--- a/XilinxProcessorIPLib/drivers/dptx/examples/index.html
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/index.html
@@ -10,6 +10,7 @@
 <h1> Example applications for the dptx driver. </h1>
 <HR>
 <ul>
+  <li>xdptx_audio_example.c <a href="xdptx_audio_example.c">(source)</a> </li>
   <li>xdptx_intr_example.c <a href="xdptx_intr_example.c">(source)</a> </li>
   <li>xdptx_poll_example.c <a href="xdptx_poll_example.c">(source)</a> </li>
   <li>xdptx_selftest_example.c <a href="xdptx_selftest_example.c">(source)</a> </li>
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/readme.txt b/XilinxProcessorIPLib/drivers/dptx/examples/readme.txt
index be07100a..9d7633e5 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/readme.txt
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/readme.txt
@@ -1,13 +1,25 @@
-There are 4 examples included in this directory:
-1) xdptx_intr_example.c : This interrupt example shows how to set up the
+There are 5 examples included in this directory:
+1) xdptx_audio_example.c : This audio example, apart from training the main link
+   and outputting video, illustrates the sequence required for setting up audio
+   in the DisplayPort TX. This example requires that an audio source, such as a
+   S/PDIF instance be present and connected to the DisplayPort TX in the
+   hardware system, and for the audio enable configuration parameter to be set
+   for the instantiated DisplayPort TX. For audio to output, the user will need
+   to implement the following functions:
+   a) Dptx_ConfigureAudioSrc : This function needs to configure the audio source
+      to output to the DisplayPort TX.
+   b) Dptx_AudioSendInfoFrame : This function needs to set up and write an audio
+      info frame as per user requirements.
+
+2) xdptx_intr_example.c : This interrupt example shows how to set up the
    interrupt system and specify the interrupt handlers for when a DisplayPort
    interrupt event occurs. An interrupt controller with a connection to the
    DisplayPort interrupt signal needs to exist in the hardware system.
 
-2) xdptx_poll_example.c : This interrupt example shows how to poll the
+3) xdptx_poll_example.c : This interrupt example shows how to poll the
    DisplayPort TX instance's registers for DisplayPort interrupt events.
 
-3) xdptx_timer_example.c : This timer example shows how to override the default
+4) xdptx_timer_example.c : This timer example shows how to override the default
    sleep/delay functionality for MicroBlaze. A timer needs to exist in the
    hardware system and will be used for sleep/delay functionality inside of a
    callback function. The default behavior in MicroBlaze for sleep/delay is to
@@ -15,7 +27,7 @@ There are 4 examples included in this directory:
    For ARM/Zynq SoC systems, the supplied callback function will be ignored -
    the usleep function will be called since the SoC has a timer built-in.
 
-4) xdptx_selftest_example.c : This self test example will perform a sanity check
+5) xdptx_selftest_example.c : This self test example will perform a sanity check
    on the state of the DisplayPort TX instance. It may be called prior to usage
    of the core or after a reset to ensure that (a subset of) the registers hold
    the default values.
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_audio_example.c b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_audio_example.c
new file mode 100644
index 00000000..2803994a
--- /dev/null
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_audio_example.c
@@ -0,0 +1,262 @@
+/*******************************************************************************
+ *
+ * Copyright (C) 2014 Xilinx, Inc.  All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * Use of the Software is limited solely to applications:
+ * (a) running on a Xilinx device, or
+ * (b) that interact with a Xilinx device through a bus or interconnect. 
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * XILINX CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+ * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * Except as contained in this notice, the name of the Xilinx shall not be used
+ * in advertising or otherwise to promote the sale, use or other dealings in
+ * this Software without prior written authorization from Xilinx.
+ *
+*******************************************************************************/
+/******************************************************************************/
+/**
+ *
+ * @file xdptx_audio_example.c
+ *
+ * Contains a design example using the XDptx driver to train the main link and
+ * to display video. In this example application, the sequence to enable audio
+ * is illustrated.
+ *
+ * @note        This example requires an audio source such as an S/PDIF instance
+ *              to be part of the hardware system. See XAPP1178 for reference.
+ * @note        This example requires that the audio enable configuration
+ *              parameter for DisplayPort be turned on when creating the
+ *              hardware design.
+ * @note        For this example to output audio, the user will need to
+ *              implement initialization of the system (Dptx_PlatformInit),
+ *              configuration of the audio source (Dptx_ConfigureAudioSrc) and,
+ *              depending on the hardware system, will need to implement sending
+ *              of an info frame (Dptx_AudioSendInfoFrame). See XAPP1178 and the
+ *              IP documentation for reference.
+ * @note        For this example to display output, after training is complete,
+ *              the user will need to implement configuration of the video
+ *              stream source in order to provide the DisplayPort core with
+ *              input (Dptx_ConfigureStreamSrc - called in
+ *              xdptx_example_common.c). See XAPP1178 for reference.
+ * @note        The functions Dptx_PlatformInit and Dptx_ConfigureStreamSrc are
+ *              declared extern in xdptx_example_common.h and are left up to the
+ *              user to implement. The functions Dptx_ConfigureAudioSrc and
+ *              Dptx_AudioSendInfoFrame are present in this file and are also
+ *              left for the user to implement. 
+ *
+ * <pre>
+ * MODIFICATION HISTORY:
+ *
+ * Ver   Who  Date     Changes
+ * ----- ---- -------- -----------------------------------------------
+ * 1.00a als  07/29/14 Initial creation.
+ * </pre>
+ *
+*******************************************************************************/
+
+/******************************* Include Files ********************************/
+
+#include "xdptx_example_common.h"
+
+/**************************** Function Prototypes *****************************/
+
+u32 Dptx_AudioExample(XDptx *InstancePtr, u16 DeviceId);
+static void Dptx_AudioInit(XDptx *InstancePtr);
+static void Dptx_ConfigureAudioSrc(XDptx *InstancePtr);
+static void Dptx_AudioSendInfoFrame(XDptx *InstancePtr);
+
+/**************************** Function Definitions ****************************/
+
+/******************************************************************************/
+/**
+ * This function is the main function of the XDptx audio example.
+ *
+ * @param       None.
+ *
+ * @return      - XST_SUCCESS if the audio example finished successfully.
+ *              - XST_FAILURE otherwise.
+ *
+ * @note        None.
+ *
+*******************************************************************************/
+int main(void)
+{
+        int Status;
+
+        /* Run the XDptx audio example. */
+        Status = Dptx_AudioExample(&DptxInstance, DPTX_DEVICE_ID);
+        if (Status != XST_SUCCESS) {
+                return XST_FAILURE;
+        }
+
+        return XST_SUCCESS;
+}
+
+/******************************************************************************/
+/**
+ * The main entry point for the audio example using the XDptx driver. This
+ * function will set up audio, initiate link training, and a video stream will
+ * start being sent over the main link.
+ *
+ * @param       InstancePtr is a pointer to the XDptx instance.
+ * @param       DeviceId is the unique device ID of the DisplayPort TX core
+ *              instance.
+ *
+ * @return      - XST_SUCCESS if the system was set up correctly and link
+ *                training was successful.
+ *              - XST_FAILURE otherwise.
+ *
+ * @note        None.
+ *
+*******************************************************************************/
+u32 Dptx_AudioExample(XDptx *InstancePtr, u16 DeviceId)
+{
+        u32 Status;
+
+        /* Do platform initialization here. This is hardware system specific -
+         * it is up to the user to implement this function. */
+        Dptx_PlatformInit();
+        /*******************/
+
+        Status = Dptx_SetupExample(InstancePtr, DeviceId);
+        if (Status != XST_SUCCESS) {
+                return XST_FAILURE;
+        }
+
+        /* Initialize DisplayPort audio. */
+        Dptx_AudioInit(InstancePtr);
+
+        XDptx_EnableTrainAdaptive(InstancePtr, TRAIN_ADAPTIVE);
+        XDptx_SetHasRedriverInPath(InstancePtr, TRAIN_HAS_REDRIVER);
+
+        /* A sink monitor must be connected at this point. See the polling or
+         * interrupt examples for how to wait for a connection event. */
+        Status = Dptx_Run(InstancePtr);
+        if (Status != XST_SUCCESS) {
+                return XST_FAILURE;
+        }
+
+        return XST_SUCCESS;
+}
+
+/******************************************************************************/
+/**
+ * This function will set up audio in the DisplayPort TX. The user will need
+ * to implement configuration of the audio stream and, if needed, sending of
+ * the info frame.
+ *
+ * @param       InstancePtr is a pointer to the XDptx instance.
+ *
+ * @return      None.
+ *
+ * @note        The user needs to implement the Dptx_ConfigureAudioSrc and
+ *              the Dptx_AudioSendInfoFrame functions to fulfill audio
+ *              initialization.
+ *
+*******************************************************************************/
+static void Dptx_AudioInit(XDptx *InstancePtr)
+{
+        u32 Fs;
+        u32 MAud;
+        u32 NAud;
+        u32 NumChs;
+
+        /* Disable audio in the DisplayPort TX. This will also flush the buffers
+         * in the DisplayPort TX and set MUTE bit in VB-ID. */
+        XDptx_WriteReg(InstancePtr->Config.BaseAddr, XDPTX_TX_AUDIO_CONTROL,
+                                                                        0x0);
+
+        /* Configure the audio source (the S/PDIF controller). It is up to the
+         * user to implement this function. */
+        Dptx_ConfigureAudioSrc(InstancePtr);
+        /*******************/
+
+        /* Write audio info frame as per user requirements. This may be optional
+         * for some systems. 8 writes are required to register
+         * XDPTX_TX_AUDIO_INFO_DATA. It is up to the user to implement this
+         * function. */
+        Dptx_AudioSendInfoFrame(InstancePtr);
+        /*******************/
+
+        Fs = 48; /* KHz (32 | 44.1 | 48) */
+        if (InstancePtr->LinkConfig.LinkRate == XDPTX_LINK_BW_SET_540GBPS) {
+                MAud = 512 * Fs;
+        }
+        else if (InstancePtr->LinkConfig.LinkRate ==
+                                                XDPTX_LINK_BW_SET_270GBPS) {
+                MAud = 512 * Fs;
+        }
+        else if (InstancePtr->LinkConfig.LinkRate ==
+                                                XDPTX_LINK_BW_SET_162GBPS) {
+                MAud = 512 * Fs;
+        }
+
+        /* Write the channel count. The value is (actual count - 1). */
+        NumChs = 2;
+        XDptx_WriteReg(InstancePtr->Config.BaseAddr, XDPTX_TX_AUDIO_CHANNELS,
+                                                                NumChs - 1);
+
+        /* NAud = 540000 | 270000 | 162000 */
+        NAud = 27 * InstancePtr->LinkConfig.LinkRate * 1000;
+
+        XDptx_WriteReg(InstancePtr->Config.BaseAddr, XDPTX_TX_AUDIO_MAUD, MAud);
+        XDptx_WriteReg(InstancePtr->Config.BaseAddr, XDPTX_TX_AUDIO_NAUD, NAud);
+
+        /* Enable audio in the DisplayPort TX. */
+        XDptx_WriteReg(InstancePtr->Config.BaseAddr, XDPTX_TX_AUDIO_CONTROL,
+                                                                        0x1);
+}
+
+/******************************************************************************/
+/**
+ * This function needs to configure the audio source.
+ *
+ * @param       InstancePtr is a pointer to the XDptx instance.
+ *
+ * @return      None.
+ *
+ * @note        The user needs to implement this. See XAPP1178 and the IP
+ *              documentation for reference.
+ *
+*******************************************************************************/
+static void Dptx_ConfigureAudioSrc(XDptx *InstancePtr)
+{
+        xil_printf("Dptx_ConfigureAudioSrc: User defined function here.\n");
+}
+
+/******************************************************************************/
+/**
+ * This function needs to send an info frame as per user requirements.
+ *
+ * @param       InstancePtr is a pointer to the XDptx instance.
+ *
+ * @return      None.
+ *
+ * @note        The user needs to implement this. See XAPP1178 and the IP
+ *              documentation for reference.
+ * @note        This may be optional for some systems.
+ * @note        A sequence of 8 writes are required to register
+ *              XDPTX_TX_AUDIO_INFO_DATA. See XAPP1178 and the IP documentation
+ *              for reference.
+ *
+*******************************************************************************/
+static void Dptx_AudioSendInfoFrame(XDptx *InstancePtr)
+{
+        xil_printf("Dptx_AudioSendInfoFrame: User defined function here.\n");
+}
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_example_common.h b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_example_common.h
index 3c4af098..ea1b4c12 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_example_common.h
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_example_common.h
@@ -62,7 +62,10 @@
 /******************************* Include Files ********************************/
 
 #include "xdptx.h"
+#include "xil_printf.h"
 #include "xil_types.h"
+#include "xparameters.h"
+#include "xstatus.h"
 
 /**************************** Constant Definitions ****************************/
 
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_intr_example.c b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_intr_example.c
index 1bbd43b1..291457d4 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_intr_example.c
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_intr_example.c
@@ -62,11 +62,7 @@
 
 /******************************* Include Files ********************************/
 
-#include "xdptx.h"
 #include "xdptx_example_common.h"
-#include "xil_printf.h"
-#include "xparameters.h"
-#include "xstatus.h"
 #ifdef XPAR_INTC_0_DEVICE_ID
 /* For MicroBlaze systems. */
 #include "xintc.h"
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_poll_example.c b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_poll_example.c
index 2a6f2c56..837e7fd7 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_poll_example.c
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_poll_example.c
@@ -60,11 +60,7 @@
 
 /******************************* Include Files ********************************/
 
-#include "xdptx.h"
 #include "xdptx_example_common.h"
-#include "xil_printf.h"
-#include "xparameters.h"
-#include "xstatus.h"
 
 /**************************** Function Prototypes *****************************/
 
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_selftest_example.c b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_selftest_example.c
index 6833c05b..2e3cb4b5 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_selftest_example.c
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_selftest_example.c
@@ -50,11 +50,7 @@
 
 /******************************* Include Files ********************************/
 
-#include "xdptx.h"
 #include "xdptx_example_common.h"
-#include "xil_printf.h"
-#include "xparameters.h"
-#include "xstatus.h"
 
 /**************************** Function Prototypes *****************************/
 
diff --git a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_timer_example.c b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_timer_example.c
index bee81a05..7ec18103 100644
--- a/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_timer_example.c
+++ b/XilinxProcessorIPLib/drivers/dptx/examples/xdptx_timer_example.c
@@ -63,11 +63,7 @@
 
 /******************************* Include Files ********************************/
 
-#include "xdptx.h"
 #include "xdptx_example_common.h"
-#include "xil_printf.h"
-#include "xparameters.h"
-#include "xstatus.h"
 #include "xtmrctr.h"
 
 /**************************** Function Prototypes *****************************/
diff --git a/XilinxProcessorIPLib/drivers/dptx/src/xdptx.h b/XilinxProcessorIPLib/drivers/dptx/src/xdptx.h
index c1ec29ce..c43184db 100644
--- a/XilinxProcessorIPLib/drivers/dptx/src/xdptx.h
+++ b/XilinxProcessorIPLib/drivers/dptx/src/xdptx.h
@@ -136,6 +136,14 @@
  * function and, for the HPD pulse handler, the XDptx_SetHpdPulseHandler
  * function.
  *
+ * <b>Audio</b>
+ *
+ * The driver does not handle audio. For an example as to how to configure and
+ * transmit audio, dptx/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.
+ *
  * <b>Asserts</b>
  *
  * Asserts are used within all Xilinx drivers to enforce constraints on argument
@@ -144,7 +152,11 @@
  * it is recommended that application developers leave asserts on during
  * development.
  *
- * The driver currently supports single-stream transport (SST) functionality.
+ * <b>Limitations</b>
+ *
+ * - The driver currently supports single-stream transport (SST) functionality.
+ * - 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.