l4/pkg/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 #pragma once
  12
  13 #include <l4/sys/compiler.h>
  14 #include <l4/vbus/vbus_types.h>
  15 #include <l4/sys/types.h>
  16
  17 enum {
  18   L4VBUS_NULL = 0,
  19   L4VBUS_ROOT_BUS = 0,
  20 };
  21
  22 /**
  23  * \defgroup l4vbus_module L4 V-BUS functions
  24  * \{
  25  */
  26
  27 __BEGIN_DECLS
  28
  29 /**
  30  * \brief Find a device by the HID ACPI conforming or L4Io static name.
  31  *
  32  * \param  vbus         Capability of the system bus
  33  * \param  parent       Handle to the parent to start the search
  34  * \retval child        Handle to the found device
  35  * \param  hid          HID name of the device
  36  * \param  depth        Depth to look for
  37  * \retval devinfo      Device information structure (might be NULL)
  38  *
  39  * \return 0 on success, else failure
  40  */
  41 int L4_CV
  42 l4vbus_get_device_by_hid(l4_cap_idx_t vbus, l4vbus_device_handle_t parent,
  43                          l4vbus_device_handle_t *child, char const *hid,
  44                          int depth, l4vbus_device_t *devinfo);
  45
  46 /**
  47  * \brief Find next child following \a child.
  48  *
  49  * \param  vbus         Capability of the system bus
  50  * \param  parent       Handle to the parent device (use 0 for the system bus)
  51  * \param  child        Handle to the child device (use 0 to get the first
  52  *                      child)
  53  * \param  depth        Depth to look for
  54  * \retval devinfo      device information (might be NULL)
  55  *
  56  * \return 0 on success, else failure
  57  */
  58 int L4_CV
  59 l4vbus_get_next_device(l4_cap_idx_t vbus, l4vbus_device_handle_t parent,
  60                        l4vbus_device_handle_t *child, int depth,
  61                        l4vbus_device_t *devinfo);
  62
  63 /**
  64  * \brief Iterate over the resources of a device
  65  *
  66  * \param  vbus         Capability of the system bus
  67  * \param  dev          Handle of the device
  68  * \retval res_idx      Index of the resource, the number of resources is
  69  *                      available in the devinfo from get device functions.
  70  * \retval res          Descriptor of the resource
  71  *
  72  * \return 0 on success, else failure
  73  */
  74 int L4_CV
  75 l4vbus_get_resource(l4_cap_idx_t vbus, l4vbus_device_handle_t dev,
  76                     int res_idx, l4vbus_resource_t *res);
  77
  78
  79 /**
  80  * \brief Check if the given device has a compatibility ID (CID) or HID that
  81  *        matches \a cid.
  82  *
  83  * \param  vbus V-BUS capability
  84  * \param  dev  device handle for which the CID shall be tested
  85  * \param  cid  the compatibility ID to test
  86  * \return 1 when the given ID (\a cid) matches the given device (\a dev),
  87  *         0 when the given ID does not match,
  88  *         <0 on error.
  89  */
  90 int L4_CV
  91 l4vbus_is_compatible(l4_cap_idx_t vbus, l4vbus_device_handle_t dev,
  92                      char const *cid);
  93
  94 /**
  95  * \brief Get the HID (hardware identifier) if a device
  96  *
  97  * \param  vbus         Capability of the system bus
  98  * \param  dev          Handle of the device
  99  * \param  hid          Pointer to a buffer for the HID string
 100  * \param  max_len      The size of the buffer (\a hid)
 101  *
 102  * \return the length of the HID string on success, else failure
 103  */
 104 int L4_CV
 105 l4vbus_get_hid(l4_cap_idx_t vbus, l4vbus_device_handle_t dev, char *hid,
 106                unsigned long max_len);
 107
 108 /**
 109  * \brief Request a resource of a specific type
 110  *
 111  * \param  vbus         Capability of the system bus
 112  * \param  res          Descriptor of the resource
 113  * \param  flags        Optional flags
 114  *
 115  * \return 0 on success, else failure
 116  *
 117  * If any resource is found that contains the requested
 118  * type and addresses this resource is returned.
 119  *
 120  * Flags are only relevant to control the memory caching.
 121  * If io-memory is requested.
 122  *
 123  * \return 0 on success, else failure
 124  */
 125 int L4_CV
 126 l4vbus_request_resource(l4_cap_idx_t vbus, l4vbus_resource_t *res,
 127                         int flags);
 128
 129 /**
 130  * \brief Release a previously requested resource
 131  *
 132  * \param  vbus         Capability of the system bus.
 133  * \param  res          Descriptor of the resource.
 134  *
 135  * \return 0 on success, else failure
 136  */
 137 int L4_CV
 138 l4vbus_release_resource(l4_cap_idx_t vbus, l4vbus_resource_t *res);
 139
 140 /**
 141  * \brief Get capability of ICU.
 142  *
 143  * \param  vbus         Capability of the system bus.
 144  * \param  icu          ICU device handle.
 145  * \param  cap          Capability slot for the capability.
 146  *
 147  * \return 0 on success, else failure
 148  */
 149 int L4_CV
 150 l4vbus_vicu_get_cap(l4_cap_idx_t vbus, l4vbus_device_handle_t icu,
 151                     l4_cap_idx_t cap);
 152
 153 __END_DECLS
 154
 155 /** \} */