2016.4 xuartps_polled_example.c Comments and Explanation


This post lists additional comments and explanation on the 2016.4 release of xuartps_polled_example.c from: https://github.com/Xilinx/embeddedsw/blob/xilinx-v2016.4/XilinxProcessorIPLib/drivers/uartps/examples/xuartps_polled_example.c


Need Help?


Click https://www.centennialsoftwaresolutions.com/post/import-xuartps_polled_example-c-into-a-xilinx-sdk-project if you need help bringing this example into and SDK project


Comments and Additional Explanation


/******************************************************************************

*

* Copyright (C) 2010 - 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

* XILINX 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 xuartps_polled_example.c

*

* This file contains an example using the XUartPs driver in polled mode.

*

* This function sends data and expects to receive the data thru the device

* using the local loopback mode.

*

* @note

* If the device does not work properly, the example may hang.

*

* MODIFICATION HISTORY:

* <pre>

* Ver Who Date Changes

* ----- ------ -------- -----------------------------------------------

* 1.00a drg/jz 01/13/10 First Release

* 1.03a sg 07/16/12 Modified the device ID to use the first Device Id

* Removed the printf at the start of the main

* </pre>

******************************************************************************/


/***************************** Include Files *********************************/


#include "xparameters.h"

#include "xuartps.h"

#include "xil_printf.h"


/************************** Constant Definitions *****************************/


/*

* The following constants map to the XPAR parameters created in the

* xparameters.h file. They are defined here such that a user can easily

* change all the needed parameters in one place.

*/

#define UART_DEVICE_ID XPAR_XUARTPS_0_DEVICE_ID


Where is XPAR_XUARTPS_0_DEVICE_ID defined?


XPAR_XUARTPS_0_DEVICE_ID comes from xparameters.h in the ps7_cortexa9_0/include/ directory of the BSP project used in the Xilinx SDK project.


In xparameters.h you'll see:


/* Canonical definitions for peripheral PS7_UART_0 */

#define XPAR_XUARTPS_0_DEVICE_ID XPAR_PS7_UART_0_DEVICE_ID

#define XPAR_XUARTPS_0_BASEADDR 0xE0000000

#define XPAR_XUARTPS_0_HIGHADDR 0xE0000FFF

#define XPAR_XUARTPS_0_UART_CLK_FREQ_HZ 100000000

#define XPAR_XUARTPS_0_HAS_MODEM 0


Where is XPAR_PS7_UART_0_DEVICE_ID defined?


XPAR_PS7_UART_0_DEVICE_ID is defined right above:

/* Definitions for peripheral PS7_UART_0 */

#define XPAR_PS7_UART_0_DEVICE_ID 0

#define XPAR_PS7_UART_0_BASEADDR 0xE0000000

#define XPAR_PS7_UART_0_HIGHADDR 0xE0000FFF

#define XPAR_PS7_UART_0_UART_CLK_FREQ_HZ 100000000

#define XPAR_PS7_UART_0_HAS_MODEM 0


Steps to Find where the Include Path is Specified


Step #1: Right-click on your SDK project

Step #2: Select C/C++ Build Settings

Step #3: Select ARM v7 gcc compiler

The include path is specified in the All options: window


/*

* The following constant controls the length of the buffers to be sent

* and received with the device, this constant must be 32 bytes or less since

* only as much as FIFO size data can be sent or received in polled mode.

*/

#define TEST_BUFFER_SIZE 32


/**************************** Type Definitions *******************************/


/***************** Macros (Inline Functions) Definitions *********************/


/************************** Function Prototypes ******************************/


int UartPsPolledExample(u16 DeviceId);


/************************** Variable Definitions *****************************/


XUartPs Uart_PS; /* Instance of the UART Device */


Where is XUartPs defined?


XUartPs is defined in xuartps.h in the ps7_cortexa9_0/include/ directory of the BSP project used in the Xilinx SDK project.


How is XUartPs defined?


/**

* The XUartPs driver instance data structure. A pointer to an instance data

* structure is passed around by functions to refer to a specific driver

* instance.

*/

