| pciepsu Vitis Drivers API Documentation

- Overview
- APIs
- File List
- Examples

Macros | Functions
xpciepsu.h File Reference

## Overview

This file contains the software API definition of the Xilinx PSU PCI IP (psu_pcie).

This driver provides "C" function interface to application/upper layer to access the hardware.

Features The driver provides its user with entry points

- To initialize and configure itself and the hardware
- To access PCIe configuration space locally

Driver Initialization & Configuration

The XPciePsu_Config structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.

To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in the following way:

- XPciePsu_LookupConfig(DeviceId) - Use the device identifier to find the static configuration structure defined in xpciepsu_g.c. This is setup by the tools.
- XPciePsu_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddress) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.

    MODIFICATION HISTORY:

    Ver   Who  Date     Changes

    1.0     bs      08/21/2018      First release

## Macros
#define | MAX_BARS 6
| No BAR allocation for Bridge. More...
#define | REQ_SIZE (MAX_BARS * sizeof(unsigned long))
| Required size for BAR Alignment. More...

## Functions
XPciePsu_Config * | XPciePsu_LookupConfig (u16 DeviceId)
| This function looks for the configuration of PCIe from the configTable based on the unique device ID. More...
u32 | XPciePsu_CfgInitialize (XPciePsu *InstancePtr, const XPciePsu_Config *CfgPtr, UINTPTR EffectiveBrgAddress)
| This function initializes the config space and PCIe bridge. More...
u8 | XPciePsu_EnumerateBus (XPciePsu *InstancePtr)
| This function starts PCIe enumeration. More...
u8 | XPciePsu_ReadConfigSpace (XPciePsu *InstancePtr, u8 Bus, u8 Device, u8 Function, u16 Offset, u32 *DataPtr)
| This function read from remote configuration space location. More...
u8 | XPciePsu_WriteConfigSpace (XPciePsu *InstancePtr, u8 Bus, u8 Device, u8 Function, u16 Offset, u32 Data)
| This function write to remote configuration space location. More...
u8 | XPciePsu_ReadLocalConfigSpace (XPciePsu *InstancePtr, u16 Offset, u32 *DataPtr)
| Read 32-bit value from one of this IP own configuration space. More...
u8 | XPciePsu_WriteLocalConfigSpace (XPciePsu *InstancePtr, u16 Offset, u32 Data)
| Write 32-bit value to one of this IP own configuration space. More...
u32 | XPciePsu_ComposeExternalConfigAddress (u8 Bus, u8 Device, u8 Function, u16 Offset)
| This function Composes configuration space location. More...
u8 | XPciePsu_HasCapability (XPciePsu *InstancePtr, u8 Bus, u8 Device, u8 Function, u8 CapId)
| This function returns whether capability Id is available or not for the particular Function. More...
u8 | XPciePsu_PrintAllCapabilites (XPciePsu *InstancePtr, u8 Bus, u8 Device, u8 Function)
| This function prints all the available capabilities in the Function. More...
u32 | XPciePsu_ReadReg (UINTPTR BaseAddr, u32 RegOffset)
| This function reads a register value from specified offset. More...
void | XPciePsu_WriteReg (UINTPTR BaseAddr, u32 RegOffset, u32 Val)
| This function writes a register value to specified offset. More...

## Macro Definition Documentation

#define MAX_BARS 6

No BAR allocation for Bridge.

#define REQ_SIZE (MAX_BARS * sizeof(unsigned long))

Required size for BAR Alignment.

## Function Documentation

u32 XPciePsu_CfgInitialize | ( | XPciePsu * | InstancePtr,
|  | const XPciePsu_Config * | CfgPtr,
|  | UINTPTR | EffectiveBrgAddress
| ) |  |

This function initializes the config space and PCIe bridge.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer
  CfgPtr | pointer to XPciePsu_Config instrance Pointer.
  EffectiveBrgAddress | config brigReg address

Returns
  XST_SUCCESS on success err on failure

Referenced by PcieInitRootComplex().

u32 XPciePsu_ComposeExternalConfigAddress | ( | u8 | Bus,
|  | u8 | Device,
|  | u8 | Function,
|  | u16 | Offset
| ) |  |

This function Composes configuration space location.

Parameters

  Bus |
  Device |
  Function |
  Offset |

Returns
  location address of the composed address

References XPCIEPSU_ECAM_BUS_MASK, XPCIEPSU_ECAM_BUS_SHIFT, XPCIEPSU_ECAM_DEV_MASK, XPCIEPSU_ECAM_DEV_SHIFT, XPCIEPSU_ECAM_FUN_MASK, XPCIEPSU_ECAM_FUN_SHIFT, XPCIEPSU_ECAM_MASK, XPCIEPSU_ECAM_REG_MASK, and XPCIEPSU_ECAM_REG_SHIFT.

Referenced by XPciePsu_ReadConfigSpace(), and XPciePsu_WriteConfigSpace().

u8 XPciePsu_EnumerateBus | ( | XPciePsu * | InstancePtr | ) |

This function starts PCIe enumeration.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer

Returns
  1 if success 0 if fails

Referenced by main().

u8 XPciePsu_HasCapability | ( | XPciePsu * | InstancePtr,
|  | u8 | Bus,
|  | u8 | Device,
|  | u8 | Function,
|  | u8 | CapId
| ) |  |

