| aiengine Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List

Data Structures
xaiedma_shim.h File Reference

## Overview

Header file for the Shim DMA functions.

    MODIFICATION HISTORY:

    Ver   Who     Date     Changes

    1.0  Naresh  03/14/2018  Initial creation
    1.1  Naresh  07/11/2018  Updated copyright info
    1.2  Nishad  12/05/2018  Renamed ME attributes to AIE
    1.3  Hyun    06/20/2019  Added APIs for individual BD / Channel reset
    1.4  Hyun    06/20/2019  Add XAieDma_ShimSoftInitialize()
    1.5  Dishita 02/07/2020  Resolved macro compilation error

## Data Structures
struct | XAieDma_ShimBdLk
| This typedef contains the lock attributes for the BD. More...
struct | XAieDma_ShimBdAxi
| This typedef contains the AXI attributes for the BD. More...
struct | XAieDma_ShimBd
| This typedef contains all the attributes for the BD configuration. More...
struct | XAieDma_Shim
| This typedef is the Shim DMA instance. More...
#define | XAieDma_ShimChControl(DmaInstPtr, ChNum, PauseStrm, PauseMm, Enable)
| Macro to configure the selected Shim DMA channel conrol bits. More...
#define | XAieDma_ShimSetStartBd(DmaInstPtr, ChNum, StartBd)
| Macro to set the StartBd for the selected Shim DMA channel. More...
u32 | XAieDma_ShimSoftInitialize (XAieGbl_Tile *TileInstPtr, XAieDma_Shim *DmaInstPtr)
| This API intializes the Shim DMA instances without programming any related resources such as bd and channel. More...
void | XAieDma_ShimInitialize (XAieGbl_Tile *TileInstPtr, XAieDma_Shim *DmaInstPtr)
| This API intializes the Shim DMA BDs to their default values and followed by disable of all the 4 channels (S2MM0, S2MM1, MM2S0, MM2S1). More...
u32 | XAieDma_ShimChReset (XAieDma_Shim *DmaInstPtr, u8 ChNum)
| This API resets the selected Shim DMA channel, followed by disabling the channel. More...
u32 | XAieDma_ShimChResetAll (XAieDma_Shim *DmaInstPtr)
| This API resets all Shim DMA channel, followed by disabling the channel. More...
void | XAieDma_ShimBdSetLock (XAieDma_Shim *DmaInstPtr, u8 BdNum, u8 LockId, u8 LockRelEn, u8 LockRelVal, u8 LockAcqEn, u8 LockAcqVal)
| This API is to configure the Lock release and acquire attributes for the selected BD entry in the Shim DMA instance which is later written to the the physical BD location. More...
void | XAieDma_ShimBdSetAxi (XAieDma_Shim *DmaInstPtr, u8 BdNum, u8 Smid, u8 BurstLen, u8 Qos, u8 Cache, u8 Secure)
| This API is to configure the AXI attributes for the selected BD entry in the Shim DMA instance. More...
void | XAieDma_ShimBdSetPkt (XAieDma_Shim *DmaInstPtr, u8 BdNum, u8 PktEn, u8 PktType, u8 PktId)
| This API configures the Packet attributes of the selected BD entry in the Shim DMA instance. More...
void | XAieDma_ShimBdSetNext (XAieDma_Shim *DmaInstPtr, u8 BdNum, u8 NextBd)
| This API configures the Next BD attribute for the selected BD entry in the Shim DMA instance. More...
void | XAieDma_ShimBdSetAddr (XAieDma_Shim *DmaInstPtr, u8 BdNum, u16 AddrHigh, u32 AddrLow, u32 Length)
| This API configures the address and length attributes for the selected BD entry in the Shim DMA instance. More...
void | XAieDma_ShimBdWrite (XAieDma_Shim *DmaInstPtr, u8 BdNum)
| This API writes all the attributes of the selected BD entry in the Shim DMA instance to the actual physical BD location. More...
void | XAieDma_ShimBdClear (XAieDma_Shim *DmaInstPtr, u8 BdNum)
| This API is used to clear the selected BD entry in the Shim DMA instance. More...
void | XAieDma_ShimBdClearAll (XAieDma_Shim *DmaInstPtr)
| This API is used to clear all BD entries in the Shim DMA instance. More...
u8 | XAieDma_ShimWaitDone (XAieDma_Shim *DmaInstPtr, u32 ChNum, u32 TimeOut)
| This API is used to wait on Shim DMA channel to be completed. More...
u8 | XAieDma_ShimPendingBdCount (XAieDma_Shim *DmaInstPtr, u32 ChNum)
| This API is used to get the count of scheduled BDs in pending. More...

