bram
Vitis Drivers API Documentation
 All Data Structures Files Functions Variables Groups Pages
Overview

Data Structures

struct  XBram_Config
 Holds configuration information for the BRAM device. More...
 
struct  XBram
 Holds instance data for a BRAM device. More...
 

Functions

XBram_Config * XBram_LookupConfig (UINTPTR BaseAddress)
 Looks up the device configuration for a BRAM instance. More...
 
int XBram_CfgInitialize (XBram *InstancePtr, XBram_Config *Config, UINTPTR EffectiveAddr)
 Initializes a specific XBram instance. More...
 
int XBram_SelfTest (XBram *InstancePtr, u8 IntMask)
 Runs a self-test on the BRAM driver and device. More...
 
void XBram_InterruptEnable (XBram *InstancePtr, u32 Mask)
 Enables selected BRAM interrupts. More...
 
void XBram_InterruptDisable (XBram *InstancePtr, u32 Mask)
 Disables selected BRAM interrupts. More...
 
void XBram_InterruptClear (XBram *InstancePtr, u32 Mask)
 Clears pending BRAM interrupts for the provided mask. More...
 
u32 XBram_InterruptGetEnabled (XBram *InstancePtr)
 Returns the BRAM interrupt enable mask. More...
 
u32 XBram_InterruptGetStatus (XBram *InstancePtr)
 Returns the status of BRAM interrupt signals. More...
 

Function Documentation

int XBram_CfgInitialize ( XBram *  InstancePtr,
XBram_Config *  Config,
UINTPTR  EffectiveAddr 
)

Initializes a specific XBram instance.

Uses a configuration structure provided by the caller. Nothing is done except to initialize InstancePtr.

Parameters
[out]InstancePtrPointer to an XBram instance. The memory the pointer references must be pre-allocated by the caller. Further calls to manipulate the driver through the XBram API must be made with this pointer.
[in]ConfigReference to a structure containing information about a specific BRAM device. This function initializes an InstancePtr object for a specific device specified by Config. This function can initialize multiple instance objects with multiple calls giving different Config information on each call.
[in]EffectiveAddrDevice base address in the virtual memory address space. The caller is responsible for keeping the address mapping from EffectiveAddr to the device physical base address unchanged once this function is invoked. Unexpected errors may occur if the address mapping changes after this function is called. If address translation is not used, use Config->BaseAddress for this parameter, passing the physical address instead.
Returns
  • XST_SUCCESS if initialization was successful.

References XBram::Config, XBram_Config::CorrectableCounterBits, XBram_Config::CorrectableFailingDataRegs, XBram_Config::CorrectableFailingRegisters, XBram_Config::CtrlBaseAddress, XBram_Config::DataWidth, XBram_Config::EccPresent, XBram_Config::EccStatusInterruptPresent, XBram_Config::FaultInjectionPresent, XBram_Config::IntId, XBram_Config::IntrParent, XBram::IsReady, XBram_Config::MemBaseAddress, XBram_Config::MemHighAddress, XBram_Config::UncorrectableFailingDataRegs, XBram_Config::UncorrectableFailingRegisters, and XBram_Config::WriteAccess.

Referenced by BramExample(), and BramIntrExample().

void XBram_InterruptClear ( XBram *  InstancePtr,
u32  Mask 
)

Clears pending BRAM interrupts for the provided mask.

Call this function after the software has serviced the pending interrupts. This function asserts if the hardware device has not been built with interrupt capabilities.

Parameters
[in]InstancePtrBRAM instance to operate on.
[in]MaskMask to clear pending interrupts for. Bit positions of 1 are cleared. This mask is formed by OR'ing bits from XBRAM_IR* bits which are contained in xbram_hw.h.

References XBram::Config, XBram_Config::CtrlBaseAddress, XBram::IsReady, XBRAM_ECC_STATUS_OFFSET, XBram_ReadReg, and XBram_WriteReg.

void XBram_InterruptDisable ( XBram *  InstancePtr,
u32  Mask 
)

Disables selected BRAM interrupts.

This function allows each specific interrupt to be disabled. This function asserts if the hardware device has not been built with interrupt capabilities.

Parameters
[in]InstancePtrBRAM instance to operate on.
[in]MaskMask to disable. Bits set to 1 are disabled. This mask is formed by OR'ing bits from XBRAM_IR* bits which are contained in xbram_hw.h.

