kobject_init changes - take 2

/**
+ * kobject_init_ng - initialize a kobject structure
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.

+ *
+ * This function will properly initialize a kobject such that it can then
+ * be passed to the kobject_add() call.
+ *
+ * If the function returns an error, the memory allocated by the kobject
+ * can be safely freed, no other functions need to be called.
+ */
+void kobject_init_ng(struct kobject *kobj, struct kobj_type *ktype)

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset

+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

+ *
+ * Under no instance should the kobject that is passed to this function
+ * be directly freed with a call to kfree(), that can leak memory.
+ */

lib/kobject.c +10 -0

+int kobject_add_ng(struct kobject *kobj, struct kobject *parent,
+		   const char *fmt, ...)
+{
+	va_list args;
+	int retval;
+
+	if (!kobj)
+		return -EINVAL;
+
+	va_start(args, fmt);

+/**
+ * kobject_init_and_add - initialize a kobject structure and add it to the kobject hierarchy
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.
+ *
+ * This function will properly initialize a kobject and then call

+ * kobject_add().
+ *
+ * If the function returns an error, the kobject passed to this function
+ * must be cleaned up by calling kobject_put(), and not by directly
+ * trying to call kfree() on the kobject.
+ *
+ * If this function succeeds, the only way to properly clean up the
+ * kobject is to call kobject_destroy(), which will clean up all of the

+ * needed sysfs objects, and the kobject itself (by calling back to the
+ * ktype->release() function.)
+ *
+ * Note that the kobject_uevent() call should be called after this
+ * function succeeds, so that userspace can properly know that the
+ * kobject was created.
+ */

lib/kobject.c +5 -0

+int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
+			 struct kobject *parent, const char *fmt, ...)
+{
+	va_list args;
+	int retval;

Quoted 6 lines · Greg KH

/**
+ * kobject_init_ng - initialize a kobject structure
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.

Quoted 8 lines

+ *
+ * This function will properly initialize a kobject such that it can then
+ * be passed to the kobject_add() call.
+ *
+ * If the function returns an error, the memory allocated by the kobject
+ * can be safely freed, no other functions need to be called.
+ */
+void kobject_init_ng(struct kobject *kobj, struct kobj_type *ktype)

Kerneldoc needs to be updated -- no @parent or @fmt. Also no error returns. But you could say that after this routine runs, the kobject should be deallocated by kobject_put() and not by calling kfree() directly.

Quoted 12 lines

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset

Quoted 8 lines

+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

In which case kobject_put() isn't needed?

Quoted 5 lines

+ *
+ * Under no instance should the kobject that is passed to this function
+ * be directly freed with a call to kfree(), that can leak memory.
+ */

Should you say something here about uevents?

Quoted 16 lines

lib/kobject.c +15 -0

+int kobject_add_ng(struct kobject *kobj, struct kobject *parent,
+		   const char *fmt, ...)
+{
+	va_list args;
+	int retval;
+
+	if (!kobj)
+		return -EINVAL;
+
+	va_start(args, fmt);
+	retval = kobject_set_name_vargs(kobj, fmt, args);
+	va_end(args);
+	if (retval) {
+		printk(KERN_ERR "kobject: can not set name properly!\n");
+		return retval;

lib/kobject.c int kobject_set_name(struct kobject *kob · line 452

Quoted 5 lines

lib/kobject.c +5 -0

+	}
+	kobj->parent = parent;
+	return kobject_add(kobj);
+}
+EXPORT_SYMBOL(kobject_add_ng);

Looks like this should call kobject_add_varg() instead of duplicating its code.

Quoted 17 lines

+/**
+ * kobject_init_and_add - initialize a kobject structure and add it to the kobject hierarchy
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.
+ *
+ * This function will properly initialize a kobject and then call
+ * kobject_add().
+ *
+ * If the function returns an error, the kobject passed to this function
+ * must be cleaned up by calling kobject_put(), and not by directly
+ * trying to call kfree() on the kobject.
+ *
+ * If this function succeeds, the only way to properly clean up the
+ * kobject is to call kobject_destroy(), which will clean up all of the

kobject_destroy()? Where did that come from? Or did you mean kobject_del()?

Quoted 8 lines

+ * needed sysfs objects, and the kobject itself (by calling back to the
+ * ktype->release() function.)
+ *
+ * Note that the kobject_uevent() call should be called after this
+ * function succeeds, so that userspace can properly know that the
+ * kobject was created.
+ */

Could the comments be made shorter by saying merely that this routine combines calls to kobject_init() and kobject_add_ng()?

Quoted 10 lines

lib/kobject.c +9 -0

+int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
+			 struct kobject *parent, const char *fmt, ...)
+{
+	va_list args;
+	int retval;
+
+	kobject_init_ng(kobj, ktype);
+
+	va_start(args, fmt);

lib/kobject.c int kobject_set_name(struct kobject *kob · line 491

Quoted 6 lines

lib/kobject.c +6 -0

+	retval = kobject_add_varg(kobj, parent, fmt, args);
+	va_end(args);
+
+	return retval;
+}
+EXPORT_SYMBOL(kobject_init_and_add);

Looks okay.

Did you want to add an extra kobject_put() to the end of kobject_del()?

Or did you want to define a new kobject_destroy() that combines calls to kobject_del() and kobject_put()?

Quoted 22 lines · Alan Stern

Quoted 11 lines · Greg KH

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset

Quoted 8 lines

+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

Quoted 1 line

In which case kobject_put() isn't needed?

kobject_del() should only undo what kobject_add() did. So kobject_put() will still be needed to clean up the memory. Perhaps the wording should be:

If the function is successful, the only way to properly clean up the kobject is to call kobject_del() for removing the kobject from the hierarchy and to subsequently call kobject_put() to clean up the memory.

Quoted 31 lines · Cornelia Huck

Quoted 22 lines · Alan Stern

Quoted 11 lines · Greg KH

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset

Quoted 8 lines

+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

Quoted 1 line

In which case kobject_put() isn't needed?

kobject_del() should only undo what kobject_add() did. So kobject_put() will still be needed to clean up the memory. Perhaps the wording should be:

Quoted 3 lines

If the function is successful, the only way to properly clean up the kobject is to call kobject_del() for removing the kobject from the hierarchy and to subsequently call kobject_put() to clean up the memory.

But that's not what the code does today in the kobject_del() function.

Quoted 13 lines

Quoted 12 lines

Quoted 4 lines

Quoted 2 lines

+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

In which case kobject_put() isn't needed?

kobject_del() should only undo what kobject_add() did. So kobject_put() will still be needed to clean up the memory. Perhaps the wording should be:

If the function is successful, the only way to properly clean up the kobject is to call kobject_del() for removing the kobject from the hierarchy and to subsequently call kobject_put() to clean up the memory.

Quoted 1 line

But that's not what the code does today in the kobject_del() function.

Hm, if I'm not completely confused, kobject_del() just gives up the extra reference obtained by kobject_add(). That leaves the initial reference we got via kobject_init(_ng)(). If we want to clean up the memory, we need to give up that reference as well.

Quoted 6 lines · Greg KH

/**
+ * kobject_init_ng - initialize a kobject structure
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.

Quoted 8 lines

+ *
+ * This function will properly initialize a kobject such that it can then
+ * be passed to the kobject_add() call.
+ *
+ * If the function returns an error, the memory allocated by the kobject
+ * can be safely freed, no other functions need to be called.
+ */
+void kobject_init_ng(struct kobject *kobj, struct kobj_type *ktype)

Kerneldoc needs to be updated -- no @parent or @fmt. Also no error returns. But you could say that after this routine runs, the kobject should be deallocated by kobject_put() and not by calling kfree() directly.

Quoted 11 lines

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset

Quoted 8 lines

+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del().

In which case kobject_put() isn't needed?

Quoted 4 lines

+ *
+ * Under no instance should the kobject that is passed to this function
+ * be directly freed with a call to kfree(), that can leak memory.
+ */

Should you say something here about uevents?

Quoted 15 lines

(quoted diff) +15 -0

+int kobject_add_ng(struct kobject *kobj, struct kobject *parent,
+		   const char *fmt, ...)
+{
+	va_list args;
+	int retval;
+
+	if (!kobj)
+		return -EINVAL;
+
+	va_start(args, fmt);
+	retval = kobject_set_name_vargs(kobj, fmt, args);
+	va_end(args);
+	if (retval) {
+		printk(KERN_ERR "kobject: can not set name properly!\n");
+		return retval;

Review

Quoted 5 lines

(quoted diff) +5 -0

+	}
+	kobj->parent = parent;
+	return kobject_add(kobj);
+}
+EXPORT_SYMBOL(kobject_add_ng);

Looks like this should call kobject_add_varg() instead of duplicating its code.

Quoted 8 lines

+/**
+ * kobject_init_and_add - initialize a kobject structure and add it to the kobject hierarchy
+ * @kobj: pointer to the kobject to initialize
+ * @ktype: pointer to the ktype for this kobject.
+ * @parent: pointer to the parent of this kobject.
+ * @fmt: the name of the kobject.
+ *
+ * This function will properly initialize a kobject and then call

Quoted 8 lines

+ * kobject_add().
+ *
+ * If the function returns an error, the kobject passed to this function
+ * must be cleaned up by calling kobject_put(), and not by directly
+ * trying to call kfree() on the kobject.
+ *
+ * If this function succeeds, the only way to properly clean up the
+ * kobject is to call kobject_destroy(), which will clean up all of the

kobject_destroy()? Where did that come from? Or did you mean kobject_del()?

Quoted 7 lines

+ * needed sysfs objects, and the kobject itself (by calling back to the
+ * ktype->release() function.)
+ *
+ * Note that the kobject_uevent() call should be called after this
+ * function succeeds, so that userspace can properly know that the
+ * kobject was created.
+ */

Could the comments be made shorter by saying merely that this routine combines calls to kobject_init() and kobject_add_ng()?

Quoted 5 lines

(quoted diff) +5 -0

+int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
+			 struct kobject *parent, const char *fmt, ...)
+{
+	va_list args;
+	int retval;

Review

Quoted 10 lines

(quoted diff) +10 -0

+
+	kobject_init_ng(kobj, ktype);
+
+	va_start(args, fmt);
+	retval = kobject_add_varg(kobj, parent, fmt, args);
+	va_end(args);
+
+	return retval;
+}
+EXPORT_SYMBOL(kobject_init_and_add);

Looks okay.

Did you want to add an extra kobject_put() to the end of kobject_del()? Or did you want to define a new kobject_destroy() that combines calls to kobject_del() and kobject_put()?

Quoted 3 lines

Did you want to add an extra kobject_put() to the end of kobject_del()? Or did you want to define a new kobject_destroy() that combines calls to kobject_del() and kobject_put()?

No, let's keep what we have there on the cleanup path for now. I have enough work to clean up the initializion part of the api for now :)

+/**
+ * kobject_add_ng - the main kobject add function
+ * @kobj: the kobject to add
+ * @parent: pointer to the parent of the kobject.
+ * @fmt: format to name the kobject with.
+ *
+ * The kobject name is set and added to the kobject hierarchy in this
+ * function.
+ *
+ * If @parent is set, then the parent of the @kobj will be set to it.
+ * If @parent is NULL, then the parent of the @kobj will be set to the
+ * kobject associted with the kset assigned to this kobject. If no kset
+ * 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.
+ *
+ * If the function is successful, the only way to properly clean up the
+ * memory is with a call to kobject_del(), in which case, a call to
+ * kobject_put() is not necessary (kobject_del() does the final
+ * kobject_put() to call the release function in the ktype's release
+ * pointer.)