## Macro Definition Documentation

#define XAieDma_ShimChControl | ( |  | DmaInstPtr,
|  |  | ChNum,
|  |  | PauseStrm,
|  |  | PauseMm,
|  |  | Enable
| ) |  |

Value:
XAieGbl_Write32(((DmaInstPtr)->BaseAddress + \
ShimDmaCh[ChNum].CtrlOff), \
(XAie_SetField(PauseStrm, ShimDmaCh[ChNum].PzStr.Lsb, \
ShimDmaCh[ChNum].PzStr.Mask) | \
XAie_SetField(PauseMm, ShimDmaCh[ChNum].PzMem.Lsb, \
ShimDmaCh[ChNum].PzMem.Mask) | \
XAie_SetField(Enable, ShimDmaCh[ChNum].En.Lsb, \
ShimDmaCh[ChNum].En.Mask)))

Macro to configure the selected Shim DMA channel conrol bits.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  ChNum | - Channel number (0-S2MM0,1-S2MM1,2-MM2S0,3-MM2S1).
  PauseStrm | - When set, pauses the stream traffic.
  PauseMm | - When set, pauses the issuing of new AXI-MM commands.
  Enable | - Enable channel (1-Enable,0-Disable).

Returns
  None.

Note
  None.

Referenced by XAieDma_ShimChReset(), and XAieDma_ShimInitialize().

#define XAieDma_ShimSetStartBd | ( |  | DmaInstPtr,
|  |  | ChNum,
|  |  | StartBd
| ) |  |

Value:
XAieGbl_Write32(((DmaInstPtr)->BaseAddress + \
ShimDmaCh[ChNum].StatQOff), \
XAie_SetField(StartBd, ShimDmaCh[ChNum].StatQ.Lsb, \
ShimDmaCh[ChNum].StatQ.Mask)); \
(DmaInstPtr)->BdStart[ChNum] = StartBd

Macro to set the StartBd for the selected Shim DMA channel.

Parameters

  DmaInstPtr | - Pointer to the Shmim DMA instance.
  ChNum | - Channel number (0-S2MM0,1-S2MM1,2-MM2S0,3-MM2S1).
  BdStart | - BD value for the channel to start with (range:0-15).

Returns
  None.

Note
  None.

Referenced by XAieDma_ShimChReset(), and XAieDma_ShimInitialize().

## Function Documentation

void XAieDma_ShimBdClear | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum
| ) |  |

This API is used to clear the selected BD entry in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index which needs to be cleared.

Returns
  None.

Note
  This doesn't clear the values in the BD physical location.

References XAieDma_ShimBd::AddrH, XAieDma_ShimBd::AddrL, XAieDma_ShimBd::Axi, XAieDma_ShimBdAxi::BrstLen, XAieDma_ShimBdAxi::Cache, XAieDma_Shim::Descrs, XAieDma_ShimBd::Length, XAieDma_ShimBdLk::LkAcqEn, XAieDma_ShimBdLk::LkAcqVal, XAieDma_ShimBdLk::LkAcqValEn, XAieDma_ShimBdLk::LkRelEn, XAieDma_ShimBdLk::LkRelVal, XAieDma_ShimBdLk::LkRelValEn, XAieDma_ShimBd::Lock, XAieDma_ShimBdLk::LockId, XAieDma_ShimBd::NextBd, XAieDma_ShimBd::NextBdEn, XAieDma_ShimBd::PktEn, XAieDma_ShimBd::PktId, XAieDma_ShimBd::PktType, XAieDma_ShimBdAxi::Qos, XAieDma_ShimBdAxi::Secure, and XAieDma_ShimBdAxi::Smid.

