Xilinx Standalone Library

Documentation

Standalone Library v7.7

UG647 (v2022.1) April 20, 2022

Xilinx is creating an environment where employees, customers, and

partners feel welcome and included. To that end, we’re removing non-
inclusive language from our products and related collateral. We’ve
launched an internal initiative to remove language that could exclude
people or reinforce historical biases, including terms embedded in our
software and IPs. You may still find examples of non-inclusive
language in our older products as we work to make these changes and
align with evolving industry standards. Follow this link for more
information.
Table of Contents
Chapter 1: Xilinx Hardware Abstraction Layer APIs................................... 4
Xilinx Hardware Abstraction Layer API..................................................................................... 4
Assert APIs and Macros.............................................................................................................. 4
Register I/O interfacing APIs..................................................................................................... 8
Hardware Platform Information............................................................................................. 19
Basic Data types for Xilinx Software IP................................................................................... 21
Customized APIs for Memory Operations............................................................................. 21
Xilinx Software Status Codes................................................................................................... 22
Test Utilities for Memory and Caches..................................................................................... 22

Chapter 2: MicroBlaze Processor APIs.............................................................. 32

MicroBlaze Processor API.........................................................................................................32
MicroBlaze Pseudo-asm Macros and Interrupt Handling APIs........................................... 32
MicroBlaze Exception APIs....................................................................................................... 34
MicroBlaze Cache APIs..............................................................................................................36
MicroBlaze Processor FSL Macros...........................................................................................43
MicroBlaze PVR Access Routines and Macros........................................................................46
Sleep Routines for MicroBlaze Processor...............................................................................50

Chapter 3: Arm Processor Common APIs........................................................ 52

Arm Processor Exception Handling........................................................................................ 52

Chapter 4: Arm Cortex-R5F Processor APIs.................................................... 59

Arm Cortex-R5F Processor API................................................................................................ 59
Arm Cortex-R5F Processor Boot Code.................................................................................... 59
Arm Cortex-R5F Processor MPU specific APIs....................................................................... 60
Arm Cortex-R5F Processor Cache Functions..........................................................................66
Arm Cortex-R5F Time Functions.............................................................................................. 73
Arm Cortex-R5F Event Counters Functions............................................................................ 75
Arm Cortex-R5F Processor Specific Include Files.................................................................. 80
Arm Cortex-R5F Peripheral Definitions.................................................................................. 80

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 2
 Chapter 5: Arm Cortex-A9 Processor APIs...................................................... 81
Arm Cortex-A9 Processor API.................................................................................................. 81
Arm Cortex-A9 Processor Boot Code...................................................................................... 81
Arm Cortex-A9 Processor Cache Functions............................................................................82
Arm Cortex-A9 Processor MMU Functions...........................................................................101
Arm Cortex-A9 Time Functions..............................................................................................103
Arm Cortex-A9 Event Counter Function............................................................................... 105
PL310 L2 Event Counters Functions...................................................................................... 106
Arm Cortex-A9 Processor and pl310 Errata Support.......................................................... 108
Arm Cortex-A9 Processor Specific Include Files.................................................................. 110

Chapter 6: Arm Cortex-A53 32-bit Processor APIs.................................... 111

Arm Cortex-A53 32-bit Processor API................................................................................... 111
Arm Cortex-A53 32-bit Processor Boot Code.......................................................................111
Arm Cortex-A53 32-bit Processor Cache Functions............................................................ 112
Arm Cortex-A53 32-bit Processor MMU Handling...............................................................119
Arm Cortex-A53 32-bit Mode Time Functions......................................................................121
Arm Cortex-A53 32-bit Processor Specific Include Files..................................................... 122

Chapter 7: Arm Cortex-A53 64-bit Processor APIs.................................... 123

Arm Cortex-A53 64-bit Processor API................................................................................... 123
Arm Cortex-A53 64-bit Processor Boot Code.......................................................................123
Arm Cortex-A53 64-bit Processor Cache Functions............................................................ 125
Arm Cortex-A53 64-bit Processor MMU Handling...............................................................131
Arm Cortex-A53 64-bit Mode Time Functions......................................................................132
Arm Cortex-A53 64-bit Processor Specific Include Files..................................................... 133

Appendix A: Additional Resources and Legal Notices........................... 135

Xilinx Resources.......................................................................................................................135
Documentation Navigator and Design Hubs...................................................................... 135
Please Read: Important Legal Notices................................................................................. 136

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 3
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Chapter 1

Xilinx Hardware Abstraction Layer

APIs

Xilinx Hardware Abstraction Layer API

This section describes the Xilinx Hardware Abstraction Layer API, These APIs are applicable for
all processors supported by Xilinx.

Assert APIs and Macros

This file contains basic assert related functions for Xilinx software IP.

The xil_assert.h file contains assert related functions and macros.

Assert APIs/Macros specifies that a application program satisfies certain conditions at particular
points in its execution. These function can be used by application programs to ensure that,
application code is satisfying certain conditions.

Table 1: Quick Function Reference

Type Name Arguments

void Xil_Assert
const char8 * File
s32 Line

void Xil_AssertSetCallback
Xil_AssertCallback Routine

void XNullHandler
void * NullParameter

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 4
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Functions
Xil_Assert
Implement assert.

Currently, it calls a user-defined callback function if one has been set. Then, it potentially enters
an infinite loop depending on the value of the Xil_AssertWait variable.

Note: None.

Prototype

void Xil_Assert(const char8 *File, s32 Line);

Parameters

The following table lists the Xil_Assert function arguments.

Table 2: Xil_Assert Arguments

Name Description
File filename of the source
Line linenumber within File

Returns

None.

Xil_AssertSetCallback
Set up a callback function to be invoked when an assert occurs.

If a callback is already installed, then it will be replaced.

Note: This function has no effect if NDEBUG is set

Prototype

void Xil_AssertSetCallback(Xil_AssertCallback Routine);

Parameters

The following table lists the Xil_AssertSetCallback function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 5
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 3: Xil_AssertSetCallback Arguments

Name Description
Routine callback to be invoked when an assert is taken

Returns

None.

XNullHandler
Null handler function.

This follows the XInterruptHandler signature for interrupt handlers. It can be used to assign a null
handler (a stub) to an interrupt controller vector table.

Note: None.

Prototype

void XNullHandler(void *NullParameter);

Parameters

The following table lists the XNullHandler function arguments.

Table 4: XNullHandler Arguments

Name Description
NullParameter arbitrary void pointer and not used.

Returns

None.

Definitions
#Define Xil_AssertVoid

Description

This assert macro is to be used for void functions.

This in conjunction with the Xil_AssertWait boolean can be used to accommodate tests so that
asserts which fail allow execution to continue.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 6
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Parameters

The following table lists the Xil_AssertVoid function arguments.

Table 5: Xil_AssertVoid Arguments

Name Description
Expression expression to be evaluated. If it evaluates to false, the assert occurs.

Returns

Returns void unless the Xil_AssertWait variable is true, in which case no return is made and an
infinite loop is entered.

#Define Xil_AssertNonvoid

Description

This assert macro is to be used for functions that do return a value.

This in conjunction with the Xil_AssertWait boolean can be used to accommodate tests so that
asserts which fail allow execution to continue.

Parameters

The following table lists the Xil_AssertNonvoid function arguments.

Table 6: Xil_AssertNonvoid Arguments

Name Description
Expression expression to be evaluated. If it evaluates to false, the assert occurs.

Returns

Returns 0 unless the Xil_AssertWait variable is true, in which case no return is made and an
infinite loop is entered.

#Define Xil_AssertVoidAlways

Description

Always assert.

This assert macro is to be used for void functions. Use for instances where an assert should
always occur.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 7
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Returns

Returns void unless the Xil_AssertWait variable is true, in which case no return is made and an
infinite loop is entered.

#Define Xil_AssertNonvoidAlways

Description

Always assert.

This assert macro is to be used for functions that do return a value. Use for instances where an
assert should always occur.

Returns

Returns void unless the Xil_AssertWait variable is true, in which case no return is made and an
infinite loop is entered.

Variables
u32 Xil_AssertStatus
This variable allows testing to be done easier with asserts. An assert sets this variable such that a
driver can evaluate this variable to determine if an assert occurred.

s32 Xil_AssertWait
This variable allows the assert functionality to be changed for testing such that it does not wait
infinitely. Use the debugger to disable the waiting during testing of asserts.

Register I/O interfacing APIs

The xil_io.h file contains the interface for the general I/O component, which encapsulates the
Input/Output functions for the processors that do not require any special I/O handling.

Table 7: Quick Function Reference

Type Name Arguments

INLINE u16 Xil_In16BE
UINTPTR Addr

INLINE u32 Xil_In32BE

