# PCIE LLD Functions
[PCIE LLD Module API]

## Functions

pcieRet_e | Pcie_open (int deviceNum, Pcie_Handle *pHandle)
| Pcie_open creates/opens a PCIe instance.
pcieRet_e | Pcie_close (Pcie_Handle *pHandle)
| Pcie_close Closes (frees) the driver handle.
pcieRet_e | Pcie_readRegs (Pcie_Handle handle, pcieLocation_e location, pcieRegisters_t *readRegs)
| Pcie_readRegs Performs a register read.
pcieRet_e | Pcie_writeRegs (Pcie_Handle handle, pcieLocation_e location, pcieRegisters_t *writeRegs)
| Pcie_writeRegs Performs a configuration write.
pcieRet_e | Pcie_setMode (pcieMode_e mode)
| Pcie_setMode sets the PCI mode.
pcieRet_e | Pcie_getMemSpaceRange (Pcie_Handle handle, void **base, uint32_t *size)
| Pcie_getMemSpaceRange Returns the PCIe Internal Address Range for the device's internal address range 1, which is the Memory Space.
pcieRet_e | Pcie_cfgObOffset (Pcie_Handle handle, uint32_t obAddrLo, uint32_t obAddrHi, uint8_t region)
| Pcie_cfgObOffset Configures the Outbound Offset registers for outbound address translation.
pcieRet_e | Pcie_cfgIbTrans (Pcie_Handle handle, pcieIbTransCfg_t *ibCfg)
| Pcie_cfgIbTrans Configures the Inbound Address Translation registers.
pcieRet_e | Pcie_cfgBar (Pcie_Handle handle, pcieBarCfg_t *barCfg)
| Pcie_cfgBar is used to configure a 32bits BAR Register.
uint32_t | Pcie_getVersion (void)
| Pcie_getVersion returns the PCIE LLD version information.
const char * | Pcie_getVersionStr (void)
| Pcie_getVersionStr returns the PCIE LLD version string.

## Function Documentation

pcieRet_e Pcie_cfgBar | ( | Pcie_Handle | handle,
|  | pcieBarCfg_t * | barCfg |
| ) |  |  |

Pcie_cfgBar is used to configure a 32bits BAR Register.

A BAR register can represent any of the following:
(a) a 32bit BAR
(b) the lower 32bits of a 64bits BAR
(c) the upper 32bits of a 64bits BAR
(d) a BAR mask

BAR registers can always be accessed using Pcie_readRegs and/or Pcie_writeRegs.

Pcie_cfgBar is used to configure a 32bits BAR Register or the lower 32bits of a 64bits BAR register. That is, (a) and (b) above.

Pcie_cfgBar should NOT be used to configure the Upper 32bits of a 64bits BAR register (c).
Pcie_cfgBar should NOT be used to configure BAR masks (d).
In order to access BAR masks or Upper 32bits BAR, use Pcie_readRegs and/or Pcie_writeRegs to perform the actual 32bits register accesses, using pcieType0Bar32bitIdx_t (for a End point BAR) or pcieType1Bar32bitIdx_t (for a Root Complex BAR).

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[in]` | barCfg | BAR configuration parameters

pcieRet_e Pcie_cfgIbTrans | ( | Pcie_Handle | handle,
|  | pcieIbTransCfg_t * | ibCfg |
| ) |  |  |

Pcie_cfgIbTrans Configures the Inbound Address Translation registers.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[in]` | ibCfg | Inbound Address Translation Configuration parameters

pcieRet_e Pcie_cfgObOffset | ( | Pcie_Handle | handle,
|  | uint32_t | obAddrLo,
|  | uint32_t | obAddrHi,
|  | uint8_t | region |
| ) |  |  |

Pcie_cfgObOffset Configures the Outbound Offset registers for outbound address translation.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[in]` | obAddrLo | Low Outbound address offset (32bits)
  `[in]` | obAddrHi | High Outbound address offset (32bits)
  `[in]` | region | Identifies the Outbound region (0-7)

pcieRet_e Pcie_close | ( | Pcie_Handle * | pHandle | ) |

Pcie_close Closes (frees) the driver handle.

The handle is released. The peripheral itself is not modified.

Precondition:
  pHandle != NULL
  *pHandle == valid handle

Return values:

  | pcieRet_e | status

Postcondition:
  *pHandle == NULL

Parameters:

  `[in]` | pHandle | The PCIE LLD instance indentifier

pcieRet_e Pcie_getMemSpaceRange | ( | Pcie_Handle | handle,
|  | void ** | base,
|  | uint32_t * | size |
| ) |  |  |

Pcie_getMemSpaceRange Returns the PCIe Internal Address Range for the device's internal address range 1, which is the Memory Space.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[out]` | base | The memory space base address
  `[out]` | size | Total size of the memory space [bytes]

