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