Encapsulated third-party dependencies. More...

Data Structures
struct	spdk_env_opts
	Environment initialization options. More...

struct	spdk_pci_addr

struct	spdk_pci_id

struct	spdk_pci_device

struct	spdk_pci_device::_spdk_pci_device_internal

struct	spdk_pci_device_provider

struct	spdk_mem_map_ops
	A function table to be implemented by each memory map. More...

struct	spdk_pci_event

Macros
#define	SPDK_ENV_NUMA_ID_ANY (-1)

#define	SPDK_ENV_SOCKET_ID_ANY (-1)

#define	SPDK_ENV_LCORE_ID_ANY (UINT32_MAX)

#define	SPDK_MALLOC_DMA 0x01
	Memory is dma-safe.

#define	SPDK_MALLOC_SHARE 0x02
	Memory is sharable across process boundaries.

#define	SPDK_MAX_MEMZONE_NAME_LEN 32

#define	SPDK_MAX_MEMPOOL_NAME_LEN 29

#define	SPDK_MEMZONE_NO_IOVA_CONTIG 0x00100000
	Memzone flags.

#define	SPDK_MEMPOOL_DEFAULT_CACHE_SIZE SIZE_MAX

#define	SPDK_ENV_FOREACH_CORE(i)

#define	SPDK_ENV_FOREACH_NUMA_ID(i)

#define	SPDK_VTOPHYS_ERROR (0xFFFFFFFFFFFFFFFFULL)

#define	SPDK_PCI_DRIVER_NEED_MAPPING 0x0001
	Device needs PCI BAR mapping (done with either IGB_UIO or VFIO)

#define	SPDK_PCI_DRIVER_WC_ACTIVATE 0x0002
	Device needs PCI BAR mapping with enabled write combining (wc)

#define	SPDK_PCI_DEVICE(vend, dev)

#define	SPDK_PCI_DRIVER_REGISTER(name, id_table, flags)

#define	SPDK_PCI_REGISTER_DEVICE_PROVIDER(name, provider)

Typedefs
typedef void	spdk_mempool_obj_cb_t(struct spdk_mempool mp, void opaque, void *obj, unsigned obj_idx)
	An object callback function for memory pool.

typedef void	spdk_mempool_mem_cb_t(struct spdk_mempool mp, void opaque, void *addr, uint64_t iova, size_t len, unsigned mem_idx)
	A memory chunk callback function for memory pool.

typedef int(*	thread_start_fn) (void *)

typedef int(*	spdk_pci_enum_cb) (void enum_ctx, struct spdk_pci_device dev)
	Callback for device attach handling.

typedef int(*	spdk_mem_map_notify_cb) (void cb_ctx, struct spdk_mem_map map, enum spdk_mem_map_notify_action action, void *vaddr, size_t size)

typedef int(*	spdk_mem_map_contiguous_translations) (uint64_t addr_1, uint64_t addr_2)

typedef void(*	spdk_pci_error_handler) (const void failure_addr, void ctx)

Enumerations
enum	spdk_ring_type { SPDK_RING_TYPE_SP_SC , SPDK_RING_TYPE_MP_SC , SPDK_RING_TYPE_MP_MC }

enum	spdk_mem_map_notify_action { SPDK_MEM_MAP_NOTIFY_REGISTER , SPDK_MEM_MAP_NOTIFY_UNREGISTER }

enum	spdk_pci_event_type { SPDK_UEVENT_ADD = 0 , SPDK_UEVENT_REMOVE = 1 }

Functions
	SPDK_STATIC_ASSERT (sizeof(struct spdk_env_opts)==128, "Incorrect size")

void *	spdk_malloc (size_t size, size_t align, uint64_t *unused, int numa_id, uint32_t flags)
	Allocate dma/sharable memory based on a given dma_flg.

void *	spdk_zmalloc (size_t size, size_t align, uint64_t *unused, int numa_id, uint32_t flags)
	Allocate dma/sharable memory based on a given dma_flg.

void *	spdk_realloc (void *buf, size_t size, size_t align)
	Resize a dma/sharable memory buffer with the given new size and alignment.

void	spdk_free (void *buf)
	Free buffer memory that was previously allocated with spdk_malloc() or spdk_zmalloc().

void	spdk_env_opts_init (struct spdk_env_opts *opts)
	Initialize the default value of opts.

int	spdk_env_init (const struct spdk_env_opts *opts)
	Initialize or reinitialize the environment library.

void	spdk_env_fini (void)
	Release any resources of the environment library that were allocated with spdk_env_init().

void *	spdk_dma_malloc (size_t size, size_t align, uint64_t *unused)
	Allocate a pinned memory buffer with the given size and alignment.

void *	spdk_dma_malloc_socket (size_t size, size_t align, uint64_t *unused, int numa_id)
	Allocate a pinned, memory buffer with the given size, alignment and socket id.

void *	spdk_dma_zmalloc (size_t size, size_t align, uint64_t *unused)
	Allocate a pinned memory buffer with the given size and alignment.

void *	spdk_dma_zmalloc_socket (size_t size, size_t align, uint64_t *unused, int numa_id)
	Allocate a pinned memory buffer with the given size, alignment and socket id.

void *	spdk_dma_realloc (void buf, size_t size, size_t align, uint64_t unused)
	Resize the allocated and pinned memory buffer with the given new size and alignment.

void	spdk_dma_free (void *buf)
	Free a memory buffer previously allocated, for example from spdk_dma_zmalloc().

void *	spdk_memzone_reserve (const char *name, size_t len, int numa_id, unsigned flags)
	Reserve a named, process shared memory zone with the given size, numa_id and flags.

void *	spdk_memzone_reserve_aligned (const char *name, size_t len, int numa_id, unsigned flags, unsigned align)
	Reserve a named, process shared memory zone with the given size, numa_id, flags and alignment.

void *	spdk_memzone_lookup (const char *name)
	Lookup the memory zone identified by the given name.

int	spdk_memzone_free (const char *name)
	Free the memory zone identified by the given name.

void	spdk_memzone_dump (FILE *f)
	Dump debug information about all memzones.

struct spdk_mempool *	spdk_mempool_create (const char *name, size_t count, size_t ele_size, size_t cache_size, int numa_id)
	Create a thread-safe memory pool.

struct spdk_mempool *	spdk_mempool_create_ctor (const char name, size_t count, size_t ele_size, size_t cache_size, int numa_id, spdk_mempool_obj_cb_t obj_init, void *obj_init_arg)
	Create a thread-safe memory pool with user provided initialization function and argument.

char *	spdk_mempool_get_name (struct spdk_mempool *mp)
	Get the name of a memory pool.

void	spdk_mempool_free (struct spdk_mempool *mp)
	Free a memory pool.

void *	spdk_mempool_get (struct spdk_mempool *mp)
	Get an element from a memory pool.

int	spdk_mempool_get_bulk (struct spdk_mempool mp, void *ele_arr, size_t count)
	Get multiple elements from a memory pool.

void	spdk_mempool_put (struct spdk_mempool mp, void ele)
	Put an element back into the memory pool.

void	spdk_mempool_put_bulk (struct spdk_mempool mp, void *ele_arr, size_t count)
	Put multiple elements back into the memory pool.

size_t	spdk_mempool_count (const struct spdk_mempool *pool)
	Get the number of entries in the memory pool.

uint32_t	spdk_mempool_obj_iter (struct spdk_mempool mp, spdk_mempool_obj_cb_t obj_cb, void obj_cb_arg)
	Iterate through all elements of the pool and call a function on each one.

uint32_t	spdk_mempool_mem_iter (struct spdk_mempool mp, spdk_mempool_mem_cb_t mem_cb, void mem_cb_arg)
	Iterate through all memory chunks of the pool and call a function on each one.

struct spdk_mempool *	spdk_mempool_lookup (const char *name)
	Lookup the memory pool identified by the given name.

uint32_t	spdk_env_get_core_count (void)
	Get the number of dedicated CPU cores utilized by this env abstraction.

uint32_t	spdk_env_get_current_core (void)
	Get the CPU core index of the current thread.

uint32_t	spdk_env_get_main_core (void)
	Get the index of the main dedicated CPU core for this application.

uint32_t	spdk_env_get_first_core (void)
	Get the index of the first dedicated CPU core for this application.

uint32_t	spdk_env_get_last_core (void)
	Get the index of the last dedicated CPU core for this application.

