Merge git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-2.6

df8dc74e · Linus Torvalds <[email protected]> · 2008-01-25 08:34:42 -08:00

This can be broken down into these major areas:
 - Documentation updates (language translations and fixes, as
   well as kobject and kset documenatation updates.)
 - major kset/kobject/ktype rework and fixes.  This cleans up the
   kset and kobject and ktype relationship and architecture,
   making sense of things now, and good documenation and samples
   are provided for others to use.  Also the attributes for
   kobjects are much easier to handle now.  This cleaned up a LOT
   of code all through the kernel, making kobjects easier to use
   if you want to.
 - struct bus_type has been reworked to now handle the lifetime
   rules properly, as the kobject is properly dynamic.
 - struct driver has also been reworked, and now the lifetime
   issues are resolved.
 - the block subsystem has been converted to use struct device
   now, and not "raw" kobjects.  This patch has been in the -mm
   tree for over a year now, and finally all the issues are
   worked out with it.  Older distros now properly work with new
   kernels, and no userspace updates are needed at all.
 - nozomi driver is added.  This has also been in -mm for a long
   time, and many people have asked for it to go in.  It is now
   in good enough shape to do so.
 - lots of class_device conversions to use struct device instead.
   The tree is almost all cleaned up now, only SCSI and IB is the
   remaining code to fix up...

* git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-2.6: (196 commits)
  Driver core: coding style fixes
  Kobject: fix coding style issues in kobject c files
  Kobject: fix coding style issues in kobject.h
  Driver core: fix coding style issues in device.h
  spi: use class iteration api
  scsi: use class iteration api
  rtc: use class iteration api
  power supply : use class iteration api
  ieee1394: use class iteration api
  Driver Core: add class iteration api
  Driver core: Cleanup get_device_parent() in device_add() and device_move()
  UIO: constify function pointer tables
  Driver Core: constify the name passed to platform_device_register_simple
  driver core: fix build with SYSFS=n
  sysfs: make SYSFS_DEPRECATED depend on SYSFS
  Driver core: use LIST_HEAD instead of call to INIT_LIST_HEAD in __init
  kobject: add sample code for how to use ksets/ktypes/kobjects
  kobject: add sample code for how to use kobjects in a simple manner.
  kobject: update the kobject/kset documentation
  kobject: remove old, outdated documentation.
  ...

Commit: df8dc74e8a383eaf2d9b44b80a71ec6f0e52b42e
Parents: 556a169d · 4a3ad20c

Merge commit. Changes below are compared with the first parent: 556a169d.

Changes

217 files changed · +8870 −4631

