summaryrefslogtreecommitdiffstats
path: root/c/src/lib/libbsp/shared/include/irq-generic.h
blob: 686c28fa74f78627c3ef7a0682d59c30bae2f47e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
/**
 * @file
 *
 * @ingroup bsp_interrupt
 *
 * @brief Header file for generic BSP interrupt support.
 */

/*
 * Based on concepts of Pavel Pisa, Till Straumann and Eric Valette. 
 *
 * Copyright (c) 2008
 * Embedded Brains GmbH
 * Obere Lagerstr. 30
 * D-82178 Puchheim
 * Germany
 * rtems@embedded-brains.de
 *
 * The license and distribution terms for this file may be found in the file
 * LICENSE in this distribution or at http://www.rtems.com/license/LICENSE.
 */

#ifndef LIBBSP_SHARED_IRQ_GENERIC_H
#define LIBBSP_SHARED_IRQ_GENERIC_H

#include <stdbool.h>

#include <rtems/irq-extension.h>

#include <bsp/irq-config.h>

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

#if !defined( BSP_INTERRUPT_VECTOR_MIN) || !defined( BSP_INTERRUPT_VECTOR_MAX) || (BSP_INTERRUPT_VECTOR_MAX + 1) < BSP_INTERRUPT_VECTOR_MIN
#error Invalid BSP_INTERRUPT_VECTOR_MIN or BSP_INTERRUPT_VECTOR_MAX.
#endif /* !defined( BSP_INTERRUPT_VECTOR_MIN) ... */

#if defined( BSP_INTERRUPT_USE_INDEX_TABLE) && !defined( BSP_INTERRUPT_HANDLER_TABLE_SIZE)
#error If you define BSP_INTERRUPT_USE_INDEX_TABLE, you have to define BSP_INTERRUPT_HANDLER_TABLE_SIZE etc. as well.
#endif /* defined( BSP_INTERRUPT_USE_INDEX_TABLE) ... */

#if defined( BSP_INTERRUPT_NO_HEAP_USAGE) && !defined( BSP_INTERRUPT_USE_INDEX_TABLE)
#error If you define BSP_INTERRUPT_NO_HEAP_USAGE, you have to define BSP_INTERRUPT_USE_INDEX_TABLE etc. as well.
#endif /* defined( BSP_INTERRUPT_NO_HEAP_USAGE) ... */

#define BSP_INTERRUPT_VECTOR_NUMBER (BSP_INTERRUPT_VECTOR_MAX - BSP_INTERRUPT_VECTOR_MIN + 1)

#ifndef BSP_INTERRUPT_HANDLER_TABLE_SIZE
#define BSP_INTERRUPT_HANDLER_TABLE_SIZE BSP_INTERRUPT_VECTOR_NUMBER
#endif /* BSP_INTERRUPT_HANDLER_TABLE_SIZE */

struct bsp_interrupt_handler_entry {
	rtems_interrupt_handler handler;
	void *arg;
	const char *info;
	struct bsp_interrupt_handler_entry *next;
};

typedef struct bsp_interrupt_handler_entry bsp_interrupt_handler_entry;

extern bsp_interrupt_handler_entry bsp_interrupt_handler_table [];

#ifdef BSP_INTERRUPT_USE_INDEX_TABLE
extern bsp_interrupt_handler_index_type bsp_interrupt_handler_index_table [];
#endif /* BSP_INTERRUPT_USE_INDEX_TABLE */

static inline rtems_vector_number bsp_interrupt_handler_index( rtems_vector_number vector)
{
#ifdef BSP_INTERRUPT_USE_INDEX_TABLE
	return bsp_interrupt_handler_index_table [vector - BSP_INTERRUPT_VECTOR_MIN];
#else /* BSP_INTERRUPT_USE_INDEX_TABLE */
	return vector - BSP_INTERRUPT_VECTOR_MIN;
#endif /* BSP_INTERRUPT_USE_INDEX_TABLE */
}