uint32_t	spdk_env_get_next_core (uint32_t prev_core)
	Get the index of the next dedicated CPU core for this application.

int32_t	spdk_env_get_numa_id (uint32_t core)
	Get the NUMA node ID for the given core.

uint32_t	spdk_env_get_socket_id (uint32_t core)
	Get the NUMA node ID for the given core.

int32_t	spdk_env_get_first_numa_id (void)
	Get the ID of the first NUMA node on this system.

int32_t	spdk_env_get_last_numa_id (void)
	Get the ID of the last NUMA node on this system.

int32_t	spdk_env_get_next_numa_id (int32_t prev_numa_id)
	Get the index of the next NUMA node on this system.

void	spdk_env_get_cpuset (struct spdk_cpuset *cpuset)
	Create a cpuset with each dedicated core's bit set to true.

bool	spdk_env_core_get_smt_cpuset (struct spdk_cpuset *cpuset, uint32_t core)
	Create a cpuset with each SMT sibling core's bit set to true.

int	spdk_env_thread_launch_pinned (uint32_t core, thread_start_fn fn, void *arg)
	Launch a thread pinned to the given core.

void	spdk_env_thread_wait_all (void)
	Wait for all threads to exit before returning.

bool	spdk_process_is_primary (void)
	Check whether the calling process is primary process.

uint64_t	spdk_get_ticks (void)
	Get a monotonic timestamp counter.

uint64_t	spdk_get_ticks_hz (void)
	Get the tick rate of spdk_get_ticks() per second.

void	spdk_delay_us (unsigned int us)
	Delay the given number of microseconds.

void	spdk_pause (void)
	Pause CPU execution for a short while.

struct spdk_ring *	spdk_ring_create (enum spdk_ring_type type, size_t count, int numa_id)
	Create a ring.

void	spdk_ring_free (struct spdk_ring *ring)
	Free the ring.

size_t	spdk_ring_count (struct spdk_ring *ring)
	Get the number of objects in the ring.

size_t	spdk_ring_enqueue (struct spdk_ring ring, void objs, size_t count, size_t free_space)
	Queue the array of objects (with length count) on the ring.

size_t	spdk_ring_dequeue (struct spdk_ring ring, void *objs, size_t count)
	Dequeue count objects from the ring into the array objs.

bool	spdk_iommu_is_enabled (void)
	Reports whether the SPDK application is using the IOMMU for DMA.

uint64_t	spdk_vtophys (const void buf, uint64_t size)
	Get the physical address of a buffer.

void	spdk_pci_driver_register (const char name, struct spdk_pci_id id_table, uint32_t flags)

struct spdk_pci_driver *	spdk_pci_vmd_get_driver (void)
	Get the VMD PCI driver object.

struct spdk_pci_driver *	spdk_pci_ioat_get_driver (void)
	Get the I/OAT PCI driver object.

struct spdk_pci_driver *	spdk_pci_idxd_get_driver (void)
	Get the IDXD PCI driver object.

struct spdk_pci_driver *	spdk_pci_virtio_get_driver (void)
	Get the Virtio PCI driver object.

struct spdk_pci_driver *	spdk_pci_get_driver (const char *name)
	Get PCI driver by name (e.g.

struct spdk_pci_driver *	spdk_pci_nvme_get_driver (void)
	Get the NVMe PCI driver object.

int	spdk_pci_enumerate (struct spdk_pci_driver driver, spdk_pci_enum_cb enum_cb, void enum_ctx)
	Enumerate all PCI devices supported by the provided driver and try to attach those that weren't attached yet.

void	spdk_pci_for_each_device (void ctx, void(fn)(void ctx, struct spdk_pci_device dev))
	Call the provided function pointer for every enumerated PCI device.

int	spdk_pci_device_map_bar (struct spdk_pci_device dev, uint32_t bar, void mapped_addr, uint64_t phys_addr, uint64_t *size)
	Map a PCI BAR in the current process.

int	spdk_pci_device_unmap_bar (struct spdk_pci_device dev, uint32_t bar, void mapped_addr)
	Unmap a PCI BAR from the current process.

int	spdk_pci_device_enable_interrupt (struct spdk_pci_device *dev)
	Enable PCI device interrupts.

int	spdk_pci_device_disable_interrupt (struct spdk_pci_device *dev)
	Disable PCI device interrupts.

int	spdk_pci_device_get_interrupt_efd (struct spdk_pci_device *dev)
	Get an event file descriptor associated with a PCI device interrupt.

int	spdk_pci_device_enable_interrupts (struct spdk_pci_device *dev, uint32_t efd_count)
	Enable PCI device interrupts, only if VFIO MSI-X is supported.

int	spdk_pci_device_disable_interrupts (struct spdk_pci_device *dev)
	Disable PCI device interrupts.

int	spdk_pci_device_get_interrupt_efd_by_index (struct spdk_pci_device *dev, uint32_t index)
	Get an event file descriptor associated with a PCI device, for a particular MSI-X index.

uint32_t	spdk_pci_device_get_domain (struct spdk_pci_device *dev)
	Get the domain of a PCI device.

uint8_t	spdk_pci_device_get_bus (struct spdk_pci_device *dev)
	Get the bus number of a PCI device.

uint8_t	spdk_pci_device_get_dev (struct spdk_pci_device *dev)
	Get the device number within the PCI bus the device is on.

uint8_t	spdk_pci_device_get_func (struct spdk_pci_device *dev)
	Get the particular function number represented by struct spdk_pci_device.

struct spdk_pci_addr	spdk_pci_device_get_addr (struct spdk_pci_device *dev)
	Get the full DomainBDF address of a PCI device.

uint16_t	spdk_pci_device_get_vendor_id (struct spdk_pci_device *dev)
	Get the vendor ID of a PCI device.

uint16_t	spdk_pci_device_get_device_id (struct spdk_pci_device *dev)
	Get the device ID of a PCI device.

uint16_t	spdk_pci_device_get_subvendor_id (struct spdk_pci_device *dev)
	Get the subvendor ID of a PCI device.

uint16_t	spdk_pci_device_get_subdevice_id (struct spdk_pci_device *dev)
	Get the subdevice ID of a PCI device.

struct spdk_pci_id	spdk_pci_device_get_id (struct spdk_pci_device *dev)
	Get the PCI ID of a PCI device.

int	spdk_pci_device_get_numa_id (struct spdk_pci_device *dev)
	Get the NUMA node the PCI device is on.

int	spdk_pci_device_get_socket_id (struct spdk_pci_device *dev)
	Get the NUMA node the PCI device is on.

int	spdk_pci_device_get_serial_number (struct spdk_pci_device dev, char sn, size_t len)
	Serialize the PCIe Device Serial Number into the provided buffer.

int	spdk_pci_device_claim (struct spdk_pci_device *dev)
	Claim a PCI device for exclusive SPDK userspace access.

void	spdk_pci_device_unclaim (struct spdk_pci_device *dev)
	Undo spdk_pci_device_claim().

void	spdk_pci_device_detach (struct spdk_pci_device *device)
	Release all resources associated with the given device and detach it.

int	spdk_pci_device_attach (struct spdk_pci_driver driver, spdk_pci_enum_cb enum_cb, void enum_ctx, struct spdk_pci_addr *pci_address)
	Attach a PCI device.

int	spdk_pci_device_allow (struct spdk_pci_addr *pci_addr)
	Allow the specified PCI device to be probed by the calling process.

int	spdk_pci_device_cfg_read (struct spdk_pci_device dev, void buf, uint32_t len, uint32_t offset)
	Read `len` bytes from the PCI configuration space.

int	spdk_pci_device_cfg_write (struct spdk_pci_device dev, void buf, uint32_t len, uint32_t offset)
	Write `len` bytes into the PCI configuration space.

int	spdk_pci_device_cfg_read8 (struct spdk_pci_device dev, uint8_t value, uint32_t offset)
	Read 1 byte from the PCI configuration space.

int	spdk_pci_device_cfg_write8 (struct spdk_pci_device *dev, uint8_t value, uint32_t offset)
	Write 1 byte into the PCI configuration space.

int	spdk_pci_device_cfg_read16 (struct spdk_pci_device dev, uint16_t value, uint32_t offset)
	Read 2 bytes from the PCI configuration space.

int	spdk_pci_device_cfg_write16 (struct spdk_pci_device *dev, uint16_t value, uint32_t offset)
	Write 2 bytes into the PCI configuration space.

int	spdk_pci_device_cfg_read32 (struct spdk_pci_device dev, uint32_t value, uint32_t offset)
	Read 4 bytes from the PCI configuration space.

int	spdk_pci_device_cfg_write32 (struct spdk_pci_device *dev, uint32_t value, uint32_t offset)
	Write 4 bytes into the PCI configuration space.

bool	spdk_pci_device_is_removed (struct spdk_pci_device *dev)
	Check if device was requested to be removed from the process.

int	spdk_pci_addr_compare (const struct spdk_pci_addr a1, const struct spdk_pci_addr a2)
	Compare two PCI addresses.

int	spdk_pci_addr_parse (struct spdk_pci_addr addr, const char bdf)
	Convert a string representation of a PCI address into a struct spdk_pci_addr.

int	spdk_pci_addr_fmt (char bdf, size_t sz, const struct spdk_pci_addr addr)
	Convert a struct spdk_pci_addr to a string.

int	spdk_pci_hook_device (struct spdk_pci_driver drv, struct spdk_pci_device dev)
	Hook a custom PCI device into the PCI layer.

void	spdk_pci_unhook_device (struct spdk_pci_device *dev)
	Un-hook a custom PCI device from the PCI layer.

const char *	spdk_pci_device_get_type (const struct spdk_pci_device *dev)
	Return the type of the PCI device.

void	spdk_pci_register_device_provider (struct spdk_pci_device_provider *provider)
	Register a PCI device provdier.

void	spdk_unaffinitize_thread (void)
	Remove any CPU affinity from the current thread.

void *	spdk_call_unaffinitized (void cb(void arg), void *arg)
	Call a function with CPU affinity unset.

struct spdk_mem_map *	spdk_mem_map_alloc (uint64_t default_translation, const struct spdk_mem_map_ops ops, void cb_ctx)
	Allocate a virtual memory address translation map.

void	spdk_mem_map_free (struct spdk_mem_map **pmap)
	Free a memory map previously allocated by spdk_mem_map_alloc().

int	spdk_mem_map_set_translation (struct spdk_mem_map *map, uint64_t vaddr, uint64_t size, uint64_t translation)
	Register an address translation for a range of virtual memory.

int	spdk_mem_map_clear_translation (struct spdk_mem_map *map, uint64_t vaddr, uint64_t size)
	Unregister an address translation.

uint64_t	spdk_mem_map_translate (const struct spdk_mem_map map, uint64_t vaddr, uint64_t size)
	Look up the translation of a virtual address in a memory map.

int	spdk_mem_register (void *vaddr, size_t len)
	Register the specified memory region for address translation.

int	spdk_mem_unregister (void *vaddr, size_t len)
	Unregister the specified memory region from vtophys address translation.

int	spdk_mem_reserve (void *vaddr, size_t len)
	Reserve the address space specified in all memory maps.

int32_t	spdk_mem_get_numa_id (const void buf, uint64_t size)
	Get the NUMA node ID for the specified memory buffer.

int	spdk_mem_get_fd_and_offset (void vaddr, uint64_t offset)
	Get the address's file descriptor and offset, it works with spdk memory allocation APIs.

int	spdk_pci_event_listen (void)
	Begin listening for PCI bus events.

int	spdk_pci_get_event (int fd, struct spdk_pci_event *event)
	Get the next PCI bus event.

int	spdk_pci_register_error_handler (spdk_pci_error_handler sighandler, void *ctx)
	Register a signal handler to handle bus errors on the PCI bus.

void	spdk_pci_unregister_error_handler (spdk_pci_error_handler sighandler)
	Register a signal handler to handle bus errors on the PCI bus.

int	spdk_get_tid (void)
	Get the tid of the current thread.

Detailed Description

Encapsulated third-party dependencies.

Macro Definition Documentation

◆ SPDK_ENV_FOREACH_CORE

#define SPDK_ENV_FOREACH_CORE ( i )

Value:

        for (i = spdk_env_get_first_core();     \
             i < UINT32_MAX;                    \
             i = spdk_env_get_next_core(i))

◆ SPDK_ENV_FOREACH_NUMA_ID

#define SPDK_ENV_FOREACH_NUMA_ID ( i )

Value:

        for (i = spdk_env_get_first_numa_id();          \
             i < INT32_MAX;                             \
             i = spdk_env_get_next_numa_id(i))

◆ SPDK_MEMZONE_NO_IOVA_CONTIG

#define SPDK_MEMZONE_NO_IOVA_CONTIG 0x00100000

Memzone flags.

no iova contiguity

◆ SPDK_PCI_DEVICE

#define SPDK_PCI_DEVICE	(		vend,
			dev )