File	Status	Add	Del	Content
Documentation/kobject.txt	modified	+293	−196	View file
Documentation/pnp.txt	modified	+2	−2	View file
Documentation/s390/cds.txt	modified	+1	−1	View file
Documentation/vm/slabinfo.c	modified	+1	−1	View file
Documentation/vm/slub.txt	modified	+1	−1	View file
Documentation/zh_CN/CodingStyle	added	+701	−0	View file
Documentation/zh_CN/HOWTO	modified	+6	−4	View file
Documentation/zh_CN/SubmittingDrivers	added	+168	−0	View file
Documentation/zh_CN/SubmittingPatches	added	+416	−0	View file
Documentation/zh_CN/oops-tracing.txt	added	+212	−0	View file
Documentation/zh_CN/sparse.txt	added	+100	−0	View file
Documentation/zh_CN/stable_kernel_rules.txt	added	+66	−0	View file
Documentation/zh_CN/volatile-considered-harmful.txt	added	+113	−0	View file
arch/arm/kernel/time.c	modified	+2	−2	View file
arch/arm/mach-integrator/integrator_ap.c	modified	+1	−1	View file
arch/arm/mach-omap1/pm.c	modified	+8	−15	View file
arch/arm/mach-pxa/cm-x270.c	modified	+1	−1	View file
arch/arm/mach-pxa/lpd270.c	modified	+1	−1	View file
arch/arm/mach-pxa/lubbock.c	modified	+1	−1	View file
arch/arm/mach-pxa/mainstone.c	modified	+1	−1	View file
arch/arm/mach-s3c2410/s3c2410.c	modified	+1	−1	View file
arch/arm/mach-s3c2412/s3c2412.c	modified	+1	−1	View file
arch/arm/mach-s3c2440/mach-osiris.c	modified	+1	−1	View file
arch/arm/mach-s3c2443/s3c2443.c	modified	+1	−1	View file
arch/arm/mach-sa1100/irq.c	modified	+1	−1	View file
arch/arm/oprofile/common.c	modified	+1	−1	View file
arch/arm/plat-omap/gpio.c	modified	+1	−1	View file
arch/arm/plat-s3c24xx/dma.c	modified	+1	−1	View file
arch/arm/plat-s3c24xx/s3c244x.c	modified	+2	−2	View file
arch/avr32/kernel/time.c	modified	+1	−1	View file
arch/cris/arch-v32/drivers/iop_fw_load.c	modified	+11	−0	View file
arch/ia64/kernel/topology.c	modified	+13	−13	View file
arch/mips/kernel/i8259.c	modified	+1	−1	View file
arch/powerpc/platforms/cell/spu_base.c	modified	+1	−1	View file
arch/powerpc/platforms/powermac/pic.c	modified	+1	−1	View file
arch/powerpc/platforms/pseries/power.c	modified	+13	−19	View file
arch/powerpc/sysdev/ipic.c	modified	+1	−1	View file
arch/powerpc/sysdev/mpic.c	modified	+1	−1	View file
arch/powerpc/sysdev/qe_lib/qe_ic.c	modified	+1	−1	View file
arch/ppc/syslib/ipic.c	modified	+1	−1	View file
arch/ppc/syslib/open_pic.c	modified	+1	−1	View file
arch/ppc/syslib/open_pic2.c	modified	+1	−1	View file
arch/s390/hypfs/inode.c	modified	+7	−6	View file
arch/s390/kernel/ipl.c	modified	+82	−65	View file
arch/s390/kernel/time.c	modified	+1	−1	View file
arch/sh/drivers/dma/dma-sysfs.c	modified	+1	−1	View file
arch/sh/kernel/cpu/sh4/sq.c	modified	+7	−6	View file
arch/sh/kernel/time.c	modified	+1	−1	View file
arch/x86/kernel/apic_32.c	modified	+1	−1	View file
arch/x86/kernel/apic_64.c	modified	+1	−1	View file
arch/x86/kernel/cpu/intel_cacheinfo.c	modified	+11	−13	View file
arch/x86/kernel/cpu/mcheck/mce_64.c	modified	+1	−1	View file
arch/x86/kernel/cpu/mcheck/mce_amd_64.c	modified	+15	−15	View file
arch/x86/kernel/cpuid.c	modified	+3	−3	View file
arch/x86/kernel/i8237.c	modified	+1	−1	View file
arch/x86/kernel/i8259_32.c	modified	+1	−1	View file
arch/x86/kernel/i8259_64.c	modified	+1	−1	View file
arch/x86/kernel/io_apic_32.c	modified	+1	−1	View file
arch/x86/kernel/io_apic_64.c	modified	+1	−1	View file
arch/x86/kernel/msr.c	modified	+3	−3	View file
arch/x86/kernel/nmi_32.c	modified	+1	−1	View file
arch/x86/kernel/nmi_64.c	modified	+1	−1	View file
arch/x86/oprofile/nmi_int.c	modified	+1	−1	View file
block/elevator.c	modified	+2	−6	View file
block/genhd.c	modified	+184	−235	View file
block/ll_rw_blk.c	modified	+4	−7	View file
drivers/acpi/bus.c	modified	+6	−5	View file
drivers/acpi/pci_link.c	modified	+1	−1	View file
drivers/acpi/system.c	modified	+6	−7	View file
drivers/base/Makefile	modified	+3	−0	View file
drivers/base/attribute_container.c	modified	+1	−8	View file
drivers/base/base.h	modified	+54	−10	View file
drivers/base/bus.c	modified	+264	−237	View file
drivers/base/class.c	modified	+231	−88	View file
drivers/base/core.c	modified	+309	−273	View file
drivers/base/cpu.c	modified	+1	−1	View file
drivers/base/dd.c	modified	+80	−84	View file
drivers/base/driver.c	modified	+141	−75	View file
drivers/base/firmware.c	modified	+8	−18	View file
drivers/base/hypervisor.c	modified	+8	−4	View file
drivers/base/init.c	modified	+3	−7	View file
drivers/base/memory.c	modified	+1	−1	View file
drivers/base/module.c	added	+94	−0	View file
drivers/base/node.c	modified	+1	−1	View file
drivers/base/platform.c	modified	+120	−119	View file
drivers/base/power/Makefile	modified	+0	−1	View file
drivers/base/power/main.c	modified	+330	−172	View file
drivers/base/power/power.h	modified	+12	−7	View file
drivers/base/power/shutdown.c	deleted	+0	−48	View before deletion
drivers/base/sys.c	modified	+20	−29	View file
drivers/block/aoe/aoeblk.c	modified	+25	−26	View file
drivers/block/aoe/aoechr.c	modified	+3	−4	View file
drivers/block/nbd.c	modified	+9	−6	View file
drivers/block/paride/pg.c	modified	+3	−3	View file
drivers/block/paride/pt.c	modified	+6	−6	View file
drivers/block/pktcdvd.c	modified	+13	−14	View file
drivers/char/Kconfig	modified	+10	−0	View file
drivers/char/Makefile	modified	+1	−0	View file
drivers/char/hvc_console.c	modified	+33	−47	View file
drivers/char/hvcs.c	modified	+25	−53	View file
drivers/char/nozomi.c	added	+1993	−0	View file
drivers/cpufreq/cpufreq.c	modified	+4	−8	View file
drivers/cpuidle/sysfs.c	modified	+11	−10	View file
drivers/dma/dmaengine.c	modified	+22	−21	View file
drivers/edac/edac_device_sysfs.c	modified	+17	−32	View file
drivers/edac/edac_mc_sysfs.c	modified	+15	−25	View file
drivers/edac/edac_module.c	modified	+1	−1	View file
drivers/edac/edac_pci_sysfs.c	modified	+11	−24	View file
drivers/firmware/edd.c	modified	+13	−12	View file
drivers/firmware/efivars.c	modified	+57	−73	View file
drivers/i2c/chips/isp1301_omap.c	modified	+0	−6	View file
drivers/ide/ide-probe.c	modified	+1	−1	View file
drivers/ide/ide-tape.c	modified	+6	−8	View file
drivers/ieee1394/nodemgr.c	modified	+176	−138	View file
drivers/infiniband/core/sysfs.c	modified	+11	−28	View file
drivers/infiniband/hw/ehca/ehca_main.c	modified	+8	−5	View file
drivers/infiniband/hw/ipath/ipath_driver.c	modified	+4	−13	View file
drivers/infiniband/hw/ipath/ipath_kernel.h	modified	+1	−2	View file
drivers/infiniband/hw/ipath/ipath_sysfs.c	modified	+5	−25	View file
drivers/isdn/capi/capi.c	modified	+3	−3	View file
drivers/isdn/gigaset/gigaset.h	modified	+0	−6	View file
drivers/kvm/kvm_main.c	modified	+1	−1	View file
drivers/macintosh/adb.c	modified	+1	−1	View file
drivers/macintosh/via-pmu.c	modified	+1	−1	View file
drivers/md/dm.c	modified	+2	−2	View file
drivers/md/md.c	modified	+14	−17	View file
drivers/mfd/ucb1x00-assabet.c	modified	+9	−8	View file
drivers/mfd/ucb1x00-core.c	modified	+7	−7	View file
drivers/mfd/ucb1x00.h	modified	+2	−2	View file
drivers/misc/ibmasm/command.c	modified	+3	−9	View file
drivers/misc/ibmasm/ibmasm.h	modified	+6	−4	View file
drivers/misc/tifm_7xx1.c	modified	+2	−2	View file
drivers/misc/tifm_core.c	modified	+12	−12	View file
drivers/mtd/mtdchar.c	modified	+5	−7	View file
drivers/net/ibmveth.c	modified	+7	−5	View file
drivers/net/iseries_veth.c	modified	+6	−13	View file
drivers/net/wan/cosa.c	modified	+2	−3	View file
drivers/parisc/pdc_stable.c	modified	+96	−98	View file
drivers/pci/hotplug/acpiphp_ibm.c	modified	+2	−2	View file
drivers/pci/hotplug/pci_hotplug_core.c	modified	+21	−18	View file
drivers/pci/hotplug/rpadlpar_sysfs.c	modified	+43	−70	View file
drivers/pci/pci-driver.c	modified	+12	−47	View file
drivers/pci/probe.c	modified	+7	−4	View file
drivers/pcmcia/ds.c	modified	+1	−2	View file
drivers/power/apm_power.c	modified	+68	−48	View file
drivers/power/power_supply_core.c	modified	+39	−35	View file
drivers/rtc/interface.c	modified	+12	−10	View file
drivers/s390/net/netiucv.c	modified	+6	−10	View file
drivers/s390/scsi/zfcp_ccw.c	modified	+4	−10	View file
drivers/s390/scsi/zfcp_ext.h	modified	+1	−2	View file
drivers/s390/scsi/zfcp_sysfs_driver.c	modified	+4	−23	View file
drivers/scsi/hosts.c	modified	+13	−11	View file
drivers/scsi/libsas/sas_scsi_host.c	modified	+1	−1	View file
drivers/serial/icom.c	modified	+10	−14	View file
drivers/serial/icom.h	modified	+1	−1	View file
drivers/spi/spi.c	modified	+15	−11	View file
drivers/uio/uio.c	modified	+50	−45	View file
drivers/usb/core/driver.c	modified	+4	−4	View file
fs/block_dev.c	modified	+4	−4	View file
fs/char_dev.c	modified	+2	−4	View file
fs/coda/psdev.c	modified	+4	−4	View file
fs/configfs/mount.c	modified	+6	−7	View file
fs/debugfs/inode.c	modified	+6	−7	View file
fs/dlm/lockspace.c	modified	+14	−36	View file
fs/ecryptfs/main.c	modified	+19	−110	View file
fs/fuse/inode.c	modified	+14	−12	View file
fs/gfs2/locking/dlm/sysfs.c	modified	+13	−25	View file
fs/gfs2/sys.c	modified	+12	−17	View file
fs/namespace.c	modified	+5	−6	View file
fs/ocfs2/cluster/masklog.c	modified	+2	−2	View file
fs/ocfs2/cluster/sys.c	modified	+21	−62	View file
fs/partitions/check.c	modified	+111	−216	View file
fs/sysfs/dir.c	modified	+1	−1	View file
fs/sysfs/file.c	modified	+11	−56	View file
fs/sysfs/symlink.c	modified	+42	−46	View file
include/acpi/acpi_bus.h	modified	+1	−1	View file
include/linux/device.h	modified	+189	−171	View file
include/linux/dmaengine.h	modified	+2	−1	View file
include/linux/fs.h	modified	+1	−1	View file
include/linux/genhd.h	modified	+23	−14	View file
include/linux/kobject.h	modified	+75	−109	View file
include/linux/kref.h	modified	+1	−0	View file
include/linux/module.h	modified	+3	−16	View file
include/linux/pci_hotplug.h	modified	+1	−1	View file
include/linux/pktcdvd.h	modified	+1	−1	View file
include/linux/platform_device.h	modified	+1	−1	View file
include/linux/sched.h	modified	+2	−7	View file
include/linux/sysdev.h	modified	+1	−0	View file
include/linux/tifm.h	modified	+1	−1	View file
include/linux/uio_driver.h	modified	+4	−2	View file
include/rdma/ib_verbs.h	modified	+1	−1	View file
init/Kconfig	modified	+1	−0	View file
init/do_mounts.c	modified	+8	−100	View file
kernel/ksysfs.c	modified	+52	−30	View file
kernel/module.c	modified	+18	−110	View file
kernel/params.c	modified	+11	−33	View file
kernel/power/disk.c	modified	+13	−7	View file
kernel/power/main.c	modified	+13	−10	View file
kernel/power/power.h	modified	+1	−3	View file
kernel/rtmutex-tester.c	modified	+1	−1	View file
kernel/time/clocksource.c	modified	+1	−1	View file
kernel/time/timekeeping.c	modified	+1	−1	View file
kernel/user.c	modified	+52	−55	View file
lib/kobject.c	modified	+455	−279	View file
lib/kobject_uevent.c	modified	+28	−10	View file
lib/kref.c	modified	+13	−2	View file
mm/slub.c	modified	+11	−12	View file
net/bridge/br_if.c	modified	+4	−8	View file
net/bridge/br_private.h	modified	+1	−1	View file
net/bridge/br_sysfs_br.c	modified	+4	−10	View file
net/bridge/br_sysfs_if.c	modified	+1	−1	View file
samples/Kconfig	modified	+10	−0	View file
samples/Makefile	modified	+1	−1	View file
samples/kobject/Makefile	added	+1	−0	View file
samples/kobject/kobject-example.c	added	+137	−0	View file
samples/kobject/kset-example.c	added	+278	−0	View file
security/inode.c	modified	+5	−6	View file

