l4/pkg/io/libvbus/include/vbus.h

   1 /*
   2  * (c) 2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   3  *          Alexander Warg <warg@os.inf.tu-dresden.de>,
   4  *          Torsten Frenzel <frenzel@os.inf.tu-dresden.de>
   5  *     economic rights: Technische Universität Dresden (Germany)
   6  *
   7  * This file is part of TUD:OS and distributed under the terms of the
   8  * GNU General Public License 2.
   9  * Please see the COPYING-GPL-2 file for details.
  10  */
  11 /**
  12  * \file vbus.h
  13  * Description of the vbus C API
  14  */
  15 #pragma once
  16
  17 #include <l4/sys/compiler.h>
  18 #include <l4/vbus/vbus_types.h>
  19 #include <l4/sys/types.h>
  20
  21 /** Constants for device nodes */
  22 enum {
  23   L4VBUS_NULL = 0,     /**< NULL device */
  24   L4VBUS_ROOT_BUS = 0, /**< Root device on the vbus */
  25 };
  26
  27 /**
  28  * \defgroup l4vbus_module L4 V-BUS functions
  29  * \{
  30  */
  31
  32 __BEGIN_DECLS
  33
  34 /**
  35  * \copybrief L4vbus::Device::device_by_hid()
  36  * \param  vbus         Capability of the system bus
  37  * \param  parent       Handle to the parent to start the search
  38  * \copydetails L4vbus::Device::device_by_hid()
  39  */
  40 int L4_CV
  41 l4vbus_get_device_by_hid(l4_cap_idx_t vbus, l4vbus_device_handle_t parent,
  42                          l4vbus_device_handle_t *child, char const *hid,
  43                          int depth, l4vbus_device_t *devinfo);
  44
  45 /**
  46  * \copybrief L4vbus::Device::next_device()
  47  * \param  vbus         Capability of the system bus
  48  * \param  parent       Handle to the parent device (use 0 for the system bus)
  49  * \param  child        Handle to the child device (use 0 to get the first
  50  *                      child)
  51  * \param  depth        Depth to look for
  52  * \param[out] devinfo  device information (might be NULL)
  53  *
  54  * \return 0 on success, else failure
  55  */
  56 int L4_CV
  57 l4vbus_get_next_device(l4_cap_idx_t vbus, l4vbus_device_handle_t parent,
  58                        l4vbus_device_handle_t *child, int depth,
  59                        l4vbus_device_t *devinfo);
  60
  61 /**
  62  * \copybrief L4vbus::Device::get_resource()
  63  * \param  vbus         Capability of the system bus
  64  * \param  dev          Handle of the device
  65  * \copydetails L4vbus::Device::get_resource()
  66  */
  67 int L4_CV
  68 l4vbus_get_resource(l4_cap_idx_t vbus, l4vbus_device_handle_t dev,
  69                     int res_idx, l4vbus_resource_t *res);
  70
  71
  72 /**
  73  * \copybrief L4vbus::Device::is_compatible()
  74  * \param  vbus Capability of the system bus
  75  * \param  dev  device handle for which the CID shall be tested
  76  * \copydetails L4vbus::Device::is_compatible()
  77  */
  78 int L4_CV
  79 l4vbus_is_compatible(l4_cap_idx_t vbus, l4vbus_device_handle_t dev,
  80                      char const *cid);
  81
  82 /**
  83  * \brief Get the HID (hardware identifier) if a device
  84  *
  85  * \param  vbus         Capability of the system bus
  86  * \param  dev          Handle of the device
  87  * \param  hid          Pointer to a buffer for the HID string
  88  * \param  max_len      The size of the buffer (\a hid)
  89  *
  90  * \return the length of the HID string on success, else failure
  91  */
  92 int L4_CV
  93 l4vbus_get_hid(l4_cap_idx_t vbus, l4vbus_device_handle_t dev, char *hid,
  94                unsigned long max_len);
  95
  96 /**
  97  * \brief Request a resource of a specific type
  98  *
  99  * \param  vbus         Capability of the system bus
 100  * \param  res          Descriptor of the resource
 101  * \param  flags        Optional flags
 102  *
 103  * \return 0 on success, else failure
 104  *
 105  * If any resource is found that contains the requested
 106  * type and addresses this resource is returned.
 107  *
 108  * Flags are only relevant to control the memory caching.
 109  * If io-memory is requested.
 110  *
 111  * \return 0 on success, else failure
 112  */
 113 int L4_CV
 114 l4vbus_request_resource(l4_cap_idx_t vbus, l4vbus_resource_t const *res,
 115                         int flags);
 116
 117 /**
 118  * Flags for l4vbus_assign_dma_domain().
 119  */
 120 enum L4vbus_dma_domain_assign_flags
 121 {
 122   /** Unbind the given DMA space from the DMA domain. */
 123   L4VBUS_DMAD_UNBIND = 0,
 124   /** Bind the given DMA space to the DMA domain. */
 125   L4VBUS_DMAD_BIND   = 1,
 126   /** The given DMA space is an L4Re::Dma_space */
 127   L4VBUS_DMAD_L4RE_DMA_SPACE = 0,
 128   /** The goven DMA space is a kernel DMA space (L4::Task) */
 129   L4VBUS_DMAD_KERNEL_DMA_SPACE = 2,
 130 };
 131
 132 /**
 133  * Bind or unbind a kernel DMA space (L4::Task) or a L4Re::Dma_space to a
 134  * DMA domain.
 135  * \param vbus       Capability of the system bus
 136  * \param domain_id  DMA domain ID (resource address of DMA domain found on
 137  *                   the vBUS).
 138  * \param flags      A combination of #L4vbus_dma_domain_assign_flags.
 139  * \param dma_space  The DMA space capability to bind or unbind, this must
 140  *                   either be an L4Re::Dma_space or a kernel DMA space
 141  *                   (L4::Task created with L4_PROTO_DMA_SPACE) and the type
 142  *                   must be reflected in the `flags`.
 143  *
 144  * \retval 0           Operation completed successfully.
 145  * \retval -L4_ENOENT  The vbus does not support a global DMA domain or no DMA
 146  *                     domain could be found.
 147  * \retval -L4_EINVAL  Invalid argument used.
 148  * \retval -L4_EBUSY   DMA domain is already active, this means another DMA
 149  *                     space is already assigned.
 150  */
 151 int L4_CV
 152 l4vbus_assign_dma_domain(l4_cap_idx_t vbus, unsigned domain_id,
 153                          unsigned flags, l4_cap_idx_t dma_space);
 154
 155 /**
 156  * \brief Release a previously requested resource
 157  *
 158  * \param  vbus         Capability of the system bus.
 159  * \param  res          Descriptor of the resource.
 160  *
 161  * \return 0 on success, else failure
 162  */
 163 int L4_CV
 164 l4vbus_release_resource(l4_cap_idx_t vbus, l4vbus_resource_t const *res);
 165
 166 /**
 167  * \brief Get capability of ICU.
 168  *
 169  * \param  vbus         Capability of the system bus.
 170  * \param  icu          ICU device handle.
 171  * \param  cap          Capability slot for the capability.
 172  *
 173  * \return 0 on success, else failure
 174  */
 175 int L4_CV
 176 l4vbus_vicu_get_cap(l4_cap_idx_t vbus, l4vbus_device_handle_t icu,
 177                     l4_cap_idx_t cap);
 178
 179 __END_DECLS
 180
 181 /** \} */