Referenced by XAieDma_ShimBdClearAll(), and XAieDma_ShimInitialize().

void XAieDma_ShimBdClearAll | ( | XAieDma_Shim * | DmaInstPtr | ) |

This API is used to clear all BD entries in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.

Returns
  None.

Note
  This doesn't clear the values in the BD physical location.

References XAieDma_ShimBdClear().

void XAieDma_ShimBdSetAddr | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum,
|  | u16 | AddrHigh,
|  | u32 | AddrLow,
|  | u32 | Length
| ) |  |

This API configures the address and length attributes for the selected BD entry in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be set to.
  AddrHigh | - Upper 16-bits base address bits.
  AddrLow | - Lower 32-bits base address bits.
  Length | - Transfer length in bytes (min length = 4 bytes).

Returns
  None.

Note
  This doesn't set the values in the BD physical location.

References XAieDma_ShimBd::AddrH, XAieDma_ShimBd::AddrL, XAieDma_Shim::Descrs, and XAieDma_ShimBd::Length.

void XAieDma_ShimBdSetAxi | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum,
|  | u8 | Smid,
|  | u8 | BurstLen,
|  | u8 | Qos,
|  | u8 | Cache,
|  | u8 | Secure
| ) |  |

This API is to configure the AXI attributes for the selected BD entry in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be set to.
  Smid | - SMID value for the AXI-MM transfer.
  BurstLen | - Burst length for the AXI-MM transfer (4 or 8 or 16).
  Qos | - AXI Qos bits (AxQOS) for the AXI-MM transfer.
  Cache | - AxCACHE bits for the AXI-MM transfer.
  Secure | - Secure staus of the transfer (1-Secure,0-Non secure).

Returns
  None.

Note
  This doesn't set the values in the BD physical location.

References XAieDma_ShimBd::Axi, XAieDma_ShimBdAxi::BrstLen, XAieDma_ShimBdAxi::Cache, XAieDma_Shim::Descrs, XAieDma_ShimBdAxi::Qos, XAieDma_ShimBdAxi::Secure, and XAieDma_ShimBdAxi::Smid.

void XAieDma_ShimBdSetLock | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum,
|  | u8 | LockId,
|  | u8 | LockRelEn,
|  | u8 | LockRelVal,
|  | u8 | LockAcqEn,
|  | u8 | LockAcqVal
| ) |  |

This API is to configure the Lock release and acquire attributes for the selected BD entry in the Shim DMA instance which is later written to the the physical BD location.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be set to.
  LockId | - Lock index value, ranging from 0-15.
  LockRelEn | - Enable/Disable lock release (1-Enable,0-Disable).
  LockRelVal | - Lock release value (Valid:0/1 & Invalid:0xFF).
  LockAcqEn | - Enable/Disable lock acquire (1-Enable,0-Disable).
  LockAcqVal | - Lock acquire value (Valid:0/1 & Invalid:0xFF).

Returns
  None.

Note
  This doesn't set the values in the BD physical location.

References XAieDma_Shim::Descrs, XAieDma_ShimBdLk::LkAcqEn, XAieDma_ShimBdLk::LkAcqVal, XAieDma_ShimBdLk::LkAcqValEn, XAieDma_ShimBdLk::LkRelEn, XAieDma_ShimBdLk::LkRelVal, XAieDma_ShimBdLk::LkRelValEn, XAieDma_ShimBd::Lock, and XAieDma_ShimBdLk::LockId.

void XAieDma_ShimBdSetNext | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum,
|  | u8 | NextBd
| ) |  |

This API configures the Next BD attribute for the selected BD entry in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be set to.
  NextBd | - Next BD to use, ranging from 0-15. If NextBd==0xFF, it is deemed invalid and UseNextBd is set to 0.

Returns
  None.

Note
  This doesn't set the values in the BD physical location.

References XAieDma_Shim::Descrs, XAieDma_ShimBd::NextBd, and XAieDma_ShimBd::NextBdEn.