Value:

        .class_id = SPDK_PCI_CLASS_ANY_ID,      \
        .vendor_id = (vend),                    \
        .device_id = (dev),                     \
        .subvendor_id = SPDK_PCI_ANY_ID,        \
        .subdevice_id = SPDK_PCI_ANY_ID

◆ SPDK_PCI_DRIVER_REGISTER

#define SPDK_PCI_DRIVER_REGISTER	(	name,
		id_table,
		flags )

Value:

__attribute__((constructor)) static void _spdk_pci_driver_register_##name(void) \
{ \
        spdk_pci_driver_register(#name, id_table, flags); \
}

◆ SPDK_PCI_REGISTER_DEVICE_PROVIDER

#define SPDK_PCI_REGISTER_DEVICE_PROVIDER	(		name,
			provider )

Value:

        static void __attribute__((constructor)) _spdk_pci_register_device_provider_##name(void) \
        { \
                spdk_pci_register_device_provider(provider); \
        }

Typedef Documentation

◆ spdk_mempool_mem_cb_t

typedef void spdk_mempool_mem_cb_t(struct spdk_mempool *mp, void *opaque, void *addr, uint64_t iova, size_t len, unsigned mem_idx)

A memory chunk callback function for memory pool.

Used by spdk_mempool_mem_iter().

◆ spdk_mempool_obj_cb_t

typedef void spdk_mempool_obj_cb_t(struct spdk_mempool *mp, void *opaque, void *obj, unsigned obj_idx)

An object callback function for memory pool.

Used by spdk_mempool_create_ctor().

◆ spdk_pci_enum_cb

typedef int(* spdk_pci_enum_cb) (void *enum_ctx, struct spdk_pci_device *dev)

Callback for device attach handling.

Parameters

enum_ctx	Opaque value.
dev	PCI device.

Returns: -1 if an error occurred, 0 if device attached successfully, 1 if device not attached.

Function Documentation

◆ spdk_call_unaffinitized()

void * spdk_call_unaffinitized	(	void *	cbvoid *arg,
		void *	arg )

Call a function with CPU affinity unset.

This can be used to run a function that creates other threads without inheriting the calling thread's CPU affinity.

Parameters

cb	Function to call
arg	Parameter to the function cb().

Returns: the return value of cb().

◆ spdk_delay_us()

void spdk_delay_us ( unsigned int us )

Delay the given number of microseconds.

Parameters

us	Number of microseconds.

◆ spdk_dma_free()

void spdk_dma_free ( void * buf )

Free a memory buffer previously allocated, for example from spdk_dma_zmalloc().

This call is never made from the performance path.

Parameters

buf	Buffer to free.

◆ spdk_dma_malloc()

void * spdk_dma_malloc	(	size_t	size,
		size_t	align,
		uint64_t *	unused )

Allocate a pinned memory buffer with the given size and alignment.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.

Returns: a pointer to the allocated memory buffer.

◆ spdk_dma_malloc_socket()

void * spdk_dma_malloc_socket	(	size_t	size,
		size_t	align,
		uint64_t *	unused,
		int	numa_id )

Allocate a pinned, memory buffer with the given size, alignment and socket id.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.

Returns: a pointer to the allocated memory buffer.

◆ spdk_dma_realloc()

void * spdk_dma_realloc	(	void *	buf,
		size_t	size,
		size_t	align,
		uint64_t *	unused )

Resize the allocated and pinned memory buffer with the given new size and alignment.

Existing contents are preserved.

Parameters

buf	Buffer to resize.
size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.

Returns: a pointer to the resized memory buffer.

◆ spdk_dma_zmalloc()

void * spdk_dma_zmalloc	(	size_t	size,
		size_t	align,
		uint64_t *	unused )

Allocate a pinned memory buffer with the given size and alignment.

