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

4.11
Last change on this file since 0e27119 was 0e27119, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 11, 2012 at 8:52:18 PM

Use proper 3 line form of license text

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