| aiengine Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List

xaielib.c File Reference

## Overview

This file contains the low level layer interface of the AIE driver with the definitions for the memory write and read operations.

    MODIFICATION HISTORY:

    Ver   Who     Date     Changes

    1.0  Naresh  03/23/2018  Initial creation
    1.1  Naresh  05/23/2018  Added bare-metal BSP support
    1.2  Naresh  06/18/2018  Updated code as per standalone driver framework
    1.3  Naresh  07/11/2018  Updated copyright info
    1.4  Hyun    10/10/2018  Added the mask write API
    1.5  Hyun    10/11/2018  Don't include the xaieio header for sim build
    1.6  Hyun    10/16/2018  Added the baremetal compile switch everywhere
                             it's needed
    1.7  Hyun    11/14/2018  Move platform dependent code to xaielib.c
    1.8  Nishad  12/05/2018  Renamed ME attributes to AIE
    1.9  Hyun    01/08/2019  Implement 128bit IO operations for baremetal
    2.0  Hyun    01/08/2019  Add XAieLib_MaskPoll()
    2.1  Hyun    04/05/2019  NPI support for simulation
    2.2  Nishad  05/16/2019  Fix deallocation of pointer not on heap MISRA-c
                                    mandatory violation
    2.3  Nishad  08/07/2019  Remove OS specific gaurd from XAieLib_usleep API
    2.4  Hyun    09/13/2019  Use the simulation elf loader function
    2.5  Hyun    09/13/2019  Use XAieSim_LoadElfMem()
    2.6  Tejus   10/14/2019  Enable assertion for linux and simulation
    2.7  Wendy   02/25/2020  Add logging API
    2.8  Tejus   04/17/2020  Fix variable overflow issue.

