Skip to contentSkip to conversation

kobject: Improve docs for kobject_add/del

PATCH Applied Tobin C. Harding 2 participants 2 messages Apr 28, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 kobject: Improve docs for kobject_add/del

There is currently some confusion on how to wind back kobject_init_and_add() during the error paths in code that uses this function.

Add documentation to kobject_add() and kobject_del() to help clarify the usage.

---

The assumption is that this is the correct usage, and that's what I've tried to document. Is this correct?

void fn(void)

{
	int ret;

	ret = kobject_init_and_add(kobj, ktype, NULL, "foo");
	if (ret) {
		kobject_put(kobj);
		return -1;
	}

	ret = some_init_fn();
	if (ret)
		goto err;

	ret = some_other_init_fn();
	if (ret)
		goto other_err;

	kobject_uevent(kobj, KOBJ_ADD);
	return 0;

other_err:

	other_clean_up_fn();
err:
	kobject_del(kobj);
	return ret;
}

thanks,
Tobin.

 lib/kobject.c | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)
lib/kobject.c +12 -5
index aa89edcd2b63..b2670671977b 100644
@@ -397,15 +397,19 @@ static __printf(3, 0) int kobject_add_varg(struct kobject *kobj,
  * is assigned to the kobject, then the kobject will be located in the
  * root of the sysfs tree.
  *
- * If this function returns an error, kobject_put() must be called to
- * properly clean up the memory associated with the object.
- * Under no instance should the kobject that is passed to this function
- * be directly freed with a call to kfree(), that can leak memory.
- *
  * Note, no "add" uevent will be created with this call, the caller should set
  * up all of the necessary sysfs files for the object and then call
  * kobject_uevent() with the UEVENT_ADD parameter to ensure that
  * userspace is properly notified of this kobject's creation.
+ *
+ * Return: If this function returns an error, kobject_put() must be
+ *         called to properly clean up the memory associated with the
+ *         object.  Under no instance should the kobject that is passed
+ *         to this function be directly freed with a call to kfree(),
+ *         that can leak memory.
+ *
+ *         If this call returns successfully and you later need to unwind
+ *         kobject_add() for the error path you should call kobject_del().
  */
 int kobject_add(struct kobject *kobj, struct kobject *parent,
 		const char *fmt, ...)
@@ -580,6 +584,9 @@ EXPORT_SYMBOL_GPL(kobject_move);
 /**
  * kobject_del - unlink kobject from hierarchy.
  * @kobj: object.
+ *
+ * This is the function that should be called to delete an object
+ * successfully added via kobject_add().
  */
 void kobject_del(struct kobject *kobj)
 {
Signature · 1 line
2.21.0
maintainer Applied
#1 lore raw
Quoted 13 lines · Tobin C. Harding

There is currently some confusion on how to wind back kobject_init_and_add() during the error paths in code that uses this function.

Add documentation to kobject_add() and kobject_del() to help clarify the usage.

---

The assumption is that this is the correct usage, and that's what I've tried to document. Is this correct?

Quoted 8 lines

void fn(void)

{
	int ret;

	ret = kobject_init_and_add(kobj, ktype, NULL, "foo");
	if (ret) {
		kobject_put(kobj);
		return -1;

Don't make up error numbers, use a real one :)

Quoted 13 lines
	}

	ret = some_init_fn();
	if (ret)
		goto err;

	ret = some_other_init_fn();
	if (ret)
		goto other_err;

	kobject_uevent(kobj, KOBJ_ADD);
	return 0;
Quoted 6 lines

other_err:

	other_clean_up_fn();
err:
	kobject_del(kobj);
	return ret;
}

Yes, this looks correct.

I've queued both of these patches up now, thanks!

greg k-h