diff options
Diffstat (limited to 'drivers/extcon/extcon.c')
| -rw-r--r-- | drivers/extcon/extcon.c | 279 |
1 files changed, 136 insertions, 143 deletions
diff --git a/drivers/extcon/extcon.c b/drivers/extcon/extcon.c index 8eccf7b14937..35e9fb885486 100644 --- a/drivers/extcon/extcon.c +++ b/drivers/extcon/extcon.c @@ -1,7 +1,5 @@ /* - * drivers/extcon/extcon.c - External Connector (extcon) framework. - * - * External connector (extcon) class driver + * drivers/extcon/extcon.c - External Connector (extcon) framework. * * Copyright (C) 2015 Samsung Electronics * Author: Chanwoo Choi <[email protected]> @@ -37,7 +35,6 @@ #include "extcon.h" #define SUPPORTED_CABLE_MAX 32 -#define CABLE_NAME_MAX 30 struct __extcon_info { unsigned int type; @@ -200,13 +197,13 @@ struct __extcon_info { }; /** - * struct extcon_cable - An internal data for each cable of extcon device. - * @edev: The extcon device - * @cable_index: Index of this cable in the edev - * @attr_g: Attribute group for the cable + * struct extcon_cable - An internal data for an external connector. + * @edev: the extcon device + * @cable_index: the index of this cable in the edev + * @attr_g: the attribute group for the cable * @attr_name: "name" sysfs entry * @attr_state: "state" sysfs entry - * @attrs: Array pointing to attr_name and attr_state for attr_g + * @attrs: the array pointing to attr_name and attr_state for attr_g */ struct extcon_cable { struct extcon_dev *edev; @@ -234,15 +231,6 @@ static struct class *extcon_class; static LIST_HEAD(extcon_dev_list); static DEFINE_MUTEX(extcon_dev_list_lock); -/** - * check_mutually_exclusive - Check if new_state violates mutually_exclusive - * condition. - * @edev: the extcon device - * @new_state: new cable attach status for @edev - * - * Returns 0 if nothing violates. Returns the index + 1 for the first - * violated condition. - */ static int check_mutually_exclusive(struct extcon_dev *edev, u32 new_state) { int i = 0; @@ -417,11 +405,13 @@ static ssize_t cable_state_show(struct device *dev, } /** - * extcon_sync() - Synchronize the states for both the attached/detached - * @edev: the extcon device that has the cable. + * extcon_sync() - Synchronize the state for an external connector. + * @edev: the extcon device + * + * Note that this function send a notification in order to synchronize + * the state and property of an external connector. * - * This function send a notification to synchronize the all states of a - * specific external connector + * Returns 0 if success or error number if fail. */ int extcon_sync(struct extcon_dev *edev, unsigned int id) { @@ -497,9 +487,11 @@ int extcon_sync(struct extcon_dev *edev, unsigned int id) EXPORT_SYMBOL_GPL(extcon_sync); /** - * extcon_get_state() - Get the state of a external connector. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector in extcon enumeration. + * extcon_get_state() - Get the state of an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * + * Returns 0 if success or error number if fail. */ int extcon_get_state(struct extcon_dev *edev, const unsigned int id) { @@ -522,20 +514,19 @@ int extcon_get_state(struct extcon_dev *edev, const unsigned int id) EXPORT_SYMBOL_GPL(extcon_get_state); /** - * extcon_set_state() - Set the state of a external connector. - * without a notification. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @state: the new cable status. The default semantics is - * true: attached / false: detached. + * extcon_set_state() - Set the state of an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @state: the new state of an external connector. + * the default semantics is true: attached / false: detached. + * + * Note that this function set the state of an external connector without + * a notification. To synchronize the state of an external connector, + * have to use extcon_set_state_sync() and extcon_sync(). * - * This function only set the state of a external connector without - * a notification. To synchronize the data of a external connector, - * use extcon_set_state_sync() and extcon_sync(). + * Returns 0 if success or error number if fail. */ -int extcon_set_state(struct extcon_dev *edev, unsigned int id, - bool cable_state) +int extcon_set_state(struct extcon_dev *edev, unsigned int id, bool state) { unsigned long flags; int index, ret = 0; @@ -550,11 +541,11 @@ int extcon_set_state(struct extcon_dev *edev, unsigned int id, spin_lock_irqsave(&edev->lock, flags); /* Check whether the external connector's state is changed. */ - if (!is_extcon_changed(edev, index, cable_state)) + if (!is_extcon_changed(edev, index, state)) goto out; if (check_mutually_exclusive(edev, - (edev->state & ~BIT(index)) | (cable_state & BIT(index)))) { + (edev->state & ~BIT(index)) | (state & BIT(index)))) { ret = -EPERM; goto out; } @@ -563,11 +554,11 @@ int extcon_set_state(struct extcon_dev *edev, unsigned int id, * Initialize the value of extcon property before setting * the detached state for an external connector. */ - if (!cable_state) + if (!state) init_property(edev, id, index); - /* Update the state for a external connector. */ - if (cable_state) + /* Update the state for an external connector. */ + if (state) edev->state |= BIT(index); else edev->state &= ~(BIT(index)); @@ -579,19 +570,18 @@ out: EXPORT_SYMBOL_GPL(extcon_set_state); /** - * extcon_set_state_sync() - Set the state of a external connector - * with a notification. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @state: the new cable status. The default semantics is - * true: attached / false: detached. + * extcon_set_state_sync() - Set the state of an external connector with sync. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @state: the new state of external connector. + * the default semantics is true: attached / false: detached. + * + * Note that this function set the state of external connector + * and synchronize the state by sending a notification. * - * This function set the state of external connector and synchronize the data - * by usning a notification. + * Returns 0 if success or error number if fail. */ -int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, - bool cable_state) +int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, bool state) { int ret, index; unsigned long flags; @@ -602,12 +592,12 @@ int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, /* Check whether the external connector's state is changed. */ spin_lock_irqsave(&edev->lock, flags); - ret = is_extcon_changed(edev, index, cable_state); + ret = is_extcon_changed(edev, index, state); spin_unlock_irqrestore(&edev->lock, flags); if (!ret) return 0; - ret = extcon_set_state(edev, id, cable_state); + ret = extcon_set_state(edev, id, state); if (ret < 0) return ret; @@ -616,19 +606,18 @@ int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_set_state_sync); /** - * extcon_get_property() - Get the property value of a specific cable. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @prop: the property id among enum extcon_property. - * @prop_val: the pointer which store the value of property. + * extcon_get_property() - Get the property value of an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @prop: the property id indicating an extcon property + * @prop_val: the pointer which store the value of extcon property * - * When getting the property value of external connector, the external connector - * should be attached. If detached state, function just return 0 without - * property value. Also, the each property should be included in the list of - * supported properties according to the type of external connectors. + * Note that when getting the property value of external connector, + * the external connector should be attached. If detached state, function + * return 0 without property value. Also, the each property should be + * included in the list of supported properties according to extcon type. * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_get_property(struct extcon_dev *edev, unsigned int id, unsigned int prop, @@ -698,17 +687,16 @@ int extcon_get_property(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_get_property); /** - * extcon_set_property() - Set the property value of a specific cable. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @prop: the property id among enum extcon_property. - * @prop_val: the pointer including the new value of property. + * extcon_set_property() - Set the property value of an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @prop: the property id indicating an extcon property + * @prop_val: the pointer including the new value of extcon property * - * The each property should be included in the list of supported properties - * according to the type of external connectors. + * Note that each property should be included in the list of supported + * properties according to the extcon type. * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_set_property(struct extcon_dev *edev, unsigned int id, unsigned int prop, @@ -766,15 +754,14 @@ int extcon_set_property(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_set_property); /** - * extcon_set_property_sync() - Set the property value of a specific cable - with a notification. - * @prop_val: the pointer including the new value of property. + * extcon_set_property_sync() - Set property of an external connector with sync. + * @prop_val: the pointer including the new value of extcon property * - * When setting the property value of external connector, the external connector - * should be attached. The each property should be included in the list of - * supported properties according to the type of external connectors. + * Note that when setting the property value of external connector, + * the external connector should be attached. The each property should + * be included in the list of supported properties according to extcon type. * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_set_property_sync(struct extcon_dev *edev, unsigned int id, unsigned int prop, @@ -791,12 +778,11 @@ int extcon_set_property_sync(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_set_property_sync); /** - * extcon_get_property_capability() - Get the capability of property - * of an external connector. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @prop: the property id among enum extcon_property. + * extcon_get_property_capability() - Get the capability of the property + * for an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @prop: the property id indicating an extcon property * * Returns 1 if the property is available or 0 if not available. */ @@ -822,18 +808,17 @@ int extcon_get_property_capability(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_get_property_capability); /** - * extcon_set_property_capability() - Set the capability of a property - * of an external connector. - * @edev: the extcon device that has the cable. - * @id: the unique id of each external connector - * in extcon enumeration. - * @prop: the property id among enum extcon_property. + * extcon_set_property_capability() - Set the capability of the property + * for an external connector. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @prop: the property id indicating an extcon property * - * This function set the capability of a property for an external connector - * to mark the bit in capability bitmap which mean the available state of - * a property. + * Note that this function set the capability of the property + * for an external connector in order to mark the bit in capability + * bitmap which mean the available state of the property. * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_set_property_capability(struct extcon_dev *edev, unsigned int id, unsigned int prop) @@ -881,8 +866,10 @@ int extcon_set_property_capability(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_set_property_capability); /** - * extcon_get_extcon_dev() - Get the extcon device instance from the name - * @extcon_name: The extcon name provided with extcon_dev_register() + * extcon_get_extcon_dev() - Get the extcon device instance from the name. + * @extcon_name: the extcon name provided with extcon_dev_register() + * + * Return the pointer of extcon device if success or ERR_PTR(err) if fail. */ struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name) { @@ -904,15 +891,17 @@ out: EXPORT_SYMBOL_GPL(extcon_get_extcon_dev); /** - * extcon_register_notifier() - Register a notifiee to get notified by - * any attach status changes from the extcon. - * @edev: the extcon device that has the external connecotr. - * @id: the unique id of each external connector in extcon enumeration. - * @nb: a notifier block to be registered. + * extcon_register_notifier() - Register a notifier block to get notified by + * any state changes from the extcon. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @nb: a notifier block to be registered * * Note that the second parameter given to the callback of nb (val) is - * "old_state", not the current state. The current state can be retrieved - * by looking at the third pameter (edev pointer)'s state value. + * the current state of an external connector and the third pameter + * is the pointer of extcon device. + * + * Returns 0 if success or error number if fail. */ int extcon_register_notifier(struct extcon_dev *edev, unsigned int id, struct notifier_block *nb) @@ -936,10 +925,12 @@ int extcon_register_notifier(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_register_notifier); /** - * extcon_unregister_notifier() - Unregister a notifiee from the extcon device. - * @edev: the extcon device that has the external connecotr. - * @id: the unique id of each external connector in extcon enumeration. - * @nb: a notifier block to be registered. + * extcon_unregister_notifier() - Unregister a notifier block from the extcon. + * @edev: the extcon device + * @id: the unique id indicating an external connector + * @nb: a notifier block to be registered + * + * Returns 0 if success or error number if fail. */ int extcon_unregister_notifier(struct extcon_dev *edev, unsigned int id, struct notifier_block *nb) @@ -963,16 +954,16 @@ int extcon_unregister_notifier(struct extcon_dev *edev, unsigned int id, EXPORT_SYMBOL_GPL(extcon_unregister_notifier); /** - * extcon_register_notifier_all() - Register a notifier block for all connectors - * @edev: the extcon device that has the external connector. - * @nb: a notifier block to be registered. + * extcon_register_notifier_all() - Register a notifier block for all connectors. + * @edev: the extcon device + * @nb: a notifier block to be registered * - * This function registers a notifier block in order to receive the state - * change of all supported external connectors from extcon device. + * Note that this function registers a notifier block in order to receive + * the state change of all supported external connectors from extcon device. * And the second parameter given to the callback of nb (val) is - * the current state and third parameter is the edev pointer. + * the current state and the third pameter is the pointer of extcon device. * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_register_notifier_all(struct extcon_dev *edev, struct notifier_block *nb) @@ -993,10 +984,10 @@ EXPORT_SYMBOL_GPL(extcon_register_notifier_all); /** * extcon_unregister_notifier_all() - Unregister a notifier block from extcon. - * @edev: the extcon device that has the external connecotr. - * @nb: a notifier block to be registered. + * @edev: the extcon device + * @nb: a notifier block to be registered * - * Returns 0 if success or error number if fail + * Returns 0 if success or error number if fail. */ int extcon_unregister_notifier_all(struct extcon_dev *edev, struct notifier_block *nb) @@ -1045,15 +1036,14 @@ static void dummy_sysfs_dev_release(struct device *dev) /* * extcon_dev_allocate() - Allocate the memory of extcon device. - * @supported_cable: Array of supported extcon ending with EXTCON_NONE. - * If supported_cable is NULL, cable name related APIs - * are disabled. + * @supported_cable: the array of the supported external connectors + * ending with EXTCON_NONE. * - * This function allocates the memory for extcon device without allocating - * memory in each extcon provider driver and initialize default setting for - * extcon device. + * Note that this function allocates the memory for extcon device + * and initialize default setting for the extcon device. * - * Return the pointer of extcon device if success or ERR_PTR(err) if fail + * Returns the pointer memory of allocated extcon_dev if success + * or ERR_PTR(err) if fail. */ struct extcon_dev *extcon_dev_allocate(const unsigned int *supported_cable) { @@ -1074,7 +1064,7 @@ struct extcon_dev *extcon_dev_allocate(const unsigned int *supported_cable) /* * extcon_dev_free() - Free the memory of extcon device. - * @edev: the extcon device to free + * @edev: the extcon device */ void extcon_dev_free(struct extcon_dev *edev) { @@ -1083,13 +1073,18 @@ void extcon_dev_free(struct extcon_dev *edev) EXPORT_SYMBOL_GPL(extcon_dev_free); /** - * extcon_dev_register() - Register a new extcon device - * @edev : the new extcon device (should be allocated before calling) + * extcon_dev_register() - Register an new extcon device + * @edev: the extcon device to be registered * * Among the members of edev struct, please set the "user initializing data" - * in any case and set the "optional callbacks" if required. However, please * do not set the values of "internal data", which are initialized by * this function. + * + * Note that before calling this funciton, have to allocate the memory + * of an extcon device by using the extcon_dev_allocate(). And the extcon + * dev should include the supported_cable information. + * + * Returns 0 if success or error number if fail. */ int extcon_dev_register(struct extcon_dev *edev) { @@ -1296,7 +1291,7 @@ EXPORT_SYMBOL_GPL(extcon_dev_register); /** * extcon_dev_unregister() - Unregister the extcon device. - * @edev: the extcon device instance to be unregistered. + * @edev: the extcon device to be unregistered. * * Note that this does not call kfree(edev) because edev was not allocated * by this class. @@ -1342,11 +1337,11 @@ EXPORT_SYMBOL_GPL(extcon_dev_unregister); #ifdef CONFIG_OF /* - * extcon_get_edev_by_phandle - Get the extcon device from devicetree - * @dev - instance to the given device - * @index - index into list of extcon_dev + * extcon_get_edev_by_phandle - Get the extcon device from devicetree. + * @dev : the instance to the given device + * @index : the index into list of extcon_dev * - * return the instance of extcon device + * Return the pointer of extcon device if success or ERR_PTR(err) if fail. */ struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev, int index) { @@ -1363,8 +1358,8 @@ struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev, int index) node = of_parse_phandle(dev->of_node, "extcon", index); if (!node) { - dev_dbg(dev, "failed to get phandle in %s node\n", - dev->of_node->full_name); + dev_dbg(dev, "failed to get phandle in %pOF node\n", + dev->of_node); return ERR_PTR(-ENODEV); } @@ -1411,8 +1406,6 @@ static void __exit extcon_class_exit(void) module_exit(extcon_class_exit); MODULE_AUTHOR("Chanwoo Choi <[email protected]>"); -MODULE_AUTHOR("Mike Lockwood <[email protected]>"); -MODULE_AUTHOR("Donggeun Kim <[email protected]>"); MODULE_AUTHOR("MyungJoo Ham <[email protected]>"); -MODULE_DESCRIPTION("External connector (extcon) class driver"); -MODULE_LICENSE("GPL"); +MODULE_DESCRIPTION("External Connector (extcon) framework"); +MODULE_LICENSE("GPL v2"); |