Modules/Interfaces/EDI/edi/edi_interrupts.h

   1 #ifndef EDI_INTERRUPTS_H
   2
   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". */
   9
  10 #define EDI_INTERRUPTS_H
  11
  12 /*! \file edi_interrupts.h
  13  * \brief Declaration and description of EDI's interrupt handling class.
  14  *
  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. */
  23
  24 #include "edi_objects.h"
  25
  26 /*! \brief Macro constant containing the name of the interrupt class
  27  */
  28 #define INTERRUPTS_CLASS        "EDI-INTERRUPT"
  29 /*! \brief The name of EDI's interrupt-handling class.
  30  *
  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;
  34 #else
  35 extern const edi_string_t interrupts_class;
  36 #endif
  37
  38 /*! \brief A pointer to an interrupt handling function.
  39  *
  40  * A pointer to a function called to handle interrupts.  Its unsigned int32_t parameter is the interrupt number that is being
  41  * handled. */
  42 typedef void (*interrupt_handler_t)(uint32_t interrupt_number);
  43
  44 #ifndef IMPLEMENTING_EDI
  45 /*! \brief Initializes an interrupt object with an interrupt number and a pointer to a handler function.
  46  *
  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.
  57  *
  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);
  63 #endif
  64
  65 #endif