The offical µGFX repository.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

167 lines
6.1 KiB

/*
* This file is subject to the terms of the GFX License. If a copy of
* the license was not distributed with this file, you can obtain one at:
*
* http://ugfx.io/license.html
*/
/**
* @file src/gdriver/gdriver.h
*
* @addtogroup GDRIVER
*
* @brief Module to support registering and unregistering of drivers
*
* @details GDRIVER provides a generalized way of defining and registering drivers.
*
* @note There are many different types of drivers and GDRIVER can handle any
* type of driver defined by the uGFX system.
*
* @note GDRIVER supports multiple drivers for one type of device. eg a SSD1289 LCD
* driver simultaneously with a framebuffer driver.
* @note GDRIVER supports multiple instances of a single driver. eg 2 SSD1289 LCD's.
* @note If there is only a single device of a particular type it will automatically
* register that device (it only needs to be included in the build, no special
* configuration is required)
* @note This module gdriver.h file is NOT included in the general gfx.h file.
* Instead it is included in each driver type's driver API.
*
* @pre GFX_USE_GDRIVER must be set to GFXON in your gfxconf.h
*
* @{
*/
#ifndef _GDRIVER_H
#define _GDRIVER_H
#if GFX_USE_GDRIVER || defined(__DOXYGEN__)
/*===========================================================================*/
/* Type definitions */
/*===========================================================================*/
#define GDRIVER_TYPE_DISPLAY 'g' // @< A graphics display
#define GDRIVER_TYPE_MOUSE 'm' // @< A mouse
#define GDRIVER_TYPE_TOUCH 'm' // @< A touch display (equivalent to a mouse)
#define GDRIVER_TYPE_TOGGLE 't' // @< A toggle device eg GPIO pins, switches etc
#define GDRIVER_TYPE_DIAL 'd' // @< A analog or digit dial (ranges in value from a minimum to a maximum)
#define GDRIVER_TYPE_KEYBOARD 'k' // @< A keyboard
#define GDRIVER_TYPE_BLOCK 'b' // @< A block device
#define GDRIVER_TYPE_STRING 's' // @< A device that returns strings of data
/**
* @brief All runtime driver structures start with this structure
*
* @note This structure (and any additional structure memory) is allocated
* dynamically by the system for each driver instance.
*/
typedef struct GDriver {
struct GDriver * driverchain;
const struct GDriverVMT * vmt;
} GDriver;
/**
* @brief All driver VMT's start with this structure.
*/
typedef struct GDriverVMT {
gU16 type; // @< What type of driver this is
gU16 flags; // @< Flags for the driver. Meaning is specific to each driver type.
gU32 objsize; // @< How big the runtime driver structure is
gBool (*init)(GDriver *driver, void *param, unsigned driverinstance, unsigned systeminstance); // @< Initialise the driver. Returns gTrue if OK.
// driverinstance is the instance 0..n of this driver.
// systeminstance is the instance 0..n of this type of device.
// The memory allocated is cleared before this call.
void (*postinit)(GDriver *driver); // @< Called once the driver is registered.
void (*deinit)(GDriver *driver); // @< De-initialise the driver
} GDriverVMT;
/**
* @brief A definition that allows getting addresses of GDriverVMT structures to put into a list.
* @note eg. <code>
* const MyDriverVMTtype a[1] = {{...}};
* const MyDriverVMTtype b[1] = {{...}};
* ...
* \#define DRIVER_LIST a, b
* extern GDriverVMTList DRIVER_LIST; // Now treated as single element arrays of GDriverVMT
* const GDriverVMT const * mylist = { DRIVER_LIST };
* </code>
*
* @note This could be one single typedef. However, some major compilers complain about duplicate const specifiers even though this is perfectly
* valid standard C. As this problem has become worse over time we opt for splitting this into two separate typedefs to prevent these
* compilers from throwing warnings.
* The single typedef would look like this:
* <code>
* typedef const struct GDriverVMT const GDriverVMTList[1];
* </code>
*/
typedef const struct GDriverVMT ConstGDriverVMT;
typedef ConstGDriverVMT const GDriverVMTList[1];
/*===========================================================================*/
/* External declarations. */
/*===========================================================================*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Register a new driver instance.
* @return The runtime driver structure or NULL if it fails.
*
* @param[in] vmt The driver's vmt
* @param[in] param An arbitrary paramater passed to the driver init routine.
*/
GDriver *gdriverRegister(const GDriverVMT *vmt, void *param);
/**
* @brief UnRegister a driver instance.
*
* @param[in] driver The driver instance's runtime structure
*/
void gdriverUnRegister(GDriver *driver);
/**
* @brief Get the driver for a particular instance of a type of device
* @return The runtime driver structure or NULL if it fails.
*
* @param[in] type The type of driver to find
* @param[in] instance The instance (0..n) to find
*/
GDriver *gdriverGetInstance(gU16 type, unsigned instance);
/**
* @brief Get the count of instances of a type of device
* @return The instance count.
*
* @note Valid instance numbers are then 0 .. count-1
*
* @param[in] type The type of driver to find
*/
unsigned gdriverInstanceCount(gU16 type);
/**
* @brief Get the instance number for a device
* @return The instance number or (unsigned)-1 if it fails.
*
* @param[in] driver The driver to find the instance number for
*/
unsigned gdriverGetDriverInstanceNumber(GDriver *driver);
/**
* @brief Get the next driver for a type of device
* @return The runtime driver structure or NULL if there are no more.
*
* @param[in] type The type of driver to find
* @param[in] driver The last driver returned or NULL to start again
*/
GDriver *gdriverGetNext(gU16 type, GDriver *driver);
#ifdef __cplusplus
}
#endif
#endif /* GFX_USE_GDRIVER */
#endif /* _GDRIVER_H */
/** @} */