KernelLand/Modules/Interfaces/EDI/edi/edi.h

   1 #ifndef EDI_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_H
  11 /*! \file edi.h
  12  * \brief The unitive EDI header to include others, start EDI, and stop EDI.
  13  *
  14  * Data structures and algorithms this header represents:
  15  *      DATA STRUCTURE: CLASS QUOTAS - The runtime and the driver have the right to set a quota on how many objects of a given class
  16  * owned by that party the other may construct.  These quotas are kept internally by the driver or runtime, are optional and are
  17  * exposed to the other party via the quota() function (for quotas of runtime-owned classes) and the k_quota() function pointer given
  18  * to the runtime by the driver.
  19  *
  20  *      ALGORITHMS: INITIALIZATION AND SHUTDOWN - On initialization of the runtime's EDI environment for this driver it calls the
  21  * driver's driver_init() routine (which must match driver_init_t) to initialize the driver with a list of EDI objects the runtime
  22  * thinks the driver should run with.  The driver then initializes.  This can include calling edi_negotiate_resources() to try and
  23  * obtain more or different objects.  Eventually driver_init() returns an edi_initialization_t structure containing its quota
  24  * function and the list of classes belonging to the driver which the runtime can construct.  Either the driver or the runtime can
  25  * shut down EDI by calling edi_shutdown(), which in turn calls the driver's driver_finish() routine.  On shutdown all objects, of
  26  * classes belonging to both the runtime and driver, are destroyed. */
  27
  28 #include "edi_objects.h"
  29 #include "edi_dma_streams.h"
  30 #include "edi_pthreads.h"
  31 #include "edi_port_io.h"
  32 #include "edi_memory_mapping.h"
  33 #include "edi_devices.h"
  34 #include "edi_interrupts.h"
  35
  36 /*! \brief A pointer to a function the runtime can call if it fails to construct one of the driver's classes to find out what the
  37  * runtime's quota is for that class.
  38  *
  39  * A pointer to a function which takes an edi_string_t as a parameter and returns in int32_t.  This function follows the same
  40  * semantics as the quota() function, returning the number of objects of the given class that can be constructed, -1 for infinity or
  41  * -2 for an erroneous class name.  It is used to tell the runtime the location of such a function in the driver so that the runtime
  42  * can check quotas on driver-owned classes. */
  43 typedef int32_t (*k_quota_t)(edi_string_t resource_class);
  44 /*!\struct edi_initialization_t
  45  * \brief Structure containing driver classes available to the runtime and the driver's quota function after the driver has initialized.
  46  *
  47  * Structure containing driver classes available to runtime, the driver's quota function and the driver's name provided to the runtime
  48  * after the driver has initialized.  driver_bus, vendor_id, and device_id are all optional fields which coders should consider
  49  * supplementary information.  Kernels can require these fields if they so please, but doing so for devices which don't run on a Vendor
  50  * ID/Product ID supporting bus is rather unwise. */
  51 typedef struct {
  52         /*!\brief The number of driver classes in the driver_classes array. */
  53         int32_t num_driver_classes;
  54         /*!\brief An array of declarations of driver classes available to the runtime.
  55          *
  56          * This array should not necessarily contain the entire list of EDI classes implemented by the driver.  Instead, it should
  57          * contain a list of those classes which the driver has correctly initialized itself to provide instances of with full
  58          * functionality. */
  59         edi_class_declaration_t *driver_classes;
  60         /*!\brief The driver's quota function. */
  61         k_quota_t k_quota;
  62         /*!\brief The driver's name. */
  63         edi_string_t driver_name;
  64         /*!\brief The bus of the device this driver wants to drive, if applicable.
  65          *
  66          * The driver does not have to supply this field, and can also supply "MULTIPLE BUSES" here to indicate that it drives devices
  67          * on multiple buses. */
  68         edi_string_t driver_bus;
  69         /*!\brief The driver's vendor ID, if applicable.
  70          *
  71          * The driver does not need to supply this field, and should supply -1 to indicate that it does not wish to. */
  72         int16_t vendor_id;
  73         /*!\brief The driver's device ID, if applicable.
  74          *
  75          * The driver does not need to supply this field, but can supply it along with vendor_id.  If either vendor_id or this field are
  76          * set to -1 the runtime should consider this field not supplied. */
  77         int16_t driver_id;
  78 } edi_initialization_t;
  79 /*!\brief A pointer to a driver's initialization function.
  80  *
  81  * The protocol for the driver's initialization function.  The runtime gives the driver a set of EDI objects representing the
  82  * resources it thinks the driver should run with.  This function returns an edi_initialization_t structure containing declarations
  83  * of the EDI classes the driver can make available to the runtime after initialization.  If any member of that structure contains 0
  84  * or NULL, it is considered invalid and the runtime should destroy the driver without calling its driver_finish() routine. */
  85 typedef edi_initialization_t (*driver_init_t)(int32_t num_resources,edi_object_metadata_t *resources);
  86 /*!\brief Requests more resources from the runtime.  Can be called during driver initialization.
  87  *
  88  * Called to negotiate with the runtime for the right to create further EDI objects/obtain further resources owned by the runtime.
  89  * When the driver calls this routine, the runtime decides whether to grant more resources.  If yes, this call returns true, and the
  90  * driver can proceed to try and create the objects it desires, in addition to destroying EDI objects it doesn't want.  Otherwise,
  91  * it returns false.
  92  * The driver must deal with whatever value this routine returns. */
  93 bool edi_negotiate_resources();
  94
  95 /*! \brief Returns the driver's quota of objects for a given runtime-owned class.
  96  *
  97  * This function takes an edi_string_t with the name of a runtime-owned class in it and returns the number of objects of that class
  98  * which drivers can construct, -1 for infinity, or -2 for an erroneous class name. */
  99 int32_t quota(edi_string_t resource_class);
 100 /*! \brief Sends a string to the operating systems debug output or logging facilities. */
 101 void edi_debug_write(uint32_t debug_string_length, char *debug_string);
 102 /*! \brief This call destroys all objects and shuts down the entire EDI environment of the driver.
 103  *
 104  * This function shuts down EDI as described in INITIALIZATION AND SHUTDOWN above.  All objects are destroyed, EDI functions can no
 105  * longer be successfully called, etc.  This function only succeeds when EDI has already been initialized, so it returns -1 when EDI
 106  * hasn't been, 1 on success, or 0 for all other errors. */
 107 int32_t shutdown_edi(void);
 108
 109 /*!\brief A pointer to the driver's finishing/shutdown function.
 110  *
 111  * The protocol for the driver's shutting down.  This function should do anything the driver wants done before it dies. */
 112 typedef void (*driver_finish_t)();
 113
 114 #endif