1 /******************************************************************************
3 * Copyright (C) 2010 - 2015 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /****************************************************************************/
36 * @addtogroup devcfg_v3_3
40 * The is the main header file for the Device Configuration Interface of the Zynq
41 * device. The device configuration interface has three main functionality.
45 * This current version of the driver supports only the AXI-PCAP and Security
46 * Policy blocks. There is a separate driver for XADC.
48 * AXI-PCAP is used for download/upload an encrypted or decrypted bitstream.
49 * DMA embedded in the AXI PCAP provides the master interface to
50 * the Device configuration block for any DMA transfers. The data transfer can
51 * take place between the Tx/RxFIFOs of AXI-PCAP and memory (on chip
52 * RAM/DDR/peripheral memory).
54 * The current driver only supports the downloading the FPGA bitstream and
55 * readback of the decrypted image (sort of loopback).
56 * The driver does not know what information needs to be written to the FPGA to
57 * readback FPGA configuration register or memory data. The application above the
58 * driver should take care of creating the data that needs to be downloaded to
59 * the FPGA so that the bitstream can be readback.
60 * This driver also does not support the reading of the internal registers of the
61 * PCAP. The driver has no knowledge of the PCAP internals.
63 * <b> Initialization and Configuration </b>
65 * The device driver enables higher layer software (e.g., an application) to
66 * communicate with the Device Configuration device.
68 * XDcfg_CfgInitialize() API is used to initialize the Device Configuration
69 * Interface. The user needs to first call the XDcfg_LookupConfig() API which
70 * returns the Configuration structure pointer which is passed as a parameter to
71 * the XDcfg_CfgInitialize() API.
74 * The Driver implements an interrupt handler to support the interrupts provided
79 * This driver is not thread safe. Any needs for threads or thread mutual
80 * exclusion must be satisfied by the layer above this driver.
84 * Asserts are used within all Xilinx drivers to enforce constraints on argument
85 * values. Asserts can be turned off on a system-wide basis by defining, at
86 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
87 * is recommended that users leave asserts on during development.
89 * <b> Building the driver </b>
91 * The XDcfg driver is composed of several source files. This allows the user
92 * to build and link only those parts of the driver that are necessary.
97 * MODIFICATION HISTORY:
99 * Ver Who Date Changes
100 * ----- --- -------- ---------------------------------------------
101 * 1.00a hvm 02/07/11 First release
102 * 2.00a nm 05/31/12 Updated the driver for CR 660835 so that input length for
103 * source/destination to the XDcfg_InitiateDma, XDcfg_Transfer
104 * APIs is words (32 bit) and not bytes.
105 * Updated the notes for XDcfg_InitiateDma/XDcfg_Transfer APIs
106 * to add information that 2 LSBs of the Source/Destination
107 * address when equal to 2�b01 indicate the last DMA command
108 * of an overall transfer.
109 * Destination Address passed to this API for secure transfers
110 * instead of using 0xFFFFFFFF for CR 662197. This issue was
111 * resulting in the failure of secure transfers of
112 * non-bitstream images.
113 * 2.01a nm 07/07/12 Updated the XDcfg_IntrClear function to directly
114 * set the mask instead of oring it with the
115 * value read from the interrupt status register
116 * Added defines for the PS Version bits,
117 * removed the FIFO Flush bits from the
118 * Miscellaneous Control Reg.
119 * Added XDcfg_GetPsVersion, XDcfg_SelectIcapInterface
120 * and XDcfg_SelectPcapInterface APIs for CR 643295
121 * The user has to call the XDcfg_SelectIcapInterface API
122 * for the PL reconfiguration using AXI HwIcap.
123 * Updated the XDcfg_Transfer API to clear the
124 * QUARTER_PCAP_RATE_EN bit in the control register for
125 * non secure writes for CR 675543.
126 * 2.02a nm 01/31/13 Fixed CR# 679335.
127 * Added Setting and Clearing the internal PCAP loopback.
128 * Removed code for enabling/disabling AES engine as BootROM
129 * locks down this setting.
131 * Skip Checking the PCFG_INIT in case of non-secure DMA
134 * XDcfg_Transfer fails to transfer data in loopback mode.
136 * Peripheral test fails with Running
137 * DcfgSelfTestExample() in SECURE bootmode.
138 * 2.03a nm 04/19/13 Fixed CR# 703728.
139 * Updated the register definitions as per the latest TRM
140 * version UG585 (v1.4) November 16, 2012.
141 * 3.0 adk 10/12/13 Updated as per the New Tcl API's
142 * 3.0 kpc 21/02/14 Added function prototype for XDcfg_ClearControlRegister
143 * 3.2 sb 08/25/14 Fixed XDcfg_PcapReadback() function
144 * updated driver code with != instead of ==,
145 * while checking for Interrupt Status with DMA and
147 * ((XDcfg_ReadReg(InstancePtr->Config.BaseAddr,
148 * XDCFG_INT_STS_OFFSET) &
149 * XDCFG_IXR_D_P_DONE_MASK) !=
150 * XDCFG_IXR_D_P_DONE_MASK);
151 * A new example has been added to read back the
152 * configuration registers from the PL region.
153 * xdevcfg_reg_readback_example.c
154 * 3.3 sk 04/06/15 Modified XDcfg_ReadMultiBootConfig Macro CR# 851335.
158 ******************************************************************************/
159 #ifndef XDCFG_H /* prevent circular inclusions */
160 #define XDCFG_H /* by using protection macros */
162 /***************************** Include Files *********************************/
164 #include "xdevcfg_hw.h"
166 #include "xil_assert.h"
172 /************************** Constant Definitions *****************************/
174 /* Types of PCAP transfers */
176 #define XDCFG_NON_SECURE_PCAP_WRITE 1
177 #define XDCFG_SECURE_PCAP_WRITE 2
178 #define XDCFG_PCAP_READBACK 3
179 #define XDCFG_CONCURRENT_SECURE_READ_WRITE 4
180 #define XDCFG_CONCURRENT_NONSEC_READ_WRITE 5
183 /**************************** Type Definitions *******************************/
185 * The handler data type allows the user to define a callback function to
186 * respond to interrupt events in the system. This function is executed
187 * in interrupt context, so amount of processing should be minimized.
189 * @param CallBackRef is the callback reference passed in by the upper
190 * layer when setting the callback functions, and passed back to
191 * the upper layer when the callback is invoked. Its type is
192 * unimportant to the driver component, so it is a void pointer.
193 * @param Status is the Interrupt status of the XDcfg device.
195 typedef void (*XDcfg_IntrHandler) (void *CallBackRef, u32 Status);
198 * This typedef contains configuration information for the device.
201 u16 DeviceId; /**< Unique ID of device */
202 u32 BaseAddr; /**< Base address of the device */
206 * The XDcfg driver instance data.
209 XDcfg_Config Config; /**< Hardware Configuration */
210 u32 IsReady; /**< Device is initialized and ready */
211 u32 IsStarted; /**< Device Configuration Interface
214 XDcfg_IntrHandler StatusHandler; /* Event handler function */
215 void *CallBackRef; /* Callback reference for event handler */
218 /****************************************************************************/
221 * Unlock the Device Config Interface block.
223 * @param InstancePtr is a pointer to the instance of XDcfg driver.
227 * @note C-style signature:
228 * void XDcfg_Unlock(XDcfg* InstancePtr)
230 *****************************************************************************/
231 #define XDcfg_Unlock(InstancePtr) \
232 XDcfg_WriteReg((InstancePtr)->Config.BaseAddr, \
233 XDCFG_UNLOCK_OFFSET, XDCFG_UNLOCK_DATA)
237 /****************************************************************************/
240 * Get the version number of the PS from the Miscellaneous Control Register.
242 * @param InstancePtr is a pointer to the instance of XDcfg driver.
244 * @return Version of the PS.
246 * @note C-style signature:
247 * void XDcfg_GetPsVersion(XDcfg* InstancePtr)
249 *****************************************************************************/
250 #define XDcfg_GetPsVersion(InstancePtr) \
251 ((XDcfg_ReadReg((InstancePtr)->Config.BaseAddr, \
252 XDCFG_MCTRL_OFFSET)) & \
253 XDCFG_MCTRL_PCAP_PS_VERSION_MASK) >> \
254 XDCFG_MCTRL_PCAP_PS_VERSION_SHIFT
258 /****************************************************************************/
261 * Read the multiboot config register value.
263 * @param InstancePtr is a pointer to the instance of XDcfg driver.
267 * @note C-style signature:
268 * u32 XDcfg_ReadMultiBootConfig(XDcfg* InstancePtr)
270 *****************************************************************************/
271 #define XDcfg_ReadMultiBootConfig(InstancePtr) \
272 XDcfg_ReadReg((InstancePtr)->Config.BaseAddr, \
273 XDCFG_MULTIBOOT_ADDR_OFFSET)
276 /****************************************************************************/
279 * Selects ICAP interface for reconfiguration after the initial configuration
282 * @param InstancePtr is a pointer to the instance of XDcfg driver.
286 * @note C-style signature:
287 * void XDcfg_SelectIcapInterface(XDcfg* InstancePtr)
289 *****************************************************************************/
290 #define XDcfg_SelectIcapInterface(InstancePtr) \
291 XDcfg_WriteReg((InstancePtr)->Config.BaseAddr, XDCFG_CTRL_OFFSET, \
292 ((XDcfg_ReadReg((InstancePtr)->Config.BaseAddr, XDCFG_CTRL_OFFSET)) \
293 & ( ~XDCFG_CTRL_PCAP_PR_MASK)))
295 /****************************************************************************/
298 * Selects PCAP interface for reconfiguration after the initial configuration
301 * @param InstancePtr is a pointer to the instance of XDcfg driver.
305 * @note C-style signature:
306 * void XDcfg_SelectPcapInterface(XDcfg* InstancePtr)
308 *****************************************************************************/
309 #define XDcfg_SelectPcapInterface(InstancePtr) \
310 XDcfg_WriteReg((InstancePtr)->Config.BaseAddr, XDCFG_CTRL_OFFSET, \
311 ((XDcfg_ReadReg((InstancePtr)->Config.BaseAddr, XDCFG_CTRL_OFFSET)) \
312 | XDCFG_CTRL_PCAP_PR_MASK))
316 /************************** Function Prototypes ******************************/
319 * Lookup configuration in xdevcfg_sinit.c.
321 XDcfg_Config *XDcfg_LookupConfig(u16 DeviceId);
324 * Selftest function in xdevcfg_selftest.c
326 int XDcfg_SelfTest(XDcfg *InstancePtr);
329 * Interface functions in xdevcfg.c
331 int XDcfg_CfgInitialize(XDcfg *InstancePtr,
332 XDcfg_Config *ConfigPtr, u32 EffectiveAddress);
334 void XDcfg_EnablePCAP(XDcfg *InstancePtr);
336 void XDcfg_DisablePCAP(XDcfg *InstancePtr);
338 void XDcfg_SetControlRegister(XDcfg *InstancePtr, u32 Mask);
340 void XDcfg_ClearControlRegister(XDcfg *InstancePtr, u32 Mask);
342 u32 XDcfg_GetControlRegister(XDcfg *InstancePtr);
344 void XDcfg_SetLockRegister(XDcfg *InstancePtr, u32 Data);
346 u32 XDcfg_GetLockRegister(XDcfg *InstancePtr);
348 void XDcfg_SetConfigRegister(XDcfg *InstancePtr, u32 Data);
350 u32 XDcfg_GetConfigRegister(XDcfg *InstancePtr);
352 void XDcfg_SetStatusRegister(XDcfg *InstancePtr, u32 Data);
354 u32 XDcfg_GetStatusRegister(XDcfg *InstancePtr);
356 void XDcfg_SetRomShadowRegister(XDcfg *InstancePtr, u32 Data);
358 u32 XDcfg_GetSoftwareIdRegister(XDcfg *InstancePtr);
360 void XDcfg_SetMiscControlRegister(XDcfg *InstancePtr, u32 Mask);
362 u32 XDcfg_GetMiscControlRegister(XDcfg *InstancePtr);
364 u32 XDcfg_IsDmaBusy(XDcfg *InstancePtr);
366 void XDcfg_InitiateDma(XDcfg *InstancePtr, u32 SourcePtr, u32 DestPtr,
367 u32 SrcWordLength, u32 DestWordLength);
369 u32 XDcfg_Transfer(XDcfg *InstancePtr,
370 void *SourcePtr, u32 SrcWordLength,
371 void *DestPtr, u32 DestWordLength,
375 * Interrupt related function prototypes implemented in xdevcfg_intr.c
377 void XDcfg_IntrEnable(XDcfg *InstancePtr, u32 Mask);
379 void XDcfg_IntrDisable(XDcfg *InstancePtr, u32 Mask);
381 u32 XDcfg_IntrGetEnabled(XDcfg *InstancePtr);
383 u32 XDcfg_IntrGetStatus(XDcfg *InstancePtr);
385 void XDcfg_IntrClear(XDcfg *InstancePtr, u32 Mask);
387 void XDcfg_InterruptHandler(XDcfg *InstancePtr);
389 void XDcfg_SetHandler(XDcfg *InstancePtr, void *CallBackFunc,
396 #endif /* end of protection macro */