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
	@driver_ops{PCIe Endpoint} More...

Typedefs
typedef void(*	pcie_ep_reset_callback_t) (void *arg)
	Callback API for PCIe reset interrupts.
typedef int(*	pcie_ep_api_conf_read) (const struct device *dev, uint32_t offset, uint32_t *data)
	@def_driverbackendgroup{PCIe Endpoint,pcie_interface}
typedef void(*	pcie_ep_api_conf_write) (const struct device *dev, uint32_t offset, uint32_t data)
	Type definition of PCIe EP API function for writing the configuration space.
typedef int(*	pcie_ep_api_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)
	Type definition of PCIe EP API function for mapping a Host address.
typedef void(*	pcie_ep_api_unmap_addr) (const struct device *dev, uint64_t mapped_addr)
	Type definition of PCIe EP API function for unmapping a Host address.
typedef int(*	pcie_ep_api_raise_irq) (const struct device *dev, enum pci_ep_irq_type irq_type, uint32_t irq_num)
	Type definition of PCIe EP API function for raising an interrupt to the Host.
typedef int(*	pcie_ep_api_register_reset_cb) (const struct device *dev, enum pcie_reset reset, pcie_ep_reset_callback_t cb, void *arg)
	Type definition of PCIe EP API function for registering a reset callback.
typedef int(*	pcie_ep_api_dma_xfer) (const struct device *dev, uint64_t mapped_addr, uintptr_t local_addr, uint32_t size, enum xfer_direction dir)
	Type definition of PCIe EP API function for data transfer using the system DMA.

Enumerations
enum	pcie_ob_mem_type { PCIE_OB_ANYMEM , PCIE_OB_LOWMEM , PCIE_OB_HIGHMEM }
	PCIe outbound memory address range type. More...
enum	pci_ep_irq_type { PCIE_EP_IRQ_LEGACY , PCIE_EP_IRQ_MSI , PCIE_EP_IRQ_MSIX }
	Type of interrupt raised to the Host. More...
enum	xfer_direction { HOST_TO_DEVICE , DEVICE_TO_HOST }
	Direction of data transfer between Host and endpoint device. More...
enum	pcie_reset { PCIE_PERST , PCIE_PERST_INB , PCIE_FLR , PCIE_RESET_MAX }
	PCIe reset interrupt type. More...

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_api_conf_read

typedef int(* pcie_ep_api_conf_read) (const struct device *dev, uint32_t offset, uint32_t *data)

@def_driverbackendgroup{PCIe Endpoint,pcie_interface}

Type definition of PCIe EP API function for reading the configuration space. See pcie_ep_conf_read() for argument descriptions.

pcie_ep_api_conf_write

typedef void(* pcie_ep_api_conf_write) (const struct device *dev, uint32_t offset, uint32_t data)

Type definition of PCIe EP API function for writing the configuration space.

See pcie_ep_conf_write() for argument descriptions.

pcie_ep_api_dma_xfer

typedef int(* pcie_ep_api_dma_xfer) (const struct device *dev, uint64_t mapped_addr, uintptr_t local_addr, uint32_t size, enum xfer_direction dir)

Type definition of PCIe EP API function for data transfer using the system DMA.

See pcie_ep_dma_xfer() for argument descriptions.

pcie_ep_api_map_addr

typedef int(* pcie_ep_api_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)

Type definition of PCIe EP API function for mapping a Host address.

See pcie_ep_map_addr() for argument descriptions.

pcie_ep_api_raise_irq

typedef int(* pcie_ep_api_raise_irq) (const struct device *dev, enum pci_ep_irq_type irq_type, uint32_t irq_num)

Type definition of PCIe EP API function for raising an interrupt to the Host.

See pcie_ep_raise_irq() for argument descriptions.

pcie_ep_api_register_reset_cb

typedef int(* pcie_ep_api_register_reset_cb) (const struct device *dev, enum pcie_reset reset, pcie_ep_reset_callback_t cb, void *arg)

Type definition of PCIe EP API function for registering a reset callback.

See pcie_ep_register_reset_cb() for argument descriptions.

pcie_ep_api_unmap_addr

typedef void(* pcie_ep_api_unmap_addr) (const struct device *dev, uint64_t mapped_addr)

Type definition of PCIe EP API function for unmapping a Host address.

See pcie_ep_unmap_addr() for argument descriptions.

pcie_ep_reset_callback_t

typedef void(* pcie_ep_reset_callback_t) (void *arg)

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

arg	Pointer provided at registration time, later to be passed back as argument to callback function

Enumeration Type Documentation

pci_ep_irq_type

enum pci_ep_irq_type

Type of interrupt raised to the Host.

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

enum pcie_ob_mem_type

PCIe outbound memory address range 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

PCIe reset interrupt type.

Enumerator
PCIE_PERST	Cold reset.
PCIE_PERST_INB	Inband hot reset.
PCIE_FLR	Functional Level Reset.
PCIE_RESET_MAX	Number of PCIe reset types.

xfer_direction

enum xfer_direction

Direction of data transfer between Host and endpoint device.

Enumerator
HOST_TO_DEVICE	Read from Host.
DEVICE_TO_HOST	Write to Host.

Function Documentation

pcie_ep_conf_read()

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

dev	Pointer to the device structure for the driver instance
offset	Offset within configuration space
data	Pointer to data read from the offset

Returns

0 if successful, negative errno code if failure.

pcie_ep_conf_write()

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

dev	Pointer to the device structure for the driver instance
offset	Offset within configuration space
data	Data to be written at the offset

pcie_ep_dma_xfer()

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

dev	Pointer to the device structure for the driver instance
mapped_addr	Mapped Host memory address
local_addr	Device memory address
size	DMA transfer length (bytes)
dir	Direction of DMA transfer

Returns

0 if successful, negative errno code if failure.

pcie_ep_map_addr()

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

dev	Pointer to the device structure for the driver instance
pcie_addr	Host memory buffer address to be mapped
mapped_addr	Mapped PCIe outbound region address
size	Host memory buffer size (bytes)
ob_mem_type	Hint 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 requester 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()

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

dev	Pointer to the device structure for the driver instance
irq_type	Type of Interrupt be raised (legacy, MSI or MSI-X)
irq_num	MSI or MSI-X interrupt number

Returns

0 if successful, negative errno code if failure.

pcie_ep_register_reset_cb()

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

dev	Pointer to the device structure for the driver instance
reset	Reset interrupt type
cb	Callback function being registered
arg	Argument to be passed back to callback function

Returns

0 if successful, negative errno code if failure.

pcie_ep_unmap_addr()

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

dev	Pointer to the device structure for the driver instance
mapped_addr	PCIe 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

dev	Pointer to the device structure for the driver instance
pcie_addr	Host memory buffer address
local_addr	Local memory buffer address
size	Data transfer size (bytes)
ob_mem_type	Hint if lowmem/highmem outbound region has to be used (PCIE_OB_LOWMEM / PCIE_OB_HIGHMEM / PCIE_OB_ANYMEM)
dir	Data 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

dev	Pointer to the device structure for the driver instance
pcie_addr	Host memory buffer address
local_addr	Local memory buffer address
size	Data transfer size (bytes)
ob_mem_type	Hint 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
dir	Data transfer direction (HOST_TO_DEVICE / DEVICE_TO_HOST)

Returns

0 if successful, negative errno code if failure.