L4Re - L4 Runtime Environment
L4 Vbus functions

C interface of the Vbus API. More...

+ Collaboration diagram for L4 Vbus functions:

Modules

 L4vbus GPIO functions
 
 L4vbus PCI 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 human interface identifier (HID). More...
 
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. More...
 
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. More...
 
int l4vbus_get_resource (l4_cap_idx_t vbus, l4vbus_device_handle_t dev, int res_idx, l4vbus_resource_t *res)
 Obtain the resource description of an individual device resource. More...
 
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. More...
 
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. More...
 
int l4vbus_request_resource (l4_cap_idx_t vbus, l4vbus_resource_t const *res, int flags)
 Request a resource of a specific type. More...
 
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 (L4::Task) or a L4Re::Dma_space to a DMA domain. More...
 
int l4vbus_release_resource (l4_cap_idx_t vbus, l4vbus_resource_t const *res)
 Release a previously requested resource. More...
 
int l4vbus_vicu_get_cap (l4_cap_idx_t vbus, l4vbus_device_handle_t icu, l4_cap_idx_t cap)
 Get capability of ICU. More...
 

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>

Refer to L4vbus for the C++ API.

Enumeration Type Documentation

◆ 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 153 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 (L4::Task) or a L4Re::Dma_space to a DMA domain.

Parameters
vbusCapability of the system bus
domain_idDMA 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.
flagsA combination of L4vbus_dma_domain_assign_flags.
dma_spaceThe 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
0Operation completed successfully.
-L4_ENOENTThe vbus does not support a global DMA domain or no DMA domain could be found.
-L4_EINVALInvalid argument used.
-L4_EBUSYDMA domain is already active, this means another DMA space is already assigned.

◆ 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
vbusCapability of the vbus to which the device is connected.
devDevice handle of the device from which to retrieve the details.
[out]devinfoInformation structure which contains details about the device. The pointer might be NULL after a successfull call.
Return values
0Success.
-L4_ENODEVNo device with the given device handle dev could be found.

◆ 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 human interface identifier (HID).

Parameters
vbusCapability of the system bus
parentHandle 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]childHandle 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.
hidHID of the device
depthMaximum depth for the recursive lookup
[out]devinfoDevice information structure (might be NULL)
Return values
>=0 A device with the given HID was found.
-L4_ENOENTNo device with the given HID could be found on the vbus.
-L4_EINVALInvalid or no HID provided.
-L4_ENODEVFunction called on a non-existing device.

◆ 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
vbusCapability of the system bus
devHandle of the device
hidPointer to a buffer for the HID string
max_lenThe 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
vbusCapability of the system bus
parentHandle to the parent device (use 0 for the system bus)
childHandle to the child device (use 0 to get the first child)
depthDepth to look for
[out]devinfodevice information (might be NULL)
Returns
0 on success, else failure

◆ l4vbus_get_resource()

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

Obtain the resource description of an individual device resource.

Parameters
vbusCapability of the vbus to which the device is connected.
devDevice 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_idxIndex 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]resDescriptor of the resource.

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

Return values
0Success.
-L4_ENOENTInvalid resource index res_idx.

◆ 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
vbusCapability of the system bus
devdevice handle for which the CID shall be tested
cidthe 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.

◆ l4vbus_release_resource()

int l4vbus_release_resource ( l4_cap_idx_t  vbus,
l4vbus_resource_t const *  res 
)

Release a previously requested resource.

Parameters
vbusCapability of the system bus.
resDescriptor of the resource.
Returns
0 on success, else failure

◆ l4vbus_request_resource()

int l4vbus_request_resource ( l4_cap_idx_t  vbus,
l4vbus_resource_t const *  res,
int  flags 
)

Request a resource of a specific type.

Parameters
vbusCapability of the system bus
resDescriptor of the resource
flagsOptional flags
Returns
0 on success, else failure

If any resource is found that contains the requested type and addresses this resource is returned.

Flags are only relevant to control the memory caching. If io-memory is requested.

Returns
0 on success, else failure

◆ 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
vbusCapability of the system bus.
icuICU device handle.
capCapability slot for the capability.
Returns
0 on success, else failure