From bcbe3d157904d3dd4d6b18a81859db45a5da2678 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:01 -0600 Subject: dm: Rename dev_get_parentdata() to dev_get_parent_priv() The current name is inconsistent with other driver model data access functions. Rename it and fix up all users. Signed-off-by: Simon Glass Reviewed-by: Joe Hershberger --- include/dm/device.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index 8519612..f152008 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -233,18 +233,18 @@ void *dev_get_parent_platdata(struct udevice *dev); void *dev_get_uclass_platdata(struct udevice *dev); /** - * dev_get_parentdata() - Get the parent data for a device + * dev_get_parent_priv() - Get the parent private data for a device * - * The parent data is data stored in the device but owned by the parent. - * For example, a USB device may have parent data which contains information - * about how to talk to the device over USB. + * The parent private data is data stored in the device but owned by the + * parent. For example, a USB device may have parent data which contains + * information about how to talk to the device over USB. * * This checks that dev is not NULL, but no other checks for now * * @dev Device to check * @return parent data, or NULL if none */ -void *dev_get_parentdata(struct udevice *dev); +void *dev_get_parent_priv(struct udevice *dev); /** * dev_get_priv() - Get the private data for a device -- cgit v1.1 From 9a79f6e6d51f35eca9fff34dd5e4689dfd2c59a8 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:02 -0600 Subject: dm: core: Adjust device.h header file order Move a few functions around so that the ordering is consistent. Signed-off-by: Simon Glass --- include/dm/device.h | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index f152008..e09f897 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -233,6 +233,16 @@ void *dev_get_parent_platdata(struct udevice *dev); void *dev_get_uclass_platdata(struct udevice *dev); /** + * dev_get_priv() - Get the private data for a device + * + * This checks that dev is not NULL, but no other checks for now + * + * @dev Device to check + * @return private data, or NULL if none + */ +void *dev_get_priv(struct udevice *dev); + +/** * dev_get_parent_priv() - Get the parent private data for a device * * The parent private data is data stored in the device but owned by the @@ -247,14 +257,14 @@ void *dev_get_uclass_platdata(struct udevice *dev); void *dev_get_parent_priv(struct udevice *dev); /** - * dev_get_priv() - Get the private data for a device + * dev_get_uclass_priv() - Get the private uclass data for a device * * This checks that dev is not NULL, but no other checks for now * * @dev Device to check - * @return private data, or NULL if none + * @return private uclass data for this device, or NULL if none */ -void *dev_get_priv(struct udevice *dev); +void *dev_get_uclass_priv(struct udevice *dev); /** * struct dev_get_parent() - Get the parent of a device @@ -265,16 +275,6 @@ void *dev_get_priv(struct udevice *dev); struct udevice *dev_get_parent(struct udevice *child); /** - * dev_get_uclass_priv() - Get the private uclass data for a device - * - * This checks that dev is not NULL, but no other checks for now - * - * @dev Device to check - * @return private uclass data for this device, or NULL if none - */ -void *dev_get_uclass_priv(struct udevice *dev); - -/** * dev_get_driver_data() - get the driver data used to bind a device * * When a device is bound using a device tree node, it matches a -- cgit v1.1 From fb04c9d7b80c5f22e79788b9345d4ee551a4fc0b Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:03 -0600 Subject: dm: core: Fix device flag whitespace Line up the flag values in the code for easier readability. Signed-off-by: Simon Glass --- include/dm/device.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index e09f897..286a702 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -21,13 +21,13 @@ struct driver_info; /* Driver is active (probed). Cleared when it is removed */ -#define DM_FLAG_ACTIVATED (1 << 0) +#define DM_FLAG_ACTIVATED (1 << 0) /* DM is responsible for allocating and freeing platdata */ -#define DM_FLAG_ALLOC_PDATA (1 << 1) +#define DM_FLAG_ALLOC_PDATA (1 << 1) /* DM should init this device prior to relocation */ -#define DM_FLAG_PRE_RELOC (1 << 2) +#define DM_FLAG_PRE_RELOC (1 << 2) /* DM is responsible for allocating and freeing parent_platdata */ #define DM_FLAG_ALLOC_PARENT_PDATA (1 << 3) @@ -36,10 +36,10 @@ struct driver_info; #define DM_FLAG_ALLOC_UCLASS_PDATA (1 << 4) /* Allocate driver private data on a DMA boundary */ -#define DM_FLAG_ALLOC_PRIV_DMA (1 << 5) +#define DM_FLAG_ALLOC_PRIV_DMA (1 << 5) /* Device is bound */ -#define DM_FLAG_BOUND (1 << 6) +#define DM_FLAG_BOUND (1 << 6) /** * struct udevice - An instance of a driver -- cgit v1.1 From 93c7fe4a0c2d16ebd44f9740f770a776f63fbaa9 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:04 -0600 Subject: dm: core: Tidy up devres comments Adjust the devres comments to be consistent with the rest of the file, and add one for the struct udevice member. Also rename the 'p' parameter to 'ptr' to avoid single-character names. Signed-off-by: Simon Glass --- include/dm/device.h | 50 ++++++++++++++++++++++++-------------------------- 1 file changed, 24 insertions(+), 26 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index 286a702..f60d153 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -78,6 +78,10 @@ struct driver_info; * @req_seq: Requested sequence number for this device (-1 = any) * @seq: Allocated sequence number for this device (-1 = none). This is set up * when the device is probed and will be unique within the device's uclass. + * @devres_head: List of memory allocations associated with this device. + * When CONFIG_DEVRES is enabled, devm_kmalloc() and friends will + * add to this list. Memory so-allocated will be freed + * automatically when the device is removed / unbound */ struct udevice { const struct driver *driver; @@ -512,7 +516,7 @@ void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp); #endif /** - * devres_alloc - Allocate device resource data + * devres_alloc() - Allocate device resource data * @release: Release function devres will be associated with * @size: Allocation size * @gfp: Allocation flags @@ -528,7 +532,7 @@ void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp); _devres_alloc(release, size, gfp | __GFP_ZERO) /** - * devres_free - Free device resource data + * devres_free() - Free device resource data * @res: Pointer to devres data to free * * Free devres created with devres_alloc(). @@ -536,7 +540,7 @@ void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp); void devres_free(void *res); /** - * devres_add - Register device resource + * devres_add() - Register device resource * @dev: Device to add resource to * @res: Resource to register * @@ -547,7 +551,7 @@ void devres_free(void *res); void devres_add(struct udevice *dev, void *res); /** - * devres_find - Find device resource + * devres_find() - Find device resource * @dev: Device to lookup resource from * @release: Look for resources associated with this release function * @match: Match function (optional) @@ -557,14 +561,13 @@ void devres_add(struct udevice *dev, void *res); * and for which @match returns 1. If @match is NULL, it's considered * to match all. * - * RETURNS: - * Pointer to found devres, NULL if not found. + * @return pointer to found devres, NULL if not found. */ void *devres_find(struct udevice *dev, dr_release_t release, dr_match_t match, void *match_data); /** - * devres_get - Find devres, if non-existent, add one atomically + * devres_get() - Find devres, if non-existent, add one atomically * @dev: Device to lookup or add devres for * @new_res: Pointer to new initialized devres to add if not found * @match: Match function (optional) @@ -574,14 +577,13 @@ void *devres_find(struct udevice *dev, dr_release_t release, * as @new_res and for which @match return 1. If found, @new_res is * freed; otherwise, @new_res is added atomically. * - * RETURNS: - * Pointer to found or added devres. + * @return ointer to found or added devres. */ void *devres_get(struct udevice *dev, void *new_res, dr_match_t match, void *match_data); /** - * devres_remove - Find a device resource and remove it + * devres_remove() - Find a device resource and remove it * @dev: Device to find resource from * @release: Look for resources associated with this release function * @match: Match function (optional) @@ -592,14 +594,13 @@ void *devres_get(struct udevice *dev, void *new_res, * match all. If found, the resource is removed atomically and * returned. * - * RETURNS: - * Pointer to removed devres on success, NULL if not found. + * @return ointer to removed devres on success, NULL if not found. */ void *devres_remove(struct udevice *dev, dr_release_t release, dr_match_t match, void *match_data); /** - * devres_destroy - Find a device resource and destroy it + * devres_destroy() - Find a device resource and destroy it * @dev: Device to find resource from * @release: Look for resources associated with this release function * @match: Match function (optional) @@ -613,14 +614,13 @@ void *devres_remove(struct udevice *dev, dr_release_t release, * only the devres-allocated data will be freed. The caller becomes * responsible for freeing any other data. * - * RETURNS: - * 0 if devres is found and freed, -ENOENT if not found. + * @return 0 if devres is found and freed, -ENOENT if not found. */ int devres_destroy(struct udevice *dev, dr_release_t release, dr_match_t match, void *match_data); /** - * devres_release - Find a device resource and destroy it, calling release + * devres_release() - Find a device resource and destroy it, calling release * @dev: Device to find resource from * @release: Look for resources associated with this release function * @match: Match function (optional) @@ -631,15 +631,14 @@ int devres_destroy(struct udevice *dev, dr_release_t release, * match all. If found, the resource is removed atomically, the * release function called and the resource freed. * - * RETURNS: - * 0 if devres is found and freed, -ENOENT if not found. + * @return 0 if devres is found and freed, -ENOENT if not found. */ int devres_release(struct udevice *dev, dr_release_t release, dr_match_t match, void *match_data); /* managed devm_k.alloc/kfree for device drivers */ /** - * devm_kmalloc - Resource-managed kmalloc + * devm_kmalloc() - Resource-managed kmalloc * @dev: Device to allocate memory for * @size: Allocation size * @gfp: Allocation gfp flags @@ -648,8 +647,7 @@ int devres_release(struct udevice *dev, dr_release_t release, * automatically freed on driver detach. Like all other devres * resources, guaranteed alignment is unsigned long long. * - * RETURNS: - * Pointer to allocated memory on success, NULL on failure. + * @return pointer to allocated memory on success, NULL on failure. */ void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp); static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp) @@ -670,13 +668,13 @@ static inline void *devm_kcalloc(struct udevice *dev, } /** - * devm_kfree - Resource-managed kfree + * devm_kfree() - Resource-managed kfree * @dev: Device this memory belongs to - * @p: Memory to free + * @ptr: Memory to free * * Free memory allocated with devm_kmalloc(). */ -void devm_kfree(struct udevice *dev, void *p); +void devm_kfree(struct udevice *dev, void *ptr); #else /* ! CONFIG_DEVRES */ @@ -750,9 +748,9 @@ static inline void *devm_kcalloc(struct udevice *dev, return kmalloc(n * size, flags | __GFP_ZERO); } -static inline void devm_kfree(struct udevice *dev, void *p) +static inline void devm_kfree(struct udevice *dev, void *ptr) { - kfree(p); + kfree(ptr); } #endif /* ! CONFIG_DEVRES */ -- cgit v1.1 From 99b81a4d862cdf6bb5aea283886f17c12bac8019 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:05 -0600 Subject: dm: core: Remove a comment about dropping per_child_auto_alloc_size This has proven useful and we no-longer intend to remove it. Drop the comment. Signed-off-by: Simon Glass --- include/dm/device.h | 4 ---- 1 file changed, 4 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index f60d153..0e40aaf 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -170,10 +170,6 @@ struct udevice_id { * @per_child_auto_alloc_size: Each device can hold private data owned by * its parent. If required this will be automatically allocated if this * value is non-zero. - * TODO(sjg@chromium.org): I'm considering dropping this, and just having - * device_probe_child() pass it in. So far the use case for allocating it - * is SPI, but I found that unsatisfactory. Since it is here I will leave it - * until things are clearer. * @per_child_platdata_auto_alloc_size: A bus likes to store information about * its children. If non-zero this is the size of this data, to be allocated * in the child's parent_platdata pointer. -- cgit v1.1 From 8d1f3a9daf65baf756fe5ada1567710b476341e6 Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Mon, 28 Sep 2015 23:32:06 -0600 Subject: dm: core: Tidy up comments in device.h Correct a few nits found in a recent review. Expand the comments in dev_get_driver_data() to make it clearer. Signed-off-by: Simon Glass --- include/dm/device.h | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'include/dm') diff --git a/include/dm/device.h b/include/dm/device.h index 0e40aaf..28ba4ca 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -278,13 +278,26 @@ struct udevice *dev_get_parent(struct udevice *child); * dev_get_driver_data() - get the driver data used to bind a device * * When a device is bound using a device tree node, it matches a - * particular compatible string as in struct udevice_id. This function + * particular compatible string in struct udevice_id. This function * returns the associated data value for that compatible string. This is * the 'data' field in struct udevice_id. * + * As an example, consider this structure: + * static const struct udevice_id tegra_i2c_ids[] = { + * { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 }, + * { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD }, + * { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC }, + * { } + * }; + * + * When driver model finds a driver for this it will store the 'data' value + * corresponding to the compatible string it matches. This function returns + * that value. This allows the driver to handle several variants of a device. + * * For USB devices, this is the driver_info field in struct usb_device_id. * * @dev: Device to check + * @return driver data (0 if none is provided) */ ulong dev_get_driver_data(struct udevice *dev); @@ -299,7 +312,7 @@ ulong dev_get_driver_data(struct udevice *dev); */ const void *dev_get_driver_ops(struct udevice *dev); -/* +/** * device_get_uclass_id() - return the uclass ID of a device * * @dev: Device to check @@ -307,7 +320,7 @@ const void *dev_get_driver_ops(struct udevice *dev); */ enum uclass_id device_get_uclass_id(struct udevice *dev); -/* +/** * dev_get_uclass_name() - return the uclass name of a device * * This checks that dev is not NULL. -- cgit v1.1