source: rtems/cpukit/include/rtems/irq-extension.h @ b697bc6

4.115
Last change on this file since b697bc6 was b697bc6, checked in by Joel Sherrill <joel.sherrill@…>, on 01/10/13 at 21:06:42

cpukit: Use Consistent Beginning of Doxygen Group Notation

This is the result of a sed script which converts all uses
of @{ into a consistent form.

  • Property mode set to 100644
File size: 8.5 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup rtems_interrupt_extension
5 *
6 * @brief Header file for the Interrupt Manager Extension.
7 */
8
9/*
10 * Based on concepts of Pavel Pisa, Till Straumann and Eric Valette.
11 *
12 * Copyright (c) 2008
13 * Embedded Brains GmbH
14 * Obere Lagerstr. 30
15 * D-82178 Puchheim
16 * Germany
17 * rtems@embedded-brains.de
18 *
19 * The license and distribution terms for this file may be
20 * found in the file LICENSE in this distribution or at
21 * http://www.rtems.com/license/LICENSE.
22 */
23
24#ifndef RTEMS_IRQ_EXTENSION_H
25#define RTEMS_IRQ_EXTENSION_H
26
27#include <rtems.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif /* __cplusplus */
32
33/**
34 * @defgroup rtems_interrupt_extension Interrupt Manager Extension
35 *
36 * @ingroup ClassicINTR
37 *
38 * In addition to the Classic API interrupt handler with a handle are
39 * supported.  You can also install multiple shared handler for one interrupt
40 * vector.
41 */
42/**@{**/
43
44/**
45 * @brief Makes the interrupt handler unique.  Prevents other handler from
46 * using the same interrupt vector.
47 */
48#define RTEMS_INTERRUPT_UNIQUE ((rtems_option) 0x00000001)
49
50/**
51 * @brief Allows that this interrupt handler may share a common interrupt
52 * vector with other handler.
53 */
54#define RTEMS_INTERRUPT_SHARED ((rtems_option) 0x00000000)
55
56/**
57 * @brief Returns true if the interrupt handler unique option is set.
58 */
59#define RTEMS_INTERRUPT_IS_UNIQUE( options) \
60  ((options) & RTEMS_INTERRUPT_UNIQUE)
61
62/**
63 * @brief Returns true if the interrupt handler shared option is set.
64 */
65#define RTEMS_INTERRUPT_IS_SHARED( options) \
66  (!RTEMS_INTERRUPT_IS_UNIQUE( options))
67
68/**
69 * @brief Interrupt handler routine type.
70 */
71typedef void (*rtems_interrupt_handler)(void *);
72
73/**
74 * @brief Installs the interrupt handler routine @a handler for the interrupt
75 * vector with number @a vector.
76 *
77 * You can set one of the mutually exclusive options
78 *
79 * - @ref RTEMS_INTERRUPT_UNIQUE
80 * - @ref RTEMS_INTERRUPT_SHARED
81 *
82 * with the @a options parameter for the interrupt handler.
83 *
84 * The handler routine shall be called with argument @a arg when dispatched.
85 * The order in which the shared interrupt handlers are dispatched for one
86 * vector is BSP dependent.
87 *
88 * If the option @ref RTEMS_INTERRUPT_UNIQUE is set then it shall be ensured
89 * that this handler will be the only one for this vector.
90 *
91 * You can provide an informative description @a info.  This may be used for
92 * system debugging and status tools.  The string has to be persistent during
93 * the handler life time.
94 *
95 * This function may block.
96 *
97 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
98 * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
99 * context this shall be returned.
100 * @retval RTEMS_INVALID_ADDRESS If the handler address is NULL this shall be
101 * returned.
102 * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
103 * returned.
104 * @retval RTEMS_INVALID_NUMBER If an option is not applicable this shall be
105 * returned.
106 * @retval RTEMS_RESOURCE_IN_USE If the vector is already occupied with a
107 * unique handler this shall be returned.  If a unique handler should be
108 * installed and there is already a handler installed this shall be returned.
109 * @retval RTEMS_TOO_MANY If a handler with this argument is already installed
110 * for the vector this shall be returned.
111 * @retval RTEMS_IO_ERROR Reserved for board support package specific error
112 * conditions.
113 */
114rtems_status_code rtems_interrupt_handler_install(
115  rtems_vector_number vector,
116  const char *info,
117  rtems_option options,
118  rtems_interrupt_handler handler,
119  void *arg
120);
121
122/**
123 * @brief Removes the interrupt handler routine @a handler with argument @a arg
124 * for the interrupt vector with number @a vector.
125 *
126 * This function may block.
127 *
128 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
129 * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
130 * context this shall be returned.
131 * @retval RTEMS_INVALID_ADDRESS If the handler address is NULL this shall be
132 * returned.
133 * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
134 * returned.
135 * @retval RTEMS_UNSATISFIED If the handler with its argument is not installed
136 * for the vector this shall be returned.
137 * @retval RTEMS_IO_ERROR Reserved for board support package specific error
138 * conditions.
139 */
140rtems_status_code rtems_interrupt_handler_remove(
141  rtems_vector_number vector,
142  rtems_interrupt_handler handler,
143  void *arg
144);
145
146/**
147 * @brief Interrupt handler iteration routine type.
148 *
149 * @see rtems_interrupt_handler_iterate()
150 */
151typedef void (*rtems_interrupt_per_handler_routine)(
152  void *, const char *, rtems_option, rtems_interrupt_handler, void *
153);
154
155/**
156 * @brief Iterates over all installed interrupt handler of the interrupt vector
157 * with number @a vector.
158 *
159 * For each installed handler of the vector the function @a routine will be
160 * called with the supplied argument @a arg and the handler information,
161 * options, routine and argument.
162 *
163 * This function is intended for system information and diagnostics.
164 *
165 * This function may block.  Never install or remove an interrupt handler
166 * within the iteration routine.  This may result in a deadlock.
167 *
168 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
169 * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
170 * context this shall be returned.
171 * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
172 * returned.
173 * @retval RTEMS_IO_ERROR Reserved for board support package specific error
174 * conditions.
175 */
176rtems_status_code rtems_interrupt_handler_iterate(
177  rtems_vector_number vector,
178  rtems_interrupt_per_handler_routine routine,
179  void *arg
180);
181
182/**
183 * @brief Initializes an interrupt server task.
184 *
185 * The task will have the priority @a priority, the stack size @a stack_size,
186 * the modes @a modes and the attributes @a attributes.  The identifier of the
187 * server task will be returned in @a server.  Interrupt handlers can be
188 * installed on the server with rtems_interrupt_server_handler_install() and
189 * removed with rtems_interrupt_server_handler_remove() using this identifier.
190 * In case of an interrupt the request will be forwarded to the server.  The
191 * handlers are executed within the server context.  If one handler blocks on
192 * something this may delay the processing of other handlers.
193 *
194 * The server identifier pointer @a server may be @a NULL to initialize the
195 * default server.
196 *
197 * This function may block.
198 *
199 * @see rtems_task_create().
200 *
201 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
202 * @retval RTEMS_INCORRECT_STATE If the default server is already initialized
203 * this shall be returned.
204 * @retval RTEMS_IO_ERROR Reserved for board support package specific error
205 * conditions.
206 */
207rtems_status_code rtems_interrupt_server_initialize(
208  rtems_task_priority priority,
209  size_t stack_size,
210  rtems_mode modes,
211  rtems_attribute attributes,
212  rtems_id *server
213);
214
215/**
216 * @brief Installs the interrupt handler routine @a handler for the interrupt
217 * vector with number @a vector on the server @a server.
218 *
219 * The handler routine will be executed on the corresponding interrupt server
220 * task.  A server identifier @a server of @c RTEMS_ID_NONE may be used to
221 * install the handler on the default server.
222 *
223 * This function may block.
224 *
225 * @see rtems_interrupt_handler_install().
226 *
227 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
228 * @retval RTEMS_INCORRECT_STATE If the interrupt handler server is not
229 * initialized this shall be returned.
230 * @retval * For other errors see rtems_interrupt_handler_install().
231 */
232rtems_status_code rtems_interrupt_server_handler_install(
233  rtems_id server,
234  rtems_vector_number vector,
235  const char *info,
236  rtems_option options,
237  rtems_interrupt_handler handler,
238  void *arg
239);
240
241/**
242 * @brief Removes the interrupt handler routine @a handler with argument @a arg
243 * for the interrupt vector with number @a vector from the server @a server.
244 *
245 * A server identifier @a server of @c RTEMS_ID_NONE may be used to remove the
246 * handler from the default server.
247 *
248 * This function may block.
249 *
250 * @see rtems_interrupt_handler_remove().
251 *
252 * @retval RTEMS_SUCCESSFUL Shall be returned in case of success.
253 * @retval RTEMS_INCORRECT_STATE If the interrupt handler server is not
254 * initialized this shall be returned.
255 * @retval * For other errors see rtems_interrupt_handler_remove().
256 */
257rtems_status_code rtems_interrupt_server_handler_remove(
258  rtems_id server,
259  rtems_vector_number vector,
260  rtems_interrupt_handler handler,
261  void *arg
262);
263
264/** @} */
265
266#ifdef __cplusplus
267}
268#endif /* __cplusplus */
269
270#endif /* RTEMS_IRQ_EXTENSION_H */
Note: See TracBrowser for help on using the repository browser.