Only the first 600 diff lines are shown. Download the complete patch.

Documentation/kobject.txt

View file

diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt
index ca86a88..bf3256e 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.txt
@@ -1,289 +1,386 @@
-The kobject Infrastructure
+Everything you never wanted to know about kobjects, ksets, and ktypes
 
-Patrick Mochel <[email protected]>
+Greg Kroah-Hartman <[email protected]>
 
-Updated: 3 June 2003
+Based on an original article by Jon Corbet for lwn.net written October 1,
+2003 and located at http://lwn.net/Articles/51437/
 
+Last updated December 19, 2007
 
-Copyright (c)  2003 Patrick Mochel
-Copyright (c)  2003 Open Source Development Labs
 
+Part of the difficulty in understanding the driver model - and the kobject
+abstraction upon which it is built - is that there is no obvious starting
+place. Dealing with kobjects requires understanding a few different types,
+all of which make reference to each other. In an attempt to make things
+easier, we'll take a multi-pass approach, starting with vague terms and
+adding detail as we go. To that end, here are some quick definitions of
+some terms we will be working with.
 
-0. Introduction
+ - A kobject is an object of type struct kobject.  Kobjects have a name
+   and a reference count.  A kobject also has a parent pointer (allowing
+   objects to be arranged into hierarchies), a specific type, and,
+   usually, a representation in the sysfs virtual filesystem.
 
