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 /*****************************************************************************/
35 * @addtogroup bram_v4_0
39 * If ECC is not enabled, this driver exists only to allow the tools to
40 * create a memory test application and to populate xparameters.h with memory
41 * range constants. In this case there is no source code.
43 * If ECC is enabled, this file contains the software API definition of the
44 * Xilinx BRAM Interface Controller (XBram) device driver.
46 * The Xilinx BRAM controller is a soft IP core designed for Xilinx
47 * FPGAs and contains the following general features:
48 * - LMB v2.0 bus interfaces with byte enable support
49 * - Used in conjunction with bram_block peripheral to provide fast BRAM
50 * memory solution for MicroBlaze ILMB and DLMB ports
51 * - Supports byte, half-word, and word transfers
52 * - Supports optional BRAM error correction and detection.
54 * The driver provides interrupt management functions. Implementation of
55 * interrupt handlers is left to the user. Refer to the provided interrupt
56 * example in the examples directory for details.
58 * This driver is intended to be RTOS and processor independent. Any needs for
59 * dynamic memory management, threads or thread mutual exclusion, virtual
60 * memory, or cache control must be satisfied by the layer above this driver.
62 * <b>Initialization & Configuration</b>
64 * The XBram_Config structure is used by the driver to configure
65 * itself. This configuration structure is typically created by the tool-chain
66 * based on HW build properties.
68 * To support multiple runtime loading and initialization strategies employed
69 * by various operating systems, the driver instance can be initialized as
72 * - XBram_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) -
73 * Uses a configuration structure provided by the caller. If running in a
74 * system with address translation, the provided virtual memory base address
75 * replaces the physical address present in the configuration structure.
79 * This API utilizes 32 bit I/O to the BRAM registers. With less
80 * than 32 bits, the unused bits from registers are read as zero and written as
84 * MODIFICATION HISTORY:
86 * Ver Who Date Changes
87 * ----- ---- -------- -----------------------------------------------
88 * 3.00a sa 05/11/10 Added ECC support
89 * 3.01a sa 01/13/12 Changed Selftest API from
90 * XBram_SelfTest(XBram *InstancePtr) to
91 * XBram_SelfTest(XBram *InstancePtr, u8 IntMask) and
92 * fixed a problem with interrupt generation for CR 639274
93 * Modified Selftest example to return XST_SUCCESS when
94 * ECC is not enabled and return XST_FAILURE when ECC is
95 * enabled and Control Base Address is zero (CR 636581)
96 * Modified Selftest to use correct CorrectableCounterBits
98 * Updated to check CorrectableFailingDataRegs in the case
100 * Added CorrectableFailingDataRegs and
101 * UncorrectableFailingDataRegs to the config structure to
102 * distinguish between AXI BRAM and LMB BRAM.
103 * These registers are not present in the current version of
104 * the AXI BRAM Controller.
105 * 3.02a sa 04/16/12 Added test of byte and halfword read-modify-write
106 * 3.02a sa 04/16/12 Modified driver tcl to sort the address parameters
107 * to support both xps and vivado designs.
108 * 3.02a adk 24/4/13 Modified the tcl file to avoid warnings
109 * when ecc is disabled cr:705002.
110 * 3.03a bss 05/22/13 Added Xil_DCacheFlushRange in xbram_selftest.c to
111 * flush the Cache after writing to BRAM in InjectErrors
113 * 4.0 adk 19/12/13 Updated as per the New Tcl API's
114 * 4.1 sk 11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425.
115 * Changed the prototype of XBram_CfgInitialize API.
117 *****************************************************************************/
118 #ifndef XBRAM_H /* prevent circular inclusions */
119 #define XBRAM_H /* by using protection macros */
125 /***************************** Include Files ********************************/
127 #include "xil_types.h"
128 #include "xil_assert.h"
130 #include "xbram_hw.h"
132 /************************** Constant Definitions ****************************/
135 /**************************** Type Definitions ******************************/
138 * This typedef contains configuration information for the device.
141 u16 DeviceId; /**< Unique ID of device */
142 u32 DataWidth; /**< BRAM data width */
143 int EccPresent; /**< Is ECC supported in H/W */
144 int FaultInjectionPresent; /**< Is Fault Injection
145 * supported in H/W */
146 int CorrectableFailingRegisters; /**< Is Correctable Failing Registers
147 * supported in H/W */
148 int CorrectableFailingDataRegs; /**< Is Correctable Failing Data
149 * Registers supported in H/W */
150 int UncorrectableFailingRegisters; /**< Is Un-correctable Failing
151 * Registers supported in H/W */
152 int UncorrectableFailingDataRegs; /**< Is Un-correctable Failing Data
153 * Registers supported in H/W */
154 int EccStatusInterruptPresent; /**< Are ECC status and interrupts
155 * supported in H/W */
156 int CorrectableCounterBits; /**< Number of bits in the
157 * Correctable Error Counter */
158 int EccOnOffRegister; /**< Is ECC on/off register supported
160 int EccOnOffResetValue; /**< Reset value of the ECC on/off
162 int WriteAccess; /**< Is write access enabled in
164 u32 MemBaseAddress; /**< Device memory base address */
165 u32 MemHighAddress; /**< Device memory high address */
166 UINTPTR CtrlBaseAddress; /**< Device register base address.*/
167 UINTPTR CtrlHighAddress; /**< Device register base address.*/
171 * The XBram driver instance data. The user is required to
172 * allocate a variable of this type for every BRAM device in the
173 * system. A pointer to a variable of this type is then passed to the driver
177 XBram_Config Config; /* BRAM config structure */
178 u32 IsReady; /* Device is initialized and ready */
181 /***************** Macros (Inline Functions) Definitions ********************/
184 /************************** Function Prototypes *****************************/
187 * Functions in xbram_sinit.c
189 XBram_Config *XBram_LookupConfig(u16 DeviceId);
192 * Functions implemented in xbram.c
194 int XBram_CfgInitialize(XBram *InstancePtr, XBram_Config *Config,
195 UINTPTR EffectiveAddr);
198 * Functions implemented in xbram_selftest.c
200 int XBram_SelfTest(XBram *InstancePtr, u8 IntMask);
203 * Functions implemented in xbram_intr.c
205 void XBram_InterruptEnable(XBram *InstancePtr, u32 Mask);
206 void XBram_InterruptDisable(XBram *InstancePtr, u32 Mask);
207 void XBram_InterruptClear(XBram *InstancePtr, u32 Mask);
208 u32 XBram_InterruptGetEnabled(XBram *InstancePtr);
209 u32 XBram_InterruptGetStatus(XBram *InstancePtr);
215 #endif /* end of protection macro */