l4/pkg/libio-io/include/io.h

   1 /**
   2  * \file
   3  */
   4 /*
   5  * (c) 2008-2010 Adam Lackorzynski <adam@os.inf.tu-dresden.de>,
   6  *               Alexander Warg <warg@os.inf.tu-dresden.de>
   7  *     economic rights: Technische Universität Dresden (Germany)
   8  * This file is part of TUD:OS and distributed under the terms of the
   9  * GNU Lesser General Public License 2.1.
  10  * Please see the COPYING-LGPL-2.1 file for details.
  11  */
  12
  13
  14 #pragma once
  15
  16 #include <l4/sys/types.h>
  17 #include <l4/sys/linkage.h>
  18 #include <l4/io/types.h>
  19
  20 EXTERN_C_BEGIN
  21
  22 /**
  23  * \defgroup api_l4io IO interface
  24  */
  25
  26 /**
  27  * \internal
  28  * \brief Request an interrupt.
  29  * \ingroup api_l4io
  30  *
  31  * \param irqnum IRQ number.
  32  * \param irqcap Capability index to attach the IRQ to.
  33  * \return 0 on success, <0 on error
  34  *
  35  * \note This function is internal because libirq is handling IRQs. This
  36  *       is rather the interface to get the IRQ.
  37  */
  38 L4_CV long L4_EXPORT
  39 l4io_request_irq(int irqnum, l4_cap_idx_t irqcap);
  40
  41 /**
  42  * \brief Request the ICU object of the client.
  43  *
  44  * \return Client ICU object, an invalid capability selector is returned if
  45  *         no ICU is available.
  46  */
  47 L4_CV l4_cap_idx_t L4_EXPORT
  48 l4io_request_icu(void);
  49
  50 /**
  51  * \internal
  52  * \brief Release an interrupt.
  53  * \ingroup api_l4io
  54  *
  55  * \param irqnum IRQ number.
  56  * \return 0 on success, <0 on error
  57  *
  58  * \note This function is internal because libirq is handling IRQs. This
  59  *       is rather the interface to return the IRQ.
  60  */
  61 L4_CV long L4_EXPORT
  62 l4io_release_irq(int irqnum, l4_cap_idx_t irq_cap);
  63
  64 /**
  65  * \brief Request an IO memory region.
  66  * \ingroup api_l4io
  67  * \param phys   Physical address of the I/O memory region
  68  * \param size   Size of the region in Bytes, granularity pages.
  69  * \param flags  See #l4io_iomem_flags_t
  70  * \retval virt  Virtual address the region is available at.
  71  * \return 0 on success, <0 on error
  72  *
  73  * \note This function uses L4Re functionality to reserve a part of the
  74  *       virtual address space of the caller.
  75  */
  76 L4_CV long L4_EXPORT
  77 l4io_request_iomem(l4_addr_t phys, unsigned long size, int flags,
  78                    l4_addr_t *virt);
  79
  80 /**
  81  * \brief Request an IO memory region and map to a specified region.
  82  * \ingroup api_l4io
  83  * \param phys   Physical address of the I/O memory region
  84  * \param virt   Virtual address.
  85  * \param size   Size of the region in Bytes, granularity pages.
  86  * \param flags  See #l4io_iomem_flags_t
  87  * \return 0 on success, <0 on error
  88  *
  89  * \note This function uses L4Re functionality to reserve a part of the
  90  *       virtual address space of the caller.
  91  */
  92 L4_CV long L4_EXPORT
  93 l4io_request_iomem_region(l4_addr_t phys, l4_addr_t virt,
  94                           unsigned long size, int flags);
  95
  96 /**
  97  * \brief Release an IO memory region.
  98  * \ingroup api_l4io
  99  * \param virt  Virtual address of region to free, see #l4io_request_iomem
 100  * \param size  Size of the region to release.
 101  * \return 0 on success, <0 on error
 102  */
 103 L4_CV long L4_EXPORT
 104 l4io_release_iomem(l4_addr_t virt, unsigned long size);
 105
 106 /**
 107  * \brief Search for a IO memory region.
 108  * \ingroup api_l4io
 109  * \param   phys   Physical address to look for
 110  * \param   size   Size of requested memory area
 111  * \retval  rstart Start address for region
 112  * \retval  rsize  Size of region in bytes
 113  * \return 0 if an IO region was found, <0 if not
 114  */
 115 L4_CV long L4_EXPORT
 116 l4io_search_iomem_region(l4_addr_t phys, l4_addr_t size,
 117                          l4_addr_t *rstart, l4_addr_t *rsize);
 118
 119 /**
 120  * \brief Request an IO port region.
 121  * \ingroup api_l4io
 122  * \param portnum  Start of port range to request
 123  * \param len      Length of range to request
 124  * \return 0 on success, <0 on error
 125  *
 126  * \note X86 architecture only
 127  */
 128 L4_CV long L4_EXPORT
 129 l4io_request_ioport(unsigned portnum, unsigned len);
 130
 131 /**
 132  * \brief Release an IO port region.
 133  * \ingroup api_l4io
 134  * \param portnum  Start of port range to release
 135  * \param len      Length of range to request
 136  * \return 0 on success, <0 on error
 137  *
 138  * \note X86 architecture only
 139  */
 140 L4_CV long L4_EXPORT
 141 l4io_release_ioport(unsigned portnum, unsigned len);
 142
 143
 144
 145
 146
 147 /* -------------- Device handling --------------------- */
 148
 149 /**
 150  * \brief Get root device handle of the device bus.
 151  *
 152  * \return root device handle
 153  */
 154 L4_INLINE
 155 l4io_device_handle_t l4io_get_root_device(void);
 156
 157 /**
 158  * \brief Iterate over the device bus.
 159  *
 160  * \param  devhandle   Device handle to start iterating at
 161  * \retval devhandle   Next device handle
 162  * \retval dev         Device information, may be NULL
 163  * \retval reshandle   Resource handle.
 164  * \return 0 on success, error code otherwise
 165  */
 166 L4_CV int L4_EXPORT
 167 l4io_iterate_devices(l4io_device_handle_t *devhandle,
 168                      l4io_device_t *dev, l4io_resource_handle_t *reshandle);
 169
 170 /**
 171  * \brief Find a device by name.
 172  * \ingroup api_l4io
 173  *
 174  * \param  devname    Name of device
 175  * \retval dev_handle Device handle for found device, can be NULL.
 176  * \retval dev        Device information, filled by the function, can be NULL.
 177  * \retval res_handle Resource handle, can be NULL.
 178  *
 179  * \return 0 on success, error code otherwise
 180  */
 181 L4_CV int L4_EXPORT
 182 l4io_lookup_device(const char *devname,
 183                    l4io_device_handle_t *dev_handle,
 184                    l4io_device_t *dev, l4io_resource_handle_t *res_handle);
 185
 186 /**
 187  * \brief Request a specific resource from a device description.
 188  * \ingroup api_l4io
 189  *
 190  * \param  devhandle Device handle.
 191  * \param  type      Type of resource to request (see \#l4io_resource_types_t)
 192  * \param  reshandle Resource handle,
 193  *                   start with handle returned by device functions.
 194  * \retval reshandle Next resource handle.
 195  * \retval res       Device descriptor
 196  *
 197  * \return 0 on success, error code otherwise, esp. -L4_ENOENT if no more
 198  *         resources found
 199  */
 200 L4_CV int L4_EXPORT
 201 l4io_lookup_resource(l4io_device_handle_t devhandle,
 202                      enum l4io_resource_types_t type,
 203                      l4io_resource_handle_t *reshandle,
 204                      l4io_resource_t *res);
 205
 206
 207 /* --------------- Convenience functions ----------------- */
 208
 209 /**
 210  * \brief Request IO memory.
 211  * \ingroup api_l4io
 212  *
 213  * \param  devhandle Device handle.
 214  * \retval reshandle Resource handle, input and ouput, return next resource
 215  *                   handle
 216  *
 217  * \return 0 on error, virtual address otherwise
 218  */
 219 L4_CV l4_addr_t L4_EXPORT
 220 l4io_request_resource_iomem(l4io_device_handle_t devhandle,
 221                             l4io_resource_handle_t *reshandle);
 222
 223 /**
 224  * \brief Request all available IO-port resources.
 225  */
 226 L4_CV void L4_EXPORT
 227 l4io_request_all_ioports(void);
 228
 229
 230 L4_INLINE
 231 l4io_device_handle_t l4io_get_root_device(void)
 232 { return 0; }
 233
 234 EXTERN_C_END