Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
pcie_ep.h File Reference

Public APIs for the PCIe EP drivers. More...

#include <zephyr/device.h>
#include <zephyr/init.h>
#include <zephyr/kernel.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  pcie_ep_driver_api
 

Typedefs

typedef void(* pcie_ep_reset_callback_t) (void *arg)
 Callback API for PCIe reset interrupts.
 

Enumerations

enum  pcie_ob_mem_type { PCIE_OB_ANYMEM , PCIE_OB_LOWMEM , PCIE_OB_HIGHMEM }
 
enum  pci_ep_irq_type { PCIE_EP_IRQ_LEGACY , PCIE_EP_IRQ_MSI , PCIE_EP_IRQ_MSIX }
 
enum  xfer_direction { HOST_TO_DEVICE , DEVICE_TO_HOST }
 
enum  pcie_reset { PCIE_PERST , PCIE_PERST_INB , PCIE_FLR , PCIE_RESET_MAX }
 

Functions

static int pcie_ep_conf_read (const struct device *dev, uint32_t offset, uint32_t *data)
 Read PCIe EP configuration space.
 
static void pcie_ep_conf_write (const struct device *dev, uint32_t offset, uint32_t data)
 Write PCIe EP configuration space.
 
static int pcie_ep_map_addr (const struct device *dev, uint64_t pcie_addr, uint64_t *mapped_addr, uint32_t size, enum pcie_ob_mem_type ob_mem_type)
 Map a host memory buffer to PCIe outbound region.
 
static void pcie_ep_unmap_addr (const struct device *dev, uint64_t mapped_addr)
 Remove mapping to PCIe outbound region.
 
static int pcie_ep_raise_irq (const struct device *dev, enum pci_ep_irq_type irq_type, uint32_t irq_num)
 Raise interrupt to Host.
 
static int pcie_ep_register_reset_cb (const struct device *dev, enum pcie_reset reset, pcie_ep_reset_callback_t cb, void *arg)
 Register callback function for reset interrupts.
 
static int pcie_ep_dma_xfer (const struct device *dev, uint64_t mapped_addr, uintptr_t local_addr, uint32_t size, const enum xfer_direction dir)
 Data transfer between mapped Host memory and device memory with "System DMA".
 
int pcie_ep_xfer_data_memcpy (const struct device *dev, uint64_t pcie_addr, uintptr_t *local_addr, uint32_t size, enum pcie_ob_mem_type ob_mem_type, enum xfer_direction dir)
 Data transfer using memcpy.
 
int pcie_ep_xfer_data_dma (const struct device *dev, uint64_t pcie_addr, uintptr_t *local_addr, uint32_t size, enum pcie_ob_mem_type ob_mem_type, enum xfer_direction dir)
 Data transfer using system DMA.
 

Detailed Description

Public APIs for the PCIe EP drivers.

Typedef Documentation

◆ pcie_ep_reset_callback_t

pcie_ep_reset_callback_t

Callback API for PCIe reset interrupts.

These callbacks execute in interrupt context. Therefore, use only interrupt-safe APIS. Registration of callbacks is done via pcie_ep_register_reset_cb

Parameters
argPointer provided at registration time, later to be passed back as argument to callback function

Enumeration Type Documentation

◆ pci_ep_irq_type

Enumerator
PCIE_EP_IRQ_LEGACY 

Raise Legacy interrupt.

PCIE_EP_IRQ_MSI 

Raise MSI interrupt.

PCIE_EP_IRQ_MSIX 

Raise MSIX interrupt.

◆ pcie_ob_mem_type

Enumerator
PCIE_OB_ANYMEM 

PCIe OB window within any address range.

PCIE_OB_LOWMEM 

PCIe OB window within 32-bit address range.

PCIE_OB_HIGHMEM 

PCIe OB window above 32-bit address range.

◆ pcie_reset

enum pcie_reset
Enumerator
PCIE_PERST 

Cold reset.

PCIE_PERST_INB 

Inband hot reset.

PCIE_FLR 

Functional Level Reset.

PCIE_RESET_MAX 

◆ xfer_direction

Enumerator
HOST_TO_DEVICE 

Read from Host.

DEVICE_TO_HOST 

Write to Host.

Function Documentation

◆ pcie_ep_conf_read()

static int pcie_ep_conf_read ( const struct device dev,
uint32_t  offset,
uint32_t data 
)
inlinestatic

Read PCIe EP configuration space.

This API reads EP's own configuration space

Parameters
devPointer to the device structure for the driver instance
offsetOffset within configuration space
dataPointer to data read from the offset
Returns
0 if successful, negative errno code if failure.

◆ pcie_ep_conf_write()

static void pcie_ep_conf_write ( const struct device dev,
uint32_t  offset,
uint32_t  data 
)
inlinestatic

Write PCIe EP configuration space.

This API writes EP's own configuration space

Parameters
devPointer to the device structure for the driver instance
offsetOffset within configuration space
dataData to be written at the offset

◆ pcie_ep_dma_xfer()

static int pcie_ep_dma_xfer ( const struct device dev,
uint64_t  mapped_addr,
uintptr_t  local_addr,
uint32_t  size,
const enum xfer_direction  dir 
)
inlinestatic