-The kobject infrastructure performs basic object management that larger
-data structures and subsystems can leverage, rather than reimplement
-similar functionality. This functionality primarily concerns:
+   Kobjects are generally not interesting on their own; instead, they are
+   usually embedded within some other structure which contains the stuff
+   the code is really interested in.
 
-- Object reference counting.
-- Maintaining lists (sets) of objects.
-- Object set locking.
-- Userspace representation. 
+   No structure should EVER have more than one kobject embedded within it.
+   If it does, the reference counting for the object is sure to be messed
+   up and incorrect, and your code will be buggy.  So do not do this.
 
-The infrastructure consists of a number of object types to support
-this functionality. Their programming interfaces are described below
-in detail, and briefly here:
+ - A ktype is the type of object that embeds a kobject.  Every structure
+   that embeds a kobject needs a corresponding ktype.  The ktype controls
+   what happens to the kobject when it is created and destroyed.
 
-- kobjects	a simple object.
-- kset		a set of objects of a certain type.
-- ktype		a set of helpers for objects of a common type. 
+ - A kset is a group of kobjects.  These kobjects can be of the same ktype
+   or belong to different ktypes.  The kset is the basic container type for
+   collections of kobjects. Ksets contain their own kobjects, but you can
+   safely ignore that implementation detail as the kset core code handles
+   this kobject automatically.
 
+   When you see a sysfs directory full of other directories, generally each
+   of those directories corresponds to a kobject in the same kset.
 
-The kobject infrastructure maintains a close relationship with the
-sysfs filesystem. Each kobject that is registered with the kobject
-core receives a directory in sysfs. Attributes about the kobject can
-then be exported. Please see Documentation/filesystems/sysfs.txt for
-more information. 
+We'll look at how to create and manipulate all of these types. A bottom-up
+approach will be taken, so we'll go back to kobjects.
 
-The kobject infrastructure provides a flexible programming interface,
-and allows kobjects and ksets to be used without being registered
-(i.e. with no sysfs representation). This is also described later. 
 
+Embedding kobjects
 
