C interface of the Vbus API. More...

Collaboration diagram for L4 Vbus functions:

Modules
	L4vbus GPIO functions

	L4vbus PCI functions

	L4vbus power management functions

Enumerations
enum	L4vbus_dma_domain_assign_flags { L4VBUS_DMAD_UNBIND = 0 , L4VBUS_DMAD_BIND = 1 , L4VBUS_DMAD_L4RE_DMA_SPACE = 0 , L4VBUS_DMAD_KERNEL_DMA_SPACE = 2 }
	Flags for l4vbus_assign_dma_domain(). More...

Functions
int	l4vbus_get_device_by_hid (l4_cap_idx_t vbus, l4vbus_device_handle_t parent, l4vbus_device_handle_t child, char const hid, int depth, l4vbus_device_t *devinfo)
	Find a device by the hardware interface identifier (HID).

int	l4vbus_get_next_device (l4_cap_idx_t vbus, l4vbus_device_handle_t parent, l4vbus_device_handle_t child, int depth, l4vbus_device_t devinfo)
	Find next child following `child`.

int	l4vbus_get_device (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, l4vbus_device_t *devinfo)
	Obtain detailed information about a Vbus device.

int	l4vbus_get_resource (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, unsigned res_idx, l4vbus_resource_t *res)
	Obtain the resource description of an individual device resource.

int	l4vbus_is_compatible (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, char const *cid)
	Check if the given device has a compatibility ID (CID) or HID that matches cid.

int	l4vbus_get_hid (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, char *hid, unsigned long max_len)
	Get the HID (hardware identifier) of a device.

int	l4vbus_get_adr (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, l4_uint32_t *adr)
	Get the bus-specific address of a device.

int	l4vbus_request_ioport (l4_cap_idx_t vbus, l4vbus_resource_t const *res)
	Request an IO port resource.

int	l4vbus_assign_dma_domain (l4_cap_idx_t vbus, unsigned domain_id, unsigned flags, l4_cap_idx_t dma_space)
	Bind or unbind a kernel DMA space or a L4Re::Dma_space to a DMA domain.

int	l4vbus_release_ioport (l4_cap_idx_t vbus, l4vbus_resource_t const *res)
	Release a previously requested IO port resource.

int	l4vbus_vicu_get_cap (l4_cap_idx_t vbus, l4vbus_device_handle_t icu, l4_cap_idx_t cap)
	Get capability of ICU.

Detailed Description

C interface of the Vbus API.

The virtual bus (Vbus) is a hierarchical (tree) structure of device nodes where each device has a set of resources attached to it. Each virtual bus provides an Icu (Interrupt controller) for interrupt handling.

The Vbus interface allows a client to find and query devices present on his virtual bus. After obtaining a device handle for a specific device the client can enumerate its resources.

Include File: #include <l4/vbus/vbus.h>

vbus.h
Description of the vbus C API.

Refer to L4vbus for the C++ API.

Enumeration Type Documentation

◆ L4vbus_dma_domain_assign_flags

enum L4vbus_dma_domain_assign_flags

Flags for l4vbus_assign_dma_domain().

Enumerator
L4VBUS_DMAD_UNBIND	Unbind the given DMA space from the DMA domain.
L4VBUS_DMAD_BIND	Bind the given DMA space to the DMA domain.
L4VBUS_DMAD_L4RE_DMA_SPACE	The given DMA space is an L4Re::Dma_space.
L4VBUS_DMAD_KERNEL_DMA_SPACE	The given DMA space is a kernel DMA space (L4::Task)

Definition at line 176 of file vbus.h.

Function Documentation

◆ l4vbus_assign_dma_domain()

int l4vbus_assign_dma_domain	(	l4_cap_idx_t	vbus,
		unsigned	domain_id,
		unsigned	flags,
		l4_cap_idx_t	dma_space
	)

Bind or unbind a kernel DMA space or a L4Re::Dma_space to a DMA domain.

