µGFX  2.9
version 2.9
gdriver.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.io/license.html
6  */
7 
8 /**
9  * @file src/gdriver/gdriver.h
10  *
11  * @addtogroup GDRIVER
12  *
13  * @brief Module to support registering and unregistering of drivers
14  *
15  * @details GDRIVER provides a generalized way of defining and registering drivers.
16  *
17  * @note There are many different types of drivers and GDRIVER can handle any
18  * type of driver defined by the uGFX system.
19  *
20  * @note GDRIVER supports multiple drivers for one type of device. eg a SSD1289 LCD
21  * driver simultaneously with a framebuffer driver.
22  * @note GDRIVER supports multiple instances of a single driver. eg 2 SSD1289 LCD's.
23  * @note If there is only a single device of a particular type it will automatically
24  * register that device (it only needs to be included in the build, no special
25  * configuration is required)
26  * @note This module gdriver.h file is NOT included in the general gfx.h file.
27  * Instead it is included in each driver type's driver API.
28  *
29  * @pre GFX_USE_GDRIVER must be set to GFXON in your gfxconf.h
30  *
31  * @{
32  */
33 
34 #ifndef _GDRIVER_H
35 #define _GDRIVER_H
36 
37 #if GFX_USE_GDRIVER || defined(__DOXYGEN__)
38 
39 /*===========================================================================*/
40 /* Type definitions */
41 /*===========================================================================*/
42 
43 #define GDRIVER_TYPE_DISPLAY 'g' // @< A graphics display
44 #define GDRIVER_TYPE_MOUSE 'm' // @< A mouse
45 #define GDRIVER_TYPE_TOUCH 'm' // @< A touch display (equivalent to a mouse)
46 #define GDRIVER_TYPE_TOGGLE 't' // @< A toggle device eg GPIO pins, switches etc
47 #define GDRIVER_TYPE_DIAL 'd' // @< A analog or digit dial (ranges in value from a minimum to a maximum)
48 #define GDRIVER_TYPE_KEYBOARD 'k' // @< A keyboard
49 #define GDRIVER_TYPE_BLOCK 'b' // @< A block device
50 #define GDRIVER_TYPE_STRING 's' // @< A device that returns strings of data
51 
52 /**
53  * @brief All runtime driver structures start with this structure
54  *
55  * @note This structure (and any additional structure memory) is allocated
56  * dynamically by the system for each driver instance.
57  */
58 typedef struct GDriver {
59  struct GDriver * driverchain;
60  const struct GDriverVMT * vmt;
62 
63 /**
64  * @brief All driver VMT's start with this structure.
65  */
66 typedef struct GDriverVMT {
67  gU16 type; // @< What type of driver this is
68  gU16 flags; // @< Flags for the driver. Meaning is specific to each driver type.
69  gU32 objsize; // @< How big the runtime driver structure is
70  gBool (*init)(GDriver *driver, void *param, unsigned driverinstance, unsigned systeminstance); // @< Initialise the driver. Returns gTrue if OK.
71  // driverinstance is the instance 0..n of this driver.
72  // systeminstance is the instance 0..n of this type of device.
73  // The memory allocated is cleared before this call.
74  void (*postinit)(GDriver *driver); // @< Called once the driver is registered.
75  void (*deinit)(GDriver *driver); // @< De-initialise the driver
77 
78 /**
79  * @brief A definition that allows getting addresses of GDriverVMT structures to put into a list.
80  * @note eg. <code>
81  * const MyDriverVMTtype a[1] = {{...}};
82  * const MyDriverVMTtype b[1] = {{...}};
83  * ...
84  * \#define DRIVER_LIST a, b
85  * extern GDriverVMTList DRIVER_LIST; // Now treated as single element arrays of GDriverVMT
86  * const GDriverVMT const * mylist = { DRIVER_LIST };
87  * </code>
88  *
89  * @note This could be one single typedef. However, some major compilers complain about duplicate const specifiers even though this is perfectly
90  * valid standard C. As this problem has become worse over time we opt for splitting this into two separate typedefs to prevent these
91  * compilers from throwing warnings.
92  * The single typedef would look like this:
93  * <code>
94  * typedef const struct GDriverVMT const GDriverVMTList[1];
95  * </code>
96  */
97 typedef const struct GDriverVMT ConstGDriverVMT;
98 typedef ConstGDriverVMT const GDriverVMTList[1];
99 
100 /*===========================================================================*/
101 /* External declarations. */
102 /*===========================================================================*/
103 
104 #ifdef __cplusplus
105 extern "C" {
106 #endif
107 
108  /**
109  * @brief Register a new driver instance.
110  * @return The runtime driver structure or NULL if it fails.
111  *
112  * @param[in] vmt The driver's vmt
113  * @param[in] param An arbitrary paramater passed to the driver init routine.
114  */
115  GDriver *gdriverRegister(const GDriverVMT *vmt, void *param);
116 
117  /**
118  * @brief UnRegister a driver instance.
119  *
120  * @param[in] driver The driver instance's runtime structure
121  */
122  void gdriverUnRegister(GDriver *driver);
123 
124  /**
125  * @brief Get the driver for a particular instance of a type of device
126  * @return The runtime driver structure or NULL if it fails.
127  *
128  * @param[in] type The type of driver to find
129  * @param[in] instance The instance (0..n) to find
130  */
131  GDriver *gdriverGetInstance(gU16 type, unsigned instance);
132 
133  /**
134  * @brief Get the count of instances of a type of device
135  * @return The instance count.
136  *
137  * @note Valid instance numbers are then 0 .. count-1
138  *
139  * @param[in] type The type of driver to find
140  */
141  unsigned gdriverInstanceCount(gU16 type);
142 
143  /**
144  * @brief Get the instance number for a device
145  * @return The instance number or (unsigned)-1 if it fails.
146  *
147  * @param[in] driver The driver to find the instance number for
148  */
149  unsigned gdriverGetDriverInstanceNumber(GDriver *driver);
150 
151  /**
152  * @brief Get the next driver for a type of device
153  * @return The runtime driver structure or NULL if there are no more.
154  *
155  * @param[in] type The type of driver to find
156  * @param[in] driver The last driver returned or NULL to start again
157  */
158  GDriver *gdriverGetNext(gU16 type, GDriver *driver);
159 
160 #ifdef __cplusplus
161 }
162 #endif
163 
164 #endif /* GFX_USE_GDRIVER */
165 
166 #endif /* _GDRIVER_H */
167 /** @} */
struct GDriverVMT GDriverVMT
All driver VMT's start with this structure.
GDriver * gdriverRegister(const GDriverVMT *vmt, void *param)
Register a new driver instance.
Definition: gdriver.c:31
GDriver * gdriverGetInstance(gU16 type, unsigned instance)
Get the driver for a particular instance of a type of device.
Definition: gdriver.c:98
struct GDriver GDriver
All runtime driver structures start with this structure.
GDriver * gdriverGetNext(gU16 type, GDriver *driver)
Get the next driver for a type of device.
Definition: gdriver.c:127
void gdriverUnRegister(GDriver *driver)
UnRegister a driver instance.
Definition: gdriver.c:69
unsigned gdriverInstanceCount(gU16 type)
Get the count of instances of a type of device.
Definition: gdriver.c:114
unsigned gdriverGetDriverInstanceNumber(GDriver *driver)
Get the instance number for a device.
Definition: gdriver.c:136
All runtime driver structures start with this structure.
Definition: gdriver.h:58
All driver VMT's start with this structure.
Definition: gdriver.h:66