New kernel drivers and device implementation updates (#561)
- Added modular device support and devicetree bindings for ILI9341, ILI9488, CST816S, XPT2046, and GPIO button input, updating several board configurations for display/touch/backlight/keyboard/battery. - Added a setting to control deprecated HAL usage (device property + Kconfig).
This commit is contained in:
Ken Van Hoeylandt
committed by
GitHub
GitHub
parent
50c0a14a93
commit
fa4a6e255c
@@ -60,7 +60,8 @@ error_t device_construct(struct Device* device);
|
||||
* This fails when a device is busy or has children.
|
||||
*
|
||||
* @param[in,out] device non-null device pointer
|
||||
* @retval ERROR_INVALID_STATE if the device is busy or has children
|
||||
* @retval ERROR_INVALID_STATE if the device is started, added, or has children
|
||||
* @retval ERROR_RESOURCE_BUSY if the device has outstanding device_get() references
|
||||
* @retval ERROR_NONE on success
|
||||
*/
|
||||
error_t device_destruct(struct Device* device);
|
||||
@@ -92,6 +93,9 @@ error_t device_remove(struct Device* device);
|
||||
* Attach the driver.
|
||||
*
|
||||
* @warning must call device_construct() and device_add() first
|
||||
* @warning the driver's start_device callback must not call device_lock()/device_get()/
|
||||
* device_start()/device_stop() on this same device - device_start() holds this
|
||||
* device's lock for its entire body, so doing so would deadlock.
|
||||
* @param[in,out] device non-null device pointer
|
||||
* @retval ERROR_INVALID_STATE if the device is already started or not added
|
||||
* @retval ERROR_RESOURCE when driver binding fails
|
||||
@@ -102,8 +106,12 @@ error_t device_start(struct Device* device);
|
||||
/**
|
||||
* Detach the driver.
|
||||
*
|
||||
* @warning the driver's stop_device callback must not call device_lock()/device_get()/
|
||||
* device_start()/device_stop() on this same device - device_stop() holds this
|
||||
* device's lock for its entire body, so doing so would deadlock.
|
||||
* @param[in,out] device non-null device pointer
|
||||
* @retval ERROR_INVALID_STATE if the device is not started
|
||||
* @retval ERROR_RESOURCE_BUSY if the device has outstanding device_get() references
|
||||
* @retval ERROR_RESOURCE when driver unbinding fails
|
||||
* @retval ERROR_NONE on success
|
||||
*/
|
||||
@@ -226,6 +234,41 @@ bool device_try_lock(struct Device* device, TickType_t timeout);
|
||||
*/
|
||||
void device_unlock(struct Device* device);
|
||||
|
||||
/**
|
||||
* Indicates whether device_construct() has been called and device_destruct() has not
|
||||
* subsequently been called (or has been followed by another device_construct()).
|
||||
*
|
||||
* @param[in] device non-null device pointer
|
||||
* @return true if the device is currently constructed
|
||||
*/
|
||||
bool device_is_constructed(const struct Device* device);
|
||||
|
||||
/**
|
||||
* Take a reference on a device, guaranteeing its driver data remains valid until a matching
|
||||
* device_put(). Named after the Linux kernel's get_device()/put_device(). Intended to bracket
|
||||
* a single hardware operation (one API call or a short sequence of them), not to be held across
|
||||
* a blocking wait or unrelated later work - device_stop() fails with ERROR_RESOURCE_BUSY while
|
||||
* any reference is outstanding.
|
||||
*
|
||||
* @param[in,out] device non-null device pointer, already known to be valid (e.g. a static
|
||||
* devicetree pointer, or one captured earlier under a lock) - device_get() does
|
||||
* not itself protect against a dangling/freed Device*. For a fresh lookup that
|
||||
* might race a concurrent teardown of a dynamically-allocated Device, use one of
|
||||
* the device_get_*() lookup functions below instead.
|
||||
* @retval ERROR_INVALID_STATE if the device is not started (or has been destructed)
|
||||
* @retval ERROR_NONE on success; caller must call device_put(device) exactly once
|
||||
*/
|
||||
error_t device_get(struct Device* device);
|
||||
|
||||
/**
|
||||
* Release a reference previously taken with a successful device_get() (or a successful
|
||||
* device_get_by_name()/device_get_first_by_type()/device_get_first_active_by_type()/
|
||||
* device_get_first_by_compatible()).
|
||||
*
|
||||
* @param[in,out] device non-null device pointer previously passed to a successful device_get() call
|
||||
*/
|
||||
void device_put(struct Device* device);
|
||||
|
||||
/**
|
||||
* Get the type of a device.
|
||||
*
|
||||
@@ -273,7 +316,7 @@ void device_for_each_of_type(const struct DeviceType* type, void* callback_conte
|
||||
* @param[in] type the type to check
|
||||
* @return true if a device of the specified type exists
|
||||
*/
|
||||
bool device_exists_of_type(const struct DeviceType* type);
|
||||
bool device_exists_of_type(const struct DeviceType* type) ;
|
||||
|
||||
/**
|
||||
* Find a device by its name.
|
||||
@@ -281,7 +324,7 @@ bool device_exists_of_type(const struct DeviceType* type);
|
||||
* @param[in] name non-null device name to look up
|
||||
* @return the device pointer if found, or NULL if not found
|
||||
*/
|
||||
struct Device* device_find_by_name(const char* name);
|
||||
struct Device* device_find_by_name(const char* name) __attribute__((deprecated("Use device_get_by_name() and device_put()")));
|
||||
|
||||
/**
|
||||
* Find the first started device of the given type.
|
||||
@@ -289,7 +332,7 @@ struct Device* device_find_by_name(const char* name);
|
||||
* @param[in] type non-null device type pointer
|
||||
* @return the first started device of the given type, or NULL if none found
|
||||
*/
|
||||
struct Device* device_find_first_active_by_type(const struct DeviceType* type);
|
||||
struct Device* device_find_first_active_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_active_by_type() and device_put()")));
|
||||
|
||||
/**
|
||||
* Find the first device of the given type.
|
||||
@@ -297,7 +340,7 @@ struct Device* device_find_first_active_by_type(const struct DeviceType* type);
|
||||
* @param[in] type non-null device type pointer
|
||||
* @return the first device of the given type, or NULL if none found
|
||||
*/
|
||||
struct Device* device_find_first_by_type(const struct DeviceType* type);
|
||||
struct Device* device_find_first_by_type(const struct DeviceType* type) __attribute__((deprecated("Use device_get_first_by_type() and device_put()")));
|
||||
|
||||
/**
|
||||
* Find the first device whose driver matches the given compatible string.
|
||||
@@ -305,7 +348,62 @@ struct Device* device_find_first_by_type(const struct DeviceType* type);
|
||||
* @param[in] compatible non-null compatible string to match
|
||||
* @return the first matching device, or NULL if none found
|
||||
*/
|
||||
struct Device* device_find_first_by_compatible(const char* compatible);
|
||||
struct Device* device_find_first_by_compatible(const char* compatible) __attribute__((deprecated("Use device_get_first_by_compatible() and device_put()")));
|
||||
|
||||
/**
|
||||
* Find a device by name and atomically take a reference on it (equivalent to a device_find_by_name()
|
||||
* immediately followed by a successful device_get(), but race-free: the lookup and the reference
|
||||
* are taken under the same lock, so a device that gets torn down concurrently either isn't found
|
||||
* or is safely referenced - there is no gap where a caller could be handed a pointer that's about
|
||||
* to become invalid). Prefer this over device_find_by_name() + device_get() for any device that
|
||||
* might be dynamically constructed/destructed at runtime (e.g. a hot-pluggable child device),
|
||||
* rather than a static devicetree-defined one.
|
||||
*
|
||||
* @param[in] name non-null device name to look up
|
||||
* @param[out] out_device receives the found device on success; untouched on failure
|
||||
* @retval ERROR_NOT_FOUND if no device with that name exists
|
||||
* @retval ERROR_INVALID_STATE if found but not started (no reference taken)
|
||||
* @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
|
||||
*/
|
||||
error_t device_get_by_name(const char* name, struct Device** out_device);
|
||||
|
||||
/**
|
||||
* Find the first device of the given type and atomically take a reference on it. See
|
||||
* device_get_by_name() for why this is preferred over device_find_first_by_type() + device_get()
|
||||
* for dynamically constructed/destructed devices.
|
||||
*
|
||||
* @param[in] type non-null device type pointer
|
||||
* @param[out] out_device receives the found device on success; untouched on failure
|
||||
* @retval ERROR_NOT_FOUND if no device of that type exists
|
||||
* @retval ERROR_INVALID_STATE if found but not started (no reference taken)
|
||||
* @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
|
||||
*/
|
||||
error_t device_get_first_by_type(const struct DeviceType* type, struct Device** out_device);
|
||||
|
||||
/**
|
||||
* Find the first started device of the given type and atomically take a reference on it. See
|
||||
* device_get_by_name() for why this is preferred over device_find_first_active_by_type() +
|
||||
* device_get() for dynamically constructed/destructed devices.
|
||||
*
|
||||
* @param[in] type non-null device type pointer
|
||||
* @param[out] out_device receives the found device on success; untouched on failure
|
||||
* @retval ERROR_NOT_FOUND if no started device of that type exists
|
||||
* @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
|
||||
*/
|
||||
error_t device_get_first_active_by_type(const struct DeviceType* type, struct Device** out_device);
|
||||
|
||||
/**
|
||||
* Find the first device whose driver matches the given compatible string and atomically take a
|
||||
* reference on it. See device_get_by_name() for why this is preferred over
|
||||
* device_find_first_by_compatible() + device_get() for dynamically constructed/destructed devices.
|
||||
*
|
||||
* @param[in] compatible non-null compatible string to match
|
||||
* @param[out] out_device receives the found device on success; untouched on failure
|
||||
* @retval ERROR_NOT_FOUND if no matching device exists
|
||||
* @retval ERROR_INVALID_STATE if found but not started (no reference taken)
|
||||
* @retval ERROR_NONE on success; caller must call device_put(*out_device) exactly once
|
||||
*/
|
||||
error_t device_get_first_by_compatible(const char* compatible, struct Device** out_device);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
#pragma once
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
struct Device;
|
||||
|
||||
enum DeviceEvent {
|
||||
DEVICE_EVENT_STARTED,
|
||||
DEVICE_EVENT_STOPPED,
|
||||
};
|
||||
|
||||
typedef void (*DeviceListenerCallback)(
|
||||
struct Device *dev,
|
||||
enum DeviceEvent event,
|
||||
void* context
|
||||
);
|
||||
|
||||
struct DeviceEventListener {
|
||||
DeviceListenerCallback callback;
|
||||
void* callback_context;
|
||||
};
|
||||
|
||||
void device_listener_add(DeviceListenerCallback* callback, void* context);
|
||||
|
||||
void device_listener_remove(DeviceListenerCallback* callback);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
@@ -25,6 +25,7 @@ typedef int error_t;
|
||||
#define ERROR_NOT_ALLOWED 11
|
||||
#define ERROR_BUFFER_OVERFLOW 12
|
||||
#define ERROR_OUT_OF_RANGE 13
|
||||
#define ERROR_RESOURCE_BUSY 14 // Rejected: device/driver has outstanding references and cannot be stopped/destructed yet
|
||||
|
||||
/** Convert an error_t to a human-readable text. Useful for logging. */
|
||||
const char* error_to_string(error_t error);
|
||||
|
||||
Reference in New Issue
Block a user