Parameters

vbus	Capability of the system bus
domain_id	DMA domain ID (resource address of DMA domain found on the vBUS). If the value is ~0U the DMA space of the whole vBUS is used.
flags	A combination of L4vbus_dma_domain_assign_flags.
dma_space	The DMA space capability to bind or unbind, this must either be an L4Re::Dma_space or a kernel DMA space (L4::Task created with L4_PROTO_DMA_SPACE) and the type must be reflected in the `flags`.

Return values

0	Operation completed successfully.
-L4_ENOENT	The vbus does not support a global DMA domain or no DMA domain could be found.
-L4_EINVAL	Invalid argument used.
-L4_EBUSY	DMA domain is already active, this means another DMA space is already assigned.

Referenced by L4vbus::Vbus::assign_dma_domain(), and L4vbus::Vbus::assign_dma_domain().

Here is the caller graph for this function:

◆ l4vbus_get_adr()

int l4vbus_get_adr	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	dev,
		l4_uint32_t *	adr
	)

Get the bus-specific address of a device.

Parameters

	vbus	Capability of the system bus
	dev	Handle of the device
[out]	adr	Address

Return values

L4_EOK	Success.
-L4_ENOSYS	Device has no valid address.

◆ l4vbus_get_device()

int l4vbus_get_device	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	dev,
		l4vbus_device_t *	devinfo
	)

Obtain detailed information about a Vbus device.

Parameters

	vbus	Capability of the vbus to which the device is connected.
	dev	Device handle of the device from which to retrieve the details.
[out]	devinfo	Information structure which contains details about the device. The pointer might be NULL.

Return values

0	Success.
-L4_ENODEV	No device with the given device handle `dev` could be found.

Referenced by L4vbus::Device::device().

Here is the caller graph for this function:

◆ l4vbus_get_device_by_hid()

int l4vbus_get_device_by_hid	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	parent,
		l4vbus_device_handle_t *	child,
		char const *	hid,
		int	depth,
		l4vbus_device_t *	devinfo
	)

Find a device by the hardware interface identifier (HID).

Parameters

vbus	Capability of the system bus
parent	Handle to the parent to start the search

This function searches the vbus for a device with the given HID and returns a handle to the first matching device. The HID usually conforms to an ACPI HID or a Linux device tree compatible identifier.

It is possible to have multiple devices with the same HID on a vbus. In order to find all matching devices this function has to be called repeatedly with child pointing to the device found in the previous iteration. The iteration starts at child that might be any device node in the tree.

Parameters

[in,out]	child	Handle of the device from where in the device tree the search should start. To start searching from the beginning `child` must be initialized using the default (L4VBUS_NULL). If a matching device is found, its handle is returned through this parameter.
	hid	HID of the device
	depth	Maximum depth for the recursive lookup
[out]	devinfo	Device information structure (might be NULL)

Return values

>=0	A device with the given HID was found.
-L4_ENOENT	No device with the given HID could be found on the vbus.
-L4_EINVAL	Invalid or no HID provided.
-L4_ENODEV	Function called on a non-existing device.

Referenced by L4vbus::Device::device_by_hid().

Here is the caller graph for this function:

◆ l4vbus_get_hid()

int l4vbus_get_hid	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	dev,
		char *	hid,
		unsigned long	max_len
	)

Get the HID (hardware identifier) of a device.

Parameters

vbus	Capability of the system bus
dev	Handle of the device
hid	Pointer to a buffer for the HID string
max_len	The size of the buffer (hid)

Returns: the length of the HID string on success, else failure

◆ l4vbus_get_next_device()

int l4vbus_get_next_device	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	parent,
		l4vbus_device_handle_t *	child,
		int	depth,
		l4vbus_device_t *	devinfo
	)

Find next child following child.

Parameters

	vbus	Capability of the system bus
	parent	Handle to the parent device (use L4VBUS_ROOT_BUS for the system bus)