This function returns whether capability Id is available or not for the particular Function.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer
  Bus | is the number of the Bus
  Device | is the number of the Device
  Function | is number of the Function
  cap | id to check capability pointer availability

Returns
  u32 0 if capability is not available 1 if capability is available

References XPciePsu_ReadConfigSpace().

XPciePsu_Config* XPciePsu_LookupConfig | ( | u16 | DeviceId | ) |

This function looks for the configuration of PCIe from the configTable based on the unique device ID.

The table XPciePsu_ConfigTable[] contains the configuration information for each device in the system.

Parameters

  DeviceId | is the unique device ID of the device being looked up.

Returns
  A pointer to the configuration table entry corresponding to the given device ID, or NULL if no match is found.

Referenced by PcieInitRootComplex(), and XPciePsu_InitEndPoint().

u8 XPciePsu_PrintAllCapabilites | ( | XPciePsu * | InstancePtr,
|  | u8 | Bus,
|  | u8 | Device,
|  | u8 | Function
| ) |  |

This function prints all the available capabilities in the Function.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer
  Bus | is the number of the Bus
  Device | is the number of the Device
  Function | is number of the Function

Returns
  XST_SUCCESS on success XST_FAILURE on failure.

References XPciePsu_ReadConfigSpace().

u8 XPciePsu_ReadConfigSpace | ( | XPciePsu * | InstancePtr,
|  | u8 | Bus,
|  | u8 | Device,
|  | u8 | Function,
|  | u16 | Offset,
|  | u32 * | DataPtr
| ) |  |

This function read from remote configuration space location.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer
  Bus |
  Device |
  Function |
  Offset | location of the address to read data from.
  DataPtr | pointer store date available in the offset

Returns
  XST_SUCCESS on success XST_FAILURE on failure.

References XPciePsu_ComposeExternalConfigAddress(), and XPciePsu_ReadReg().

Referenced by XPciePsu_HasCapability(), and XPciePsu_PrintAllCapabilites().

u8 XPciePsu_ReadLocalConfigSpace | ( | XPciePsu * | InstancePtr,
|  | u16 | Offset,
|  | u32 * | DataPtr
| ) |  |

Read 32-bit value from one of this IP own configuration space.

Location is identified by its offset from the beginning of the configuration space.

Parameters

  InstancePtr | is the XPciePsu instance to operate on.
  Offset | from beginning of IP own configuration space.
  DataPtr | is a pointer to a variable where the driver will pass back the value read from the specified location.

Returns
  XST_SUCCESS on success XST_FAILURE on failure.

Note
  None

References XPciePsu_ReadReg().

Referenced by PcieInitRootComplex().

u32 XPciePsu_ReadReg | ( | UINTPTR | BaseAddr,
|  | u32 | RegOffset
| ) |  |

This function reads a register value from specified offset.

Parameters

  BaseAddr | BaseAddr of the register
  RegOffset | Offset from the base address to be read

Returns
  Register value

Referenced by main(), XPciePsu_Egress_EP_BridgeInitialize(), XPciePsu_EP_BridgeInitialize(), XPciePsu_EP_IntrHandler(), XPciePsu_EP_SetupEgress(), XPciePsu_EP_SetupIngress(), XPciePsu_EP_WaitForEnumeration(), XPciePsu_EP_WaitForLinkup(), XPciePsu_ReadConfigSpace(), XPciePsu_ReadLocalConfigSpace(), and XPciePsu_WriteConfigSpace().

u8 XPciePsu_WriteConfigSpace | ( | XPciePsu * | InstancePtr,
|  | u8 | Bus,
|  | u8 | Device,
|  | u8 | Function,
|  | u16 | Offset,
|  | u32 | Data
| ) |  |

This function write to remote configuration space location.

Parameters

  InstancePtr | pointer to XPciePsu Instance Pointer
  Bus |
  Device |
  Function |
  Offset | location of the address to write data.
  Data | to be written on to the offset

Returns
  XST_SUCCESS on success XST_FAILURE on failure.

References XPciePsu_ComposeExternalConfigAddress(), XPciePsu_ReadReg(), and XPciePsu_WriteReg().

u8 XPciePsu_WriteLocalConfigSpace | ( | XPciePsu * | InstancePtr,
|  | u16 | Offset,
|  | u32 | Data
| ) |  |

Write 32-bit value to one of this IP own configuration space.

Location is identified by its offset from the beginning of the configuration space.

Parameters

  InstancePtr | is the PCIe component to operate on.
  Offset | from beggininng of IP own configuration space.
  Data | to be written to the specified location.

Returns
  XST_SUCCESS on success XST_FAILURE on failure.

Note
  This function is valid only when IP is configured as a root complex.

References XPciePsu_WriteReg().

Referenced by PcieInitRootComplex().

void XPciePsu_WriteReg | ( | UINTPTR | BaseAddr,
|  | u32 | RegOffset,
|  | u32 | Val
| ) |  |

This function writes a register value to specified offset.

Parameters

  BaseAddr | Base Address of the register
  RegOffset | Offset from the base address to be written
  Val | Value to be written

Returns
  none

Referenced by main(), XPciePsu_Egress_EP_BridgeInitialize(), XPciePsu_EP_BridgeInitialize(), XPciePsu_EP_IntrHandler(), XPciePsu_EP_SetupEgress(), XPciePsu_EP_SetupIngress(), XPciePsu_WriteConfigSpace(), and XPciePsu_WriteLocalConfigSpace().