References XBram::Config, XBram_Config::CtrlBaseAddress, XBram::IsReady, XBRAM_ECC_EN_IRQ_OFFSET, XBram_ReadReg, and XBram_WriteReg.

void XBram_InterruptEnable ( XBram *  InstancePtr,
u32  Mask 
)

Enables selected BRAM interrupts.

This function asserts if the hardware device has not been built with interrupt capabilities.

Parameters
[in]InstancePtrBRAM instance to operate on.
[in]MaskMask to enable. Bit positions of 1 are enabled. This mask is formed by OR'ing bits from XBRAM_IR* bits which are contained in xbram_hw.h.

References XBram::Config, XBram_Config::CtrlBaseAddress, XBram::IsReady, XBRAM_ECC_EN_IRQ_OFFSET, XBram_ReadReg, and XBram_WriteReg.

u32 XBram_InterruptGetEnabled ( XBram *  InstancePtr)

Returns the BRAM interrupt enable mask.

This function asserts if the hardware device has not been built with interrupt capabilities.

Parameters
[in]InstancePtrBRAM instance to operate on.
Returns
A mask of bits made from XBRAM_IR* bits which are contained in xbram_hw.h.

References XBram::Config, XBram_Config::CtrlBaseAddress, XBram::IsReady, XBRAM_ECC_EN_IRQ_OFFSET, and XBram_ReadReg.

u32 XBram_InterruptGetStatus ( XBram *  InstancePtr)

Returns the status of BRAM interrupt signals.

Any bit in the mask set to 1 indicates that the channel associated with the bit has asserted an interrupt condition. This function asserts if the hardware device has not been built with interrupt capabilities.

Parameters
[in]InstancePtrBRAM instance to operate on.
Returns
A mask of bits made from XBRAM_IR* bits which are contained in xbram_hw.h.
Note
The interrupt status indicates the status of the device regardless of whether interrupts have been enabled through XBram_InterruptEnable().

References XBram::Config, XBram_Config::CtrlBaseAddress, XBram::IsReady, XBRAM_ECC_STATUS_OFFSET, and XBram_ReadReg.

XBram_Config* XBram_LookupConfig ( UINTPTR  BaseAddress)

Looks up the device configuration for a BRAM instance.

Uses XBram_ConfigTable[] which contains the configuration info for each device in the system.

Parameters
[in]BaseAddressContains the base address of the device.
Returns
A pointer to the configuration found, or NULL if the specified device ID or base address was not found. See xbram.h for the definition of XBram_Config.
Note
In XSCT/classic flow, DeviceId is used to look up the device configuration.

References XBram_Config::Name.

Referenced by BramExample(), and BramIntrExample().

int XBram_SelfTest ( XBram *  InstancePtr,
u8  IntMask 
)

Runs a self-test on the BRAM driver and device.

Unless fault injection is implemented in hardware, this function only does a minimal test in which available registers (if any) are written and read.

With fault injection, all possible single-bit and double-bit errors are injected, and checked to the extent possible, given the implemented hardware.

Parameters
[in]InstancePtrPointer to the XBram instance.
[in]IntMaskInterrupt mask to use. When testing with interrupts, this should be set to allow interrupt generation, otherwise it should be 0.
Returns
  • XST_SUCCESS if fault injection and detection are working, or if ECC is not enabled in the hardware.
  • XST_FAILURE if the injected fault is not correctly detected, or the control base address is zero when ECC is enabled.

If the BRAM device is not present in the hardware a bus error could be generated. Other indicators of a bus error, such as registers in bridges or buses, may be necessary to determine if this function caused a bus error.

References XBram::Config, XBram_Config::CorrectableCounterBits, XBram_Config::CorrectableFailingDataRegs, XBram_Config::CorrectableFailingRegisters, XBram_Config::CtrlBaseAddress, XBram_Config::DataWidth, XBram_Config::EccPresent, XBram_Config::EccStatusInterruptPresent, XBram_Config::FaultInjectionPresent, XBram::IsReady, XBram_Config::MemBaseAddress, XBram_Config::MemHighAddress, XBram_Config::UncorrectableFailingDataRegs, XBram_Config::UncorrectableFailingRegisters, XBram_Config::WriteAccess, XBram_In32, XBRAM_IR_ALL_MASK, XBRAM_IR_CE_MASK, XBRAM_IR_UE_MASK, and XBram_Out32.

Referenced by BramExample(), and BramIntrExample().