[in,out]	child	Handle of the device that precedes the device that shall be returned. To start from the beginning, `child` must be initialized with L4VBUS_NULL. If a device is found, its handle is returned through this parameter.
	depth	Depth to look for
[out]	devinfo	Device information (might be NULL)

Returns: 0 on success, else failure

Referenced by L4vbus::Device::next_device().

Here is the caller graph for this function:

◆ l4vbus_get_resource()

int l4vbus_get_resource	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	dev,
		unsigned	res_idx,
		l4vbus_resource_t *	res
	)

Obtain the resource description of an individual device resource.

Parameters

	vbus	Capability of the vbus to which the device is connected.
	dev	Device handle of the device on the vbus. The device handle can be obtained by using the l4vbus_get_device_by_hid() and l4vbus_get_next_device() functions.
	res_idx	Index of the resource for which the resource description should be returned. The total number of resources for a device is available in the l4vbus_device_t structure that is returned by L4vbus::Device::device_by_hid() and L4vbus::Device::next_device().
[out]	res	Descriptor of the resource.

This function returns the resource descriptor of an individual device resource selected by the res_idx parameter.

Return values

0	Success.
-L4_ENOENT	Invalid resource index `res_idx`.

Referenced by L4vbus::Device::get_resource().

Here is the caller graph for this function:

◆ l4vbus_is_compatible()

int l4vbus_is_compatible	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	dev,
		char const *	cid
	)

Check if the given device has a compatibility ID (CID) or HID that matches cid.

Parameters

vbus	Capability of the system bus
dev	device handle for which the CID shall be tested
cid	the compatibility ID to test

Returns: 1 when the given ID (cid) matches this device, 0 when the given ID does not match, <0 on error.

Referenced by L4vbus::Device::is_compatible().

Here is the caller graph for this function:

◆ l4vbus_release_ioport()

int l4vbus_release_ioport	(	l4_cap_idx_t	vbus,
		l4vbus_resource_t const *	res
	)

Release a previously requested IO port resource.

Parameters

	vbus	Capability of the system bus.
[in]	res	The IO port resource to be released from the bus.

Returns: >=0 on success, <0 on error.

Referenced by L4vbus::Vbus::release_ioport().

Here is the caller graph for this function:

◆ l4vbus_request_ioport()

int l4vbus_request_ioport	(	l4_cap_idx_t	vbus,
		l4vbus_resource_t const *	res
	)

Request an IO port resource.

Parameters

	vbus	Capability of the system bus.
[in]	res	The IO port resource to be requested from the bus.

Return values

0	Success.
-L4_EINVAL	Resource is not an IO port resource.
-L4_ENOENT	No matching IO port resource found.

If any IO port resource is found that contains the requested IO port range the IO ports are obtained.

Referenced by L4vbus::Vbus::request_ioport().

Here is the caller graph for this function:

◆ l4vbus_vicu_get_cap()

int l4vbus_vicu_get_cap	(	l4_cap_idx_t	vbus,
		l4vbus_device_handle_t	icu,
		l4_cap_idx_t	cap
	)

Get capability of ICU.

Parameters

vbus	Capability of the system bus.
icu	ICU device handle.
cap	Capability slot for the capability.

Returns: 0 on success, else failure

Referenced by L4vbus::Icu::vicu().

Here is the caller graph for this function:

Modules

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ L4vbus_dma_domain_assign_flags

Function Documentation

◆ l4vbus_assign_dma_domain()

◆ l4vbus_get_adr()

◆ l4vbus_get_device()

◆ l4vbus_get_device_by_hid()

◆ l4vbus_get_hid()

◆ l4vbus_get_next_device()

◆ l4vbus_get_resource()

◆ l4vbus_is_compatible()

◆ l4vbus_release_ioport()

◆ l4vbus_request_ioport()

◆ l4vbus_vicu_get_cap()