-1. kobjects
+It is rare for kernel code to create a standalone kobject, with one major
+exception explained below.  Instead, kobjects are used to control access to
+a larger, domain-specific object.  To this end, kobjects will be found
+embedded in other structures.  If you are used to thinking of things in
+object-oriented terms, kobjects can be seen as a top-level, abstract class
+from which other classes are derived.  A kobject implements a set of
+capabilities which are not particularly useful by themselves, but which are
+nice to have in other objects.  The C language does not allow for the
+direct expression of inheritance, so other techniques - such as structure
+embedding - must be used.
 
-1.1 Description
+So, for example, the UIO code has a structure that defines the memory
+region associated with a uio device:
 
+struct uio_mem {
+	struct kobject kobj;
+	unsigned long addr;
+	unsigned long size;
+	int memtype;
+	void __iomem *internal_addr;
+};
 
-struct kobject is a simple data type that provides a foundation for
-more complex object types. It provides a set of basic fields that
-almost all complex data types share. kobjects are intended to be
-embedded in larger data structures and replace fields they duplicate. 
+If you have a struct uio_mem structure, finding its embedded kobject is
+just a matter of using the kobj member.  Code that works with kobjects will
+often have the opposite problem, however: given a struct kobject pointer,
+what is the pointer to the containing structure?  You must avoid tricks
+(such as assuming that the kobject is at the beginning of the structure)
+and, instead, use the container_of() macro, found in <linux/kernel.h>:
 
-1.2 Definition
+	container_of(pointer, type, member)
 
-struct kobject {
-	const char		* k_name;
-	struct kref		kref;
-	struct list_head	entry;
-	struct kobject		* parent;
-	struct kset		* kset;
-	struct kobj_type	* ktype;
-	struct sysfs_dirent	* sd;
-	wait_queue_head_t	poll;
-};
+where pointer is the pointer to the embedded kobject, type is the type of
+the containing structure, and member is the name of the structure field to
+which pointer points.  The return value from container_of() is a pointer to
+the given type. So, for example, a pointer "kp" to a struct kobject
+embedded within a struct uio_mem could be converted to a pointer to the
+containing uio_mem structure with:
 
-void kobject_init(struct kobject *);
-int kobject_add(struct kobject *);
-int kobject_register(struct kobject *);
+    struct uio_mem *u_mem = container_of(kp, struct uio_mem, kobj);
 
-void kobject_del(struct kobject *);
-void kobject_unregister(struct kobject *);
+Programmers often define a simple macro for "back-casting" kobject pointers
+to the containing type.
 
-struct kobject * kobject_get(struct kobject *);
-void kobject_put(struct kobject *);
 
+Initialization of kobjects
 
-1.3 kobject Programming Interface
+Code which creates a kobject must, of course, initialize that object. Some
+of the internal fields are setup with a (mandatory) call to kobject_init():
 
-kobjects may be dynamically added and removed from the kobject core
-using kobject_register() and kobject_unregister(). Registration
-includes inserting the kobject in the list of its dominant kset and
-creating a directory for it in sysfs.
+    void kobject_init(struct kobject *kobj, struct kobj_type *ktype);
 
-Alternatively, one may use a kobject without adding it to its kset's list
-or exporting it via sysfs, by simply calling kobject_init(). An
-initialized kobject may later be added to the object hierarchy by
-calling kobject_add(). An initialized kobject may be used for
-reference counting.
+The ktype is required for a kobject to be created properly, as every kobject
+must have an associated kobj_type.  After calling kobject_init(), to
+register the kobject with sysfs, the function kobject_add() must be called:
 
-Note: calling kobject_init() then kobject_add() is functionally
-equivalent to calling kobject_register().
+    int kobject_add(struct kobject *kobj, struct kobject *parent, const char *fmt, ...);
 
-When a kobject is unregistered, it is removed from its kset's list,
-removed from the sysfs filesystem, and its reference count is decremented.
-List and sysfs removal happen in kobject_del(), and may be called
-manually. kobject_put() decrements the reference count, and may also
-be called manually. 
+This sets up the parent of the kobject and the name for the kobject
+properly.  If the kobject is to be associated with a specific kset,
+kobj->kset must be assigned before calling kobject_add().  If a kset is
+associated with a kobject, then the parent for the kobject can be set to
+NULL in the call to kobject_add() and then the kobject's parent will be the
+kset itself.
 
-A kobject's reference count may be incremented with kobject_get(),
-which returns a valid reference to a kobject; and decremented with 
-kobject_put(). An object's reference count may only be incremented if
-it is already positive. 
+As the name of the kobject is set when it is added to the kernel, the name
+of the kobject should never be manipulated directly.  If you must change
+the name of the kobject, call kobject_rename():
 