The buffer will be zeroed.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.

Returns: a pointer to the allocated memory buffer.

◆ spdk_dma_zmalloc_socket()

void * spdk_dma_zmalloc_socket	(	size_t	size,
		size_t	align,
		uint64_t *	unused,
		int	numa_id )

Allocate a pinned memory buffer with the given size, alignment and socket id.

The buffer will be zeroed.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.

Returns: a pointer to the allocated memory buffer.

◆ spdk_env_core_get_smt_cpuset()

bool spdk_env_core_get_smt_cpuset	(	struct spdk_cpuset *	cpuset,
		uint32_t	core )

Create a cpuset with each SMT sibling core's bit set to true.

This function will first zero the cpuset and then set the bit for each SMT sibling core to true.

If the specified core has no SMT siblings, then only the specified core's bit will be set.

If the specified core has SMT siblings, then all of the siblings, including the specified core, will be set. Note: this will set bits for all siblings, even ones not part of the application's core mask.

If the specified core is UINT32_MAX, then bits will be set for all SMT siblings of all cores in the application's core mask.

Parameters

cpuset	spdk_cpuset for SMT sibling cores
core	core to get siblings for (UINT32_MAX for all cores in app core mask)

Returns: true if environment supports SMT detection, false otherwise (in which case the spdk_cpuset will be invalid)

◆ spdk_env_fini()

void spdk_env_fini ( void )

Release any resources of the environment library that were allocated with spdk_env_init().

After this call, no SPDK env function calls may be made. It is expected that common usage of this function is to call it just before terminating the process or before reinitializing the environment library within the same process.

◆ spdk_env_get_core_count()

uint32_t spdk_env_get_core_count ( void )

Get the number of dedicated CPU cores utilized by this env abstraction.

Returns: the number of dedicated CPU cores.

◆ spdk_env_get_cpuset()

void spdk_env_get_cpuset ( struct spdk_cpuset * cpuset )

Create a cpuset with each dedicated core's bit set to true.

This function will first zero the cpuset and then set the bit for each core dedicated to this application to true.

Parameters

cpuset spdk_cpuset to initialize

◆ spdk_env_get_current_core()

uint32_t spdk_env_get_current_core ( void )

Get the CPU core index of the current thread.

This will only function when called from threads set up by this environment abstraction. For any other threads SPDK_ENV_LCORE_ID_ANY will be returned.

Returns: the CPU core index of the current thread.

◆ spdk_env_get_first_core()

uint32_t spdk_env_get_first_core ( void )

Get the index of the first dedicated CPU core for this application.

Returns: the index of the first dedicated CPU core.

◆ spdk_env_get_first_numa_id()

int32_t spdk_env_get_first_numa_id ( void )

Get the ID of the first NUMA node on this system.

Returns: the ID of the first NUMA node

◆ spdk_env_get_last_core()

uint32_t spdk_env_get_last_core ( void )

Get the index of the last dedicated CPU core for this application.

Returns: the index of the last dedicated CPU core.

◆ spdk_env_get_last_numa_id()

int32_t spdk_env_get_last_numa_id ( void )

Get the ID of the last NUMA node on this system.

Returns: the ID of the last NUMA node

◆ spdk_env_get_main_core()

uint32_t spdk_env_get_main_core ( void )

Get the index of the main dedicated CPU core for this application.

Returns: the index of the main dedicated CPU core.

◆ spdk_env_get_next_core()

uint32_t spdk_env_get_next_core ( uint32_t prev_core )

Get the index of the next dedicated CPU core for this application.

If there is no next core, return UINT32_MAX.

Parameters

prev_core Index of previous core.

Returns: the index of the next dedicated CPU core.

◆ spdk_env_get_next_numa_id()

int32_t spdk_env_get_next_numa_id ( int32_t prev_numa_id )

Get the index of the next NUMA node on this system.

If there is no next NUMA ID, or the passed prev_numa_id is not a valid NUMA ID, return INT32_MAX.

Parameters

prev_numa_id Index of previous NUMA ID.

Returns: the index of the next NUMA ID, or INT32_MAX if there is no next one

◆ spdk_env_get_numa_id()

int32_t spdk_env_get_numa_id ( uint32_t core )

Get the NUMA node ID for the given core.

Parameters

core	CPU core to query.

Returns: the NUMA node ID for the given core.

◆ spdk_env_get_socket_id()

uint32_t spdk_env_get_socket_id ( uint32_t core )

Get the NUMA node ID for the given core.

Deprecated, use spdk_env_get_numa_id() instead.

Parameters

core	CPU core to query.

Returns: the NUMA node ID for the given core.

◆ spdk_env_init()

int spdk_env_init ( const struct spdk_env_opts * opts )

Initialize or reinitialize the environment library.

For initialization, this must be called prior to using any other functions in this library. For reinitialization, the parameter opts must be set to NULL and this must be called after the environment library was finished by spdk_env_fini() within the same process.

Parameters

opts	Environment initialization options.

Returns: 0 on success, or negative errno on failure.

◆ spdk_env_opts_init()

void spdk_env_opts_init ( struct spdk_env_opts * opts )

Initialize the default value of opts.

Parameters

opts	Data structure where SPDK will initialize the default options.

◆ spdk_env_thread_launch_pinned()

int spdk_env_thread_launch_pinned	(	uint32_t	core,
		thread_start_fn	fn,
		void *	arg )

Launch a thread pinned to the given core.

Only a single pinned thread may be launched per core. Subsequent attempts to launch pinned threads on that core will fail.

Parameters

core	The core to pin the thread to.
fn	Entry point on the new thread.
arg	Argument passed to thread_start_fn

Returns: 0 on success, negative errno on failure.

◆ spdk_free()

void spdk_free ( void * buf )

Free buffer memory that was previously allocated with spdk_malloc() or spdk_zmalloc().

Parameters

buf	Buffer to free.

◆ spdk_get_ticks()

uint64_t spdk_get_ticks ( void )

Get a monotonic timestamp counter.

Returns: the monotonic timestamp counter.

◆ spdk_get_ticks_hz()

uint64_t spdk_get_ticks_hz ( void )

Get the tick rate of spdk_get_ticks() per second.

Returns: the tick rate of spdk_get_ticks() per second.

◆ spdk_iommu_is_enabled()

bool spdk_iommu_is_enabled ( void )

Reports whether the SPDK application is using the IOMMU for DMA.

Returns: True if we are using the IOMMU, false otherwise.

◆ spdk_malloc()

void * spdk_malloc	(	size_t	size,
		size_t	align,
		uint64_t *	unused,
		int	numa_id,
		uint32_t	flags )

Allocate dma/sharable memory based on a given dma_flg.

It is a memory buffer with the given size, alignment and socket id.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.
flags	Combination of SPDK_MALLOC flags (SPDK_MALLOC_DMA, SPDK_MALLOC_SHARE). At least one flag must be specified.

Returns: a pointer to the allocated memory buffer.

◆ spdk_mem_get_fd_and_offset()

int spdk_mem_get_fd_and_offset	(	void *	vaddr,
		uint64_t *	offset )

Get the address's file descriptor and offset, it works with spdk memory allocation APIs.

Parameters

vaddr	Virtual address to get
offset	Virtual address's map offset to the file descriptor

Returns: negative errno on failure, otherwise return the file descriptor

◆ spdk_mem_get_numa_id()

int32_t spdk_mem_get_numa_id	(	const void *	buf,
		uint64_t *	size )

Get the NUMA node ID for the specified memory buffer.

Note: this only works for memory allocated via the environment layer.

Parameters

buf	A pointer to a buffer.
size	Contains the size of the memory region pointed to by vaddr. If vaddr is successfully translated, then this is updated with the size of the memory region for which the translation is valid.

Returns: NUMA ID of the buffer if known, SPDK_ENV_NUMA_ID_ANY otherwise

◆ spdk_mem_map_alloc()

struct spdk_mem_map * spdk_mem_map_alloc	(	uint64_t	default_translation,
		const struct spdk_mem_map_ops *	ops,
		void *	cb_ctx )

Allocate a virtual memory address translation map.

Parameters

default_translation	Default translation for the map.
ops	Table of callback functions for map operations.
cb_ctx	Argument passed to the callback function.

Returns: a pointer to the allocated virtual memory address translation map.

◆ spdk_mem_map_clear_translation()