void XAieDma_ShimBdSetPkt | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum,
|  | u8 | PktEn,
|  | u8 | PktType,
|  | u8 | PktId
| ) |  |

This API configures the Packet attributes of the selected BD entry in the Shim DMA instance.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be set to.
  PktEn | - Enable/Disable Pkt switching mode (1-Enable,0-Disable).
  PktType | - Packet type.
  PktId | - ID value for the packet.

Returns
  None.

Note
  This doesn't set the values in the BD physical location.

References XAieDma_Shim::Descrs, XAieDma_ShimBd::PktEn, XAieDma_ShimBd::PktId, and XAieDma_ShimBd::PktType.

void XAieDma_ShimBdWrite | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | BdNum
| ) |  |

This API writes all the attributes of the selected BD entry in the Shim DMA instance to the actual physical BD location.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  BdNum | - BD index whose attributes need to be written to the corresponding physical location.

Returns
  None.

Note
  None.

References XAieGbl_RegShimBdCtrl::AcqEn, XAieGbl_RegShimBdCtrl::AcqVal, XAieGbl_RegShimBdCtrl::AcqValEn, XAieGbl_RegShimBdCtrl::Addh, XAieGbl_RegShimDmaBd::Addl, XAieDma_ShimBd::AddrH, XAieDma_ShimBd::AddrL, XAieDma_ShimBd::Axi, XAieGbl_RegShimDmaBd::Axi, XAieDma_Shim::BaseAddress, XAieGbl_RegShimBdAxi::Blen, XAieDma_ShimBdAxi::BrstLen, XAieDma_ShimBdAxi::Cache, XAieGbl_RegShimBdAxi::Cache, XAieGbl_RegShimDmaBd::Ctrl, XAieDma_Shim::Descrs, XAieGbl_RegShimBdPkt::En, XAieGbl_RegShimBdPkt::Id, XAieGbl_RegShimDmaBd::Len, XAieDma_ShimBd::Length, XAieDma_ShimBdLk::LkAcqEn, XAieDma_ShimBdLk::LkAcqVal, XAieDma_ShimBdLk::LkAcqValEn, XAieDma_ShimBdLk::LkRelEn, XAieDma_ShimBdLk::LkRelVal, XAieDma_ShimBdLk::LkRelValEn, XAieDma_ShimBd::Lock, XAieGbl_RegShimBdCtrl::Lock, XAieDma_ShimBdLk::LockId, XAieGbl_RegFldAttr::Lsb, XAieGbl_RegFldAttr::Mask, XAieGbl_RegShimBdCtrl::NexBd, XAieGbl_RegShimBdCtrl::NexEn, XAieDma_ShimBd::NextBd, XAieDma_ShimBd::NextBdEn, XAieGbl_RegShimDmaBd::Pkt, XAieDma_ShimBd::PktEn, XAieDma_ShimBd::PktId, XAieDma_ShimBd::PktType, XAieDma_ShimBdAxi::Qos, XAieGbl_RegShimBdAxi::Qos, XAieGbl_RegShimDmaBd::RegOff, XAieGbl_RegShimBdCtrl::RelEn, XAieGbl_RegShimBdCtrl::RelVal, XAieGbl_RegShimBdCtrl::RelValEn, XAieGbl_RegShimBdAxi::Sec, XAieDma_ShimBdAxi::Secure, XAieDma_ShimBdAxi::Smid, XAieGbl_RegShimBdAxi::Smid, XAieGbl_RegShimBdPkt::Type, and XAieGbl_RegShimBdCtrl::Valid.

u32 XAieDma_ShimChReset | ( | XAieDma_Shim * | DmaInstPtr,
|  | u8 | ChNum
| ) |  |

This API resets the selected Shim DMA channel, followed by disabling the channel.

The StartBd is cleared to default value.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  ChNum | - Channel number (0-S2MM0,1-S2MM1,2-MM2S0,3-MM2S1).

Returns
  XAIE_SUCCESS if successful, else XAIE_FAILURE.

Note
  None.

References XAieDma_ShimChControl, and XAieDma_ShimSetStartBd.

