source: rtems/cpukit/include/rtems/rtems/intr.h @ 85d482f

Last change on this file since 85d482f was 85d482f, checked in by Sebastian Huber <sebastian.huber@…>, on 09/08/22 at 06:09:30

rtems: Include <rtems/score/cpuopts.h>

Directly include <rtems/score/cpuopts.h> in header files using CPU build
options.

  • Property mode set to 100644
File size: 105.4 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @ingroup RTEMSImplClassic
7 *
8 * @brief This header file defines the Interrupt Manager API.
9 */
10
11/*
12 * Copyright (C) 2008, 2022 embedded brains GmbH (http://www.embedded-brains.de)
13 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 * 1. Redistributions of source code must retain the above copyright
19 *    notice, this list of conditions and the following disclaimer.
20 * 2. Redistributions in binary form must reproduce the above copyright
21 *    notice, this list of conditions and the following disclaimer in the
22 *    documentation and/or other materials provided with the distribution.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 * POSSIBILITY OF SUCH DAMAGE.
35 */
36
37/*
38 * This file is part of the RTEMS quality process and was automatically
39 * generated.  If you find something that needs to be fixed or
40 * worded better please post a report or patch to an RTEMS mailing list
41 * or raise a bug report:
42 *
43 * https://www.rtems.org/bugs.html
44 *
45 * For information on updating and regenerating please refer to the How-To
46 * section in the Software Requirements Engineering chapter of the
47 * RTEMS Software Engineering manual.  The manual is provided as a part of
48 * a release.  For development sources please refer to the online
49 * documentation at:
50 *
51 * https://docs.rtems.org
52 */
53
54/* Generated from spec:/rtems/intr/if/header */
55
56#ifndef _RTEMS_RTEMS_INTR_H
57#define _RTEMS_RTEMS_INTR_H
58
59#include <stddef.h>
60#include <stdint.h>
61#include <sys/cpuset.h>
62#include <rtems/rtems/attr.h>
63#include <rtems/rtems/modes.h>
64#include <rtems/rtems/options.h>
65#include <rtems/rtems/status.h>
66#include <rtems/rtems/types.h>
67#include <rtems/score/basedefs.h>
68#include <rtems/score/chain.h>
69#include <rtems/score/cpu.h>
70#include <rtems/score/cpuopts.h>
71#include <rtems/score/isr.h>
72#include <rtems/score/isrlevel.h>
73#include <rtems/score/isrlock.h>
74#include <rtems/score/smplock.h>
75
76#ifdef __cplusplus
77extern "C" {
78#endif
79
80/* Generated from spec:/rtems/intr/if/group */
81
82/**
83 * @defgroup RTEMSAPIClassicIntr Interrupt Manager
84 *
85 * @ingroup RTEMSAPIClassic
86 *
87 * @brief Any real-time executive must provide a mechanism for quick response
88 *   to externally generated interrupts to satisfy the critical time
89 *   constraints of the application.  The Interrupt Manager provides this
90 *   mechanism for RTEMS. This manager permits quick interrupt response times
91 *   by providing the critical ability to alter task execution which allows a
92 *   task to be preempted upon exit from an ISR.
93 */
94
95/* Generated from spec:/rtems/intr/if/vector-number */
96
97/**
98 * @ingroup RTEMSAPIClassicIntr
99 *
100 * @brief This integer type represents interrupt vector numbers.
101 */
102typedef ISR_Vector_number rtems_vector_number;
103
104/* Generated from spec:/rtems/intr/if/level */
105
106/**
107 * @ingroup RTEMSAPIClassicIntr
108 *
109 * @brief This integer type represents interrupt levels.
110 */
111typedef ISR_Level rtems_interrupt_level;
112
113/* Generated from spec:/rtems/intr/if/isr */
114
115/**
116 * @ingroup RTEMSAPIClassicIntr
117 *
118 * @brief This type defines the return type of interrupt service routines.
119 *
120 * This type can be used to document interrupt service routines in the source
121 * code.
122 */
123typedef ISR_Handler rtems_isr;
124
125/* Generated from spec:/rtems/intr/if/isr-entry */
126
127/**
128 * @ingroup RTEMSAPIClassicIntr
129 *
130 * @brief Interrupt service routines installed by rtems_interrupt_catch() shall
131 *   have this type.
132 */
133#if CPU_SIMPLE_VECTORED_INTERRUPTS == TRUE
134  typedef ISR_Handler_entry rtems_isr_entry;
135#else
136  typedef void ( *rtems_isr_entry )( void * );
137#endif
138
139/* Generated from spec:/rtems/intr/if/catch */
140
141/**
142 * @ingroup RTEMSAPIClassicIntr
143 *
144 * @brief Establishes an interrupt service routine.
145 *
146 * @param new_isr_handler is the new interrupt service routine.
147 *
148 * @param vector is the interrupt vector number.
149 *
150 * @param[out] old_isr_handler is the pointer to an ::rtems_isr_entry object.
151 *   When the directive call is successful, the previous interrupt service
152 *   routine established for this interrupt vector will be stored in this
153 *   object.
154 *
155 * This directive establishes an interrupt service routine (ISR) for the
156 * interrupt specified by the ``vector`` number.  The ``new_isr_handler``
157 * parameter specifies the entry point of the ISR.  The entry point of the
158 * previous ISR for the specified vector is returned in ``old_isr_handler``.
159 *
160 * To release an interrupt vector, pass the old handler's address obtained when
161 * the vector was first capture.
162 *
163 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
164 *
165 * @retval ::RTEMS_INVALID_NUMBER The interrupt vector number was illegal.
166 *
167 * @retval ::RTEMS_INVALID_ADDRESS The ``new_isr_handler`` parameter was NULL.
168 *
169 * @retval ::RTEMS_INVALID_ADDRESS The ``old_isr_handler`` parameter was NULL.
170 *
171 * @par Constraints
172 * @parblock
173 * The following constraints apply to this directive:
174 *
175 * * The directive may be called from within interrupt context.
176 *
177 * * The directive may be called from within device driver initialization
178 *   context.
179 *
180 * * The directive may be called from within task context.
181 *
182 * * The directive will not cause the calling task to be preempted.
183 *
184 * * The directive is only available where the target architecture support
185 *   enabled simple vectored interrupts.
186 * @endparblock
187 */
188rtems_status_code rtems_interrupt_catch(
189  rtems_isr_entry     new_isr_handler,
190  rtems_vector_number vector,
191  rtems_isr_entry    *old_isr_handler
192);
193
194#if !defined(RTEMS_SMP)
195  /* Generated from spec:/rtems/intr/if/disable */
196
197  /**
198   * @ingroup RTEMSAPIClassicIntr
199   *
200   * @brief Disables the maskable interrupts on the current processor.
201   *
202   * @param[out] _isr_cookie is a variable of type ::rtems_interrupt_level which
203   *   will be used to save the previous interrupt level.
204   *
205   * This directive disables all maskable interrupts on the current processor and
206   * returns the previous interrupt level in ``_isr_cookie``.
207   *
208   * @par Notes
209   * @parblock
210   * A later invocation of the rtems_interrupt_enable() directive should be used
211   * to restore the previous interrupt level.
212   *
213   * This directive is implemented as a macro which sets the ``_isr_cookie``
214   * parameter.
215   *
216   * @code
217   * #include <rtems.h>
218   *
219   * void local_critical_section( void )
220   * {
221   *   rtems_interrupt_level level;
222   *
223   *   // Please note that the rtems_interrupt_disable() is a macro.  The
224   *   // previous interrupt level (before the maskable interrupts are
225   *   // disabled) is returned here in the level macro parameter.  This
226   *   // would be wrong:
227   *   //
228   *   // rtems_interrupt_disable( &level );
229   *   rtems_interrupt_disable( level );
230   *
231   *   // Here is the critical section: maskable interrupts are disabled
232   *
233   *   {
234   *     rtems_interrupt_level nested_level;
235   *
236   *     rtems_interrupt_disable( nested_level );
237   *
238   *     // Here is a nested critical section
239   *
240   *     rtems_interrupt_enable( nested_level );
241   *   }
242   *
243   *   // Maskable interrupts are still disabled
244   *
245   *   rtems_interrupt_enable( level );
246   * }
247   * @endcode
248   * @endparblock
249   *
250   * @par Constraints
251   * @parblock
252   * The following constraints apply to this directive:
253   *
254   * * The directive may be called from within any runtime context.
255   *
256   * * The directive will not cause the calling task to be preempted.
257   *
258   * * Where the system was built with SMP support enabled, the directive is not
259   *   available.  Its use will result in compiler warnings and linker errors.
260   *   The rtems_interrupt_local_disable() and rtems_interrupt_local_enable()
261   *   directives are available in all build configurations.
262   * @endparblock
263   */
264  #define rtems_interrupt_disable( _isr_cookie ) _ISR_Local_disable( _isr_cookie )
265#endif
266
267#if !defined(RTEMS_SMP)
268  /* Generated from spec:/rtems/intr/if/enable */
269
270  /**
271   * @ingroup RTEMSAPIClassicIntr
272   *
273   * @brief Restores the previous interrupt level on the current processor.
274   *
275   * @param[in] _isr_cookie is the previous interrupt level to restore.  The
276   *   value must be obtained by a previous call to rtems_interrupt_disable() or
277   *   rtems_interrupt_flash().
278   *
279   * This directive restores the interrupt level specified by ``_isr_cookie`` on
280   * the current processor.
281   *
282   * @par Notes
283   * @parblock
284   * The ``_isr_cookie`` parameter value must be obtained by a previous call to
285   * rtems_interrupt_disable() or rtems_interrupt_flash().  Using an otherwise
286   * obtained value is undefined behaviour.
287   *
288   * This directive is unsuitable to enable particular interrupt sources, for
289   * example in an interrupt controller.
290   * @endparblock
291   *
292   * @par Constraints
293   * @parblock
294   * The following constraints apply to this directive:
295   *
296   * * The directive may be called from within any runtime context.
297   *
298   * * The directive will not cause the calling task to be preempted.
299   *
300   * * While at least one maskable interrupt is pending, when the directive
301   *   enables maskable interrupts, the pending interrupts are immediately
302   *   serviced.  The interrupt service routines may unblock higher priority
303   *   tasks which may preempt the calling task.
304   *
305   * * Where the system was built with SMP support enabled, the directive is not
306   *   available.  Its use will result in compiler warnings and linker errors.
307   *   The rtems_interrupt_local_disable() and rtems_interrupt_local_enable()
308   *   directives are available in all build configurations.
309   * @endparblock
310   */
311  #define rtems_interrupt_enable( _isr_cookie ) _ISR_Local_enable( _isr_cookie )
312#endif
313
314#if !defined(RTEMS_SMP)
315  /* Generated from spec:/rtems/intr/if/flash */
316
317  /**
318   * @ingroup RTEMSAPIClassicIntr
319   *
320   * @brief Flashes interrupts on the current processor.
321   *
322   * @param[in,out] _isr_cookie is the previous interrupt level.
323   *
324   * This directive is functionally equivalent to a calling
325   * rtems_interrupt_enable() immediately followed by a
326   * rtems_interrupt_disable().  On some architectures it is possible to provide
327   * an optimized implementation for this sequence.
328   *
329   * @par Notes
330   * @parblock
331   * The ``_isr_cookie`` parameter value must be obtained by a previous call to
332   * rtems_interrupt_disable() or rtems_interrupt_flash().  Using an otherwise
333   * obtained value is undefined behaviour.
334   *
335   * Historically, the interrupt flash directive was heavily used in the
336   * operating system implementation.  However, this is no longer the case.  The
337   * interrupt flash directive is provided for backward compatibility reasons.
338   * @endparblock
339   *
340   * @par Constraints
341   * @parblock
342   * The following constraints apply to this directive:
343   *
344   * * The directive may be called from within any runtime context.
345   *
346   * * The directive will not cause the calling task to be preempted.
347   *
348   * * Where the system was built with SMP support enabled, the directive is not
349   *   available.  Its use will result in compiler warnings and linker errors.
350   *   The rtems_interrupt_local_disable() and rtems_interrupt_local_enable()
351   *   directives are available in all build configurations.
352   * @endparblock
353   */
354  #define rtems_interrupt_flash( _isr_cookie ) _ISR_Local_flash( _isr_cookie )
355#endif
356
357/* Generated from spec:/rtems/intr/if/local-disable */
358
359/**
360 * @ingroup RTEMSAPIClassicIntr
361 *
362 * @brief Disables the maskable interrupts on the current processor.
363 *
364 * @param[out] _isr_cookie is a variable of type ::rtems_interrupt_level which
365 *   will be used to save the previous interrupt level.
366 *
367 * This directive disables all maskable interrupts on the current processor and
368 * returns the previous interrupt level in ``_isr_cookie``.
369 *
370 * @par Notes
371 * @parblock
372 * A later invocation of the rtems_interrupt_local_enable() directive should be
373 * used to restore the previous interrupt level.
374 *
375 * This directive is implemented as a macro which sets the ``_isr_cookie``
376 * parameter.
377 *
378 * Where the system was built with SMP support enabled, this will not ensure
379 * system wide mutual exclusion.  Use interrupt locks instead, see
380 * rtems_interrupt_lock_acquire().  Interrupt disabled critical sections may be
381 * used to access processor-specific data structures or disable thread
382 * dispatching.
383 *
384 * @code
385 * #include <rtems.h>
386 *
387 * void local_critical_section( void )
388 * {
389 *   rtems_interrupt_level level;
390 *
391 *   // Please note that the rtems_interrupt_local_disable() is a macro.
392 *   // The previous interrupt level (before the maskable interrupts are
393 *   // disabled) is returned here in the level macro parameter.  This would
394 *   // be wrong:
395 *   //
396 *   // rtems_interrupt_local_disable( &level );
397 *   rtems_interrupt_local_disable( level );
398 *
399 *   // Here is the critical section: maskable interrupts are disabled
400 *
401 *   {
402 *     rtems_interrupt_level nested_level;
403 *
404 *     rtems_interrupt_local_disable( nested_level );
405 *
406 *     // Here is a nested critical section
407 *
408 *     rtems_interrupt_local_enable( nested_level );
409 *   }
410 *
411 *   // Maskable interrupts are still disabled
412 *
413 *   rtems_interrupt_local_enable( level );
414 * }
415 * @endcode
416 * @endparblock
417 *
418 * @par Constraints
419 * @parblock
420 * The following constraints apply to this directive:
421 *
422 * * The directive may be called from within any runtime context.
423 *
424 * * The directive will not cause the calling task to be preempted.
425 * @endparblock
426 */
427#define rtems_interrupt_local_disable( _isr_cookie ) \
428  _ISR_Local_disable( _isr_cookie )
429
430/* Generated from spec:/rtems/intr/if/local-enable */
431
432/**
433 * @ingroup RTEMSAPIClassicIntr
434 *
435 * @brief Restores the previous interrupt level on the current processor.
436 *
437 * @param[in] _isr_cookie is the previous interrupt level to restore.  The
438 *   value must be obtained by a previous call to
439 *   rtems_interrupt_local_disable().
440 *
441 * This directive restores the interrupt level specified by ``_isr_cookie`` on
442 * the current processor.
443 *
444 * @par Notes
445 * @parblock
446 * The ``_isr_cookie`` parameter value must be obtained by a previous call to
447 * rtems_interrupt_local_disable().  Using an otherwise obtained value is
448 * undefined behaviour.
449 *
450 * This directive is unsuitable to enable particular interrupt sources, for
451 * example in an interrupt controller.
452 * @endparblock
453 *
454 * @par Constraints
455 * @parblock
456 * The following constraints apply to this directive:
457 *
458 * * The directive may be called from within any runtime context.
459 *
460 * * The directive will not cause the calling task to be preempted.
461 *
462 * * While at least one maskable interrupt is pending, when the directive
463 *   enables maskable interrupts, the pending interrupts are immediately
464 *   serviced.  The interrupt service routines may unblock higher priority
465 *   tasks which may preempt the calling task.
466 * @endparblock
467 */
468#define rtems_interrupt_local_enable( _isr_cookie ) \
469  _ISR_Local_enable( _isr_cookie )
470
471/* Generated from spec:/rtems/intr/if/is-in-progress */
472
473/**
474 * @ingroup RTEMSAPIClassicIntr
475 *
476 * @brief Checks if an ISR is in progress on the current processor.
477 *
478 * This directive returns ``true``, if the current processor is currently
479 * servicing an interrupt, and ``false`` otherwise.  A return value of ``true``
480 * indicates that the caller is an interrupt service routine, **not** a task.
481 * The directives available to an interrupt service routine are restricted.
482 *
483 * @return Returns true, if the current processor is currently servicing an
484 *   interrupt, otherwise false.
485 *
486 * @par Constraints
487 * @parblock
488 * The following constraints apply to this directive:
489 *
490 * * The directive may be called from within any runtime context.
491 *
492 * * The directive will not cause the calling task to be preempted.
493 * @endparblock
494 */
495#define rtems_interrupt_is_in_progress() _ISR_Is_in_progress()
496
497/* Generated from spec:/rtems/intr/if/lock */
498
499/**
500 * @ingroup RTEMSAPIClassicIntr
501 *
502 * @brief This structure represents an ISR lock.
503 */
504typedef ISR_lock_Control rtems_interrupt_lock;
505
506/* Generated from spec:/rtems/intr/if/lock-context */
507
508/**
509 * @ingroup RTEMSAPIClassicIntr
510 *
511 * @brief This structure provides an ISR lock context for acquire and release
512 *   pairs.
513 */
514typedef ISR_lock_Context rtems_interrupt_lock_context;
515
516/* Generated from spec:/rtems/intr/if/lock-initialize */
517
518/**
519 * @ingroup RTEMSAPIClassicIntr
520 *
521 * @brief Initializes the ISR lock.
522 *
523 * @param[out] _lock is the ISR lock to initialize.
524 *
525 * @param _name is the ISR lock name.  It shall be a string.  The name is only
526 *   used where the system was built with profiling support enabled.
527 *
528 * @par Notes
529 * ISR locks may also be statically defined by RTEMS_INTERRUPT_LOCK_DEFINE() or
530 * statically initialized by RTEMS_INTERRUPT_LOCK_INITIALIZER().
531 */
532#define rtems_interrupt_lock_initialize( _lock, _name ) \
533  _ISR_lock_Initialize( _lock, _name )
534
535/* Generated from spec:/rtems/intr/if/lock-destroy */
536
537/**
538 * @ingroup RTEMSAPIClassicIntr
539 *
540 * @brief Destroys the ISR lock.
541 *
542 * @param[in,out] _lock is the ISR lock to destroy.
543 *
544 * @par Notes
545 * @parblock
546 * The lock must have been dynamically initialized by
547 * rtems_interrupt_lock_initialize(), statically defined by
548 * RTEMS_INTERRUPT_LOCK_DEFINE(), or statically initialized by
549 * RTEMS_INTERRUPT_LOCK_INITIALIZER().
550 *
551 * Concurrent lock use during the destruction or concurrent destruction leads
552 * to unpredictable results.
553 * @endparblock
554 *
555 * @par Constraints
556 * @parblock
557 * The following constraints apply to this directive:
558 *
559 * * The directive may be called from within any runtime context.
560 *
561 * * The directive will not cause the calling task to be preempted.
562 * @endparblock
563 */
564#define rtems_interrupt_lock_destroy( _lock ) _ISR_lock_Destroy( _lock )
565
566/* Generated from spec:/rtems/intr/if/lock-acquire */
567
568/**
569 * @ingroup RTEMSAPIClassicIntr
570 *
571 * @brief Acquires the ISR lock.
572 *
573 * @param[in,out] _lock is the ISR lock to acquire.
574 *
575 * @param[out] _lock_context is the ISR lock context.  This lock context shall
576 *   be used to release the lock by calling rtems_interrupt_lock_release().
577 *
578 * This directive acquires the ISR lock specified by ``_lock`` using the lock
579 * context provided by ``_lock_context``.  Maskable interrupts will be disabled
580 * on the current processor.
581 *
582 * @par Notes
583 * @parblock
584 * A caller-specific lock context shall be provided for each acquire/release
585 * pair, for example an automatic variable.
586 *
587 * Where the system was built with SMP support enabled, this directive acquires
588 * an SMP lock.  An attempt to recursively acquire the lock may result in an
589 * infinite loop with maskable interrupts disabled.
590 *
591 * This directive establishes a non-preemptive critical section with system
592 * wide mutual exclusion on the local node in all RTEMS build configurations.
593 *
594 * @code
595 * #include <rtems.h>
596 *
597 * void critical_section( rtems_interrupt_lock *lock )
598 * {
599 *   rtems_interrupt_lock_context lock_context;
600 *
601 *   rtems_interrupt_lock_acquire( lock, &lock_context );
602 *
603 *   // Here is the critical section.  Maskable interrupts are disabled.
604 *   // Where the system was built with SMP support enabled, this section
605 *   // is protected by an SMP lock.
606 *
607 *   rtems_interrupt_lock_release( lock, &lock_context );
608 * }
609 * @endcode
610 * @endparblock
611 *
612 * @par Constraints
613 * @parblock
614 * The following constraints apply to this directive:
615 *
616 * * The directive may be called from within any runtime context.
617 *
618 * * The directive will not cause the calling task to be preempted.
619 * @endparblock
620 */
621#define rtems_interrupt_lock_acquire( _lock, _lock_context ) \
622  _ISR_lock_ISR_disable_and_acquire( _lock, _lock_context )
623
624/* Generated from spec:/rtems/intr/if/lock-release */
625
626/**
627 * @ingroup RTEMSAPIClassicIntr
628 *
629 * @brief Releases the ISR lock.
630 *
631 * @param[in,out] _lock is the ISR lock to release.
632 *
633 * @param[in,out] _lock_context is the ISR lock context.  This lock context
634 *   shall have been used to acquire the lock by calling
635 *   rtems_interrupt_lock_acquire().
636 *
637 * This directive releases the ISR lock specified by ``_lock`` using the lock
638 * context provided by ``_lock_context``.  The previous interrupt level will be
639 * restored on the current processor.
640 *
641 * @par Notes
642 * @parblock
643 * The lock context shall be the one used to acquire the lock, otherwise the
644 * result is unpredictable.
645 *
646 * Where the system was built with SMP support enabled, this directive releases
647 * an SMP lock.
648 * @endparblock
649 *
650 * @par Constraints
651 * @parblock
652 * The following constraints apply to this directive:
653 *
654 * * The directive may be called from within any runtime context.
655 *
656 * * The directive will not cause the calling task to be preempted.
657 *
658 * * While at least one maskable interrupt is pending, when the directive
659 *   enables maskable interrupts, the pending interrupts are immediately
660 *   serviced.  The interrupt service routines may unblock higher priority
661 *   tasks which may preempt the calling task.
662 * @endparblock
663 */
664#define rtems_interrupt_lock_release( _lock, _lock_context ) \
665  _ISR_lock_Release_and_ISR_enable( _lock, _lock_context )
666
667/* Generated from spec:/rtems/intr/if/lock-acquire-isr */
668
669/**
670 * @ingroup RTEMSAPIClassicIntr
671 *
672 * @brief Acquires the ISR lock from within an ISR.
673 *
674 * @param[in,out] _lock is the ISR lock to acquire within an ISR.
675 *
676 * @param[out] _lock_context is the ISR lock context.  This lock context shall
677 *   be used to release the lock by calling rtems_interrupt_lock_release_isr().
678 *
679 * This directive acquires the ISR lock specified by ``_lock`` using the lock
680 * context provided by ``_lock_context``.  The interrupt level will remain
681 * unchanged.
682 *
683 * @par Notes
684 * @parblock
685 * A caller-specific lock context shall be provided for each acquire/release
686 * pair, for example an automatic variable.
687 *
688 * Where the system was built with SMP support enabled, this directive acquires
689 * an SMP lock.  An attempt to recursively acquire the lock may result in an
690 * infinite loop.
691 *
692 * This directive is intended for device drivers and should be called from the
693 * corresponding interrupt service routine.
694 *
695 * In case the corresponding interrupt service routine can be interrupted by
696 * higher priority interrupts and these interrupts enter the critical section
697 * protected by this lock, then the result is unpredictable.  This directive
698 * may be used under specific circumstances as an optimization.  In doubt, use
699 * rtems_interrupt_lock_acquire() and rtems_interrupt_lock_release().
700 * @endparblock
701 *
702 * @par Constraints
703 * @parblock
704 * The following constraints apply to this directive:
705 *
706 * * The directive may be called from within any runtime context.
707 *
708 * * The directive will not cause the calling task to be preempted.
709 * @endparblock
710 */
711#if defined(RTEMS_SMP)
712  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
713    _SMP_lock_Acquire( \
714      &( _lock )->Lock, \
715      &( _lock_context )->Lock_context \
716    )
717#else
718  #define rtems_interrupt_lock_acquire_isr( _lock, _lock_context ) \
719    do { (void) _lock_context; } while ( 0 )
720#endif
721
722/* Generated from spec:/rtems/intr/if/lock-release-isr */
723
724/**
725 * @ingroup RTEMSAPIClassicIntr
726 *
727 * @brief Releases the ISR lock from within an ISR.
728 *
729 * @param[in,out] _lock is the ISR lock to release within an ISR.
730 *
731 * @param[in,out] _lock_context is the ISR lock context.  This lock context
732 *   shall have been used to acquire the lock by calling
733 *   rtems_interrupt_lock_acquire_isr().
734 *
735 * This directive releases the ISR lock specified by ``_lock`` using the lock
736 * context provided by ``_lock_context``.  The interrupt level will remain
737 * unchanged.
738 *
739 * @par Notes
740 * @parblock
741 * The lock context shall be the one used to acquire the lock, otherwise the
742 * result is unpredictable.
743 *
744 * Where the system was built with SMP support enabled, this directive releases
745 * an SMP lock.
746 * @endparblock
747 *
748 * @par Constraints
749 * @parblock
750 * The following constraints apply to this directive:
751 *
752 * * The directive may be called from within any runtime context.
753 *
754 * * The directive will not cause the calling task to be preempted.
755 * @endparblock
756 */
757#if defined(RTEMS_SMP)
758  #define rtems_interrupt_lock_release_isr( _lock, _lock_context ) \
759    _SMP_lock_Release( \
760      &( _lock )->Lock, \
761      &( _lock_context )->Lock_context \
762    )
763#else
764  #define rtems_interrupt_lock_release_isr( _lock, _lock_context ) \
765    do { (void) _lock_context; } while ( 0 )
766#endif
767
768/* Generated from spec:/rtems/intr/if/lock-isr-disable */
769
770/**
771 * @ingroup RTEMSAPIClassicIntr
772 *
773 * @brief Disables maskable interrupts on the current processor.
774 *
775 * @param[out] _lock_context is the ISR lock context for an acquire and release
776 *   pair.
777 *
778 * This directive disables maskable interrupts on the current processor and
779 * stores the previous interrupt level in ``_lock_context``.
780 *
781 * @par Constraints
782 * @parblock
783 * The following constraints apply to this directive:
784 *
785 * * The directive may be called from within any runtime context.
786 *
787 * * The directive will not cause the calling task to be preempted.
788 * @endparblock
789 */
790#define rtems_interrupt_lock_interrupt_disable( _lock_context ) \
791  _ISR_lock_ISR_disable( _lock_context )
792
793/* Generated from spec:/rtems/intr/if/lock-declare */
794
795/**
796 * @ingroup RTEMSAPIClassicIntr
797 *
798 * @brief Declares an ISR lock object.
799 *
800 * @param _specifier is the storage-class specifier for the ISR lock to
801 *   declare, for example ``extern`` or ``static``.
802 *
803 * @param _designator is the ISR lock object designator.
804 *
805 * @par Notes
806 * Do not add a ";" after this macro.
807 */
808#define RTEMS_INTERRUPT_LOCK_DECLARE( _specifier, _designator ) \
809  ISR_LOCK_DECLARE( _specifier, _designator )
810
811/* Generated from spec:/rtems/intr/if/lock-define */
812
813/**
814 * @ingroup RTEMSAPIClassicIntr
815 *
816 * @brief Defines an ISR lock object.
817 *
818 * @param _specifier is the storage-class specifier for the ISR lock to
819 *   declare, for example ``extern`` or ``static``.
820 *
821 * @param _designator is the ISR lock object designator.
822 *
823 * @param _name is the ISR lock name.  It shall be a string.  The name is only
824 *   used where the system was built with profiling support enabled.
825 *
826 * @par Notes
827 * @parblock
828 * Do not add a ";" after this macro.
829 *
830 * ISR locks may also be dynamically initialized by
831 * rtems_interrupt_lock_initialize() or statically by
832 * RTEMS_INTERRUPT_LOCK_INITIALIZER().
833 * @endparblock
834 */
835#define RTEMS_INTERRUPT_LOCK_DEFINE( _specifier, _designator, _name ) \
836  ISR_LOCK_DEFINE( _specifier, _designator, _name )
837
838/* Generated from spec:/rtems/intr/if/lock-initializer */
839
840/**
841 * @ingroup RTEMSAPIClassicIntr
842 *
843 * @brief Statically initializes an ISR lock object.
844 *
845 * @param _name is the ISR lock name.  It shall be a string.  The name is only
846 *   used where the system was built with profiling support enabled.
847 *
848 * @par Notes
849 * ISR locks may also be dynamically initialized by
850 * rtems_interrupt_lock_initialize() or statically defined by
851 * RTEMS_INTERRUPT_LOCK_DEFINE().
852 */
853#define RTEMS_INTERRUPT_LOCK_INITIALIZER( _name ) ISR_LOCK_INITIALIZER( _name )
854
855/* Generated from spec:/rtems/intr/if/lock-member */
856
857/**
858 * @ingroup RTEMSAPIClassicIntr
859 *
860 * @brief Defines an ISR lock member.
861 *
862 * @param _designator is the ISR lock member designator.
863 *
864 * @par Notes
865 * Do not add a ";" after this macro.
866 */
867#define RTEMS_INTERRUPT_LOCK_MEMBER( _designator ) \
868  ISR_LOCK_MEMBER( _designator )
869
870/* Generated from spec:/rtems/intr/if/lock-reference */
871
872/**
873 * @ingroup RTEMSAPIClassicIntr
874 *
875 * @brief Defines an ISR lock object reference.
876 *
877 * @param _designator is the ISR lock reference designator.
878 *
879 * @param _target is the target object to reference.
880 *
881 * @par Notes
882 * Do not add a ";" after this macro.
883 */
884#define RTEMS_INTERRUPT_LOCK_REFERENCE( _designator, _target ) \
885  ISR_LOCK_REFERENCE( _designator, _target )
886
887/* Generated from spec:/rtems/intr/if/shared */
888
889/**
890 * @ingroup RTEMSAPIClassicIntr
891 *
892 * @brief This interrupt handler install option allows that the interrupt
893 *   handler may share the interrupt vector with other handler.
894 */
895#define RTEMS_INTERRUPT_SHARED ( (rtems_option) 0x00000000 )
896
897/* Generated from spec:/rtems/intr/if/unique */
898
899/**
900 * @ingroup RTEMSAPIClassicIntr
901 *
902 * @brief This interrupt handler install option ensures that the interrupt
903 *   handler is unique.
904 *
905 * This option prevents other handler from using the same interrupt vector.
906 */
907#define RTEMS_INTERRUPT_UNIQUE ( (rtems_option) 0x00000001 )
908
909/* Generated from spec:/rtems/intr/if/replace */
910
911/**
912 * @ingroup RTEMSAPIClassicIntr
913 *
914 * @brief This interrupt handler install option requests that the interrupt
915 *   handler replaces the first handler with the same argument.
916 */
917#define RTEMS_INTERRUPT_REPLACE ( (rtems_option) 0x00000002 )
918
919/* Generated from spec:/rtems/intr/if/is-shared */
920
921/**
922 * @brief Checks if the interrupt handler shared option is set.
923 *
924 * @param _options is the interrupt handler option set to check.
925 *
926 * @return Returns true, if the interrupt handler shared option
927 *   #RTEMS_INTERRUPT_SHARED is set, otherwise false.
928 */
929#define RTEMS_INTERRUPT_IS_SHARED( _options ) \
930  ( ( _options ) & RTEMS_INTERRUPT_SHARED )
931
932/* Generated from spec:/rtems/intr/if/is-unique */
933
934/**
935 * @brief Checks if the interrupt handler unique option is set.
936 *
937 * @param _options is the interrupt handler option set to check.
938 *
939 * @return Returns true, if the interrupt handler unique option
940 *   #RTEMS_INTERRUPT_UNIQUE is set, otherwise false.
941 */
942#define RTEMS_INTERRUPT_IS_UNIQUE( _options ) \
943  ( ( _options ) & RTEMS_INTERRUPT_UNIQUE )
944
945/* Generated from spec:/rtems/intr/if/is-replace */
946
947/**
948 * @brief Checks if the interrupt handler replace option is set.
949 *
950 * @param _options is the interrupt handler option set to check.
951 *
952 * @return Returns true, if the interrupt handler replace option
953 *   #RTEMS_INTERRUPT_REPLACE is set, otherwise false.
954 */
955#define RTEMS_INTERRUPT_IS_REPLACE( _options ) \
956  ( ( _options ) & RTEMS_INTERRUPT_REPLACE )
957
958/* Generated from spec:/rtems/intr/if/handler */
959
960/**
961 * @ingroup RTEMSAPIClassicIntr
962 *
963 * @brief Interrupt handler routines shall have this type.
964 */
965typedef void ( *rtems_interrupt_handler )( void * );
966
967/* Generated from spec:/rtems/intr/if/per-handler-routine */
968
969/**
970 * @ingroup RTEMSAPIClassicIntr
971 *
972 * @brief Visitor routines invoked by rtems_interrupt_handler_iterate() shall
973 *   have this type.
974 */
975typedef void ( *rtems_interrupt_per_handler_routine )(
976  void *,
977  const char *,
978  rtems_option,
979  rtems_interrupt_handler,
980  void *
981);
982
983/* Generated from spec:/rtems/intr/if/entry */
984
985/**
986 * @ingroup RTEMSAPIClassicIntr
987 *
988 * @brief This structure represents an interrupt entry.
989 *
990 * @par Notes
991 * This structure shall be treated as an opaque data type from the API point of
992 * view.  Members shall not be accessed directly.  An entry may be initialized
993 * by RTEMS_INTERRUPT_ENTRY_INITIALIZER() or
994 * rtems_interrupt_entry_initialize().  It may be installed for an interrupt
995 * vector with rtems_interrupt_entry_install() and removed from an interrupt
996 * vector by rtems_interrupt_entry_remove().
997 */
998typedef struct rtems_interrupt_entry {
999  /**
1000   * @brief This member is the interrupt handler routine.
1001   */
1002  rtems_interrupt_handler handler;
1003
1004  /**
1005   * @brief This member is the interrupt handler argument.
1006   */
1007  void *arg;
1008
1009  /**
1010   * @brief This member is the reference to the next entry or NULL.
1011   */
1012  struct rtems_interrupt_entry *next;
1013
1014  /**
1015   * @brief This member is the descriptive information of the entry.
1016   */
1017  const char *info;
1018} rtems_interrupt_entry;
1019
1020/* Generated from spec:/rtems/intr/if/entry-initializer */
1021
1022/**
1023 * @ingroup RTEMSAPIClassicIntr
1024 *
1025 * @brief Statically initializes an interrupt entry object.
1026 *
1027 * @param _routine is the interrupt handler routine for the entry.
1028 *
1029 * @param _arg is the interrupt handler argument for the entry.
1030 *
1031 * @param _info is the descriptive information for the entry.
1032 *
1033 * @par Notes
1034 * Alternatively, rtems_interrupt_entry_initialize() may be used to dynamically
1035 * initialize an interrupt entry.
1036 */
1037#define RTEMS_INTERRUPT_ENTRY_INITIALIZER( _routine, _arg, _info ) \
1038  { _routine,  _arg, NULL, _info }
1039
1040/* Generated from spec:/rtems/intr/if/entry-initialize */
1041
1042/**
1043 * @ingroup RTEMSAPIClassicIntr
1044 *
1045 * @brief Initializes the interrupt entry.
1046 *
1047 * @param[out] entry is the interrupt entry to initialize.
1048 *
1049 * @param routine is the interrupt handler routine for the entry.
1050 *
1051 * @param arg is the interrupt handler argument for the entry.
1052 *
1053 * @param info is the descriptive information for the entry.
1054 *
1055 * @par Notes
1056 * Alternatively, RTEMS_INTERRUPT_ENTRY_INITIALIZER() may be used to statically
1057 * initialize an interrupt entry.
1058 *
1059 * @par Constraints
1060 * @parblock
1061 * The following constraints apply to this directive:
1062 *
1063 * * The directive may be called from within any runtime context.
1064 *
1065 * * The directive will not cause the calling task to be preempted.
1066 * @endparblock
1067 */
1068static inline void rtems_interrupt_entry_initialize(
1069  rtems_interrupt_entry  *entry,
1070  rtems_interrupt_handler routine,
1071  void                   *arg,
1072  const char             *info
1073)
1074{
1075  entry->handler = routine;
1076  entry->arg = arg;
1077  entry->next = NULL;
1078  entry->info = info;
1079}
1080
1081/* Generated from spec:/rtems/intr/if/entry-install */
1082
1083/**
1084 * @ingroup RTEMSAPIClassicIntr
1085 *
1086 * @brief Installs the interrupt entry at the interrupt vector.
1087 *
1088 * @param vector is the interrupt vector number.
1089 *
1090 * @param options is the interrupt entry install option set.
1091 *
1092 * @param entry is the interrupt entry to install.
1093 *
1094 * One of the following mutually exclusive options
1095 *
1096 * * #RTEMS_INTERRUPT_UNIQUE, and
1097 *
1098 * * #RTEMS_INTERRUPT_SHARED
1099 *
1100 * shall be set in the ``options`` parameter.
1101 *
1102 * The handler routine of the entry specified by ``entry`` will be called with
1103 * the handler argument of the entry when dispatched.  The order in which
1104 * shared interrupt handlers are dispatched for one vector is defined by the
1105 * installation order.  The first installed handler is dispatched first.
1106 *
1107 * If the option #RTEMS_INTERRUPT_UNIQUE is set, then it will be ensured that
1108 * the handler will be the only one for the interrupt vector.
1109 *
1110 * If the option #RTEMS_INTERRUPT_SHARED is set, then multiple handlers may be
1111 * installed for the interrupt vector.
1112 *
1113 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1114 *
1115 * @retval ::RTEMS_INVALID_ADDRESS The ``entry`` parameter was NULL.
1116 *
1117 * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
1118 *
1119 * @retval ::RTEMS_INVALID_ADDRESS The handler routine of the entry was NULL.
1120 *
1121 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1122 *   number specified by ``vector``.
1123 *
1124 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
1125 *   interrupt context.
1126 *
1127 * @retval ::RTEMS_INVALID_NUMBER An option specified by ``options`` was not
1128 *   applicable.
1129 *
1130 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set
1131 *   in ``entry`` and the interrupt vector was already occupied by a handler.
1132 *
1133 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set
1134 *   in ``entry`` and the interrupt vector was already occupied by a unique
1135 *   handler.
1136 *
1137 * @retval ::RTEMS_TOO_MANY The handler routine of the entry specified by
1138 *   ``entry`` was already installed for the interrupt vector specified by
1139 *   ``vector`` with an argument equal to the handler argument of the entry.
1140 *
1141 * @par Notes
1142 * When the directive call was successful, the ownership of the interrupt entry
1143 * has been transferred from the caller to the interrupt service.  An installed
1144 * interrupt entry may be removed from the interrupt service by calling
1145 * rtems_interrupt_entry_remove().
1146 *
1147 * @par Constraints
1148 * @parblock
1149 * The following constraints apply to this directive:
1150 *
1151 * * The directive may be called from within device driver initialization
1152 *   context.
1153 *
1154 * * The directive may be called from within task context.
1155 *
1156 * * The directive may obtain and release the object allocator mutex.  This may
1157 *   cause the calling task to be preempted.
1158 *
1159 * * The interrupt entry shall have been initialized by
1160 *   rtems_interrupt_entry_initialize() or RTEMS_INTERRUPT_ENTRY_INITIALIZER().
1161 * @endparblock
1162 */
1163rtems_status_code rtems_interrupt_entry_install(
1164  rtems_vector_number    vector,
1165  rtems_option           options,
1166  rtems_interrupt_entry *entry
1167);
1168
1169/* Generated from spec:/rtems/intr/if/entry-remove */
1170
1171/**
1172 * @ingroup RTEMSAPIClassicIntr
1173 *
1174 * @brief Removes the interrupt entry from the interrupt vector.
1175 *
1176 * @param vector is the interrupt vector number.
1177 *
1178 * @param entry is the interrupt entry to remove.
1179 *
1180 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1181 *
1182 * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
1183 *
1184 * @retval ::RTEMS_INVALID_ADDRESS The ``entry`` parameter was NULL.
1185 *
1186 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1187 *   number specified by ``vector``.
1188 *
1189 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
1190 *   interrupt context.
1191 *
1192 * @retval ::RTEMS_UNSATISFIED The entry specified by ``entry`` was not
1193 *   installed at the interrupt vector specified by ``vector``.
1194 *
1195 * @par Notes
1196 * When the directive call was successful, the ownership of the interrupt entry
1197 * has been transferred from the interrupt service to the caller.
1198 *
1199 * @par Constraints
1200 * @parblock
1201 * The following constraints apply to this directive:
1202 *
1203 * * The directive may be called from within device driver initialization
1204 *   context.
1205 *
1206 * * The directive may be called from within task context.
1207 *
1208 * * The directive may obtain and release the object allocator mutex.  This may
1209 *   cause the calling task to be preempted.
1210 *
1211 * * The interrupt entry shall have been installed by
1212 *   rtems_interrupt_entry_install().
1213 * @endparblock
1214 */
1215rtems_status_code rtems_interrupt_entry_remove(
1216  rtems_vector_number    vector,
1217  rtems_interrupt_entry *entry
1218);
1219
1220/* Generated from spec:/rtems/intr/if/handler-install */
1221
1222/**
1223 * @ingroup RTEMSAPIClassicIntr
1224 *
1225 * @brief Installs the interrupt handler routine and argument at the interrupt
1226 *   vector.
1227 *
1228 * @param vector is the interrupt vector number.
1229 *
1230 * @param info is the descriptive information of the interrupt handler to
1231 *   install.
1232 *
1233 * @param options is the interrupt handler install option set.
1234 *
1235 * @param routine is the interrupt handler routine to install.
1236 *
1237 * @param arg is the interrupt handler argument to install.
1238 *
1239 * One of the following mutually exclusive options
1240 *
1241 * * #RTEMS_INTERRUPT_UNIQUE,
1242 *
1243 * * #RTEMS_INTERRUPT_SHARED, and
1244 *
1245 * * #RTEMS_INTERRUPT_REPLACE
1246 *
1247 * shall be set in the ``options`` parameter.
1248 *
1249 * The handler routine will be called with the argument specified by ``arg``
1250 * when dispatched.  The order in which shared interrupt handlers are
1251 * dispatched for one vector is defined by the installation order.  The first
1252 * installed handler is dispatched first.
1253 *
1254 * If the option #RTEMS_INTERRUPT_UNIQUE is set, then it will be ensured that
1255 * the handler will be the only one for the interrupt vector.
1256 *
1257 * If the option #RTEMS_INTERRUPT_SHARED is set, then multiple handler may be
1258 * installed for the interrupt vector.
1259 *
1260 * If the option #RTEMS_INTERRUPT_REPLACE is set, then the handler specified by
1261 * ``routine`` will replace the first handler with the same argument for the
1262 * interrupt vector if it exists, otherwise an error status will be returned.
1263 * A second handler with the same argument for the interrupt vector will remain
1264 * unchanged.  The new handler will inherit the unique or shared options from
1265 * the replaced handler.
1266 *
1267 * An informative description may be provided in ``info``.  It may be used for
1268 * system debugging and diagnostic tools.  The referenced string has to be
1269 * persistent as long as the handler is installed.
1270 *
1271 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1272 *
1273 * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
1274 *
1275 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
1276 *
1277 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1278 *   number specified by ``vector``.
1279 *
1280 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
1281 *   interrupt context.
1282 *
1283 * @retval ::RTEMS_NO_MEMORY There was not enough memory available to allocate
1284 *   data structures to install the handler.
1285 *
1286 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set
1287 *   in ``options`` and the interrupt vector was already occupied by a handler.
1288 *
1289 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set
1290 *   in ``options`` and the interrupt vector was already occupied by a unique
1291 *   handler.
1292 *
1293 * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already
1294 *   installed for the interrupt vector specified by ``vector`` with an
1295 *   argument equal to the argument specified by ``arg``.
1296 *
1297 * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in
1298 *   ``options`` and no handler to replace was installed.
1299 *
1300 * @par Constraints
1301 * @parblock
1302 * The following constraints apply to this directive:
1303 *
1304 * * The directive may be called from within device driver initialization
1305 *   context.
1306 *
1307 * * The directive may be called from within task context.
1308 *
1309 * * The directive may obtain and release the object allocator mutex.  This may
1310 *   cause the calling task to be preempted.
1311 * @endparblock
1312 */
1313rtems_status_code rtems_interrupt_handler_install(
1314  rtems_vector_number     vector,
1315  const char             *info,
1316  rtems_option            options,
1317  rtems_interrupt_handler routine,
1318  void                   *arg
1319);
1320
1321/* Generated from spec:/rtems/intr/if/handler-remove */
1322
1323/**
1324 * @ingroup RTEMSAPIClassicIntr
1325 *
1326 * @brief Removes the interrupt handler routine and argument from the interrupt
1327 *   vector.
1328 *
1329 * @param vector is the interrupt vector number.
1330 *
1331 * @param routine is the interrupt handler routine to remove.
1332 *
1333 * @param arg is the interrupt handler argument to remove.
1334 *
1335 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1336 *
1337 * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
1338 *
1339 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
1340 *
1341 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1342 *   number specified by ``vector``.
1343 *
1344 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
1345 *   interrupt context.
1346 *
1347 * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair
1348 *   installed specified by ``routine`` and ``arg``.
1349 *
1350 * @par Constraints
1351 * @parblock
1352 * The following constraints apply to this directive:
1353 *
1354 * * The directive may be called from within device driver initialization
1355 *   context.
1356 *
1357 * * The directive may be called from within task context.
1358 *
1359 * * The directive may obtain and release the object allocator mutex.  This may
1360 *   cause the calling task to be preempted.
1361 * @endparblock
1362 */
1363rtems_status_code rtems_interrupt_handler_remove(
1364  rtems_vector_number     vector,
1365  rtems_interrupt_handler routine,
1366  void                   *arg
1367);
1368
1369/* Generated from spec:/rtems/intr/if/vector-is-enabled */
1370
1371/**
1372 * @ingroup RTEMSAPIClassicIntr
1373 *
1374 * @brief Checks if the interrupt vector is enabled.
1375 *
1376 * @param vector is the interrupt vector number.
1377 *
1378 * @param[out] enabled is the pointer to a ``bool`` object.  When the directive
1379 *   call is successful, the enabled status of the interrupt associated with
1380 *   the interrupt vector specified by ``vector`` will be stored in this
1381 *   object.  When the interrupt was enabled for the processor executing the
1382 *   directive call at some time point during the call, the object value will
1383 *   be set to true, otherwise to false.
1384 *
1385 * The directive checks if the interrupt associated with the interrupt vector
1386 * specified by ``vector`` was enabled for the processor executing the
1387 * directive call at some time point during the call.
1388 *
1389 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1390 *
1391 * @retval ::RTEMS_INVALID_ADDRESS The ``enabled`` parameter was NULL.
1392 *
1393 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1394 *   number specified by ``vector``.
1395 *
1396 * @par Notes
1397 * Interrupt vectors may be enabled by rtems_interrupt_vector_enable() and
1398 * disabled by rtems_interrupt_vector_disable().
1399 *
1400 * @par Constraints
1401 * @parblock
1402 * The following constraints apply to this directive:
1403 *
1404 * * The directive may be called from within interrupt context.
1405 *
1406 * * The directive may be called from within device driver initialization
1407 *   context.
1408 *
1409 * * The directive may be called from within task context.
1410 *
1411 * * The directive will not cause the calling task to be preempted.
1412 * @endparblock
1413 */
1414rtems_status_code rtems_interrupt_vector_is_enabled(
1415  rtems_vector_number vector,
1416  bool               *enabled
1417);
1418
1419/* Generated from spec:/rtems/intr/if/vector-enable */
1420
1421/**
1422 * @ingroup RTEMSAPIClassicIntr
1423 *
1424 * @brief Enables the interrupt vector.
1425 *
1426 * @param vector is the number of the interrupt vector to enable.
1427 *
1428 * The directive enables the interrupt vector specified by ``vector``. This
1429 * allows that interrupt service requests are issued to the target processors
1430 * of the interrupt vector.  Interrupt service requests for an interrupt vector
1431 * may be raised by rtems_interrupt_raise(), rtems_interrupt_raise_on(),
1432 * external signals, or messages.
1433 *
1434 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1435 *
1436 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1437 *   number specified by ``vector``.
1438 *
1439 * @retval ::RTEMS_UNSATISFIED The request to enable the interrupt vector has
1440 *   not been satisfied.
1441 *
1442 * @par Notes
1443 * The rtems_interrupt_get_attributes() directive may be used to check if an
1444 * interrupt vector can be enabled.  Interrupt vectors may be disabled by
1445 * rtems_interrupt_vector_disable().
1446 *
1447 * @par Constraints
1448 * @parblock
1449 * The following constraints apply to this directive:
1450 *
1451 * * The directive may be called from within interrupt context.
1452 *
1453 * * The directive may be called from within device driver initialization
1454 *   context.
1455 *
1456 * * The directive may be called from within task context.
1457 *
1458 * * The directive will not cause the calling task to be preempted.
1459 * @endparblock
1460 */
1461rtems_status_code rtems_interrupt_vector_enable( rtems_vector_number vector );
1462
1463/* Generated from spec:/rtems/intr/if/vector-disable */
1464
1465/**
1466 * @ingroup RTEMSAPIClassicIntr
1467 *
1468 * @brief Disables the interrupt vector.
1469 *
1470 * @param vector is the number of the interrupt vector to disable.
1471 *
1472 * The directive disables the interrupt vector specified by ``vector``.  This
1473 * prevents that an interrupt service request is issued to the target
1474 * processors of the interrupt vector.
1475 *
1476 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1477 *
1478 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1479 *   number specified by ``vector``.
1480 *
1481 * @retval ::RTEMS_UNSATISFIED The request to disable the interrupt vector has
1482 *   not been satisfied.
1483 *
1484 * @par Notes
1485 * The rtems_interrupt_get_attributes() directive may be used to check if an
1486 * interrupt vector can be disabled.  Interrupt vectors may be enabled by
1487 * rtems_interrupt_vector_enable().  There may be targets on which some
1488 * interrupt vectors cannot be disabled, for example a hardware watchdog
1489 * interrupt or software generated interrupts.
1490 *
1491 * @par Constraints
1492 * @parblock
1493 * The following constraints apply to this directive:
1494 *
1495 * * The directive may be called from within interrupt context.
1496 *
1497 * * The directive may be called from within device driver initialization
1498 *   context.
1499 *
1500 * * The directive may be called from within task context.
1501 *
1502 * * The directive will not cause the calling task to be preempted.
1503 * @endparblock
1504 */
1505rtems_status_code rtems_interrupt_vector_disable( rtems_vector_number vector );
1506
1507/* Generated from spec:/rtems/intr/if/is-pending */
1508
1509/**
1510 * @ingroup RTEMSAPIClassicIntr
1511 *
1512 * @brief Checks if the interrupt is pending.
1513 *
1514 * @param vector is the interrupt vector number.
1515 *
1516 * @param[out] pending is the pointer to a ``bool`` object.  When the directive
1517 *   call is successful, the pending status of the interrupt associated with
1518 *   the interrupt vector specified by ``vector`` will be stored in this
1519 *   object.  When the interrupt was pending for the processor executing the
1520 *   directive call at some time point during the call, the object value will
1521 *   be set to true, otherwise to false.
1522 *
1523 * The directive checks if the interrupt associated with the interrupt vector
1524 * specified by ``vector`` was pending for the processor executing the
1525 * directive call at some time point during the call.
1526 *
1527 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1528 *
1529 * @retval ::RTEMS_INVALID_ADDRESS The ``pending`` parameter was NULL.
1530 *
1531 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1532 *   number specified by ``vector``.
1533 *
1534 * @retval ::RTEMS_UNSATISFIED The request to get the pending status has not
1535 *   been satisfied.
1536 *
1537 * @par Notes
1538 * Interrupts may be made pending by calling the rtems_interrupt_raise() or
1539 * rtems_interrupt_raise_on() directives or due to external signals or
1540 * messages.  The pending state may be cleared by rtems_interrupt_clear().
1541 *
1542 * @par Constraints
1543 * @parblock
1544 * The following constraints apply to this directive:
1545 *
1546 * * The directive may be called from within interrupt context.
1547 *
1548 * * The directive may be called from within device driver initialization
1549 *   context.
1550 *
1551 * * The directive may be called from within task context.
1552 *
1553 * * The directive will not cause the calling task to be preempted.
1554 * @endparblock
1555 */
1556rtems_status_code rtems_interrupt_is_pending(
1557  rtems_vector_number vector,
1558  bool               *pending
1559);
1560
1561/* Generated from spec:/rtems/intr/if/raise */
1562
1563/**
1564 * @ingroup RTEMSAPIClassicIntr
1565 *
1566 * @brief Raises the interrupt vector.
1567 *
1568 * @param vector is the number of the interrupt vector to raise.
1569 *
1570 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1571 *
1572 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1573 *   number specified by ``vector``.
1574 *
1575 * @retval ::RTEMS_UNSATISFIED The request to raise the interrupt vector has
1576 *   not been satisfied.
1577 *
1578 * @par Notes
1579 * The rtems_interrupt_get_attributes() directive may be used to check if an
1580 * interrupt vector can be raised.
1581 *
1582 * @par Constraints
1583 * @parblock
1584 * The following constraints apply to this directive:
1585 *
1586 * * The directive may be called from within interrupt context.
1587 *
1588 * * The directive may be called from within device driver initialization
1589 *   context.
1590 *
1591 * * The directive may be called from within task context.
1592 *
1593 * * The directive will not cause the calling task to be preempted.
1594 * @endparblock
1595 */
1596rtems_status_code rtems_interrupt_raise( rtems_vector_number vector );
1597
1598/* Generated from spec:/rtems/intr/if/raise-on */
1599
1600/**
1601 * @ingroup RTEMSAPIClassicIntr
1602 *
1603 * @brief Raises the interrupt vector on the processor.
1604 *
1605 * @param vector is the number of the interrupt vector to raise.
1606 *
1607 * @param cpu_index is the index of the target processor of the interrupt
1608 *   vector to raise.
1609 *
1610 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1611 *
1612 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1613 *   number specified by ``vector``.
1614 *
1615 * @retval ::RTEMS_NOT_CONFIGURED The processor specified by ``cpu_index`` was
1616 *   not configured to be used by the application.
1617 *
1618 * @retval ::RTEMS_INCORRECT_STATE The processor specified by ``cpu_index`` was
1619 *   configured to be used by the application, however, it was not online.
1620 *
1621 * @retval ::RTEMS_UNSATISFIED The request to raise the interrupt vector has
1622 *   not been satisfied.
1623 *
1624 * @par Notes
1625 * The rtems_interrupt_get_attributes() directive may be used to check if an
1626 * interrupt vector can be raised on a processor.
1627 *
1628 * @par Constraints
1629 * @parblock
1630 * The following constraints apply to this directive:
1631 *
1632 * * The directive may be called from within interrupt context.
1633 *
1634 * * The directive may be called from within device driver initialization
1635 *   context.
1636 *
1637 * * The directive may be called from within task context.
1638 *
1639 * * The directive will not cause the calling task to be preempted.
1640 * @endparblock
1641 */
1642rtems_status_code rtems_interrupt_raise_on(
1643  rtems_vector_number vector,
1644  uint32_t            cpu_index
1645);
1646
1647/* Generated from spec:/rtems/intr/if/clear */
1648
1649/**
1650 * @ingroup RTEMSAPIClassicIntr
1651 *
1652 * @brief Clears the interrupt vector.
1653 *
1654 * @param vector is the number of the interrupt vector to clear.
1655 *
1656 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1657 *
1658 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1659 *   number specified by ``vector``.
1660 *
1661 * @retval ::RTEMS_UNSATISFIED The request to raise the interrupt vector has
1662 *   not been satisfied.
1663 *
1664 * @par Notes
1665 * The rtems_interrupt_get_attributes() directive may be used to check if an
1666 * interrupt vector can be cleared.
1667 *
1668 * @par Constraints
1669 * @parblock
1670 * The following constraints apply to this directive:
1671 *
1672 * * The directive may be called from within interrupt context.
1673 *
1674 * * The directive may be called from within device driver initialization
1675 *   context.
1676 *
1677 * * The directive may be called from within task context.
1678 *
1679 * * The directive will not cause the calling task to be preempted.
1680 * @endparblock
1681 */
1682rtems_status_code rtems_interrupt_clear( rtems_vector_number vector );
1683
1684/* Generated from spec:/rtems/intr/if/get-affinity */
1685
1686/**
1687 * @ingroup RTEMSAPIClassicIntr
1688 *
1689 * @brief Gets the processor affinity set of the interrupt vector.
1690 *
1691 * @param vector is the interrupt vector number.
1692 *
1693 * @param affinity_size is the size of the processor set referenced by
1694 *   ``affinity`` in bytes.
1695 *
1696 * @param[out] affinity is the pointer to a cpu_set_t object.  When the
1697 *   directive call is successful, the processor affinity set of the interrupt
1698 *   vector will be stored in this object.  A set bit in the processor set
1699 *   means that the corresponding processor is in the processor affinity set of
1700 *   the interrupt vector, otherwise the bit is cleared.
1701 *
1702 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1703 *
1704 * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL.
1705 *
1706 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1707 *   number specified by ``vector``.
1708 *
1709 * @retval ::RTEMS_INVALID_SIZE The size specified by ``affinity_size`` of the
1710 *   processor set was too small for the processor affinity set of the
1711 *   interrupt vector.
1712 *
1713 * @par Constraints
1714 * @parblock
1715 * The following constraints apply to this directive:
1716 *
1717 * * The directive may be called from within interrupt context.
1718 *
1719 * * The directive may be called from within device driver initialization
1720 *   context.
1721 *
1722 * * The directive may be called from within task context.
1723 *
1724 * * The directive will not cause the calling task to be preempted.
1725 * @endparblock
1726 */
1727rtems_status_code rtems_interrupt_get_affinity(
1728  rtems_vector_number vector,
1729  size_t              affinity_size,
1730  cpu_set_t          *affinity
1731);
1732
1733/* Generated from spec:/rtems/intr/if/set-affinity */
1734
1735/**
1736 * @ingroup RTEMSAPIClassicIntr
1737 *
1738 * @brief Sets the processor affinity set of the interrupt vector.
1739 *
1740 * @param vector is the interrupt vector number.
1741 *
1742 * @param affinity_size is the size of the processor set referenced by
1743 *   ``affinity`` in bytes.
1744 *
1745 * @param affinity is the pointer to a cpu_set_t object.  The processor set
1746 *   defines the new processor affinity set of the interrupt vector.  A set bit
1747 *   in the processor set means that the corresponding processor shall be in
1748 *   the processor affinity set of the interrupt vector, otherwise the bit
1749 *   shall be cleared.
1750 *
1751 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1752 *
1753 * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL.
1754 *
1755 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1756 *   number specified by ``vector``.
1757 *
1758 * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid
1759 *   new processor affinity set for the interrupt vector.
1760 *
1761 * @retval ::RTEMS_UNSATISFIED The request to set the processor affinity of the
1762 *   interrupt vector has not been satisfied.
1763 *
1764 * @par Notes
1765 * @parblock
1766 * The rtems_interrupt_get_attributes() directive may be used to check if the
1767 * processor affinity of an interrupt vector can be set.
1768 *
1769 * Only online processors of the affinity set specified by ``affinity_size``
1770 * and ``affinity`` are considered by the directive.  Other processors of the
1771 * set are ignored.  If the set contains no online processor, then the set is
1772 * invalid and an error status is returned.
1773 * @endparblock
1774 *
1775 * @par Constraints
1776 * @parblock
1777 * The following constraints apply to this directive:
1778 *
1779 * * The directive may be called from within interrupt context.
1780 *
1781 * * The directive may be called from within device driver initialization
1782 *   context.
1783 *
1784 * * The directive may be called from within task context.
1785 *
1786 * * The directive will not cause the calling task to be preempted.
1787 * @endparblock
1788 */
1789rtems_status_code rtems_interrupt_set_affinity(
1790  rtems_vector_number vector,
1791  size_t              affinity_size,
1792  const cpu_set_t    *affinity
1793);
1794
1795/* Generated from spec:/rtems/intr/if/signal-variant */
1796
1797/**
1798 * @ingroup RTEMSAPIClassicIntr
1799 *
1800 * @brief This enumeration provides interrupt trigger signal variants.
1801 */
1802typedef enum {
1803  /**
1804   * @brief This interrupt signal variant indicates that the interrupt trigger
1805   *   signal is unspecified.
1806   */
1807  RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL,
1808
1809  /**
1810   * @brief This interrupt signal variant indicates that the interrupt cannot be
1811   *   triggered by a signal.
1812   */
1813  RTEMS_INTERRUPT_NO_SIGNAL,
1814
1815  /**
1816   * @brief This interrupt signal variant indicates that the interrupt is
1817   *   triggered by a low level signal.
1818   */
1819  RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW,
1820
1821  /**
1822   * @brief This interrupt signal variant indicates that the interrupt is
1823   *   triggered by a high level signal.
1824   */
1825  RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH,
1826
1827  /**
1828   * @brief This interrupt signal variant indicates that the interrupt is
1829   *   triggered by a falling edge signal.
1830   */
1831  RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING,
1832
1833  /**
1834   * @brief This interrupt signal variant indicates that the interrupt is
1835   *   triggered by a raising edge signal.
1836   */
1837  RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING
1838} rtems_interrupt_signal_variant;
1839
1840/* Generated from spec:/rtems/intr/if/attributes */
1841
1842/**
1843 * @ingroup RTEMSAPIClassicIntr
1844 *
1845 * @brief This structure provides the attributes of an interrupt vector.
1846 *
1847 * The rtems_interrupt_get_attributes() directive may be used to obtain the
1848 * attributes of an interrupt vector.
1849 */
1850typedef struct {
1851  /**
1852   * @brief This member is true, if the interrupt vector is maskable by
1853   *   rtems_interrupt_local_disable(), otherwise it is false.
1854   *
1855   * Interrupt vectors which are not maskable by rtems_interrupt_local_disable()
1856   * should be used with care since they cannot use most operating system
1857   * services.
1858   */
1859  bool is_maskable;
1860
1861  /**
1862   * @brief This member is true, if the interrupt vector can be enabled by
1863   *   rtems_interrupt_vector_enable(), otherwise it is false.
1864   *
1865   * When an interrupt vector can be enabled, this means that the enabled state
1866   * can always be changed from disabled to enabled.  For an interrupt vector
1867   * which can be enabled it follows that it may be enabled.
1868   */
1869  bool can_enable;
1870
1871  /**
1872   * @brief This member is true, if the interrupt vector may be enabled by
1873   *   rtems_interrupt_vector_enable(), otherwise it is false.
1874   *
1875   * When an interrupt vector may be enabled, this means that the enabled state
1876   * may be changed from disabled to enabled.  The requested enabled state change
1877   * should be checked by rtems_interrupt_vector_is_enabled().  Some interrupt
1878   * vectors may be optionally available and cannot be enabled on a particular
1879   * target.
1880   */
1881  bool maybe_enable;
1882
1883  /**
1884   * @brief This member is true, if the interrupt vector can be disabled by
1885   *   rtems_interrupt_vector_disable(), otherwise it is false.
1886   *
1887   * When an interrupt vector can be disabled, this means that the enabled state
1888   * can be changed from enabled to disabled.  For an interrupt vector which can
1889   * be disabled it follows that it may be disabled.
1890   */
1891  bool can_disable;
1892
1893  /**
1894   * @brief This member is true, if the interrupt vector may be disabled by
1895   *   rtems_interrupt_vector_disable(), otherwise it is false.
1896   *
1897   * When an interrupt vector may be disabled, this means that the enabled state
1898   * may be changed from enabled to disabled.  The requested enabled state change
1899   * should be checked by rtems_interrupt_vector_is_enabled().  Some interrupt
1900   * vectors may be always enabled and cannot be disabled on a particular target.
1901   */
1902  bool maybe_disable;
1903
1904  /**
1905   * @brief This member is true, if the interrupt vector can be raised by
1906   *   rtems_interrupt_raise(), otherwise it is false.
1907   */
1908  bool can_raise;
1909
1910  /**
1911   * @brief This member is true, if the interrupt vector can be raised on a
1912   *   processor by rtems_interrupt_raise_on(), otherwise it is false.
1913   */
1914  bool can_raise_on;
1915
1916  /**
1917   * @brief This member is true, if the interrupt vector can be cleared by
1918   *   rtems_interrupt_clear(), otherwise it is false.
1919   */
1920  bool can_clear;
1921
1922  /**
1923   * @brief This member is true, if the pending status of the interrupt
1924   *   associated with the interrupt vector is cleared by an interrupt
1925   *   acknowledge from the processor, otherwise it is false.
1926   */
1927  bool cleared_by_acknowledge;
1928
1929  /**
1930   * @brief This member is true, if the affinity set of the interrupt vector can
1931   *   be obtained by rtems_interrupt_get_affinity(), otherwise it is false.
1932   */
1933  bool can_get_affinity;
1934
1935  /**
1936   * @brief This member is true, if the affinity set of the interrupt vector can
1937   *   be set by rtems_interrupt_set_affinity(), otherwise it is false.
1938   */
1939  bool can_set_affinity;
1940
1941  /**
1942   * @brief This member is true, if the interrupt associated with the interrupt
1943   *   vector can be triggered by a message.
1944   *
1945   * Interrupts may be also triggered by signals, rtems_interrupt_raise(), or
1946   * rtems_interrupt_raise_on().  Examples for message triggered interrupts are
1947   * the PCIe MSI/MSI-X and the ARM GICv3 Locality-specific Peripheral Interrupts
1948   * (LPI).
1949   */
1950  bool can_be_triggered_by_message;
1951
1952  /**
1953   * @brief This member describes the trigger signal of the interrupt associated
1954   *   with the interrupt vector.
1955   *
1956   * Interrupts are normally triggered by signals which indicate an interrupt
1957   * request from a peripheral.  Interrupts may be also triggered by messages,
1958   * rtems_interrupt_raise(), or rtems_interrupt_raise_on().
1959   */
1960  rtems_interrupt_signal_variant trigger_signal;
1961} rtems_interrupt_attributes;
1962
1963/* Generated from spec:/rtems/intr/if/get-attributes */
1964
1965/**
1966 * @ingroup RTEMSAPIClassicIntr
1967 *
1968 * @brief Gets the attributes of the interrupt vector.
1969 *
1970 * @param vector is the interrupt vector number.
1971 *
1972 * @param[out] attributes is the pointer to an rtems_interrupt_attributes
1973 *   object.  When the directive call is successful, the attributes of the
1974 *   interrupt vector will be stored in this object.
1975 *
1976 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
1977 *
1978 * @retval ::RTEMS_INVALID_ADDRESS The ``attributes`` parameter was NULL.
1979 *
1980 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
1981 *   number specified by ``vector``.
1982 *
1983 * @par Constraints
1984 * @parblock
1985 * The following constraints apply to this directive:
1986 *
1987 * * The directive may be called from within interrupt context.
1988 *
1989 * * The directive may be called from within device driver initialization
1990 *   context.
1991 *
1992 * * The directive may be called from within task context.
1993 *
1994 * * The directive will not cause the calling task to be preempted.
1995 * @endparblock
1996 */
1997rtems_status_code rtems_interrupt_get_attributes(
1998  rtems_vector_number         vector,
1999  rtems_interrupt_attributes *attributes
2000);
2001
2002/* Generated from spec:/rtems/intr/if/handler-iterate */
2003
2004/**
2005 * @ingroup RTEMSAPIClassicIntr
2006 *
2007 * @brief Iterates over all interrupt handler installed at the interrupt
2008 *   vector.
2009 *
2010 * @param vector is the interrupt vector number.
2011 *
2012 * @param routine is the visitor routine.
2013 *
2014 * @param arg is the visitor argument.
2015 *
2016 * For each installed handler at the interrupt vector the visitor function
2017 * specified by ``routine`` will be called with the argument specified by
2018 * ``arg`` and the handler information, options, routine and argument.
2019 *
2020 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2021 *
2022 * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
2023 *
2024 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
2025 *
2026 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
2027 *   number specified by ``vector``.
2028 *
2029 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
2030 *   interrupt context.
2031 *
2032 * @par Notes
2033 * @parblock
2034 * The directive is intended for system information and diagnostics.
2035 *
2036 * Never install or remove an interrupt handler within the visitor function.
2037 * This may result in a deadlock.
2038 * @endparblock
2039 *
2040 * @par Constraints
2041 * @parblock
2042 * The following constraints apply to this directive:
2043 *
2044 * * The directive may be called from within device driver initialization
2045 *   context.
2046 *
2047 * * The directive may be called from within task context.
2048 *
2049 * * The directive may obtain and release the object allocator mutex.  This may
2050 *   cause the calling task to be preempted.
2051 * @endparblock
2052 */
2053rtems_status_code rtems_interrupt_handler_iterate(
2054  rtems_vector_number                 vector,
2055  rtems_interrupt_per_handler_routine routine,
2056  void                               *arg
2057);
2058
2059/* Generated from spec:/rtems/intr/if/server-default */
2060
2061/**
2062 * @ingroup RTEMSAPIClassicIntr
2063 *
2064 * @brief The constant represents the index of the default interrupt server.
2065 */
2066#define RTEMS_INTERRUPT_SERVER_DEFAULT 0
2067
2068/* Generated from spec:/rtems/intr/if/server-control */
2069
2070/**
2071 * @ingroup RTEMSAPIClassicIntr
2072 *
2073 * @brief This structure represents an interrupt server.
2074 *
2075 * @par Notes
2076 * This structure shall be treated as an opaque data type from the API point of
2077 * view.  Members shall not be accessed directly.  The structure is initialized
2078 * by rtems_interrupt_server_create() and maintained by the interrupt server
2079 * support.
2080 */
2081typedef struct rtems_interrupt_server_control {
2082  #if defined(RTEMS_SMP)
2083    /**
2084     * @brief This member is the ISR lock protecting the server control state.
2085     */
2086    rtems_interrupt_lock lock;
2087  #endif
2088
2089  /**
2090   * @brief This member is the chain of pending interrupt entries.
2091   */
2092  Chain_Control entries;
2093
2094  /**
2095   * @brief This member is the identifier of the server task.
2096   */
2097  rtems_id server;
2098
2099  /**
2100   * @brief This member is the error count.
2101   */
2102  unsigned long errors;
2103
2104  /**
2105   * @brief This member is the server index.
2106   */
2107  uint32_t index;
2108
2109  /**
2110   * @brief This member is the node for the interrupt server registry.
2111   */
2112  Chain_Node node;
2113
2114  /**
2115   * @brief This member is the optional handler to destroy the interrupt server
2116   *   control.
2117   */
2118  void ( *destroy )( struct rtems_interrupt_server_control * );
2119} rtems_interrupt_server_control;
2120
2121/* Generated from spec:/rtems/intr/if/server-config */
2122
2123/**
2124 * @ingroup RTEMSAPIClassicIntr
2125 *
2126 * @brief This structure defines an interrupt server configuration.
2127 *
2128 * @par Notes
2129 * See also rtems_interrupt_server_create().
2130 */
2131typedef struct {
2132  /**
2133   * @brief This member is the task name of the interrupt server.
2134   */
2135  rtems_name name;
2136
2137  /**
2138   * @brief This member is the initial task priority of the interrupt server.
2139   */
2140  rtems_task_priority priority;
2141
2142  /**
2143   * @brief This member is the task storage area of the interrupt server.
2144   *
2145   * It shall be NULL for interrupt servers created by
2146   * rtems_interrupt_server_create().
2147   */
2148  void *storage_area;
2149
2150  /**
2151   * @brief This member is the task storage size of the interrupt server.
2152   *
2153   * For interrupt servers created by rtems_interrupt_server_create() this is the
2154   * task stack size.
2155   */
2156  size_t storage_size;
2157
2158  /**
2159   * @brief This member is the initial mode set of the interrupt server.
2160   */
2161  rtems_mode modes;
2162
2163  /**
2164   * @brief This member is the attribute set of the interrupt server.
2165   */
2166  rtems_attribute attributes;
2167
2168  /**
2169   * @brief This member is an optional handler to destroy the interrupt server
2170   *   control handed over to rtems_interrupt_server_create().
2171   *
2172   * The destroy handler is optional and may be NULL.  If the destroy handler is
2173   * present, it is called from within the context of the interrupt server to be
2174   * deleted, see also rtems_interrupt_server_delete().
2175   */
2176  void ( *destroy )( rtems_interrupt_server_control * );
2177} rtems_interrupt_server_config;
2178
2179/* Generated from spec:/rtems/intr/if/server-initialize */
2180
2181/**
2182 * @ingroup RTEMSAPIClassicIntr
2183 *
2184 * @brief Initializes the interrupt server tasks.
2185 *
2186 * @param priority is the initial task priority of the created interrupt
2187 *   servers.
2188 *
2189 * @param stack_size is the task stack size of the created interrupt servers.
2190 *
2191 * @param modes is the initial mode set of the created interrupt servers.
2192 *
2193 * @param attributes is the attribute set of the created interrupt servers.
2194 *
2195 * @param[out] server_count is the pointer to an uint32_t object or NULL. When
2196 *   the pointer is not equal to NULL, the count of successfully created
2197 *   interrupt servers is stored in this object regardless of the return
2198 *   status.
2199 *
2200 * The directive tries to create an interrupt server task for each online
2201 * processor in the system.  The tasks will have the initial priority specified
2202 * by ``priority``, the stack size specified by ``stack_size``, the initial
2203 * mode set specified by ``modes``, and the attribute set specified by
2204 * ``attributes``.  The count of successfully created server tasks will be
2205 * returned in ``server_count`` if the pointer is not equal to NULL.
2206 *
2207 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2208 *
2209 * @retval ::RTEMS_INCORRECT_STATE The interrupt servers were already
2210 *   initialized.
2211 *
2212 * @return The directive uses rtems_task_create().  If this directive fails,
2213 *   then its error status will be returned.
2214 *
2215 * @par Notes
2216 * @parblock
2217 * Interrupt handlers may be installed on an interrupt server with
2218 * rtems_interrupt_server_handler_install() and removed with
2219 * rtems_interrupt_server_handler_remove() using a server index.  In case of an
2220 * interrupt, the request will be forwarded to the interrupt server.  The
2221 * handlers are executed within the interrupt server context.  If one handler
2222 * blocks on something this may delay the processing of other handlers.
2223 *
2224 * Interrupt servers may be deleted by rtems_interrupt_server_delete().
2225 * @endparblock
2226 *
2227 * @par Constraints
2228 * @parblock
2229 * The following constraints apply to this directive:
2230 *
2231 * * The directive may be called from within device driver initialization
2232 *   context.
2233 *
2234 * * The directive may be called from within task context.
2235 *
2236 * * The directive may obtain and release the object allocator mutex.  This may
2237 *   cause the calling task to be preempted.
2238 * @endparblock
2239 */
2240rtems_status_code rtems_interrupt_server_initialize(
2241  rtems_task_priority priority,
2242  size_t              stack_size,
2243  rtems_mode          modes,
2244  rtems_attribute     attributes,
2245  uint32_t           *server_count
2246);
2247
2248/* Generated from spec:/rtems/intr/if/server-create */
2249
2250/**
2251 * @ingroup RTEMSAPIClassicIntr
2252 *
2253 * @brief Creates an interrupt server.
2254 *
2255 * @param[out] control is the pointer to an rtems_interrupt_server_control
2256 *   object.  When the directive call was successful, the ownership of the
2257 *   object was transferred from the caller of the directive to the interrupt
2258 *   server management.
2259 *
2260 * @param config is the interrupt server configuration.
2261 *
2262 * @param[out] server_index is the pointer to an uint32_t object.  When the
2263 *   directive call was successful, the index of the created interrupt server
2264 *   will be stored in this object.
2265 *
2266 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2267 *
2268 * @return The directive uses rtems_task_create().  If this directive fails,
2269 *   then its error status will be returned.
2270 *
2271 * @par Notes
2272 * See also rtems_interrupt_server_initialize() and
2273 * rtems_interrupt_server_delete().
2274 *
2275 * @par Constraints
2276 * @parblock
2277 * The following constraints apply to this directive:
2278 *
2279 * * The directive may be called from within device driver initialization
2280 *   context.
2281 *
2282 * * The directive may be called from within task context.
2283 *
2284 * * The directive may obtain and release the object allocator mutex.  This may
2285 *   cause the calling task to be preempted.
2286 * @endparblock
2287 */
2288rtems_status_code rtems_interrupt_server_create(
2289  rtems_interrupt_server_control      *control,
2290  const rtems_interrupt_server_config *config,
2291  uint32_t                            *server_index
2292);
2293
2294/* Generated from spec:/rtems/intr/if/server-handler-install */
2295
2296/**
2297 * @ingroup RTEMSAPIClassicIntr
2298 *
2299 * @brief Installs the interrupt handler routine and argument at the interrupt
2300 *   vector on the interrupt server.
2301 *
2302 * @param server_index is the interrupt server index.  The constant
2303 *   #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
2304 *   interrupt server.
2305 *
2306 * @param vector is the interrupt vector number.
2307 *
2308 * @param info is the descriptive information of the interrupt handler to
2309 *   install.
2310 *
2311 * @param options is the interrupt handler install option set.
2312 *
2313 * @param routine is the interrupt handler routine to install.
2314 *
2315 * @param arg is the interrupt handler argument to install.
2316 *
2317 * The handler routine specified by ``routine`` will be executed within the
2318 * context of the interrupt server task specified by ``server_index``.
2319 *
2320 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2321 *
2322 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2323 *   index specified by ``server_index``.
2324 *
2325 * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
2326 *   interrupt context.
2327 *
2328 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
2329 *
2330 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
2331 *   number specified by ``vector``.
2332 *
2333 * @retval ::RTEMS_INVALID_NUMBER An option specified by ``info`` was not
2334 *   applicable.
2335 *
2336 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set
2337 *   in ``info`` and the interrupt vector was already occupied by a handler.
2338 *
2339 * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set
2340 *   in ``info`` and the interrupt vector was already occupied by a unique
2341 *   handler.
2342 *
2343 * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already
2344 *   installed for the interrupt vector specified by ``vector`` with an
2345 *   argument equal to the argument specified by ``arg``.
2346 *
2347 * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in
2348 *   ``info`` and no handler to replace was installed.
2349 *
2350 * @par Notes
2351 * See also rtems_interrupt_handler_install().
2352 *
2353 * @par Constraints
2354 * @parblock
2355 * The following constraints apply to this directive:
2356 *
2357 * * The directive may be called from within device driver initialization
2358 *   context.
2359 *
2360 * * The directive may be called from within task context.
2361 *
2362 * * The directive may obtain and release the object allocator mutex.  This may
2363 *   cause the calling task to be preempted.
2364 * @endparblock
2365 */
2366rtems_status_code rtems_interrupt_server_handler_install(
2367  uint32_t                server_index,
2368  rtems_vector_number     vector,
2369  const char             *info,
2370  rtems_option            options,
2371  rtems_interrupt_handler routine,
2372  void                   *arg
2373);
2374
2375/* Generated from spec:/rtems/intr/if/server-handler-remove */
2376
2377/**
2378 * @ingroup RTEMSAPIClassicIntr
2379 *
2380 * @brief Removes the interrupt handler routine and argument from the interrupt
2381 *   vector and the interrupt server.
2382 *
2383 * @param server_index is the interrupt server index.  The constant
2384 *   #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
2385 *   interrupt server.
2386 *
2387 * @param vector is the interrupt vector number.
2388 *
2389 * @param routine is the interrupt handler routine to remove.
2390 *
2391 * @param arg is the interrupt handler argument to remove.
2392 *
2393 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2394 *
2395 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2396 *   index specified by ``server_index``.
2397 *
2398 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
2399 *   number specified by ``vector``.
2400 *
2401 * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair
2402 *   installed specified by ``routine`` and ``arg``.
2403 *
2404 * @par Constraints
2405 * @parblock
2406 * The following constraints apply to this directive:
2407 *
2408 * * The directive may be called from within task context.
2409 *
2410 * * The directive may obtain and release the object allocator mutex.  This may
2411 *   cause the calling task to be preempted.
2412 *
2413 * * The directive sends a request to another task and waits for a response.
2414 *   This may cause the calling task to be blocked and unblocked.
2415 *
2416 * * The directive shall not be called from within the context of an interrupt
2417 *   server.  Calling the directive from within the context of an interrupt
2418 *   server is undefined behaviour.
2419 * @endparblock
2420 */
2421rtems_status_code rtems_interrupt_server_handler_remove(
2422  uint32_t                server_index,
2423  rtems_vector_number     vector,
2424  rtems_interrupt_handler routine,
2425  void                   *arg
2426);
2427
2428/* Generated from spec:/rtems/intr/if/server-set-affinity */
2429
2430/**
2431 * @ingroup RTEMSAPIClassicIntr
2432 *
2433 * @brief Sets the processor affinity of the interrupt server.
2434 *
2435 * @param server_index is the interrupt server index.  The constant
2436 *   #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
2437 *   interrupt server.
2438 *
2439 * @param affinity_size is the size of the processor set referenced by
2440 *   ``affinity`` in bytes.
2441 *
2442 * @param affinity is the pointer to a cpu_set_t object.  The processor set
2443 *   defines the new processor affinity set of the interrupt server.  A set bit
2444 *   in the processor set means that the corresponding processor shall be in
2445 *   the processor affinity set of the task, otherwise the bit shall be
2446 *   cleared.
2447 *
2448 * @param priority is the new real priority for the interrupt server.
2449 *
2450 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2451 *
2452 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2453 *   index specified by ``server_index``.
2454 *
2455 * @return The directive uses rtems_scheduler_ident_by_processor_set(),
2456 *   rtems_task_set_scheduler(), and rtems_task_set_affinity().  If one of
2457 *   these directive fails, then its error status will be returned.
2458 *
2459 * @par Notes
2460 * @parblock
2461 * The scheduler is set determined by the highest numbered processor in the
2462 * affinity set specified by ``affinity``.
2463 *
2464 * This operation is only reliable in case the interrupt server was suspended
2465 * via rtems_interrupt_server_suspend().
2466 * @endparblock
2467 *
2468 * @par Constraints
2469 * @parblock
2470 * The following constraints apply to this directive:
2471 *
2472 * * The directive may be called from within interrupt context.
2473 *
2474 * * The directive may be called from within device driver initialization
2475 *   context.
2476 *
2477 * * The directive may be called from within task context.
2478 *
2479 * * The directive may change the processor affinity of a task.  This may cause
2480 *   the calling task to be preempted.
2481 *
2482 * * The directive may change the priority of a task.  This may cause the
2483 *   calling task to be preempted.
2484 * @endparblock
2485 */
2486rtems_status_code rtems_interrupt_server_set_affinity(
2487  uint32_t            server_index,
2488  size_t              affinity_size,
2489  const cpu_set_t    *affinity,
2490  rtems_task_priority priority
2491);
2492
2493/* Generated from spec:/rtems/intr/if/server-delete */
2494
2495/**
2496 * @ingroup RTEMSAPIClassicIntr
2497 *
2498 * @brief Deletes the interrupt server.
2499 *
2500 * @param server_index is the index of the interrupt server to delete.
2501 *
2502 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2503 *
2504 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2505 *   server index specified by ``server_index``.
2506 *
2507 * @par Notes
2508 * @parblock
2509 * The interrupt server deletes itself, so after the return of the directive
2510 * the interrupt server may be still in the termination process depending on
2511 * the task priorities of the system.
2512 *
2513 * See also rtems_interrupt_server_create().
2514 * @endparblock
2515 *
2516 * @par Constraints
2517 * @parblock
2518 * The following constraints apply to this directive:
2519 *
2520 * * The directive may be called from within task context.
2521 *
2522 * * The directive shall not be called from within the context of an interrupt
2523 *   server.  Calling the directive from within the context of an interrupt
2524 *   server is undefined behaviour.
2525 *
2526 * * The directive sends a request to another task and waits for a response.
2527 *   This may cause the calling task to be blocked and unblocked.
2528 * @endparblock
2529 */
2530rtems_status_code rtems_interrupt_server_delete( uint32_t server_index );
2531
2532/* Generated from spec:/rtems/intr/if/server-suspend */
2533
2534/**
2535 * @ingroup RTEMSAPIClassicIntr
2536 *
2537 * @brief Suspends the interrupt server.
2538 *
2539 * @param server_index is the index of the interrupt server to suspend.  The
2540 *   constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
2541 *   default interrupt server.
2542 *
2543 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2544 *
2545 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2546 *   index specified by ``server_index``.
2547 *
2548 * @par Notes
2549 * Interrupt server may be resumed by rtems_interrupt_server_resume().
2550 *
2551 * @par Constraints
2552 * @parblock
2553 * The following constraints apply to this directive:
2554 *
2555 * * The directive may be called from within task context.
2556 *
2557 * * The directive shall not be called from within the context of an interrupt
2558 *   server.  Calling the directive from within the context of an interrupt
2559 *   server is undefined behaviour.
2560 *
2561 * * The directive sends a request to another task and waits for a response.
2562 *   This may cause the calling task to be blocked and unblocked.
2563 * @endparblock
2564 */
2565rtems_status_code rtems_interrupt_server_suspend( uint32_t server_index );
2566
2567/* Generated from spec:/rtems/intr/if/server-resume */
2568
2569/**
2570 * @ingroup RTEMSAPIClassicIntr
2571 *
2572 * @brief Resumes the interrupt server.
2573 *
2574 * @param server_index is the index of the interrupt server to resume.  The
2575 *   constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
2576 *   default interrupt server.
2577 *
2578 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2579 *
2580 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2581 *   index specified by ``server_index``.
2582 *
2583 * @par Notes
2584 * Interrupt server may be suspended by rtems_interrupt_server_suspend().
2585 *
2586 * @par Constraints
2587 * @parblock
2588 * The following constraints apply to this directive:
2589 *
2590 * * The directive may be called from within task context.
2591 *
2592 * * The directive shall not be called from within the context of an interrupt
2593 *   server.  Calling the directive from within the context of an interrupt
2594 *   server is undefined behaviour.
2595 *
2596 * * The directive sends a request to another task and waits for a response.
2597 *   This may cause the calling task to be blocked and unblocked.
2598 * @endparblock
2599 */
2600rtems_status_code rtems_interrupt_server_resume( uint32_t server_index );
2601
2602/* Generated from spec:/rtems/intr/if/server-move */
2603
2604/**
2605 * @ingroup RTEMSAPIClassicIntr
2606 *
2607 * @brief Moves the interrupt handlers installed at the interrupt vector and
2608 *   the source interrupt server to the destination interrupt server.
2609 *
2610 * @param source_server_index is the index of the source interrupt server.  The
2611 *   constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
2612 *   default interrupt server.
2613 *
2614 * @param vector is the interrupt vector number.
2615 *
2616 * @param destination_server_index is the index of the destination interrupt
2617 *   server.  The constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to
2618 *   specify the default interrupt server.
2619 *
2620 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2621 *
2622 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2623 *   index specified by ``source_server_index``.
2624 *
2625 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2626 *   index specified by ``destination_server_index``.
2627 *
2628 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
2629 *   number specified by ``vector``.
2630 *
2631 * @par Constraints
2632 * @parblock
2633 * The following constraints apply to this directive:
2634 *
2635 * * The directive may be called from within task context.
2636 *
2637 * * The directive shall not be called from within the context of an interrupt
2638 *   server.  Calling the directive from within the context of an interrupt
2639 *   server is undefined behaviour.
2640 *
2641 * * The directive sends a request to another task and waits for a response.
2642 *   This may cause the calling task to be blocked and unblocked.
2643 * @endparblock
2644 */
2645rtems_status_code rtems_interrupt_server_move(
2646  uint32_t            source_server_index,
2647  rtems_vector_number vector,
2648  uint32_t            destination_server_index
2649);
2650
2651/* Generated from spec:/rtems/intr/if/server-handler-iterate */
2652
2653/**
2654 * @ingroup RTEMSAPIClassicIntr
2655 *
2656 * @brief Iterates over all interrupt handler installed at the interrupt vector
2657 *   and interrupt server.
2658 *
2659 * @param server_index is the index of the interrupt server.
2660 *
2661 * @param vector is the interrupt vector number.
2662 *
2663 * @param routine is the visitor routine.
2664 *
2665 * @param arg is the visitor argument.
2666 *
2667 * For each installed handler at the interrupt vector and interrupt server the
2668 * visitor function specified by ``vector`` will be called with the argument
2669 * specified by ``routine`` and the handler information, options, routine and
2670 * argument.
2671 *
2672 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2673 *
2674 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2675 *   index specified by ``server_index``.
2676 *
2677 * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
2678 *   number specified by ``vector``.
2679 *
2680 * @par Notes
2681 * @parblock
2682 * The directive is intended for system information and diagnostics.
2683 *
2684 * Never install or remove an interrupt handler within the visitor function.
2685 * This may result in a deadlock.
2686 * @endparblock
2687 *
2688 * @par Constraints
2689 * @parblock
2690 * The following constraints apply to this directive:
2691 *
2692 * * The directive may be called from within device driver initialization
2693 *   context.
2694 *
2695 * * The directive may be called from within task context.
2696 *
2697 * * The directive may obtain and release the object allocator mutex.  This may
2698 *   cause the calling task to be preempted.
2699 * @endparblock
2700 */
2701rtems_status_code rtems_interrupt_server_handler_iterate(
2702  uint32_t                            server_index,
2703  rtems_vector_number                 vector,
2704  rtems_interrupt_per_handler_routine routine,
2705  void                               *arg
2706);
2707
2708/* Generated from spec:/rtems/intr/if/server-action */
2709
2710/**
2711 * @ingroup RTEMSAPIClassicIntr
2712 *
2713 * @brief This structure represents an interrupt server action.
2714 *
2715 * @par Notes
2716 * This structure shall be treated as an opaque data type from the API point of
2717 * view.  Members shall not be accessed directly.
2718 */
2719typedef struct rtems_interrupt_server_action {
2720  /**
2721   * @brief This member is the reference to the next action or NULL.
2722   */
2723  struct rtems_interrupt_server_action *next;
2724
2725  /**
2726   * @brief This member is the interrupt handler.
2727   */
2728  rtems_interrupt_handler handler;
2729
2730  /**
2731   * @brief This member is the interrupt handler argument.
2732   */
2733  void *arg;
2734} rtems_interrupt_server_action;
2735
2736/* Generated from spec:/rtems/intr/if/server-entry */
2737
2738/**
2739 * @ingroup RTEMSAPIClassicIntr
2740 *
2741 * @brief This structure represents an interrupt server entry.
2742 *
2743 * @par Notes
2744 * This structure shall be treated as an opaque data type from the API point of
2745 * view.  Members shall not be accessed directly.  An entry is initialized by
2746 * rtems_interrupt_server_entry_initialize() and destroyed by
2747 * rtems_interrupt_server_entry_destroy().  Interrupt server actions can be
2748 * prepended to the entry by rtems_interrupt_server_action_prepend().  The
2749 * entry is submitted to be serviced by rtems_interrupt_server_entry_submit().
2750 */
2751typedef struct {
2752  /**
2753   * @brief This member is the node for the interrupt entry processing.
2754   */
2755  Chain_Node node;
2756
2757  /**
2758   * @brief This member references the interrupt server used to process the
2759   *   entry.
2760   */
2761  rtems_interrupt_server_control *server;
2762
2763  /**
2764   * @brief This member is the interrupt vector number.
2765   */
2766  rtems_vector_number vector;
2767
2768  /**
2769   * @brief This member is the interrupt server actions list head.
2770   */
2771  rtems_interrupt_server_action *actions;
2772} rtems_interrupt_server_entry;
2773
2774/* Generated from spec:/rtems/intr/if/server-entry-initialize */
2775
2776/**
2777 * @ingroup RTEMSAPIClassicIntr
2778 *
2779 * @brief Initializes the interrupt server entry.
2780 *
2781 * @param server_index is the interrupt server index.  The constant
2782 *   #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
2783 *   interrupt server.
2784 *
2785 * @param entry is the interrupt server entry to initialize.
2786 *
2787 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2788 *
2789 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2790 *   index specified by ``server_index``.
2791 *
2792 * @par Notes
2793 * After initialization, the list of actions of the interrupt server entry is
2794 * empty.  Actions may be prepended by rtems_interrupt_server_action_prepend().
2795 * Interrupt server entries may be moved to another interrupt vector with
2796 * rtems_interrupt_server_entry_move().  Server entries may be submitted to get
2797 * serviced by the interrupt server with rtems_interrupt_server_entry_submit().
2798 * Server entries may be destroyed by rtems_interrupt_server_entry_destroy().
2799 *
2800 * @par Constraints
2801 * @parblock
2802 * The following constraints apply to this directive:
2803 *
2804 * * The directive may be called from within device driver initialization
2805 *   context.
2806 *
2807 * * The directive may be called from within task context.
2808 *
2809 * * The directive may obtain and release the object allocator mutex.  This may
2810 *   cause the calling task to be preempted.
2811 * @endparblock
2812 */
2813rtems_status_code rtems_interrupt_server_entry_initialize(
2814  uint32_t                      server_index,
2815  rtems_interrupt_server_entry *entry
2816);
2817
2818/* Generated from spec:/rtems/intr/if/server-action-prepend */
2819
2820/**
2821 * @ingroup RTEMSAPIClassicIntr
2822 *
2823 * @brief Prepends the interrupt server action to the list of actions of the
2824 *   interrupt server entry.
2825 *
2826 * @param[in,out] entry is the interrupt server entry to prepend the interrupt
2827 *   server action.  It shall have been initialized via
2828 *   rtems_interrupt_server_entry_initialize().
2829 *
2830 * @param[out] action is the interrupt server action to initialize and prepend
2831 *   to the list of actions of the entry.
2832 *
2833 * @param routine is the interrupt handler routine to set in the action.
2834 *
2835 * @param arg is the interrupt handler argument to set in the action.
2836 *
2837 * @par Notes
2838 * No error checking is performed by the directive.
2839 *
2840 * @par Constraints
2841 * @parblock
2842 * The following constraints apply to this directive:
2843 *
2844 * * The directive may be called from within interrupt context.
2845 *
2846 * * The directive may be called from within device driver initialization
2847 *   context.
2848 *
2849 * * The directive may be called from within task context.
2850 *
2851 * * The directive will not cause the calling task to be preempted.
2852 *
2853 * * The interrupt server entry shall have been initialized by
2854 *   rtems_interrupt_server_entry_initialize() and further optional calls to
2855 *   rtems_interrupt_server_action_prepend().
2856 *
2857 * * The directive shall not be called concurrently with
2858 *   rtems_interrupt_server_action_prepend() with the same interrupt server
2859 *   entry. Calling the directive under this condition is undefined behaviour.
2860 *
2861 * * The directive shall not be called concurrently with
2862 *   rtems_interrupt_server_entry_move() with the same interrupt server entry.
2863 *   Calling the directive under this condition is undefined behaviour.
2864 *
2865 * * The directive shall not be called concurrently with
2866 *   rtems_interrupt_server_entry_submit() with the same interrupt server
2867 *   entry. Calling the directive under this condition is undefined behaviour.
2868 *
2869 * * The directive shall not be called while the interrupt server entry is
2870 *   pending on or serviced by its current interrupt server.  Calling the
2871 *   directive under these conditions is undefined behaviour.
2872 * @endparblock
2873 */
2874void rtems_interrupt_server_action_prepend(
2875  rtems_interrupt_server_entry  *entry,
2876  rtems_interrupt_server_action *action,
2877  rtems_interrupt_handler        routine,
2878  void                          *arg
2879);
2880
2881/* Generated from spec:/rtems/intr/if/server-entry-destroy */
2882
2883/**
2884 * @ingroup RTEMSAPIClassicIntr
2885 *
2886 * @brief Destroys the interrupt server entry.
2887 *
2888 * @param[in,out] entry is the interrupt server entry to destroy.
2889 *
2890 * @par Notes
2891 * No error checking is performed by the directive.
2892 *
2893 * @par Constraints
2894 * @parblock
2895 * The following constraints apply to this directive:
2896 *
2897 * * The directive may be called from within task context.
2898 *
2899 * * The directive shall not be called from within the context of an interrupt
2900 *   server.  Calling the directive from within the context of an interrupt
2901 *   server is undefined behaviour.
2902 *
2903 * * The directive sends a request to another task and waits for a response.
2904 *   This may cause the calling task to be blocked and unblocked.
2905 *
2906 * * The interrupt server entry shall have been initialized by
2907 *   rtems_interrupt_server_entry_initialize() and further optional calls to
2908 *   rtems_interrupt_server_action_prepend().
2909 * @endparblock
2910 */
2911void rtems_interrupt_server_entry_destroy(
2912  rtems_interrupt_server_entry *entry
2913);
2914
2915/* Generated from spec:/rtems/intr/if/server-entry-submit */
2916
2917/**
2918 * @ingroup RTEMSAPIClassicIntr
2919 *
2920 * @brief Submits the interrupt server entry to be serviced by the interrupt
2921 *   server.
2922 *
2923 * @param entry is the interrupt server entry to submit.
2924 *
2925 * The directive appends the entry to the pending entries of the interrupt
2926 * server.  The interrupt server is notified that a new entry is pending.  Once
2927 * the interrupt server is scheduled it services the actions of all pending
2928 * entries.
2929 *
2930 * @par Notes
2931 * @parblock
2932 * This directive may be used to do a two-step interrupt processing.  The first
2933 * step is done from within interrupt context by a call to this directive.  The
2934 * second step is then done from within the context of the interrupt server.
2935 *
2936 * No error checking is performed by the directive.
2937 *
2938 * A submitted entry may be destroyed by
2939 * rtems_interrupt_server_entry_destroy().
2940 * @endparblock
2941 *
2942 * @par Constraints
2943 * @parblock
2944 * The following constraints apply to this directive:
2945 *
2946 * * The directive may be called from within interrupt context.
2947 *
2948 * * The directive may be called from within device driver initialization
2949 *   context.
2950 *
2951 * * The directive may be called from within task context.
2952 *
2953 * * The directive may unblock a task.  This may cause the calling task to be
2954 *   preempted.
2955 *
2956 * * The interrupt server entry shall have been initialized by
2957 *   rtems_interrupt_server_entry_initialize() and further optional calls to
2958 *   rtems_interrupt_server_action_prepend().
2959 *
2960 * * The directive shall not be called concurrently with
2961 *   rtems_interrupt_server_action_prepend() with the same interrupt server
2962 *   entry. Calling the directive under this condition is undefined behaviour.
2963 *
2964 * * The directive shall not be called concurrently with
2965 *   rtems_interrupt_server_entry_move() with the same interrupt server entry.
2966 *   Calling the directive under this condition is undefined behaviour.
2967 * @endparblock
2968 */
2969void rtems_interrupt_server_entry_submit(
2970  rtems_interrupt_server_entry *entry
2971);
2972
2973/* Generated from spec:/rtems/intr/if/server-entry-move */
2974
2975/**
2976 * @ingroup RTEMSAPIClassicIntr
2977 *
2978 * @brief Moves the interrupt server entry to the interrupt server.
2979 *
2980 * @param entry is the interrupt server entry to move.
2981 *
2982 * @param server_index is the index of the destination interrupt server.  The
2983 *   constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
2984 *   default interrupt server.
2985 *
2986 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
2987 *
2988 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
2989 *   index specified by ``server_index``.
2990 *
2991 * @par Constraints
2992 * @parblock
2993 * The following constraints apply to this directive:
2994 *
2995 * * The directive may be called from within device driver initialization
2996 *   context.
2997 *
2998 * * The directive may be called from within task context.
2999 *
3000 * * The directive may obtain and release the object allocator mutex.  This may
3001 *   cause the calling task to be preempted.
3002 *
3003 * * The interrupt server entry shall have been initialized by
3004 *   rtems_interrupt_server_entry_initialize() and further optional calls to
3005 *   rtems_interrupt_server_action_prepend().
3006 *
3007 * * The directive shall not be called concurrently with
3008 *   rtems_interrupt_server_action_prepend() with the same interrupt server
3009 *   entry. Calling the directive under this condition is undefined behaviour.
3010 *
3011 * * The directive shall not be called concurrently with
3012 *   rtems_interrupt_server_entry_move() with the same interrupt server entry.
3013 *   Calling the directive under this condition is undefined behaviour.
3014 *
3015 * * The directive shall not be called concurrently with
3016 *   rtems_interrupt_server_entry_submit() with the same interrupt server
3017 *   entry. Calling the directive under this condition is undefined behaviour.
3018 *
3019 * * The directive shall not be called while the interrupt server entry is
3020 *   pending on or serviced by its current interrupt server.  Calling the
3021 *   directive under these conditions is undefined behaviour.
3022 * @endparblock
3023 */
3024rtems_status_code rtems_interrupt_server_entry_move(
3025  rtems_interrupt_server_entry *entry,
3026  uint32_t                      server_index
3027);
3028
3029/* Generated from spec:/rtems/intr/if/server-request */
3030
3031/**
3032 * @ingroup RTEMSAPIClassicIntr
3033 *
3034 * @brief This structure represents an interrupt server request.
3035 *
3036 * @par Notes
3037 * This structure shall be treated as an opaque data type from the API point of
3038 * view.  Members shall not be accessed directly.  A request is initialized by
3039 * rtems_interrupt_server_request_initialize() and destroyed by
3040 * rtems_interrupt_server_request_destroy().  The interrupt vector of the
3041 * request can be set by rtems_interrupt_server_request_set_vector().  The
3042 * request is submitted to be serviced by
3043 * rtems_interrupt_server_request_submit().
3044 */
3045typedef struct {
3046  /**
3047   * @brief This member is the interrupt server entry.
3048   */
3049  rtems_interrupt_server_entry entry;
3050
3051  /**
3052   * @brief This member is the interrupt server action.
3053   */
3054  rtems_interrupt_server_action action;
3055} rtems_interrupt_server_request;
3056
3057/* Generated from spec:/rtems/intr/if/server-request-initialize */
3058
3059/**
3060 * @ingroup RTEMSAPIClassicIntr
3061 *
3062 * @brief Initializes the interrupt server request.
3063 *
3064 * @param server_index is the interrupt server index.  The constant
3065 *   #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
3066 *   interrupt server.
3067 *
3068 * @param[out] request is the interrupt server request to initialize.
3069 *
3070 * @param routine is the interrupt handler routine for the request action.
3071 *
3072 * @param arg is the interrupt handler argument for the request action.
3073 *
3074 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
3075 *
3076 * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
3077 *   index specified by ``server_index``.
3078 *
3079 * @par Notes
3080 * An interrupt server requests consists of an interrupt server entry and
3081 * exactly one interrupt server action.  The interrupt vector of the request
3082 * may be changed with rtems_interrupt_server_request_set_vector().  Interrupt
3083 * server requests may be submitted to get serviced by the interrupt server
3084 * with rtems_interrupt_server_request_submit().  Requests may be destroyed by
3085 * rtems_interrupt_server_request_destroy().
3086 *
3087 * @par Constraints
3088 * @parblock
3089 * The following constraints apply to this directive:
3090 *
3091 * * The directive may be called from within device driver initialization
3092 *   context.
3093 *
3094 * * The directive may be called from within task context.
3095 *
3096 * * The directive may obtain and release the object allocator mutex.  This may
3097 *   cause the calling task to be preempted.
3098 * @endparblock
3099 */
3100rtems_status_code rtems_interrupt_server_request_initialize(
3101  uint32_t                        server_index,
3102  rtems_interrupt_server_request *request,
3103  rtems_interrupt_handler         routine,
3104  void                           *arg
3105);
3106
3107/* Generated from spec:/rtems/intr/if/server-request-set-vector */
3108
3109/**
3110 * @ingroup RTEMSAPIClassicIntr
3111 *
3112 * @brief Sets the interrupt vector in the interrupt server request.
3113 *
3114 * @param[in,out] request is the interrupt server request to change.
3115 *
3116 * @param vector is the interrupt vector number to be used by the request.
3117 *
3118 * @par Notes
3119 * @parblock
3120 * By default, the interrupt vector of an interrupt server request is set to a
3121 * special value which is outside the range of vectors supported by the
3122 * interrupt controller hardware.
3123 *
3124 * Calls to rtems_interrupt_server_request_submit() will disable the interrupt
3125 * vector of the request.  After processing of the request by the interrupt
3126 * server the interrupt vector will be enabled again.
3127 * @endparblock
3128 *
3129 * @par Constraints
3130 * @parblock
3131 * The following constraints apply to this directive:
3132 *
3133 * * The directive may be called from within interrupt context.
3134 *
3135 * * The directive may be called from within device driver initialization
3136 *   context.
3137 *
3138 * * The directive may be called from within task context.
3139 *
3140 * * The directive will not cause the calling task to be preempted.
3141 *
3142 * * The interrupt server request shall have been initialized by
3143 *   rtems_interrupt_server_request_initialize().
3144 *
3145 * * The directive shall not be called concurrently with
3146 *   rtems_interrupt_server_request_set_vector() with the same interrupt server
3147 *   request.  Calling the directive under this condition is undefined
3148 *   behaviour.
3149 *
3150 * * The directive shall not be called concurrently with
3151 *   rtems_interrupt_server_request_submit() with the same interrupt server
3152 *   request. Calling the directive under this condition is undefined
3153 *   behaviour.
3154 *
3155 * * The directive shall not be called while the interrupt server entry is
3156 *   pending on or serviced by its current interrupt server.  Calling the
3157 *   directive under these conditions is undefined behaviour.
3158 * @endparblock
3159 */
3160static inline void rtems_interrupt_server_request_set_vector(
3161  rtems_interrupt_server_request *request,
3162  rtems_vector_number             vector
3163)
3164{
3165  request->entry.vector = vector;
3166}
3167
3168/* Generated from spec:/rtems/intr/if/server-request-destroy */
3169
3170/**
3171 * @ingroup RTEMSAPIClassicIntr
3172 *
3173 * @brief Destroys the interrupt server request.
3174 *
3175 * @param[in,out] request is the interrupt server request to destroy.
3176 *
3177 * @par Notes
3178 * No error checking is performed by the directive.
3179 *
3180 * @par Constraints
3181 * @parblock
3182 * The following constraints apply to this directive:
3183 *
3184 * * The directive may be called from within task context.
3185 *
3186 * * The directive shall not be called from within the context of an interrupt
3187 *   server.  Calling the directive from within the context of an interrupt
3188 *   server is undefined behaviour.
3189 *
3190 * * The directive sends a request to another task and waits for a response.
3191 *   This may cause the calling task to be blocked and unblocked.
3192 *
3193 * * The interrupt server request shall have been initialized by
3194 *   rtems_interrupt_server_request_initialize().
3195 * @endparblock
3196 */
3197static inline void rtems_interrupt_server_request_destroy(
3198  rtems_interrupt_server_request *request
3199)
3200{
3201  rtems_interrupt_server_entry_destroy( &request->entry );
3202}
3203
3204/* Generated from spec:/rtems/intr/if/server-request-submit */
3205
3206/**
3207 * @ingroup RTEMSAPIClassicIntr
3208 *
3209 * @brief Submits the interrupt server request to be serviced by the interrupt
3210 *   server.
3211 *
3212 * @param[in,out] request is the interrupt server request to submit.
3213 *
3214 * The directive appends the interrupt server entry of the request to the
3215 * pending entries of the interrupt server.  The interrupt server is notified
3216 * that a new entry is pending.  Once the interrupt server is scheduled it
3217 * services the actions of all pending entries.
3218 *
3219 * @par Notes
3220 * @parblock
3221 * This directive may be used to do a two-step interrupt processing.  The first
3222 * step is done from within interrupt context by a call to this directive.  The
3223 * second step is then done from within the context of the interrupt server.
3224 *
3225 * No error checking is performed by the directive.
3226 *
3227 * A submitted request may be destroyed by
3228 * rtems_interrupt_server_request_destroy().
3229 * @endparblock
3230 *
3231 * @par Constraints
3232 * @parblock
3233 * The following constraints apply to this directive:
3234 *
3235 * * The directive may be called from within interrupt context.
3236 *
3237 * * The directive may be called from within device driver initialization
3238 *   context.
3239 *
3240 * * The directive may be called from within task context.
3241 *
3242 * * The directive may unblock a task.  This may cause the calling task to be
3243 *   preempted.
3244 *
3245 * * The interrupt server request shall have been initialized by
3246 *   rtems_interrupt_server_request_initialize().
3247 *
3248 * * The directive shall not be called concurrently with
3249 *   rtems_interrupt_server_request_set_vector() with the same interrupt server
3250 *   request.  Calling the directive under this condition is undefined
3251 *   behaviour.
3252 * @endparblock
3253 */
3254static inline void rtems_interrupt_server_request_submit(
3255  rtems_interrupt_server_request *request
3256)
3257{
3258  rtems_interrupt_server_entry_submit( &request->entry );
3259}
3260
3261#ifdef __cplusplus
3262}
3263#endif
3264
3265#endif /* _RTEMS_RTEMS_INTR_H */
Note: See TracBrowser for help on using the repository browser.