UINTPTR Addr

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 8
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 7: Quick Function Reference (cont'd)

Type Name Arguments

INLINE void Xil_Out16BE
UINTPTR Addr
u16 Value

INLINE void Xil_Out32BE

UINTPTR Addr
u32 Value

INLINE u16 Xil_In16LE

UINTPTR Addr

INLINE u32 Xil_In32LE

UINTPTR Addr

INLINE void Xil_Out16LE

UINTPTR Addr
u16 Value

INLINE void Xil_Out32LE

UINTPTR Addr
u32 Value

INLINE u8 Xil_In8
UINTPTR Addr

INLINE u16 Xil_In16

UINTPTR Addr

INLINE u32 Xil_In32

UINTPTR Addr

INLINE u64 Xil_In64

UINTPTR Addr

INLINE void Xil_Out8

UINTPTR Addr
u8 Value

INLINE void Xil_Out16

UINTPTR Addr
u16 Value

INLINE void Xil_Out32

UINTPTR Addr
u32 Value

INLINE void Xil_Out64

UINTPTR Addr
u64 Value

INLINE int Xil_SecureOut32

UINTPTR Addr
u32 Value

u16 Xil_EndianSwap16
u16 Data

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 9
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 7: Quick Function Reference (cont'd)

Type Name Arguments

u32 Xil_EndianSwap32
u32 Data

Functions
Xil_In16BE
Perform an big-endian input operation for a 16-bit memory location by reading from the
specified address and returning the value read from that address.

Prototype

INLINE u16 Xil_In16BE(UINTPTR Addr);

Parameters

The following table lists the Xil_In16BE function arguments.

Table 8: Xil_In16BE Arguments

Name Description
Addr contains the address at which to perform the input operation.

Returns

The value read from the specified input address with the proper endianness. The return value has
the same endianness as that of the processor. For example, if the processor is little-endian, the
return value is the byte-swapped value read from the address.

Xil_In32BE
Perform a big-endian input operation for a 32-bit memory location by reading from the specified
address and returning the value read from that address.

Prototype

INLINE u32 Xil_In32BE(UINTPTR Addr);

Parameters

The following table lists the Xil_In32BE function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 10
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 9: Xil_In32BE Arguments

Name Description
Addr contains the address at which to perform the input operation.

Returns

The value read from the specified input address with the proper endianness. The return value has
the same endianness as that of the processor. For example, if the processor is little-endian, the
return value is the byte-swapped value read from the address.

Xil_Out16BE
Perform a big-endian output operation for a 16-bit memory location by writing the specified
value to the specified address.

Prototype

INLINE void Xil_Out16BE(UINTPTR Addr, u16 Value);

Parameters

The following table lists the Xil_Out16BE function arguments.

Table 10: Xil_Out16BE Arguments

Name Description
Addr contains the address at which to perform the output operation.
Value contains the value to be output at the specified address. The value has the same
endianness as that of the processor. For example, if the processor is little-endian, the
byteswapped value is written to the address.

Xil_Out32BE
Perform a big-endian output operation for a 32-bit memory location by writing the specified
value to the specified address.

Prototype

INLINE void Xil_Out32BE(UINTPTR Addr, u32 Value);

Parameters

The following table lists the Xil_Out32BE function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 11
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 11: Xil_Out32BE Arguments

Name Description
Addr contains the address at which to perform the output operation.
Value contains the value to be output at the specified address. The value has the same
endianness as that of the processor. For example, if the processor is little-endian, the
byteswapped value is written to the address.

Xil_In16LE
Perform a little-endian input operation for a 16-bit memory location by reading from the
specified address and returning the value read from that address.

Prototype

INLINE u16 Xil_In16LE(UINTPTR Addr)[static];

Parameters

The following table lists the Xil_In16LE function arguments.

Table 12: Xil_In16LE Arguments

Name Description
Addr contains the address at which to perform the input operation.

Returns

The value read from the specified input address with the proper endianness. The return value has
the same endianness as that of the processor. For example, if the processor is big-endian, the
return value is the byte-swapped value read from the address.

Xil_In32LE
Perform a little-endian input operation for a 32-bit memory location by reading from the
specified address and returning the value read from that address.

Prototype

INLINE u32 Xil_In32LE(UINTPTR Addr)[static];

Parameters

The following table lists the Xil_In32LE function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 12
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 13: Xil_In32LE Arguments

Name Description
Addr contains the address at which to perform the input operation.

Returns

The value read from the specified input address with the proper endianness. The return value has
the same endianness as that of the processor. For example, if the processor is big-endian, the
return value is the byte-swapped value read from the address.

Xil_Out16LE
Perform a little-endian output operation for a 16-bit memory location by writing the specified
value to the specified address.

Prototype

INLINE void Xil_Out16LE(UINTPTR Addr, u16 Value)[static];

Parameters

The following table lists the Xil_Out16LE function arguments.

Table 14: Xil_Out16LE Arguments

Name Description
Addr contains the address at which to perform the input operation.
Value contains the value to be output at the specified address. The value has the same
endianness as that of the processor. For example, if the processor is big-endian, the
byteswapped value is written to the address.

Xil_Out32LE
Perform a little-endian output operation for a 32-bit memory location by writing the specified
value to the specified address.

Prototype

INLINE void Xil_Out32LE(UINTPTR Addr, u32 Value)[static];

Parameters

The following table lists the Xil_Out32LE function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 13
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 15: Xil_Out32LE Arguments

Name Description
Addr contains the address at which to perform the input operation.
Value contains the value to be output at the specified address. The value has the same
endianness as that of the processor. For example, if the processor is big-endian, the
byteswapped value is written to the address

Xil_In8
Performs an input operation for a memory location by reading from the specified address and
returning the 8 bit Value read from that address.

Prototype

INLINE u8 Xil_In8(UINTPTR Addr);

Parameters

The following table lists the Xil_In8 function arguments.

Table 16: Xil_In8 Arguments

Name Description
Addr contains the address to perform the input operation

Returns

The 8 bit Value read from the specified input address.

Xil_In16
Performs an input operation for a memory location by reading from the specified address and
returning the 16 bit Value read from that address.

Prototype

INLINE u16 Xil_In16(UINTPTR Addr);

Parameters

The following table lists the Xil_In16 function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 14
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 17: Xil_In16 Arguments

Name Description
Addr contains the address to perform the input operation

Returns

The 16 bit Value read from the specified input address.

Xil_In32
Performs an input operation for a memory location by reading from the specified address and
returning the 32 bit Value read from that address.

Prototype

INLINE u32 Xil_In32(UINTPTR Addr);

Parameters

The following table lists the Xil_In32 function arguments.

Table 18: Xil_In32 Arguments

Name Description
Addr contains the address to perform the input operation

Returns

The 32 bit Value read from the specified input address.

Xil_In64
Performs an input operation for a memory location by reading the 64 bit Value read from that
address.

Prototype

INLINE u64 Xil_In64(UINTPTR Addr);

Parameters

The following table lists the Xil_In64 function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 15
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 19: Xil_In64 Arguments

Name Description
Addr contains the address to perform the input operation

Returns

The 64 bit Value read from the specified input address.

Xil_Out8
Performs an output operation for an memory location by writing the 8 bit Value to the the
specified address.

Prototype

INLINE void Xil_Out8(UINTPTR Addr, u8 Value);

Parameters

The following table lists the Xil_Out8 function arguments.

Table 20: Xil_Out8 Arguments

Name Description
Addr contains the address to perform the output operation
Value contains the 8 bit Value to be written at the specified address.

Returns

None.

Xil_Out16
Performs an output operation for a memory location by writing the 16 bit Value to the the
specified address.

Prototype

INLINE void Xil_Out16(UINTPTR Addr, u16 Value);

Parameters

The following table lists the Xil_Out16 function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 16
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 21: Xil_Out16 Arguments

Name Description
Addr contains the address to perform the output operation
Value contains the Value to be written at the specified address.

Returns

None.

Xil_Out32
Performs an output operation for a memory location by writing the 32 bit Value to the the
specified address.

Prototype

INLINE void Xil_Out32(UINTPTR Addr, u32 Value);

Parameters

The following table lists the Xil_Out32 function arguments.

Table 22: Xil_Out32 Arguments

Name Description
Addr contains the address to perform the output operation
Value contains the 32 bit Value to be written at the specified address.

Returns

None.

Xil_Out64
Performs an output operation for a memory location by writing the 64 bit Value to the the
specified address.

Prototype

INLINE void Xil_Out64(UINTPTR Addr, u64 Value);

Parameters

The following table lists the Xil_Out64 function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 17
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 23: Xil_Out64 Arguments

Name Description
Addr contains the address to perform the output operation
Value contains 64 bit Value to be written at the specified address.

Returns

None.

Xil_SecureOut32
Performs an output operation for a memory location by writing the 32 bit Value to the the
specified address and then reading it back to verify the value written in the register.

Prototype

INLINE int Xil_SecureOut32(UINTPTR Addr, u32 Value);

Parameters

The following table lists the Xil_SecureOut32 function arguments.

Table 24: Xil_SecureOut32 Arguments

Name Description
Addr contains the address to perform the output operation
Value contains 32 bit Value to be written at the specified address

Returns

Returns Status

• XST_SUCCESS on success
• XST_FAILURE on failure

Xil_EndianSwap16
Perform a 16-bit endian conversion.

Prototype

u16 Xil_EndianSwap16(u16 Data) INLINE __attribute__((always_inline));

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 18
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Parameters

The following table lists the Xil_EndianSwap16 function arguments.

Table 25: Xil_EndianSwap16 Arguments

Name Description
Data 16-bit value to be converted

Returns

16 bit Data with converted endianness

Xil_EndianSwap32
Perform a 32-bit endian conversion.

Prototype

u32 Xil_EndianSwap32(u32 Data) INLINE __attribute__((always_inline));

Parameters

The following table lists the Xil_EndianSwap32 function arguments.

Table 26: Xil_EndianSwap32 Arguments

Name Description
Data 32-bit value to be converted

Returns

32-bit data with converted endianness

Hardware Platform Information

This file contains information about hardware for which the code is built.

The xplatform_info.h file contains definitions for various available Xilinx platforms.

Also, it contains prototype of APIs, which can be used to get the platform information.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 19
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 27: Quick Function Reference

Type Name Arguments

u32 XGetPlatform_Info
void

u32 XGet_Zynq_UltraMp_Platform_info
void

u32 XGetPSVersion_Info
void

Functions
XGetPlatform_Info
This API is used to provide information about platform.

Prototype

u32 XGetPlatform_Info();

Returns

The information about platform defined in xplatform_info.h

XGet_Zynq_UltraMp_Platform_info
This API is used to provide information about zynq ultrascale MP platform.

Prototype

u32 XGet_Zynq_UltraMp_Platform_info();

Returns

The information about zynq ultrascale MP platform defined in xplatform_info.h

XGetPSVersion_Info
This API is used to provide information about PS Silicon version.

Prototype

u32 XGetPSVersion_Info();

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 20
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Returns

The information about PS Silicon version.

Basic Data types for Xilinx Software IP

The xil_types.h file contains basic types for Xilinx software IP.

These data types are applicable for all processors supported by Xilinx.

Customized APIs for Memory Operations

The xil_mem.h file contains prototype for functions related to memory operations.

These APIs are applicable for all processors supported by Xilinx.

Table 28: Quick Function Reference

Type Name Arguments

void Xil_MemCpy
void * dst
const void * src
u32 cnt

Functions
Xil_MemCpy
This function copies memory from once location to other.

Prototype

void Xil_MemCpy(void *dst, const void *src, u32 cnt);

Parameters

The following table lists the Xil_MemCpy function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 21
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 29: Xil_MemCpy Arguments

Name Description
dst pointer pointing to destination memory
src pointer pointing to source memory
cnt 32 bit length of bytes to be copied

Xilinx Software Status Codes

The xstatus.h file contains the Xilinx software status codes.These codes are used throughout the
Xilinx device drivers.

Test Utilities for Memory and Caches

The xil_testcache.h, xil_testio.h and the xil_testmem.h files contain utility functions to test cache
and memory.

Details of supported tests and subtests are listed below.

The xil_testcache.h file contains utility functions to test cache.

The xil_testio.h file contains utility functions to test endian related memory IO functions.

A subset of the memory tests can be selected or all of the tests can be run in order. If there is an
error detected by a subtest, the test stops and the failure code is returned. Further tests are not
run even if all of the tests are selected.

• Cache test: xil_testcache.h contains utility functions to test cache.

• I/O test: The Xil_testio.h file contains endian related memory IO functions. A subset of the
memory tests can be selected or all of the tests can be run in order. If there is an error
detected by a subtest, the test stops and the failure code is returned. Further tests are not run
even if all of the tests are selected.
• Memory test: The xil_testmem.h file contains utility functions to test memory. A subset of the
memory tests can be selected or all of the tests can be run in order. If there is an error
detected by a subtest, the test stops and the failure code is returned. Further tests are not run
even if all of the tests are selected.

Following list describes the supported memory tests:

• XIL_TESTMEM_ALLMEMTESTS: This test runs all of the subtests.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 22
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

• XIL_TESTMEM_INCREMENT: This test starts at 'XIL_TESTMEM_INIT_VALUE' and uses the

incrementing value as the test value for memory.
• XIL_TESTMEM_WALKONES: Also known as the Walking ones test. This test uses a walking '1'
as the test value for memory.
location 1 = 0x00000001
location 2 = 0x00000002
...

• XIL_TESTMEM_WALKZEROS: Also known as the Walking zero's test. This test uses the
inverse value of the walking ones test as the test value for memory.
location 1 = 0xFFFFFFFE
location 2 = 0xFFFFFFFD
...

• XIL_TESTMEM_INVERSEADDR: Also known as the inverse address test. This test uses the
inverse of the address of the location under test as the test value for memory.
• XIL_TESTMEM_FIXEDPATTERN: Also known as the fixed pattern test. This test uses the
provided patters as the test value for memory. If zero is provided as the pattern the test uses
'0xDEADBEEF".

CAUTION! The tests are DESTRUCTIVE. Run before any initialized memory spaces have been set up. The
address provided to the memory tests is not checked for validity except for the NULL case. It is possible to
provide a code-space pointer for this test to start with and ultimately destroy executable code causing
random failures.

Note: Used for spaces where the address range of the region is smaller than the data width. If the memory
range is greater than 2 ** width, the patterns used in XIL_TESTMEM_WALKONES and
XIL_TESTMEM_WALKZEROS will repeat on a boundary of a power of two making it more difficult to
detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests
suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller
regions of memory to allow the test patterns used not to repeat over the region tested.

Table 30: Quick Function Reference

Type Name Arguments

s32 Xil_TestMem32
u32 * Addr
u32 Words
u32 Pattern
u8 Subtest

s32 Xil_TestMem16
u16 * Addr
u32 Words
u16 Pattern
u8 Subtest

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 23
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 30: Quick Function Reference (cont'd)

Type Name Arguments

s32 Xil_TestMem8
u8 * Addr
u32 Words
u8 Pattern
u8 Subtest

u32 RotateLeft
u32 Input
u8 Width

u32 RotateRight
u32 Input
u8 Width

s32 Xil_TestDCacheRange
void

s32 Xil_TestDCacheAll
void

s32 Xil_TestICacheRange
void

s32 Xil_TestICacheAll
void

s32 Xil_TestIO8
u8 * Addr
s32 Length
u8 Value

s32 Xil_TestIO16
u16 * Addr
s32 Length
u16 Value
s32 Kind
s32 Swap

s32 Xil_TestIO32
u32 * Addr
s32 Length
u32 Value
s32 Kind
s32 Swap

Functions
Xil_TestMem32
Perform a destructive 32-bit wide memory test.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 24
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Note: Used for spaces where the address range of the region is smaller than the data width. If the memory
range is greater than 2 ** Width, the patterns used in XIL_TESTMEM_WALKONES and
XIL_TESTMEM_WALKZEROS will repeat on a boundary of a power of two making it more difficult to
detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests
suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller
regions of memory to allow the test patterns used not to repeat over the region tested.

Prototype

s32 Xil_TestMem32(u32 *Addr, u32 Words, u32 Pattern, u8 Subtest);

Parameters

The following table lists the Xil_TestMem32 function arguments.

Table 31: Xil_TestMem32 Arguments

Name Description
Addr pointer to the region of memory to be tested.
Words length of the block.
Pattern constant used for the constant pattern test, if 0, 0xDEADBEEF is used.
Subtest test type selected. See xil_testmem.h for possible values.

Returns

• 0 is returned for a pass

• 1 is returned for a failure

Xil_TestMem16
Perform a destructive 16-bit wide memory test.

Note: Used for spaces where the address range of the region is smaller than the data width. If the memory
range is greater than 2 ** Width, the patterns used in XIL_TESTMEM_WALKONES and
XIL_TESTMEM_WALKZEROS will repeat on a boundary of a power of two making it more difficult to
detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests
suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller
regions of memory to allow the test patterns used not to repeat over the region tested.

Prototype

s32 Xil_TestMem16(u16 *Addr, u32 Words, u16 Pattern, u8 Subtest);

Parameters

The following table lists the Xil_TestMem16 function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 25
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Table 32: Xil_TestMem16 Arguments

Name Description
Addr pointer to the region of memory to be tested.
Words length of the block.
Pattern constant used for the constant Pattern test, if 0, 0xDEADBEEF is used.
Subtest type of test selected. See xil_testmem.h for possible values.

Returns

• -1 is returned for a failure

• 0 is returned for a pass

Xil_TestMem8
Perform a destructive 8-bit wide memory test.

Note: Used for spaces where the address range of the region is smaller than the data width. If the memory
range is greater than 2 ** Width, the patterns used in XIL_TESTMEM_WALKONES and
XIL_TESTMEM_WALKZEROS will repeat on a boundary of a power of two making it more difficult to
detect addressing errors. The XIL_TESTMEM_INCREMENT and XIL_TESTMEM_INVERSEADDR tests
suffer the same problem. Ideally, if large blocks of memory are to be tested, break them up into smaller
regions of memory to allow the test patterns used not to repeat over the region tested.

Prototype

s32 Xil_TestMem8(u8 *Addr, u32 Words, u8 Pattern, u8 Subtest);

Parameters

The following table lists the Xil_TestMem8 function arguments.

Table 33: Xil_TestMem8 Arguments

Name Description
Addr pointer to the region of memory to be tested.
Words length of the block.
Pattern constant used for the constant pattern test, if 0, 0xDEADBEEF is used.
Subtest type of test selected. See xil_testmem.h for possible values.

Returns

• -1 is returned for a failure

• 0 is returned for a pass

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 26
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

RotateLeft
Rotates the provided value to the left one bit position.

Prototype

u32 RotateLeft(u32 Input, u8 Width);

Parameters

The following table lists the RotateLeft function arguments.

Table 34: RotateLeft Arguments

Name Description
Input is value to be rotated to the left
Width is the number of bits in the input data

Returns

The resulting unsigned long value of the rotate left

RotateRight
Rotates the provided value to the right one bit position.

Prototype

u32 RotateRight(u32 Input, u8 Width);

Parameters

The following table lists the RotateRight function arguments.

Table 35: RotateRight Arguments

Name Description
Input value to be rotated to the right
Width number of bits in the input data

Returns

The resulting u32 value of the rotate right

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 27
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Xil_TestDCacheRange
Perform DCache range related API test such as Xil_DCacheFlushRange and
Xil_DCacheInvalidateRange.

This test function writes a constant value to the Data array, flushes the range, writes a new
value, then invalidates the corresponding range.

Prototype

s32 Xil_TestDCacheRange(void);

Returns

• -1 is returned for a failure

• 0 is returned for a pass

Xil_TestDCacheAll
Perform DCache all related API test such as Xil_DCacheFlush and Xil_DCacheInvalidate.

This test function writes a constant value to the Data array, flushes the DCache, writes a new
value, then invalidates the DCache.

Prototype

s32 Xil_TestDCacheAll(void);

Returns

• 0 is returned for a pass

• -1 is returned for a failure

Xil_TestICacheRange
Perform Xil_ICacheInvalidateRange() on a few function pointers.

Note: The function will hang if it fails.

Prototype

s32 Xil_TestICacheRange(void);

Returns

• 0 is returned for a pass

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 28
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Xil_TestICacheAll
Perform Xil_ICacheInvalidate() on a few function pointers.

Note: The function will hang if it fails.

Prototype

s32 Xil_TestICacheAll(void);

Returns

• 0 is returned for a pass

Xil_TestIO8
Perform a destructive 8-bit wide register IO test where the register is accessed using Xil_Out8
and Xil_In8, and comparing the written values by reading them back.

Prototype

s32 Xil_TestIO8(u8 *Addr, s32 Length, u8 Value);

Parameters

The following table lists the Xil_TestIO8 function arguments.

Table 36: Xil_TestIO8 Arguments

Name Description
Addr a pointer to the region of memory to be tested.
Length Length of the block.
Value constant used for writing the memory.

Returns

• -1 is returned for a failure

• 0 is returned for a pass

Xil_TestIO16
Perform a destructive 16-bit wide register IO test.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 29
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Each location is tested by sequentially writing a 16-bit wide register, reading the register, and
comparing value. This function tests three kinds of register IO functions, normal register IO, little-
endian register IO, and big-endian register IO. When testing little/big-endian IO, the function
performs the following sequence, Xil_Out16LE/Xil_Out16BE, Xil_In16, Compare In-Out values,
Xil_Out16, Xil_In16LE/Xil_In16BE, Compare In-Out values. Whether to swap the read-in value
before comparing is controlled by the 5th argument.

Prototype

s32 Xil_TestIO16(u16 *Addr, s32 Length, u16 Value, s32 Kind, s32 Swap);

Parameters

The following table lists the Xil_TestIO16 function arguments.

Table 37: Xil_TestIO16 Arguments

Name Description
Addr a pointer to the region of memory to be tested.
Length Length of the block.
Value constant used for writing the memory.
Kind Type of test. Acceptable values are: XIL_TESTIO_DEFAULT, XIL_TESTIO_LE,
XIL_TESTIO_BE.
Swap indicates whether to byte swap the read-in value.

Returns

• -1 is returned for a failure

• 0 is returned for a pass

Xil_TestIO32
Perform a destructive 32-bit wide register IO test.

Each location is tested by sequentially writing a 32-bit wide register, reading the register, and
comparing value. This function tests three kinds of register IO functions, normal register IO, little-
endian register IO, and big-endian register IO. When testing little/big-endian IO, the function
perform the following sequence, Xil_Out32LE/ Xil_Out32BE, Xil_In32, Compare, Xil_Out32,
Xil_In32LE/Xil_In32BE, Compare. Whether to swap the read-in value *before comparing is
controlled by the 5th argument.

Prototype

s32 Xil_TestIO32(u32 *Addr, s32 Length, u32 Value, s32 Kind, s32 Swap);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 30
 Chapter 1: Xilinx Hardware Abstraction Layer APIs

Parameters

The following table lists the Xil_TestIO32 function arguments.

Table 38: Xil_TestIO32 Arguments

Name Description
Addr a pointer to the region of memory to be tested.
Length Length of the block.
Value constant used for writing the memory.
Kind type of test. Acceptable values are: XIL_TESTIO_DEFAULT, XIL_TESTIO_LE,
XIL_TESTIO_BE.
Swap indicates whether to byte swap the read-in value.

Returns

• -1 is returned for a failure

• 0 is returned for a pass

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 31
 Chapter 2: MicroBlaze Processor APIs

Chapter 2

MicroBlaze Processor APIs

MicroBlaze Processor API

This section provides a linked summary and detailed descriptions of the MicroBlaze Processor
APIs.

MicroBlaze Pseudo-asm Macros and Interrupt

Handling APIs
The MicroBlaze BSP includes macros to provide convenient access to various registers in the
MicroBlaze processor. Some of these macros are very useful within exception handlers for
retrieving information about the exception. Also, the interrupt handling functions help manage
interrupt handling on MicroBlaze processor devices. To use these functions, include the header
file mb_interface.h in your source code.

Table 39: Quick Function Reference

Type Name Arguments

void microblaze_register_handler
XInterruptHandler Handler
void * DataPtr

void microblaze_register_exception_handler
u32 ExceptionId
Top
void * DataPtr

Functions
microblaze_register_handler
Registers a top-level interrupt handler for the MicroBlaze.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 32
 Chapter 2: MicroBlaze Processor APIs

The argument provided in this call as the DataPtr is used as the argument for the handler when it
is called.

Prototype

void microblaze_register_handler(XInterruptHandler Handler, void *DataPtr);

Parameters

The following table lists the microblaze_register_handler function arguments.

Table 40: microblaze_register_handler Arguments

Name Description
Handler Top level handler.
DataPtr a reference to data that will be passed to the handler when it gets called.

Returns

None.

microblaze_register_exception_handler
Registers an exception handler for the MicroBlaze.

The argument provided in this call as the DataPtr is used as the argument for the handler when it
is called.

Prototype

void microblaze_register_exception_handler(u32 ExceptionId,

Xil_ExceptionHandler Handler, void *DataPtr);

Parameters

The following table lists the microblaze_register_exception_handler function

arguments.

Table 41: microblaze_register_exception_handler Arguments

Name Description
ExceptionId is the id of the exception to register this handler for.
Top level handler.
DataPtr is a reference to data that will be passed to the handler when it gets called.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 33
 Chapter 2: MicroBlaze Processor APIs

Returns

None.

MicroBlaze Exception APIs

The xil_exception.h file, available in the <install-directory>/src/microblaze folder, contains
Microblaze specific exception related APIs and macros.

Application programs can use these APIs for various exception related operations. For example,
enable exception, disable exception, register exception hander.

Note: To use exception related functions, xil_exception.h must be added in source code

Table 42: Quick Function Reference

Type Name Arguments

void Xil_ExceptionNullHandler
void * Data

void Xil_ExceptionInit
void

void Xil_ExceptionEnable
void

void Xil_ExceptionDisable
void

void Xil_ExceptionRegisterHandler
u32 Id
Xil_ExceptionHandler Handler
void * Data

void Xil_ExceptionRemoveHandler
u32 Id

Functions
Xil_ExceptionNullHandler
This function is a stub handler that is the default handler that gets called if the application has
not setup a handler for a specific exception.

The function interface has to match the interface specified for a handler even though none of the
arguments are used.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 34
 Chapter 2: MicroBlaze Processor APIs

Prototype

void Xil_ExceptionNullHandler(void *Data);

Parameters

The following table lists the Xil_ExceptionNullHandler function arguments.

Table 43: Xil_ExceptionNullHandler Arguments

Name Description
Data unused by this function.

Xil_ExceptionInit
Initialize exception handling for the processor.

The exception vector table is setup with the stub handler for all exceptions.

Prototype

void Xil_ExceptionInit(void);

Xil_ExceptionEnable
Enable Exceptions.

Prototype

void Xil_ExceptionEnable(void);

Xil_ExceptionDisable
Disable Exceptions.

Prototype

void Xil_ExceptionDisable(void);

Xil_ExceptionRegisterHandler
Makes the connection between the Id of the exception source and the associated handler that is
to run when the exception is recognized.

The argument provided in this call as the DataPtr is used as the argument for the handler when it
is called.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 35
 Chapter 2: MicroBlaze Processor APIs

Prototype

void Xil_ExceptionRegisterHandler(u32 Id, Xil_ExceptionHandler Handler,

void *Data);

Parameters

The following table lists the Xil_ExceptionRegisterHandler function arguments.

Table 44: Xil_ExceptionRegisterHandler Arguments

Name Description
Id contains the 32 bit ID of the exception source and should be XIL_EXCEPTION_INT or be
in the range of 0 to XIL_EXCEPTION_LAST. See xil_mach_exception.h for further
information.
Handler handler function to be registered for exception
Data a reference to data that will be passed to the handler when it gets called.

Xil_ExceptionRemoveHandler
Removes the handler for a specific exception Id.

The stub handler is then registered for this exception Id.

Prototype

void Xil_ExceptionRemoveHandler(u32 Id);

Parameters

The following table lists the Xil_ExceptionRemoveHandler function arguments.

Table 45: Xil_ExceptionRemoveHandler Arguments

Name Description
Id contains the 32 bit ID of the exception source and should be XIL_EXCEPTION_INT or in
the range of 0 to XIL_EXCEPTION_LAST. See xexception_l.h for further information.

MicroBlaze Cache APIs

This contains implementation of cache related driver functions.

The xil_cache.h file contains cache related driver functions (or macros) that can be used to access
the device.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 36
 Chapter 2: MicroBlaze Processor APIs

The user should refer to the hardware device specification for more details of the device
operation. The functions in this header file can be used across all Xilinx supported processors.

Table 46: Quick Function Reference

Type Name Arguments

void Xil_DCacheDisable
void

void Xil_ICacheDisable
void

Functions
Xil_DCacheDisable
Disable the data cache.

Prototype

void Xil_DCacheDisable(void);

Returns

None.

Xil_ICacheDisable
Disable the instruction cache.

Prototype

void Xil_ICacheDisable(void);

Returns

None.

Microblaze Cache Maintenance Macro

Microblaze BSP includes macros to provide mechanism to conduct cache maintenance
operations. To use these functions, include the header file xil_cache.h in your source code.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 37
 Chapter 2: MicroBlaze Processor APIs

Definitions
#Define Xil_L1DCacheInvalidate

Description

Invalidate the entire L1 data cache.

If the cacheline is modified (dirty), the modified contents are lost.

Note: Processor must be in real mode.

#Define Xil_L2CacheInvalidate

Description

Invalidate the entire L2 data cache.

If the cacheline is modified (dirty),the modified contents are lost.

Note: Processor must be in real mode.

#Define Xil_L1DCacheInvalidateRange

Description

Invalidate the L1 data cache for the given address range.

If the bytes specified by the address (Addr) are cached by the L1 data cache, the cacheline
containing that byte is invalidated.If the cacheline is modified (dirty), the modified contents are
lost.

Note: Processor must be in real mode.

Parameters

The following table lists the Xil_L1DCacheInvalidateRange function arguments.

Table 47: Xil_L1DCacheInvalidateRange Arguments

Name Description
Addr is address of range to be invalidated.
Len is the length in bytes to be invalidated.

#Define Xil_L2CacheInvalidateRange

Description

Invalidate the L1 data cache for the given address range.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 38
 Chapter 2: MicroBlaze Processor APIs

If the bytes specified by the address (Addr) are cached by the L1 data cache, the cacheline
containing that byte is invalidated. If the cacheline is modified (dirty), the modified contents are
lost.

Note: Processor must be in real mode.

Parameters

The following table lists the Xil_L2CacheInvalidateRange function arguments.

Table 48: Xil_L2CacheInvalidateRange Arguments

Name Description
Addr address of range to be invalidated.
Len length in bytes to be invalidated.

#Define Xil_L1DCacheFlushRange

Description

Flush the L1 data cache for the given address range.

If the bytes specified by the address (Addr) are cached by the data cache, and is modified (dirty),
the cacheline will be written to system memory.The cacheline will also be invalidated.

Parameters

The following table lists the Xil_L1DCacheFlushRange function arguments.

Table 49: Xil_L1DCacheFlushRange Arguments

Name Description
Addr the starting address of the range to be flushed.
Len length in byte to be flushed.

#Define Xil_L2CacheFlushRange

Description

Flush the L2 data cache for the given address range.

If the bytes specified by the address (Addr) are cached by the data cache, and is modified (dirty),
the cacheline will be written to system memory. The cacheline will also be invalidated.

Parameters

The following table lists the Xil_L2CacheFlushRange function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 39
 Chapter 2: MicroBlaze Processor APIs

Table 50: Xil_L2CacheFlushRange Arguments

Name Description
Addr the starting address of the range to be flushed.
Len length in byte to be flushed.

#Define Xil_L1DCacheFlush

Description

Flush the entire L1 data cache.

If any cacheline is dirty, the cacheline will be written to system memory. The entire data cache
will be invalidated.

#Define Xil_L2CacheFlush

Description

Flush the entire L2 data cache.

If any cacheline is dirty, the cacheline will be written to system memory. The entire data cache
will be invalidated.

#Define Xil_L1ICacheInvalidateRange

Description

Invalidate the instruction cache for the given address range.

Parameters

The following table lists the Xil_L1ICacheInvalidateRange function arguments.

Table 51: Xil_L1ICacheInvalidateRange Arguments

Name Description
Addr is address of ragne to be invalidated.
Len is the length in bytes to be invalidated.

#Define Xil_L1ICacheInvalidate

Description

Invalidate the entire instruction cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 40
 Chapter 2: MicroBlaze Processor APIs

#Define Xil_L1DCacheEnable

Description

Enable the L1 data cache.

Note: This is processor specific.

#Define Xil_L1DCacheDisable

Description

Disable the L1 data cache.

Note: This is processor specific.

#Define Xil_L1ICacheEnable

Description

Enable the instruction cache.

Note: This is processor specific.

#Define Xil_L1ICacheDisable

Description

Disable the L1 Instruction cache.

Note: This is processor specific.

#Define Xil_DCacheEnable

Description

Enable the data cache.

#Define Xil_ICacheEnable

Description

Enable the instruction cache.

#Define Xil_DCacheInvalidate

Description

Invalidate the entire Data cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 41
 Chapter 2: MicroBlaze Processor APIs

#Define Xil_DCacheInvalidateRange

Description

Invalidate the Data cache for the given address range.

If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Parameters

The following table lists the Xil_DCacheInvalidateRange function arguments.

Table 52: Xil_DCacheInvalidateRange Arguments

Name Description
Addr Start address of range to be invalidated.
Len Length of range to be invalidated in bytes.

#Define Xil_DCacheFlush

Description

Flush the entire Data cache.

#Define Xil_DCacheFlushRange

Description

Flush the Data cache for the given address range.

If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the written to system memory first
before the before the line is invalidated.

Parameters

The following table lists the Xil_DCacheFlushRange function arguments.

Table 53: Xil_DCacheFlushRange Arguments

Name Description
Addr Start address of range to be flushed.
Len Length of range to be flushed in bytes.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 42
 Chapter 2: MicroBlaze Processor APIs

#Define Xil_ICacheInvalidate

Description

Invalidate the entire instruction cache.

MicroBlaze Processor FSL Macros

Microblaze BSP includes macros to provide convenient access to accelerators connected to the
MicroBlaze Fast Simplex Link (FSL) Interfaces.To use these functions, include the header file fsl.h
in your source code.

Definitions
#Define getfslx

Description

Performs a get function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the getfslx function arguments.

Table 54: getfslx Arguments

Name Description
val variable to sink data from get function
id literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

#Define putfslx

Description

Performs a put function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the putfslx function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 43
 Chapter 2: MicroBlaze Processor APIs

Table 55: putfslx Arguments

Name Description
val variable to source data to put function
id literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

#Define tgetfslx

Description

Performs a test get function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the tgetfslx function arguments.

Table 56: tgetfslx Arguments

Name Description
val variable to sink data from get function
id literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

#Define tputfslx

Description

Performs a put function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the tputfslx function arguments.

Table 57: tputfslx Arguments

Name Description
id FSL identifier
flags valid FSL macro flags

#Define getdfslx

Description

Performs a getd function on an input FSL of the MicroBlaze processor.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 44
 Chapter 2: MicroBlaze Processor APIs

Parameters

The following table lists the getdfslx function arguments.

Table 58: getdfslx Arguments

Name Description
val variable to sink data from getd function
var literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

#Define putdfslx

Description

Performs a putd function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the putdfslx function arguments.

Table 59: putdfslx Arguments

Name Description
val variable to source data to putd function
var literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

#Define tgetdfslx

Description

Performs a test getd function on an input FSL of the MicroBlaze processor;.

Parameters

The following table lists the tgetdfslx function arguments.

Table 60: tgetdfslx Arguments

Name Description
val variable to sink data from getd function
var literal in the range of 0 to 7 (0 to 15 for MicroBlaze v7.00.a and later)
flags valid FSL macro flags

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 45
 Chapter 2: MicroBlaze Processor APIs

#Define tputdfslx

Description

Performs a put function on an input FSL of the MicroBlaze processor.

Parameters

The following table lists the tputdfslx function arguments.

Table 61: tputdfslx Arguments

Name Description
var FSL identifier
flags valid FSL macro flags

MicroBlaze PVR Access Routines and Macros

The MicroBlaze processor v5.00.a and later versions have configurable Processor Version
Registers (PVRs). The contents of the PVR are captured using the pvr_t data structure, which is
defined as an array of 32-bit words, with each word corresponding to a PVR register on
hardware. The number of PVR words is determined by the number of PVRs configured in the
hardware. You should not attempt to access PVR registers that are not present in hardware, as
the pvr_t data structure is resized to hold only as many PVRs as are present in hardware. To
access information in the PVR:

1. Use the microblaze_get_pvr() function to populate the PVR data into a pvr_t data
structure.
2. In subsequent steps, you can use any one of the PVR access macros list to get individual data
stored in the PVR.
Note: The pvr.h header file must be included to source to use PVR macros.

Table 62: Quick Function Reference

Type Name Arguments

int microblaze_get_pvr
pvr-

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 46
 Chapter 2: MicroBlaze Processor APIs

Functions
microblaze_get_pvr
Populate the PVR data structure to which pvr points, with the values of the hardware PVR
registers.

Prototype

int microblaze_get_pvr(pvr_t *pvr);

Parameters

The following table lists the microblaze_get_pvr function arguments.

Table 63: microblaze_get_pvr Arguments

Name Description
pvr- address of PVR data structure to be populated

Returns

0 - SUCCESS -1 - FAILURE

Definitions
#Define MICROBLAZE_PVR_IS_FULL

Description

Return non-zero integer if PVR is of type FULL, 0 if basic.

Parameters

The following table lists the MICROBLAZE_PVR_IS_FULL function arguments.

Table 64: MICROBLAZE_PVR_IS_FULL Arguments

Name Description
_pvr pvr data structure

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 47
 Chapter 2: MicroBlaze Processor APIs

#Define MICROBLAZE_PVR_USE_BARREL

Description

Return non-zero integer if hardware barrel shifter present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_BARREL function arguments.

Table 65: MICROBLAZE_PVR_USE_BARREL Arguments

Name Description
_pvr pvr data structure

#Define MICROBLAZE_PVR_USE_DIV

Description

Return non-zero integer if hardware divider present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_DIV function arguments.

Table 66: MICROBLAZE_PVR_USE_DIV Arguments

Name Description
_pvr pvr data structure

#Define MICROBLAZE_PVR_USE_HW_MUL

Description

Return non-zero integer if hardware multiplier present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_HW_MUL function arguments.

Table 67: MICROBLAZE_PVR_USE_HW_MUL Arguments

Name Description
_pvr pvr data structure

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 48
 Chapter 2: MicroBlaze Processor APIs

#Define MICROBLAZE_PVR_USE_FPU

Description

Return non-zero integer if hardware floating point unit (FPU) present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_FPU function arguments.

Table 68: MICROBLAZE_PVR_USE_FPU Arguments

Name Description
_pvr pvr data structure

#Define MICROBLAZE_PVR_USE_ICACHE

Description

Return non-zero integer if I-cache present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_ICACHE function arguments.

Table 69: MICROBLAZE_PVR_USE_ICACHE Arguments

Name Description
_pvr pvr data structure

#Define MICROBLAZE_PVR_USE_DCACHE

Description

Return non-zero integer if D-cache present.

Parameters

The following table lists the MICROBLAZE_PVR_USE_DCACHE function arguments.

Table 70: MICROBLAZE_PVR_USE_DCACHE Arguments

Name Description
_pvr pvr data structure

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 49
 Chapter 2: MicroBlaze Processor APIs

Sleep Routines for MicroBlaze Processor

The microblaze_sleep.h file contains MicroBlaze sleep APIs. These APIs provides delay for
requested duration.

Note: The microblaze_sleep.h file may contain architecture-dependent items.

Table 71: Quick Function Reference

Type Name Arguments

u32 Xil_SetMBFrequency
u32 Val

u32 Xil_GetMBFrequency
void

void MB_Sleep
MilliSeconds-

Functions
Xil_SetMBFrequency
Sets variable which stores Microblaze frequency value.

Note: It must be called after runtime change in Microblaze frequency, failing to do so would result in to
incorrect behavior of sleep routines

Prototype

u32 Xil_SetMBFrequency(u32 Val);

Parameters

The following table lists the Xil_SetMBFrequency function arguments.

Table 72: Xil_SetMBFrequency Arguments

Name Description
Val - Frequency value to be set

Returns

XST_SUCCESS - If frequency updated successfully XST_INVALID_PARAM - If specified

frequency value is not valid

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 50
 Chapter 2: MicroBlaze Processor APIs

Xil_GetMBFrequency
Returns current Microblaze frequency value.

Prototype

u32 Xil_GetMBFrequency();

Returns

MBFreq - Current Microblaze frequency value

MB_Sleep
Provides delay for requested duration.

Note: Instruction cache should be enabled for this to work.

Prototype

void MB_Sleep(u32 MilliSeconds) __attribute__((__deprecated__));

Parameters

The following table lists the MB_Sleep function arguments.

Table 73: MB_Sleep Arguments

Name Description
MilliSeconds- Delay time in milliseconds.

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 51
 Chapter 3: Arm Processor Common APIs

Chapter 3

Arm Processor Common APIs

This section provides a linked summary and detailed descriptions of the Arm Processor Common
APIs.

Arm Processor Exception Handling

Arm processors specific exception related APIs for Arm Cortex-A53, Cortex-A9, and Cortex-R5F
can utilized for enabling/disabling IRQ, registering/removing handler for exceptions or initializing
exception vector table with null handler.

Table 74: Quick Function Reference

Type Name Arguments

void Xil_ExceptionRegisterHandler
u32 Exception_id
Xil_ExceptionHandler Handler
void * Data

void Xil_ExceptionRemoveHandler
u32 Exception_id

void Xil_GetExceptionRegisterHandler
u32 Exception_id
Xil_ExceptionHandler * Handler
void ** Data

void Xil_ExceptionInit
void

void Xil_DataAbortHandler
void

void Xil_PrefetchAbortHandler
void

void Xil_UndefinedExceptionHandler
void

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 52
 Chapter 3: Arm Processor Common APIs

Functions
Xil_ExceptionRegisterHandler
Register a handler for a specific exception.

This handler is being called when the processor encounters the specified exception.

Prototype

void Xil_ExceptionRegisterHandler(u32 Exception_id, Xil_ExceptionHandler

Handler, void *Data);

Parameters

The following table lists the Xil_ExceptionRegisterHandler function arguments.

Table 75: Xil_ExceptionRegisterHandler Arguments

Name Description
Exception_id contains the ID of the exception source and should be in the range of 0 to
XIL_EXCEPTION_ID_LAST. See xil_exception.h for further information.
Handler to the Handler for that exception.
Data is a reference to Data that will be passed to the Handler when it gets called.

Returns

None.

Xil_ExceptionRemoveHandler
Removes the handler for a specific exception Id.

The stub handler is then registered for this exception Id.

Prototype

void Xil_ExceptionRemoveHandler(u32 Exception_id);

Parameters

The following table lists the Xil_ExceptionRemoveHandler function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 53
 Chapter 3: Arm Processor Common APIs

Table 76: Xil_ExceptionRemoveHandler Arguments

Name Description
Exception_id contains the ID of the exception source and should be in the range of 0 to
XIL_EXCEPTION_ID_LAST. See xil_exception.h for further information.

Returns

None.

Xil_GetExceptionRegisterHandler
Get a handler for a specific exception.

This handler is being called when the processor encounters the specified exception.

Prototype

void Xil_GetExceptionRegisterHandler(u32 Exception_id, Xil_ExceptionHandler

*Handler, void **Data);

Parameters

The following table lists the Xil_GetExceptionRegisterHandler function arguments.

Table 77: Xil_GetExceptionRegisterHandler Arguments

Name Description
Exception_id contains the ID of the exception source and should be in the range of 0 to
XIL_EXCEPTION_ID_LAST. See xil_exception.h for further information.
Handler to the Handler for that exception.
Data is a reference to Data that will be passed to the Handler when it gets called.

Returns

None.

Xil_ExceptionInit
The function is a common API used to initialize exception handlers across all supported arm
processors.

For Arm Cortex-A53, Cortex-R5F, and Cortex-A9, the exception handlers are being initialized
statically and this function does not do anything. However, it is still present to take care of
backward compatibility issues (in earlier versions of BSPs, this API was being used to initialize
exception handlers).

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 54
 Chapter 3: Arm Processor Common APIs

Prototype

void Xil_ExceptionInit(void);

Returns

None.

Xil_DataAbortHandler
Default Data abort handler which prints data fault status register through which information
about data fault can be acquired.

Prototype

void Xil_DataAbortHandler(void *CallBackRef);

Returns

None.

Xil_PrefetchAbortHandler
Default Prefetch abort handler which prints prefetch fault status register through which
information about instruction prefetch fault can be acquired.

Prototype

void Xil_PrefetchAbortHandler(void *CallBackRef);

Returns

None.

Xil_UndefinedExceptionHandler
Default undefined exception handler which prints address of the undefined instruction if debug
prints are enabled.

Prototype

void Xil_UndefinedExceptionHandler(void *CallBackRef);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 55
 Chapter 3: Arm Processor Common APIs

Definitions
Define Xil_ExceptionEnableMask

Definition

#define Xil_ExceptionEnableMask { \
register u32 Reg __asm("cpsr"); \
mtcpsr((Reg) & (~((Mask) & XIL_EXCEPTION_ALL))); \
}

Description

Enable Exceptions.

Note: If bit is 0, exception is enabled. C-Style signature: void Xil_ExceptionEnableMask(Mask)

Define Xil_ExceptionEnable

Definition

#define Xil_ExceptionEnable

Xil_ExceptionEnableMask
(XIL_EXCEPTION_IRQ)

Description

Enable the IRQ exception.

Note: None.

Define Xil_ExceptionDisableMask

Definition

#define Xil_ExceptionDisableMask
{ \
register u32 Reg __asm("cpsr"); \
mtcpsr((Reg) | ((Mask) & XIL_EXCEPTION_ALL)); \
}

Description

Disable Exceptions.

Note: If bit is 1, exception is disabled. C-Style signature: Xil_ExceptionDisableMask(Mask)

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 56
 Chapter 3: Arm Processor Common APIs

Define Xil_ExceptionDisable

Definition

#define Xil_ExceptionDisable

Xil_ExceptionDisableMask
(XIL_EXCEPTION_IRQ)

Description

Disable the IRQ exception.

Note: None.

Define Xil_EnableNestedInterrupts

Definition

#define Xil_EnableNestedInterrupts __asm__ __volatile__ ("stmfd

sp!, {lr}"); \
__asm__ __volatile__ ("mrs lr, spsr"); \
__asm__ __volatile__ ("stmfd sp!, {lr}"); \
__asm__ __volatile__ ("msr cpsr_c, #0x1F"); \
__asm__ __volatile__ ("stmfd sp!, {lr}");

Description

Enable nested interrupts by clearing the I and F bits in CPSR.

This API is defined for Cortex-A9 and Cortex-R5F.

Note: This macro is supposed to be used from interrupt handlers. In the interrupt handler the interrupts are
disabled by default (I and F are 1). To allow nesting of interrupts, this macro should be used. It clears the I
and F bits by changing the ARM mode to system mode. Once these bits are cleared and provided the
preemption of interrupt conditions are met in the GIC, nesting of interrupts will start happening. Caution:
This macro must be used with caution. Before calling this macro, the user must ensure that the source of
the current IRQ is appropriately cleared. Otherwise, as soon as we clear the I and F bits, there can be an
infinite loop of interrupts with an eventual crash (all the stack space getting consumed).

Define Xil_DisableNestedInterrupts

Definition

#define Xil_DisableNestedInterrupts __asm__ __volatile__ ("ldmfd

sp!, {lr}"); \
__asm__ __volatile__ ("msr cpsr_c, #0x92"); \
__asm__ __volatile__ ("ldmfd sp!, {lr}"); \
__asm__ __volatile__ ("msr spsr_cxsf, lr"); \
__asm__ __volatile__ ("ldmfd sp!, {lr}"); \

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 57
 Chapter 3: Arm Processor Common APIs

Description

Disable the nested interrupts by setting the I and F bits.

This API is defined for Cortex-A9 and Cortex-R5F.

Note: This macro is meant to be called in the interrupt service routines. This macro cannot be used
independently. It can only be used when nesting of interrupts have been enabled by using the macro
Xil_EnableNestedInterrupts() . In a typical flow, the user first calls the Xil_EnableNestedInterrupts
in the ISR at the appropriate point. The user then must call this macro before exiting the interrupt service
routine. This macro puts the ARM back in IRQ/FIQ mode and hence sets back the I and F bits.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 58
 Chapter 4: Arm Cortex-R5F Processor APIs

Chapter 4

Arm Cortex-R5F Processor APIs

Arm Cortex-R5F Processor API

Standalone BSP contains boot code, cache, exception handling, file and memory management,
configuration, time and processor-specific include functions.

It supports gcc compiler. This section provides a linked summary and detailed descriptions of the
Arm Cortex-R5F processor APIs.

Arm Cortex-R5F Processor Boot Code

The boot.S file contains a minimal set of code for transferring control from the processor reset
location of the processor to the start of the application. The boot code performs minimum
configuration which is required for an application to run starting from reset state of the
processor. Below is a sequence illustrating what all configuration is performed before control
reaches to main function.

1. Program vector table base for exception handling

2. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system)
3. Disable instruction cache, data cache and MPU
4. Invalidate instruction and data cache
5. Configure MPU with short descriptor translation table format and program base address of
translation table
6. Enable data cache, instruction cache and MPU
7. Enable Floating point unit
8. Transfer control to _start which clears BSS sections and jumping to main application

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 59
 Chapter 4: Arm Cortex-R5F Processor APIs

Arm Cortex-R5F Processor MPU specific APIs

MPU functions provides access to MPU operations such as enable MPU, disable MPU and set
attribute for section of memory.

Boot code invokes Init_MPU function to configure the MPU. A total of 10 MPU regions are
allocated with another 6 being free for users. Overview of the memory attributes for different
MPU regions is as given below,

Memory Range Attributes of MPURegion

DDR 0x00000000 - 0x7FFFFFFF Normal write-back Cacheable
PL 0x80000000 - 0xBFFFFFFF Strongly Ordered
QSPI 0xC0000000 - 0xDFFFFFFF Device Memory
PCIe 0xE0000000 - 0xEFFFFFFF Device Memory
STM_CORESIGHT 0xF8000000 - 0xF8FFFFFF Device Memory
RPU_R5_GIC 0xF9000000 - 0xF90FFFFF Device memory
FPS 0xFD000000 - 0xFDFFFFFF Device Memory
LPS 0xFE000000 - 0xFFFFFFFF Device Memory
OCM 0xFFFC0000 - 0xFFFFFFFF Normal write-back Cacheable

Note: For a system where DDR is less than 2GB, region after DDR and before PL is marked as undefined in
translation table. Memory range 0xFE000000-0xFEFFFFFF is allocated for upper LPS slaves, where as
memory region 0xFF000000-0xFFFFFFFF is allocated for lower LPS slaves.

Table 78: Quick Function Reference

Type Name Arguments

void Xil_SetTlbAttributes
addr
u32 attrib

void Xil_EnableMPU
void

void Xil_DisableMPU
void

u32 Xil_SetMPURegion
INTPTR addr
u64 size
u32 attrib

u32 Xil_UpdateMPUConfig
u32 reg_num
INTPTR address
u32 size
u32 attrib

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 60
 Chapter 4: Arm Cortex-R5F Processor APIs

Table 78: Quick Function Reference (cont'd)

Type Name Arguments

void Xil_GetMPUConfig
XMpu_Config mpuconfig

u32 Xil_GetNumOfFreeRegions
void

u32 Xil_GetNextMPURegion
void

u32 Xil_DisableMPURegionByRegNum
u32 reg_num

u16 Xil_GetMPUFreeRegMask
void

u32 Xil_SetMPURegionByRegNum
u32 reg_num
INTPTR addr
u64 size
u32 attrib

void * Xil_MemMap
UINTPTR Physaddr
size_t size
u32 flags

Functions
Xil_SetTlbAttributes
This function sets the memory attributes for a section covering 1MB, of memory in the
translation table.

Prototype

void Xil_SetTlbAttributes(INTPTR Addr, u32 attrib);

Parameters

The following table lists the Xil_SetTlbAttributes function arguments.

Table 79: Xil_SetTlbAttributes Arguments

Name Description
addr 32-bit address for which memory attributes need to be set.
attrib Attribute for the given memory region.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 61
 Chapter 4: Arm Cortex-R5F Processor APIs

Returns

None.

Xil_EnableMPU
Enable MPU for Cortex-R5F processor.

This function invalidates I cache and flush the D Caches, and then enables the MPU.

Prototype

void Xil_EnableMPU(void);

Returns

None.

Xil_DisableMPU
Disable MPU for Cortex-R5F processors.

This function invalidates I cache and flush the D Caches, and then disabes the MPU.

Prototype

void Xil_DisableMPU(void);

Returns

None.

Xil_SetMPURegion
Set the memory attributes for a section of memory in the translation table.

Prototype

u32 Xil_SetMPURegion(INTPTR addr, u64 size, u32 attrib);

Parameters

The following table lists the Xil_SetMPURegion function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 62
 Chapter 4: Arm Cortex-R5F Processor APIs

Table 80: Xil_SetMPURegion Arguments

Name Description
addr 32-bit address for which memory attributes need to be set..
size size is the size of the region.
attrib Attribute for the given memory region.

Returns

None.

Xil_UpdateMPUConfig
Update the MPU configuration for the requested region number in the global MPU configuration
table.

Prototype

u32 Xil_UpdateMPUConfig(u32 reg_num, INTPTR address, u32 size, u32 attrib);

Parameters

The following table lists the Xil_UpdateMPUConfig function arguments.

Table 81: Xil_UpdateMPUConfig Arguments

Name Description
reg_num The requested region number to be updated information for.
address 32 bit address for start of the region.
size Requested size of the region.
attrib Attribute for the corresponding region.

Returns

XST_FAILURE: When the requested region number if 16 or more. XST_SUCCESS: When the
MPU configuration table is updated.

Xil_GetMPUConfig
The MPU configuration table is passed to the caller.

Prototype

void Xil_GetMPUConfig(XMpu_Config mpuconfig);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 63
 Chapter 4: Arm Cortex-R5F Processor APIs

Parameters

The following table lists the Xil_GetMPUConfig function arguments.

Table 82: Xil_GetMPUConfig Arguments

Name Description
mpuconfig This is of type XMpu_Config which is an array of 16 entries of type structure
representing the MPU config table

Returns

none

Xil_GetNumOfFreeRegions
Returns the total number of free MPU regions available.

Prototype

u32 Xil_GetNumOfFreeRegions(void);

Returns

Number of free regions available to users

Xil_GetNextMPURegion
Returns the next available free MPU region.

Prototype

u32 Xil_GetNextMPURegion(void);

Returns

The free MPU region available

Xil_DisableMPURegionByRegNum
Disables the corresponding region number as passed by the user.

Prototype

u32 Xil_DisableMPURegionByRegNum(u32 reg_num);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 64
 Chapter 4: Arm Cortex-R5F Processor APIs

Parameters

The following table lists the Xil_DisableMPURegionByRegNum function arguments.

Table 83: Xil_DisableMPURegionByRegNum Arguments

Name Description
reg_num The region number to be disabled

Returns

XST_SUCCESS: If the region could be disabled successfully XST_FAILURE: If the requested region
number is 16 or more.

Xil_GetMPUFreeRegMask
Returns the total number of free MPU regions available in the form of a mask.

A bit of 1 in the returned 16 bit value represents the corresponding region number to be
available. For example, if this function returns 0xC0000, this would mean, the regions 14 and 15
are available to users.

Prototype

u16 Xil_GetMPUFreeRegMask(void);

Returns

The free region mask as a 16 bit value

Xil_SetMPURegionByRegNum
Enables the corresponding region number as passed by the user.

Prototype

u32 Xil_SetMPURegionByRegNum(u32 reg_num, INTPTR addr, u64 size, u32

attrib);

Parameters

The following table lists the Xil_SetMPURegionByRegNum function arguments.

Table 84: Xil_SetMPURegionByRegNum Arguments

Name Description
reg_num The region number to be enabled

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 65
 Chapter 4: Arm Cortex-R5F Processor APIs

Table 84: Xil_SetMPURegionByRegNum Arguments (cont'd)

Name Description
addr 32 bit address for start of the region.
size Requested size of the region.
attrib Attribute for the corresponding region.

Returns

XST_SUCCESS: If the region could be created successfully XST_FAILURE: If the requested region
number is 16 or more.

Xil_MemMap
Memory mapping for Cortex-R5F. If successful, the mapped region will include all of the memory
requested, but may include more. Specifically, it will be a power of two in size, aligned on a
boundary of that size.

Prototype

void * Xil_MemMap(UINTPTR Physaddr, size_t size, u32 flags);

Parameters

The following table lists the Xil_MemMap function arguments.

Table 85: Xil_MemMap Arguments

Name Description
Physaddr is base physical address at which to start mapping. NULL in Physaddr masks possible
mapping errors.
size of region to be mapped.
flags used to set translation table.

Returns

Physaddr on success, NULL on error. Ambiguous if Physaddr==NULL

Arm Cortex-R5F Processor Cache Functions

Cache functions provide access to cache related operations such as flush and invalidate for
instruction and data caches.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 66
 Chapter 4: Arm Cortex-R5F Processor APIs

It gives option to perform the cache operations on a single cacheline, a range of memory and an
entire cache.

Table 86: Quick Function Reference

Type Name Arguments

void Xil_DCacheEnable
void

void Xil_DCacheDisable
void

void Xil_DCacheInvalidate
void

void Xil_DCacheInvalidateRange
INTPTR adr
u32 len

void Xil_DCacheFlush
void

void Xil_DCacheFlushRange
INTPTR adr
u32 len

void Xil_DCacheInvalidateLine
INTPTR adr

void Xil_DCacheFlushLine
INTPTR adr

void Xil_DCacheStoreLine
INTPTR adr

void Xil_ICacheEnable
void

void Xil_ICacheDisable
void

void Xil_ICacheInvalidate
void

void Xil_ICacheInvalidateRange
INTPTR adr
u32 len

void Xil_ICacheInvalidateLine
INTPTR adr

Functions
Xil_DCacheEnable
Enable the Data cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 67
 Chapter 4: Arm Cortex-R5F Processor APIs

Prototype

void Xil_DCacheEnable(void);

Returns

None.

Xil_DCacheDisable
Disable the Data cache.

Prototype

void Xil_DCacheDisable(void);

Returns

None.

Xil_DCacheInvalidate
Invalidate the entire Data cache.

Prototype

void Xil_DCacheInvalidate(void);

Returns

None.

Xil_DCacheInvalidateRange
Invalidate the Data cache for the given address range.

If the bytes specified by the address (adr) are cached by the Data cache,the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Prototype

void Xil_DCacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheInvalidateRange function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 68
 Chapter 4: Arm Cortex-R5F Processor APIs

Table 87: Xil_DCacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of range to be invalidated in bytes.

Returns

None.

Xil_DCacheFlush
Flush the entire Data cache.

Prototype

void Xil_DCacheFlush(void);

Returns

None.

Xil_DCacheFlushRange
Flush the Data cache for the given address range.

If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing
those bytes is invalidated.If the cacheline is modified (dirty), the written to system memory
before the lines are invalidated.

Prototype

void Xil_DCacheFlushRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheFlushRange function arguments.

Table 88: Xil_DCacheFlushRange Arguments

Name Description
adr 32bit start address of the range to be flushed.
len Length of the range to be flushed in bytes

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 69
 Chapter 4: Arm Cortex-R5F Processor APIs

Returns

None.

Xil_DCacheInvalidateLine
Invalidate a Data cache line.

If the byte specified by the address (adr) is cached by the data cache, the cacheline containing
that byte is invalidated.If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheInvalidateLine(INTPTR adr);

Parameters

The following table lists the Xil_DCacheInvalidateLine function arguments.

Table 89: Xil_DCacheInvalidateLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_DCacheFlushLine
Flush a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline
are written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheFlushLine(INTPTR adr);

Parameters

The following table lists the Xil_DCacheFlushLine function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 70
 Chapter 4: Arm Cortex-R5F Processor APIs

Table 90: Xil_DCacheFlushLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_DCacheStoreLine
Store a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache and the cacheline is
modified (dirty), the entire contents of the cacheline are written to system memory.After the
store completes, the cacheline is marked as unmodified (not dirty).

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheStoreLine(INTPTR adr);

Parameters

The following table lists the Xil_DCacheStoreLine function arguments.

Table 91: Xil_DCacheStoreLine Arguments

Name Description
adr 32bit address of the data to be stored

Returns

None.

Xil_ICacheEnable
Enable the instruction cache.

Prototype

void Xil_ICacheEnable(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 71
 Chapter 4: Arm Cortex-R5F Processor APIs

Xil_ICacheDisable
Disable the instruction cache.

Prototype

void Xil_ICacheDisable(void);

Returns

None.

Xil_ICacheInvalidate
Invalidate the entire instruction cache.

Prototype

void Xil_ICacheInvalidate(void);

Returns

None.

Xil_ICacheInvalidateRange
Invalidate the instruction cache for the given address range.

If the bytes specified by the address (adr) are cached by the Data cache, the cacheline containing
that byte is invalidated. If the cachelineis modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Prototype

void Xil_ICacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_ICacheInvalidateRange function arguments.

Table 92: Xil_ICacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 72
 Chapter 4: Arm Cortex-R5F Processor APIs

Returns

None.

Xil_ICacheInvalidateLine
Invalidate an instruction cache line.If the instruction specified by the address is cached by the
instruction cache, the cacheline containing that instruction is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_ICacheInvalidateLine(INTPTR adr);

Parameters

The following table lists the Xil_ICacheInvalidateLine function arguments.

Table 93: Xil_ICacheInvalidateLine Arguments

Name Description
adr 32bit address of the instruction to be invalidated.

Returns

None.

Arm Cortex-R5F Time Functions

The xtime_l.h provides access to 32-bit TTC timer counter.

These functions can be used by applications to track the time.

Table 94: Quick Function Reference

Type Name Arguments

void XTime_SetTime
XTime Xtime_Global

void XTime_GetTime
XTime * Xtime_Global

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 73
 Chapter 4: Arm Cortex-R5F Processor APIs

Functions
XTime_SetTime
TTC Timer runs continuously and the time can not be set as desired.

This API doesn't contain anything. It is defined to have uniformity across platforms.

Note: In multiprocessor environment reference time will reset/lost for all processors, when this function
called by any one processor.

Prototype

void XTime_SetTime(XTime Xtime_Global);

Parameters

The following table lists the XTime_SetTime function arguments.

Table 95: XTime_SetTime Arguments

Name Description
Xtime_Global 32 bit value to be written to the timer counter register.

Returns

None.

XTime_GetTime
Get the time from the timer counter register.

Prototype

void XTime_GetTime(XTime *Xtime_Global);

Parameters

The following table lists the XTime_GetTime function arguments.

Table 96: XTime_GetTime Arguments

Name Description
Xtime_Global Pointer to the 32 bit location to be updated with the time current value of timer
counter register.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 74
 Chapter 4: Arm Cortex-R5F Processor APIs

Returns

None.

Arm Cortex-R5F Event Counters Functions

Cortex-R5F event counter functions can be utilized to configure and control the Cortex-R5F
performance monitor events.

Cortex-R5F Performance Monitor has 3 event counters which can be used to count a variety of
events described in Coretx-R5 TRM. The xpm_counter.h file defines configurations
XPM_CNTRCFGx which can be used to program the event counters to count a set of events.

Table 97: Quick Function Reference

Type Name Arguments

void Xpm_SetEvents
s32 PmcrCfg

void Xpm_GetEventCounters
u32 * PmCtrValue

u32 Xpm_DisableEvent
EventCntrId

u32 Xpm_SetUpAnEvent
u32 EventID

u32 Xpm_GetEventCounter
EventCntrId
u32 * CntVal

void Xpm_DisableEventCounters
void

void Xpm_EnableEventCounters
void

void Xpm_ResetEventCounters
void

void Xpm_SleepPerfCounter
u32 delay
u64 frequency

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 75
 Chapter 4: Arm Cortex-R5F Processor APIs

Functions
Xpm_SetEvents
This function configures the Cortex-R5F event counters controller, with the event codes, in a
configuration selected by the user and enables the counters.

Prototype

void Xpm_SetEvents(s32 PmcrCfg);

Parameters

The following table lists the Xpm_SetEvents function arguments.

Table 98: Xpm_SetEvents Arguments

Name Description
PmcrCfg Configuration value based on which the event counters are
configured.XPM_CNTRCFG* values defined in xpm_counter.h can be utilized for setting
configuration

Returns

None.

Xpm_GetEventCounters
This function disables the event counters and returns the counter values.

Prototype

void Xpm_GetEventCounters(u32 *PmCtrValue);

Parameters

The following table lists the Xpm_GetEventCounters function arguments.

Table 99: Xpm_GetEventCounters Arguments

Name Description
PmCtrValue Pointer to an array of type u32 PmCtrValue[6]. It is an output parameter which is used
to return the PM counter values.

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 76
 Chapter 4: Arm Cortex-R5F Processor APIs

Xpm_DisableEvent
Disables the requested event counter.

Prototype

u32 Xpm_DisableEvent(u32 EventHandlerId);

Parameters

The following table lists the Xpm_DisableEvent function arguments.

Table 100: Xpm_DisableEvent Arguments

Name Description
EventCntrId Event Counter ID. The counter ID is the same that was earlier returned through a call
to Xpm_SetUpAnEvent. Cortex-R5F supports only 3 counters. The valid values are 0, 1,
or 2.

Returns

• XST_SUCCESS if successful.
• XST_FAILURE if the passed Counter ID is invalid (i.e. greater than 2).

Xpm_SetUpAnEvent
Sets up one of the event counters to count events based on the Event ID passed.

For supported Event IDs please refer xpm_counter.h. Upon invoked, the API searches for an
available counter. After finding one, it sets up the counter to count events for the requested
event.

Prototype

u32 Xpm_SetUpAnEvent(u32 EventID);

Parameters

The following table lists the Xpm_SetUpAnEvent function arguments.

Table 101: Xpm_SetUpAnEvent Arguments

Name Description
EventID For valid values, please refer xpm_counter.h.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 77
 Chapter 4: Arm Cortex-R5F Processor APIs

Returns

• Counter Number if successful. For Cortex-R5F, valid return values are 0, 1, or 2.

• XPM_NO_COUNTERS_AVAILABLE (0xFF) if all counters are being used

Xpm_GetEventCounter
Reads the counter value for the requested counter ID.

This is used to read the number of events that has been counted for the requsted event ID. This
can only be called after a call to Xpm_SetUpAnEvent.

Prototype

u32 Xpm_GetEventCounter(u32 EventHandlerId, u32 *CntVal);

Parameters

The following table lists the Xpm_GetEventCounter function arguments.

Table 102: Xpm_GetEventCounter Arguments

Name Description
EventCntrId The counter ID is the same that was earlier returned through a call to
Xpm_SetUpAnEvent. Cortex-R5F supports only 3 counters. The valid values are 0, 1, or
2.
CntVal Pointer to a 32 bit unsigned int type. This is used to return the event counter value.

Returns

• XST_SUCCESS if successful.
• XST_FAILURE if the passed Counter ID is invalid (i.e. greater than 2).

Xpm_DisableEventCounters
This function disables the Cortex-R5F event counters.

Prototype

void Xpm_DisableEventCounters(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 78
 Chapter 4: Arm Cortex-R5F Processor APIs

Xpm_EnableEventCounters
This function enables the Cortex-R5F event counters.

Prototype

void Xpm_EnableEventCounters(void);

Returns

None.

Xpm_ResetEventCounters
This function resets the Cortex-R5F event counters.

Prototype

void Xpm_ResetEventCounters(void);

Returns

None.

Xpm_SleepPerfCounter
This is helper function used by sleep/usleep APIs to generate delay in sec/usec.

Prototype

void Xpm_SleepPerfCounter(u32 delay, u64 frequency);

Parameters

The following table lists the Xpm_SleepPerfCounter function arguments.

Table 103: Xpm_SleepPerfCounter Arguments

Name Description
delay - delay time in sec/usec
frequency - Number of countes in second/micro second

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 79
 Chapter 4: Arm Cortex-R5F Processor APIs

Arm Cortex-R5F Processor Specific Include

Files
The xpseudo_asm.h includes xreg_cortexr5.h and xpseudo_asm_gcc.h.

The xreg_cortexr5.h file contains definitions for inline assembler code. It provides inline
definitions for Cortex-R5F GPRs, SPRs,co-processor registers and Debug register

The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler
instructions, available as macros. These can be very useful for tasks such as setting or getting
special purpose registers, synchronization,or cache manipulation. These inline assembler
instructions can be used from drivers and user applications written in C.

Arm Cortex-R5F Peripheral Definitions

The xparameters_ps.h file contains the canonical definitions and constant declarations for
peripherals within hardblock, attached to the Arm Cortex-R5F core.

These definitions can be used by drivers or applications to access the peripherals.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 80
 Chapter 5: Arm Cortex-A9 Processor APIs

Chapter 5

Arm Cortex-A9 Processor APIs

Arm Cortex-A9 Processor API

Standalone BSP contains boot code, cache, exception handling, file and memory management,
configuration, time and processor-specific include functions.

It supports gcc compilers.

Arm Cortex-A9 Processor Boot Code

The boot code performs minimum configuration which is required for an application to run
starting from processor reset state of the processor. Below is a sequence illustrating what all
configuration is performed before control reaches to main function.

1. Program vector table base for exception handling

2. Invalidate instruction cache, data cache and TLBs
3. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system)
4. Configure MMU with short descriptor translation table format and program base address of
translation table
5. Enable data cache, instruction cache and MMU
6. Enable Floating point unit
7. Transfer control to _start which clears BSS sections, initializes global timer and runs global
constructor before jumping to main application

The translation_table.S contains a static page table required by MMU for cortex-A9. This
translation table is flat mapped (input address = output address) with default memory attributes
defined for Zynq-7000 architecture. It utilizes short descriptor translation table format with each
section defining 1 MB of memory.

The overview of translation table memory attributes is described below.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 81
 Chapter 5: Arm Cortex-A9 Processor APIs

Memory Range Definition in Translation Table

DDR 0x00000000 - 0x3FFFFFFF Normal write-back Cacheable
PL 0x40000000 - 0xBFFFFFFF Strongly Ordered
Reserved 0xC0000000 - 0xDFFFFFFF Unassigned
Memory mapped devices 0xE0000000 - 0xE02FFFFF Device Memory
Reserved 0xE0300000 - 0xE0FFFFFF Unassigned
NAND, NOR 0xE1000000 - 0xE3FFFFFF Device memory
SRAM 0xE4000000 - 0xE5FFFFFF Normal write-back Cacheable
Reserved 0xE6000000 - 0xF7FFFFFF Unassigned
AMBA APB Peripherals 0xF8000000 - 0xF8FFFFFF Device Memory
Reserved 0xF9000000 - 0xFBFFFFFF Unassigned
Linear QSPI - XIP 0xFC000000 - 0xFDFFFFFF Normal write-through cacheable
Reserved 0xFE000000 - 0xFFEFFFFF Unassigned
OCM 0xFFF00000 - 0xFFFFFFFF Normal inner write-back cacheable

Note: For region 0x00000000 - 0x3FFFFFFF, a system where DDR is less than 1 GB, region after DDR and
before PL is marked as undefined/reserved in translation table. In 0xF8000000 - 0xF8FFFFFF,
0xF8000C00 - 0xF8000FFF, 0xF8010000 - 0xF88FFFFF and 0xF8F03000 to 0xF8FFFFFF are reserved
but due to granual size of 1 MB, it is not possible to define separate regions for them. For region
0xFFF00000 - 0xFFFFFFFF, 0xFFF00000 to 0xFFFB0000 is reserved but due to 1MB granual size, it is not
possible to define separate region for it.

Arm Cortex-A9 Processor Cache Functions

Cache functions provide access to cache related operations such as flush and invalidate for
instruction and data caches.

It gives option to perform the cache operations on a single cacheline, a range of memory and an
entire cache.

Table 104: Quick Function Reference

Type Name Arguments

void Xil_DCacheEnable
void

void Xil_DCacheDisable
void

void Xil_DCacheInvalidate
void

void Xil_DCacheInvalidateRange
INTPTR adr
u32 len

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 82
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 104: Quick Function Reference (cont'd)

Type Name Arguments

void Xil_DCacheFlush
void

void Xil_DCacheFlushRange
INTPTR adr
u32 len

void Xil_ICacheEnable
void

void Xil_ICacheDisable
void

void Xil_ICacheInvalidate
void

void Xil_ICacheInvalidateRange
INTPTR adr
u32 len

void Xil_DCacheInvalidateLine
u32 adr

void Xil_DCacheFlushLine
u32 adr

void Xil_DCacheStoreLine
u32 adr

void Xil_ICacheInvalidateLine
u32 adr

void Xil_L1DCacheEnable
void

void Xil_L1DCacheDisable
void

void Xil_L1DCacheInvalidate
void

void Xil_L1DCacheInvalidateLine
u32 adr

void Xil_L1DCacheInvalidateRange
u32 adr
u32 len

void Xil_L1DCacheFlush
void

void Xil_L1DCacheFlushLine
u32 adr

void Xil_L1DCacheFlushRange
u32 adr
u32 len

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 83
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 104: Quick Function Reference (cont'd)

Type Name Arguments

void Xil_L1DCacheStoreLine
u32 adr

void Xil_L1ICacheEnable
void

void Xil_L1ICacheDisable
void

void Xil_L1ICacheInvalidate
void

void Xil_L1ICacheInvalidateLine
u32 adr

void Xil_L1ICacheInvalidateRange
u32 adr
u32 len

void Xil_L2CacheEnable
void

void Xil_L2CacheDisable
void

void Xil_L2CacheInvalidate
void

void Xil_L2CacheInvalidateLine
u32 adr

void Xil_L2CacheInvalidateRange
u32 adr
u32 len

void Xil_L2CacheFlush
void

void Xil_L2CacheFlushLine
u32 adr

void Xil_L2CacheFlushRange
u32 adr
u32 len

void Xil_L2CacheStoreLine
u32 adr

Functions
Xil_DCacheEnable
Enable the Data cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 84
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_DCacheEnable(void);

Returns

None.

Xil_DCacheDisable
Disable the Data cache.

Prototype

void Xil_DCacheDisable(void);

Returns

None.

Xil_DCacheInvalidate
Invalidate the entire Data cache.

Prototype

void Xil_DCacheInvalidate(void);

Returns

None.

Xil_DCacheInvalidateRange
Invalidate the Data cache for the given address range.

If the bytes specified by the address range are cached by the Data cache, the cachelines
containing those bytes are invalidated. If the cachelines are modified (dirty), the modified
contents are lost and NOT written to the system memory before the lines are invalidated.

In this function, if start address or end address is not aligned to cache-line, particular cache-line
containing unaligned start or end address is flush first and then invalidated the others as
invalidating the same unaligned cache line may result into loss of data. This issue raises few
possibilities.

If the address to be invalidated is not cache-line aligned, the following choices are available:

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 85
 Chapter 5: Arm Cortex-A9 Processor APIs

1. Invalidate the cache line when required and do not bother much for the side effects. Though
it sounds good, it can result in hard-to-debug issues. The problem is, if some other variable
are allocated in the same cache line and had been recently updated (in cache), the
invalidation would result in loss of data.
2. Flush the cache line first. This will ensure that if any other variable present in the same cache
line and updated recently are flushed out to memory. Then it can safely be invalidated. Again
it sounds good, but this can result in issues. For example, when the invalidation happens in a
typical ISR (after a DMA transfer has updated the memory), then flushing the cache line
means, losing data that were updated recently before the ISR got invoked.

Linux prefers the second one. To have uniform implementation (across standalone and Linux), the
second option is implemented. This being the case, following needs to be taken care of:

1. Whenever possible, the addresses must be cache line aligned. Please nore that, not just start
address, even the end address must be cache line aligned. If that is taken care of, this will
always work.
2. Avoid situations where invalidation has to be done after the data is updated by
peripheral/DMA directly into the memory. It is not tough to achieve (may be a bit risky). The
common use case to do invalidation is when a DMA happens. Generally for such use cases,
buffers can be allocated first and then start the DMA. The practice that needs to be followed
here is, immediately after buffer allocation and before starting the DMA, do the invalidation.
With this approach, invalidation need not to be done after the DMA transfer is over.

This is going to always work if done carefully. However, the concern is, there is no guarantee that
invalidate has not needed to be done after DMA is complete. For example, because of some
reasons if the first cache line or last cache line (assuming the buffer in question comprises of
multiple cache lines) are brought into cache (between the time it is invalidated and DMA
completes) because of some speculative prefetching or reading data for a variable present in the
same cache line, then we will have to invalidate the cache after DMA is complete.

Prototype

void Xil_DCacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheInvalidateRange function arguments.

Table 105: Xil_DCacheInvalidateRange Arguments

Name Description
adr 32-bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 86
 Chapter 5: Arm Cortex-A9 Processor APIs

Returns

None.

Xil_DCacheFlush
Flush the entire Data cache.

Prototype

void Xil_DCacheFlush(void);

Returns

None.

Xil_DCacheFlushRange
Flush the Data cache for the given address range.

If the bytes specified by the address range are cached by the data cache, the cachelines
containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to
the system memory before the lines are invalidated.

Prototype

void Xil_DCacheFlushRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheFlushRange function arguments.

Table 106: Xil_DCacheFlushRange Arguments

Name Description
adr 32bit start address of the range to be flushed.
len Length of the range to be flushed in bytes.

Returns

None.

Xil_ICacheEnable
Enable the instruction cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 87
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_ICacheEnable(void);

Returns

None.

Xil_ICacheDisable
Disable the instruction cache.

Prototype

void Xil_ICacheDisable(void);

Returns

None.

Xil_ICacheInvalidate
Invalidate the entire instruction cache.

Prototype

void Xil_ICacheInvalidate(void);

Returns

None.

Xil_ICacheInvalidateRange
Invalidate the instruction cache for the given address range.

If the instructions specified by the address range are cached by the instrunction cache, the
cachelines containing those instructions are invalidated.

Prototype

void Xil_ICacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_ICacheInvalidateRange function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 88
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 107: Xil_ICacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_DCacheInvalidateLine
Invalidate a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to the system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_DCacheInvalidateLine function arguments.

Table 108: Xil_DCacheInvalidateLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_DCacheFlushLine
Flush a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline
are written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 89
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_DCacheFlushLine(u32 adr);

Parameters

The following table lists the Xil_DCacheFlushLine function arguments.

Table 109: Xil_DCacheFlushLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_DCacheStoreLine
Store a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache and the cacheline is
modified (dirty), the entire contents of the cacheline are written to system memory. After the
store completes, the cacheline is marked as unmodified (not dirty).

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheStoreLine(u32 adr);

Parameters

The following table lists the Xil_DCacheStoreLine function arguments.

Table 110: Xil_DCacheStoreLine Arguments

Name Description
adr 32bit address of the data to be stored.

Returns

None.

Xil_ICacheInvalidateLine
Invalidate an instruction cache line.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 90
 Chapter 5: Arm Cortex-A9 Processor APIs

If the instruction specified by the address is cached by the instruction cache, the cacheline
containing that instruction is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_ICacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_ICacheInvalidateLine function arguments.

Table 111: Xil_ICacheInvalidateLine Arguments

Name Description
adr 32bit address of the instruction to be invalidated.

Returns

None.

Xil_L1DCacheEnable
Enable the level 1 Data cache.

Prototype

void Xil_L1DCacheEnable(void);

Returns

None.

Xil_L1DCacheDisable
Disable the level 1 Data cache.

Prototype

void Xil_L1DCacheDisable(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 91
 Chapter 5: Arm Cortex-A9 Processor APIs

Xil_L1DCacheInvalidate
Invalidate the level 1 Data cache.

Note: In Cortex A9, there is no cp instruction for invalidating the whole D-cache. This function invalidates
each line by set/way.

Prototype

void Xil_L1DCacheInvalidate(void);

Returns

None.

Xil_L1DCacheInvalidateLine
Invalidate a level 1 Data cache line.

If the byte specified by the address (Addr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Note: The bottom 5 bits are set to 0, forced by architecture.

Prototype

void Xil_L1DCacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_L1DCacheInvalidateLine function arguments.

Table 112: Xil_L1DCacheInvalidateLine Arguments

Name Description
adr 32bit address of the data to be invalidated.

Returns

None.

Xil_L1DCacheInvalidateRange
Invalidate the level 1 Data cache for the given address range.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 92
 Chapter 5: Arm Cortex-A9 Processor APIs

If the bytes specified by the address range are cached by the Data cache, the cachelines
containing those bytes are invalidated. If the cachelines are modified (dirty), the modified
contents are lost and NOT written to the system memory before the lines are invalidated.

Prototype

void Xil_L1DCacheInvalidateRange(u32 adr, u32 len);

Parameters

The following table lists the Xil_L1DCacheInvalidateRange function arguments.

Table 113: Xil_L1DCacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_L1DCacheFlush
Flush the level 1 Data cache.

Note: In Cortex A9, there is no cp instruction for flushing the whole D-cache. Need to flush each line.

Prototype

void Xil_L1DCacheFlush(void);

Returns

None.

Xil_L1DCacheFlushLine
Flush a level 1 Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline
are written to system memory before the line is invalidated.

Note: The bottom 5 bits are set to 0, forced by architecture.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 93
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_L1DCacheFlushLine(u32 adr);

Parameters

The following table lists the Xil_L1DCacheFlushLine function arguments.

Table 114: Xil_L1DCacheFlushLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_L1DCacheFlushRange
Flush the level 1 Data cache for the given address range.

If the bytes specified by the address range are cached by the Data cache, the cacheline
containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to
system memory before the lines are invalidated.

Prototype

void Xil_L1DCacheFlushRange(u32 adr, u32 len);

Parameters

The following table lists the Xil_L1DCacheFlushRange function arguments.

Table 115: Xil_L1DCacheFlushRange Arguments

Name Description
adr 32bit start address of the range to be flushed.
len Length of the range to be flushed in bytes.

Returns

None.

Xil_L1DCacheStoreLine
Store a level 1 Data cache line.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 94
 Chapter 5: Arm Cortex-A9 Processor APIs

If the byte specified by the address (adr) is cached by the Data cache and the cacheline is
modified (dirty), the entire contents of the cacheline are written to system memory. After the
store completes, the cacheline is marked as unmodified (not dirty).

Note: The bottom 5 bits are set to 0, forced by architecture.

Prototype

void Xil_L1DCacheStoreLine(u32 adr);

Parameters

The following table lists the Xil_L1DCacheStoreLine function arguments.

Table 116: Xil_L1DCacheStoreLine Arguments

Name Description
adr Address to be stored.

Returns

None.

Xil_L1ICacheEnable
Enable the level 1 instruction cache.

Prototype

void Xil_L1ICacheEnable(void);

Returns

None.

Xil_L1ICacheDisable
Disable level 1 the instruction cache.

Prototype

void Xil_L1ICacheDisable(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 95
 Chapter 5: Arm Cortex-A9 Processor APIs

Xil_L1ICacheInvalidate
Invalidate the entire level 1 instruction cache.

Prototype

void Xil_L1ICacheInvalidate(void);

Returns

None.

Xil_L1ICacheInvalidateLine
Invalidate a level 1 instruction cache line.

If the instruction specified by the address is cached by the instruction cache, the cacheline
containing that instruction is invalidated.

Note: The bottom 5 bits are set to 0, forced by architecture.

Prototype

void Xil_L1ICacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_L1ICacheInvalidateLine function arguments.

Table 117: Xil_L1ICacheInvalidateLine Arguments

Name Description
adr 32bit address of the instruction to be invalidated.

Returns

None.

Xil_L1ICacheInvalidateRange
Invalidate the level 1 instruction cache for the given address range.

If the instrucions specified by the address range are cached by the instruction cache, the
cacheline containing those bytes are invalidated.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 96
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_L1ICacheInvalidateRange(u32 adr, u32 len);

Parameters

The following table lists the Xil_L1ICacheInvalidateRange function arguments.

Table 118: Xil_L1ICacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_L2CacheEnable
Enable the L2 cache.

Prototype

void Xil_L2CacheEnable(void);

Returns

None.

Xil_L2CacheDisable
Disable the L2 cache.

Prototype

void Xil_L2CacheDisable(void);

Returns

None.

Xil_L2CacheInvalidate
Invalidate the entire level 2 cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 97
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_L2CacheInvalidate(void);

Returns

None.

Xil_L2CacheInvalidateLine
Invalidate a level 2 cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the modified contents are lost and are
NOT written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_L2CacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_L2CacheInvalidateLine function arguments.

Table 119: Xil_L2CacheInvalidateLine Arguments

Name Description
adr 32bit address of the data/instruction to be invalidated.

Returns

None.

Xil_L2CacheInvalidateRange
Invalidate the level 2 cache for the given address range.

If the bytes specified by the address range are cached by the L2 cache, the cacheline containing
those bytes are invalidated. If the cachelines are modified (dirty), the modified contents are lost
and are NOT written to system memory before the lines are invalidated.

Prototype

void Xil_L2CacheInvalidateRange(u32 adr, u32 len);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 98
 Chapter 5: Arm Cortex-A9 Processor APIs

Parameters

The following table lists the Xil_L2CacheInvalidateRange function arguments.

Table 120: Xil_L2CacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_L2CacheFlush
Flush the entire level 2 cache.

Prototype

void Xil_L2CacheFlush(void);

Returns

None.

Xil_L2CacheFlushLine
Flush a level 2 cache line.

If the byte specified by the address (adr) is cached by the L2 cache, the cacheline containing that
byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline are
written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_L2CacheFlushLine(u32 adr);

Parameters

The following table lists the Xil_L2CacheFlushLine function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 99
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 121: Xil_L2CacheFlushLine Arguments

Name Description
adr 32bit address of the data/instruction to be flushed.

Returns

None.

Xil_L2CacheFlushRange
Flush the level 2 cache for the given address range.

If the bytes specified by the address range are cached by the L2 cache, the cacheline containing
those bytes are invalidated. If the cachelines are modified (dirty), they are written to the system
memory before the lines are invalidated.

Prototype

void Xil_L2CacheFlushRange(u32 adr, u32 len);

Parameters

The following table lists the Xil_L2CacheFlushRange function arguments.

Table 122: Xil_L2CacheFlushRange Arguments

Name Description
adr 32bit start address of the range to be flushed.
len Length of the range to be flushed in bytes.

Returns

None.

Xil_L2CacheStoreLine
Store a level 2 cache line.

If the byte specified by the address (adr) is cached by the L2 cache and the cacheline is modified
(dirty), the entire contents of the cacheline are written to system memory. After the store
completes, the cacheline is marked as unmodified (not dirty).

Note: The bottom 4 bits are set to 0, forced by architecture.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 100
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void Xil_L2CacheStoreLine(u32 adr);

Parameters

The following table lists the Xil_L2CacheStoreLine function arguments.

Table 123: Xil_L2CacheStoreLine Arguments

Name Description
adr 32bit address of the data/instruction to be stored.

Returns

None.

Arm Cortex-A9 Processor MMU Functions

MMU functions equip users to enable MMU, disable MMU and modify default memory
attributes of MMU table as per the need.

Table 124: Quick Function Reference

Type Name Arguments

void Xil_SetTlbAttributes
INTPTR Addr
u32 attrib

void Xil_EnableMMU
void

void Xil_DisableMMU
void

void * Xil_MemMap
UINTPTR PhysAddr
size_t size
u32 flags

Functions
Xil_SetTlbAttributes
This function sets the memory attributes for a section covering 1MB of memory in the
translation table.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 101
 Chapter 5: Arm Cortex-A9 Processor APIs

Note: The MMU or D-cache does not need to be disabled before changing a translation table entry.

Prototype

void Xil_SetTlbAttributes(INTPTR Addr, u32 attrib);

Parameters

The following table lists the Xil_SetTlbAttributes function arguments.

Table 125: Xil_SetTlbAttributes Arguments

Name Description
Addr 32-bit address for which memory attributes need to be set.
attrib Attribute for the given memory region. xil_mmu.h contains definitions of commonly
used memory attributes which can be utilized for this function.

Returns

None.

Xil_EnableMMU
Enable MMU for cortex A9 processor.

This function invalidates the instruction and data caches, and then enables MMU.

Prototype

void Xil_EnableMMU(void);

Returns

None.

Xil_DisableMMU
Disable MMU for Cortex A9 processors.

This function invalidates the TLBs, Branch Predictor Array and flushed the D Caches before
disabling the MMU.

Note: When the MMU is disabled, all the memory accesses are treated as strongly ordered.

Prototype

void Xil_DisableMMU(void);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 102
 Chapter 5: Arm Cortex-A9 Processor APIs

Returns

None.

Xil_MemMap
Memory mapping for Cortex A9 processor.

Note: : Previously this was implemented in libmetal. Move to embeddedsw as this functionality is specific
to A9 processor.

Prototype

void * Xil_MemMap(UINTPTR PhysAddr, size_t size, u32 flags);

Parameters

The following table lists the Xil_MemMap function arguments.

Table 126: Xil_MemMap Arguments

Name Description
PhysAddr is physical address.
size is size of region.
flags is flags used to set translation table.

Returns

Pointer to virtual address.

Arm Cortex-A9 Time Functions

xtime_l.h provides access to the 64-bit Global Counter in the PMU.

This counter increases by one at every two processor cycles. These functions can be used to
get/set time in the global timer.

Table 127: Quick Function Reference

Type Name Arguments

void XTime_SetTime
XTime Xtime_Global

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 103
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 127: Quick Function Reference (cont'd)

Type Name Arguments

void XTime_GetTime
XTime * Xtime_Global

Functions
XTime_SetTime
Set the time in the Global Timer Counter Register.

Note: When this function is called by any one processor in a multi- processor environment, reference time
will reset/lost for all processors.

Prototype

void XTime_SetTime(XTime Xtime_Global);

Parameters

The following table lists the XTime_SetTime function arguments.

Table 128: XTime_SetTime Arguments

Name Description
Xtime_Global 64-bit Value to be written to the Global Timer Counter Register.

Returns

None.

XTime_GetTime
Get the time from the Global Timer Counter Register.

Note: None.

Prototype

void XTime_GetTime(XTime *Xtime_Global);

Parameters

The following table lists the XTime_GetTime function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 104
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 129: XTime_GetTime Arguments

Name Description
Xtime_Global Pointer to the 64-bit location which will be updated with the current timer value.

Returns

None.

Arm Cortex-A9 Event Counter Function

Cortex A9 event counter functions can be utilized to configure and control the Cortex-A9
performance monitor events.

Cortex-A9 performance monitor has six event counters which can be used to count a variety of
events described in Coretx-A9 TRM. xpm_counter.h defines configurations XPM_CNTRCFGx
which can be used to program the event counters to count a set of events.

Note: It doesn't handle the Cortex-A9 cycle counter, as the cycle counter is being used for time keeping.

Table 130: Quick Function Reference

Type Name Arguments

void Xpm_SetEvents
s32 PmcrCfg

void Xpm_GetEventCounters
u32 * PmCtrValue

Functions
Xpm_SetEvents
This function configures the Cortex A9 event counters controller, with the event codes, in a
configuration selected by the user and enables the counters.

Prototype

void Xpm_SetEvents(s32 PmcrCfg);

Parameters

The following table lists the Xpm_SetEvents function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 105
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 131: Xpm_SetEvents Arguments

Name Description
PmcrCfg Configuration value based on which the event counters are configured.
XPM_CNTRCFG* values defined in xpm_counter.h can be utilized for setting
configuration.

Returns

None.

Xpm_GetEventCounters
This function disables the event counters and returns the counter values.

Prototype

void Xpm_GetEventCounters(u32 *PmCtrValue);

Parameters

The following table lists the Xpm_GetEventCounters function arguments.

Table 132: Xpm_GetEventCounters Arguments

Name Description
PmCtrValue Pointer to an array of type u32 PmCtrValue[6]. It is an output parameter which is used
to return the PM counter values.

Returns

None.

PL310 L2 Event Counters Functions

xl2cc_counter.h contains APIs for configuring and controlling the event counters in PL310 L2
cache controller.

PL310 has two event counters which can be used to count variety of events like DRHIT, DRREQ,
DWHIT, DWREQ, etc. xl2cc_counter.h contains definitions for different configurations which can
be used for the event counters to count a set of events.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 106
 Chapter 5: Arm Cortex-A9 Processor APIs

Table 133: Quick Function Reference

Type Name Arguments

void XL2cc_EventCtrInit
s32 Event0
s32 Event1

void XL2cc_EventCtrStart
void

void XL2cc_EventCtrStop
u32 * EveCtr0
u32 * EveCtr1

Functions
XL2cc_EventCtrInit
This function initializes the event counters in L2 Cache controller with a set of event codes
specified by the user.

Note: The definitions for event codes XL2CC_* can be found in xl2cc_counter.h.

Prototype

void XL2cc_EventCtrInit(s32 Event0, s32 Event1);

Parameters

The following table lists the XL2cc_EventCtrInit function arguments.

Table 134: XL2cc_EventCtrInit Arguments

Name Description
Event0 Event code for counter 0.
Event1 Event code for counter 1.

Returns

None.

XL2cc_EventCtrStart
This function starts the event counters in L2 Cache controller.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 107
 Chapter 5: Arm Cortex-A9 Processor APIs

Prototype

void XL2cc_EventCtrStart(void);

Returns

None.

XL2cc_EventCtrStop
This function disables the event counters in L2 Cache controller, saves the counter values and
resets the counters.

Prototype

void XL2cc_EventCtrStop(u32 *EveCtr0, u32 *EveCtr1);

Parameters

The following table lists the XL2cc_EventCtrStop function arguments.

Table 135: XL2cc_EventCtrStop Arguments

Name Description
EveCtr0 Output parameter which is used to return the value in event counter 0.
EveCtr1 Output parameter which is used to return the value in event counter 1.

Returns

None.

Arm Cortex-A9 Processor and pl310 Errata

Support
Various ARM errata are handled in the standalone BSP.

The implementation for errata handling follows ARM guidelines and is based on the open source
Linux support for these errata.

Note: The errata handling is enabled by default. To disable handling of all the errata globally, un-define the
macro ENABLE_ARM_ERRATA in xil_errata.h. To disable errata on a per-erratum basis, un-define relevant
macros in xil_errata.h.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 108
 Chapter 5: Arm Cortex-A9 Processor APIs

Definitions
Define CONFIG_ARM_ERRATA_742230

Definition

#define CONFIG_ARM_ERRATA_7422301

Description

Errata No: 742230 Description: DMB operation may be faulty.

Define CONFIG_ARM_ERRATA_743622

Definition

#define CONFIG_ARM_ERRATA_7436221

Description

Errata No: 743622 Description: Faulty hazard checking in the Store Buffer may lead to data
corruption.

Define CONFIG_ARM_ERRATA_775420

Definition

#define CONFIG_ARM_ERRATA_7754201

Description

Errata No: 775420 Description: A data cache maintenance operation which aborts, might lead to
deadlock.

Define CONFIG_ARM_ERRATA_794073

Definition

#define CONFIG_ARM_ERRATA_7940731

Description

Errata No: 794073 Description: Speculative instruction fetches with MMU disabled might not
comply with architectural requirements.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 109
 Chapter 5: Arm Cortex-A9 Processor APIs

Define CONFIG_PL310_ERRATA_588369

Definition

#define CONFIG_PL310_ERRATA_5883691

Description

PL310 L2 Cache Errata.

Errata No: 588369 Description: Clean & Invalidate maintenance operations do not invalidate
clean lines

Define CONFIG_PL310_ERRATA_727915

Definition

#define CONFIG_PL310_ERRATA_7279151

Description

Errata No: 727915 Description: Background Clean and Invalidate by Way operation can cause
data corruption.

Arm Cortex-A9 Processor Specific Include Files

The xpseudo_asm.h includes xreg_cortexa9.h and xpseudo_asm_gcc.h.

The xreg_cortexa9.h file contains definitions for inline assembler code. It provides inline
definitions for Cortex A9 GPRs, SPRs, MPE registers, co-processor registers and Debug registers.

The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler
instructions, available as macros. These can be very useful for tasks such as setting or getting
special purpose registers, synchronization, or cache manipulation etc. These inline assembler
instructions can be used from drivers and user applications written in C.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 110
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Chapter 6

Arm Cortex-A53 32-bit Processor

APIs

Arm Cortex-A53 32-bit Processor API

Cortex-A53 standalone BSP contains two separate BSPs for 32-bit mode and 64-bit mode.

The 32-bit mode of cortex-A53 is compatible with Armv7-A architecture.

Arm Cortex-A53 32-bit Processor Boot Code

The boot.S file contains a minimal set of code for transferring control from the processor reset
location to the start of the application. The boot code performs minimum configuration which is
required for an application to run starting from processor reset state of the processor. Below is a
sequence illustrating what all configuration is performed before control reaches to main function.

1. Program vector table base for exception handling

2. Invalidate instruction cache, data cache and TLBs
3. Program stack pointer for various modes (IRQ, FIQ, supervisor, undefine, abort, system)
4. Program counter frequency
5. Configure MMU with short descriptor translation table format and program base address of
translation table
6. Enable data cache, instruction cache and MMU
7. Transfer control to _start which clears BSS sections and runs global constructor before
jumping to main application

The translation_table.S contains a static page table required by MMU for cortex-A53. This
translation table is flat mapped (input address = output address) with default memory attributes
defined for Zynq Ultrascale+ architecture. It utilizes short descriptor translation table format with
each section defining 1 MB of memory.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 111
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

The overview of translation table memory attributes is described below.

Memory Range Definition in Translation Table

DDR 0x00000000 - 0x7FFFFFFF Normal write-back Cacheable
PL 0x80000000 - 0xBFFFFFFF Strongly Ordered
QSPI, lower PCIe 0xC0000000 - 0xEFFFFFFF Device Memory
Reserved 0xF0000000 - 0xF7FFFFFF Unassigned
STM Coresight 0xF8000000 - 0xF8FFFFFF Device Memory
GIC 0xF9000000 - 0xF90FFFFF Device memory
Reserved 0xF9100000 - 0xFCFFFFFF Unassigned
FPS, LPS slaves 0xFD000000 - 0xFFBFFFFF Device memory
CSU, PMU 0xFFC00000 - 0xFFDFFFFF Device Memory
TCM, OCM 0xFFE00000 - 0xFFFFFFFF Normal write-back cacheable

Note: For DDR in region 0x00000000 - 0x7FFFFFFF, a system where DDR is less than 2 GB, region after
DDR and before PL is marked as undefined/reserved in translation table. In region 0xFFC00000 -
0xFFDFFFFF, it contains CSU and PMU memory which are marked as Device since it is less than 1 MB and
falls in a region with device memory.

Arm Cortex-A53 32-bit Processor Cache

Functions
Cache functions provide access to cache related operations such as flush and invalidate for
instruction and data caches.

It gives option to perform the cache operations on a single cacheline, a range of memory and an
entire cache.

Table 136: Quick Function Reference

Type Name Arguments

void Xil_DCacheEnable
void

void Xil_DCacheDisable
void

void Xil_DCacheInvalidate
void

void Xil_DCacheInvalidateRange
INTPTR adr
u32 len

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 112
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Table 136: Quick Function Reference (cont'd)

Type Name Arguments

void Xil_DCacheFlush
void

void Xil_DCacheFlushRange
INTPTR adr
u32 len

void Xil_DCacheInvalidateLine
u32 adr

void Xil_DCacheFlushLine
u32 adr

void Xil_ICacheInvalidateLine
u32 adr

void Xil_ICacheEnable
void

void Xil_ICacheDisable
void

void Xil_ICacheInvalidate
void

void Xil_ICacheInvalidateRange
INTPTR adr
u32 len

Functions
Xil_DCacheEnable
Enable the Data cache.

Prototype

void Xil_DCacheEnable(void);

Returns

None.

Xil_DCacheDisable
Disable the Data cache.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 113
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Prototype

void Xil_DCacheDisable(void);

Returns

None.

Xil_DCacheInvalidate
Invalidate the Data cache.

The contents present in the data cache are cleaned and invalidated.

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate to avoid such corruption.

Prototype

void Xil_DCacheInvalidate(void);

Returns

None.

Xil_DCacheInvalidateRange
Invalidate the Data cache for the given address range.

The cachelines present in the adderss range are cleaned and invalidated

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate to avoid such corruption.

Prototype

void Xil_DCacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheInvalidateRange function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 114
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Table 137: Xil_DCacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_DCacheFlush
Flush the Data cache.

Prototype

void Xil_DCacheFlush(void);

Returns

None.

Xil_DCacheFlushRange
Flush the Data cache for the given address range.

If the bytes specified by the address range are cached by the Data cache, the cachelines
containing those bytes are invalidated. If the cachelines are modified (dirty), they are written to
system memory before the lines are invalidated.

Prototype

void Xil_DCacheFlushRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_DCacheFlushRange function arguments.

Table 138: Xil_DCacheFlushRange Arguments

Name Description
adr 32bit start address of the range to be flushed.
len Length of range to be flushed in bytes.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 115
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Returns

None.

Xil_DCacheInvalidateLine
Invalidate a Data cache line.

The cacheline is cleaned and invalidated.

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate to avoid such corruption.

Prototype

void Xil_DCacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_DCacheInvalidateLine function arguments.

Table 139: Xil_DCacheInvalidateLine Arguments

Name Description
adr 32 bit address of the data to be invalidated.

Returns

None.

Xil_DCacheFlushLine
Flush a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline
are written to system memory before the line is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheFlushLine(u32 adr);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 116
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Parameters

The following table lists the Xil_DCacheFlushLine function arguments.

Table 140: Xil_DCacheFlushLine Arguments

Name Description
adr 32bit address of the data to be flushed.

Returns

None.

Xil_ICacheInvalidateLine
Invalidate an instruction cache line.

If the instruction specified by the address is cached by the instruction cache, the cachecline
containing that instruction is invalidated.

Note: The bottom 4 bits are set to 0, forced by architecture.

Prototype

void Xil_ICacheInvalidateLine(u32 adr);

Parameters

The following table lists the Xil_ICacheInvalidateLine function arguments.

Table 141: Xil_ICacheInvalidateLine Arguments

Name Description
adr 32bit address of the instruction to be invalidated..

Returns

None.

Xil_ICacheEnable
Enable the instruction cache.

Prototype

void Xil_ICacheEnable(void);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 117
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Returns

None.

Xil_ICacheDisable
Disable the instruction cache.

Prototype

void Xil_ICacheDisable(void);

Returns

None.

Xil_ICacheInvalidate
Invalidate the entire instruction cache.

Prototype

void Xil_ICacheInvalidate(void);

Returns

None.

Xil_ICacheInvalidateRange
Invalidate the instruction cache for the given address range.

If the instructions specified by the address range are cached by the instrunction cache, the
cachelines containing those instructions are invalidated.

Prototype

void Xil_ICacheInvalidateRange(INTPTR adr, u32 len);

Parameters

The following table lists the Xil_ICacheInvalidateRange function arguments.

Table 142: Xil_ICacheInvalidateRange Arguments

Name Description
adr 32bit start address of the range to be invalidated.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 118
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Table 142: Xil_ICacheInvalidateRange Arguments (cont'd)

Name Description
len Length of the range to be invalidated in bytes.

Returns

None.

Arm Cortex-A53 32-bit Processor MMU

Handling
MMU functions equip users to enable MMU, disable MMU and modify default memory
attributes of MMU table as per the need.

None.

Note:

Table 143: Quick Function Reference

Type Name Arguments

void Xil_SetTlbAttributes
UINTPTR Addr
u32 attrib

void Xil_EnableMMU
void

void Xil_DisableMMU
void

Functions
Xil_SetTlbAttributes
This function sets the memory attributes for a section covering 1MB of memory in the
translation table.

Note: The MMU or D-cache does not need to be disabled before changing a translation table entry.

Prototype

void Xil_SetTlbAttributes(UINTPTR Addr, u32 attrib);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 119
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Parameters

The following table lists the Xil_SetTlbAttributes function arguments.

Table 144: Xil_SetTlbAttributes Arguments

Name Description
Addr 32-bit address for which the attributes need to be set.
attrib Attributes for the specified memory region. xil_mmu.h contains commonly used
memory attributes definitions which can be utilized for this function.

Returns

None.

Xil_EnableMMU
Enable MMU for Cortex-A53 processor in 32bit mode.

This function invalidates the instruction and data caches before enabling MMU.

Prototype

void Xil_EnableMMU(void);

Returns

None.

Xil_DisableMMU
Disable MMU for Cortex A53 processors in 32bit mode.

This function invalidates the TLBs, Branch Predictor Array and flushed the data cache before
disabling the MMU.

Note: When the MMU is disabled, all the memory accesses are treated as strongly ordered.

Prototype

void Xil_DisableMMU(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 120
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Arm Cortex-A53 32-bit Mode Time Functions

xtime_l.h provides access to the 64-bit physical timer counter.

Table 145: Quick Function Reference

Type Name Arguments

void XTime_SetTime
XTime Xtime_Global

void XTime_GetTime
XTime * Xtime_Global

Functions
XTime_SetTime
Timer of A53 runs continuously and the time can not be set as desired.

This API doesn't contain anything. It is defined to have uniformity across platforms.

Prototype

void XTime_SetTime(XTime Xtime_Global);

Parameters

The following table lists the XTime_SetTime function arguments.

Table 146: XTime_SetTime Arguments

Name Description
Xtime_Global 64bit Value to be written to the Global Timer Counter Register. But since the function
does not contain anything, the value is not used for anything.

Returns

None.

XTime_GetTime
Get the time from the physical timer counter register.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 121
 Chapter 6: Arm Cortex-A53 32-bit Processor APIs

Prototype

void XTime_GetTime(XTime *Xtime_Global);

Parameters

The following table lists the XTime_GetTime function arguments.

Table 147: XTime_GetTime Arguments

Name Description
Xtime_Global Pointer to the 64-bit location to be updated with the current value in physical timer
counter.

Returns

None.

Arm Cortex-A53 32-bit Processor Specific

Include Files
The xpseudo_asm.h includes xreg_cortexa53.h and xpseudo_asm_gcc.h.

The xreg_cortexa53.h file contains definitions for inline assembler code. It provides inline
definitions for Cortex A53 GPRs, SPRs, co-processor registers and floating point registers.

The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler
instructions, available as macros. These can be very useful for tasks such as setting or getting
special purpose registers, synchronization, or cache manipulation etc. These inline assembler
instructions can be used from drivers and user applications written in C.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 122
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Chapter 7

Arm Cortex-A53 64-bit Processor

APIs

Arm Cortex-A53 64-bit Processor API

Cortex-A53 standalone BSP contains two separate BSPs for 32-bit mode and 64-bit mode.

The 64-bit mode of cortex-A53 contains Armv8-A architecture. This section provides a linked
summary and detailed descriptions of the Arm Cortex-A53 64-bit Processor APIs.

Note: These APIs are applicable for the Cortex-A72 processor as well.

Arm Cortex-A53 64-bit Processor Boot Code

The boot code performs minimum configuration which is required for an application. Cortex-A53
starts by checking current exception level. If the current exception level is EL3 and BSP is built
for EL3, it will do initialization required for application execution at EL3. Below is a sequence
illustrating what all configuration is performed before control reaches to main function for EL3
execution.

1. Program vector table base for exception handling

2. Set reset vector table base address
3. Program stack pointer for EL3
4. Routing of interrupts to EL3
5. Enable ECC protection
6. Program generic counter frequency
7. Invalidate instruction cache, data cache and TLBs
8. Configure MMU registers and program base address of translation table
9. Transfer control to _start which clears BSS sections and runs global constructor before
jumping to main application

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 123
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

If the current exception level is EL1 and BSP is also built for EL1_NONSECURE it will perform
initialization required for application execution at EL1 non-secure. For all other combination, the
execution will go into infinite loop. Below is a sequence illustrating what all configuration is
performed before control reaches to main function for EL1 execution.

1. Program vector table base for exception handling

2. Program stack pointer for EL1
3. Invalidate instruction cache, data cache and TLBs
4. Configure MMU registers and program base address of translation table
5. Transfer control to _start which clears BSS sections and runs global constructor before
jumping to main application

The translation_table.S contains a static page table required by MMU for cortex-A53. This
translation table is flat mapped (input address = output address) with default memory attributes
defined for zynq ultrascale+ architecture. It utilizes translation granual size of 4 KB with 2 MB
section size for initial 4 GB memory and 1 GB section size for memory after 4 GB. The overview
of translation table memory attributes is described below.

Memory Range Definition in Translation Table

DDR 0x0000000000 - 0x007FFFFFFF Normal write-back Cacheable
PL 0x0080000000 - 0x00BFFFFFFF Strongly Ordered
QSPI, lower PCIe 0x00C0000000 - 0x00EFFFFFFF Strongly Ordere
Reserved 0x00F0000000 - 0x00F7FFFFFF Unassigned
STM Coresight 0x00F8000000 - 0x00F8FFFFFF Strongly Ordered
GIC 0x00F9000000 - 0x00F91FFFFF Strongly Ordered
Reserved 0x00F9200000 - 0x00FCFFFFFF Unassigned
FPS, LPS slaves 0x00FD000000 - 0x00FFBFFFFF Strongly Ordered
CSU, PMU 0x00FFC00000 - 0x00FFDFFFFF Strongly Ordered
TCM, OCM 0x00FFE00000 - 0x00FFFFFFFF Normal inner write-back cacheable
Reserved 0x0100000000 - 0x03FFFFFFFF Unassigned
PL, PCIe 0x0400000000 - 0x07FFFFFFFF Strongly Ordered
DDR 0x0800000000 - 0x0FFFFFFFFF Normal inner write-back cacheable
PL, PCIe 0x1000000000 - 0xBFFFFFFFFF Strongly Ordered
Reserved 0xC000000000 - 0xFFFFFFFFFF Unassigned

Note: For DDR region 0x0000000000 - 0x007FFFFFFF, a system where DDR is less than 2 GB, region
after DDR and before PL is marked as undefined/reserved in translation table. Region 0xF9100000 -
0xF91FFFFF is reserved memory in 0x00F9000000 - 0x00F91FFFFF range, but it is marked as strongly
ordered because minimum section size in translation table section is 2 MB. Region 0x00FFC00000 -
0x00FFDFFFFF contains CSU and PMU memory which are marked as Device since it is less than 1MB and
falls in a region with device memory.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 124
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Arm Cortex-A53 64-bit Processor Cache

Functions
Cache functions provide access to cache related operations such as flush and invalidate for
instruction and data caches.

It gives option to perform the cache operations on a single cacheline, a range of memory and an
entire cache.

Table 148: Quick Function Reference

Type Name Arguments

void Xil_DCacheEnable
void

void Xil_DCacheDisable
void

void Xil_DCacheInvalidate
void

void Xil_DCacheInvalidateRange
INTPTR adr
INTPTR len

void Xil_DCacheInvalidateLine
INTPTR adr

void Xil_DCacheFlush
void

void Xil_DCacheFlushLine
INTPTR adr

void Xil_ICacheEnable
void

void Xil_ICacheDisable
void

void Xil_ICacheInvalidate
void

void Xil_ICacheInvalidateRange
INTPTR adr
INTPTR len

void Xil_ICacheInvalidateLine
INTPTR adr

void Xil_ConfigureL1Prefetch
u8 num

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 125
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Functions
Xil_DCacheEnable
Enable the Data cache.

Prototype

void Xil_DCacheEnable(void);

Returns

None.

Xil_DCacheDisable
Disable the Data cache.

Prototype

void Xil_DCacheDisable(void);

Returns

None.

Xil_DCacheInvalidate
Invalidate the Data cache.

The contents present in the cache are cleaned and invalidated.

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate which avoids such corruption.

Prototype

void Xil_DCacheInvalidate(void);

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 126
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Xil_DCacheInvalidateRange
Invalidate the Data cache for the given address range.

The cachelines present in the adderss range are cleaned and invalidated

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate which avoids such corruption.

Prototype

void Xil_DCacheInvalidateRange(INTPTR adr, INTPTR len);

Parameters

The following table lists the Xil_DCacheInvalidateRange function arguments.

Table 149: Xil_DCacheInvalidateRange Arguments

Name Description
adr 64bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_DCacheInvalidateLine
Invalidate a Data cache line.

The cacheline is cleaned and invalidated.

Note: In Cortex-A53, functionality to simply invalid the cachelines is not present. Such operations are a
problem for an environment that supports virtualisation. It would allow one OS to invalidate a line
belonging to another OS. This could lead to the other OS crashing because of the loss of essential data.
Hence, such operations are promoted to clean and invalidate which avoids such corruption.

Prototype

void Xil_DCacheInvalidateLine(INTPTR adr);

Parameters

The following table lists the Xil_DCacheInvalidateLine function arguments.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 127
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Table 150: Xil_DCacheInvalidateLine Arguments

Name Description
adr 64bit address of the data to be flushed.

Returns

None.

Xil_DCacheFlush
Flush the Data cache.

Prototype

void Xil_DCacheFlush(void);

Returns

None.

Xil_DCacheFlushLine
Flush a Data cache line.

If the byte specified by the address (adr) is cached by the Data cache, the cacheline containing
that byte is invalidated. If the cacheline is modified (dirty), the entire contents of the cacheline
are written to system memory before the line is invalidated.

Note: The bottom 6 bits are set to 0, forced by architecture.

Prototype

void Xil_DCacheFlushLine(INTPTR adr);

Parameters

The following table lists the Xil_DCacheFlushLine function arguments.

Table 151: Xil_DCacheFlushLine Arguments

Name Description
adr 64bit address of the data to be flushed.

Returns

None.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 128
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Xil_ICacheEnable
Enable the instruction cache.

Prototype

void Xil_ICacheEnable(void);

Returns

None.

Xil_ICacheDisable
Disable the instruction cache.

Prototype

void Xil_ICacheDisable(void);

Returns

None.

Xil_ICacheInvalidate
Invalidate the entire instruction cache.

Prototype

void Xil_ICacheInvalidate(void);

Returns

None.

Xil_ICacheInvalidateRange
Invalidate the instruction cache for the given address range.

If the instructions specified by the address range are cached by the instrunction cache, the
cachelines containing those instructions are invalidated.

Prototype

void Xil_ICacheInvalidateRange(INTPTR adr, INTPTR len);

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 129
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Parameters

The following table lists the Xil_ICacheInvalidateRange function arguments.

Table 152: Xil_ICacheInvalidateRange Arguments

Name Description
adr 64bit start address of the range to be invalidated.
len Length of the range to be invalidated in bytes.

Returns

None.

Xil_ICacheInvalidateLine
Invalidate an instruction cache line.

If the instruction specified by the parameter adr is cached by the instruction cache, the cacheline
containing that instruction is invalidated.

Note: The bottom 6 bits are set to 0, forced by architecture.

Prototype

void Xil_ICacheInvalidateLine(INTPTR adr);

Parameters

The following table lists the Xil_ICacheInvalidateLine function arguments.

Table 153: Xil_ICacheInvalidateLine Arguments

Name Description
adr 64bit address of the instruction to be invalidated.

Returns

None.

Xil_ConfigureL1Prefetch
Configure the maximum number of outstanding data prefetches allowed in L1 cache.

Note: This function is implemented only for EL3 privilege level.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 130
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Prototype

void Xil_ConfigureL1Prefetch(u8 num);

Parameters

The following table lists the Xil_ConfigureL1Prefetch function arguments.

Table 154: Xil_ConfigureL1Prefetch Arguments

Name Description
num maximum number of outstanding data prefetches allowed, valid values are 0-7.

Returns

None.

Arm Cortex-A53 64-bit Processor MMU

Handling
MMU function equip users to modify default memory attributes of MMU table as per the need.

None.

Note:

Table 155: Quick Function Reference

Type Name Arguments

void Xil_SetTlbAttributes
UINTPTR Addr
u64 attrib

Functions
Xil_SetTlbAttributes
It sets the memory attributes for a section, in the translation table.

If the address (defined by Addr) is less than 4GB, the memory attribute(attrib) is set for a section
of 2MB memory. If the address (defined by Addr) is greater than 4GB, the memory attribute
(attrib) is set for a section of 1GB memory.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 131
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Note: The MMU and D-cache need not be disabled before changing an translation table attribute.

Prototype

void Xil_SetTlbAttributes(UINTPTR Addr, u64 attrib);

Parameters

The following table lists the Xil_SetTlbAttributes function arguments.

Table 156: Xil_SetTlbAttributes Arguments

Name Description
Addr 64-bit address for which attributes are to be set.
attrib Attribute for the specified memory region. xil_mmu.h contains commonly used
memory attributes definitions which can be utilized for this function.

Returns

None.

Arm Cortex-A53 64-bit Mode Time Functions

xtime_l.h provides access to the 64-bit physical timer counter.

Table 157: Quick Function Reference

Type Name Arguments

void XTime_SetTime
XTime Xtime_Global

void XTime_GetTime
XTime * Xtime_Global

Functions
XTime_SetTime
Timer of A53 runs continuously and the time can not be set as desired.

This API doesn't contain anything. It is defined to have uniformity across platforms.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 132
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

Prototype

void XTime_SetTime(XTime Xtime_Global);

Parameters

The following table lists the XTime_SetTime function arguments.

Table 158: XTime_SetTime Arguments

Name Description
Xtime_Global 64bit value to be written to the physical timer counter register. Since API does not do
anything, the value is not utilized.

Returns

None.

XTime_GetTime
Get the time from the physical timer counter register.

Prototype

void XTime_GetTime(XTime *Xtime_Global);

Parameters

The following table lists the XTime_GetTime function arguments.

Table 159: XTime_GetTime Arguments

Name Description
Xtime_Global Pointer to the 64-bit location to be updated with the current value of physical timer
counter register.

Returns

None.

Arm Cortex-A53 64-bit Processor Specific

Include Files
The xpseudo_asm.h includes xreg_cortexa53.h and xpseudo_asm_gcc.h.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 133
 Chapter 7: Arm Cortex-A53 64-bit Processor APIs

The xreg_cortexa53.h file contains definitions for inline assembler code. It provides inline
definitions for Cortex A53 GPRs, SPRs and floating point registers.

The xpseudo_asm_gcc.h contains the definitions for the most often used inline assembler
instructions, available as macros. These can be very useful for tasks such as setting or getting
special purpose registers, synchronization, or cache manipulation etc. These inline assembler
instructions can be used from drivers and user applications written in C.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 134
 Appendix A: Additional Resources and Legal Notices

Appendix A

Additional Resources and Legal

Notices

Xilinx Resources
For support resources such as Answers, Documentation, Downloads, and Forums, see Xilinx
Support.

Documentation Navigator and Design Hubs

Xilinx® Documentation Navigator (DocNav) provides access to Xilinx documents, videos, and
support resources, which you can filter and search to find information. To open DocNav:

• From the Vivado® IDE, select Help → Documentation and Tutorials.

• On Windows, select Start → All Programs → Xilinx Design Tools → DocNav.
• At the Linux command prompt, enter docnav.

Xilinx Design Hubs provide links to documentation organized by design tasks and other topics,
which you can use to learn key concepts and address frequently asked questions. To access the
Design Hubs:

• In DocNav, click the Design Hubs View tab.

• On the Xilinx website, see the Design Hubs page.

Note: For more information on DocNav, see the Documentation Navigator page on the Xilinx website.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 135
 Appendix A: Additional Resources and Legal Notices

Please Read: Important Legal Notices

The information disclosed to you hereunder (the "Materials") is provided solely for the selection
and use of Xilinx products. To the maximum extent permitted by applicable law: (1) Materials are
made available "AS IS" and with all faults, Xilinx hereby DISCLAIMS ALL WARRANTIES AND
CONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO
WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY
PARTICULAR PURPOSE; and (2) Xilinx shall not be liable (whether in contract or tort, including
negligence, or under any other theory of liability) for any loss or damage of any kind or nature
related to, arising under, or in connection with, the Materials (including your use of the
Materials), including for any direct, indirect, special, incidental, or consequential loss or damage
(including loss of data, profits, goodwill, or any type of loss or damage suffered as a result of any
action brought by a third party) even if such damage or loss was reasonably foreseeable or Xilinx
had been advised of the possibility of the same. Xilinx assumes no obligation to correct any
errors contained in the Materials or to notify you of updates to the Materials or to product
specifications. You may not reproduce, modify, distribute, or publicly display the Materials
without prior written consent. Certain products are subject to the terms and conditions of
Xilinx's limited warranty, please refer to Xilinx's Terms of Sale which can be viewed at https://
www.xilinx.com/legal.htm#tos; IP cores may be subject to warranty and support terms contained
in a license issued to you by Xilinx. Xilinx products are not designed or intended to be fail-safe or
for use in any application requiring fail-safe performance; you assume sole risk and liability for
use of Xilinx products in such critical applications, please refer to Xilinx's Terms of Sale which can
be viewed at https://www.xilinx.com/legal.htm#tos.

AUTOMOTIVE APPLICATIONS DISCLAIMER

AUTOMOTIVE PRODUCTS (IDENTIFIED AS "XA" IN THE PART NUMBER) ARE NOT

WARRANTED FOR USE IN THE DEPLOYMENT OF AIRBAGS OR FOR USE IN APPLICATIONS
THAT AFFECT CONTROL OF A VEHICLE ("SAFETY APPLICATION") UNLESS THERE IS A
SAFETY CONCEPT OR REDUNDANCY FEATURE CONSISTENT WITH THE ISO 26262
AUTOMOTIVE SAFETY STANDARD ("SAFETY DESIGN"). CUSTOMER SHALL, PRIOR TO USING
OR DISTRIBUTING ANY SYSTEMS THAT INCORPORATE PRODUCTS, THOROUGHLY TEST
SUCH SYSTEMS FOR SAFETY PURPOSES. USE OF PRODUCTS IN A SAFETY APPLICATION
WITHOUT A SAFETY DESIGN IS FULLY AT THE RISK OF CUSTOMER, SUBJECT ONLY TO
APPLICABLE LAWS AND REGULATIONS GOVERNING LIMITATIONS ON PRODUCT
LIABILITY.

Copyright

© Copyright 2020-2022 Xilinx, Inc. Xilinx, the Xilinx logo, Alveo, Artix, Kintex, Kria, Spartan,
Versal, Vitis, Virtex, Vivado, Zynq, and other designated brands included herein are trademarks of
Xilinx in the United States and other countries. All other trademarks are the property of their
respective owners.

UG647 (v2022.1) April 20, 2022 www.xilinx.com

Send Feedback
Standalone Library v7.7 136