1 #ifndef EDI_INTERRUPTS_H
3 /* Copyright (c) 2006 Eli Gottlieb.
4 * Permission is granted to copy, distribute and/or modify this document
5 * under the terms of the GNU Free Documentation License, Version 1.2
6 * or any later version published by the Free Software Foundation;
7 * with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
8 * Texts. A copy of the license is included in the file entitled "COPYING". */
10 #define EDI_INTERRUPTS_H
12 /*! \file edi_interrupts.h
13 * \brief Declaration and description of EDI's interrupt handling class.
15 * Data structures and algorithms this header represents:
16 * DATA STRUCTURE AND ALGORITHM: INTERRUPT OBJECTS - The class EDI-INTERRUPT encapsulates the handling of machine interrupts.
17 * It is initialized with an interrupt number to handle and a handler routine to call when that interrupt occurs. Only a couple of
18 * guarantees are made to the driver regarding the runtime's implementation of interrupt handling: 1) That the driver's handler is
19 * called for every time the interrupt associated with a valid and initialized interrupt object occurs, in the order of the
20 * occurences, 2) That the runtime handle the architecture-specific (general to the entire machine, not just this device)
21 * end-of-interrupt code when the driver is called without first returning from the machine interrupt. Note that the runtime hands
22 * out interrupt numbers at its own discretion and policy. */
24 #include "edi_objects.h"
26 /*! \brief Macro constant containing the name of the interrupt class
28 #define INTERRUPTS_CLASS "EDI-INTERRUPT"
29 /*! \brief The name of EDI's interrupt-handling class.
31 * An edi_string_t holding the name of the runtime-implemented interrupt object class. It's value is "EDI-INTERRUPT". */
32 #if defined(EDI_MAIN_FILE) || defined(IMPLEMENTING_EDI)
33 const edi_string_t interrupts_class = INTERRUPTS_CLASS;
35 extern const edi_string_t interrupts_class;
38 /*! \brief A pointer to an interrupt handling function.
40 * A pointer to a function called to handle interrupts. Its unsigned int32_t parameter is the interrupt number that is being
42 typedef void (*interrupt_handler_t)(uint32_t interrupt_number);
44 #ifndef IMPLEMENTING_EDI
45 /*! \brief Initializes an interrupt object with an interrupt number and a pointer to a handler function.
47 * A pointer to the init_interrupt() method of class EDI-INTERRUPT. This method initializes a newly-created interrupt object with an
48 * interrupt number and a pointer to the driver's handler of type interrupt_handler_t. It can only be called once per object, and
49 * returns 1 on success, fails with -1 when the interrupt number is invalid or unacceptable to the runtime, fails with -2 when the
50 * pointer to the driver's interrupt handler is invalid, and fails with -3 for all other errors. */
51 EDI_DEFVAR int32_t (*init_interrupt)(object_pointer interrupt, uint32_t interrupt_number, interrupt_handler_t handler);
52 /*! \brief Get this interrupt object's interrupt number. */
53 EDI_DEFVAR uint32_t (*interrupt_get_irq)(object_pointer interrupt);
54 /*! \brief Set a new handler for this interrupt object. */
55 EDI_DEFVAR void (*interrupt_set_handler)(object_pointer interrupt, interrupt_handler_t handler);
56 /*! \brief Return from this interrupt, letting the runtime run any necessary End-Of-Interrupt code.
58 * A pointer to the interrupt_return() method of class EDI-INTERRUPT. This method returns from the interrupt designated by the
59 * calling interrupt object. If there is a machine-wide end-of-interrupt procedure and the driver was called during the handling of
60 * the machine interrupt (as opposed to delaying the handling and letting the runtime EOI), the runtime runs it during this method.
61 * This method has no return value, since once it's called control leaves the calling thread. */
62 EDI_DEFVAR void (*interrupt_return)(object_pointer interrupt);