int spdk_mem_map_clear_translation	(	struct spdk_mem_map *	map,
		uint64_t	vaddr,
		uint64_t	size )

Unregister an address translation.

Parameters

map	Memory map.
vaddr	Virtual address of the region to unregister - must be 2 MB aligned.
size	Size of the region in bytes - must be multiple of 2 MB in the current implementation.

See also: spdk_mem_map_set_translation().

Returns: 0 on success, negative errno on failure.

◆ spdk_mem_map_free()

void spdk_mem_map_free ( struct spdk_mem_map ** pmap )

Free a memory map previously allocated by spdk_mem_map_alloc().

Parameters

pmap	Memory map to free.

◆ spdk_mem_map_set_translation()

int spdk_mem_map_set_translation	(	struct spdk_mem_map *	map,
		uint64_t	vaddr,
		uint64_t	size,
		uint64_t	translation )

Register an address translation for a range of virtual memory.

Parameters

map	Memory map.
vaddr	Virtual address of the region to register - must be 2 MB aligned.
size	Size of the region in bytes - must be multiple of 2 MB in the current implementation.
translation	Translation to store in the map for this address range.

See also: spdk_mem_map_clear_translation().

Returns: 0 on success, negative errno on failure.

◆ spdk_mem_map_translate()

uint64_t spdk_mem_map_translate	(	const struct spdk_mem_map *	map,
		uint64_t	vaddr,
		uint64_t *	size )

Look up the translation of a virtual address in a memory map.

Parameters

map	Memory map.
vaddr	Virtual address.
size	Contains the size of the memory region pointed to by vaddr. If vaddr is successfully translated, then this is updated with the size of the memory region for which the translation is valid.

Returns: the translation of vaddr stored in the map, or default_translation as specified in spdk_mem_map_alloc() if vaddr is not present in the map.

◆ spdk_mem_register()

int spdk_mem_register	(	void *	vaddr,
		size_t	len )

Register the specified memory region for address translation.

The memory region must map to pinned huge pages (2MB or greater).

Parameters

vaddr	Virtual address to register.
len	Length in bytes of the vaddr.

Returns: 0 on success, negative errno on failure.

◆ spdk_mem_reserve()

int spdk_mem_reserve	(	void *	vaddr,
		size_t	len )

Reserve the address space specified in all memory maps.

This pre-allocates the necessary space in the memory maps such that future calls to spdk_mem_register() on that region require no internal memory allocations.

Parameters

vaddr	Virtual address to reserve
len	Length in bytes of vaddr

Returns: 0 on success, negated errno on failure.

◆ spdk_mem_unregister()

int spdk_mem_unregister	(	void *	vaddr,
		size_t	len )

Unregister the specified memory region from vtophys address translation.

The caller must ensure all in-flight DMA operations to this memory region are completed or cancelled before calling this function.

Parameters

vaddr	Virtual address to unregister.
len	Length in bytes of the vaddr.

Returns: 0 on success, negative errno on failure.

◆ spdk_mempool_count()

size_t spdk_mempool_count ( const struct spdk_mempool * pool )

Get the number of entries in the memory pool.

Parameters

pool	Memory pool to query.

Returns: the number of entries in the memory pool.

◆ spdk_mempool_create()

struct spdk_mempool * spdk_mempool_create	(	const char *	name,
		size_t	count,
		size_t	ele_size,
		size_t	cache_size,
		int	numa_id )

Create a thread-safe memory pool.

Parameters

name	Name for the memory pool.
count	Count of elements.
ele_size	Element size in bytes.
cache_size	How many elements may be cached in per-core caches. Use SPDK_MEMPOOL_DEFAULT_CACHE_SIZE for a reasonable default, or 0 for no per-core cache.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.

Returns: a pointer to the created memory pool.

◆ spdk_mempool_create_ctor()

struct spdk_mempool * spdk_mempool_create_ctor	(	const char *	name,
		size_t	count,
		size_t	ele_size,
		size_t	cache_size,
		int	numa_id,
		spdk_mempool_obj_cb_t *	obj_init,
		void *	obj_init_arg )

Create a thread-safe memory pool with user provided initialization function and argument.

Parameters

name	Name for the memory pool.
count	Count of elements.
ele_size	Element size in bytes.
cache_size	How many elements may be cached in per-core caches. Use SPDK_MEMPOOL_DEFAULT_CACHE_SIZE for a reasonable default, or 0 for no per-core cache.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.
obj_init	User provided object callback initialization function.
obj_init_arg	User provided callback initialization function argument.

Returns: a pointer to the created memory pool.

◆ spdk_mempool_get()

void * spdk_mempool_get ( struct spdk_mempool * mp )

Get an element from a memory pool.

If no elements remain, return NULL.

Parameters

mp	Memory pool to query.

Returns: a pointer to the element.

◆ spdk_mempool_get_bulk()

int spdk_mempool_get_bulk	(	struct spdk_mempool *	mp,
		void **	ele_arr,
		size_t	count )

Get multiple elements from a memory pool.

Parameters

mp	Memory pool to get multiple elements from.
ele_arr	Array of the elements to fill.
count	Count of elements to get.

Returns: 0 on success, negative errno on failure.

◆ spdk_mempool_get_name()

char * spdk_mempool_get_name ( struct spdk_mempool * mp )

Get the name of a memory pool.

Parameters

mp	Memory pool to query.

Returns: the name of the memory pool.

◆ spdk_mempool_lookup()

struct spdk_mempool * spdk_mempool_lookup ( const char * name )

Lookup the memory pool identified by the given name.

Parameters

name	Name of the memory pool.

Returns: a pointer to the memory pool on success, or NULL on failure.

◆ spdk_mempool_mem_iter()

uint32_t spdk_mempool_mem_iter	(	struct spdk_mempool *	mp,
		spdk_mempool_mem_cb_t	mem_cb,
		void *	mem_cb_arg )

Iterate through all memory chunks of the pool and call a function on each one.

Parameters

mp	Memory pool to iterate on.
mem_cb	Function to call on each memory chunk.
mem_cb_arg	Opaque pointer passed to the callback function.

Returns: Number of memory chunks iterated.

◆ spdk_mempool_obj_iter()

uint32_t spdk_mempool_obj_iter	(	struct spdk_mempool *	mp,
		spdk_mempool_obj_cb_t	obj_cb,
		void *	obj_cb_arg )

Iterate through all elements of the pool and call a function on each one.

Parameters

mp	Memory pool to iterate on.
obj_cb	Function to call on each element.
obj_cb_arg	Opaque pointer passed to the callback function.

Returns: Number of elements iterated.

◆ spdk_mempool_put()

void spdk_mempool_put	(	struct spdk_mempool *	mp,
		void *	ele )

Put an element back into the memory pool.

Parameters

mp	Memory pool to put element back into.
ele	Element to put.

◆ spdk_mempool_put_bulk()

void spdk_mempool_put_bulk	(	struct spdk_mempool *	mp,
		void **	ele_arr,
		size_t	count )

Put multiple elements back into the memory pool.

Parameters

mp	Memory pool to put multiple elements back into.
ele_arr	Array of the elements to put.
count	Count of elements to put.

◆ spdk_memzone_dump()

void spdk_memzone_dump ( FILE * f )

Dump debug information about all memzones.

Parameters

f	File to write debug information to.

◆ spdk_memzone_free()

int spdk_memzone_free ( const char * name )

Free the memory zone identified by the given name.

Returns: 0 on success, -1 on failure.

◆ spdk_memzone_lookup()

void * spdk_memzone_lookup ( const char * name )

Lookup the memory zone identified by the given name.

Parameters

name	Name of the memory zone.

Returns: a pointer to the reserved memory address on success, or NULL on failure.

◆ spdk_memzone_reserve()

void * spdk_memzone_reserve	(	const char *	name,
		size_t	len,
		int	numa_id,
		unsigned	flags )

Reserve a named, process shared memory zone with the given size, numa_id and flags.

Unless SPDK_MEMZONE_NO_IOVA_CONTIG flag is provided, the returned memory will be IOVA contiguous.

Parameters

name	Name to set for this memory zone.
len	Length in bytes.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.
flags	Flags to set for this memory zone.

Returns: a pointer to the allocated memory address on success, or NULL on failure.

◆ spdk_memzone_reserve_aligned()

void * spdk_memzone_reserve_aligned	(	const char *	name,
		size_t	len,
		int	numa_id,
		unsigned	flags,
		unsigned	align )