Data transfer between mapped Host memory and device memory with "System DMA".

The term "System DMA" is used to clarify that we are not talking about dedicated "PCIe DMA"; rather the one which does not understand PCIe address directly, and uses the mapped Host memory.

If DMA controller is available in the EP device, this API can be used to achieve data transfer between mapped Host memory, i.e. outbound memory and EP device's local memory with DMA

Parameters
devPointer to the device structure for the driver instance
mapped_addrMapped Host memory address
local_addrDevice memory address
sizeDMA transfer length (bytes)
dirDirection of DMA transfer
Returns
0 if successful, negative errno code if failure.

◆ pcie_ep_map_addr()

static int pcie_ep_map_addr ( const struct device dev,
uint64_t  pcie_addr,
uint64_t mapped_addr,
uint32_t  size,
enum pcie_ob_mem_type  ob_mem_type 
)
inlinestatic

Map a host memory buffer to PCIe outbound region.

This API maps a host memory buffer to PCIe outbound region, It is left to EP driver to manage multiple mappings through multiple PCIe outbound regions if supported by SoC

Parameters
devPointer to the device structure for the driver instance
pcie_addrHost memory buffer address to be mapped
mapped_addrMapped PCIe outbound region address
sizeHost memory buffer size (bytes)
ob_mem_typeHint if lowmem/highmem outbound region has to be used, this is useful in cases where bus master cannot generate more than 32-bit address; it becomes essential to use lowmem outbound region
Returns
Mapped size : If mapped size is less than requested size, then requestor has to call the same API again to map the unmapped host buffer after data transfer is done with mapped size. This situation may arise because of the mapping alignment requirements.
Negative errno code if failure.

◆ pcie_ep_raise_irq()

static int pcie_ep_raise_irq ( const struct device dev,
enum pci_ep_irq_type  irq_type,
uint32_t  irq_num 
)
inlinestatic

Raise interrupt to Host.

This API raises interrupt to Host

Parameters
devPointer to the device structure for the driver instance
irq_typeType of Interrupt be raised (legacy, MSI or MSI-X)
irq_numMSI or MSI-X interrupt number
Returns
0 if successful, negative errno code if failure.

◆ pcie_ep_register_reset_cb()

static int pcie_ep_register_reset_cb ( const struct device dev,
enum pcie_reset  reset,
pcie_ep_reset_callback_t  cb,
void *  arg 
)
inlinestatic

Register callback function for reset interrupts.

If reset interrupts are handled by device, this API can be used to register callback function, which will be executed part of corresponding PCIe reset handler

Parameters
devPointer to the device structure for the driver instance
resetReset interrupt type
cbCallback function being registered
argArgument to be passed back to callback function
Returns
0 if successful, negative errno code if failure.

◆ pcie_ep_unmap_addr()

static void pcie_ep_unmap_addr ( const struct device dev,
uint64_t  mapped_addr 
)
inlinestatic

Remove mapping to PCIe outbound region.

This API removes mapping to PCIe outbound region. Mapped PCIe outbound region address is given as argument to figure out the outbound region to be unmapped

Parameters
devPointer to the device structure for the driver instance
mapped_addrPCIe outbound region address

◆ pcie_ep_xfer_data_dma()

int pcie_ep_xfer_data_dma ( const struct device dev,
uint64_t  pcie_addr,
uintptr_t local_addr,
uint32_t  size,
enum pcie_ob_mem_type  ob_mem_type,
enum xfer_direction  dir 
)

Data transfer using system DMA.

Helper API to achieve data transfer with system DMA through PCIe outbound memory, this API is based off pcie_ep_xfer_data_memcpy, here we use "system dma" instead of memcpy

Parameters
devPointer to the device structure for the driver instance
pcie_addrHost memory buffer address
local_addrLocal memory buffer address
sizeData transfer size (bytes)
ob_mem_typeHint if lowmem/highmem outbound region has to be used (PCIE_OB_LOWMEM / PCIE_OB_HIGHMEM / PCIE_OB_ANYMEM)
dirData transfer direction (HOST_TO_DEVICE / DEVICE_TO_HOST)
Returns
0 if successful, negative errno code if failure.

◆ pcie_ep_xfer_data_memcpy()

int pcie_ep_xfer_data_memcpy ( const struct device dev,
uint64_t  pcie_addr,
uintptr_t local_addr,
uint32_t  size,
enum pcie_ob_mem_type  ob_mem_type,
enum xfer_direction  dir 
)

Data transfer using memcpy.

Helper API to achieve data transfer with memcpy through PCIe outbound memory

Parameters
devPointer to the device structure for the driver instance
pcie_addrHost memory buffer address
local_addrLocal memory buffer address
sizeData transfer size (bytes)
ob_mem_typeHint if lowmem/highmem outbound region has to be used (PCIE_OB_LOWMEM / PCIE_OB_HIGHMEM / PCIE_OB_ANYMEM), should be PCIE_OB_LOWMEM if bus master cannot generate more than 32-bit address
dirData transfer direction (HOST_TO_DEVICE / DEVICE_TO_HOST)
Returns
0 if successful, negative errno code if failure.