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". */
12 * \brief The unitive EDI header to include others, start EDI, and stop EDI.
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.
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. */
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"
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.
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.
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. */
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.
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
59 edi_class_declaration_t *driver_classes;
60 /*!\brief The driver's quota function. */
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.
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.
71 * The driver does not need to supply this field, and should supply -1 to indicate that it does not wish to. */
73 /*!\brief The driver's device ID, if applicable.
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. */
78 } edi_initialization_t;
79 /*!\brief A pointer to a driver's initialization function.
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.
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,
92 * The driver must deal with whatever value this routine returns. */
93 bool edi_negotiate_resources();
95 /*! \brief Returns the driver's quota of objects for a given runtime-owned class.
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.
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);
109 /*!\brief A pointer to the driver's finishing/shutdown function.
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)();