Reserve a named, process shared memory zone with the given size, numa_id, flags and alignment.

Unless SPDK_MEMZONE_NO_IOVA_CONTIG flag is provided, the returned memory will be IOVA contiguous.

Parameters

name	Name to set for this memory zone.
len	Length in bytes.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.
flags	Flags to set for this memory zone.
align	Alignment for resulting memzone. Must be a power of 2.

Returns: a pointer to the allocated memory address on success, or NULL on failure.

◆ spdk_pci_addr_compare()

int spdk_pci_addr_compare	(	const struct spdk_pci_addr *	a1,
		const struct spdk_pci_addr *	a2 )

Compare two PCI addresses.

Parameters

a1	PCI address 1.
a2	PCI address 2.

Returns: 0 if a1 == a2, less than 0 if a1 < a2, greater than 0 if a1 > a2

◆ spdk_pci_addr_fmt()

int spdk_pci_addr_fmt	(	char *	bdf,
		size_t	sz,
		const struct spdk_pci_addr *	addr )

Convert a struct spdk_pci_addr to a string.

Parameters

bdf	String into which a string will be output in the format domain:bus:device.function. The string must be at least 14 characters in size.
sz	Size of bdf in bytes. Must be at least 14.
addr	PCI address.

Returns: 0 on success, or a negated errno on failure.

◆ spdk_pci_addr_parse()

int spdk_pci_addr_parse	(	struct spdk_pci_addr *	addr,
		const char *	bdf )

Convert a string representation of a PCI address into a struct spdk_pci_addr.

Parameters

addr	PCI address output on success.
bdf	PCI address in domain:bus:device.function format or domain.bus.device.function format.

Returns: 0 on success, negative errno on failure.

◆ spdk_pci_device_allow()

int spdk_pci_device_allow ( struct spdk_pci_addr * pci_addr )

Allow the specified PCI device to be probed by the calling process.

When using spdk_pci_enumerate(), only devices with allowed PCI addresses will be probed. By default, this is all PCI addresses, but the pci_allowed and pci_blocked environment options can override this behavior. This API enables the caller to allow a new PCI address that may have previously been blocked.

Parameters

pci_addr PCI address to allow

Returns: 0 if successful; -ENOMEM if environment-specific data structures cannot be allocated; -EINVAL if specified PCI address is not valid

◆ spdk_pci_device_attach()

int spdk_pci_device_attach	(	struct spdk_pci_driver *	driver,
		spdk_pci_enum_cb	enum_cb,
		void *	enum_ctx,
		struct spdk_pci_addr *	pci_address )

Attach a PCI device.

This will bypass all blocked list rules and explicitly attach a device at the provided address. The return code of the provided callback will decide whether that device is attached or not. Attached devices have to be manually detached with spdk_pci_device_detach() to be attach-able again.

Parameters

driver	Driver for a specific device type. The device will only be attached if it's supported by this driver.
enum_cb	Callback to be called for the PCI device once it's found.
enum_ctx	Additional context passed to the callback function.
pci_address	Address of the device to attach.

Returns: -1 if a device at the provided PCI address couldn't be found, -1 if an internal error happened or the provided callback returned non-zero, 0 otherwise

◆ spdk_pci_device_cfg_read()

int spdk_pci_device_cfg_read	(	struct spdk_pci_device *	dev,
		void *	buf,
		uint32_t	len,
		uint32_t	offset )

Read len bytes from the PCI configuration space.

Parameters

dev	PCI device.
buf	A buffer to copy the data into.
len	Number of bytes to read.
offset	Offset (in bytes) in the PCI config space to start reading from.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_read16()

int spdk_pci_device_cfg_read16	(	struct spdk_pci_device *	dev,
		uint16_t *	value,
		uint32_t	offset )

Read 2 bytes from the PCI configuration space.

Parameters

dev	PCI device.
value	A buffer to copy the data into.
offset	Offset (in bytes) in the PCI config space to start reading from.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_read32()

int spdk_pci_device_cfg_read32	(	struct spdk_pci_device *	dev,
		uint32_t *	value,
		uint32_t	offset )

Read 4 bytes from the PCI configuration space.

Parameters

dev	PCI device.
value	A buffer to copy the data into.
offset	Offset (in bytes) in the PCI config space to start reading from.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_read8()

int spdk_pci_device_cfg_read8	(	struct spdk_pci_device *	dev,
		uint8_t *	value,
		uint32_t	offset )

Read 1 byte from the PCI configuration space.

Parameters

dev	PCI device.
value	A buffer to copy the data into.
offset	Offset (in bytes) in the PCI config space to start reading from.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_write()

int spdk_pci_device_cfg_write	(	struct spdk_pci_device *	dev,
		void *	buf,
		uint32_t	len,
		uint32_t	offset )

Write len bytes into the PCI configuration space.

Parameters

dev	PCI device.
buf	A buffer to copy the data from.
len	Number of bytes to write.
offset	Offset (in bytes) in the PCI config space to start writing to.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_write16()

int spdk_pci_device_cfg_write16	(	struct spdk_pci_device *	dev,
		uint16_t	value,
		uint32_t	offset )

Write 2 bytes into the PCI configuration space.

Parameters

dev	PCI device.
value	A value to write.
offset	Offset (in bytes) in the PCI config space to start writing to.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_write32()

int spdk_pci_device_cfg_write32	(	struct spdk_pci_device *	dev,
		uint32_t	value,
		uint32_t	offset )

Write 4 bytes into the PCI configuration space.

Parameters

dev	PCI device.
value	A value to write.
offset	Offset (in bytes) in the PCI config space to start writing to.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_cfg_write8()

int spdk_pci_device_cfg_write8	(	struct spdk_pci_device *	dev,
		uint8_t	value,
		uint32_t	offset )

Write 1 byte into the PCI configuration space.

Parameters

dev	PCI device.
value	A value to write.
offset	Offset (in bytes) in the PCI config space to start writing to.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_claim()

int spdk_pci_device_claim ( struct spdk_pci_device * dev )

Claim a PCI device for exclusive SPDK userspace access.

Uses F_SETLK on a shared memory file with the PCI address embedded in its name. As long as this file remains open with the lock acquired, other processes will not be able to successfully call this function on the same PCI device.

The device can be un-claimed by the owning process with spdk_pci_device_unclaim(). It will be also unclaimed automatically when detached.

Parameters

dev	PCI device to claim.

Returns: -EACCES if the device has already been claimed, negative errno on unexpected errors, 0 on success.

◆ spdk_pci_device_detach()

void spdk_pci_device_detach ( struct spdk_pci_device * device )

Release all resources associated with the given device and detach it.

As long as the PCI device is physically available, it will attachable again.

Parameters

device PCI device.

◆ spdk_pci_device_disable_interrupt()

int spdk_pci_device_disable_interrupt ( struct spdk_pci_device * dev )

Disable PCI device interrupts.

(Experimental)

Parameters

dev	PCI device.

Returns: 0 on success, negative value on error.

◆ spdk_pci_device_disable_interrupts()

int spdk_pci_device_disable_interrupts ( struct spdk_pci_device * dev )

Disable PCI device interrupts.

This disables the MSI-X interrupts for all the created event file descriptors and frees them.

Parameters

dev	PCI device.

Returns: 0 on success, negative value on error.

◆ spdk_pci_device_enable_interrupt()

int spdk_pci_device_enable_interrupt ( struct spdk_pci_device * dev )

Enable PCI device interrupts.

(Experimental)

Parameters

dev	PCI device.

Returns: 0 on success, negative value on error.

◆ spdk_pci_device_enable_interrupts()

int spdk_pci_device_enable_interrupts	(	struct spdk_pci_device *	dev,
		uint32_t	efd_count )

Enable PCI device interrupts, only if VFIO MSI-X is supported.

This creates a bunch of event file descriptors, for which VFIO IRQ are set, which then can be used to enable interrupts.

Parameters

dev	PCI device.
efd_count	Number of event fds to create.

Returns: 0 on success, negative value on error.

◆ spdk_pci_device_get_addr()

struct spdk_pci_addr spdk_pci_device_get_addr ( struct spdk_pci_device * dev )

Get the full DomainBDF address of a PCI device.

Parameters

dev	PCI device.

Returns: PCI address.

◆ spdk_pci_device_get_bus()

uint8_t spdk_pci_device_get_bus ( struct spdk_pci_device * dev )