-When a kobject's reference count reaches 0, the method struct
-kobj_type::release() (which the kobject's kset points to) is called.
-This allows any memory allocated for the object to be freed.
+    int kobject_rename(struct kobject *kobj, const char *new_name);
 
+There is a function called kobject_set_name() but that is legacy cruft and
+is being removed.  If your code needs to call this function, it is
+incorrect and needs to be fixed.
 
-NOTE!!! 
+To properly access the name of the kobject, use the function
+kobject_name():
 
-It is _imperative_ that you supply a destructor for dynamically
-allocated kobjects to free them if you are using kobject reference
-counts. The reference count controls the lifetime of the object.
-If it goes to 0, then it is assumed that the object will
-be freed and cannot be used. 
+    const char *kobject_name(const struct kobject * kobj);
 
-More importantly, you must free the object there, and not immediately
-after an unregister call. If someone else is referencing the object
-(e.g. through a sysfs file), they will obtain a reference to the
-object, assume it's valid and operate on it. If the object is
-unregistered and freed in the meantime, the operation will then
-reference freed memory and go boom. 
+There is a helper function to both initialize and add the kobject to the
+kernel at the same time, called supprisingly enough kobject_init_and_add():
 
-This can be prevented, in the simplest case, by defining a release
-method and freeing the object from there only. Note that this will not
-secure reference count/object management models that use a dual
-reference count or do other wacky things with the reference count
-(like the networking layer). 
+    int kobject_init_and_add(struct kobject *kobj, struct kobj_type *ktype,
+                             struct kobject *parent, const char *fmt, ...);
 
+The arguments are the same as the individual kobject_init() and
+kobject_add() functions described above.
 
-1.4 sysfs
 
-Each kobject receives a directory in sysfs. This directory is created
-under the kobject's parent directory. 
+Uevents
 
-If a kobject does not have a parent when it is registered, its parent
-becomes its dominant kset. 
+After a kobject has been registered with the kobject core, you need to
+announce to the world that it has been created.  This can be done with a
+call to kobject_uevent():
 
-If a kobject does not have a parent nor a dominant kset, its directory
-is created at the top-level of the sysfs partition.
+    int kobject_uevent(struct kobject *kobj, enum kobject_action action);
 
+Use the KOBJ_ADD action for when the kobject is first added to the kernel.
+This should be done only after any attributes or children of the kobject
+have been initialized properly, as userspace will instantly start to look
+for them when this call happens.
 
+When the kobject is removed from the kernel (details on how to do that is
+below), the uevent for KOBJ_REMOVE will be automatically created by the
+kobject core, so the caller does not have to worry about doing that by
+hand.
 
-2. ksets
 
-2.1 Description
+Reference counts
 
-A kset is a set of kobjects that are embedded in the same type. 
+One of the key functions of a kobject is to serve as a reference counter
+for the object in which it is embedded. As long as references to the object
+exist, the object (and the code which supports it) must continue to exist.
+The low-level functions for manipulating a kobject's reference counts are:
 
+    struct kobject *kobject_get(struct kobject *kobj);
+    void kobject_put(struct kobject *kobj);
 
-struct kset {
-	struct kobj_type	* ktype;
-	struct list_head	list;
-	struct kobject		kobj;
-	struct kset_uevent_ops	* uevent_ops;
-};
+A successful call to kobject_get() will increment the kobject's reference
+counter and return the pointer to the kobject.
 
+When a reference is released, the call to kobject_put() will decrement the
+reference count and, possibly, free the object. Note that kobject_init()
+sets the reference count to one, so the code which sets up the kobject will
+need to do a kobject_put() eventually to release that reference.
 
-void kset_init(struct kset * k);
-int kset_add(struct kset * k);
-int kset_register(struct kset * k);
-void kset_unregister(struct kset * k);
+Because kobjects are dynamic, they must not be declared statically or on
+the stack, but instead, always allocated dynamically.  Future versions of
+the kernel will contain a run-time check for kobjects that are created
+statically and will warn the developer of this improper usage.
 
-struct kset * kset_get(struct kset * k);
-void kset_put(struct kset * k);
+If all that you want to use a kobject for is to provide a reference counter
+for your structure, please use the struct kref instead; a kobject would be
+overkill.  For more information on how to use struct kref, please see the
+file Documentation/kref.txt in the Linux kernel source tree.
 
-struct kobject * kset_find_obj(struct kset *, char *);
 
+Creating "simple" kobjects
 
-The type that the kobjects are embedded in is described by the ktype
-pointer.
+Sometimes all that a developer wants is a way to create a simple directory
+in the sysfs hierarchy, and not have to mess with the whole complication of
+ksets, show and store functions, and other details.  This is the one
+exception where a single kobject should be created.  To create such an
+entry, use the function:
 
-A kset contains a kobject itself, meaning that it may be registered in
-the kobject hierarchy and exported via sysfs. More importantly, the
-kset may be embedded in a larger data type, and may be part of another
-kset (of that object type). 
+    struct kobject *kobject_create_and_add(char *name, struct kobject *parent);
 
-For example, a block device is an object (struct gendisk) that is
-contained in a set of block devices. It may also contain a set of
-partitions (struct hd_struct) that have been found on the device. The
-following code snippet illustrates how to express this properly.
+This function will create a kobject and place it in sysfs in the location
+underneath the specified parent kobject.  To create simple attributes
+associated with this kobject, use:
 
-	 struct gendisk * disk;
-	 ...
-	 disk->kset.kobj.kset = &block_kset;
-	 disk->kset.ktype = &partition_ktype;
-	 kset_register(&disk->kset);
+    int sysfs_create_file(struct kobject *kobj, struct attribute *attr);
+or
+    int sysfs_create_group(struct kobject *kobj, struct attribute_group *grp);
 
-- The kset that the disk's embedded object belongs to is the
-  block_kset, and is pointed to by disk->kset.kobj.kset. 
+Both types of attributes used here, with a kobject that has been created
+with the kobject_create_and_add(), can be of type kobj_attribute, so no
+special custom attribute is needed to be created.
 
-- The type of objects on the disk's _subordinate_ list are partitions, 
-  and is set in disk->kset.ktype. 
+See the example module, samples/kobject/kobject-example.c for an
+implementation of a simple kobject and attributes.
 
-- The kset is then registered, which handles initializing and adding
-  the embedded kobject to the hierarchy. 
 
 
-2.2 kset Programming Interface 
+ktypes and release methods
 
-All kset functions, except kset_find_obj(), eventually forward the
-calls to their embedded kobjects after performing kset-specific
-operations. ksets offer a similar programming model to kobjects: they
-may be used after they are initialized, without registering them in
-the hierarchy. 
+One important thing still missing from the discussion is what happens to a
+kobject when its reference count reaches zero. The code which created the
+kobject generally does not know when that will happen; if it did, there
+would be little point in using a kobject in the first place. Even
+predictable object lifecycles become more complicated when sysfs is brought
+in as other portions of the kernel can get a reference on any kobject that
+is registered in the system.
 
-kset_find_obj() may be used to locate a kobject with a particular
-name. The kobject, if found, is returned. 
+The end result is that a structure protected by a kobject cannot be freed
+before its reference count goes to zero. The reference count is not under
+the direct control of the code which created the kobject. So that code must
+be notified asynchronously whenever the last reference to one of its
+kobjects goes away.
 
-There are also some helper functions which names point to the formerly
-existing "struct subsystem", whose functions have been taken over by
-ksets.
+Once you registered your kobject via kobject_add(), you must never use
+kfree() to free it directly. The only safe way is to use kobject_put(). It
+is good practice to always use kobject_put() after kobject_init() to avoid
+errors creeping in.
 
+This notification is done through a kobject's release() method. Usually
+such a method has a form like:
 
-decl_subsys(name,type,uevent_ops)
+    void my_object_release(struct kobject *kobj)
+    {
+    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);
 
-Declares a kset named '<name>_subsys' of type <type> with
-uevent_ops <uevent_ops>. For example,
+	    /* Perform any additional cleanup on this object, then... */
+	    kfree(mine);
+    }
 