uint32_t Pcie_getVersion | ( | void |  | ) |

Pcie_getVersion returns the PCIE LLD version information.

This function is used to get the version information of the PCIE LLD in 0xAABBCCDD format. where Arch (AA); API Changes (BB); Major (CC); Minor (DD)

Return values:

  | 32-bit | version information

const char* Pcie_getVersionStr | ( | void |  | ) |

Pcie_getVersionStr returns the PCIE LLD version string.

This function is used to get the version string of the PCIE LLD.

Return values:

  | Version | string

pcieRet_e Pcie_open | ( | int | deviceNum,
|  | Pcie_Handle * | pHandle |
| ) |  |  |

Pcie_open creates/opens a PCIe instance.

This function creates a handle. The peripheral itself is not modified. More than one handle to the same PCIe peripheral can exist at the same time.

Precondition:
  pHandle != NULL
  *pHandle == NULL

Return values:

  | pcieRet_e | status

Postcondition:
  *pHandle == valid handle

Parameters:

  `[in]` | deviceNum | PCIe device number (0,1,...)
  `[out]` | pHandle | Resulting instance handle

pcieRet_e Pcie_readRegs | ( | Pcie_Handle | handle,
|  | pcieLocation_e | location,
|  | pcieRegisters_t * | readRegs |
| ) |  |  |

Pcie_readRegs Performs a register read.

Reads one or more of the device registers

Each non-NULL register pointer in readRegs will be read and broken into its fields.

Some registers have multiple instances (e.g. BAR registers, there is BAR0, BAR1, etc). In these cases an "index" is used to select which instance of the register will be accessed (e.g. use index 0 to access BAR0 and so on).

Registers that need an "index" input can only be read one index at a time. Also, "index" must be set by the code before issuing a read request.

It is the users responsibility to ensure that no other tasks or cores will modify the registers while they are read, or betwen the time the registers are read and they are later written back.

Since the peripheral is shared across the device, and even between peripherals, it is not expected to be dynamically reprogramed (such as between thread or task switches). It should only be reprogrammed at startup or when changing applications. Therefore, there is a single-entry API instead of a set of inlines since it is not time-critical code.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[in]` | location | Local or remote peripheral
  `[in,out]` | readRegs | List of registers to read

pcieRet_e Pcie_setMode | ( | pcieMode_e | mode | ) |

Pcie_setMode sets the PCI mode.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | mode | PCIE Mode

pcieRet_e Pcie_writeRegs | ( | Pcie_Handle | handle,
|  | pcieLocation_e | location,
|  | pcieRegisters_t * | writeRegs |
| ) |  |  |

Pcie_writeRegs Performs a configuration write.

Writes one or more of the device registers.

Each non-NULL register pointer in writeRegs will be writen.

Some registers have multiple instances (e.g. BAR registers, there is BAR0, BAR1, etc). In these cases an "index" is used to select which instance of the register will be accessed (e.g. use index 0 to access BAR0 and so on).

Registers that need an "index" input can only be written one index at a time.

It is the users responsibility to ensure that no other tasks or cores will modify the registers while they are read, or betwen the time the registers are read and they are later written back.

The user will typically use Pcie_readRegs to read the current values in the registers, modify them in the local copies, then write back using Pcie_writeRegs.

On exit, the actual written values are returned in each register's reg->raw.

Since the peripheral is shared across the device, and even between peripherals, it is not expected to be dynamically reprogramed (such as between thread or task switches). It should only be reprogrammed at startup or when changing applications. Therefore, there is a single-entry API instead of a set of inlines since it is not time-critical code.

Return values:

  | pcieRet_e | status

Parameters:

  `[in]` | handle | The PCIE LLD instance identifier
  `[in]` | location | Local or remote peripheral
  `[in]` | writeRegs | List of registers to write

Copyright 2012, Texas Instruments Incorporated