Get the bus number of a PCI device.

Parameters

dev	PCI device.

Returns: PCI bus number.

◆ spdk_pci_device_get_dev()

uint8_t spdk_pci_device_get_dev ( struct spdk_pci_device * dev )

Get the device number within the PCI bus the device is on.

Parameters

dev	PCI device.

Returns: PCI device number.

◆ spdk_pci_device_get_device_id()

uint16_t spdk_pci_device_get_device_id ( struct spdk_pci_device * dev )

Get the device ID of a PCI device.

Parameters

dev	PCI device.

Returns: device ID.

◆ spdk_pci_device_get_domain()

uint32_t spdk_pci_device_get_domain ( struct spdk_pci_device * dev )

Get the domain of a PCI device.

Parameters

dev	PCI device.

Returns: PCI device domain.

◆ spdk_pci_device_get_func()

uint8_t spdk_pci_device_get_func ( struct spdk_pci_device * dev )

Get the particular function number represented by struct spdk_pci_device.

Parameters

dev	PCI device.

Returns: PCI function number.

◆ spdk_pci_device_get_id()

struct spdk_pci_id spdk_pci_device_get_id ( struct spdk_pci_device * dev )

Get the PCI ID of a PCI device.

Parameters

dev	PCI device.

Returns: PCI ID.

◆ spdk_pci_device_get_interrupt_efd()

int spdk_pci_device_get_interrupt_efd ( struct spdk_pci_device * dev )

Get an event file descriptor associated with a PCI device interrupt.

(Experimental)

Parameters

dev	PCI device.

Returns: Event file descriptor on success, negative value on error.

◆ spdk_pci_device_get_interrupt_efd_by_index()

int spdk_pci_device_get_interrupt_efd_by_index	(	struct spdk_pci_device *	dev,
		uint32_t	index )

Get an event file descriptor associated with a PCI device, for a particular MSI-X index.

Parameters

dev	PCI device.
index	event file descriptor index.

Returns: Event file descriptor on success, negative value on error.

◆ spdk_pci_device_get_numa_id()

int spdk_pci_device_get_numa_id ( struct spdk_pci_device * dev )

Get the NUMA node the PCI device is on.

Parameters

dev	PCI device.

Returns: NUMA node index (>= 0).

◆ spdk_pci_device_get_serial_number()

int spdk_pci_device_get_serial_number	(	struct spdk_pci_device *	dev,
		char *	sn,
		size_t	len )

Serialize the PCIe Device Serial Number into the provided buffer.

The buffer will contain a 16-character-long serial number followed by a NULL terminator.

Parameters

dev	PCI device.
sn	Buffer to store the serial number in.
len	Length of buffer. Must be at least 17.

Returns: 0 on success, -1 on failure.

◆ spdk_pci_device_get_socket_id()

int spdk_pci_device_get_socket_id ( struct spdk_pci_device * dev )

Get the NUMA node the PCI device is on.

Deprecated. Use ref spdk_pci_device_get_numa_id() instead.

Parameters

dev	PCI device.

Returns: NUMA node index (>= 0).

◆ spdk_pci_device_get_subdevice_id()

uint16_t spdk_pci_device_get_subdevice_id ( struct spdk_pci_device * dev )

Get the subdevice ID of a PCI device.

Parameters

dev	PCI device.

Returns: subdevice ID.

◆ spdk_pci_device_get_subvendor_id()

uint16_t spdk_pci_device_get_subvendor_id ( struct spdk_pci_device * dev )

Get the subvendor ID of a PCI device.

Parameters

dev	PCI device.

Returns: subvendor ID.

◆ spdk_pci_device_get_type()

const char * spdk_pci_device_get_type ( const struct spdk_pci_device * dev )

Return the type of the PCI device.

Parameters

dev	PCI device

Returns: string representing the type of the device

◆ spdk_pci_device_get_vendor_id()

uint16_t spdk_pci_device_get_vendor_id ( struct spdk_pci_device * dev )

Get the vendor ID of a PCI device.

Parameters

dev	PCI device.

Returns: vendor ID.

◆ spdk_pci_device_is_removed()

bool spdk_pci_device_is_removed ( struct spdk_pci_device * dev )

Check if device was requested to be removed from the process.

This can be caused either by physical device hotremoval or OS-triggered removal. In the latter case, the device may continue to function properly even if this function returns true . The upper-layer driver may check this function periodically and eventually detach the device.

Parameters

dev	PCI device.

Returns: if device was requested to be removed

◆ spdk_pci_device_map_bar()

int spdk_pci_device_map_bar	(	struct spdk_pci_device *	dev,
		uint32_t	bar,
		void **	mapped_addr,
		uint64_t *	phys_addr,
		uint64_t *	size )

Map a PCI BAR in the current process.

Parameters

dev	PCI device.
bar	BAR number.
mapped_addr	A variable to store the virtual address of the mapping.
phys_addr	A variable to store the physical address of the mapping.
size	A variable to store the size of the bar (in bytes).

Returns: 0 on success.

◆ spdk_pci_device_unclaim()

void spdk_pci_device_unclaim ( struct spdk_pci_device * dev )

Undo spdk_pci_device_claim().

Parameters

dev	PCI device to unclaim.

◆ spdk_pci_device_unmap_bar()

int spdk_pci_device_unmap_bar	(	struct spdk_pci_device *	dev,
		uint32_t	bar,
		void *	mapped_addr )

Unmap a PCI BAR from the current process.

This happens automatically when the PCI device is detached.

Parameters

dev	PCI device.
bar	BAR number.
mapped_addr	Virtual address of the bar.

Returns: 0 on success.

◆ spdk_pci_enumerate()

int spdk_pci_enumerate	(	struct spdk_pci_driver *	driver,
		spdk_pci_enum_cb	enum_cb,
		void *	enum_ctx )

Enumerate all PCI devices supported by the provided driver and try to attach those that weren't attached yet.

The provided callback will be called for each such device and its return code will decide whether that device is attached or not. Attached devices have to be manually detached with spdk_pci_device_detach() to be attach-able again.

During enumeration all registered pci devices with exposed access to userspace are getting probed internally unless not explicitly specified on denylist. Because of that it becomes not possible to either use such devices with another application or unbind the driver (e.g. vfio).

2s asynchronous delay is introduced to avoid race conditions between user space software initialization and in-kernel device handling for newly inserted devices. Subsequent enumerate call after the delay shall allow for a successful device attachment.

Parameters

driver	Driver for a specific device type.
enum_cb	Callback to be called for each non-attached PCI device.
enum_ctx	Additional context passed to the callback function.

Returns: -1 if an internal error occurred or the provided callback returned -1, 0 otherwise

◆ spdk_pci_event_listen()

int spdk_pci_event_listen ( void )

Begin listening for PCI bus events.

This is used to detect hot-insert and hot-remove events. Once the system is listening, events may be retrieved by calling spdk_pci_get_event() periodically.

Returns: negative errno on failure, otherwise, return a file descriptor that may be later passed to spdk_pci_get_event().

◆ spdk_pci_for_each_device()

void spdk_pci_for_each_device	(	void *	ctx,
		void(*	fn )(void ctx, struct spdk_pci_device dev) )

Call the provided function pointer for every enumerated PCI device.

Parameters

ctx	Context parameter to pass to fn.
fn	Function to call for each PCI device

◆ spdk_pci_get_driver()

struct spdk_pci_driver * spdk_pci_get_driver ( const char * name )

Get PCI driver by name (e.g.

"nvme", "vmd", "ioat").

◆ spdk_pci_get_event()

int spdk_pci_get_event	(	int	fd,
		struct spdk_pci_event *	event )

Get the next PCI bus event.

Parameters

fd	A file descriptor returned by spdk_pci_event_listen()
event	An event on the PCI bus

Returns: Negative errno on failure. 0 for no event. A positive number when an event has been returned

◆ spdk_pci_hook_device()

int spdk_pci_hook_device	(	struct spdk_pci_driver *	drv,
		struct spdk_pci_device *	dev )

Hook a custom PCI device into the PCI layer.

The device will be attachable, enumerable, and will call provided callbacks on each PCI resource access request.

Parameters

drv	driver that will be able to attach the device
dev	fully initialized PCI device struct

Returns: 0 on success, negative errno otherwise.

◆ spdk_pci_idxd_get_driver()