Referenced by XAieDma_ShimChResetAll().

u32 XAieDma_ShimChResetAll | ( | XAieDma_Shim * | DmaInstPtr | ) |

This API resets all Shim DMA channel, followed by disabling the channel.

The StartBd is cleared to default value.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.

Returns
  XAIE_SUCCESS if successful, else XAIE_FAILURE.

Note
  None.

References XAieDma_ShimChReset().

void XAieDma_ShimInitialize | ( | XAieGbl_Tile * | TileInstPtr,
|  | XAieDma_Shim * | DmaInstPtr
| ) |  |

This API intializes the Shim DMA BDs to their default values and followed by disable of all the 4 channels (S2MM0, S2MM1, MM2S0, MM2S1).

Parameters

  TileInstPtr | - Pointer to the Tile instance.
  DmaInstPtr | - Pointer to the Shim DMA instance.

Returns
  None.

Note
  This API is required to be invoked first in the sequence, before any of the other Shim DMA driver APIs are used.

References XAieDma_Shim::BaseAddress, XAieGbl_Tile::TileAddr, XAieGbl_Tile::TileType, XAieDma_ShimBdClear(), XAieDma_ShimChControl, and XAieDma_ShimSetStartBd.

u8 XAieDma_ShimPendingBdCount | ( | XAieDma_Shim * | DmaInstPtr,
|  | u32 | ChNum
| ) |  |

This API is used to get the count of scheduled BDs in pending.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  ChNum | - Should be one of XAIEDMA_SHIM_CHNUM_S2MM0, XAIEDMA_SHIM_CHNUM_S2MM1, XAIEDMA_SHIM_CHNUM_MM2S0, or XAIEDMA_SHIM_CHNUM_MM2S1.

Returns
  Number of scheduled BDs in pending

Note
  This function checks the number of pending BDs in the queue as well as if there's any BD that the channel is currently operating on. If multiple BDs are chained, it's counted as one BD.

References XAieDma_Shim::BaseAddress, XAieGbl_RegFldAttr::Mask, XAieGbl_RegShimDmaSts::RegOff, XAieGbl_RegShimDmaSts::Stalled, XAieGbl_RegShimDmaSts::StartQSize, and XAieGbl_RegShimDmaSts::Sts.

u32 XAieDma_ShimSoftInitialize | ( | XAieGbl_Tile * | TileInstPtr,
|  | XAieDma_Shim * | DmaInstPtr
| ) |  |

This API intializes the Shim DMA instances without programming any related resources such as bd and channel.

This allows the resource to be managed independently.

Parameters

  TileInstPtr | - Pointer to the Tile instance.
  DmaInstPtr | - Pointer to the Shim DMA instance.

Returns
  XAIE_SUCCESS if successful, else XAIE_FAILURE.

Note
  This API is required to be invoked first in the sequence, before any of the other Shim DMA driver APIs are used.

References XAieDma_Shim::BaseAddress, XAieGbl_Tile::TileAddr, and XAieGbl_Tile::TileType.

u8 XAieDma_ShimWaitDone | ( | XAieDma_Shim * | DmaInstPtr,
|  | u32 | ChNum,
|  | u32 | TimeOut
| ) |  |

This API is used to wait on Shim DMA channel to be completed.

Parameters

  DmaInstPtr | - Pointer to the Shim DMA instance.
  ChNum | - Should be one of XAIEDMA_SHIM_CHNUM_S2MM0, XAIEDMA_SHIM_CHNUM_S2MM1, XAIEDMA_SHIM_CHNUM_MM2S0, or XAIEDMA_SHIM_CHNUM_MM2S1.
  TimeOut | - Minimum timeout value in micro seconds.

Returns
  0 if completed or 1 for timedout.

Note
  None.

References XAieDma_Shim::BaseAddress, XAieGbl_RegFldAttr::Lsb, XAieGbl_RegFldAttr::Mask, XAieGbl_RegShimDmaSts::RegOff, XAieGbl_RegShimDmaSts::Stalled, XAieGbl_RegShimDmaSts::StartQSize, and XAieGbl_RegShimDmaSts::Sts.