u32 | XAieLib_AssertNonvoid (u8 Cond, const char *func, const u32 line)
| This asserts if the condition doesn't meet. More...
void | XAieLib_AssertVoid (u8 Cond, const char *func, const u32 line)
| This asserts if the condition doesn't meet. More...
int | XAieLib_usleep (u64 Usec)
| This provides to sleep in micro seconds. More...
u32 | XAieLib_LoadElf (XAieGbl_Tile *TileInstPtr, u8 *ElfPtr, u8 LoadSym)
| This API loads the elf to corresponding tile. More...
u32 | XAieLib_LoadElfMem (XAieGbl_Tile *TileInstPtr, u8 *ElfPtr, u8 LoadSym)
| This API loads the elf to corresponding tile. More...
void | XAieLib_InitDev (void)
| This API initializes the platform specific device instance if needed. More...
u32 | XAieLib_InitTile (XAieGbl_Tile *TileInstPtr)
| This API initializes the platform specific tile instance if needed. More...
void | XAieLib_InterruptUnregisterIsr (int Offset)
| This API unregisters the interrupt. More...
int | XAieLib_InterruptRegisterIsr (int Offset, int(*Handler)(void *Data), void *Data)
| This API registers the handler for interrupt. More...
void | XAieLib_InterruptEnable (void)
| This API enables AIE interrupt. More...
void | XAieLib_InterruptDisable (void)
| This API disables AIE interrupt. More...
void | XAieLib_IntPrint (const char *Format,...)
| This API re-routes to platform print function. More...
u32 | XAieLib_OpenLogFile (const char *File)
| This API set the log file. More...
void | XAieLib_CloseLogFile (void)
| This API close the log file. More...
void | XAieLib_log (XAieLib_LogLevel Level, const char *Format,...)
| This API implements AIE logging. More...
XAieLib_MemInst * | XAieLib_MemInit (u8 idx)
| This is the memory function to initialize the platform specific memory instance. More...
void | XAieLib_MemFinish (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to free the platform specific memory instance. More...
XAieLib_MemInst * | XAieLib_MemAttach (u64 Vaddr, u64 Paddr, u64 Size, u64 MemHandle)
| This is the memory function to attach the external memory to device. More...
void | XAieLib_MemDetach (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to detach the memory from device. More...
XAieLib_MemInst * | XAieLib_MemAllocate (u64 Size, u32 Attr)
| This is the memory function to allocate a memory. More...
void | XAieLib_MemFree (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to free the memory. More...
u8 | XAieLib_MemSyncForCPU (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to sync the memory for CPU. More...
u8 | XAieLib_MemSyncForDev (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to sync the memory for device. More...
u64 | XAieLib_MemGetSize (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to return the size of the memory instance. More...
u64 | XAieLib_MemGetVaddr (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to return the virtual address of the memory instance. More...
u64 | XAieLib_MemGetPaddr (XAieLib_MemInst *XAieLib_MemInstPtr)
| This is the memory function to return the virtual address of the memory instance. More...
void | XAieLib_MemWrite32 (XAieLib_MemInst *XAieLib_MemInstPtr, u64 Addr, u32 Data)
| This is the memory function to write to the physical address. More...
u32 | XAieLib_MemRead32 (XAieLib_MemInst *XAieLib_MemInstPtr, u64 Addr)
| This is the memory function to read from the physical address. More...
u32 | XAieLib_Read32 (u64 Addr)
| This is the memory IO function to read 32bit data from the specified address. More...
void | XAieLib_Read128 (u64 Addr, u32 *Data)
| This is the memory IO function to read 128b data from the specified address. More...
void | XAieLib_Write32 (u64 Addr, u32 Data)
| This is the memory IO function to write 32bit data to the specified address. More...
void | XAieLib_MaskWrite32 (u64 Addr, u32 Mask, u32 Data)
| This is the memory IO function to write a masked 32bit data to the specified address. More...
void | XAieLib_Write128 (u64 Addr, u32 *Data)
| This is the memory IO function to write 128bit data to the specified address. More...
void | XAieLib_WriteCmd (u8 Command, u8 ColId, u8 RowId, u32 CmdWd0, u32 CmdWd1, u8 *CmdStr)
| This is the memory IO function to write 128bit data to the specified address. More...
u32 | XAieLib_MaskPoll (u64 Addr, u32 Mask, u32 Value, u32 TimeOutUs)
| This is the IO function to poll until the value at the address to be given masked value. More...
u32 | XAieLib_NPIRead32 (u64 Addr)
| This is the NPI IO function to read 32bit data from the specified address. More...
void | XAieLib_NPIWrite32 (u64 Addr, u32 Data)
| This is the NPI IO function to write 32bit data to the specified address. More...
void | XAieLib_NPIMaskWrite32 (u64 Addr, u32 Mask, u32 Data)
| This is the NPI IO function to write a masked 32bit data to the specified address. More...
u32 | XAieLib_NPIMaskPoll (u64 Addr, u32 Mask, u32 Value, u32 TimeOutUs)
| This is the NPI IO function to poll until the value at the address to be given masked value. More...

## Function Documentation

u32 XAieLib_AssertNonvoid | ( | u8 | Cond,
|  | const char * | func,
|  | const u32 | line
| ) |  |

This asserts if the condition doesn't meet.

Parameters

  Cond,: | Condition to meet. Should be 0 or 1.

Returns
  0

Note
  None.

void XAieLib_AssertVoid | ( | u8 | Cond,
|  | const char * | func,
|  | const u32 | line
| ) |  |

This asserts if the condition doesn't meet.

Can be used for void return function.

Parameters

  Cond,: | Condition to meet. Should be 0 or 1.

Returns
  None.

Note
  None.

void XAieLib_CloseLogFile | ( | void |  | ) |

This API close the log file.

Returns
  None.

Note
  None.

void XAieLib_InitDev | ( | void |  | ) |

This API initializes the platform specific device instance if needed.

Parameters

  None. |

Returns
  None.

Note
  None.

References XAieIO_Init().

Referenced by XAieGbl_CfgInitialize().

u32 XAieLib_InitTile | ( | XAieGbl_Tile * | TileInstPtr | ) |

This API initializes the platform specific tile instance if needed.

Parameters

  TileInstPtr,: | Tile instance to be initialized

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE.

Note
  If there's no platform specific initialization, return XAIELIB_SUCCESS.

References XAieTileProc_Init().

Referenced by XAieGbl_CfgInitialize().

void XAieLib_InterruptDisable | ( | void |  | ) |

This API disables AIE interrupt.

Returns
  None.

Note
  None.

References XAieIO_IntrDisable().

void XAieLib_InterruptEnable | ( | void |  | ) |

This API enables AIE interrupt.

Returns
  None.

Note
  None.

References XAieIO_IntrEnable().

int XAieLib_InterruptRegisterIsr | ( | int | Offset,
|  | int(*)(void *Data) | Handler,
|  | void * | Data
| ) |  |

This API registers the handler for interrupt.

Parameters

  Offset,: | The value should one of 1 - 3.
  Handler,: | the callback to be called upon interrupt.
  Data,: | the data to be used with the handler.

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE.

Note
  None.

References XAieIO_IntrRegisterIsr().

void XAieLib_InterruptUnregisterIsr | ( | int | Offset | ) |

This API unregisters the interrupt.

Parameters

  Offest,: | Should be 1 - 3.

Returns
  None.

Note
  None.

References XAieIO_IntrUnregisterIsr().

void XAieLib_IntPrint | ( | const char * | Format,
|  |  | ...
| ) |  |

This API re-routes to platform print function.

Parameters

  format | strings

Returns
  None.

Note
  None.

Referenced by XAieLib_OpenLogFile(), and XAieTile_ErrorRegisterNotification().

u32 XAieLib_LoadElf | ( | XAieGbl_Tile * | TileInstPtr,
|  | u8 * | ElfPtr,
|  | u8 | LoadSym
| ) |  |

This API loads the elf to corresponding tile.

Parameters

  TileInstPtr,: | Tile instance for the elf to be loaded
  ElfPtr,: | path to the elf file

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE

Note
  None.

References XAieSim_LoadElf().

u32 XAieLib_LoadElfMem | ( | XAieGbl_Tile * | TileInstPtr,
|  | u8 * | ElfPtr,
|  | u8 | LoadSym
| ) |  |

This API loads the elf to corresponding tile.

Parameters

  TileInstPtr,: | Tile instance for the elf to be loaded
  ElfPtr,: | pointer to the elf in memory

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE

Note
  None.

References XAieSim_LoadElfMem().

void XAieLib_log | ( | XAieLib_LogLevel | Level,
|  | const char * | Format,
|  |  | ...
| ) |  |

This API implements AIE logging.

Parameters

  Level | - Log level
  Format | - format string

Returns
  None.

Note
  None.

u32 XAieLib_MaskPoll | ( | u64 | Addr,
|  | u32 | Mask,
|  | u32 | Value,
|  | u32 | TimeOutUs
| ) |  |

This is the IO function to poll until the value at the address to be given masked value.

Parameters

  Addr,: | Address to write to.
  Mask,: | Mask to be applied to read data.
  Value,: | The expected value
  TimeOutUs,: | Minimum timeout in usec.

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE

Note
  None.

References XAieLib_Read32(), XAieLib_usleep(), and XAieSim_MaskPoll().

void XAieLib_MaskWrite32 | ( | u64 | Addr,
|  | u32 | Mask,
|  | u32 | Data
| ) |  |

This is the memory IO function to write a masked 32bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Mask,: | Mask to be applied to Data.
  Data,: | 32-bit data to be written.

Returns
  None.

Note
  None.

References XAieIO_Read32(), XAieIO_Write32(), and XAieSim_MaskWrite32().

XAieLib_MemInst* XAieLib_MemAllocate | ( | u64 | Size,
|  | u32 | Attr
| ) |  |

This is the memory function to allocate a memory.

Parameters

  Size,: | Size of the memory
  Attr,: | Any of XAIELIB_MEM_ATTR_*

Returns
  Pointer to the allocated IO memory instance.

Note
  None.

References XAieIO_MemAllocate().

XAieLib_MemInst* XAieLib_MemAttach | ( | u64 | Vaddr,
|  | u64 | Paddr,
|  | u64 | Size,
|  | u64 | MemHandle
| ) |  |

This is the memory function to attach the external memory to device.

Parameters

  Vaddr,: | Vaddr of the memory
  Paddr,: | Paddr of the memory
  Size,: | Size of the memory
  MemHandle,: | Handle of the memory. For linux, dmabuf fd

Returns
  Pointer to the attached memory instance.

Note
  Some arguments are not required for some backend platforms. This is determined by platform implementation.

References XAieIO_MemAttach().

void XAieLib_MemDetach | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to detach the memory from device.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.

Returns
  None.

Note
  None.

References XAieIO_MemDetach().

void XAieLib_MemFinish | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to free the platform specific memory instance.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.

Returns
  None.

Note
  is freed and invalid after this function.

References XAieIO_MemFinish().

void XAieLib_MemFree | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to free the memory.

Parameters

  XAieLib_MemInstPtr,: | IO Memory instance pointer.

Returns
  None.

Note
  None.

References XAieIO_MemFree().

u64 XAieLib_MemGetPaddr | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to return the virtual address of the memory instance.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.

Returns
  Physical address of the memory instance. 0 if not supported.

Note
  None.

References XAieIO_MemGetPaddr().

u64 XAieLib_MemGetSize | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to return the size of the memory instance.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.

Returns
  size of the memory instance. 0 if not supported.

Note
  None.

References XAieIO_MemGetSize().

u64 XAieLib_MemGetVaddr | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to return the virtual address of the memory instance.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.

Returns
  Mapped virtual address of the memory instance. 0 if not supported.

Note
  None.

References XAieIO_MemGetVaddr().

XAieLib_MemInst* XAieLib_MemInit | ( | u8 | idx | ) |

This is the memory function to initialize the platform specific memory instance.

Parameters

  idx,: | Index of the memory to initialize.

Returns
  Pointer to the initialized memory instance. Null or 0 if not supported.

Note
  None.

References XAieIO_MemInit().

u32 XAieLib_MemRead32 | ( | XAieLib_MemInst * | XAieLib_MemInstPtr,
|  | u64 | Addr
| ) |  |

This is the memory function to read from the physical address.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.
  Addr,: | Absolute physical address to write.

Returns
  A read 32 bit data. 0 if not supported.

Note
  None.

References XAieIO_MemRead32().

u8 XAieLib_MemSyncForCPU | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to sync the memory for CPU.

Parameters

  XAieLib_MemInstPtr,: | IO Memory instance pointer.

Returns
  XAIELIB_SUCCESS if successful.

Note
  None.

References XAieIO_MemSyncForCPU().

u8 XAieLib_MemSyncForDev | ( | XAieLib_MemInst * | XAieLib_MemInstPtr | ) |

This is the memory function to sync the memory for device.

Parameters

  XAieLib_MemInstPtr,: | IO Memory instance pointer.

Returns
  XAIELIB_SUCCESS if successful.

Note
  None.

References XAieIO_MemSyncForDev().

void XAieLib_MemWrite32 | ( | XAieLib_MemInst * | XAieLib_MemInstPtr,
|  | u64 | Addr,
|  | u32 | Data
| ) |  |

This is the memory function to write to the physical address.

Parameters

  XAieLib_MemInstPtr,: | Memory instance pointer.
  Addr,: | Absolute physical address to write.
  Data,: | A 32 bit data to write.

Returns
  None.

Note
  None.

References XAieIO_MemWrite32().

u32 XAieLib_NPIMaskPoll | ( | u64 | Addr,
|  | u32 | Mask,
|  | u32 | Value,
|  | u32 | TimeOutUs
| ) |  |

This is the NPI IO function to poll until the value at the address to be given masked value.

Parameters

  Addr,: | Address to write to.
  Mask,: | Mask to be applied to read data.
  Value,: | The expected value
  TimeOutUs,: | Minimum timeout in usec.

Returns
  XAIELIB_SUCCESS on success, otherwise XAIELIB_FAILURE

Note
  This only work if NPI is accessble.

References XAieLib_NPIRead32(), XAieLib_usleep(), and XAieSim_NPIMaskPoll().

void XAieLib_NPIMaskWrite32 | ( | u64 | Addr,
|  | u32 | Mask,
|  | u32 | Data
| ) |  |

This is the NPI IO function to write a masked 32bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Mask,: | Mask to be applied to Data.
  Data,: | 32-bit data to be written.

Returns
  None.

Note
  This only work if NPI is accessble.

References XAieIO_NPIRead32(), XAieIO_NPIWrite32(), and XAieSim_NPIMaskWrite32().

u32 XAieLib_NPIRead32 | ( | u64 | Addr | ) |

This is the NPI IO function to read 32bit data from the specified address.

Parameters

  Addr,: | Address to read from.

Returns
  32-bit read value.

Note
  This only work if NPI is accessble.

References XAieIO_NPIRead32(), and XAieSim_NPIRead32().

Referenced by XAieLib_NPIMaskPoll().

void XAieLib_NPIWrite32 | ( | u64 | Addr,
|  | u32 | Data
| ) |  |

This is the NPI IO function to write 32bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Data,: | 32-bit data to be written.

Returns
  None.

Note
  This only work if NPI is accessble.

References XAieIO_NPIWrite32(), and XAieSim_NPIWrite32().

u32 XAieLib_OpenLogFile | ( | const char * | File | ) |

This API set the log file.

Parameters

  File | - path of the file for logging.

Returns
  XAIE_SUCCESS for success or XAIE_FAILURE for failure.

Note
  If will be fail if the file is failed to open, or if there is already logging file opened.

References XAieLib_IntPrint().

void XAieLib_Read128 | ( | u64 | Addr,
|  | u32 * | Data
| ) |  |

This is the memory IO function to read 128b data from the specified address.

Parameters

  Addr,: | Address to read from.
  Data,: | Pointer to the 128-bit buffer to store the read data.

Returns
  None.

Note
  None.

References XAieIO_Read32(), and XAieSim_Read32().

u32 XAieLib_Read32 | ( | u64 | Addr | ) |

This is the memory IO function to read 32bit data from the specified address.

Parameters

  Addr,: | Address to read from.

Returns
  32-bit read value.

Note
  None.

References XAieIO_Read32(), and XAieSim_Read32().

Referenced by XAieLib_MaskPoll().

int XAieLib_usleep | ( | u64 | Usec | ) |

This provides to sleep in micro seconds.

Parameters

  Usec,: | Micro seconds to sleep

Returns
  0 for success, and -1 for error..

Note
  None.

FIXME: Platform implementation of usleep() API, returns void when it is expected to return SUCCESS/FAILURE code. Instead of returning a zero, this API must return SUCCESS/FAILURE code when usleep API is fixed.

Referenced by XAieLib_MaskPoll(), and XAieLib_NPIMaskPoll().

void XAieLib_Write128 | ( | u64 | Addr,
|  | u32 * | Data
| ) |  |

This is the memory IO function to write 128bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Data,: | Pointer to the 128-bit data buffer.

Returns
  None.

Note
  None.

References XAieIO_Write128(), and XAieSim_Write128().

void XAieLib_Write32 | ( | u64 | Addr,
|  | u32 | Data
| ) |  |

This is the memory IO function to write 32bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Data,: | 32-bit data to be written.

Returns
  None.

Note
  None.

References XAieIO_Write32(), and XAieSim_Write32().

void XAieLib_WriteCmd | ( | u8 | Command,
|  | u8 | ColId,
|  | u8 | RowId,
|  | u32 | CmdWd0,
|  | u32 | CmdWd1,
|  | u8 * | CmdStr
| ) |  |

This is the memory IO function to write 128bit data to the specified address.

Parameters

  Addr,: | Address to write to.
  Data,: | Pointer to the 128-bit data buffer.

Returns
  None.

Note
  None.

References XAieSim_WriteCmd().