-decl_subsys(devices, &ktype_device, &device_uevent_ops);
+One important point cannot be overstated: every kobject must have a
+release() method, and the kobject must persist (in a consistent state)
+until that method is called. If these constraints are not met, the code is
+flawed.  Note that the kernel will warn you if you forget to provide a
+release() method.  Do not try to get rid of this warning by providing an
+"empty" release function; you will be mocked mercilessly by the kobject
+maintainer if you attempt this.
 
-is equivalent to doing:
+Note, the name of the kobject is available in the release function, but it
+must NOT be changed within this callback.  Otherwise there will be a memory
+leak in the kobject core, which makes people unhappy.
 
-struct kset devices_subsys = {
-     .ktype = &ktype_devices,
-     .uevent_ops = &device_uevent_ops,
-};
-kobject_set_name(&devices_subsys, name);
+Interestingly, the release() method is not stored in the kobject itself;
+instead, it is associated with the ktype. So let us introduce struct
+kobj_type:
+
+    struct kobj_type {
+	    void (*release)(struct kobject *);
+	    struct sysfs_ops	*sysfs_ops;
+	    struct attribute	**default_attrs;
+    };
 
-The objects that are registered with a subsystem that use the
-subsystem's default list must have their kset ptr set properly. These
-objects may have embedded kobjects or ksets. The
-following helper makes setting the kset easier:
+This structure is used to describe a particular type of kobject (or, more
+correctly, of containing object). Every kobject needs to have an associated
+kobj_type structure; a pointer to that structure must be specified when you
+call kobject_init() or kobject_init_and_add().
 
+The release field in struct kobj_type is, of course, a pointer to the
+release() method for this type of kobject. The other two fields (sysfs_ops
+and default_attrs) control how objects of this type are represented in
+sysfs; they are beyond the scope of this document.
 
-kobj_set_kset_s(obj,subsys)
+The default_attrs pointer is a list of default attributes that will be
+automatically created for any kobject that is registered with this ktype.
 
-- Assumes that obj->kobj exists, and is a struct kobject.
-- Sets the kset of that kobject to the kset <subsys>.
 
-int subsystem_register(struct kset *s);
-void subsystem_unregister(struct kset *s);
+ksets
 
-These are just wrappers around the respective kset_* functions.
+A kset is merely a collection of kobjects that want to be associated with
+each other.  There is no restriction that they be of the same ktype, but be
+very careful if they are not.
 
-2.3 sysfs
+A kset serves these functions:
 
-ksets are represented in sysfs when their embedded kobjects are
-registered. They follow the same rules of parenting, with one
-exception. If a kset does not have a parent, nor is its embedded
-kobject part of another kset, the kset's parent becomes its dominant
-subsystem. 
+ - It serves as a bag containing a group of objects. A kset can be used by
+   the kernel to track "all block devices" or "all PCI device drivers."
 
-If the kset does not have a parent, its directory is created at the
-sysfs root. This should only happen when the kset registered is
-embedded in a subsystem itself. 
+ - A kset is also a subdirectory in sysfs, where the associated kobjects
+   with the kset can show up.  Every kset contains a kobject which can be
+   set up to be the parent of other kobjects; the top-level directories of
+   the sysfs hierarchy are constructed in this way.
 
