Commit 6ab6094f authored by Chanwoo Choi's avatar Chanwoo Choi

extcon: Correct description to improve the readability

The extcon files explains the detailed operation for functions and
what is meaning of extcon structure. There are different explanation
even if the same argument.

So, it modifies the description for both functions and structures
in order to improve the readability and guide the role of functions
more well.

Also, this patch fixes the mismatching license info as a GPL v2
and removes the inactive author information.
Signed-off-by: default avatarChanwoo Choi <cw00.choi@samsung.com>
parent dd4ed69a
...@@ -59,10 +59,9 @@ static void devm_extcon_dev_notifier_all_unreg(struct device *dev, void *res) ...@@ -59,10 +59,9 @@ static void devm_extcon_dev_notifier_all_unreg(struct device *dev, void *res)
/** /**
* devm_extcon_dev_allocate - Allocate managed extcon device * devm_extcon_dev_allocate - Allocate managed extcon device
* @dev: device owning the extcon device being created * @dev: the device owning the extcon device being created
* @supported_cable: Array of supported extcon ending with EXTCON_NONE. * @supported_cable: the array of the supported external connectors
* If supported_cable is NULL, cable name related APIs * ending with EXTCON_NONE.
* are disabled.
* *
* This function manages automatically the memory of extcon device using device * This function manages automatically the memory of extcon device using device
* resource management and simplify the control of freeing the memory of extcon * resource management and simplify the control of freeing the memory of extcon
...@@ -97,8 +96,8 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_allocate); ...@@ -97,8 +96,8 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_allocate);
/** /**
* devm_extcon_dev_free() - Resource-managed extcon_dev_unregister() * devm_extcon_dev_free() - Resource-managed extcon_dev_unregister()
* @dev: device the extcon belongs to * @dev: the device owning the extcon device being created
* @edev: the extcon device to unregister * @edev: the extcon device to be freed
* *
* Free the memory that is allocated with devm_extcon_dev_allocate() * Free the memory that is allocated with devm_extcon_dev_allocate()
* function. * function.
...@@ -112,10 +111,9 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_free); ...@@ -112,10 +111,9 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_free);
/** /**
* devm_extcon_dev_register() - Resource-managed extcon_dev_register() * devm_extcon_dev_register() - Resource-managed extcon_dev_register()
* @dev: device to allocate extcon device * @dev: the device owning the extcon device being created
* @edev: the new extcon device to register * @edev: the extcon device to be registered
* *
* Managed extcon_dev_register() function. If extcon device is attached with
* this function, that extcon device is automatically unregistered on driver * this function, that extcon device is automatically unregistered on driver
* detach. Internally this function calls extcon_dev_register() function. * detach. Internally this function calls extcon_dev_register() function.
* To get more information, refer that function. * To get more information, refer that function.
...@@ -149,8 +147,8 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_register); ...@@ -149,8 +147,8 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_register);
/** /**
* devm_extcon_dev_unregister() - Resource-managed extcon_dev_unregister() * devm_extcon_dev_unregister() - Resource-managed extcon_dev_unregister()
* @dev: device the extcon belongs to * @dev: the device owning the extcon device being created
* @edev: the extcon device to unregister * @edev: the extcon device to unregistered
* *
* Unregister extcon device that is registered with devm_extcon_dev_register() * Unregister extcon device that is registered with devm_extcon_dev_register()
* function. * function.
...@@ -164,10 +162,10 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_unregister); ...@@ -164,10 +162,10 @@ EXPORT_SYMBOL_GPL(devm_extcon_dev_unregister);
/** /**
* devm_extcon_register_notifier() - Resource-managed extcon_register_notifier() * devm_extcon_register_notifier() - Resource-managed extcon_register_notifier()
* @dev: device to allocate extcon device * @dev: the device owning the extcon device being created
* @edev: the extcon device that has the external connecotr. * @edev: the extcon device
* @id: the unique id of each external connector in extcon enumeration. * @id: the unique id among the extcon enumeration
* @nb: a notifier block to be registered. * @nb: a notifier block to be registered
* *
* This function manages automatically the notifier of extcon device using * This function manages automatically the notifier of extcon device using
* device resource management and simplify the control of unregistering * device resource management and simplify the control of unregistering
...@@ -208,10 +206,10 @@ EXPORT_SYMBOL(devm_extcon_register_notifier); ...@@ -208,10 +206,10 @@ EXPORT_SYMBOL(devm_extcon_register_notifier);
/** /**
* devm_extcon_unregister_notifier() * devm_extcon_unregister_notifier()
- Resource-managed extcon_unregister_notifier() - Resource-managed extcon_unregister_notifier()
* @dev: device to allocate extcon device * @dev: the device owning the extcon device being created
* @edev: the extcon device that has the external connecotr. * @edev: the extcon device
* @id: the unique id of each external connector in extcon enumeration. * @id: the unique id among the extcon enumeration
* @nb: a notifier block to be registered. * @nb: a notifier block to be registered
*/ */
void devm_extcon_unregister_notifier(struct device *dev, void devm_extcon_unregister_notifier(struct device *dev,
struct extcon_dev *edev, unsigned int id, struct extcon_dev *edev, unsigned int id,
...@@ -225,9 +223,9 @@ EXPORT_SYMBOL(devm_extcon_unregister_notifier); ...@@ -225,9 +223,9 @@ EXPORT_SYMBOL(devm_extcon_unregister_notifier);
/** /**
* devm_extcon_register_notifier_all() * devm_extcon_register_notifier_all()
* - Resource-managed extcon_register_notifier_all() * - Resource-managed extcon_register_notifier_all()
* @dev: device to allocate extcon device * @dev: the device owning the extcon device being created
* @edev: the extcon device that has the external connecotr. * @edev: the extcon device
* @nb: a notifier block to be registered. * @nb: a notifier block to be registered
* *
* This function manages automatically the notifier of extcon device using * This function manages automatically the notifier of extcon device using
* device resource management and simplify the control of unregistering * device resource management and simplify the control of unregistering
...@@ -263,9 +261,9 @@ EXPORT_SYMBOL(devm_extcon_register_notifier_all); ...@@ -263,9 +261,9 @@ EXPORT_SYMBOL(devm_extcon_register_notifier_all);
/** /**
* devm_extcon_unregister_notifier_all() * devm_extcon_unregister_notifier_all()
* - Resource-managed extcon_unregister_notifier_all() * - Resource-managed extcon_unregister_notifier_all()
* @dev: device to allocate extcon device * @dev: the device owning the extcon device being created
* @edev: the extcon device that has the external connecotr. * @edev: the extcon device
* @nb: a notifier block to be registered. * @nb: a notifier block to be registered
*/ */
void devm_extcon_unregister_notifier_all(struct device *dev, void devm_extcon_unregister_notifier_all(struct device *dev,
struct extcon_dev *edev, struct extcon_dev *edev,
......
This diff is collapsed.
/* /*
* External connector (extcon) class driver * External Connector (extcon) framework
* *
* Copyright (C) 2015 Samsung Electronics * Copyright (C) 2015 Samsung Electronics
* Author: Chanwoo Choi <cw00.choi@samsung.com> * Author: Chanwoo Choi <cw00.choi@samsung.com>
...@@ -20,8 +20,7 @@ ...@@ -20,8 +20,7 @@
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details. * GNU General Public License for more details.
* */
*/
#ifndef __LINUX_EXTCON_H__ #ifndef __LINUX_EXTCON_H__
#define __LINUX_EXTCON_H__ #define __LINUX_EXTCON_H__
...@@ -93,7 +92,7 @@ ...@@ -93,7 +92,7 @@
#define EXTCON_NUM 63 #define EXTCON_NUM 63
/* /*
* Define the property of supported external connectors. * Define the properties of supported external connectors.
* *
* When adding the new extcon property, they *must* have * When adding the new extcon property, they *must* have
* the type/value/default information. Also, you *have to* * the type/value/default information. Also, you *have to*
...@@ -176,44 +175,42 @@ struct extcon_dev; ...@@ -176,44 +175,42 @@ struct extcon_dev;
#if IS_ENABLED(CONFIG_EXTCON) #if IS_ENABLED(CONFIG_EXTCON)
/* /* Following APIs register/unregister the extcon device. */
* Following APIs are for notifiers or configurations.
* Notifiers are the external port and connection devices.
*/
extern int extcon_dev_register(struct extcon_dev *edev); extern int extcon_dev_register(struct extcon_dev *edev);
extern void extcon_dev_unregister(struct extcon_dev *edev); extern void extcon_dev_unregister(struct extcon_dev *edev);
extern int devm_extcon_dev_register(struct device *dev, extern int devm_extcon_dev_register(struct device *dev,
struct extcon_dev *edev); struct extcon_dev *edev);
extern void devm_extcon_dev_unregister(struct device *dev, extern void devm_extcon_dev_unregister(struct device *dev,
struct extcon_dev *edev); struct extcon_dev *edev);
extern struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name);
/* /* Following APIs allocate/free the memory of the extcon device. */
* Following APIs control the memory of extcon device.
*/
extern struct extcon_dev *extcon_dev_allocate(const unsigned int *cable); extern struct extcon_dev *extcon_dev_allocate(const unsigned int *cable);
extern void extcon_dev_free(struct extcon_dev *edev); extern void extcon_dev_free(struct extcon_dev *edev);
extern struct extcon_dev *devm_extcon_dev_allocate(struct device *dev, extern struct extcon_dev *devm_extcon_dev_allocate(struct device *dev,
const unsigned int *cable); const unsigned int *cable);
extern void devm_extcon_dev_free(struct device *dev, struct extcon_dev *edev); extern void devm_extcon_dev_free(struct device *dev, struct extcon_dev *edev);
/* Synchronize the state and property value for each external connector. */
extern int extcon_sync(struct extcon_dev *edev, unsigned int id);
/* /*
* get/set_state access each bit of the 32b encoded state value. * Following APIs get/set the connected state of each external connector.
* They are used to access the status of each cable based on the cable id. * The 'id' argument indicates the defined external connector.
*/ */
extern int extcon_get_state(struct extcon_dev *edev, unsigned int id); extern int extcon_get_state(struct extcon_dev *edev, unsigned int id);
extern int extcon_set_state(struct extcon_dev *edev, unsigned int id, extern int extcon_set_state(struct extcon_dev *edev, unsigned int id,
bool cable_state); bool state);
extern int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, extern int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id,
bool cable_state); bool state);
/*
* Synchronize the state and property data for a specific external connector.
*/
extern int extcon_sync(struct extcon_dev *edev, unsigned int id);
/* /*
* get/set_property access the property value of each external connector. * Following APIs get/set the property of each external connector.
* They are used to access the property of each cable based on the property id. * The 'id' argument indicates the defined external connector
* and the 'prop' indicates the extcon property.
*
* And extcon_get/set_property_capability() set the capability of the property
* for each external connector. They are used to set the capability of the
* property of each external connector based on the id and property.
*/ */
extern int extcon_get_property(struct extcon_dev *edev, unsigned int id, extern int extcon_get_property(struct extcon_dev *edev, unsigned int id,
unsigned int prop, unsigned int prop,
...@@ -224,19 +221,15 @@ extern int extcon_set_property(struct extcon_dev *edev, unsigned int id, ...@@ -224,19 +221,15 @@ extern int extcon_set_property(struct extcon_dev *edev, unsigned int id,
extern int extcon_set_property_sync(struct extcon_dev *edev, unsigned int id, extern int extcon_set_property_sync(struct extcon_dev *edev, unsigned int id,
unsigned int prop, unsigned int prop,
union extcon_property_value prop_val); union extcon_property_value prop_val);
/*
* get/set_property_capability set the capability of the property for each
* external connector. They are used to set the capability of the property
* of each external connector based on the id and property.
*/
extern int extcon_get_property_capability(struct extcon_dev *edev, extern int extcon_get_property_capability(struct extcon_dev *edev,
unsigned int id, unsigned int prop); unsigned int id, unsigned int prop);
extern int extcon_set_property_capability(struct extcon_dev *edev, extern int extcon_set_property_capability(struct extcon_dev *edev,
unsigned int id, unsigned int prop); unsigned int id, unsigned int prop);
/* /*
* Following APIs are to monitor the status change of the external connectors. * Following APIs register the notifier block in order to detect
* the change of both state and property value for each external connector.
*
* extcon_register_notifier(*edev, id, *nb) : Register a notifier block * extcon_register_notifier(*edev, id, *nb) : Register a notifier block
* for specific external connector of the extcon. * for specific external connector of the extcon.
* extcon_register_notifier_all(*edev, *nb) : Register a notifier block * extcon_register_notifier_all(*edev, *nb) : Register a notifier block
...@@ -265,16 +258,15 @@ extern void devm_extcon_unregister_notifier_all(struct device *dev, ...@@ -265,16 +258,15 @@ extern void devm_extcon_unregister_notifier_all(struct device *dev,
struct notifier_block *nb); struct notifier_block *nb);
/* /*
* Following API get the extcon device from devicetree. * Following APIs get the extcon_dev from devicetree or by through extcon name.
* This function use phandle of devicetree to get extcon device directly.
*/ */
extern struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name);
extern struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev, extern struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev,
int index); int index);
/* Following API to get information of extcon device */ /* Following API get the name of extcon device. */
extern const char *extcon_get_edev_name(struct extcon_dev *edev); extern const char *extcon_get_edev_name(struct extcon_dev *edev);
#else /* CONFIG_EXTCON */ #else /* CONFIG_EXTCON */
static inline int extcon_dev_register(struct extcon_dev *edev) static inline int extcon_dev_register(struct extcon_dev *edev)
{ {
...@@ -314,13 +306,13 @@ static inline int extcon_get_state(struct extcon_dev *edev, unsigned int id) ...@@ -314,13 +306,13 @@ static inline int extcon_get_state(struct extcon_dev *edev, unsigned int id)
} }
static inline int extcon_set_state(struct extcon_dev *edev, unsigned int id, static inline int extcon_set_state(struct extcon_dev *edev, unsigned int id,
bool cable_state) bool state)
{ {
return 0; return 0;
} }
static inline int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id, static inline int extcon_set_state_sync(struct extcon_dev *edev, unsigned int id,
bool cable_state) bool state)
{ {
return 0; return 0;
} }
...@@ -362,11 +354,6 @@ static inline int extcon_set_property_capability(struct extcon_dev *edev, ...@@ -362,11 +354,6 @@ static inline int extcon_set_property_capability(struct extcon_dev *edev,
return 0; return 0;
} }
static inline struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name)
{
return NULL;
}
static inline int extcon_register_notifier(struct extcon_dev *edev, static inline int extcon_register_notifier(struct extcon_dev *edev,
unsigned int id, unsigned int id,
struct notifier_block *nb) struct notifier_block *nb)
...@@ -392,6 +379,11 @@ static inline void devm_extcon_unregister_notifier(struct device *dev, ...@@ -392,6 +379,11 @@ static inline void devm_extcon_unregister_notifier(struct device *dev,
struct extcon_dev *edev, unsigned int id, struct extcon_dev *edev, unsigned int id,
struct notifier_block *nb) { } struct notifier_block *nb) { }
static inline struct extcon_dev *extcon_get_extcon_dev(const char *extcon_name)
{
return NULL;
}
static inline struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev, static inline struct extcon_dev *extcon_get_edev_by_phandle(struct device *dev,
int index) int index)
{ {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment