Loading...
Searching...
No Matches
L4 Vbus functions

C interface of the Vbus API. More...

Collaboration diagram for L4 Vbus functions:

## Topics

| 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

L4_BEGIN_DECLS 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 174 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.

References L4_CV.

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.

References L4_CV.

## 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.

References L4_CV.

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

Here is the caller graph for this function:

## l4vbus_get_device_by_hid()

L4_BEGIN_DECLS 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.

References L4_CV.

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

References L4_CV.

## 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

References L4_CV.

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.

References L4_CV.

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.

References L4_CV.

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.

References L4_CV.

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

References L4_END_DECLS.

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

Here is the caller graph for this function: