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

4.104.114.95
Last change on this file since 075d817 was 075d817, checked in by Thomas Doerfler <Thomas.Doerfler@…>, on Jul 24, 2008 at 12:45:23 PM

New function rtems_interrupt_handler_iterate()
for system information and diagnostics

  • Property mode set to 100644
File size: 5.6 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup rtems_interrupt_extension
5 *
6 * @brief Header file for the RTEMS 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 found in the file
20 * LICENSE in this distribution or at http://www.rtems.com/license/LICENSE.
21 */
22
23#ifndef RTEMS_IRQ_EXTENSION_H
24#define RTEMS_IRQ_EXTENSION_H
25
26#include <rtems.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif /* __cplusplus */
31
32/**
33 * @defgroup rtems_interrupt_extension RTEMS Interrupt Manager Extension
34 *
35 * @ingroup ClassicINTR
36 *
37 * In addition to the classic API interrupt handler with a handle are
38 * supported.  You can also install multiple shared handler for one interrupt
39 * vector.
40 *
41 * @{
42 */
43
44/**
45 * @brief Interrupt handler routine type.
46 */
47typedef void (*rtems_interrupt_handler)( rtems_vector_number, void *);
48
49/**
50 * @brief Installs the interrupt handler routine @a handler for the interrupt
51 * vector with number @a vector.
52 *
53 * You can set some @ref rtems_interrupt_extension_options "options" with @a
54 * options for the interrupt handler.
55 *
56 * The handler routine shall be called with argument @a arg when dispatched.
57 * The order in which the shared interrupt handlers are dispatched for one
58 * vector is BSP dependent.
59 *
60 * If the option @ref RTEMS_INTERRUPT_UNIQUE is set then it shall be ensured
61 * that this handler will be the only one for this vector.
62 *
63 * You can provide an informative description @a info.  This may be used for
64 * system debugging and status tools.  The string has to be persistent during
65 * the handler life time.
66 *
67 * @note This function may block.
68 *
69 * @return
70 * - On success RTEMS_SUCCESSFUL shall be returned.
71 * - If the vector is already occupied with a unique handler the
72 * RTEMS_RESOURCE_IN_USE status code shall be returned.
73 * - If you want to install a unique handler and there is already a handler
74 * installed RTEMS_RESOURCE_IN_USE shall be returned.
75 * - If this function is called within interrupt context RTEMS_CALLED_FROM_ISR
76 * shall be returned.
77 * - If the vector number is out of range RTEMS_INVALID_NUMBER shall be
78 * returned.
79 * - If the handler address is NULL a RTEMS_INVALID_ADDRESS shall be returned.
80 * - If a handler with this argument is already installed for this vector
81 * RTEMS_TOO_MANY shall be returned.
82 * - Other error states are BSP specific.
83 */
84rtems_status_code rtems_interrupt_handler_install(
85  rtems_vector_number vector,
86  const char *info,
87  rtems_option options,
88  rtems_interrupt_handler handler,
89  void *arg
90);
91
92/**
93 * @brief Removes the interrupt handler routine @a handler with argument @a arg
94 * for the interrupt vector with number @a vector.
95 *
96 * @note This function may block.
97 *
98 * @return
99 * - On success RTEMS_SUCCESSFUL shall be returned.
100 * - If this function is called within interrupt context RTEMS_CALLED_FROM_ISR
101 * shall be returned.
102 * - If the vector number is out of range RTEMS_INVALID_NUMBER shall be
103 * returned.
104 * - If the handler address is NULL a RTEMS_INVALID_ADDRESS shall be returned.
105 * - If the handler with this argument is not installed for this vector
106 * RTEMS_UNSATISFIED shall be returned.
107 * - Other error states are BSP specific.
108 */
109rtems_status_code rtems_interrupt_handler_remove(
110  rtems_vector_number vector,
111  rtems_interrupt_handler handler,
112  void *arg
113);
114
115/**
116 * @brief Interrupt handler iteration routine type.
117 *
118 * @see rtems_interrupt_handler_iterate()
119 */
120typedef void (*rtems_interrupt_per_handler_routine)(
121  void *, const char *, rtems_option, rtems_interrupt_handler, void *
122);
123
124/**
125 * @brief Iterates over all installed interrupt handler of the interrupt vector
126 * with number @a vector.
127 *
128 * For each installed handler of the vector the function @a routine will be
129 * called with the supplied argument @a arg and the handler information,
130 * options, routine and argument.
131 *
132 * This function is intended for system information and diagnostics.
133 *
134 * @note This function may block.  Never install or remove an interrupt handler
135 * within the iteration routine.  This may result in a deadlock.
136 *
137 * @return
138 * - On success RTEMS_SUCCESSFUL shall be returned.
139 * - If this function is called within interrupt context RTEMS_CALLED_FROM_ISR
140 * shall be returned.
141 * - If the vector number is out of range RTEMS_INVALID_NUMBER shall be
142 * returned.
143 * - Other error states are BSP specific.
144 */
145rtems_status_code rtems_interrupt_handler_iterate(
146  rtems_vector_number vector,
147  rtems_interrupt_per_handler_routine routine,
148  void *arg
149);
150
151/** @} */
152
153/**
154 * @defgroup rtems_interrupt_extension_options Interrupt Handler Options
155 *
156 * @ingroup rtems_interrupt_extension
157 *
158 * @{
159 */
160
161/**
162 * @name Options
163 *
164 * @{
165 */
166
167/**
168 * @brief Makes the interrupt handler unique.  Prevents other handler from
169 * using the same interrupt vector.
170 */
171#define RTEMS_INTERRUPT_UNIQUE ((rtems_option) 0x00000001)
172
173/**
174 * @brief Allows that this interrupt handler may share a common interrupt
175 * vector with other handler.
176 */
177#define RTEMS_INTERRUPT_SHARED ((rtems_option) 0x00000000)
178
179/** @} */
180
181/**
182 * @name Option Set Checks
183 *
184 * @{
185 */
186
187/**
188 * @brief Returns true if the interrupt handler unique option is set.
189 */
190#define RTEMS_INTERRUPT_IS_UNIQUE( options) \
191  ((options) & RTEMS_INTERRUPT_UNIQUE)
192
193/**
194 * @brief Returns true if the interrupt handler shared option is set.
195 */
196#define RTEMS_INTERRUPT_IS_SHARED( options) \
197  (!RTEMS_INTERRUPT_IS_UNIQUE( options))
198
199/** @} */
200
201/** @} */
202
203#ifdef __cplusplus
204}
205#endif /* __cplusplus */
206
207#endif /* RTEMS_IRQ_EXTENSION_H */
Note: See TracBrowser for help on using the repository browser.