typedef struct {

XUartPs_Config Config; /* Configuration data structure */

u32 InputClockHz; /* Input clock frequency */

u32 IsReady; /* Device is initialized and ready */

u32 BaudRate; /* Current baud rate */


XUartPsBuffer SendBuffer;

XUartPsBuffer ReceiveBuffer;


XUartPs_Handler Handler;

void *CallBackRef; /* Callback reference for event handler */

u32 Platform;

u8 is_rxbs_error;

} XUartPs;


/*

* The following buffers are used in this example to send and receive data

* with the UART.

*/

static u8 SendBuffer[TEST_BUFFER_SIZE]; /* Buffer for Transmitting Data */

static u8 RecvBuffer[TEST_BUFFER_SIZE]; /* Buffer for Receiving Data */


Why are these buffers 32 bytes?

I'm not sure. The receive FIFO is 64 bytes and the transmit FIFO is 64 bytes as listed on page 590 of the Zynq-7000 TRM [link].


/*****************************************************************************/

/**

*

* Main function to call the Uart Polled mode example.

*

* @param None

*

* @return XST_SUCCESS if succesful, otherwise XST_FAILURE

*

* @note None

*

******************************************************************************/

#ifndef TESTAPP_GEN

int main(void)

{

int Status;



/*

* Run the Uart_PS polled example , specify the the Device ID that is

* generated in xparameters.h

*/

Status = UartPsPolledExample(UART_DEVICE_ID);

if (Status != XST_SUCCESS) {

xil_printf("UART Polled Mode Example Test Failed\r\n");

return XST_FAILURE;

}


xil_printf("Successfully ran UART Polled Mode Example Test\r\n");


Does the xil_printf still work?

There appears to be a problem here, but there isn't. xil_printf() uses UART0 in Normal Mode (see page 598 of the Zynq-7000 TRM [link]). UartPsPolledExample() also uses UART0 and places UART0 into Local Loopback Mode. It appears that xil_printf() wouldn't work. However, xil_printf() does still work because UartPsPolledExample() restores UART0 to Normal Mode.


return XST_SUCCESS;

}

#endif

/*****************************************************************************/

/**

*

* This function does a minimal test on the XUartPs device in polled mode.

*

* This function sends data and expects to receive the data thru the UART

* using the local loopback mode.

*

*

* @param DeviceId is the unique device id from hardware build.

*

* @return XST_SUCCESS if successful, XST_FAILURE if unsuccessful

*

* @note

* This function polls the UART, it may hang if the hardware is not

* working correctly.

*

****************************************************************************/

int UartPsPolledExample(u16 DeviceId)

{

int Status;

XUartPs_Config *Config;

unsigned int SentCount;

unsigned int ReceivedCount;

u16 Index;

u32 LoopCount = 0;


/*

* Initialize the UART driver so that it's ready to use.

* Look up the configuration in the config table, then initialize it.

*/

Config = XUartPs_LookupConfig(DeviceId);

if (NULL == Config) {

return XST_FAILURE;

}


Where is XUartPs_LookupConfig() and what does it do?


XUartPs_LookupConfig() is located in xuart_sint.c which is located in the ps7_cortexa9_0/libsrc/uartps_v3_3/src/ directory of the BSP project used in the Xilinx SDK project.


It performs the following operations:


/****************************************************************************/

/**

*

* Looks up the device configuration based on the unique device ID. The table

* contains the configuration info for each device in the system.

*

* @param DeviceId contains the ID of the device

*

* @return A pointer to the configuration structure or NULL if the

* specified device is not in the system.

*

* @note None.

*

******************************************************************************/

XUartPs_Config *XUartPs_LookupConfig(u16 DeviceId)

{

XUartPs_Config *CfgPtr = NULL;


u32 Index;


for (Index = 0U; Index < (u32)XPAR_XUARTPS_NUM_INSTANCES; Index++) {

if (XUartPs_ConfigTable[Index].DeviceId == DeviceId) {

CfgPtr = &XUartPs_ConfigTable[Index];

break;

}

}


return (XUartPs_Config *)CfgPtr;

}


Where is XUartPs_ConfigTable[] defined and what does it contain?


XUartPs_ConfigTable[] is defined in xuartps_g.c which is included in