/**
 * @defgroup bsp_interrupt BSP Interrupt Support
 *
 * @ingroup rtems_interrupt_extension
 *
 * The BSP interrupt support manages a sequence of interrupt vector numbers
 * ranging from @ref BSP_INTERRUPT_VECTOR_MIN to @ref BSP_INTERRUPT_VECTOR_MAX
 * including the end points.  It provides methods to @ref
 * bsp_interrupt_handler_install() "install", @ref
 * bsp_interrupt_handler_remove() "remove" and @ref
 * bsp_interrupt_handler_dispatch() "dispatch" interrupt handlers for each
 * vector number.  It implements parts of the RTEMS interrupt manager.
 *
 * The entry points to a list of interrupt handlers are stored in a table
 * (= handler table).
 *
 * You have to configure the BSP interrupt support in the bsp/irq-config.h file
 * for each BSP.  For a minimum configuration you have to provide @ref
 * BSP_INTERRUPT_VECTOR_MIN and @ref BSP_INTERRUPT_VECTOR_MAX.
 *
 * For boards with small memory requirements you can define @ref
 * BSP_INTERRUPT_USE_INDEX_TABLE.  With an enabled index table the handler
 * table will be accessed via a small index table.  You can define the size of
 * the handler table with @ref BSP_INTERRUPT_HANDLER_TABLE_SIZE.  You must
 * provide a data type for the index table (@ref
 * bsp_interrupt_handler_index_type).  It must be an integer type big enough to
 * index the complete handler table.
 *
 * Normally new list entries are allocated from the heap.  You may define @ref
 * BSP_INTERRUPT_NO_HEAP_USAGE, if you do not want to use the heap.  For this
 * option you have to define @ref BSP_INTERRUPT_USE_INDEX_TABLE as well.
 *
 * You have to provide some special routines in your BSP (follow the links for
 * the details):
 * - bsp_interrupt_facility_initialize()
 * - bsp_interrupt_vector_enable()
 * - bsp_interrupt_vector_disable()
 * - bsp_interrupt_handler_default()
 *
 * The following now deprecated functions are provided for backward
 * compatibility:
 * - BSP_get_current_rtems_irq_handler()
 * - BSP_install_rtems_irq_handler()
 * - BSP_install_rtems_shared_irq_handler()
 * - BSP_remove_rtems_irq_handler()
 * - BSP_rtems_irq_mngt_set()
 * - BSP_rtems_irq_mngt_get()
 *
 * @{
 */

/**
 * @brief Returns true if the interrupt vector with number @a vector is valid.
 */
static inline bool bsp_interrupt_is_valid_vector( rtems_vector_number vector)
{
	return (rtems_vector_number) BSP_INTERRUPT_VECTOR_MIN <= vector
		&& vector <= (rtems_vector_number) BSP_INTERRUPT_VECTOR_MAX;
}

/**
 * @brief Default interrupt handler.
 *
 * This routine will be called from bsp_interrupt_handler_dispatch() with the
 * current vector number @a vector when the handler list for this vector is
 * empty or the vector number is out of range.
 *
 * @note This function must cope with arbitrary vector numbers @a vector.
 */
void bsp_interrupt_handler_default( rtems_vector_number vector);

rtems_status_code bsp_interrupt_initialize( void);

/**
 * @brief BSP specific initialization.
 *
 * This routine will be called form bsp_interrupt_initialize() and shall do the
 * following:
 * - Initialize the facilities that call bsp_interrupt_handler_dispatch().  For
 * example on PowerPC the external exception handler.
 * - Initialize the interrupt controller.  You shall set the interrupt
 * controller in a state such that interrupts are disabled for all vectors.
 * The vectors will be enabled with your bsp_interrupt_vector_enable() function
 * and disabled via your bsp_interrupt_vector_disable() function.  These
 * functions have to work afterwards.
 *
 * @return On success RTEMS_SUCCESSFUL shall be returned.
 */
rtems_status_code bsp_interrupt_facility_initialize( void);

/**
 * @brief Enables the interrupt vector with number @a vector.
 *
 * This function shall enable the vector at the corresponding facility (in most
 * cases the interrupt controller).  It will be called then the first handler
 * is installed for the vector in bsp_interrupt_handler_install().  For a
 * vector out of range this function shall do nothing except returning
 * RTEMS_SUCCESSFUL.
 *
 * @note You must not install or remove an interrupt handler in this function.
 * This may result in a deadlock.
 *
 * @return On success RTEMS_SUCCESSFUL shall be returned.
 */
rtems_status_code bsp_interrupt_vector_enable( rtems_vector_number vector);

/**
 * @brief Disables the interrupt vector with number @a vector.
 *
 * This function shall disable the vector at the corresponding facility (in
 * most cases the interrupt controller).  It will be called then the last
 * handler is removed for the vector in bsp_interrupt_handler_remove().  For a
 * vector out of range this function shall do nothing except returning
 * RTEMS_SUCCESSFUL.
 *
 * @note You must not install or remove an interrupt handler in this function.
 * This may result in a deadlock.
 *
 * @return On success RTEMS_SUCCESSFUL shall be returned.
 */
rtems_status_code bsp_interrupt_vector_disable( rtems_vector_number vector);

/**
 * @brief Sequencially calls all interrupt handlers for the vector number @a
 * vector.
 *
 * If the vector number is out of range or the handler list is empty
 * bsp_interrupt_handler_default() will be called with argument @a vector.
 *
 * You can call this function within every context which can be disabled via
 * rtems_interrupt_disable().
 */
static inline void bsp_interrupt_handler_dispatch( rtems_vector_number vector)
{
	if (bsp_interrupt_is_valid_vector( vector)) {
		bsp_interrupt_handler_entry *e = &bsp_interrupt_handler_table [bsp_interrupt_handler_index( vector)];

		do {
			e->handler( vector, e->arg);
			e = e->next;
		} while (e != NULL);
	} else {
		bsp_interrupt_handler_default( vector);
	}
}

/** @} */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* LIBBSP_SHARED_IRQ_GENERIC_H */