+ - Ksets can support the "hotplugging" of kobjects and influence how
+   uevent events are reported to user space.
 
-3. struct ktype
+In object-oriented terms, "kset" is the top-level container class; ksets
+contain their own kobject, but that kobject is managed by the kset code and
+should not be manipulated by any other user.
 
-3.1. Description
+A kset keeps its children in a standard kernel linked list.  Kobjects point
+back to their containing kset via their kset field. In almost all cases,
+the kobjects belonging to a ket have that kset (or, strictly, its embedded
+kobject) in their parent.
 
-struct kobj_type {
-	void (*release)(struct kobject *);
-	struct sysfs_ops	* sysfs_ops;
-	struct attribute	** default_attrs;
+As a kset contains a kobject within it, it should always be dynamically
+created and never declared statically or on the stack.  To create a new
+kset use:
+  struct kset *kset_create_and_add(const char *name,
+				   struct kset_uevent_ops *u,
+				   struct kobject *parent);
+
+When you are finished with the kset, call:
+  void kset_unregister(struct kset *kset);
+to destroy it.
+
+An example of using a kset can be seen in the
+samples/kobject/kset-example.c file in the kernel tree.
+
+If a kset wishes to control the uevent operations of the kobjects
+associated with it, it can use the struct kset_uevent_ops to handle it:
+
+struct kset_uevent_ops {
+        int (*filter)(struct kset *kset, struct kobject *kobj);
+        const char *(*name)(struct kset *kset, struct kobject *kobj);
+        int (*uevent)(struct kset *kset, struct kobject *kobj,
+                      struct kobj_uevent_env *env);
 };
 
 
-Object types require specific functions for converting between the
-generic object and the more complex type. struct kobj_type provides
-the object-specific fields, which include:
+The filter function allows a kset to prevent a uevent from being emitted to
+userspace for a specific kobject.  If the function returns 0, the uevent
+will not be emitted.
+
+The name function will be called to override the default name of the kset
+that the uevent sends to userspace.  By default, the name will be the same
+as the kset itself, but this function, if present, can override that name.
+
+The uevent function will be called when the uevent is about to be sent to
+userspace to allow more environment variables to be added to the uevent.
+
+One might ask how, exactly, a kobject is added to a kset, given that no
+functions which perform that function have been presented.  The answer is
+that this task is handled by kobject_add().  When a kobject is passed to
+kobject_add(), its kset member should point to the kset to which the
+kobject will belong.  kobject_add() will handle the rest.
+
+If the kobject belonging to a kset has no parent kobject set, it will be
+added to the kset's directory.  Not all members of a kset do necessarily
+live in the kset directory.  If an explicit parent kobject is assigned
+before the kobject is added, the kobject is registered with the kset, but
+added below the parent kobject.
+
+
+Kobject removal
 
-- release: Called when the kobject's reference count reaches 0. This
-  should convert the object to the more complex type and free it. 
+After a kobject has been registered with the kobject core successfully, it
+must be cleaned up when the code is finished with it.  To do that, call
+kobject_put().  By doing this, the kobject core will automatically clean up
+all of the memory allocated by this kobject.  If a KOBJ_ADD uevent has been
+sent for the object, a corresponding KOBJ_REMOVE uevent will be sent, and
+any other sysfs housekeeping will be handled for the caller properly.
 
-- sysfs_ops: Provides conversion functions for sysfs access. Please
-  see the sysfs documentation for more information. 
+If you need to do a two-stage delete of the kobject (say you are not
+allowed to sleep when you need to destroy the object), then call
+kobject_del() which will unregister the kobject from sysfs.  This makes the
+kobject "invisible", but it is not cleaned up, and the reference count of
+the object is still the same.  At a later time call kobject_put() to finish
+the cleanup of the memory associated with the kobject.
 
-- default_attrs: Default attributes to be exported via sysfs when the
-  object is registered.Note that the last attribute has to be
-  initialized to NULL ! You can find a complete implementation
-  in block/genhd.c
+kobject_del() can be used to drop the reference to the parent object, if
+circular references are constructed.  It is valid in some cases, that a
+parent objects references a child.  Circular references _must_ be broken
+with an explicit call to kobject_del(), so that a release functions will be
+called, and the objects in the former circle release each other.
 
 
-Instances of struct kobj_type are not registered; only referenced by
-the kset. A kobj_type may be referenced by an arbitrary number of
-ksets, as there may be disparate sets of identical objects. 
+Example code to copy from
 
+For a more complete example of using ksets and kobjects properly, see the
+sample/kobject/kset-example.c code.

Documentation/pnp.txt

View file

diff --git a/Documentation/pnp.txt b/Documentation/pnp.txt
index 481faf5..a327db6 100644
--- a/Documentation/pnp.txt
+++ b/Documentation/pnp.txt
@@ -17,9 +17,9 @@ The User Interface
 ------------------
 	The Linux Plug and Play user interface provides a means to activate PnP devices
 for legacy and user level drivers that do not support Linux Plug and Play.  The 
-user interface is integrated into driverfs.
+user interface is integrated into sysfs.
 
-In addition to the standard driverfs file the following are created in each 
+In addition to the standard sysfs file the following are created in each

This diff is incomplete. Download the complete patch.