l4/pkg/libirq/include/irq.h

   1 /**
   2  * \file
   3  * \brief IRQ handling routines.
   4  */
   5 /*
   6  * (c) 2008-2009 Technische Universität Dresden
   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/sys/types.h>
  15
  16 __BEGIN_DECLS
  17
  18 /**
  19  * \defgroup l4irq_api IRQ handling library
  20  *
  21  * \defgroup l4irq_api_irq Interface using direct functionality.
  22  * \ingroup l4irq_api
  23  */
  24
  25 struct l4irq_t;
  26 typedef struct l4irq_t l4irq_t;
  27
  28 /**
  29  * \brief Attach/connect to IRQ.
  30  * \ingroup l4irq_api_irq
  31  *
  32  * \param  irqnum          IRQ number to request
  33  * \return Pointer to l4irq_t structure, 0 on error
  34  *
  35  * This l4irq_attach has to be called in the same thread as
  36  * l4irq_wait and caller has to be a pthread thread.
  37  */
  38 L4_CV l4irq_t *
  39 l4irq_attach(int irqnum);
  40
  41 /**
  42  * \brief Attach/connect to IRQ using given type.
  43  * \ingroup l4irq_api_irq
  44  *
  45  * \param  irqnum          IRQ number to request
  46  * \param  flow_type       Interrupt type, \see L4_irq_flow_type
  47  * \return Pointer to l4irq_t structure, 0 on error
  48  *
  49  * This l4irq_attach has to be called in the same thread as
  50  * l4irq_wait and caller has to be a pthread thread.
  51  */
  52 L4_CV l4irq_t *
  53 l4irq_attach_ft(int irqnum, unsigned flow_type);
  54
  55 /**
  56  * \brief Attach/connect to IRQ.
  57  * \ingroup l4irq_api_irq
  58  *
  59  * \param  irqnum          IRQ number to request
  60  * \param  to_thread       Attach IRQ to this specified thread.
  61  * \return Pointer to l4irq_t structure, 0 on error
  62  *
  63  * The pointer to the IRQ structure is used as a label in the IRQ object.
  64  */
  65 L4_CV l4irq_t *
  66 l4irq_attach_thread(int irqnum, l4_cap_idx_t to_thread);
  67
  68 /**
  69  * \brief Attach/connect to IRQ using given type.
  70  * \ingroup l4irq_api_irq
  71  *
  72  * \param  irqnum          IRQ number to request
  73  * \param  to_thread       Attach IRQ to this specified thread.
  74  * \param  flow_type       Interrupt type, \see L4_irq_flow_type
  75  * \return Pointer to l4irq_t structure, 0 on error
  76  *
  77  * The pointer to the IRQ structure is used as a label in the IRQ object.
  78  */
  79 L4_CV l4irq_t *
  80 l4irq_attach_thread_ft(int irqnum, l4_cap_idx_t to_thread,
  81                        unsigned flow_type);
  82
  83 /**
  84  * \brief Wait for specified IRQ.
  85  * \ingroup l4irq_api_irq
  86  *
  87  * \param irq  IRQ data structure
  88  * \return 0 on success, != 0 on error
  89  */
  90 L4_CV long
  91 l4irq_wait(l4irq_t *irq);
  92
  93 /**
  94  * \brief Unmask a specific IRQ and wait for any attached IRQ.
  95  * \ingroup l4irq_api_irq
  96  *
  97  * \param  unmask_irq  IRQ data structure for unmask.
  98  * \retval ret_irq     Received interrupt.
  99  * \return 0 on success, != 0 on error
 100  */
 101 L4_CV long
 102 l4irq_unmask_and_wait_any(l4irq_t *unmask_irq, l4irq_t **ret_irq);
 103
 104 /**
 105  * \brief Wait for any attached IRQ.
 106  * \ingroup l4irq_api_irq
 107  *
 108  * \retval irq     Received interrupt.
 109  * \return 0 on success, != 0 on error
 110  */
 111 L4_CV long
 112 l4irq_wait_any(l4irq_t **irq);
 113
 114 /**
 115  * \brief Unmask a specific IRQ.
 116  * \ingroup l4irq_api_irq
 117  *
 118  * \param irq  IRQ data structure
 119  * \return 0 on success, != 0 on error
 120  *
 121  * This function is useful if a thread wants to wait for multiple IRQs using
 122  * l4_ipc_wait.
 123  */
 124 L4_CV long
 125 l4irq_unmask(l4irq_t *irq);
 126
 127 /**
 128  * \brief Detach from IRQ.
 129  * \ingroup l4irq_api_irq
 130  *
 131  * \param irq  IRQ data structure
 132  * \return 0 on success, != 0 on error
 133  */
 134 L4_CV long
 135 l4irq_detach(l4irq_t *irq);
 136
 137
 138
 139 /***********************************************************************/
 140 /**
 141  * \defgroup l4irq_api_async Interface for asynchronous ISR handlers.
 142  * \ingroup l4irq_api
 143  *
 144  * This interface has just two (main) functions. l4irq_request to install a
 145  * handler for an interrupt and l4irq_release to uninstall the handler again
 146  * and release all resources associated with it.
 147  */
 148
 149 /**
 150  * \brief Attach asychronous ISR handler to IRQ.
 151  * \ingroup l4irq_api_async
 152  *
 153  * \param irqnum          IRQ number to request
 154  * \param isr_handler     Handler routine that is called when an interrupt triggers
 155  * \param isr_data        Pointer given as argument to isr_handler
 156  * \param irq_thread_prio L4 thread priority of the ISR handler. Give -1 for same priority as creator.
 157  * \param flow_type       Interrupt type, \see L4_irq_flow_type
 158  *
 159  * \return Pointer to l4irq_t structure, 0 on error
 160  */
 161 L4_CV l4irq_t *
 162 l4irq_request(int irqnum, void (*isr_handler)(void *), void *isr_data,
 163               int irq_thread_prio, unsigned flow_type);
 164
 165 /**
 166  * \brief Release asynchronous ISR handler and free resources.
 167  * \ingroup l4irq_api_async
 168  *
 169  * \param irq  IRQ data structure
 170  * \return 0 sucess, != 0 failure
 171  */
 172 L4_CV long
 173 l4irq_release(l4irq_t *irq);
 174
 175
 176
 177 /***********************************************************************/
 178 /***********************************************************************/
 179
 180 /**
 181  * \defgroup l4irq_api_irq_cap Interface using direct functionality.
 182  * \ingroup l4irq_api_irq
 183  */
 184
 185 /**
 186  * \brief Attach/connect to IRQ.
 187  * \ingroup l4irq_api_irq_cap
 188  *
 189  * \param  irqcap          IRQ capability
 190  * \return Pointer to l4irq_t structure, 0 on error
 191  *
 192  * This l4irq_attach has to be called in the same thread as
 193  * l4irq_wait and caller has to be a pthread thread.
 194  */
 195 L4_CV l4irq_t *
 196 l4irq_attach_cap(l4_cap_idx_t irqcap);
 197
 198 /**
 199  * \brief Attach/connect to IRQ using given type.
 200  * \ingroup l4irq_api_irq_cap
 201  *
 202  * \param  irqcap          IRQ capability
 203  * \param  flow_type       Interrupt type, \see L4_irq_flow_type
 204  * \return Pointer to l4irq_t structure, 0 on error
 205  *
 206  * This l4irq_attach has to be called in the same thread as
 207  * l4irq_wait and caller has to be a pthread thread.
 208  */
 209 L4_CV l4irq_t *
 210 l4irq_attach_cap_ft(l4_cap_idx_t irqcap, unsigned flow_type);
 211
 212 /**
 213  * \brief Attach/connect to IRQ.
 214  * \ingroup l4irq_api_irq_cap
 215  *
 216  * \param  irqcap          IRQ capability
 217  * \param  to_thread       Attach IRQ to this thread.
 218  * \return Pointer to l4irq_t structure, 0 on error
 219  *
 220  * The pointer to the IRQ structure is used as a label in the IRQ object.
 221  */
 222 L4_CV l4irq_t *
 223 l4irq_attach_thread_cap(l4_cap_idx_t irqcap, l4_cap_idx_t to_thread);
 224
 225 /**
 226  * \brief Attach/connect to IRQ using given type.
 227  * \ingroup l4irq_api_irq_cap
 228  *
 229  * \param  irqcap          IRQ capability
 230  * \param  to_thread       Attach IRQ to this thread.
 231  * \param  flow_type       Interrupt type, \see L4_irq_flow_type
 232  * \return Pointer to l4irq_t structure, 0 on error
 233  *
 234  * The pointer to the IRQ structure is used as a label in the IRQ object.
 235  */
 236 L4_CV l4irq_t *
 237 l4irq_attach_thread_cap_ft(l4_cap_idx_t irqcap, l4_cap_idx_t to_thread,
 238                            unsigned flow_type);
 239
 240 /***********************************************************************/
 241 /**
 242  * \defgroup l4irq_api_async_cap Interface for asynchronous ISR handlers with a given IRQ capability.
 243  * \ingroup l4irq_api_async
 244  *
 245  * This group is just an enhanced version to l4irq_request() which takes a
 246  * capability object instead of a plain number.
 247  */
 248
 249 /**
 250  * \brief Attach asychronous ISR handler to IRQ.
 251  * \ingroup l4irq_api_async_cap
 252  *
 253  * \param irqcap          IRQ capability
 254  * \param isr_handler     Handler routine that is called when an interrupt triggers
 255  * \param isr_data        Pointer given as argument to isr_handler
 256  * \param irq_thread_prio L4 thread priority of the ISR handler. Give -1 for same priority as creator.
 257  * \param flow_type       Interrupt type, \see L4_irq_flow_type
 258  *
 259  * \return Pointer to l4irq_t structure, 0 on error
 260  */
 261 L4_CV l4irq_t *
 262 l4irq_request_cap(l4_cap_idx_t irqcap,
 263                   void (*isr_handler)(void *), void *isr_data,
 264                   int irq_thread_prio, unsigned flow_type);
 265
 266 __END_DECLS