struct spdk_pci_driver * spdk_pci_idxd_get_driver ( void )

Get the IDXD PCI driver object.

Returns: PCI driver.

◆ spdk_pci_ioat_get_driver()

struct spdk_pci_driver * spdk_pci_ioat_get_driver ( void )

Get the I/OAT PCI driver object.

Returns: PCI driver.

◆ spdk_pci_nvme_get_driver()

struct spdk_pci_driver * spdk_pci_nvme_get_driver ( void )

Get the NVMe PCI driver object.

Returns: PCI driver.

◆ spdk_pci_register_device_provider()

void spdk_pci_register_device_provider ( struct spdk_pci_device_provider * provider )

Register a PCI device provdier.

Parameters

provider PCI device provider.

◆ spdk_pci_register_error_handler()

int spdk_pci_register_error_handler	(	spdk_pci_error_handler	sighandler,
		void *	ctx )

Register a signal handler to handle bus errors on the PCI bus.

Parameters

sighandler	Signal bus handler of the PCI bus
ctx	The arg pass to the registered signal bus handler.

Returns: negative errno on failure, otherwise it means successful

◆ spdk_pci_unhook_device()

void spdk_pci_unhook_device ( struct spdk_pci_device * dev )

Un-hook a custom PCI device from the PCI layer.

The device must not be attached.

Parameters

dev	fully initialized PCI device struct

◆ spdk_pci_unregister_error_handler()

void spdk_pci_unregister_error_handler ( spdk_pci_error_handler sighandler )

Register a signal handler to handle bus errors on the PCI bus.

Parameters

sighandler Signal bus handler of the PCI bus

◆ spdk_pci_virtio_get_driver()

struct spdk_pci_driver * spdk_pci_virtio_get_driver ( void )

Get the Virtio PCI driver object.

Returns: PCI driver.

◆ spdk_pci_vmd_get_driver()

struct spdk_pci_driver * spdk_pci_vmd_get_driver ( void )

Get the VMD PCI driver object.

Returns: PCI driver.

◆ spdk_process_is_primary()

bool spdk_process_is_primary ( void )

Check whether the calling process is primary process.

Returns: true if the calling process is primary process, or false otherwise.

◆ spdk_realloc()

void * spdk_realloc	(	void *	buf,
		size_t	size,
		size_t	align )

Resize a dma/sharable memory buffer with the given new size and alignment.

Existing contents are preserved.

Parameters

buf	Buffer to resize.
size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.

Returns: a pointer to the resized memory buffer.

◆ spdk_ring_count()

size_t spdk_ring_count ( struct spdk_ring * ring )

Get the number of objects in the ring.

Parameters

ring the ring.

Returns: the number of objects in the ring.

◆ spdk_ring_create()

struct spdk_ring * spdk_ring_create	(	enum spdk_ring_type	type,
		size_t	count,
		int	numa_id )

Create a ring.

Parameters

type	Type for the ring. (SPDK_RING_TYPE_SP_SC or SPDK_RING_TYPE_MP_SC).
count	Size of the ring in elements.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.

Returns: a pointer to the created ring.

◆ spdk_ring_dequeue()

size_t spdk_ring_dequeue	(	struct spdk_ring *	ring,
		void **	objs,
		size_t	count )

Dequeue count objects from the ring into the array objs.

Parameters

ring	A pointer to the ring.
objs	A pointer to the array to be dequeued.
count	Maximum number of elements to be dequeued.

Returns: the number of objects dequeued which is less than 'count'.

◆ spdk_ring_enqueue()

size_t spdk_ring_enqueue	(	struct spdk_ring *	ring,
		void **	objs,
		size_t	count,
		size_t *	free_space )

Queue the array of objects (with length count) on the ring.

Parameters

ring	A pointer to the ring.
objs	A pointer to the array to be queued.
count	Length count of the array of objects.
free_space	If non-NULL, amount of free space after the enqueue has finished.

Returns: the number of objects enqueued.

◆ spdk_ring_free()

void spdk_ring_free ( struct spdk_ring * ring )

Free the ring.

Parameters

ring	Ring to free.

◆ spdk_vtophys()

uint64_t spdk_vtophys	(	const void *	buf,
		uint64_t *	size )

Get the physical address of a buffer.

Parameters

buf	A pointer to a buffer.
size	Contains the size of the memory region pointed to by vaddr. If vaddr is successfully translated, then this is updated with the size of the memory region for which the translation is valid.

Returns: the physical address of this buffer on success, or SPDK_VTOPHYS_ERROR on failure.

◆ spdk_zmalloc()

void * spdk_zmalloc	(	size_t	size,
		size_t	align,
		uint64_t *	unused,
		int	numa_id,
		uint32_t	flags )

Allocate dma/sharable memory based on a given dma_flg.

It is a memory buffer with the given size, alignment and socket id. Also, the buffer will be zeroed.

Parameters

size	Size in bytes.
align	If non-zero, the allocated buffer is aligned to a multiple of align. In this case, it must be a power of two. The returned buffer is always aligned to at least cache line size.
unused	Invalid. If not a NULL, the function will fail and return NULL.
numa_id	NUMA node ID to allocate memory on, or SPDK_ENV_NUMA_ID_ANY for any NUMA node.
flags	Combination of SPDK_MALLOC flags (SPDK_MALLOC_DMA, SPDK_MALLOC_SHARE).

Returns: a pointer to the allocated memory buffer.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SPDK_ENV_FOREACH_CORE

◆ SPDK_ENV_FOREACH_NUMA_ID

◆ SPDK_MEMZONE_NO_IOVA_CONTIG

◆ SPDK_PCI_DEVICE

◆ SPDK_PCI_DRIVER_REGISTER

◆ SPDK_PCI_REGISTER_DEVICE_PROVIDER

Typedef Documentation

◆ spdk_mempool_mem_cb_t

◆ spdk_mempool_obj_cb_t

◆ spdk_pci_enum_cb

Function Documentation

◆ spdk_call_unaffinitized()

◆ spdk_delay_us()

◆ spdk_dma_free()

◆ spdk_dma_malloc()

◆ spdk_dma_malloc_socket()

◆ spdk_dma_realloc()

◆ spdk_dma_zmalloc()

◆ spdk_dma_zmalloc_socket()

◆ spdk_env_core_get_smt_cpuset()

◆ spdk_env_fini()

◆ spdk_env_get_core_count()

◆ spdk_env_get_cpuset()

◆ spdk_env_get_current_core()

◆ spdk_env_get_first_core()

◆ spdk_env_get_first_numa_id()

◆ spdk_env_get_last_core()

◆ spdk_env_get_last_numa_id()

◆ spdk_env_get_main_core()

◆ spdk_env_get_next_core()

◆ spdk_env_get_next_numa_id()

◆ spdk_env_get_numa_id()

◆ spdk_env_get_socket_id()

◆ spdk_env_init()

◆ spdk_env_opts_init()

◆ spdk_env_thread_launch_pinned()

◆ spdk_free()

◆ spdk_get_ticks()

◆ spdk_get_ticks_hz()

◆ spdk_iommu_is_enabled()

◆ spdk_malloc()

◆ spdk_mem_get_fd_and_offset()

◆ spdk_mem_get_numa_id()

◆ spdk_mem_map_alloc()

◆ spdk_mem_map_clear_translation()

◆ spdk_mem_map_free()

◆ spdk_mem_map_set_translation()

◆ spdk_mem_map_translate()

◆ spdk_mem_register()

◆ spdk_mem_reserve()

◆ spdk_mem_unregister()

◆ spdk_mempool_count()

◆ spdk_mempool_create()

◆ spdk_mempool_create_ctor()

◆ spdk_mempool_get()

◆ spdk_mempool_get_bulk()

◆ spdk_mempool_get_name()

◆ spdk_mempool_lookup()

◆ spdk_mempool_mem_iter()

◆ spdk_mempool_obj_iter()

◆ spdk_mempool_put()

◆ spdk_mempool_put_bulk()

◆ spdk_memzone_dump()

◆ spdk_memzone_free()

◆ spdk_memzone_lookup()

◆ spdk_memzone_reserve()

◆ spdk_memzone_reserve_aligned()

◆ spdk_pci_addr_compare()

◆ spdk_pci_addr_fmt()

◆ spdk_pci_addr_parse()

◆ spdk_pci_device_allow()

◆ spdk_pci_device_attach()

◆ spdk_pci_device_cfg_read()