From 80e5302e4bc85a6b685b7668c36c6487b5f90e9a Mon Sep 17 00:00:00 2001 From: "Naveen N. Rao" Date: Thu, 27 Jun 2019 00:08:01 +0530 Subject: recordmcount: Fix spurious mcount entries on powerpc An impending change to enable HAVE_C_RECORDMCOUNT on powerpc leads to warnings such as the following: # modprobe kprobe_example ftrace-powerpc: Not expected bl: opcode is 3c4c0001 WARNING: CPU: 0 PID: 227 at kernel/trace/ftrace.c:2001 ftrace_bug+0x90/0x318 Modules linked in: CPU: 0 PID: 227 Comm: modprobe Not tainted 5.2.0-rc6-00678-g1c329100b942 #2 NIP: c000000000264318 LR: c00000000025d694 CTR: c000000000f5cd30 REGS: c000000001f2b7b0 TRAP: 0700 Not tainted (5.2.0-rc6-00678-g1c329100b942) MSR: 900000010282b033 CR: 28228222 XER: 00000000 CFAR: c0000000002642fc IRQMASK: 0 NIP [c000000000264318] ftrace_bug+0x90/0x318 LR [c00000000025d694] ftrace_process_locs+0x4f4/0x5e0 Call Trace: [c000000001f2ba40] [0000000000000004] 0x4 (unreliable) [c000000001f2bad0] [c00000000025d694] ftrace_process_locs+0x4f4/0x5e0 [c000000001f2bb90] [c00000000020ff10] load_module+0x25b0/0x30c0 [c000000001f2bd00] [c000000000210cb0] sys_finit_module+0xc0/0x130 [c000000001f2be20] [c00000000000bda4] system_call+0x5c/0x70 Instruction dump: 419e0018 2f83ffff 419e00bc 2f83ffea 409e00cc 4800001c 0fe00000 3c62ff96 39000001 39400000 386386d0 480000c4 <0fe00000> 3ce20003 39000001 3c62ff96 ---[ end trace 4c438d5cebf78381 ]--- ftrace failed to modify [] 0xc0080000012a0008 actual: 01:00:4c:3c Initializing ftrace call sites ftrace record flags: 2000000 (0) expected tramp: c00000000006af4c Looking at the relocation records in __mcount_loc shows a few spurious entries: RELOCATION RECORDS FOR [__mcount_loc]: OFFSET TYPE VALUE 0000000000000000 R_PPC64_ADDR64 .text.unlikely+0x0000000000000008 0000000000000008 R_PPC64_ADDR64 .text.unlikely+0x0000000000000014 0000000000000010 R_PPC64_ADDR64 .text.unlikely+0x0000000000000060 0000000000000018 R_PPC64_ADDR64 .text.unlikely+0x00000000000000b4 0000000000000020 R_PPC64_ADDR64 .init.text+0x0000000000000008 0000000000000028 R_PPC64_ADDR64 .init.text+0x0000000000000014 The first entry in each section is incorrect. Looking at the relocation records, the spurious entries correspond to the R_PPC64_ENTRY records: RELOCATION RECORDS FOR [.text.unlikely]: OFFSET TYPE VALUE 0000000000000000 R_PPC64_REL64 .TOC.-0x0000000000000008 0000000000000008 R_PPC64_ENTRY *ABS* 0000000000000014 R_PPC64_REL24 _mcount The problem is that we are not validating the return value from get_mcountsym() in sift_rel_mcount(). With this entry, mcountsym is 0, but Elf_r_sym(relp) also ends up being 0. Fix this by ensuring mcountsym is valid before processing the entry. Signed-off-by: Naveen N. Rao Acked-by: Steven Rostedt (VMware) Tested-by: Satheesh Rajendran Signed-off-by: Michael Ellerman --- scripts/recordmcount.h | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/recordmcount.h b/scripts/recordmcount.h index 2e7793735e14..ccfbfde61556 100644 --- a/scripts/recordmcount.h +++ b/scripts/recordmcount.h @@ -326,7 +326,8 @@ static uint_t *sift_rel_mcount(uint_t *mlocp, if (!mcountsym) mcountsym = get_mcountsym(sym0, relp, str0); - if (mcountsym == Elf_r_sym(relp) && !is_fake_mcount(relp)) { + if (mcountsym && mcountsym == Elf_r_sym(relp) && + !is_fake_mcount(relp)) { uint_t const addend = _w(_w(relp->r_offset) - recval + mcount_adjust); mrelp->r_offset = _w(offbase -- cgit v1.2.3 From 3975b097e577bac77267ed8df0f525e3ad3499ec Mon Sep 17 00:00:00 2001 From: Kirill Smelkov Date: Wed, 19 Jun 2019 20:26:56 +0300 Subject: *: convert stream-like files -> stream_open, even if they use noop_llseek This patch continues 10dce8af3422 (fs: stream_open - opener for stream-like files so that read and write can run simultaneously without deadlock) and c5bf68fe0c86 (*: convert stream-like files from nonseekable_open -> stream_open) and teaches steam_open.cocci to consider files as being stream-like not only if they have .llseek=no_llseek, but also if they have .llseek=noop_llseek. This is safe to do: the comment about noop_llseek says This is an implementation of ->llseek useable for the rare special case when userspace expects the seek to succeed but the (device) file is actually not able to perform the seek. In this case you use noop_llseek() instead of falling back to the default implementation of ->llseek. and in general noop_llseek was massively added to drivers in 6038f373a3dc (llseek: automatically add .llseek fop) when changing default for NULL .llseek from NOP to no_llseek with the idea to avoid breaking compatibility, if maybe some user-space program was using lseek on a device without caring about the result, but caring if it was an error or not. Amended semantic patch produces two changes when applied tree-wide: drivers/hid/hid-sensor-custom.c:690:8-24: WARNING: hid_sensor_custom_fops: .read() has stream semantic; safe to change nonseekable_open -> stream_open. drivers/input/mousedev.c:564:1-17: ERROR: mousedev_fops: .read() can deadlock .write(); change nonseekable_open -> stream_open to fix. Cc: Julia Lawall Cc: Jan Blunck Cc: Arnd Bergmann Cc: Jiri Kosina Cc: Jonathan Cameron Cc: Srinivas Pandruvada Cc: Benjamin Tissoires Cc: Dmitry Torokhov Signed-off-by: Kirill Smelkov --- drivers/hid/hid-sensor-custom.c | 2 +- drivers/input/mousedev.c | 2 +- scripts/coccinelle/api/stream_open.cocci | 9 ++++++++- 3 files changed, 10 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/drivers/hid/hid-sensor-custom.c b/drivers/hid/hid-sensor-custom.c index c60f82673cf2..fb827c295842 100644 --- a/drivers/hid/hid-sensor-custom.c +++ b/drivers/hid/hid-sensor-custom.c @@ -687,7 +687,7 @@ static int hid_sensor_custom_open(struct inode *inode, struct file *file) if (test_and_set_bit(0, &sensor_inst->misc_opened)) return -EBUSY; - return nonseekable_open(inode, file); + return stream_open(inode, file); } static __poll_t hid_sensor_custom_poll(struct file *file, diff --git a/drivers/input/mousedev.c b/drivers/input/mousedev.c index 3b73e0f17848..505c562a5daa 100644 --- a/drivers/input/mousedev.c +++ b/drivers/input/mousedev.c @@ -558,7 +558,7 @@ static int mousedev_open(struct inode *inode, struct file *file) goto err_free_client; file->private_data = client; - nonseekable_open(inode, file); + stream_open(inode, file); return 0; diff --git a/scripts/coccinelle/api/stream_open.cocci b/scripts/coccinelle/api/stream_open.cocci index 350145da7669..f00c05d207d9 100644 --- a/scripts/coccinelle/api/stream_open.cocci +++ b/scripts/coccinelle/api/stream_open.cocci @@ -134,6 +134,13 @@ identifier fops0.fops; .llseek = no_llseek, }; +@ has_noop_llseek @ +identifier fops0.fops; +@@ + struct file_operations fops = { + .llseek = noop_llseek, + }; + @ has_mmap @ identifier fops0.fops; identifier mmap_f; @@ -180,7 +187,7 @@ identifier splice_write_f; // // XXX for simplicity require no .{read/write}_iter and no .splice_{read/write} for now. // XXX maybe_steam.fops cannot be used in other rules - it gives "bad rule maybe_stream or bad variable fops". -@ maybe_stream depends on (!has_llseek || has_no_llseek) && !has_mmap && !has_copy_file_range && !has_remap_file_range && !has_read_iter && !has_write_iter && !has_splice_read && !has_splice_write @ +@ maybe_stream depends on (!has_llseek || has_no_llseek || has_noop_llseek) && !has_mmap && !has_copy_file_range && !has_remap_file_range && !has_read_iter && !has_write_iter && !has_splice_read && !has_splice_write @ identifier fops0.fops; @@ struct file_operations fops = { -- cgit v1.2.3 From d5ccd65ab6272f21f442695b0022a4f553d818e5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 19 Apr 2019 19:01:18 -0300 Subject: docs: move gcc_plugins.txt to core-api and rename to .rst The gcc_plugins.txt file is already a ReST file. Move it to the core-api book while renaming it. Signed-off-by: Mauro Carvalho Chehab Acked-by: Kees Cook --- Documentation/core-api/gcc-plugins.rst | 93 ++++++++++++++++++++++++++++++++++ Documentation/core-api/index.rst | 1 + Documentation/gcc-plugins.txt | 93 ---------------------------------- MAINTAINERS | 2 +- scripts/gcc-plugins/Kconfig | 2 +- 5 files changed, 96 insertions(+), 95 deletions(-) create mode 100644 Documentation/core-api/gcc-plugins.rst delete mode 100644 Documentation/gcc-plugins.txt (limited to 'scripts') diff --git a/Documentation/core-api/gcc-plugins.rst b/Documentation/core-api/gcc-plugins.rst new file mode 100644 index 000000000000..8502f24396fb --- /dev/null +++ b/Documentation/core-api/gcc-plugins.rst @@ -0,0 +1,93 @@ +========================= +GCC plugin infrastructure +========================= + + +Introduction +============ + +GCC plugins are loadable modules that provide extra features to the +compiler [1]_. They are useful for runtime instrumentation and static analysis. +We can analyse, change and add further code during compilation via +callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. + +The GCC plugin infrastructure of the kernel supports all gcc versions from +4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a +separate directory. +Plugin source files have to be compilable by both a C and a C++ compiler as well +because gcc versions 4.5 and 4.6 are compiled by a C compiler, +gcc-4.7 can be compiled by a C or a C++ compiler, +and versions 4.8+ can only be compiled by a C++ compiler. + +Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and +powerpc architectures. + +This infrastructure was ported from grsecurity [6]_ and PaX [7]_. + +-- + +.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html +.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API +.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html +.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html +.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html +.. [6] https://grsecurity.net/ +.. [7] https://pax.grsecurity.net/ + + +Files +===== + +**$(src)/scripts/gcc-plugins** + + This is the directory of the GCC plugins. + +**$(src)/scripts/gcc-plugins/gcc-common.h** + + This is a compatibility header for GCC plugins. + It should be always included instead of individual gcc headers. + +**$(src)/scripts/gcc-plugin.sh** + + This script checks the availability of the included headers in + gcc-common.h and chooses the proper host compiler to build the plugins + (gcc-4.7 can be built by either gcc or g++). + +**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, +$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** + + These headers automatically generate the registration structures for + GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions + from 4.5 to 6.0. + They should be preferred to creating the structures by hand. + + +Usage +===== + +You must install the gcc plugin headers for your gcc version, +e.g., on Ubuntu for gcc-4.9:: + + apt-get install gcc-4.9-plugin-dev + +Enable a GCC plugin based feature in the kernel config:: + + CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y + +To compile only the plugin(s):: + + make gcc-plugins + +or just run the kernel make and compile the whole kernel with +the cyclomatic complexity GCC plugin. + + +4. How to add a new GCC plugin +============================== + +The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory +here. It must be added to $(src)/scripts/gcc-plugins/Makefile, +$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. +See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 322ac954b390..da0ed972d224 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -36,6 +36,7 @@ Core utilities memory-hotplug protection-keys ../RCU/index + gcc-plugins Interfaces for kernel debugging diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.txt deleted file mode 100644 index 8502f24396fb..000000000000 --- a/Documentation/gcc-plugins.txt +++ /dev/null @@ -1,93 +0,0 @@ -========================= -GCC plugin infrastructure -========================= - - -Introduction -============ - -GCC plugins are loadable modules that provide extra features to the -compiler [1]_. They are useful for runtime instrumentation and static analysis. -We can analyse, change and add further code during compilation via -callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_. - -The GCC plugin infrastructure of the kernel supports all gcc versions from -4.5 to 6.0, building out-of-tree modules, cross-compilation and building in a -separate directory. -Plugin source files have to be compilable by both a C and a C++ compiler as well -because gcc versions 4.5 and 4.6 are compiled by a C compiler, -gcc-4.7 can be compiled by a C or a C++ compiler, -and versions 4.8+ can only be compiled by a C++ compiler. - -Currently the GCC plugin infrastructure supports only the x86, arm, arm64 and -powerpc architectures. - -This infrastructure was ported from grsecurity [6]_ and PaX [7]_. - --- - -.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html -.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API -.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html -.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html -.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html -.. [6] https://grsecurity.net/ -.. [7] https://pax.grsecurity.net/ - - -Files -===== - -**$(src)/scripts/gcc-plugins** - - This is the directory of the GCC plugins. - -**$(src)/scripts/gcc-plugins/gcc-common.h** - - This is a compatibility header for GCC plugins. - It should be always included instead of individual gcc headers. - -**$(src)/scripts/gcc-plugin.sh** - - This script checks the availability of the included headers in - gcc-common.h and chooses the proper host compiler to build the plugins - (gcc-4.7 can be built by either gcc or g++). - -**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h, -$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h** - - These headers automatically generate the registration structures for - GIMPLE, SIMPLE_IPA, IPA and RTL passes. They support all gcc versions - from 4.5 to 6.0. - They should be preferred to creating the structures by hand. - - -Usage -===== - -You must install the gcc plugin headers for your gcc version, -e.g., on Ubuntu for gcc-4.9:: - - apt-get install gcc-4.9-plugin-dev - -Enable a GCC plugin based feature in the kernel config:: - - CONFIG_GCC_PLUGIN_CYC_COMPLEXITY = y - -To compile only the plugin(s):: - - make gcc-plugins - -or just run the kernel make and compile the whole kernel with -the cyclomatic complexity GCC plugin. - - -4. How to add a new GCC plugin -============================== - -The GCC plugins are in $(src)/scripts/gcc-plugins/. You can use a file or a directory -here. It must be added to $(src)/scripts/gcc-plugins/Makefile, -$(src)/scripts/Makefile.gcc-plugins and $(src)/arch/Kconfig. -See the cyc_complexity_plugin.c (CONFIG_GCC_PLUGIN_CYC_COMPLEXITY) GCC plugin. diff --git a/MAINTAINERS b/MAINTAINERS index 4b9fd11466a2..db96cd4a229b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6655,7 +6655,7 @@ S: Maintained F: scripts/gcc-plugins/ F: scripts/gcc-plugin.sh F: scripts/Makefile.gcc-plugins -F: Documentation/gcc-plugins.txt +F: Documentation/core-api/gcc-plugins.rst GASKET DRIVER FRAMEWORK M: Rob Springer diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig index e9c677a53c74..d33de0b9f4f5 100644 --- a/scripts/gcc-plugins/Kconfig +++ b/scripts/gcc-plugins/Kconfig @@ -23,7 +23,7 @@ config GCC_PLUGINS GCC plugins are loadable modules that provide extra features to the compiler. They are useful for runtime instrumentation and static analysis. - See Documentation/gcc-plugins.txt for details. + See Documentation/core-api/gcc-plugins.rst for details. menu "GCC plugins" depends on GCC_PLUGINS -- cgit v1.2.3 From fe34c89d25429e079ba67416529514120dd715f8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 12:34:59 -0300 Subject: docs: driver-model: move it to the driver-api book The audience for the Kernel driver-model is clearly Kernel hackers. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jeff Kirsher # ice driver changes --- Documentation/driver-api/driver-model/binding.rst | 98 +++++ Documentation/driver-api/driver-model/bus.rst | 146 +++++++ Documentation/driver-api/driver-model/class.rst | 149 +++++++ .../driver-api/driver-model/design-patterns.rst | 116 ++++++ Documentation/driver-api/driver-model/device.rst | 109 +++++ Documentation/driver-api/driver-model/devres.rst | 414 +++++++++++++++++++ Documentation/driver-api/driver-model/driver.rst | 223 ++++++++++ Documentation/driver-api/driver-model/index.rst | 24 ++ Documentation/driver-api/driver-model/overview.rst | 124 ++++++ Documentation/driver-api/driver-model/platform.rst | 246 +++++++++++ Documentation/driver-api/driver-model/porting.rst | 448 +++++++++++++++++++++ Documentation/driver-api/gpio/driver.rst | 2 +- Documentation/driver-api/index.rst | 1 + Documentation/driver-model/binding.rst | 98 ----- Documentation/driver-model/bus.rst | 146 ------- Documentation/driver-model/class.rst | 149 ------- Documentation/driver-model/design-patterns.rst | 116 ------ Documentation/driver-model/device.rst | 109 ----- Documentation/driver-model/devres.rst | 414 ------------------- Documentation/driver-model/driver.rst | 223 ---------- Documentation/driver-model/index.rst | 26 -- Documentation/driver-model/overview.rst | 124 ------ Documentation/driver-model/platform.rst | 246 ----------- Documentation/driver-model/porting.rst | 448 --------------------- Documentation/eisa.txt | 4 +- Documentation/filesystems/sysfs.txt | 2 +- Documentation/hwmon/submitting-patches.rst | 2 +- .../translations/zh_CN/filesystems/sysfs.txt | 2 +- drivers/base/platform.c | 2 +- drivers/gpio/gpio-cs5535.c | 2 +- drivers/net/ethernet/intel/ice/ice_main.c | 2 +- drivers/staging/unisys/Documentation/overview.txt | 4 +- include/linux/device.h | 2 +- include/linux/platform_device.h | 2 +- scripts/coccinelle/free/devm_free.cocci | 2 +- 35 files changed, 2112 insertions(+), 2113 deletions(-) create mode 100644 Documentation/driver-api/driver-model/binding.rst create mode 100644 Documentation/driver-api/driver-model/bus.rst create mode 100644 Documentation/driver-api/driver-model/class.rst create mode 100644 Documentation/driver-api/driver-model/design-patterns.rst create mode 100644 Documentation/driver-api/driver-model/device.rst create mode 100644 Documentation/driver-api/driver-model/devres.rst create mode 100644 Documentation/driver-api/driver-model/driver.rst create mode 100644 Documentation/driver-api/driver-model/index.rst create mode 100644 Documentation/driver-api/driver-model/overview.rst create mode 100644 Documentation/driver-api/driver-model/platform.rst create mode 100644 Documentation/driver-api/driver-model/porting.rst delete mode 100644 Documentation/driver-model/binding.rst delete mode 100644 Documentation/driver-model/bus.rst delete mode 100644 Documentation/driver-model/class.rst delete mode 100644 Documentation/driver-model/design-patterns.rst delete mode 100644 Documentation/driver-model/device.rst delete mode 100644 Documentation/driver-model/devres.rst delete mode 100644 Documentation/driver-model/driver.rst delete mode 100644 Documentation/driver-model/index.rst delete mode 100644 Documentation/driver-model/overview.rst delete mode 100644 Documentation/driver-model/platform.rst delete mode 100644 Documentation/driver-model/porting.rst (limited to 'scripts') diff --git a/Documentation/driver-api/driver-model/binding.rst b/Documentation/driver-api/driver-model/binding.rst new file mode 100644 index 000000000000..7ea1d7a41e1d --- /dev/null +++ b/Documentation/driver-api/driver-model/binding.rst @@ -0,0 +1,98 @@ +============== +Driver Binding +============== + +Driver binding is the process of associating a device with a device +driver that can control it. Bus drivers have typically handled this +because there have been bus-specific structures to represent the +devices and the drivers. With generic device and device driver +structures, most of the binding can take place using common code. + + +Bus +~~~ + +The bus type structure contains a list of all devices that are on that bus +type in the system. When device_register is called for a device, it is +inserted into the end of this list. The bus object also contains a +list of all drivers of that bus type. When driver_register is called +for a driver, it is inserted at the end of this list. These are the +two events which trigger driver binding. + + +device_register +~~~~~~~~~~~~~~~ + +When a new device is added, the bus's list of drivers is iterated over +to find one that supports it. In order to determine that, the device +ID of the device must match one of the device IDs that the driver +supports. The format and semantics for comparing IDs is bus-specific. +Instead of trying to derive a complex state machine and matching +algorithm, it is up to the bus driver to provide a callback to compare +a device against the IDs of a driver. The bus returns 1 if a match was +found; 0 otherwise. + +int match(struct device * dev, struct device_driver * drv); + +If a match is found, the device's driver field is set to the driver +and the driver's probe callback is called. This gives the driver a +chance to verify that it really does support the hardware, and that +it's in a working state. + +Device Class +~~~~~~~~~~~~ + +Upon the successful completion of probe, the device is registered with +the class to which it belongs. Device drivers belong to one and only one +class, and that is set in the driver's devclass field. +devclass_add_device is called to enumerate the device within the class +and actually register it with the class, which happens with the +class's register_dev callback. + + +Driver +~~~~~~ + +When a driver is attached to a device, the device is inserted into the +driver's list of devices. + + +sysfs +~~~~~ + +A symlink is created in the bus's 'devices' directory that points to +the device's directory in the physical hierarchy. + +A symlink is created in the driver's 'devices' directory that points +to the device's directory in the physical hierarchy. + +A directory for the device is created in the class's directory. A +symlink is created in that directory that points to the device's +physical location in the sysfs tree. + +A symlink can be created (though this isn't done yet) in the device's +physical directory to either its class directory, or the class's +top-level directory. One can also be created to point to its driver's +directory also. + + +driver_register +~~~~~~~~~~~~~~~ + +The process is almost identical for when a new driver is added. +The bus's list of devices is iterated over to find a match. Devices +that already have a driver are skipped. All the devices are iterated +over, to bind as many devices as possible to the driver. + + +Removal +~~~~~~~ + +When a device is removed, the reference count for it will eventually +go to 0. When it does, the remove callback of the driver is called. It +is removed from the driver's list of devices and the reference count +of the driver is decremented. All symlinks between the two are removed. + +When a driver is removed, the list of devices that it supports is +iterated over, and the driver's remove callback is called for each +one. The device is removed from that list and the symlinks removed. diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst new file mode 100644 index 000000000000..016b15a6e8ea --- /dev/null +++ b/Documentation/driver-api/driver-model/bus.rst @@ -0,0 +1,146 @@ +========= +Bus Types +========= + +Definition +~~~~~~~~~~ +See the kerneldoc for the struct bus_type. + +int bus_register(struct bus_type * bus); + + +Declaration +~~~~~~~~~~~ + +Each bus type in the kernel (PCI, USB, etc) should declare one static +object of this type. They must initialize the name field, and may +optionally initialize the match callback:: + + struct bus_type pci_bus_type = { + .name = "pci", + .match = pci_bus_match, + }; + +The structure should be exported to drivers in a header file: + +extern struct bus_type pci_bus_type; + + +Registration +~~~~~~~~~~~~ + +When a bus driver is initialized, it calls bus_register. This +initializes the rest of the fields in the bus object and inserts it +into a global list of bus types. Once the bus object is registered, +the fields in it are usable by the bus driver. + + +Callbacks +~~~~~~~~~ + +match(): Attaching Drivers to Devices +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The format of device ID structures and the semantics for comparing +them are inherently bus-specific. Drivers typically declare an array +of device IDs of devices they support that reside in a bus-specific +driver structure. + +The purpose of the match callback is to give the bus an opportunity to +determine if a particular driver supports a particular device by +comparing the device IDs the driver supports with the device ID of a +particular device, without sacrificing bus-specific functionality or +type-safety. + +When a driver is registered with the bus, the bus's list of devices is +iterated over, and the match callback is called for each device that +does not have a driver associated with it. + + + +Device and Driver Lists +~~~~~~~~~~~~~~~~~~~~~~~ + +The lists of devices and drivers are intended to replace the local +lists that many buses keep. They are lists of struct devices and +struct device_drivers, respectively. Bus drivers are free to use the +lists as they please, but conversion to the bus-specific type may be +necessary. + +The LDM core provides helper functions for iterating over each list:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, + int (*fn)(struct device *, void *)); + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + +These helpers iterate over the respective list, and call the callback +for each device or driver in the list. All list accesses are +synchronized by taking the bus's lock (read currently). The reference +count on each object in the list is incremented before the callback is +called; it is decremented after the next object has been obtained. The +lock is not held when calling the callback. + + +sysfs +~~~~~~~~ +There is a top-level directory named 'bus'. + +Each bus gets a directory in the bus directory, along with two default +directories:: + + /sys/bus/pci/ + |-- devices + `-- drivers + +Drivers registered with the bus get a directory in the bus's drivers +directory:: + + /sys/bus/pci/ + |-- devices + `-- drivers + |-- Intel ICH + |-- Intel ICH Joystick + |-- agpgart + `-- e100 + +Each device that is discovered on a bus of that type gets a symlink in +the bus's devices directory to the device's directory in the physical +hierarchy:: + + /sys/bus/pci/ + |-- devices + | |-- 00:00.0 -> ../../../root/pci0/00:00.0 + | |-- 00:01.0 -> ../../../root/pci0/00:01.0 + | `-- 00:02.0 -> ../../../root/pci0/00:02.0 + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); + }; + +Bus drivers can export attributes using the BUS_ATTR_RW macro that works +similarly to the DEVICE_ATTR_RW macro for devices. For example, a +definition like this:: + + static BUS_ATTR_RW(debug); + +is equivalent to declaring:: + + static bus_attribute bus_attr_debug; + +This can then be used to add and remove the attribute from the bus's +sysfs directory using:: + + int bus_create_file(struct bus_type *, struct bus_attribute *); + void bus_remove_file(struct bus_type *, struct bus_attribute *); diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst new file mode 100644 index 000000000000..fff55b80e86a --- /dev/null +++ b/Documentation/driver-api/driver-model/class.rst @@ -0,0 +1,149 @@ +============== +Device Classes +============== + +Introduction +~~~~~~~~~~~~ +A device class describes a type of device, like an audio or network +device. The following device classes have been identified: + + + + +Each device class defines a set of semantics and a programming interface +that devices of that class adhere to. Device drivers are the +implementation of that programming interface for a particular device on +a particular bus. + +Device classes are agnostic with respect to what bus a device resides +on. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The device class structure looks like:: + + + typedef int (*devclass_add)(struct device *); + typedef void (*devclass_remove)(struct device *); + +See the kerneldoc for the struct class. + +A typical device class definition would look like:: + + struct device_class input_devclass = { + .name = "input", + .add_device = input_add_device, + .remove_device = input_remove_device, + }; + +Each device class structure should be exported in a header file so it +can be used by drivers, extensions and interfaces. + +Device classes are registered and unregistered with the core using:: + + int devclass_register(struct device_class * cls); + void devclass_unregister(struct device_class * cls); + + +Devices +~~~~~~~ +As devices are bound to drivers, they are added to the device class +that the driver belongs to. Before the driver model core, this would +typically happen during the driver's probe() callback, once the device +has been initialized. It now happens after the probe() callback +finishes from the core. + +The device is enumerated in the class. Each time a device is added to +the class, the class's devnum field is incremented and assigned to the +device. The field is never decremented, so if the device is removed +from the class and re-added, it will receive a different enumerated +value. + +The class is allowed to create a class-specific structure for the +device and store it in the device's class_data pointer. + +There is no list of devices in the device class. Each driver has a +list of devices that it supports. The device class has a list of +drivers of that particular class. To access all of the devices in the +class, iterate over the device lists of each driver in the class. + + +Device Drivers +~~~~~~~~~~~~~~ +Device drivers are added to device classes when they are registered +with the core. A driver specifies the class it belongs to by setting +the struct device_driver::devclass field. + + +sysfs directory structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There is a top-level sysfs directory named 'class'. + +Each class gets a directory in the class directory, along with two +default subdirectories:: + + class/ + `-- input + |-- devices + `-- drivers + + +Drivers registered with the class get a symlink in the drivers/ directory +that points to the driver's directory (under its bus directory):: + + class/ + `-- input + |-- devices + `-- drivers + `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ + + +Each device gets a symlink in the devices/ directory that points to the +device's directory in the physical hierarchy:: + + class/ + `-- input + |-- devices + | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ + `-- drivers + + +Exporting Attributes +~~~~~~~~~~~~~~~~~~~~ + +:: + + struct devclass_attribute { + struct attribute attr; + ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); + ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); + }; + +Class drivers can export attributes using the DEVCLASS_ATTR macro that works +similarly to the DEVICE_ATTR macro for devices. For example, a definition +like this:: + + static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); + +is equivalent to declaring:: + + static devclass_attribute devclass_attr_debug; + +The bus driver can add and remove the attribute from the class's +sysfs directory using:: + + int devclass_create_file(struct device_class *, struct devclass_attribute *); + void devclass_remove_file(struct device_class *, struct devclass_attribute *); + +In the example above, the file will be named 'debug' in placed in the +class's directory in sysfs. + + +Interfaces +~~~~~~~~~~ +There may exist multiple mechanisms for accessing the same device of a +particular class type. Device interfaces describe these mechanisms. + +When a device is added to a device class, the core attempts to add it +to every interface that is registered with the device class. diff --git a/Documentation/driver-api/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst new file mode 100644 index 000000000000..41eb8f41f7dd --- /dev/null +++ b/Documentation/driver-api/driver-model/design-patterns.rst @@ -0,0 +1,116 @@ +============================= +Device Driver Design Patterns +============================= + +This document describes a few common design patterns found in device drivers. +It is likely that subsystem maintainers will ask driver developers to +conform to these design patterns. + +1. State Container +2. container_of() + + +1. State Container +~~~~~~~~~~~~~~~~~~ + +While the kernel contains a few device drivers that assume that they will +only be probed() once on a certain system (singletons), it is custom to assume +that the device the driver binds to will appear in several instances. This +means that the probe() function and all callbacks need to be reentrant. + +The most common way to achieve this is to use the state container design +pattern. It usually has this form:: + + struct foo { + spinlock_t lock; /* Example member */ + (...) + }; + + static int foo_probe(...) + { + struct foo *foo; + + foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); + if (!foo) + return -ENOMEM; + spin_lock_init(&foo->lock); + (...) + } + +This will create an instance of struct foo in memory every time probe() is +called. This is our state container for this instance of the device driver. +Of course it is then necessary to always pass this instance of the +state around to all functions that need access to the state and its members. + +For example, if the driver is registering an interrupt handler, you would +pass around a pointer to struct foo like this:: + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + (...) + ret = request_irq(irq, foo_handler, 0, "foo", foo); + } + +This way you always get a pointer back to the correct instance of foo in +your interrupt handler. + + +2. container_of() +~~~~~~~~~~~~~~~~~ + +Continuing on the above example we add an offloaded work:: + + struct foo { + spinlock_t lock; + struct workqueue_struct *wq; + struct work_struct offload; + (...) + }; + + static void foo_work(struct work_struct *work) + { + struct foo *foo = container_of(work, struct foo, offload); + + (...) + } + + static irqreturn_t foo_handler(int irq, void *arg) + { + struct foo *foo = arg; + + queue_work(foo->wq, &foo->offload); + (...) + } + + static int foo_probe(...) + { + struct foo *foo; + + foo->wq = create_singlethread_workqueue("foo-wq"); + INIT_WORK(&foo->offload, foo_work); + (...) + } + +The design pattern is the same for an hrtimer or something similar that will +return a single argument which is a pointer to a struct member in the +callback. + +container_of() is a macro defined in + +What container_of() does is to obtain a pointer to the containing struct from +a pointer to a member by a simple subtraction using the offsetof() macro from +standard C, which allows something similar to object oriented behaviours. +Notice that the contained member must not be a pointer, but an actual member +for this to work. + +We can see here that we avoid having global pointers to our struct foo * +instance this way, while still keeping the number of parameters passed to the +work function to a single pointer. diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst new file mode 100644 index 000000000000..2b868d49d349 --- /dev/null +++ b/Documentation/driver-api/driver-model/device.rst @@ -0,0 +1,109 @@ +========================== +The Basic Device Structure +========================== + +See the kerneldoc for the struct device. + + +Programming Interface +~~~~~~~~~~~~~~~~~~~~~ +The bus driver that discovers the device uses this to register the +device with the core:: + + int device_register(struct device * dev); + +The bus should initialize the following fields: + + - parent + - name + - bus_id + - bus + +A device is removed from the core when its reference count goes to +0. The reference count can be adjusted using:: + + struct device * get_device(struct device * dev); + void put_device(struct device * dev); + +get_device() will return a pointer to the struct device passed to it +if the reference is not already 0 (if it's in the process of being +removed already). + +A driver can access the lock in the device structure using:: + + void lock_device(struct device * dev); + void unlock_device(struct device * dev); + + +Attributes +~~~~~~~~~~ + +:: + + struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + }; + +Attributes of devices can be exported by a device driver through sysfs. + +Please see Documentation/filesystems/sysfs.txt for more information +on how sysfs works. + +As explained in Documentation/kobject.txt, device attributes must be +created before the KOBJ_ADD uevent is generated. The only way to realize +that is by defining an attribute group. + +Attributes are declared using a macro called DEVICE_ATTR:: + + #define DEVICE_ATTR(name,mode,show,store) + +Example::: + + static DEVICE_ATTR(type, 0444, show_type, NULL); + static DEVICE_ATTR(power, 0644, show_power, store_power); + +This declares two structures of type struct device_attribute with respective +names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be +organized as follows into a group:: + + static struct attribute *dev_attrs[] = { + &dev_attr_type.attr, + &dev_attr_power.attr, + NULL, + }; + + static struct attribute_group dev_attr_group = { + .attrs = dev_attrs, + }; + + static const struct attribute_group *dev_attr_groups[] = { + &dev_attr_group, + NULL, + }; + +This array of groups can then be associated with a device by setting the +group pointer in struct device before device_register() is invoked:: + + dev->groups = dev_attr_groups; + device_register(dev); + +The device_register() function will use the 'groups' pointer to create the +device attributes and the device_unregister() function will use this pointer +to remove the device attributes. + +Word of warning: While the kernel allows device_create_file() and +device_remove_file() to be called on a device at any time, userspace has +strict expectations on when attributes get created. When a new device is +registered in the kernel, a uevent is generated to notify userspace (like +udev) that a new device is available. If attributes are added after the +device is registered, then userspace won't get notified and userspace will +not know about the new attributes. + +This is important for device driver that need to publish additional +attributes for a device at driver probe time. If the device driver simply +calls device_create_file() on the device structure passed to it, then +userspace will never be notified of the new attributes. diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst new file mode 100644 index 000000000000..4ac99122b5f1 --- /dev/null +++ b/Documentation/driver-api/driver-model/devres.rst @@ -0,0 +1,414 @@ +================================ +Devres - Managed Device Resource +================================ + +Tejun Heo + +First draft 10 January 2007 + +.. contents + + 1. Intro : Huh? Devres? + 2. Devres : Devres in a nutshell + 3. Devres Group : Group devres'es and release them together + 4. Details : Life time rules, calling context, ... + 5. Overhead : How much do we have to pay for this? + 6. List of managed interfaces: Currently implemented managed interfaces + + +1. Intro +-------- + +devres came up while trying to convert libata to use iomap. Each +iomapped address should be kept and unmapped on driver detach. For +example, a plain SFF ATA controller (that is, good old PCI IDE) in +native mode makes use of 5 PCI BARs and all of them should be +maintained. + +As with many other device drivers, libata low level drivers have +sufficient bugs in ->remove and ->probe failure path. Well, yes, +that's probably because libata low level driver developers are lazy +bunch, but aren't all low level driver developers? After spending a +day fiddling with braindamaged hardware with no document or +braindamaged document, if it's finally working, well, it's working. + +For one reason or another, low level drivers don't receive as much +attention or testing as core code, and bugs on driver detach or +initialization failure don't happen often enough to be noticeable. +Init failure path is worse because it's much less travelled while +needs to handle multiple entry points. + +So, many low level drivers end up leaking resources on driver detach +and having half broken failure path implementation in ->probe() which +would leak resources or even cause oops when failure occurs. iomap +adds more to this mix. So do msi and msix. + + +2. Devres +--------- + +devres is basically linked list of arbitrarily sized memory areas +associated with a struct device. Each devres entry is associated with +a release function. A devres can be released in several ways. No +matter what, all devres entries are released on driver detach. On +release, the associated release function is invoked and then the +devres entry is freed. + +Managed interface is created for resources commonly used by device +drivers using devres. For example, coherent DMA memory is acquired +using dma_alloc_coherent(). The managed version is called +dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except +for the DMA memory allocated using it is managed and will be +automatically released on driver detach. Implementation looks like +the following:: + + struct dma_devres { + size_t size; + void *vaddr; + dma_addr_t dma_handle; + }; + + static void dmam_coherent_release(struct device *dev, void *res) + { + struct dma_devres *this = res; + + dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); + } + + dmam_alloc_coherent(dev, size, dma_handle, gfp) + { + struct dma_devres *dr; + void *vaddr; + + dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); + ... + + /* alloc DMA memory as usual */ + vaddr = dma_alloc_coherent(...); + ... + + /* record size, vaddr, dma_handle in dr */ + dr->vaddr = vaddr; + ... + + devres_add(dev, dr); + + return vaddr; + } + +If a driver uses dmam_alloc_coherent(), the area is guaranteed to be +freed whether initialization fails half-way or the device gets +detached. If most resources are acquired using managed interface, a +driver can have much simpler init and exit code. Init path basically +looks like the following:: + + my_init_one() + { + struct mydev *d; + + d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); + if (!d) + return -ENOMEM; + + d->ring = dmam_alloc_coherent(...); + if (!d->ring) + return -ENOMEM; + + if (check something) + return -EINVAL; + ... + + return register_to_upper_layer(d); + } + +And exit path:: + + my_remove_one() + { + unregister_from_upper_layer(d); + shutdown_my_hardware(); + } + +As shown above, low level drivers can be simplified a lot by using +devres. Complexity is shifted from less maintained low level drivers +to better maintained higher layer. Also, as init failure path is +shared with exit path, both can get more testing. + +Note though that when converting current calls or assignments to +managed devm_* versions it is up to you to check if internal operations +like allocating memory, have failed. Managed resources pertains to the +freeing of these resources *only* - all other checks needed are still +on you. In some cases this may mean introducing checks that were not +necessary before moving to the managed devm_* calls. + + +3. Devres group +--------------- + +Devres entries can be grouped using devres group. When a group is +released, all contained normal devres entries and properly nested +groups are released. One usage is to rollback series of acquired +resources on failure. For example:: + + if (!devres_open_group(dev, NULL, GFP_KERNEL)) + return -ENOMEM; + + acquire A; + if (failed) + goto err; + + acquire B; + if (failed) + goto err; + ... + + devres_remove_group(dev, NULL); + return 0; + + err: + devres_release_group(dev, NULL); + return err_code; + +As resource acquisition failure usually means probe failure, constructs +like above are usually useful in midlayer driver (e.g. libata core +layer) where interface function shouldn't have side effect on failure. +For LLDs, just returning error code suffices in most cases. + +Each group is identified by `void *id`. It can either be explicitly +specified by @id argument to devres_open_group() or automatically +created by passing NULL as @id as in the above example. In both +cases, devres_open_group() returns the group's id. The returned id +can be passed to other devres functions to select the target group. +If NULL is given to those functions, the latest open group is +selected. + +For example, you can do something like the following:: + + int my_midlayer_create_something() + { + if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) + return -ENOMEM; + + ... + + devres_close_group(dev, my_midlayer_create_something); + return 0; + } + + void my_midlayer_destroy_something() + { + devres_release_group(dev, my_midlayer_create_something); + } + + +4. Details +---------- + +Lifetime of a devres entry begins on devres allocation and finishes +when it is released or destroyed (removed and freed) - no reference +counting. + +devres core guarantees atomicity to all basic devres operations and +has support for single-instance devres types (atomic +lookup-and-add-if-not-found). Other than that, synchronizing +concurrent accesses to allocated devres data is caller's +responsibility. This is usually non-issue because bus ops and +resource allocations already do the job. + +For an example of single-instance devres type, read pcim_iomap_table() +in lib/devres.c. + +All devres interface functions can be called without context if the +right gfp mask is given. + + +5. Overhead +----------- + +Each devres bookkeeping info is allocated together with requested data +area. With debug option turned off, bookkeeping info occupies 16 +bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded +up to ull alignment). If singly linked list is used, it can be +reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). + +Each devres group occupies 8 pointers. It can be reduced to 6 if +singly linked list is used. + +Memory space overhead on ahci controller with two ports is between 300 +and 400 bytes on 32bit machine after naive conversion (we can +certainly invest a bit more effort into libata core layer). + + +6. List of managed interfaces +----------------------------- + +CLOCK + devm_clk_get() + devm_clk_get_optional() + devm_clk_put() + devm_clk_hw_register() + devm_of_clk_add_hw_provider() + devm_clk_hw_register_clkdev() + +DMA + dmaenginem_async_device_register() + dmam_alloc_coherent() + dmam_alloc_attrs() + dmam_free_coherent() + dmam_pool_create() + dmam_pool_destroy() + +DRM + devm_drm_dev_init() + +GPIO + devm_gpiod_get() + devm_gpiod_get_index() + devm_gpiod_get_index_optional() + devm_gpiod_get_optional() + devm_gpiod_put() + devm_gpiod_unhinge() + devm_gpiochip_add_data() + devm_gpio_request() + devm_gpio_request_one() + devm_gpio_free() + +I2C + devm_i2c_new_dummy_device() + +IIO + devm_iio_device_alloc() + devm_iio_device_free() + devm_iio_device_register() + devm_iio_device_unregister() + devm_iio_kfifo_allocate() + devm_iio_kfifo_free() + devm_iio_triggered_buffer_setup() + devm_iio_triggered_buffer_cleanup() + devm_iio_trigger_alloc() + devm_iio_trigger_free() + devm_iio_trigger_register() + devm_iio_trigger_unregister() + devm_iio_channel_get() + devm_iio_channel_release() + devm_iio_channel_get_all() + devm_iio_channel_release_all() + +INPUT + devm_input_allocate_device() + +IO region + devm_release_mem_region() + devm_release_region() + devm_release_resource() + devm_request_mem_region() + devm_request_region() + devm_request_resource() + +IOMAP + devm_ioport_map() + devm_ioport_unmap() + devm_ioremap() + devm_ioremap_nocache() + devm_ioremap_wc() + devm_ioremap_resource() : checks resource, requests memory region, ioremaps + devm_iounmap() + pcim_iomap() + pcim_iomap_regions() : do request_region() and iomap() on multiple BARs + pcim_iomap_table() : array of mapped addresses indexed by BAR + pcim_iounmap() + +IRQ + devm_free_irq() + devm_request_any_context_irq() + devm_request_irq() + devm_request_threaded_irq() + devm_irq_alloc_descs() + devm_irq_alloc_desc() + devm_irq_alloc_desc_at() + devm_irq_alloc_desc_from() + devm_irq_alloc_descs_from() + devm_irq_alloc_generic_chip() + devm_irq_setup_generic_chip() + devm_irq_sim_init() + +LED + devm_led_classdev_register() + devm_led_classdev_unregister() + +MDIO + devm_mdiobus_alloc() + devm_mdiobus_alloc_size() + devm_mdiobus_free() + +MEM + devm_free_pages() + devm_get_free_pages() + devm_kasprintf() + devm_kcalloc() + devm_kfree() + devm_kmalloc() + devm_kmalloc_array() + devm_kmemdup() + devm_kstrdup() + devm_kvasprintf() + devm_kzalloc() + +MFD + devm_mfd_add_devices() + +MUX + devm_mux_chip_alloc() + devm_mux_chip_register() + devm_mux_control_get() + +PER-CPU MEM + devm_alloc_percpu() + devm_free_percpu() + +PCI + devm_pci_alloc_host_bridge() : managed PCI host bridge allocation + devm_pci_remap_cfgspace() : ioremap PCI configuration space + devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource + pcim_enable_device() : after success, all PCI ops become managed + pcim_pin_device() : keep PCI device enabled after release + +PHY + devm_usb_get_phy() + devm_usb_put_phy() + +PINCTRL + devm_pinctrl_get() + devm_pinctrl_put() + devm_pinctrl_register() + devm_pinctrl_unregister() + +POWER + devm_reboot_mode_register() + devm_reboot_mode_unregister() + +PWM + devm_pwm_get() + devm_pwm_put() + +REGULATOR + devm_regulator_bulk_get() + devm_regulator_get() + devm_regulator_put() + devm_regulator_register() + +RESET + devm_reset_control_get() + devm_reset_controller_register() + +SERDEV + devm_serdev_device_open() + +SLAVE DMA ENGINE + devm_acpi_dma_controller_register() + +SPI + devm_spi_register_master() + +WATCHDOG + devm_watchdog_register_device() diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst new file mode 100644 index 000000000000..11d281506a04 --- /dev/null +++ b/Documentation/driver-api/driver-model/driver.rst @@ -0,0 +1,223 @@ +============== +Device Drivers +============== + +See the kerneldoc for the struct device_driver. + + +Allocation +~~~~~~~~~~ + +Device drivers are statically allocated structures. Though there may +be multiple devices in a system that a driver supports, struct +device_driver represents the driver as a whole (not a particular +device instance). + +Initialization +~~~~~~~~~~~~~~ + +The driver must initialize at least the name and bus fields. It should +also initialize the devclass field (when it arrives), so it may obtain +the proper linkage internally. It should also initialize as many of +the callbacks as possible, though each is optional. + +Declaration +~~~~~~~~~~~ + +As stated above, struct device_driver objects are statically +allocated. Below is an example declaration of the eepro100 +driver. This declaration is hypothetical only; it relies on the driver +being converted completely to the new model:: + + static struct device_driver eepro100_driver = { + .name = "eepro100", + .bus = &pci_bus_type, + + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }; + +Most drivers will not be able to be converted completely to the new +model because the bus they belong to has a bus-specific structure with +bus-specific fields that cannot be generalized. + +The most common example of this are device ID structures. A driver +typically defines an array of device IDs that it supports. The format +of these structures and the semantics for comparing device IDs are +completely bus-specific. Defining them as bus-specific entities would +sacrifice type-safety, so we keep bus-specific structures around. + +Bus-specific drivers should include a generic struct device_driver in +the definition of the bus-specific driver. Like this:: + + struct pci_driver { + const struct pci_device_id *id_table; + struct device_driver driver; + }; + +A definition that included bus-specific fields would look like +(using the eepro100 driver again):: + + static struct pci_driver eepro100_driver = { + .id_table = eepro100_pci_tbl, + .driver = { + .name = "eepro100", + .bus = &pci_bus_type, + .probe = eepro100_probe, + .remove = eepro100_remove, + .suspend = eepro100_suspend, + .resume = eepro100_resume, + }, + }; + +Some may find the syntax of embedded struct initialization awkward or +even a bit ugly. So far, it's the best way we've found to do what we want... + +Registration +~~~~~~~~~~~~ + +:: + + int driver_register(struct device_driver *drv); + +The driver registers the structure on startup. For drivers that have +no bus-specific fields (i.e. don't have a bus-specific driver +structure), they would use driver_register and pass a pointer to their +struct device_driver object. + +Most drivers, however, will have a bus-specific structure and will +need to register with the bus using something like pci_driver_register. + +It is important that drivers register their driver structure as early as +possible. Registration with the core initializes several fields in the +struct device_driver object, including the reference count and the +lock. These fields are assumed to be valid at all times and may be +used by the device model core or the bus driver. + + +Transition Bus Drivers +~~~~~~~~~~~~~~~~~~~~~~ + +By defining wrapper functions, the transition to the new model can be +made easier. Drivers can ignore the generic structure altogether and +let the bus wrapper fill in the fields. For the callbacks, the bus can +define generic callbacks that forward the call to the bus-specific +callbacks of the drivers. + +This solution is intended to be only temporary. In order to get class +information in the driver, the drivers must be modified anyway. Since +converting drivers to the new model should reduce some infrastructural +complexity and code size, it is recommended that they are converted as +class information is added. + +Access +~~~~~~ + +Once the object has been registered, it may access the common fields of +the object, like the lock and the list of devices:: + + int driver_for_each_dev(struct device_driver *drv, void *data, + int (*callback)(struct device *dev, void *data)); + +The devices field is a list of all the devices that have been bound to +the driver. The LDM core provides a helper function to operate on all +the devices a driver controls. This helper locks the driver on each +node access, and does proper reference counting on each device as it +accesses it. + + +sysfs +~~~~~ + +When a driver is registered, a sysfs directory is created in its +bus's directory. In this directory, the driver can export an interface +to userspace to control operation of the driver on a global basis; +e.g. toggling debugging output in the driver. + +A future feature of this directory will be a 'devices' directory. This +directory will contain symlinks to the directories of devices it +supports. + + + +Callbacks +~~~~~~~~~ + +:: + + int (*probe) (struct device *dev); + +The probe() entry is called in task context, with the bus's rwsem locked +and the driver partially bound to the device. Drivers commonly use +container_of() to convert "dev" to a bus-specific type, both in probe() +and other routines. That type often provides device resource data, such +as pci_dev.resource[] or platform_device.resources, which is used in +addition to dev->platform_data to initialize the driver. + +This callback holds the driver-specific logic to bind the driver to a +given device. That includes verifying that the device is present, that +it's a version the driver can handle, that driver data structures can +be allocated and initialized, and that any hardware can be initialized. +Drivers often store a pointer to their state with dev_set_drvdata(). +When the driver has successfully bound itself to that device, then probe() +returns zero and the driver model code will finish its part of binding +the driver to that device. + +A driver's probe() may return a negative errno value to indicate that +the driver did not bind to this device, in which case it should have +released all resources it allocated:: + + int (*remove) (struct device *dev); + +remove is called to unbind a driver from a device. This may be +called if a device is physically removed from the system, if the +driver module is being unloaded, during a reboot sequence, or +in other cases. + +It is up to the driver to determine if the device is present or +not. It should free any resources allocated specifically for the +device; i.e. anything in the device's driver_data field. + +If the device is still present, it should quiesce the device and place +it into a supported low-power state:: + + int (*suspend) (struct device *dev, pm_message_t state); + +suspend is called to put the device in a low power state:: + + int (*resume) (struct device *dev); + +Resume is used to bring a device back from a low power state. + + +Attributes +~~~~~~~~~~ + +:: + + struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *driver, char *buf); + ssize_t (*store)(struct device_driver *, const char *buf, size_t count); + }; + +Device drivers can export attributes via their sysfs directories. +Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO +macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO +macros. + +Example:: + + DRIVER_ATTR_RW(debug); + +This is equivalent to declaring:: + + struct driver_attribute driver_attr_debug; + +This can then be used to add and remove the attribute from the +driver's directory using:: + + int driver_create_file(struct device_driver *, const struct driver_attribute *); + void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst new file mode 100644 index 000000000000..755016422269 --- /dev/null +++ b/Documentation/driver-api/driver-model/index.rst @@ -0,0 +1,24 @@ +============ +Driver Model +============ + +.. toctree:: + :maxdepth: 1 + + binding + bus + class + design-patterns + device + devres + driver + overview + platform + porting + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst new file mode 100644 index 000000000000..d4d1e9b40e0c --- /dev/null +++ b/Documentation/driver-api/driver-model/overview.rst @@ -0,0 +1,124 @@ +============================= +The Linux Kernel Device Model +============================= + +Patrick Mochel + +Drafted 26 August 2002 +Updated 31 January 2006 + + +Overview +~~~~~~~~ + +The Linux Kernel Driver Model is a unification of all the disparate driver +models that were previously used in the kernel. It is intended to augment the +bus-specific drivers for bridges and devices by consolidating a set of data +and operations into globally accessible data structures. + +Traditional driver models implemented some sort of tree-like structure +(sometimes just a list) for the devices they control. There wasn't any +uniformity across the different bus types. + +The current driver model provides a common, uniform data model for describing +a bus and the devices that can appear under the bus. The unified bus +model includes a set of common attributes which all busses carry, and a set +of common callbacks, such as device discovery during bus probing, bus +shutdown, bus power management, etc. + +The common device and bridge interface reflects the goals of the modern +computer: namely the ability to do seamless device "plug and play", power +management, and hot plug. In particular, the model dictated by Intel and +Microsoft (namely ACPI) ensures that almost every device on almost any bus +on an x86-compatible system can work within this paradigm. Of course, +not every bus is able to support all such operations, although most +buses support most of those operations. + + +Downstream Access +~~~~~~~~~~~~~~~~~ + +Common data fields have been moved out of individual bus layers into a common +data structure. These fields must still be accessed by the bus layers, +and sometimes by the device-specific drivers. + +Other bus layers are encouraged to do what has been done for the PCI layer. +struct pci_dev now looks like this:: + + struct pci_dev { + ... + + struct device dev; /* Generic device interface */ + ... + }; + +Note first that the struct device dev within the struct pci_dev is +statically allocated. This means only one allocation on device discovery. + +Note also that that struct device dev is not necessarily defined at the +front of the pci_dev structure. This is to make people think about what +they're doing when switching between the bus driver and the global driver, +and to discourage meaningless and incorrect casts between the two. + +The PCI bus layer freely accesses the fields of struct device. It knows about +the structure of struct pci_dev, and it should know the structure of struct +device. Individual PCI device drivers that have been converted to the current +driver model generally do not and should not touch the fields of struct device, +unless there is a compelling reason to do so. + +The above abstraction prevents unnecessary pain during transitional phases. +If it were not done this way, then when a field was renamed or removed, every +downstream driver would break. On the other hand, if only the bus layer +(and not the device layer) accesses the struct device, it is only the bus +layer that needs to change. + + +User Interface +~~~~~~~~~~~~~~ + +By virtue of having a complete hierarchical view of all the devices in the +system, exporting a complete hierarchical view to userspace becomes relatively +easy. This has been accomplished by implementing a special purpose virtual +file system named sysfs. + +Almost all mainstream Linux distros mount this filesystem automatically; you +can see some variation of the following in the output of the "mount" command:: + + $ mount + ... + none on /sys type sysfs (rw,noexec,nosuid,nodev) + ... + $ + +The auto-mounting of sysfs is typically accomplished by an entry similar to +the following in the /etc/fstab file:: + + none /sys sysfs defaults 0 0 + +or something similar in the /lib/init/fstab file on Debian-based systems:: + + none /sys sysfs nodev,noexec,nosuid 0 0 + +If sysfs is not automatically mounted, you can always do it manually with:: + + # mount -t sysfs sysfs /sys + +Whenever a device is inserted into the tree, a directory is created for it. +This directory may be populated at each layer of discovery - the global layer, +the bus layer, or the device layer. + +The global layer currently creates two files - 'name' and 'power'. The +former only reports the name of the device. The latter reports the +current power state of the device. It will also be used to set the current +power state. + +The bus layer may also create files for the devices it finds while probing the +bus. For example, the PCI layer currently creates 'irq' and 'resource' files +for each PCI device. + +A device-specific driver may also export files in its directory to expose +device-specific data or tunable interfaces. + +More information about the sysfs directory layout can be found in +the other documents in this directory and in the file +Documentation/filesystems/sysfs.txt. diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst new file mode 100644 index 000000000000..334dd4071ae4 --- /dev/null +++ b/Documentation/driver-api/driver-model/platform.rst @@ -0,0 +1,246 @@ +============================ +Platform Devices and Drivers +============================ + +See for the driver model interface to the +platform bus: platform_device, and platform_driver. This pseudo-bus +is used to connect devices on busses with minimal infrastructure, +like those used to integrate peripherals on many system-on-chip +processors, or some "legacy" PC interconnects; as opposed to large +formally specified ones like PCI or USB. + + +Platform devices +~~~~~~~~~~~~~~~~ +Platform devices are devices that typically appear as autonomous +entities in the system. This includes legacy port-based devices and +host bridges to peripheral buses, and most controllers integrated +into system-on-chip platforms. What they usually have in common +is direct addressing from a CPU bus. Rarely, a platform_device will +be connected through a segment of some other kind of bus; but its +registers will still be directly addressable. + +Platform devices are given a name, used in driver binding, and a +list of resources such as addresses and IRQs:: + + struct platform_device { + const char *name; + u32 id; + struct device dev; + u32 num_resources; + struct resource *resource; + }; + + +Platform drivers +~~~~~~~~~~~~~~~~ +Platform drivers follow the standard driver model convention, where +discovery/enumeration is handled outside the drivers, and drivers +provide probe() and remove() methods. They support power management +and shutdown notifications using the standard conventions:: + + struct platform_driver { + int (*probe)(struct platform_device *); + int (*remove)(struct platform_device *); + void (*shutdown)(struct platform_device *); + int (*suspend)(struct platform_device *, pm_message_t state); + int (*suspend_late)(struct platform_device *, pm_message_t state); + int (*resume_early)(struct platform_device *); + int (*resume)(struct platform_device *); + struct device_driver driver; + }; + +Note that probe() should in general verify that the specified device hardware +actually exists; sometimes platform setup code can't be sure. The probing +can use device resources, including clocks, and device platform_data. + +Platform drivers register themselves the normal way:: + + int platform_driver_register(struct platform_driver *drv); + +Or, in common situations where the device is known not to be hot-pluggable, +the probe() routine can live in an init section to reduce the driver's +runtime memory footprint:: + + int platform_driver_probe(struct platform_driver *drv, + int (*probe)(struct platform_device *)) + +Kernel modules can be composed of several platform drivers. The platform core +provides helpers to register and unregister an array of drivers:: + + int __platform_register_drivers(struct platform_driver * const *drivers, + unsigned int count, struct module *owner); + void platform_unregister_drivers(struct platform_driver * const *drivers, + unsigned int count); + +If one of the drivers fails to register, all drivers registered up to that +point will be unregistered in reverse order. Note that there is a convenience +macro that passes THIS_MODULE as owner parameter:: + + #define platform_register_drivers(drivers, count) + + +Device Enumeration +~~~~~~~~~~~~~~~~~~ +As a rule, platform specific (and often board-specific) setup code will +register platform devices:: + + int platform_device_register(struct platform_device *pdev); + + int platform_add_devices(struct platform_device **pdevs, int ndev); + +The general rule is to register only those devices that actually exist, +but in some cases extra devices might be registered. For example, a kernel +might be configured to work with an external network adapter that might not +be populated on all boards, or likewise to work with an integrated controller +that some boards might not hook up to any peripherals. + +In some cases, boot firmware will export tables describing the devices +that are populated on a given board. Without such tables, often the +only way for system setup code to set up the correct devices is to build +a kernel for a specific target board. Such board-specific kernels are +common with embedded and custom systems development. + +In many cases, the memory and IRQ resources associated with the platform +device are not enough to let the device's driver work. Board setup code +will often provide additional information using the device's platform_data +field to hold additional information. + +Embedded systems frequently need one or more clocks for platform devices, +which are normally kept off until they're actively needed (to save power). +System setup also associates those clocks with the device, so that that +calls to clk_get(&pdev->dev, clock_name) return them as needed. + + +Legacy Drivers: Device Probing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers are not fully converted to the driver model, because they take +on a non-driver role: the driver registers its platform device, rather than +leaving that for system infrastructure. Such drivers can't be hotplugged +or coldplugged, since those mechanisms require device creation to be in a +different system component than the driver. + +The only "good" reason for this is to handle older system designs which, like +original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware +configuration. Newer systems have largely abandoned that model, in favor of +bus-level support for dynamic configuration (PCI, USB), or device tables +provided by the boot firmware (e.g. PNPACPI on x86). There are too many +conflicting options about what might be where, and even educated guesses by +an operating system will be wrong often enough to make trouble. + +This style of driver is discouraged. If you're updating such a driver, +please try to move the device enumeration to a more appropriate location, +outside the driver. This will usually be cleanup, since such drivers +tend to already have "normal" modes, such as ones using device nodes that +were created by PNP or by platform device setup. + +None the less, there are some APIs to support such legacy drivers. Avoid +using these calls except with such hotplug-deficient drivers:: + + struct platform_device *platform_device_alloc( + const char *name, int id); + +You can use platform_device_alloc() to dynamically allocate a device, which +you will then initialize with resources and platform_device_register(). +A better solution is usually:: + + struct platform_device *platform_device_register_simple( + const char *name, int id, + struct resource *res, unsigned int nres); + +You can use platform_device_register_simple() as a one-step call to allocate +and register a device. + + +Device Naming and Driver Binding +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The platform_device.dev.bus_id is the canonical name for the devices. +It's built from two components: + + * platform_device.name ... which is also used to for driver matching. + + * platform_device.id ... the device instance number, or else "-1" + to indicate there's only one. + +These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and +"serial/3" indicates bus_id "serial.3"; both would use the platform_driver +named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) +and use the platform_driver called "my_rtc". + +Driver binding is performed automatically by the driver core, invoking +driver probe() after finding a match between device and driver. If the +probe() succeeds, the driver and device are bound as usual. There are +three different ways to find such a match: + + - Whenever a device is registered, the drivers for that bus are + checked for matches. Platform devices should be registered very + early during system boot. + + - When a driver is registered using platform_driver_register(), all + unbound devices on that bus are checked for matches. Drivers + usually register later during booting, or by module loading. + + - Registering a driver using platform_driver_probe() works just like + using platform_driver_register(), except that the driver won't + be probed later if another device registers. (Which is OK, since + this interface is only for use with non-hotpluggable devices.) + + +Early Platform Devices and Drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The early platform interfaces provide platform data to platform device +drivers early on during the system boot. The code is built on top of the +early_param() command line parsing and can be executed very early on. + +Example: "earlyprintk" class early serial console in 6 steps + +1. Registering early platform device data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code registers platform device data using the function +early_platform_add_devices(). In the case of early serial console this +should be hardware configuration for the serial port. Devices registered +at this point will later on be matched against early platform drivers. + +2. Parsing kernel command line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls parse_early_param() to parse the kernel +command line. This will execute all matching early_param() callbacks. +User specified early platform devices will be registered at this point. +For the early serial console case the user can specify port on the +kernel command line as "earlyprintk=serial.0" where "earlyprintk" is +the class string, "serial" is the name of the platform driver and +0 is the platform device id. If the id is -1 then the dot and the +id can be omitted. + +3. Installing early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code may optionally force registration of all early +platform drivers belonging to a certain class using the function +early_platform_driver_register_all(). User specified devices from +step 2 have priority over these. This step is omitted by the serial +driver example since the early serial driver code should be disabled +unless the user has specified port on the kernel command line. + +4. Early platform driver registration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Compiled-in platform drivers making use of early_platform_init() are +automatically registered during step 2 or 3. The serial driver example +should use early_platform_init("earlyprintk", &platform_driver). + +5. Probing of early platform drivers belonging to a certain class +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The architecture code calls early_platform_driver_probe() to match +registered early platform devices associated with a certain class with +registered early platform drivers. Matched devices will get probed(). +This step can be executed at any point during the early boot. As soon +as possible may be good for the serial port case. + +6. Inside the early platform driver probe() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver code needs to take special care during early boot, especially +when it comes to memory allocation and interrupt registration. The code +in the probe() function can use is_early_platform_device() to check if +it is called at early platform device or at the regular platform device +time. The early serial driver performs register_console() at this point. + +For further information, see . diff --git a/Documentation/driver-api/driver-model/porting.rst b/Documentation/driver-api/driver-model/porting.rst new file mode 100644 index 000000000000..931ea879af3f --- /dev/null +++ b/Documentation/driver-api/driver-model/porting.rst @@ -0,0 +1,448 @@ +======================================= +Porting Drivers to the New Driver Model +======================================= + +Patrick Mochel + +7 January 2003 + + +Overview + +Please refer to `Documentation/driver-api/driver-model/*.rst` for definitions of +various driver types and concepts. + +Most of the work of porting devices drivers to the new model happens +at the bus driver layer. This was intentional, to minimize the +negative effect on kernel drivers, and to allow a gradual transition +of bus drivers. + +In a nutshell, the driver model consists of a set of objects that can +be embedded in larger, bus-specific objects. Fields in these generic +objects can replace fields in the bus-specific objects. + +The generic objects must be registered with the driver model core. By +doing so, they will exported via the sysfs filesystem. sysfs can be +mounted by doing:: + + # mount -t sysfs sysfs /sys + + + +The Process + +Step 0: Read include/linux/device.h for object and function definitions. + +Step 1: Registering the bus driver. + + +- Define a struct bus_type for the bus driver:: + + struct bus_type pci_bus_type = { + .name = "pci", + }; + + +- Register the bus type. + + This should be done in the initialization function for the bus type, + which is usually the module_init(), or equivalent, function:: + + static int __init pci_driver_init(void) + { + return bus_register(&pci_bus_type); + } + + subsys_initcall(pci_driver_init); + + + The bus type may be unregistered (if the bus driver may be compiled + as a module) by doing:: + + bus_unregister(&pci_bus_type); + + +- Export the bus type for others to use. + + Other code may wish to reference the bus type, so declare it in a + shared header file and export the symbol. + +From include/linux/pci.h:: + + extern struct bus_type pci_bus_type; + + +From file the above code appears in:: + + EXPORT_SYMBOL(pci_bus_type); + + + +- This will cause the bus to show up in /sys/bus/pci/ with two + subdirectories: 'devices' and 'drivers':: + + # tree -d /sys/bus/pci/ + /sys/bus/pci/ + |-- devices + `-- drivers + + + +Step 2: Registering Devices. + +struct device represents a single device. It mainly contains metadata +describing the relationship the device has to other entities. + + +- Embed a struct device in the bus-specific device type:: + + + struct pci_dev { + ... + struct device dev; /* Generic device interface */ + ... + }; + + It is recommended that the generic device not be the first item in + the struct to discourage programmers from doing mindless casts + between the object types. Instead macros, or inline functions, + should be created to convert from the generic object type:: + + + #define to_pci_dev(n) container_of(n, struct pci_dev, dev) + + or + + static inline struct pci_dev * to_pci_dev(struct kobject * kobj) + { + return container_of(n, struct pci_dev, dev); + } + + This allows the compiler to verify type-safety of the operations + that are performed (which is Good). + + +- Initialize the device on registration. + + When devices are discovered or registered with the bus type, the + bus driver should initialize the generic device. The most important + things to initialize are the bus_id, parent, and bus fields. + + The bus_id is an ASCII string that contains the device's address on + the bus. The format of this string is bus-specific. This is + necessary for representing devices in sysfs. + + parent is the physical parent of the device. It is important that + the bus driver sets this field correctly. + + The driver model maintains an ordered list of devices that it uses + for power management. This list must be in order to guarantee that + devices are shutdown before their physical parents, and vice versa. + The order of this list is determined by the parent of registered + devices. + + Also, the location of the device's sysfs directory depends on a + device's parent. sysfs exports a directory structure that mirrors + the device hierarchy. Accurately setting the parent guarantees that + sysfs will accurately represent the hierarchy. + + The device's bus field is a pointer to the bus type the device + belongs to. This should be set to the bus_type that was declared + and initialized before. + + Optionally, the bus driver may set the device's name and release + fields. + + The name field is an ASCII string describing the device, like + + "ATI Technologies Inc Radeon QD" + + The release field is a callback that the driver model core calls + when the device has been removed, and all references to it have + been released. More on this in a moment. + + +- Register the device. + + Once the generic device has been initialized, it can be registered + with the driver model core by doing:: + + device_register(&dev->dev); + + It can later be unregistered by doing:: + + device_unregister(&dev->dev); + + This should happen on buses that support hotpluggable devices. + If a bus driver unregisters a device, it should not immediately free + it. It should instead wait for the driver model core to call the + device's release method, then free the bus-specific object. + (There may be other code that is currently referencing the device + structure, and it would be rude to free the device while that is + happening). + + + When the device is registered, a directory in sysfs is created. + The PCI tree in sysfs looks like:: + + /sys/devices/pci0/ + |-- 00:00.0 + |-- 00:01.0 + | `-- 01:00.0 + |-- 00:02.0 + | `-- 02:1f.0 + | `-- 03:00.0 + |-- 00:1e.0 + | `-- 04:04.0 + |-- 00:1f.0 + |-- 00:1f.1 + | |-- ide0 + | | |-- 0.0 + | | `-- 0.1 + | `-- ide1 + | `-- 1.0 + |-- 00:1f.2 + |-- 00:1f.3 + `-- 00:1f.5 + + Also, symlinks are created in the bus's 'devices' directory + that point to the device's directory in the physical hierarchy:: + + /sys/bus/pci/devices/ + |-- 00:00.0 -> ../../../devices/pci0/00:00.0 + |-- 00:01.0 -> ../../../devices/pci0/00:01.0 + |-- 00:02.0 -> ../../../devices/pci0/00:02.0 + |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 + |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 + |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 + |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 + |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 + |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 + |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 + |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 + |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 + `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 + + + +Step 3: Registering Drivers. + +struct device_driver is a simple driver structure that contains a set +of operations that the driver model core may call. + + +- Embed a struct device_driver in the bus-specific driver. + + Just like with devices, do something like:: + + struct pci_driver { + ... + struct device_driver driver; + }; + + +- Initialize the generic driver structure. + + When the driver registers with the bus (e.g. doing pci_register_driver()), + initialize the necessary fields of the driver: the name and bus + fields. + + +- Register the driver. + + After the generic driver has been initialized, call:: + + driver_register(&drv->driver); + + to register the driver with the core. + + When the driver is unregistered from the bus, unregister it from the + core by doing:: + + driver_unregister(&drv->driver); + + Note that this will block until all references to the driver have + gone away. Normally, there will not be any. + + +- Sysfs representation. + + Drivers are exported via sysfs in their bus's 'driver's directory. + For example:: + + /sys/bus/pci/drivers/ + |-- 3c59x + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + |-- e100 + `-- serial + + +Step 4: Define Generic Methods for Drivers. + +struct device_driver defines a set of operations that the driver model +core calls. Most of these operations are probably similar to +operations the bus already defines for drivers, but taking different +parameters. + +It would be difficult and tedious to force every driver on a bus to +simultaneously convert their drivers to generic format. Instead, the +bus driver should define single instances of the generic methods that +forward call to the bus-specific drivers. For instance:: + + + static int pci_device_remove(struct device * dev) + { + struct pci_dev * pci_dev = to_pci_dev(dev); + struct pci_driver * drv = pci_dev->driver; + + if (drv) { + if (drv->remove) + drv->remove(pci_dev); + pci_dev->driver = NULL; + } + return 0; + } + + +The generic driver should be initialized with these methods before it +is registered:: + + /* initialize common driver fields */ + drv->driver.name = drv->name; + drv->driver.bus = &pci_bus_type; + drv->driver.probe = pci_device_probe; + drv->driver.resume = pci_device_resume; + drv->driver.suspend = pci_device_suspend; + drv->driver.remove = pci_device_remove; + + /* register with core */ + driver_register(&drv->driver); + + +Ideally, the bus should only initialize the fields if they are not +already set. This allows the drivers to implement their own generic +methods. + + +Step 5: Support generic driver binding. + +The model assumes that a device or driver can be dynamically +registered with the bus at any time. When registration happens, +devices must be bound to a driver, or drivers must be bound to all +devices that it supports. + +A driver typically contains a list of device IDs that it supports. The +bus driver compares these IDs to the IDs of devices registered with it. +The format of the device IDs, and the semantics for comparing them are +bus-specific, so the generic model does attempt to generalize them. + +Instead, a bus may supply a method in struct bus_type that does the +comparison:: + + int (*match)(struct device * dev, struct device_driver * drv); + +match should return positive value if the driver supports the device, +and zero otherwise. It may also return error code (for example +-EPROBE_DEFER) if determining that given driver supports the device is +not possible. + +When a device is registered, the bus's list of drivers is iterated +over. bus->match() is called for each one until a match is found. + +When a driver is registered, the bus's list of devices is iterated +over. bus->match() is called for each device that is not already +claimed by a driver. + +When a device is successfully bound to a driver, device->driver is +set, the device is added to a per-driver list of devices, and a +symlink is created in the driver's sysfs directory that points to the +device's physical directory:: + + /sys/bus/pci/drivers/ + |-- 3c59x + | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 + |-- Ensoniq AudioPCI + |-- agpgart-amdk7 + | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 + |-- e100 + | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 + `-- serial + + +This driver binding should replace the existing driver binding +mechanism the bus currently uses. + + +Step 6: Supply a hotplug callback. + +Whenever a device is registered with the driver model core, the +userspace program /sbin/hotplug is called to notify userspace. +Users can define actions to perform when a device is inserted or +removed. + +The driver model core passes several arguments to userspace via +environment variables, including + +- ACTION: set to 'add' or 'remove' +- DEVPATH: set to the device's physical path in sysfs. + +A bus driver may also supply additional parameters for userspace to +consume. To do this, a bus must implement the 'hotplug' method in +struct bus_type:: + + int (*hotplug) (struct device *dev, char **envp, + int num_envp, char *buffer, int buffer_size); + +This is called immediately before /sbin/hotplug is executed. + + +Step 7: Cleaning up the bus driver. + +The generic bus, device, and driver structures provide several fields +that can replace those defined privately to the bus driver. + +- Device list. + +struct bus_type contains a list of all devices registered with the bus +type. This includes all devices on all instances of that bus type. +An internal list that the bus uses may be removed, in favor of using +this one. + +The core provides an iterator to access these devices:: + + int bus_for_each_dev(struct bus_type * bus, struct device * start, + void * data, int (*fn)(struct device *, void *)); + + +- Driver list. + +struct bus_type also contains a list of all drivers registered with +it. An internal list of drivers that the bus driver maintains may +be removed in favor of using the generic one. + +The drivers may be iterated over, like devices:: + + int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, + void * data, int (*fn)(struct device_driver *, void *)); + + +Please see drivers/base/bus.c for more information. + + +- rwsem + +struct bus_type contains an rwsem that protects all core accesses to +the device and driver lists. This can be used by the bus driver +internally, and should be used when accessing the device or driver +lists the bus maintains. + + +- Device and driver fields. + +Some of the fields in struct device and struct device_driver duplicate +fields in the bus-specific representations of these objects. Feel free +to remove the bus-specific ones and favor the generic ones. Note +though, that this will likely mean fixing up all the drivers that +reference the bus-specific fields (though those should all be 1-line +changes). diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 349f2dc33029..921c71a3d683 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -399,7 +399,7 @@ symbol: will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.rst) + (See Documentation/driver-api/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b4c993ff7655..9fb03b7bdeb1 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -14,6 +14,7 @@ available subsections can be seen below. .. toctree:: :maxdepth: 2 + driver-model/index basics infrastructure early-userspace/index diff --git a/Documentation/driver-model/binding.rst b/Documentation/driver-model/binding.rst deleted file mode 100644 index 7ea1d7a41e1d..000000000000 --- a/Documentation/driver-model/binding.rst +++ /dev/null @@ -1,98 +0,0 @@ -============== -Driver Binding -============== - -Driver binding is the process of associating a device with a device -driver that can control it. Bus drivers have typically handled this -because there have been bus-specific structures to represent the -devices and the drivers. With generic device and device driver -structures, most of the binding can take place using common code. - - -Bus -~~~ - -The bus type structure contains a list of all devices that are on that bus -type in the system. When device_register is called for a device, it is -inserted into the end of this list. The bus object also contains a -list of all drivers of that bus type. When driver_register is called -for a driver, it is inserted at the end of this list. These are the -two events which trigger driver binding. - - -device_register -~~~~~~~~~~~~~~~ - -When a new device is added, the bus's list of drivers is iterated over -to find one that supports it. In order to determine that, the device -ID of the device must match one of the device IDs that the driver -supports. The format and semantics for comparing IDs is bus-specific. -Instead of trying to derive a complex state machine and matching -algorithm, it is up to the bus driver to provide a callback to compare -a device against the IDs of a driver. The bus returns 1 if a match was -found; 0 otherwise. - -int match(struct device * dev, struct device_driver * drv); - -If a match is found, the device's driver field is set to the driver -and the driver's probe callback is called. This gives the driver a -chance to verify that it really does support the hardware, and that -it's in a working state. - -Device Class -~~~~~~~~~~~~ - -Upon the successful completion of probe, the device is registered with -the class to which it belongs. Device drivers belong to one and only one -class, and that is set in the driver's devclass field. -devclass_add_device is called to enumerate the device within the class -and actually register it with the class, which happens with the -class's register_dev callback. - - -Driver -~~~~~~ - -When a driver is attached to a device, the device is inserted into the -driver's list of devices. - - -sysfs -~~~~~ - -A symlink is created in the bus's 'devices' directory that points to -the device's directory in the physical hierarchy. - -A symlink is created in the driver's 'devices' directory that points -to the device's directory in the physical hierarchy. - -A directory for the device is created in the class's directory. A -symlink is created in that directory that points to the device's -physical location in the sysfs tree. - -A symlink can be created (though this isn't done yet) in the device's -physical directory to either its class directory, or the class's -top-level directory. One can also be created to point to its driver's -directory also. - - -driver_register -~~~~~~~~~~~~~~~ - -The process is almost identical for when a new driver is added. -The bus's list of devices is iterated over to find a match. Devices -that already have a driver are skipped. All the devices are iterated -over, to bind as many devices as possible to the driver. - - -Removal -~~~~~~~ - -When a device is removed, the reference count for it will eventually -go to 0. When it does, the remove callback of the driver is called. It -is removed from the driver's list of devices and the reference count -of the driver is decremented. All symlinks between the two are removed. - -When a driver is removed, the list of devices that it supports is -iterated over, and the driver's remove callback is called for each -one. The device is removed from that list and the symlinks removed. diff --git a/Documentation/driver-model/bus.rst b/Documentation/driver-model/bus.rst deleted file mode 100644 index 016b15a6e8ea..000000000000 --- a/Documentation/driver-model/bus.rst +++ /dev/null @@ -1,146 +0,0 @@ -========= -Bus Types -========= - -Definition -~~~~~~~~~~ -See the kerneldoc for the struct bus_type. - -int bus_register(struct bus_type * bus); - - -Declaration -~~~~~~~~~~~ - -Each bus type in the kernel (PCI, USB, etc) should declare one static -object of this type. They must initialize the name field, and may -optionally initialize the match callback:: - - struct bus_type pci_bus_type = { - .name = "pci", - .match = pci_bus_match, - }; - -The structure should be exported to drivers in a header file: - -extern struct bus_type pci_bus_type; - - -Registration -~~~~~~~~~~~~ - -When a bus driver is initialized, it calls bus_register. This -initializes the rest of the fields in the bus object and inserts it -into a global list of bus types. Once the bus object is registered, -the fields in it are usable by the bus driver. - - -Callbacks -~~~~~~~~~ - -match(): Attaching Drivers to Devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The format of device ID structures and the semantics for comparing -them are inherently bus-specific. Drivers typically declare an array -of device IDs of devices they support that reside in a bus-specific -driver structure. - -The purpose of the match callback is to give the bus an opportunity to -determine if a particular driver supports a particular device by -comparing the device IDs the driver supports with the device ID of a -particular device, without sacrificing bus-specific functionality or -type-safety. - -When a driver is registered with the bus, the bus's list of devices is -iterated over, and the match callback is called for each device that -does not have a driver associated with it. - - - -Device and Driver Lists -~~~~~~~~~~~~~~~~~~~~~~~ - -The lists of devices and drivers are intended to replace the local -lists that many buses keep. They are lists of struct devices and -struct device_drivers, respectively. Bus drivers are free to use the -lists as they please, but conversion to the bus-specific type may be -necessary. - -The LDM core provides helper functions for iterating over each list:: - - int bus_for_each_dev(struct bus_type * bus, struct device * start, - void * data, - int (*fn)(struct device *, void *)); - - int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - -These helpers iterate over the respective list, and call the callback -for each device or driver in the list. All list accesses are -synchronized by taking the bus's lock (read currently). The reference -count on each object in the list is incremented before the callback is -called; it is decremented after the next object has been obtained. The -lock is not held when calling the callback. - - -sysfs -~~~~~~~~ -There is a top-level directory named 'bus'. - -Each bus gets a directory in the bus directory, along with two default -directories:: - - /sys/bus/pci/ - |-- devices - `-- drivers - -Drivers registered with the bus get a directory in the bus's drivers -directory:: - - /sys/bus/pci/ - |-- devices - `-- drivers - |-- Intel ICH - |-- Intel ICH Joystick - |-- agpgart - `-- e100 - -Each device that is discovered on a bus of that type gets a symlink in -the bus's devices directory to the device's directory in the physical -hierarchy:: - - /sys/bus/pci/ - |-- devices - | |-- 00:00.0 -> ../../../root/pci0/00:00.0 - | |-- 00:01.0 -> ../../../root/pci0/00:01.0 - | `-- 00:02.0 -> ../../../root/pci0/00:02.0 - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct bus_attribute { - struct attribute attr; - ssize_t (*show)(struct bus_type *, char * buf); - ssize_t (*store)(struct bus_type *, const char * buf, size_t count); - }; - -Bus drivers can export attributes using the BUS_ATTR_RW macro that works -similarly to the DEVICE_ATTR_RW macro for devices. For example, a -definition like this:: - - static BUS_ATTR_RW(debug); - -is equivalent to declaring:: - - static bus_attribute bus_attr_debug; - -This can then be used to add and remove the attribute from the bus's -sysfs directory using:: - - int bus_create_file(struct bus_type *, struct bus_attribute *); - void bus_remove_file(struct bus_type *, struct bus_attribute *); diff --git a/Documentation/driver-model/class.rst b/Documentation/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - - - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation of that programming interface for a particular device on -a particular bus. - -Device classes are agnostic with respect to what bus a device resides -on. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The device class structure looks like:: - - - typedef int (*devclass_add)(struct device *); - typedef void (*devclass_remove)(struct device *); - -See the kerneldoc for the struct class. - -A typical device class definition would look like:: - - struct device_class input_devclass = { - .name = "input", - .add_device = input_add_device, - .remove_device = input_remove_device, - }; - -Each device class structure should be exported in a header file so it -can be used by drivers, extensions and interfaces. - -Device classes are registered and unregistered with the core using:: - - int devclass_register(struct device_class * cls); - void devclass_unregister(struct device_class * cls); - - -Devices -~~~~~~~ -As devices are bound to drivers, they are added to the device class -that the driver belongs to. Before the driver model core, this would -typically happen during the driver's probe() callback, once the device -has been initialized. It now happens after the probe() callback -finishes from the core. - -The device is enumerated in the class. Each time a device is added to -the class, the class's devnum field is incremented and assigned to the -device. The field is never decremented, so if the device is removed -from the class and re-added, it will receive a different enumerated -value. - -The class is allowed to create a class-specific structure for the -device and store it in the device's class_data pointer. - -There is no list of devices in the device class. Each driver has a -list of devices that it supports. The device class has a list of -drivers of that particular class. To access all of the devices in the -class, iterate over the device lists of each driver in the class. - - -Device Drivers -~~~~~~~~~~~~~~ -Device drivers are added to device classes when they are registered -with the core. A driver specifies the class it belongs to by setting -the struct device_driver::devclass field. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs directory named 'class'. - -Each class gets a directory in the class directory, along with two -default subdirectories:: - - class/ - `-- input - |-- devices - `-- drivers - - -Drivers registered with the class get a symlink in the drivers/ directory -that points to the driver's directory (under its bus directory):: - - class/ - `-- input - |-- devices - `-- drivers - `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/ - - -Each device gets a symlink in the devices/ directory that points to the -device's directory in the physical hierarchy:: - - class/ - `-- input - |-- devices - | `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/ - `-- drivers - - -Exporting Attributes -~~~~~~~~~~~~~~~~~~~~ - -:: - - struct devclass_attribute { - struct attribute attr; - ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off); - ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off); - }; - -Class drivers can export attributes using the DEVCLASS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this:: - - static DEVCLASS_ATTR(debug,0644,show_debug,store_debug); - -is equivalent to declaring:: - - static devclass_attribute devclass_attr_debug; - -The bus driver can add and remove the attribute from the class's -sysfs directory using:: - - int devclass_create_file(struct device_class *, struct devclass_attribute *); - void devclass_remove_file(struct device_class *, struct devclass_attribute *); - -In the example above, the file will be named 'debug' in placed in the -class's directory in sysfs. - - -Interfaces -~~~~~~~~~~ -There may exist multiple mechanisms for accessing the same device of a -particular class type. Device interfaces describe these mechanisms. - -When a device is added to a device class, the core attempts to add it -to every interface that is registered with the device class. diff --git a/Documentation/driver-model/design-patterns.rst b/Documentation/driver-model/design-patterns.rst deleted file mode 100644 index 41eb8f41f7dd..000000000000 --- a/Documentation/driver-model/design-patterns.rst +++ /dev/null @@ -1,116 +0,0 @@ -============================= -Device Driver Design Patterns -============================= - -This document describes a few common design patterns found in device drivers. -It is likely that subsystem maintainers will ask driver developers to -conform to these design patterns. - -1. State Container -2. container_of() - - -1. State Container -~~~~~~~~~~~~~~~~~~ - -While the kernel contains a few device drivers that assume that they will -only be probed() once on a certain system (singletons), it is custom to assume -that the device the driver binds to will appear in several instances. This -means that the probe() function and all callbacks need to be reentrant. - -The most common way to achieve this is to use the state container design -pattern. It usually has this form:: - - struct foo { - spinlock_t lock; /* Example member */ - (...) - }; - - static int foo_probe(...) - { - struct foo *foo; - - foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL); - if (!foo) - return -ENOMEM; - spin_lock_init(&foo->lock); - (...) - } - -This will create an instance of struct foo in memory every time probe() is -called. This is our state container for this instance of the device driver. -Of course it is then necessary to always pass this instance of the -state around to all functions that need access to the state and its members. - -For example, if the driver is registering an interrupt handler, you would -pass around a pointer to struct foo like this:: - - static irqreturn_t foo_handler(int irq, void *arg) - { - struct foo *foo = arg; - (...) - } - - static int foo_probe(...) - { - struct foo *foo; - - (...) - ret = request_irq(irq, foo_handler, 0, "foo", foo); - } - -This way you always get a pointer back to the correct instance of foo in -your interrupt handler. - - -2. container_of() -~~~~~~~~~~~~~~~~~ - -Continuing on the above example we add an offloaded work:: - - struct foo { - spinlock_t lock; - struct workqueue_struct *wq; - struct work_struct offload; - (...) - }; - - static void foo_work(struct work_struct *work) - { - struct foo *foo = container_of(work, struct foo, offload); - - (...) - } - - static irqreturn_t foo_handler(int irq, void *arg) - { - struct foo *foo = arg; - - queue_work(foo->wq, &foo->offload); - (...) - } - - static int foo_probe(...) - { - struct foo *foo; - - foo->wq = create_singlethread_workqueue("foo-wq"); - INIT_WORK(&foo->offload, foo_work); - (...) - } - -The design pattern is the same for an hrtimer or something similar that will -return a single argument which is a pointer to a struct member in the -callback. - -container_of() is a macro defined in - -What container_of() does is to obtain a pointer to the containing struct from -a pointer to a member by a simple subtraction using the offsetof() macro from -standard C, which allows something similar to object oriented behaviours. -Notice that the contained member must not be a pointer, but an actual member -for this to work. - -We can see here that we avoid having global pointers to our struct foo * -instance this way, while still keeping the number of parameters passed to the -work function to a single pointer. diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-model/device.rst deleted file mode 100644 index 2b868d49d349..000000000000 --- a/Documentation/driver-model/device.rst +++ /dev/null @@ -1,109 +0,0 @@ -========================== -The Basic Device Structure -========================== - -See the kerneldoc for the struct device. - - -Programming Interface -~~~~~~~~~~~~~~~~~~~~~ -The bus driver that discovers the device uses this to register the -device with the core:: - - int device_register(struct device * dev); - -The bus should initialize the following fields: - - - parent - - name - - bus_id - - bus - -A device is removed from the core when its reference count goes to -0. The reference count can be adjusted using:: - - struct device * get_device(struct device * dev); - void put_device(struct device * dev); - -get_device() will return a pointer to the struct device passed to it -if the reference is not already 0 (if it's in the process of being -removed already). - -A driver can access the lock in the device structure using:: - - void lock_device(struct device * dev); - void unlock_device(struct device * dev); - - -Attributes -~~~~~~~~~~ - -:: - - struct device_attribute { - struct attribute attr; - ssize_t (*show)(struct device *dev, struct device_attribute *attr, - char *buf); - ssize_t (*store)(struct device *dev, struct device_attribute *attr, - const char *buf, size_t count); - }; - -Attributes of devices can be exported by a device driver through sysfs. - -Please see Documentation/filesystems/sysfs.txt for more information -on how sysfs works. - -As explained in Documentation/kobject.txt, device attributes must be -created before the KOBJ_ADD uevent is generated. The only way to realize -that is by defining an attribute group. - -Attributes are declared using a macro called DEVICE_ATTR:: - - #define DEVICE_ATTR(name,mode,show,store) - -Example::: - - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); - -This declares two structures of type struct device_attribute with respective -names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be -organized as follows into a group:: - - static struct attribute *dev_attrs[] = { - &dev_attr_type.attr, - &dev_attr_power.attr, - NULL, - }; - - static struct attribute_group dev_attr_group = { - .attrs = dev_attrs, - }; - - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, - NULL, - }; - -This array of groups can then be associated with a device by setting the -group pointer in struct device before device_register() is invoked:: - - dev->groups = dev_attr_groups; - device_register(dev); - -The device_register() function will use the 'groups' pointer to create the -device attributes and the device_unregister() function will use this pointer -to remove the device attributes. - -Word of warning: While the kernel allows device_create_file() and -device_remove_file() to be called on a device at any time, userspace has -strict expectations on when attributes get created. When a new device is -registered in the kernel, a uevent is generated to notify userspace (like -udev) that a new device is available. If attributes are added after the -device is registered, then userspace won't get notified and userspace will -not know about the new attributes. - -This is important for device driver that need to publish additional -attributes for a device at driver probe time. If the device driver simply -calls device_create_file() on the device structure passed to it, then -userspace will never be notified of the new attributes. diff --git a/Documentation/driver-model/devres.rst b/Documentation/driver-model/devres.rst deleted file mode 100644 index 4ac99122b5f1..000000000000 --- a/Documentation/driver-model/devres.rst +++ /dev/null @@ -1,414 +0,0 @@ -================================ -Devres - Managed Device Resource -================================ - -Tejun Heo - -First draft 10 January 2007 - -.. contents - - 1. Intro : Huh? Devres? - 2. Devres : Devres in a nutshell - 3. Devres Group : Group devres'es and release them together - 4. Details : Life time rules, calling context, ... - 5. Overhead : How much do we have to pay for this? - 6. List of managed interfaces: Currently implemented managed interfaces - - -1. Intro --------- - -devres came up while trying to convert libata to use iomap. Each -iomapped address should be kept and unmapped on driver detach. For -example, a plain SFF ATA controller (that is, good old PCI IDE) in -native mode makes use of 5 PCI BARs and all of them should be -maintained. - -As with many other device drivers, libata low level drivers have -sufficient bugs in ->remove and ->probe failure path. Well, yes, -that's probably because libata low level driver developers are lazy -bunch, but aren't all low level driver developers? After spending a -day fiddling with braindamaged hardware with no document or -braindamaged document, if it's finally working, well, it's working. - -For one reason or another, low level drivers don't receive as much -attention or testing as core code, and bugs on driver detach or -initialization failure don't happen often enough to be noticeable. -Init failure path is worse because it's much less travelled while -needs to handle multiple entry points. - -So, many low level drivers end up leaking resources on driver detach -and having half broken failure path implementation in ->probe() which -would leak resources or even cause oops when failure occurs. iomap -adds more to this mix. So do msi and msix. - - -2. Devres ---------- - -devres is basically linked list of arbitrarily sized memory areas -associated with a struct device. Each devres entry is associated with -a release function. A devres can be released in several ways. No -matter what, all devres entries are released on driver detach. On -release, the associated release function is invoked and then the -devres entry is freed. - -Managed interface is created for resources commonly used by device -drivers using devres. For example, coherent DMA memory is acquired -using dma_alloc_coherent(). The managed version is called -dmam_alloc_coherent(). It is identical to dma_alloc_coherent() except -for the DMA memory allocated using it is managed and will be -automatically released on driver detach. Implementation looks like -the following:: - - struct dma_devres { - size_t size; - void *vaddr; - dma_addr_t dma_handle; - }; - - static void dmam_coherent_release(struct device *dev, void *res) - { - struct dma_devres *this = res; - - dma_free_coherent(dev, this->size, this->vaddr, this->dma_handle); - } - - dmam_alloc_coherent(dev, size, dma_handle, gfp) - { - struct dma_devres *dr; - void *vaddr; - - dr = devres_alloc(dmam_coherent_release, sizeof(*dr), gfp); - ... - - /* alloc DMA memory as usual */ - vaddr = dma_alloc_coherent(...); - ... - - /* record size, vaddr, dma_handle in dr */ - dr->vaddr = vaddr; - ... - - devres_add(dev, dr); - - return vaddr; - } - -If a driver uses dmam_alloc_coherent(), the area is guaranteed to be -freed whether initialization fails half-way or the device gets -detached. If most resources are acquired using managed interface, a -driver can have much simpler init and exit code. Init path basically -looks like the following:: - - my_init_one() - { - struct mydev *d; - - d = devm_kzalloc(dev, sizeof(*d), GFP_KERNEL); - if (!d) - return -ENOMEM; - - d->ring = dmam_alloc_coherent(...); - if (!d->ring) - return -ENOMEM; - - if (check something) - return -EINVAL; - ... - - return register_to_upper_layer(d); - } - -And exit path:: - - my_remove_one() - { - unregister_from_upper_layer(d); - shutdown_my_hardware(); - } - -As shown above, low level drivers can be simplified a lot by using -devres. Complexity is shifted from less maintained low level drivers -to better maintained higher layer. Also, as init failure path is -shared with exit path, both can get more testing. - -Note though that when converting current calls or assignments to -managed devm_* versions it is up to you to check if internal operations -like allocating memory, have failed. Managed resources pertains to the -freeing of these resources *only* - all other checks needed are still -on you. In some cases this may mean introducing checks that were not -necessary before moving to the managed devm_* calls. - - -3. Devres group ---------------- - -Devres entries can be grouped using devres group. When a group is -released, all contained normal devres entries and properly nested -groups are released. One usage is to rollback series of acquired -resources on failure. For example:: - - if (!devres_open_group(dev, NULL, GFP_KERNEL)) - return -ENOMEM; - - acquire A; - if (failed) - goto err; - - acquire B; - if (failed) - goto err; - ... - - devres_remove_group(dev, NULL); - return 0; - - err: - devres_release_group(dev, NULL); - return err_code; - -As resource acquisition failure usually means probe failure, constructs -like above are usually useful in midlayer driver (e.g. libata core -layer) where interface function shouldn't have side effect on failure. -For LLDs, just returning error code suffices in most cases. - -Each group is identified by `void *id`. It can either be explicitly -specified by @id argument to devres_open_group() or automatically -created by passing NULL as @id as in the above example. In both -cases, devres_open_group() returns the group's id. The returned id -can be passed to other devres functions to select the target group. -If NULL is given to those functions, the latest open group is -selected. - -For example, you can do something like the following:: - - int my_midlayer_create_something() - { - if (!devres_open_group(dev, my_midlayer_create_something, GFP_KERNEL)) - return -ENOMEM; - - ... - - devres_close_group(dev, my_midlayer_create_something); - return 0; - } - - void my_midlayer_destroy_something() - { - devres_release_group(dev, my_midlayer_create_something); - } - - -4. Details ----------- - -Lifetime of a devres entry begins on devres allocation and finishes -when it is released or destroyed (removed and freed) - no reference -counting. - -devres core guarantees atomicity to all basic devres operations and -has support for single-instance devres types (atomic -lookup-and-add-if-not-found). Other than that, synchronizing -concurrent accesses to allocated devres data is caller's -responsibility. This is usually non-issue because bus ops and -resource allocations already do the job. - -For an example of single-instance devres type, read pcim_iomap_table() -in lib/devres.c. - -All devres interface functions can be called without context if the -right gfp mask is given. - - -5. Overhead ------------ - -Each devres bookkeeping info is allocated together with requested data -area. With debug option turned off, bookkeeping info occupies 16 -bytes on 32bit machines and 24 bytes on 64bit (three pointers rounded -up to ull alignment). If singly linked list is used, it can be -reduced to two pointers (8 bytes on 32bit, 16 bytes on 64bit). - -Each devres group occupies 8 pointers. It can be reduced to 6 if -singly linked list is used. - -Memory space overhead on ahci controller with two ports is between 300 -and 400 bytes on 32bit machine after naive conversion (we can -certainly invest a bit more effort into libata core layer). - - -6. List of managed interfaces ------------------------------ - -CLOCK - devm_clk_get() - devm_clk_get_optional() - devm_clk_put() - devm_clk_hw_register() - devm_of_clk_add_hw_provider() - devm_clk_hw_register_clkdev() - -DMA - dmaenginem_async_device_register() - dmam_alloc_coherent() - dmam_alloc_attrs() - dmam_free_coherent() - dmam_pool_create() - dmam_pool_destroy() - -DRM - devm_drm_dev_init() - -GPIO - devm_gpiod_get() - devm_gpiod_get_index() - devm_gpiod_get_index_optional() - devm_gpiod_get_optional() - devm_gpiod_put() - devm_gpiod_unhinge() - devm_gpiochip_add_data() - devm_gpio_request() - devm_gpio_request_one() - devm_gpio_free() - -I2C - devm_i2c_new_dummy_device() - -IIO - devm_iio_device_alloc() - devm_iio_device_free() - devm_iio_device_register() - devm_iio_device_unregister() - devm_iio_kfifo_allocate() - devm_iio_kfifo_free() - devm_iio_triggered_buffer_setup() - devm_iio_triggered_buffer_cleanup() - devm_iio_trigger_alloc() - devm_iio_trigger_free() - devm_iio_trigger_register() - devm_iio_trigger_unregister() - devm_iio_channel_get() - devm_iio_channel_release() - devm_iio_channel_get_all() - devm_iio_channel_release_all() - -INPUT - devm_input_allocate_device() - -IO region - devm_release_mem_region() - devm_release_region() - devm_release_resource() - devm_request_mem_region() - devm_request_region() - devm_request_resource() - -IOMAP - devm_ioport_map() - devm_ioport_unmap() - devm_ioremap() - devm_ioremap_nocache() - devm_ioremap_wc() - devm_ioremap_resource() : checks resource, requests memory region, ioremaps - devm_iounmap() - pcim_iomap() - pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_table() : array of mapped addresses indexed by BAR - pcim_iounmap() - -IRQ - devm_free_irq() - devm_request_any_context_irq() - devm_request_irq() - devm_request_threaded_irq() - devm_irq_alloc_descs() - devm_irq_alloc_desc() - devm_irq_alloc_desc_at() - devm_irq_alloc_desc_from() - devm_irq_alloc_descs_from() - devm_irq_alloc_generic_chip() - devm_irq_setup_generic_chip() - devm_irq_sim_init() - -LED - devm_led_classdev_register() - devm_led_classdev_unregister() - -MDIO - devm_mdiobus_alloc() - devm_mdiobus_alloc_size() - devm_mdiobus_free() - -MEM - devm_free_pages() - devm_get_free_pages() - devm_kasprintf() - devm_kcalloc() - devm_kfree() - devm_kmalloc() - devm_kmalloc_array() - devm_kmemdup() - devm_kstrdup() - devm_kvasprintf() - devm_kzalloc() - -MFD - devm_mfd_add_devices() - -MUX - devm_mux_chip_alloc() - devm_mux_chip_register() - devm_mux_control_get() - -PER-CPU MEM - devm_alloc_percpu() - devm_free_percpu() - -PCI - devm_pci_alloc_host_bridge() : managed PCI host bridge allocation - devm_pci_remap_cfgspace() : ioremap PCI configuration space - devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource - pcim_enable_device() : after success, all PCI ops become managed - pcim_pin_device() : keep PCI device enabled after release - -PHY - devm_usb_get_phy() - devm_usb_put_phy() - -PINCTRL - devm_pinctrl_get() - devm_pinctrl_put() - devm_pinctrl_register() - devm_pinctrl_unregister() - -POWER - devm_reboot_mode_register() - devm_reboot_mode_unregister() - -PWM - devm_pwm_get() - devm_pwm_put() - -REGULATOR - devm_regulator_bulk_get() - devm_regulator_get() - devm_regulator_put() - devm_regulator_register() - -RESET - devm_reset_control_get() - devm_reset_controller_register() - -SERDEV - devm_serdev_device_open() - -SLAVE DMA ENGINE - devm_acpi_dma_controller_register() - -SPI - devm_spi_register_master() - -WATCHDOG - devm_watchdog_register_device() diff --git a/Documentation/driver-model/driver.rst b/Documentation/driver-model/driver.rst deleted file mode 100644 index 11d281506a04..000000000000 --- a/Documentation/driver-model/driver.rst +++ /dev/null @@ -1,223 +0,0 @@ -============== -Device Drivers -============== - -See the kerneldoc for the struct device_driver. - - -Allocation -~~~~~~~~~~ - -Device drivers are statically allocated structures. Though there may -be multiple devices in a system that a driver supports, struct -device_driver represents the driver as a whole (not a particular -device instance). - -Initialization -~~~~~~~~~~~~~~ - -The driver must initialize at least the name and bus fields. It should -also initialize the devclass field (when it arrives), so it may obtain -the proper linkage internally. It should also initialize as many of -the callbacks as possible, though each is optional. - -Declaration -~~~~~~~~~~~ - -As stated above, struct device_driver objects are statically -allocated. Below is an example declaration of the eepro100 -driver. This declaration is hypothetical only; it relies on the driver -being converted completely to the new model:: - - static struct device_driver eepro100_driver = { - .name = "eepro100", - .bus = &pci_bus_type, - - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, - }; - -Most drivers will not be able to be converted completely to the new -model because the bus they belong to has a bus-specific structure with -bus-specific fields that cannot be generalized. - -The most common example of this are device ID structures. A driver -typically defines an array of device IDs that it supports. The format -of these structures and the semantics for comparing device IDs are -completely bus-specific. Defining them as bus-specific entities would -sacrifice type-safety, so we keep bus-specific structures around. - -Bus-specific drivers should include a generic struct device_driver in -the definition of the bus-specific driver. Like this:: - - struct pci_driver { - const struct pci_device_id *id_table; - struct device_driver driver; - }; - -A definition that included bus-specific fields would look like -(using the eepro100 driver again):: - - static struct pci_driver eepro100_driver = { - .id_table = eepro100_pci_tbl, - .driver = { - .name = "eepro100", - .bus = &pci_bus_type, - .probe = eepro100_probe, - .remove = eepro100_remove, - .suspend = eepro100_suspend, - .resume = eepro100_resume, - }, - }; - -Some may find the syntax of embedded struct initialization awkward or -even a bit ugly. So far, it's the best way we've found to do what we want... - -Registration -~~~~~~~~~~~~ - -:: - - int driver_register(struct device_driver *drv); - -The driver registers the structure on startup. For drivers that have -no bus-specific fields (i.e. don't have a bus-specific driver -structure), they would use driver_register and pass a pointer to their -struct device_driver object. - -Most drivers, however, will have a bus-specific structure and will -need to register with the bus using something like pci_driver_register. - -It is important that drivers register their driver structure as early as -possible. Registration with the core initializes several fields in the -struct device_driver object, including the reference count and the -lock. These fields are assumed to be valid at all times and may be -used by the device model core or the bus driver. - - -Transition Bus Drivers -~~~~~~~~~~~~~~~~~~~~~~ - -By defining wrapper functions, the transition to the new model can be -made easier. Drivers can ignore the generic structure altogether and -let the bus wrapper fill in the fields. For the callbacks, the bus can -define generic callbacks that forward the call to the bus-specific -callbacks of the drivers. - -This solution is intended to be only temporary. In order to get class -information in the driver, the drivers must be modified anyway. Since -converting drivers to the new model should reduce some infrastructural -complexity and code size, it is recommended that they are converted as -class information is added. - -Access -~~~~~~ - -Once the object has been registered, it may access the common fields of -the object, like the lock and the list of devices:: - - int driver_for_each_dev(struct device_driver *drv, void *data, - int (*callback)(struct device *dev, void *data)); - -The devices field is a list of all the devices that have been bound to -the driver. The LDM core provides a helper function to operate on all -the devices a driver controls. This helper locks the driver on each -node access, and does proper reference counting on each device as it -accesses it. - - -sysfs -~~~~~ - -When a driver is registered, a sysfs directory is created in its -bus's directory. In this directory, the driver can export an interface -to userspace to control operation of the driver on a global basis; -e.g. toggling debugging output in the driver. - -A future feature of this directory will be a 'devices' directory. This -directory will contain symlinks to the directories of devices it -supports. - - - -Callbacks -~~~~~~~~~ - -:: - - int (*probe) (struct device *dev); - -The probe() entry is called in task context, with the bus's rwsem locked -and the driver partially bound to the device. Drivers commonly use -container_of() to convert "dev" to a bus-specific type, both in probe() -and other routines. That type often provides device resource data, such -as pci_dev.resource[] or platform_device.resources, which is used in -addition to dev->platform_data to initialize the driver. - -This callback holds the driver-specific logic to bind the driver to a -given device. That includes verifying that the device is present, that -it's a version the driver can handle, that driver data structures can -be allocated and initialized, and that any hardware can be initialized. -Drivers often store a pointer to their state with dev_set_drvdata(). -When the driver has successfully bound itself to that device, then probe() -returns zero and the driver model code will finish its part of binding -the driver to that device. - -A driver's probe() may return a negative errno value to indicate that -the driver did not bind to this device, in which case it should have -released all resources it allocated:: - - int (*remove) (struct device *dev); - -remove is called to unbind a driver from a device. This may be -called if a device is physically removed from the system, if the -driver module is being unloaded, during a reboot sequence, or -in other cases. - -It is up to the driver to determine if the device is present or -not. It should free any resources allocated specifically for the -device; i.e. anything in the device's driver_data field. - -If the device is still present, it should quiesce the device and place -it into a supported low-power state:: - - int (*suspend) (struct device *dev, pm_message_t state); - -suspend is called to put the device in a low power state:: - - int (*resume) (struct device *dev); - -Resume is used to bring a device back from a low power state. - - -Attributes -~~~~~~~~~~ - -:: - - struct driver_attribute { - struct attribute attr; - ssize_t (*show)(struct device_driver *driver, char *buf); - ssize_t (*store)(struct device_driver *, const char *buf, size_t count); - }; - -Device drivers can export attributes via their sysfs directories. -Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO -macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO -macros. - -Example:: - - DRIVER_ATTR_RW(debug); - -This is equivalent to declaring:: - - struct driver_attribute driver_attr_debug; - -This can then be used to add and remove the attribute from the -driver's directory using:: - - int driver_create_file(struct device_driver *, const struct driver_attribute *); - void driver_remove_file(struct device_driver *, const struct driver_attribute *); diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst deleted file mode 100644 index 9f85d579ce56..000000000000 --- a/Documentation/driver-model/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -:orphan: - -============ -Driver Model -============ - -.. toctree:: - :maxdepth: 1 - - binding - bus - class - design-patterns - device - devres - driver - overview - platform - porting - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/driver-model/overview.rst b/Documentation/driver-model/overview.rst deleted file mode 100644 index d4d1e9b40e0c..000000000000 --- a/Documentation/driver-model/overview.rst +++ /dev/null @@ -1,124 +0,0 @@ -============================= -The Linux Kernel Device Model -============================= - -Patrick Mochel - -Drafted 26 August 2002 -Updated 31 January 2006 - - -Overview -~~~~~~~~ - -The Linux Kernel Driver Model is a unification of all the disparate driver -models that were previously used in the kernel. It is intended to augment the -bus-specific drivers for bridges and devices by consolidating a set of data -and operations into globally accessible data structures. - -Traditional driver models implemented some sort of tree-like structure -(sometimes just a list) for the devices they control. There wasn't any -uniformity across the different bus types. - -The current driver model provides a common, uniform data model for describing -a bus and the devices that can appear under the bus. The unified bus -model includes a set of common attributes which all busses carry, and a set -of common callbacks, such as device discovery during bus probing, bus -shutdown, bus power management, etc. - -The common device and bridge interface reflects the goals of the modern -computer: namely the ability to do seamless device "plug and play", power -management, and hot plug. In particular, the model dictated by Intel and -Microsoft (namely ACPI) ensures that almost every device on almost any bus -on an x86-compatible system can work within this paradigm. Of course, -not every bus is able to support all such operations, although most -buses support most of those operations. - - -Downstream Access -~~~~~~~~~~~~~~~~~ - -Common data fields have been moved out of individual bus layers into a common -data structure. These fields must still be accessed by the bus layers, -and sometimes by the device-specific drivers. - -Other bus layers are encouraged to do what has been done for the PCI layer. -struct pci_dev now looks like this:: - - struct pci_dev { - ... - - struct device dev; /* Generic device interface */ - ... - }; - -Note first that the struct device dev within the struct pci_dev is -statically allocated. This means only one allocation on device discovery. - -Note also that that struct device dev is not necessarily defined at the -front of the pci_dev structure. This is to make people think about what -they're doing when switching between the bus driver and the global driver, -and to discourage meaningless and incorrect casts between the two. - -The PCI bus layer freely accesses the fields of struct device. It knows about -the structure of struct pci_dev, and it should know the structure of struct -device. Individual PCI device drivers that have been converted to the current -driver model generally do not and should not touch the fields of struct device, -unless there is a compelling reason to do so. - -The above abstraction prevents unnecessary pain during transitional phases. -If it were not done this way, then when a field was renamed or removed, every -downstream driver would break. On the other hand, if only the bus layer -(and not the device layer) accesses the struct device, it is only the bus -layer that needs to change. - - -User Interface -~~~~~~~~~~~~~~ - -By virtue of having a complete hierarchical view of all the devices in the -system, exporting a complete hierarchical view to userspace becomes relatively -easy. This has been accomplished by implementing a special purpose virtual -file system named sysfs. - -Almost all mainstream Linux distros mount this filesystem automatically; you -can see some variation of the following in the output of the "mount" command:: - - $ mount - ... - none on /sys type sysfs (rw,noexec,nosuid,nodev) - ... - $ - -The auto-mounting of sysfs is typically accomplished by an entry similar to -the following in the /etc/fstab file:: - - none /sys sysfs defaults 0 0 - -or something similar in the /lib/init/fstab file on Debian-based systems:: - - none /sys sysfs nodev,noexec,nosuid 0 0 - -If sysfs is not automatically mounted, you can always do it manually with:: - - # mount -t sysfs sysfs /sys - -Whenever a device is inserted into the tree, a directory is created for it. -This directory may be populated at each layer of discovery - the global layer, -the bus layer, or the device layer. - -The global layer currently creates two files - 'name' and 'power'. The -former only reports the name of the device. The latter reports the -current power state of the device. It will also be used to set the current -power state. - -The bus layer may also create files for the devices it finds while probing the -bus. For example, the PCI layer currently creates 'irq' and 'resource' files -for each PCI device. - -A device-specific driver may also export files in its directory to expose -device-specific data or tunable interfaces. - -More information about the sysfs directory layout can be found in -the other documents in this directory and in the file -Documentation/filesystems/sysfs.txt. diff --git a/Documentation/driver-model/platform.rst b/Documentation/driver-model/platform.rst deleted file mode 100644 index 334dd4071ae4..000000000000 --- a/Documentation/driver-model/platform.rst +++ /dev/null @@ -1,246 +0,0 @@ -============================ -Platform Devices and Drivers -============================ - -See for the driver model interface to the -platform bus: platform_device, and platform_driver. This pseudo-bus -is used to connect devices on busses with minimal infrastructure, -like those used to integrate peripherals on many system-on-chip -processors, or some "legacy" PC interconnects; as opposed to large -formally specified ones like PCI or USB. - - -Platform devices -~~~~~~~~~~~~~~~~ -Platform devices are devices that typically appear as autonomous -entities in the system. This includes legacy port-based devices and -host bridges to peripheral buses, and most controllers integrated -into system-on-chip platforms. What they usually have in common -is direct addressing from a CPU bus. Rarely, a platform_device will -be connected through a segment of some other kind of bus; but its -registers will still be directly addressable. - -Platform devices are given a name, used in driver binding, and a -list of resources such as addresses and IRQs:: - - struct platform_device { - const char *name; - u32 id; - struct device dev; - u32 num_resources; - struct resource *resource; - }; - - -Platform drivers -~~~~~~~~~~~~~~~~ -Platform drivers follow the standard driver model convention, where -discovery/enumeration is handled outside the drivers, and drivers -provide probe() and remove() methods. They support power management -and shutdown notifications using the standard conventions:: - - struct platform_driver { - int (*probe)(struct platform_device *); - int (*remove)(struct platform_device *); - void (*shutdown)(struct platform_device *); - int (*suspend)(struct platform_device *, pm_message_t state); - int (*suspend_late)(struct platform_device *, pm_message_t state); - int (*resume_early)(struct platform_device *); - int (*resume)(struct platform_device *); - struct device_driver driver; - }; - -Note that probe() should in general verify that the specified device hardware -actually exists; sometimes platform setup code can't be sure. The probing -can use device resources, including clocks, and device platform_data. - -Platform drivers register themselves the normal way:: - - int platform_driver_register(struct platform_driver *drv); - -Or, in common situations where the device is known not to be hot-pluggable, -the probe() routine can live in an init section to reduce the driver's -runtime memory footprint:: - - int platform_driver_probe(struct platform_driver *drv, - int (*probe)(struct platform_device *)) - -Kernel modules can be composed of several platform drivers. The platform core -provides helpers to register and unregister an array of drivers:: - - int __platform_register_drivers(struct platform_driver * const *drivers, - unsigned int count, struct module *owner); - void platform_unregister_drivers(struct platform_driver * const *drivers, - unsigned int count); - -If one of the drivers fails to register, all drivers registered up to that -point will be unregistered in reverse order. Note that there is a convenience -macro that passes THIS_MODULE as owner parameter:: - - #define platform_register_drivers(drivers, count) - - -Device Enumeration -~~~~~~~~~~~~~~~~~~ -As a rule, platform specific (and often board-specific) setup code will -register platform devices:: - - int platform_device_register(struct platform_device *pdev); - - int platform_add_devices(struct platform_device **pdevs, int ndev); - -The general rule is to register only those devices that actually exist, -but in some cases extra devices might be registered. For example, a kernel -might be configured to work with an external network adapter that might not -be populated on all boards, or likewise to work with an integrated controller -that some boards might not hook up to any peripherals. - -In some cases, boot firmware will export tables describing the devices -that are populated on a given board. Without such tables, often the -only way for system setup code to set up the correct devices is to build -a kernel for a specific target board. Such board-specific kernels are -common with embedded and custom systems development. - -In many cases, the memory and IRQ resources associated with the platform -device are not enough to let the device's driver work. Board setup code -will often provide additional information using the device's platform_data -field to hold additional information. - -Embedded systems frequently need one or more clocks for platform devices, -which are normally kept off until they're actively needed (to save power). -System setup also associates those clocks with the device, so that that -calls to clk_get(&pdev->dev, clock_name) return them as needed. - - -Legacy Drivers: Device Probing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some drivers are not fully converted to the driver model, because they take -on a non-driver role: the driver registers its platform device, rather than -leaving that for system infrastructure. Such drivers can't be hotplugged -or coldplugged, since those mechanisms require device creation to be in a -different system component than the driver. - -The only "good" reason for this is to handle older system designs which, like -original IBM PCs, rely on error-prone "probe-the-hardware" models for hardware -configuration. Newer systems have largely abandoned that model, in favor of -bus-level support for dynamic configuration (PCI, USB), or device tables -provided by the boot firmware (e.g. PNPACPI on x86). There are too many -conflicting options about what might be where, and even educated guesses by -an operating system will be wrong often enough to make trouble. - -This style of driver is discouraged. If you're updating such a driver, -please try to move the device enumeration to a more appropriate location, -outside the driver. This will usually be cleanup, since such drivers -tend to already have "normal" modes, such as ones using device nodes that -were created by PNP or by platform device setup. - -None the less, there are some APIs to support such legacy drivers. Avoid -using these calls except with such hotplug-deficient drivers:: - - struct platform_device *platform_device_alloc( - const char *name, int id); - -You can use platform_device_alloc() to dynamically allocate a device, which -you will then initialize with resources and platform_device_register(). -A better solution is usually:: - - struct platform_device *platform_device_register_simple( - const char *name, int id, - struct resource *res, unsigned int nres); - -You can use platform_device_register_simple() as a one-step call to allocate -and register a device. - - -Device Naming and Driver Binding -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The platform_device.dev.bus_id is the canonical name for the devices. -It's built from two components: - - * platform_device.name ... which is also used to for driver matching. - - * platform_device.id ... the device instance number, or else "-1" - to indicate there's only one. - -These are concatenated, so name/id "serial"/0 indicates bus_id "serial.0", and -"serial/3" indicates bus_id "serial.3"; both would use the platform_driver -named "serial". While "my_rtc"/-1 would be bus_id "my_rtc" (no instance id) -and use the platform_driver called "my_rtc". - -Driver binding is performed automatically by the driver core, invoking -driver probe() after finding a match between device and driver. If the -probe() succeeds, the driver and device are bound as usual. There are -three different ways to find such a match: - - - Whenever a device is registered, the drivers for that bus are - checked for matches. Platform devices should be registered very - early during system boot. - - - When a driver is registered using platform_driver_register(), all - unbound devices on that bus are checked for matches. Drivers - usually register later during booting, or by module loading. - - - Registering a driver using platform_driver_probe() works just like - using platform_driver_register(), except that the driver won't - be probed later if another device registers. (Which is OK, since - this interface is only for use with non-hotpluggable devices.) - - -Early Platform Devices and Drivers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The early platform interfaces provide platform data to platform device -drivers early on during the system boot. The code is built on top of the -early_param() command line parsing and can be executed very early on. - -Example: "earlyprintk" class early serial console in 6 steps - -1. Registering early platform device data -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code registers platform device data using the function -early_platform_add_devices(). In the case of early serial console this -should be hardware configuration for the serial port. Devices registered -at this point will later on be matched against early platform drivers. - -2. Parsing kernel command line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls parse_early_param() to parse the kernel -command line. This will execute all matching early_param() callbacks. -User specified early platform devices will be registered at this point. -For the early serial console case the user can specify port on the -kernel command line as "earlyprintk=serial.0" where "earlyprintk" is -the class string, "serial" is the name of the platform driver and -0 is the platform device id. If the id is -1 then the dot and the -id can be omitted. - -3. Installing early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code may optionally force registration of all early -platform drivers belonging to a certain class using the function -early_platform_driver_register_all(). User specified devices from -step 2 have priority over these. This step is omitted by the serial -driver example since the early serial driver code should be disabled -unless the user has specified port on the kernel command line. - -4. Early platform driver registration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Compiled-in platform drivers making use of early_platform_init() are -automatically registered during step 2 or 3. The serial driver example -should use early_platform_init("earlyprintk", &platform_driver). - -5. Probing of early platform drivers belonging to a certain class -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The architecture code calls early_platform_driver_probe() to match -registered early platform devices associated with a certain class with -registered early platform drivers. Matched devices will get probed(). -This step can be executed at any point during the early boot. As soon -as possible may be good for the serial port case. - -6. Inside the early platform driver probe() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The driver code needs to take special care during early boot, especially -when it comes to memory allocation and interrupt registration. The code -in the probe() function can use is_early_platform_device() to check if -it is called at early platform device or at the regular platform device -time. The early serial driver performs register_console() at this point. - -For further information, see . diff --git a/Documentation/driver-model/porting.rst b/Documentation/driver-model/porting.rst deleted file mode 100644 index ae4bf843c1d6..000000000000 --- a/Documentation/driver-model/porting.rst +++ /dev/null @@ -1,448 +0,0 @@ -======================================= -Porting Drivers to the New Driver Model -======================================= - -Patrick Mochel - -7 January 2003 - - -Overview - -Please refer to `Documentation/driver-model/*.rst` for definitions of -various driver types and concepts. - -Most of the work of porting devices drivers to the new model happens -at the bus driver layer. This was intentional, to minimize the -negative effect on kernel drivers, and to allow a gradual transition -of bus drivers. - -In a nutshell, the driver model consists of a set of objects that can -be embedded in larger, bus-specific objects. Fields in these generic -objects can replace fields in the bus-specific objects. - -The generic objects must be registered with the driver model core. By -doing so, they will exported via the sysfs filesystem. sysfs can be -mounted by doing:: - - # mount -t sysfs sysfs /sys - - - -The Process - -Step 0: Read include/linux/device.h for object and function definitions. - -Step 1: Registering the bus driver. - - -- Define a struct bus_type for the bus driver:: - - struct bus_type pci_bus_type = { - .name = "pci", - }; - - -- Register the bus type. - - This should be done in the initialization function for the bus type, - which is usually the module_init(), or equivalent, function:: - - static int __init pci_driver_init(void) - { - return bus_register(&pci_bus_type); - } - - subsys_initcall(pci_driver_init); - - - The bus type may be unregistered (if the bus driver may be compiled - as a module) by doing:: - - bus_unregister(&pci_bus_type); - - -- Export the bus type for others to use. - - Other code may wish to reference the bus type, so declare it in a - shared header file and export the symbol. - -From include/linux/pci.h:: - - extern struct bus_type pci_bus_type; - - -From file the above code appears in:: - - EXPORT_SYMBOL(pci_bus_type); - - - -- This will cause the bus to show up in /sys/bus/pci/ with two - subdirectories: 'devices' and 'drivers':: - - # tree -d /sys/bus/pci/ - /sys/bus/pci/ - |-- devices - `-- drivers - - - -Step 2: Registering Devices. - -struct device represents a single device. It mainly contains metadata -describing the relationship the device has to other entities. - - -- Embed a struct device in the bus-specific device type:: - - - struct pci_dev { - ... - struct device dev; /* Generic device interface */ - ... - }; - - It is recommended that the generic device not be the first item in - the struct to discourage programmers from doing mindless casts - between the object types. Instead macros, or inline functions, - should be created to convert from the generic object type:: - - - #define to_pci_dev(n) container_of(n, struct pci_dev, dev) - - or - - static inline struct pci_dev * to_pci_dev(struct kobject * kobj) - { - return container_of(n, struct pci_dev, dev); - } - - This allows the compiler to verify type-safety of the operations - that are performed (which is Good). - - -- Initialize the device on registration. - - When devices are discovered or registered with the bus type, the - bus driver should initialize the generic device. The most important - things to initialize are the bus_id, parent, and bus fields. - - The bus_id is an ASCII string that contains the device's address on - the bus. The format of this string is bus-specific. This is - necessary for representing devices in sysfs. - - parent is the physical parent of the device. It is important that - the bus driver sets this field correctly. - - The driver model maintains an ordered list of devices that it uses - for power management. This list must be in order to guarantee that - devices are shutdown before their physical parents, and vice versa. - The order of this list is determined by the parent of registered - devices. - - Also, the location of the device's sysfs directory depends on a - device's parent. sysfs exports a directory structure that mirrors - the device hierarchy. Accurately setting the parent guarantees that - sysfs will accurately represent the hierarchy. - - The device's bus field is a pointer to the bus type the device - belongs to. This should be set to the bus_type that was declared - and initialized before. - - Optionally, the bus driver may set the device's name and release - fields. - - The name field is an ASCII string describing the device, like - - "ATI Technologies Inc Radeon QD" - - The release field is a callback that the driver model core calls - when the device has been removed, and all references to it have - been released. More on this in a moment. - - -- Register the device. - - Once the generic device has been initialized, it can be registered - with the driver model core by doing:: - - device_register(&dev->dev); - - It can later be unregistered by doing:: - - device_unregister(&dev->dev); - - This should happen on buses that support hotpluggable devices. - If a bus driver unregisters a device, it should not immediately free - it. It should instead wait for the driver model core to call the - device's release method, then free the bus-specific object. - (There may be other code that is currently referencing the device - structure, and it would be rude to free the device while that is - happening). - - - When the device is registered, a directory in sysfs is created. - The PCI tree in sysfs looks like:: - - /sys/devices/pci0/ - |-- 00:00.0 - |-- 00:01.0 - | `-- 01:00.0 - |-- 00:02.0 - | `-- 02:1f.0 - | `-- 03:00.0 - |-- 00:1e.0 - | `-- 04:04.0 - |-- 00:1f.0 - |-- 00:1f.1 - | |-- ide0 - | | |-- 0.0 - | | `-- 0.1 - | `-- ide1 - | `-- 1.0 - |-- 00:1f.2 - |-- 00:1f.3 - `-- 00:1f.5 - - Also, symlinks are created in the bus's 'devices' directory - that point to the device's directory in the physical hierarchy:: - - /sys/bus/pci/devices/ - |-- 00:00.0 -> ../../../devices/pci0/00:00.0 - |-- 00:01.0 -> ../../../devices/pci0/00:01.0 - |-- 00:02.0 -> ../../../devices/pci0/00:02.0 - |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0 - |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0 - |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1 - |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2 - |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3 - |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5 - |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0 - |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0 - |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0 - `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0 - - - -Step 3: Registering Drivers. - -struct device_driver is a simple driver structure that contains a set -of operations that the driver model core may call. - - -- Embed a struct device_driver in the bus-specific driver. - - Just like with devices, do something like:: - - struct pci_driver { - ... - struct device_driver driver; - }; - - -- Initialize the generic driver structure. - - When the driver registers with the bus (e.g. doing pci_register_driver()), - initialize the necessary fields of the driver: the name and bus - fields. - - -- Register the driver. - - After the generic driver has been initialized, call:: - - driver_register(&drv->driver); - - to register the driver with the core. - - When the driver is unregistered from the bus, unregister it from the - core by doing:: - - driver_unregister(&drv->driver); - - Note that this will block until all references to the driver have - gone away. Normally, there will not be any. - - -- Sysfs representation. - - Drivers are exported via sysfs in their bus's 'driver's directory. - For example:: - - /sys/bus/pci/drivers/ - |-- 3c59x - |-- Ensoniq AudioPCI - |-- agpgart-amdk7 - |-- e100 - `-- serial - - -Step 4: Define Generic Methods for Drivers. - -struct device_driver defines a set of operations that the driver model -core calls. Most of these operations are probably similar to -operations the bus already defines for drivers, but taking different -parameters. - -It would be difficult and tedious to force every driver on a bus to -simultaneously convert their drivers to generic format. Instead, the -bus driver should define single instances of the generic methods that -forward call to the bus-specific drivers. For instance:: - - - static int pci_device_remove(struct device * dev) - { - struct pci_dev * pci_dev = to_pci_dev(dev); - struct pci_driver * drv = pci_dev->driver; - - if (drv) { - if (drv->remove) - drv->remove(pci_dev); - pci_dev->driver = NULL; - } - return 0; - } - - -The generic driver should be initialized with these methods before it -is registered:: - - /* initialize common driver fields */ - drv->driver.name = drv->name; - drv->driver.bus = &pci_bus_type; - drv->driver.probe = pci_device_probe; - drv->driver.resume = pci_device_resume; - drv->driver.suspend = pci_device_suspend; - drv->driver.remove = pci_device_remove; - - /* register with core */ - driver_register(&drv->driver); - - -Ideally, the bus should only initialize the fields if they are not -already set. This allows the drivers to implement their own generic -methods. - - -Step 5: Support generic driver binding. - -The model assumes that a device or driver can be dynamically -registered with the bus at any time. When registration happens, -devices must be bound to a driver, or drivers must be bound to all -devices that it supports. - -A driver typically contains a list of device IDs that it supports. The -bus driver compares these IDs to the IDs of devices registered with it. -The format of the device IDs, and the semantics for comparing them are -bus-specific, so the generic model does attempt to generalize them. - -Instead, a bus may supply a method in struct bus_type that does the -comparison:: - - int (*match)(struct device * dev, struct device_driver * drv); - -match should return positive value if the driver supports the device, -and zero otherwise. It may also return error code (for example --EPROBE_DEFER) if determining that given driver supports the device is -not possible. - -When a device is registered, the bus's list of drivers is iterated -over. bus->match() is called for each one until a match is found. - -When a driver is registered, the bus's list of devices is iterated -over. bus->match() is called for each device that is not already -claimed by a driver. - -When a device is successfully bound to a driver, device->driver is -set, the device is added to a per-driver list of devices, and a -symlink is created in the driver's sysfs directory that points to the -device's physical directory:: - - /sys/bus/pci/drivers/ - |-- 3c59x - | `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0 - |-- Ensoniq AudioPCI - |-- agpgart-amdk7 - | `-- 00:00.0 -> ../../../../devices/pci0/00:00.0 - |-- e100 - | `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0 - `-- serial - - -This driver binding should replace the existing driver binding -mechanism the bus currently uses. - - -Step 6: Supply a hotplug callback. - -Whenever a device is registered with the driver model core, the -userspace program /sbin/hotplug is called to notify userspace. -Users can define actions to perform when a device is inserted or -removed. - -The driver model core passes several arguments to userspace via -environment variables, including - -- ACTION: set to 'add' or 'remove' -- DEVPATH: set to the device's physical path in sysfs. - -A bus driver may also supply additional parameters for userspace to -consume. To do this, a bus must implement the 'hotplug' method in -struct bus_type:: - - int (*hotplug) (struct device *dev, char **envp, - int num_envp, char *buffer, int buffer_size); - -This is called immediately before /sbin/hotplug is executed. - - -Step 7: Cleaning up the bus driver. - -The generic bus, device, and driver structures provide several fields -that can replace those defined privately to the bus driver. - -- Device list. - -struct bus_type contains a list of all devices registered with the bus -type. This includes all devices on all instances of that bus type. -An internal list that the bus uses may be removed, in favor of using -this one. - -The core provides an iterator to access these devices:: - - int bus_for_each_dev(struct bus_type * bus, struct device * start, - void * data, int (*fn)(struct device *, void *)); - - -- Driver list. - -struct bus_type also contains a list of all drivers registered with -it. An internal list of drivers that the bus driver maintains may -be removed in favor of using the generic one. - -The drivers may be iterated over, like devices:: - - int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, - void * data, int (*fn)(struct device_driver *, void *)); - - -Please see drivers/base/bus.c for more information. - - -- rwsem - -struct bus_type contains an rwsem that protects all core accesses to -the device and driver lists. This can be used by the bus driver -internally, and should be used when accessing the device or driver -lists the bus maintains. - - -- Device and driver fields. - -Some of the fields in struct device and struct device_driver duplicate -fields in the bus-specific representations of these objects. Feel free -to remove the bus-specific ones and favor the generic ones. Note -though, that this will likely mean fixing up all the drivers that -reference the bus-specific fields (though those should all be 1-line -changes). diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt index f388545a85a7..c07565ba57da 100644 --- a/Documentation/eisa.txt +++ b/Documentation/eisa.txt @@ -103,7 +103,7 @@ id_table an array of NULL terminated EISA id strings, (driver_data). driver a generic driver, such as described in - Documentation/driver-model/driver.rst. Only .name, + Documentation/driver-api/driver-model/driver.rst. Only .name, .probe and .remove members are mandatory. =============== ==================================================== @@ -152,7 +152,7 @@ state set of flags indicating the state of the device. Current flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED. res set of four 256 bytes I/O regions allocated to this device dma_mask DMA mask set from the parent device. -dev generic device (see Documentation/driver-model/device.rst) +dev generic device (see Documentation/driver-api/driver-model/device.rst) ======== ============================================================ You can get the 'struct eisa_device' from 'struct device' using the diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 5b5311f9358d..ddf15b1b0d5a 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -319,7 +319,7 @@ quick way to lookup the sysfs interface for a device from the result of a stat(2) operation. More information can driver-model specific features can be found in -Documentation/driver-model/. +Documentation/driver-api/driver-model/. TODO: Finish this section. diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst index d5b05d3e54ba..452fc28d8e0b 100644 --- a/Documentation/hwmon/submitting-patches.rst +++ b/Documentation/hwmon/submitting-patches.rst @@ -89,7 +89,7 @@ increase the chances of your change being accepted. console. Excessive logging can seriously affect system performance. * Use devres functions whenever possible to allocate resources. For rationale - and supported functions, please see Documentation/driver-model/devres.rst. + and supported functions, please see Documentation/driver-api/driver-model/devres.rst. If a function is not supported by devres, consider using devm_add_action(). * If the driver has a detect function, make sure it is silent. Debug messages diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt index 452271dda141..ee1f37da5b23 100644 --- a/Documentation/translations/zh_CN/filesystems/sysfs.txt +++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt @@ -288,7 +288,7 @@ dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有 中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 设备 sysfs 接口快捷的方法。 -更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ +更多有关 driver-model 的特性信息可以在 Documentation/driver-api/driver-model/ 中找到。 diff --git a/drivers/base/platform.c b/drivers/base/platform.c index 713903290385..506a0175a5a7 100644 --- a/drivers/base/platform.c +++ b/drivers/base/platform.c @@ -5,7 +5,7 @@ * Copyright (c) 2002-3 Patrick Mochel * Copyright (c) 2002-3 Open Source Development Labs * - * Please see Documentation/driver-model/platform.rst for more + * Please see Documentation/driver-api/driver-model/platform.rst for more * information. */ diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c index 3611a0571667..53b24e3ae7de 100644 --- a/drivers/gpio/gpio-cs5535.c +++ b/drivers/gpio/gpio-cs5535.c @@ -41,7 +41,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask."); /* * FIXME: convert this singleton driver to use the state container - * design pattern, see Documentation/driver-model/design-patterns.rst + * design pattern, see Documentation/driver-api/driver-model/design-patterns.rst */ static struct cs5535_gpio_chip { struct gpio_chip chip; diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c index 41c90f2ddb31..63db08d9bafa 100644 --- a/drivers/net/ethernet/intel/ice/ice_main.c +++ b/drivers/net/ethernet/intel/ice/ice_main.c @@ -2286,7 +2286,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent) struct ice_hw *hw; int err; - /* this driver uses devres, see Documentation/driver-model/devres.rst */ + /* this driver uses devres, see Documentation/driver-api/driver-model/devres.rst */ err = pcim_enable_device(pdev); if (err) return err; diff --git a/drivers/staging/unisys/Documentation/overview.txt b/drivers/staging/unisys/Documentation/overview.txt index 9ab30af265a5..f8a4144b239c 100644 --- a/drivers/staging/unisys/Documentation/overview.txt +++ b/drivers/staging/unisys/Documentation/overview.txt @@ -15,7 +15,7 @@ normally be unsharable, specifically: * visorinput - keyboard and mouse These drivers conform to the standard Linux bus/device model described -within Documentation/driver-model/, and utilize a driver named visorbus to +within Documentation/driver-api/driver-model/, and utilize a driver named visorbus to present the virtual busses involved. Drivers in the 'visor*' driver set are commonly referred to as "guest drivers" or "client drivers". All drivers except visorbus expose a device of a specific usable class to the Linux guest @@ -141,7 +141,7 @@ called automatically by the visorbus driver at appropriate times: ----------------------------------- Because visorbus is a standard Linux bus driver in the model described in -Documentation/driver-model/, the hierarchy of s-Par virtual devices is +Documentation/driver-api/driver-model/, the hierarchy of s-Par virtual devices is published in the sysfs tree beneath /bus/visorbus/, e.g., /sys/bus/visorbus/devices/ might look like: diff --git a/include/linux/device.h b/include/linux/device.h index 5eabfa0c4dee..c330b75c6c57 100644 --- a/include/linux/device.h +++ b/include/linux/device.h @@ -6,7 +6,7 @@ * Copyright (c) 2004-2009 Greg Kroah-Hartman * Copyright (c) 2008-2009 Novell Inc. * - * See Documentation/driver-model/ for more information. + * See Documentation/driver-api/driver-model/ for more information. */ #ifndef _DEVICE_H_ diff --git a/include/linux/platform_device.h b/include/linux/platform_device.h index beb25f277889..9bc36b589827 100644 --- a/include/linux/platform_device.h +++ b/include/linux/platform_device.h @@ -4,7 +4,7 @@ * * Copyright (c) 2001-2003 Patrick Mochel * - * See Documentation/driver-model/ for more information. + * See Documentation/driver-api/driver-model/ for more information. */ #ifndef _PLATFORM_DEVICE_H_ diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci index fefd0331a2de..441799b5359b 100644 --- a/scripts/coccinelle/free/devm_free.cocci +++ b/scripts/coccinelle/free/devm_free.cocci @@ -3,7 +3,7 @@ /// functions. Values allocated using the devm_functions are freed when /// the device is detached, and thus the use of the standard freeing /// function would cause a double free. -/// See Documentation/driver-model/devres.rst for more information. +/// See Documentation/driver-api/driver-model/devres.rst for more information. /// /// A difficulty of detecting this problem is that the standard freeing /// function might be called from a different function than the one -- cgit v1.2.3 From 3266c806dc8692e079768ee2814498dcd6a91e61 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 5 Jun 2019 03:14:53 +0900 Subject: kconfig: run olddefconfig instead of oldconfig after merging fragments 'make olddefconfig' is non-interactive, so we can drop 'yes'. The behavior is equivalent. Signed-off-by: Masahiro Yamada --- scripts/kconfig/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kconfig/Makefile b/scripts/kconfig/Makefile index ab30fe724c43..7656e1137b6b 100644 --- a/scripts/kconfig/Makefile +++ b/scripts/kconfig/Makefile @@ -94,7 +94,7 @@ configfiles=$(wildcard $(srctree)/kernel/configs/$@ $(srctree)/arch/$(SRCARCH)/c %.config: $(obj)/conf $(if $(call configfiles),, $(error No configuration exists for this target on this architecture)) $(Q)$(CONFIG_SHELL) $(srctree)/scripts/kconfig/merge_config.sh -m .config $(configfiles) - +$(Q)yes "" | $(MAKE) -f $(srctree)/Makefile oldconfig + $(Q)$(MAKE) -f $(srctree)/Makefile olddefconfig PHONY += kvmconfig kvmconfig: kvm_guest.config -- cgit v1.2.3 From 5a46421789f46165416d2b4834647b153c231c55 Mon Sep 17 00:00:00 2001 From: Cedric Hombourger Date: Tue, 9 Jul 2019 09:43:35 +0200 Subject: builddeb: generate multi-arch friendly linux-libc-dev package Debian-based distributions place libc header files in a machine specific directory (/usr/include/) instead of /usr/include/asm to support installation of the linux-libc-dev package from multiple architectures. Move headers installed by "make headers_install" accordingly using Debian's tuple from dpkg-architecture (stored in debian/arch). Signed-off-by: Cedric Hombourger Signed-off-by: Masahiro Yamada --- scripts/package/builddeb | 5 +++++ scripts/package/mkdebian | 1 + 2 files changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/package/builddeb b/scripts/package/builddeb index e8ca6dc97e96..c4c580f547ef 100755 --- a/scripts/package/builddeb +++ b/scripts/package/builddeb @@ -132,6 +132,11 @@ fi if [ "$ARCH" != "um" ]; then $MAKE -f $srctree/Makefile headers $MAKE -f $srctree/Makefile headers_install INSTALL_HDR_PATH="$libc_headers_dir/usr" + # move asm headers to /usr/include//asm to match the structure + # used by Debian-based distros (to support multi-arch) + host_arch=$(dpkg-architecture -a$(cat debian/arch) -qDEB_HOST_MULTIARCH) + mkdir $libc_headers_dir/usr/include/$host_arch + mv $libc_headers_dir/usr/include/asm $libc_headers_dir/usr/include/$host_arch/ fi # Install the maintainer scripts diff --git a/scripts/package/mkdebian b/scripts/package/mkdebian index 8351584cb24e..e0750b70453f 100755 --- a/scripts/package/mkdebian +++ b/scripts/package/mkdebian @@ -197,6 +197,7 @@ Architecture: $debarch Description: Linux support headers for userspace development This package provides userspaces headers from the Linux kernel. These headers are used by the installed headers for GNU glibc and other system libraries. +Multi-Arch: same Package: $dbg_packagename Section: debug -- cgit v1.2.3 From 49662503e8e4df9db29bfc354112a9a6312d7a25 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Tue, 16 Jul 2019 16:27:09 -0700 Subject: get_maintainer: add ability to skip moderated mailing lists Add a command line switch --no-moderated to skip L: mailing lists marked with 'moderated'. Some people prefer not emailing moderated mailing lists as the moderation time can be indeterminate and some emails can be intentionally dropped by a moderator. This can cause fragmentation of email threads when some are subscribed to a moderated list but others are not and emails are dropped. Link: http://lkml.kernel.org/r/6f23c2918ad9fc744269feb8f909bdfb105c5afc.camel@perches.com Signed-off-by: Joe Perches Tested-by: Peter Zijlstra (Intel) Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/get_maintainer.pl | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/get_maintainer.pl b/scripts/get_maintainer.pl index c1c088ef1420..5ef59214c555 100755 --- a/scripts/get_maintainer.pl +++ b/scripts/get_maintainer.pl @@ -27,6 +27,7 @@ my $email_usename = 1; my $email_maintainer = 1; my $email_reviewer = 1; my $email_list = 1; +my $email_moderated_list = 1; my $email_subscriber_list = 0; my $email_git_penguin_chiefs = 0; my $email_git = 0; @@ -248,6 +249,7 @@ if (!GetOptions( 'r!' => \$email_reviewer, 'n!' => \$email_usename, 'l!' => \$email_list, + 'moderated!' => \$email_moderated_list, 's!' => \$email_subscriber_list, 'multiline!' => \$output_multiline, 'roles!' => \$output_roles, @@ -1023,7 +1025,8 @@ MAINTAINER field selection options: --r => include reviewer(s) if any --n => include name 'Full Name ' --l => include list(s) if any - --s => include subscriber only list(s) if any + --moderated => include moderated lists(s) if any (default: true) + --s => include subscriber only list(s) if any (default: false) --remove-duplicates => minimize duplicate email names/addresses --roles => show roles (status:subsystem, git-signer, list, etc...) --rolestats => show roles and statistics (commits/total_commits, %) @@ -1313,11 +1316,14 @@ sub add_categories { } else { if ($email_list) { if (!$hash_list_to{lc($list_address)}) { - $hash_list_to{lc($list_address)} = 1; if ($list_additional =~ m/moderated/) { - push(@list_to, [$list_address, - "moderated list${list_role}"]); + if ($email_moderated_list) { + $hash_list_to{lc($list_address)} = 1; + push(@list_to, [$list_address, + "moderated list${list_role}"]); + } } else { + $hash_list_to{lc($list_address)} = 1; push(@list_to, [$list_address, "open list${list_role}"]); } -- cgit v1.2.3 From 6a8d76cbd647d414248d314300106d1ce04daa4b Mon Sep 17 00:00:00 2001 From: Matteo Croce Date: Tue, 16 Jul 2019 16:27:48 -0700 Subject: checkpatch.pl: warn on duplicate sysctl local variable Commit d91bff3011cf ("proc/sysctl: add shared variables for range check") adds some shared const variables to be used instead of a local copy in each source file. Warn when a chunk duplicates one of these values in a ctl_table struct: $ scripts/checkpatch.pl 0001-test-commit.patch WARNING: duplicated sysctl range checking value 'zero', consider using the shared one in include/linux/sysctl.h #27: FILE: arch/arm/kernel/isa.c:48: + .extra1 = &zero, WARNING: duplicated sysctl range checking value 'int_max', consider using the shared one in include/linux/sysctl.h #28: FILE: arch/arm/kernel/isa.c:49: + .extra2 = &int_max, total: 0 errors, 2 warnings, 14 lines checked Link: http://lkml.kernel.org/r/20190531131422.14970-1-mcroce@redhat.com Signed-off-by: Matteo Croce Reviewed-by: Kees Cook Cc: Joe Perches Cc: Aaron Tomlin Cc: Matthew Wilcox Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/checkpatch.pl | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index a6d436809bf5..93a7edfe0f05 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -6639,6 +6639,12 @@ sub process { "unknown module license " . $extracted_string . "\n" . $herecurr); } } + +# check for sysctl duplicate constants + if ($line =~ /\.extra[12]\s*=\s*&(zero|one|int_max)\b/) { + WARN("DUPLICATED_SYSCTL_CONST", + "duplicated sysctl range checking value '$1', consider using the shared one in include/linux/sysctl.h\n" . $herecurr); + } } # If we have no input at all, then there is nothing to report on -- cgit v1.2.3 From 8207d4a88e1ef4ab54f05f2f18edd444a5099099 Mon Sep 17 00:00:00 2001 From: Leonard Crestez Date: Tue, 16 Jul 2019 16:30:12 -0700 Subject: scripts/gdb: add lx-genpd-summary command This is like /sys/kernel/debug/pm/pm_genpd_summary except it's accessible through a debugger. This can be useful if the target crashes or hangs because power domains were not properly enabled. Link: http://lkml.kernel.org/r/f9ee627a0d4f94b894aa202fee8a98444049bed8.1561492937.git.leonard.crestez@nxp.com Signed-off-by: Leonard Crestez Reviewed-by: Stephen Boyd Cc: Kieran Bingham Cc: Jan Kiszka Cc: "Rafael J. Wysocki" Cc: Greg Kroah-Hartman Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/gdb/linux/genpd.py | 83 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/gdb/vmlinux-gdb.py | 1 + 2 files changed, 84 insertions(+) create mode 100644 scripts/gdb/linux/genpd.py (limited to 'scripts') diff --git a/scripts/gdb/linux/genpd.py b/scripts/gdb/linux/genpd.py new file mode 100644 index 000000000000..6ca93bd2949e --- /dev/null +++ b/scripts/gdb/linux/genpd.py @@ -0,0 +1,83 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright (c) NXP 2019 + +import gdb +import sys + +from linux.utils import CachedType +from linux.lists import list_for_each_entry + +generic_pm_domain_type = CachedType('struct generic_pm_domain') +pm_domain_data_type = CachedType('struct pm_domain_data') +device_link_type = CachedType('struct device_link') + + +def kobject_get_path(kobj): + path = kobj['name'].string() + parent = kobj['parent'] + if parent: + path = kobject_get_path(parent) + '/' + path + return path + + +def rtpm_status_str(dev): + if dev['power']['runtime_error']: + return 'error' + if dev['power']['disable_depth']: + return 'unsupported' + _RPM_STATUS_LOOKUP = [ + "active", + "resuming", + "suspended", + "suspending" + ] + return _RPM_STATUS_LOOKUP[dev['power']['runtime_status']] + + +class LxGenPDSummary(gdb.Command): + '''Print genpd summary + +Output is similar to /sys/kernel/debug/pm_genpd/pm_genpd_summary''' + + def __init__(self): + super(LxGenPDSummary, self).__init__('lx-genpd-summary', gdb.COMMAND_DATA) + + def summary_one(self, genpd): + if genpd['status'] == 0: + status_string = 'on' + else: + status_string = 'off-{}'.format(genpd['state_idx']) + + slave_names = [] + for link in list_for_each_entry( + genpd['master_links'], + device_link_type.get_type().pointer(), + 'master_node'): + slave_names.apend(link['slave']['name']) + + gdb.write('%-30s %-15s %s\n' % ( + genpd['name'].string(), + status_string, + ', '.join(slave_names))) + + # Print devices in domain + for pm_data in list_for_each_entry(genpd['dev_list'], + pm_domain_data_type.get_type().pointer(), + 'list_node'): + dev = pm_data['dev'] + kobj_path = kobject_get_path(dev['kobj']) + gdb.write(' %-50s %s\n' % (kobj_path, rtpm_status_str(dev))) + + def invoke(self, arg, from_tty): + gdb.write('domain status slaves\n'); + gdb.write(' /device runtime status\n'); + gdb.write('----------------------------------------------------------------------\n'); + for genpd in list_for_each_entry( + gdb.parse_and_eval('&gpd_list'), + generic_pm_domain_type.get_type().pointer(), + 'gpd_list_node'): + self.summary_one(genpd) + + +LxGenPDSummary() diff --git a/scripts/gdb/vmlinux-gdb.py b/scripts/gdb/vmlinux-gdb.py index eff5a48ac026..a504f511e752 100644 --- a/scripts/gdb/vmlinux-gdb.py +++ b/scripts/gdb/vmlinux-gdb.py @@ -35,3 +35,4 @@ else: import linux.constants import linux.timerlist import linux.clk + import linux.genpd -- cgit v1.2.3 From 778c1f5ccbd95722cf84d2233c6acbf4d01a3ec7 Mon Sep 17 00:00:00 2001 From: Leonard Crestez Date: Tue, 16 Jul 2019 16:30:15 -0700 Subject: scripts/gdb: add helpers to find and list devices Add helper commands and functions for finding pointers to struct device by enumerating linux device bus/class infrastructure. This can be used to fetch subsystem and driver-specific structs: (gdb) p *$container_of($lx_device_find_by_class_name("net", "eth0"), "struct net_device", "dev") (gdb) p *$container_of($lx_device_find_by_bus_name("i2c", "0-004b"), "struct i2c_client", "dev") (gdb) p *(struct imx_port*)$lx_device_find_by_class_name("tty", "ttymxc1")->parent->driver_data Several generic "lx-device-list" functions are included to enumerate devices by bus and class: (gdb) lx-device-list-bus usb (gdb) lx-device-list-class (gdb) lx-device-list-tree &platform_bus Similar information is available in /sys but pointer values are deliberately hidden. Link: http://lkml.kernel.org/r/c948628041311cbf1b9b4cff3dda7d2073cb3eaa.1561492937.git.leonard.crestez@nxp.com Signed-off-by: Leonard Crestez Reviewed-by: Stephen Boyd Cc: Kieran Bingham Cc: Jan Kiszka Cc: "Rafael J. Wysocki" Cc: Greg Kroah-Hartman Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/gdb/linux/device.py | 182 ++++++++++++++++++++++++++++++++++++++++++++ scripts/gdb/vmlinux-gdb.py | 1 + 2 files changed, 183 insertions(+) create mode 100644 scripts/gdb/linux/device.py (limited to 'scripts') diff --git a/scripts/gdb/linux/device.py b/scripts/gdb/linux/device.py new file mode 100644 index 000000000000..16376c5cfec6 --- /dev/null +++ b/scripts/gdb/linux/device.py @@ -0,0 +1,182 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Copyright (c) NXP 2019 + +import gdb + +from linux.utils import CachedType +from linux.utils import container_of +from linux.lists import list_for_each_entry + + +device_private_type = CachedType('struct device_private') +device_type = CachedType('struct device') + +subsys_private_type = CachedType('struct subsys_private') +kobject_type = CachedType('struct kobject') +kset_type = CachedType('struct kset') + +bus_type = CachedType('struct bus_type') +class_type = CachedType('struct class') + + +def dev_name(dev): + dev_init_name = dev['init_name'] + if dev_init_name: + return dev_init_name.string() + return dev['kobj']['name'].string() + + +def kset_for_each_object(kset): + return list_for_each_entry(kset['list'], + kobject_type.get_type().pointer(), "entry") + + +def for_each_bus(): + for kobj in kset_for_each_object(gdb.parse_and_eval('bus_kset')): + subsys = container_of(kobj, kset_type.get_type().pointer(), 'kobj') + subsys_priv = container_of(subsys, subsys_private_type.get_type().pointer(), 'subsys') + yield subsys_priv['bus'] + + +def for_each_class(): + for kobj in kset_for_each_object(gdb.parse_and_eval('class_kset')): + subsys = container_of(kobj, kset_type.get_type().pointer(), 'kobj') + subsys_priv = container_of(subsys, subsys_private_type.get_type().pointer(), 'subsys') + yield subsys_priv['class'] + + +def get_bus_by_name(name): + for item in for_each_bus(): + if item['name'].string() == name: + return item + raise gdb.GdbError("Can't find bus type {!r}".format(name)) + + +def get_class_by_name(name): + for item in for_each_class(): + if item['name'].string() == name: + return item + raise gdb.GdbError("Can't find device class {!r}".format(name)) + + +klist_type = CachedType('struct klist') +klist_node_type = CachedType('struct klist_node') + + +def klist_for_each(klist): + return list_for_each_entry(klist['k_list'], + klist_node_type.get_type().pointer(), 'n_node') + + +def bus_for_each_device(bus): + for kn in klist_for_each(bus['p']['klist_devices']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_bus') + yield dp['device'] + + +def class_for_each_device(cls): + for kn in klist_for_each(cls['p']['klist_devices']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_class') + yield dp['device'] + + +def device_for_each_child(dev): + for kn in klist_for_each(dev['p']['klist_children']): + dp = container_of(kn, device_private_type.get_type().pointer(), 'knode_parent') + yield dp['device'] + + +def _show_device(dev, level=0, recursive=False): + gdb.write('{}dev {}:\t{}\n'.format('\t' * level, dev_name(dev), dev)) + if recursive: + for child in device_for_each_child(dev): + _show_device(child, level + 1, recursive) + + +class LxDeviceListBus(gdb.Command): + '''Print devices on a bus (or all buses if not specified)''' + + def __init__(self): + super(LxDeviceListBus, self).__init__('lx-device-list-bus', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + for bus in for_each_bus(): + gdb.write('bus {}:\t{}\n'.format(bus['name'].string(), bus)) + for dev in bus_for_each_device(bus): + _show_device(dev, level=1) + else: + bus = get_bus_by_name(arg) + if not bus: + raise gdb.GdbError("Can't find bus {!r}".format(arg)) + for dev in bus_for_each_device(bus): + _show_device(dev) + + +class LxDeviceListClass(gdb.Command): + '''Print devices in a class (or all classes if not specified)''' + + def __init__(self): + super(LxDeviceListClass, self).__init__('lx-device-list-class', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + for cls in for_each_class(): + gdb.write("class {}:\t{}\n".format(cls['name'].string(), cls)) + for dev in class_for_each_device(cls): + _show_device(dev, level=1) + else: + cls = get_class_by_name(arg) + for dev in class_for_each_device(cls): + _show_device(dev) + + +class LxDeviceListTree(gdb.Command): + '''Print a device and its children recursively''' + + def __init__(self): + super(LxDeviceListTree, self).__init__('lx-device-list-tree', gdb.COMMAND_DATA) + + def invoke(self, arg, from_tty): + if not arg: + raise gdb.GdbError('Please provide pointer to struct device') + dev = gdb.parse_and_eval(arg) + if dev.type != device_type.get_type().pointer(): + raise gdb.GdbError('Please provide pointer to struct device') + _show_device(dev, level=0, recursive=True) + + +class LxDeviceFindByBusName(gdb.Function): + '''Find struct device by bus and name (both strings)''' + + def __init__(self): + super(LxDeviceFindByBusName, self).__init__('lx_device_find_by_bus_name') + + def invoke(self, bus, name): + name = name.string() + bus = get_bus_by_name(bus.string()) + for dev in bus_for_each_device(bus): + if dev_name(dev) == name: + return dev + + +class LxDeviceFindByClassName(gdb.Function): + '''Find struct device by class and name (both strings)''' + + def __init__(self): + super(LxDeviceFindByClassName, self).__init__('lx_device_find_by_class_name') + + def invoke(self, cls, name): + name = name.string() + cls = get_class_by_name(cls.string()) + for dev in class_for_each_device(cls): + if dev_name(dev) == name: + return dev + + +LxDeviceListBus() +LxDeviceListClass() +LxDeviceListTree() +LxDeviceFindByBusName() +LxDeviceFindByClassName() diff --git a/scripts/gdb/vmlinux-gdb.py b/scripts/gdb/vmlinux-gdb.py index a504f511e752..4136dc2c59df 100644 --- a/scripts/gdb/vmlinux-gdb.py +++ b/scripts/gdb/vmlinux-gdb.py @@ -36,3 +36,4 @@ else: import linux.timerlist import linux.clk import linux.genpd + import linux.device -- cgit v1.2.3 From 8e2442a5f86e1f77b86401fce274a7f622740bc4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Fri, 12 Jul 2019 15:07:09 +0900 Subject: kconfig: fix missing choice values in auto.conf MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since commit 00c864f8903d ("kconfig: allow all config targets to write auto.conf if missing"), Kconfig creates include/config/auto.conf in the defconfig stage when it is missing. Joonas Kylmälä reported incorrect auto.conf generation under some circumstances. To reproduce it, apply the following diff: | --- a/arch/arm/configs/imx_v6_v7_defconfig | +++ b/arch/arm/configs/imx_v6_v7_defconfig | @@ -345,14 +345,7 @@ CONFIG_USB_CONFIGFS_F_MIDI=y | CONFIG_USB_CONFIGFS_F_HID=y | CONFIG_USB_CONFIGFS_F_UVC=y | CONFIG_USB_CONFIGFS_F_PRINTER=y | -CONFIG_USB_ZERO=m | -CONFIG_USB_AUDIO=m | -CONFIG_USB_ETH=m | -CONFIG_USB_G_NCM=m | -CONFIG_USB_GADGETFS=m | -CONFIG_USB_FUNCTIONFS=m | -CONFIG_USB_MASS_STORAGE=m | -CONFIG_USB_G_SERIAL=m | +CONFIG_USB_FUNCTIONFS=y | CONFIG_MMC=y | CONFIG_MMC_SDHCI=y | CONFIG_MMC_SDHCI_PLTFM=y And then, run: $ make ARCH=arm mrproper imx_v6_v7_defconfig You will see CONFIG_USB_FUNCTIONFS=y is correctly contained in the .config, but not in the auto.conf. Please note drivers/usb/gadget/legacy/Kconfig is included from a choice block in drivers/usb/gadget/Kconfig. So USB_FUNCTIONFS is a choice value. This is probably a similar situation described in commit beaaddb62540 ("kconfig: tests: test defconfig when two choices interact"). When sym_calc_choice() is called, the choice symbol forgets the SYMBOL_DEF_USER unless all of its choice values are explicitly set by the user. The choice symbol is given just one chance to recall it because set_all_choice_values() is called if SYMBOL_NEED_SET_CHOICE_VALUES is set. When sym_calc_choice() is called again, the choice symbol forgets it forever, since SYMBOL_NEED_SET_CHOICE_VALUES is a one-time aid. Hence, we cannot call sym_clear_all_valid() again and again. It is crazy to repeat set and unset of internal flags. However, we cannot simply get rid of "sym->flags &= flags | ~SYMBOL_DEF_USER;" Doing so would re-introduce the problem solved by commit 5d09598d488f ("kconfig: fix new choices being skipped upon config update"). To work around the issue, conf_write_autoconf() stopped calling sym_clear_all_valid(). conf_write() must be changed accordingly. Currently, it clears SYMBOL_WRITE after the symbol is written into the .config file. This is needed to prevent it from writing the same symbol multiple times in case the symbol is declared in two or more locations. I added the new flag SYMBOL_WRITTEN, to track the symbols that have been written. Anyway, this is a cheesy workaround in order to suppress the issue as far as defconfig is concerned. Handling of choices is totally broken. sym_clear_all_valid() is called every time a user touches a symbol from the GUI interface. To reproduce it, just add a new symbol drivers/usb/gadget/legacy/Kconfig, then touch around unrelated symbols from menuconfig. USB_FUNCTIONFS will disappear from the .config file. I added the Fixes tag since it is more fatal than before. But, this has been broken since long long time before, and still it is. We should take a closer look to fix this correctly somehow. Fixes: 00c864f8903d ("kconfig: allow all config targets to write auto.conf if missing") Cc: linux-stable # 4.19+ Reported-by: Joonas Kylmälä Signed-off-by: Masahiro Yamada Tested-by: Joonas Kylmälä --- scripts/kconfig/confdata.c | 7 +++---- scripts/kconfig/expr.h | 1 + 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kconfig/confdata.c b/scripts/kconfig/confdata.c index 501fdcc5e999..1134892599da 100644 --- a/scripts/kconfig/confdata.c +++ b/scripts/kconfig/confdata.c @@ -895,7 +895,8 @@ int conf_write(const char *name) "# %s\n" "#\n", str); need_newline = false; - } else if (!(sym->flags & SYMBOL_CHOICE)) { + } else if (!(sym->flags & SYMBOL_CHOICE) && + !(sym->flags & SYMBOL_WRITTEN)) { sym_calc_value(sym); if (!(sym->flags & SYMBOL_WRITE)) goto next; @@ -903,7 +904,7 @@ int conf_write(const char *name) fprintf(out, "\n"); need_newline = false; } - sym->flags &= ~SYMBOL_WRITE; + sym->flags |= SYMBOL_WRITTEN; conf_write_symbol(out, sym, &kconfig_printer_cb, NULL); } @@ -1063,8 +1064,6 @@ int conf_write_autoconf(int overwrite) if (!overwrite && is_present(autoconf_name)) return 0; - sym_clear_all_valid(); - conf_write_dep("include/config/auto.conf.cmd"); if (conf_touch_deps()) diff --git a/scripts/kconfig/expr.h b/scripts/kconfig/expr.h index 8dde65bc3165..017843c9a4f4 100644 --- a/scripts/kconfig/expr.h +++ b/scripts/kconfig/expr.h @@ -141,6 +141,7 @@ struct symbol { #define SYMBOL_OPTIONAL 0x0100 /* choice is optional - values can be 'n' */ #define SYMBOL_WRITE 0x0200 /* write symbol to file (KCONFIG_CONFIG) */ #define SYMBOL_CHANGED 0x0400 /* ? */ +#define SYMBOL_WRITTEN 0x0800 /* track info to avoid double-write to .config */ #define SYMBOL_NO_WRITE 0x1000 /* Symbol for internal use only; it will not be written */ #define SYMBOL_CHECKED 0x2000 /* used during dependency checking */ #define SYMBOL_WARNED 0x8000 /* warning has been issued */ -- cgit v1.2.3 From c04d1e46fcd6090f2ae04e285e9d3adcf376f5b1 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Mon, 15 Jul 2019 23:11:03 +0900 Subject: kbuild: remove unused hostcc-option We can re-add this whenever it is needed. At this moment, it is unused. Signed-off-by: Masahiro Yamada --- scripts/Kbuild.include | 5 ----- 1 file changed, 5 deletions(-) (limited to 'scripts') diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include index 73e80b917f12..77c742fa4fb1 100644 --- a/scripts/Kbuild.include +++ b/scripts/Kbuild.include @@ -125,11 +125,6 @@ CC_OPTION_CFLAGS = $(filter-out $(GCC_PLUGINS_CFLAGS),$(KBUILD_CFLAGS)) cc-option = $(call __cc-option, $(CC),\ $(KBUILD_CPPFLAGS) $(CC_OPTION_CFLAGS),$(1),$(2)) -# hostcc-option -# Usage: cflags-y += $(call hostcc-option,-march=winchip-c6,-march=i586) -hostcc-option = $(call __cc-option, $(HOSTCC),\ - $(KBUILD_HOSTCFLAGS) $(HOST_EXTRACFLAGS),$(1),$(2)) - # cc-option-yn # Usage: flag := $(call cc-option-yn,-march=winchip-c6) cc-option-yn = $(call try-run,\ -- cgit v1.2.3 From 4bd01de8f201abb704ae9bda3af4ea9ba3a10b0a Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Tue, 16 Jul 2019 22:29:45 +0900 Subject: kbuild: compile-test headers listed in header-test-m as well It will be useful to control the header-test by a tristate option. If CONFIG_FOO is a tristate option, you can write like this: header-test-$(CONFIG_FOO) += foo.h Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 2 +- scripts/Makefile.lib | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index be38198d98b2..5829ccbc7dd0 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -294,7 +294,7 @@ quiet_cmd_cc_lst_c = MKLST $@ $(obj)/%.lst: $(src)/%.c FORCE $(call if_changed_dep,cc_lst_c) -# header test (header-test-y target) +# header test (header-test-y, header-test-m target) # --------------------------------------------------------------------------- quiet_cmd_cc_s_h = CC $@ diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib index 6cb3aa5cbc79..5241d0751eb0 100644 --- a/scripts/Makefile.lib +++ b/scripts/Makefile.lib @@ -78,7 +78,7 @@ header-test-y += $(filter-out $(header-test-), \ $(wildcard $(addprefix $(srctree)/$(src)/, \ $(header-test-pattern-y))))) -extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y)) +extra-$(CONFIG_HEADER_TEST) += $(addsuffix .s, $(header-test-y) $(header-test-m)) # Add subdir path -- cgit v1.2.3 From d09778d16e20bc4f1f4971cc9a9fd7ff6ba898ff Mon Sep 17 00:00:00 2001 From: Himanshu Jha Date: Tue, 16 Jul 2019 11:22:22 +0530 Subject: coccinelle: api: add devm_platform_ioremap_resource script Use recently introduced devm_platform_ioremap_resource helper which wraps platform_get_resource() and devm_ioremap_resource() together. This helps produce much cleaner code and remove local `struct resource` declaration. Signed-off-by: Himanshu Jha Signed-off-by: Julia Lawall Signed-off-by: Masahiro Yamada --- .../api/devm_platform_ioremap_resource.cocci | 60 ++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 scripts/coccinelle/api/devm_platform_ioremap_resource.cocci (limited to 'scripts') diff --git a/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci b/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci new file mode 100644 index 000000000000..56a2e261d61d --- /dev/null +++ b/scripts/coccinelle/api/devm_platform_ioremap_resource.cocci @@ -0,0 +1,60 @@ +// SPDX-License-Identifier: GPL-2.0 +/// Use devm_platform_ioremap_resource helper which wraps +/// platform_get_resource() and devm_ioremap_resource() together. +/// +// Confidence: High +// Copyright: (C) 2019 Himanshu Jha GPLv2. +// Copyright: (C) 2019 Julia Lawall, Inria/LIP6. GPLv2. +// Keywords: platform_get_resource, devm_ioremap_resource, +// Keywords: devm_platform_ioremap_resource + +virtual patch +virtual report + +@r depends on patch && !report@ +expression e1, e2, arg1, arg2, arg3; +identifier id; +@@ + +( +- id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +| +- struct resource *id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +) + ... when != id +- e1 = devm_ioremap_resource(arg3, id); ++ e1 = devm_platform_ioremap_resource(arg1, arg2); + ... when != id +? id = e2 + +@r1 depends on patch && !report@ +identifier r.id; +type T; +@@ + +- T *id; + ...when != id + +@r2 depends on report && !patch@ +identifier id; +expression e1, e2, arg1, arg2, arg3; +position j0; +@@ + +( + id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +| + struct resource *id = platform_get_resource(arg1, IORESOURCE_MEM, arg2); +) + ... when != id + e1@j0 = devm_ioremap_resource(arg3, id); + ... when != id +? id = e2 + +@script:python depends on report && !patch@ +e1 << r2.e1; +j0 << r2.j0; +@@ + +msg = "WARNING: Use devm_platform_ioremap_resource for %s" % (e1) +coccilib.report.print_report(j0[0], msg) -- cgit v1.2.3 From 7e13191879d6d589cd987a8db3a70019251fc757 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:49 +0900 Subject: kbuild: do not create empty modules.order in the prepare stage Currently, $(objtree)/modules.order is touched in two places. In the 'prepare0' rule, scripts/Makefile.build creates an empty modules.order while processing 'obj=.' In the 'modules' rule, the top-level Makefile overwrites it with the correct list of modules. While this might be a good side-effect that modules.order is made empty every time (probably this is not intended functionality), I personally do not like this behavior. Create modules.order only when it is sensible to do so. This avoids creating the following pointless files: scripts/basic/modules.order scripts/dtc/modules.order scripts/gcc-plugins/modules.order scripts/genksyms/modules.order scripts/mod/modules.order scripts/modules.order scripts/selinux/genheaders/modules.order scripts/selinux/mdp/modules.order scripts/selinux/modules.order Going forward, $(objtree)/modules.order lists the modules that was built in the last successful build. Signed-off-by: Masahiro Yamada --- Makefile | 4 ++-- scripts/Makefile.build | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index e43285786102..b74a6e9cefc8 100644 --- a/Makefile +++ b/Makefile @@ -1072,7 +1072,7 @@ $(sort $(vmlinux-deps)): $(vmlinux-dirs) ; PHONY += $(vmlinux-dirs) $(vmlinux-dirs): prepare - $(Q)$(MAKE) $(build)=$@ need-builtin=1 + $(Q)$(MAKE) $(build)=$@ need-builtin=1 need-modorder=1 filechk_kernel.release = \ echo "$(KERNELVERSION)$$($(CONFIG_SHELL) $(srctree)/scripts/setlocalversion $(srctree))" @@ -1616,7 +1616,7 @@ $(objtree)/Module.symvers: module-dirs := $(addprefix _module_,$(KBUILD_EXTMOD)) PHONY += $(module-dirs) modules $(module-dirs): prepare $(objtree)/Module.symvers - $(Q)$(MAKE) $(build)=$(patsubst _module_%,%,$@) + $(Q)$(MAKE) $(build)=$(patsubst _module_%,%,$@) need-modorder=1 modules: $(module-dirs) @$(kecho) ' Building modules, stage 2.'; diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 5829ccbc7dd0..631bb89524de 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -63,7 +63,7 @@ ifneq ($(strip $(real-obj-y) $(need-builtin)),) builtin-target := $(obj)/built-in.a endif -ifdef CONFIG_MODULES +ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif -- cgit v1.2.3 From 1bd9a468018dd318283c7c620729ddf1923f2024 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:50 +0900 Subject: kbuild: get rid of kernel/ prefix from in-tree modules.{order,builtin} Removing the 'kernel/' prefix will make our life easier because we can simply do 'cat modules.order' to get all built modules with full paths. Currently, we parse the first line of '*.mod' files in $(MODVERDIR). Since we have duplicated functionality here, I plan to remove MODVERDIR entirely. In fact, modules.order is generated also for external modules in a broken format. It adds the 'kernel/' prefix to the absolute path of the module, like this: kernel//path/to/your/external/module/foo.ko This is fine for now since modules.order is not used for external modules. However, I want to sanitize the format everywhere towards the goal of removing MODVERDIR. We cannot change the format of installed module.{order,builtin}. So, 'make modules_install' will add the 'kernel/' prefix while copying them to $(MODLIB)/. Signed-off-by: Masahiro Yamada --- Makefile | 4 ++-- scripts/Makefile.build | 2 +- scripts/Makefile.modbuiltin | 2 +- scripts/modules-check.sh | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index b74a6e9cefc8..396cd5e525d1 100644 --- a/Makefile +++ b/Makefile @@ -1329,8 +1329,8 @@ _modinst_: rm -f $(MODLIB)/build ; \ ln -s $(CURDIR) $(MODLIB)/build ; \ fi - @cp -f $(objtree)/modules.order $(MODLIB)/ - @cp -f $(objtree)/modules.builtin $(MODLIB)/ + @sed 's:^:kernel/:' modules.order > $(MODLIB)/modules.order + @sed 's:^:kernel/:' modules.builtin > $(MODLIB)/modules.builtin @cp -f $(objtree)/modules.builtin.modinfo $(MODLIB)/ $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modinst diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 631bb89524de..10e92a27ec20 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -426,7 +426,7 @@ endif # builtin-target modorder-cmds = \ $(foreach m, $(modorder), \ $(if $(filter %/modules.order, $m), \ - cat $m;, echo kernel/$m;)) + cat $m;, echo $m;)) $(modorder-target): $(subdir-ym) FORCE $(Q)(cat /dev/null; $(modorder-cmds)) > $@ diff --git a/scripts/Makefile.modbuiltin b/scripts/Makefile.modbuiltin index 50a9990760f3..7d4711b88656 100644 --- a/scripts/Makefile.modbuiltin +++ b/scripts/Makefile.modbuiltin @@ -40,7 +40,7 @@ __modbuiltin: $(modbuiltin-target) $(subdir-ym) @: $(modbuiltin-target): $(subdir-ym) FORCE - $(Q)(for m in $(modbuiltin-mods); do echo kernel/$$m; done; \ + $(Q)(for m in $(modbuiltin-mods); do echo $$m; done; \ cat /dev/null $(modbuiltin-subdirs)) > $@ PHONY += FORCE diff --git a/scripts/modules-check.sh b/scripts/modules-check.sh index 39e8cb36ba19..f51f446707b8 100755 --- a/scripts/modules-check.sh +++ b/scripts/modules-check.sh @@ -9,7 +9,7 @@ check_same_name_modules() for m in $(sed 's:.*/::' modules.order | sort | uniq -d) do echo "warning: same module names found:" >&2 - sed -n "/\/$m/s:^kernel/: :p" modules.order >&2 + sed -n "/\/$m/s:^: :p" modules.order >&2 done } -- cgit v1.2.3 From e0e1b1ec397e153da10f90355545607d2fd13293 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:51 +0900 Subject: kbuild: remove duplication from modules.order in sub-directories Currently, only the top-level modules.order drops duplicated entries. The modules.order files in sub-directories potentially contain duplication. To list out the paths of all modules, I want to use modules.order instead of parsing *.mod files in $(MODVERDIR). To achieve this, I want to rip off duplication from modules.order of external modules too. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 10e92a27ec20..be32a3752de4 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -423,13 +423,10 @@ endif # builtin-target # # Create commands to either record .ko file or cat modules.order from # a subdirectory -modorder-cmds = \ - $(foreach m, $(modorder), \ - $(if $(filter %/modules.order, $m), \ - cat $m;, echo $m;)) - $(modorder-target): $(subdir-ym) FORCE - $(Q)(cat /dev/null; $(modorder-cmds)) > $@ + $(Q){ $(foreach m, $(modorder), \ + $(if $(filter %/modules.order, $m), cat $m, echo $m);) :; } \ + | $(AWK) '!x[$$0]++' - > $@ # # Rule to compile a set of .o files into one .a file (with symbol table) -- cgit v1.2.3 From d56aec102c0c462b94513421726e33938695cef4 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:53 +0900 Subject: kbuild: modinst: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be installed. This is simpler than parsing *.mod files in $(MODVERDIR). For external modules, $(KBUILD_EXTMOD)/modules.order should be read. Signed-off-by: Masahiro Yamada --- scripts/Makefile.modinst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.modinst b/scripts/Makefile.modinst index 0dae402661f3..5a4579e76485 100644 --- a/scripts/Makefile.modinst +++ b/scripts/Makefile.modinst @@ -8,10 +8,7 @@ __modinst: include scripts/Kbuild.include -# - -__modules := $(sort $(shell grep -h '\.ko$$' /dev/null $(wildcard $(MODVERDIR)/*.mod))) -modules := $(patsubst %.o,%.ko,$(wildcard $(__modules:.ko=.o))) +modules := $(sort $(shell cat $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)modules.order)) PHONY += $(modules) __modinst: $(modules) -- cgit v1.2.3 From c35c87d6f258ad943d0fb350ed45fa9302c36b52 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:54 +0900 Subject: kbuild: modsign: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be signed. This is simpler than parsing *.mod files in $(MODVERDIR). The modules_sign target is only supported for in-kernel modules. So, this commit does not take care of external modules. Signed-off-by: Masahiro Yamada --- scripts/Makefile.modsign | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.modsign b/scripts/Makefile.modsign index da56aa78d245..d7325cefe709 100644 --- a/scripts/Makefile.modsign +++ b/scripts/Makefile.modsign @@ -8,8 +8,7 @@ __modsign: include scripts/Kbuild.include -__modules := $(sort $(shell grep -h '\.ko$$' /dev/null $(wildcard $(MODVERDIR)/*.mod))) -modules := $(patsubst %.o,%.ko,$(wildcard $(__modules:.ko=.o))) +modules := $(sort $(shell cat modules.order)) PHONY += $(modules) __modsign: $(modules) -- cgit v1.2.3 From ff9b45c55b2659d14420424da0ce4e8aa3dbce28 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:55 +0900 Subject: kbuild: modpost: read modules.order instead of $(MODVERDIR)/*.mod Towards the goal of removing MODVERDIR, read out modules.order to get the list of modules to be processed. This is simpler than parsing *.mod files in $(MODVERDIR). For external modules, $(KBUILD_EXTMOD)/modules.order should be read. I removed the single target %.ko from the top Makefile. To make sure modpost works correctly, vmlinux and the other modules must be built. You cannot build a particular .ko file alone. Signed-off-by: Masahiro Yamada --- Makefile | 2 -- scripts/Makefile.modpost | 15 +++++++++------ 2 files changed, 9 insertions(+), 8 deletions(-) (limited to 'scripts') diff --git a/Makefile b/Makefile index 396cd5e525d1..d9103e731187 100644 --- a/Makefile +++ b/Makefile @@ -1772,8 +1772,6 @@ build-dir = $(patsubst %/,%,$(dir $(build-target))) $(Q)$(MAKE) $(build)=$(build-dir) $(build-target) %.symtypes: prepare FORCE $(Q)$(MAKE) $(build)=$(build-dir) $(build-target) -%.ko: %.o - $(Q)$(MAKE) -f $(srctree)/scripts/Makefile.modpost # Modules PHONY += / diff --git a/scripts/Makefile.modpost b/scripts/Makefile.modpost index fec6ec2ffa47..5841508ffca9 100644 --- a/scripts/Makefile.modpost +++ b/scripts/Makefile.modpost @@ -8,9 +8,10 @@ # b) A .o file which is the .o files above linked together # c) A .mod file in $(MODVERDIR)/, listing the name of the # the preliminary .o file, plus all .o files +# d) modules.order, which lists all the modules # Stage 2 is handled by this file and does the following -# 1) Find all modules from the files listed in $(MODVERDIR)/ +# 1) Find all modules listed in modules.order # 2) modpost is then used to # 3) create one .mod.c file pr. module # 4) create one Module.symvers file with CRC for all exported symbols @@ -60,10 +61,12 @@ include scripts/Makefile.lib kernelsymfile := $(objtree)/Module.symvers modulesymfile := $(firstword $(KBUILD_EXTMOD))/Module.symvers -# Step 1), find all modules listed in $(MODVERDIR)/ -MODLISTCMD := find $(MODVERDIR) -name '*.mod' | xargs -r grep -h '\.ko$$' | sort -u -__modules := $(shell $(MODLISTCMD)) -modules := $(patsubst %.o,%.ko, $(wildcard $(__modules:.ko=.o))) +modorder := $(if $(KBUILD_EXTMOD),$(KBUILD_EXTMOD)/)modules.order + +# Step 1), find all modules listed in modules.order +ifdef CONFIG_MODULES +modules := $(sort $(shell cat $(modorder))) +endif # Stop after building .o files if NOFINAL is set. Makes compile tests quicker _modpost: $(if $(KBUILD_MODPOST_NOFINAL), $(modules:.ko:.o),$(modules)) @@ -84,7 +87,7 @@ MODPOST_OPT=$(subst -i,-n,$(filter -i,$(MAKEFLAGS))) # We can go over command line length here, so be careful. quiet_cmd_modpost = MODPOST $(words $(filter-out vmlinux FORCE, $^)) modules - cmd_modpost = $(MODLISTCMD) | sed 's/\.ko$$/.o/' | $(modpost) $(MODPOST_OPT) -s -T - + cmd_modpost = sed 's/ko$$/o/' $(modorder) | $(modpost) $(MODPOST_OPT) -s -T - PHONY += __modpost __modpost: $(modules:.ko=.o) FORCE -- cgit v1.2.3 From 7deb55f57159f9de696ef8d5e93b201a6aba871c Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:56 +0900 Subject: kbuild: export_report: read modules.order instead of .tmp_versions/*.mod Towards the goal of removing MODVERDIR aka .tmp_versions, read out modules.order to get the list of modules to be processed. This is simpler than parsing *.mod files in .tmp_versions. Signed-off-by: Masahiro Yamada --- scripts/export_report.pl | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'scripts') diff --git a/scripts/export_report.pl b/scripts/export_report.pl index 0f604f62f067..7d3030d03a25 100755 --- a/scripts/export_report.pl +++ b/scripts/export_report.pl @@ -52,13 +52,12 @@ sub usage { sub collectcfiles { my @file; - while (<.tmp_versions/*.mod>) { - open my $fh, '<', $_ or die "cannot open $_: $!\n"; - push (@file, - grep s/\.ko/.mod.c/, # change the suffix - grep m/.+\.ko/, # find the .ko path - <$fh>); # lines in opened file + open my $fh, '< modules.order' or die "cannot open modules.order: $!\n"; + while (<$fh>) { + s/\.ko$/.mod.c/; + push (@file, $_) } + close($fh); chomp @file; return @file; } -- cgit v1.2.3 From b7dca6dd1e591ad19a9aae716f3898be8063f880 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:57 +0900 Subject: kbuild: create *.mod with full directory path and remove MODVERDIR While descending directories, Kbuild produces objects for modules, but do not link final *.ko files; it is done in the modpost. To keep track of modules, Kbuild creates a *.mod file in $(MODVERDIR) for every module it is building. Some post-processing steps read the necessary information from *.mod files. This avoids descending into directories again. This mechanism was introduced in 2003 or so. Later, commit 551559e13af1 ("kbuild: implement modules.order") added modules.order. So, we can simply read it out to know all the modules with directory paths. This is easier than parsing the first line of *.mod files. $(MODVERDIR) has a flat directory structure, that is, *.mod files are named only with base names. This is based on the assumption that the module name is unique across the tree. This assumption is really fragile. Stephen Rothwell reported a race condition caused by a module name conflict: https://lkml.org/lkml/2019/5/13/991 In parallel building, two different threads could write to the same $(MODVERDIR)/*.mod simultaneously. Non-unique module names are the source of all kind of troubles, hence commit 3a48a91901c5 ("kbuild: check uniqueness of module names") introduced a new checker script. However, it is still fragile in the build system point of view because this race happens before scripts/modules-check.sh is invoked. If it happens again, the modpost will emit unclear error messages. To fix this issue completely, create *.mod with full directory path so that two threads never attempt to write to the same file. $(MODVERDIR) is no longer needed. Since modules with directory paths are listed in modules.order, Kbuild is still able to find *.mod files without additional descending. I also killed cmd_secanalysis; scripts/mod/sumversion.c computes MD4 hash for modules with MODULE_VERSION(). When CONFIG_DEBUG_SECTION_MISMATCH=y, it occurs not only in the modpost stage, but also during directory descending, where sumversion.c may parse stale *.mod files. It would emit 'No such file or directory' warning when an object consisting a module is renamed, or when a single-obj module is turned into a multi-obj module or vice versa. Signed-off-by: Masahiro Yamada Acked-by: Nicolas Pitre --- .gitignore | 1 + Documentation/dontdiff | 1 + Makefile | 20 +++----------------- lib/Kconfig.debug | 12 +----------- scripts/Makefile.build | 15 +++------------ scripts/Makefile.modpost | 4 ++-- scripts/adjust_autoksyms.sh | 14 +++++--------- scripts/mod/sumversion.c | 16 +++------------- scripts/package/mkspec | 2 +- tools/power/cpupower/debug/kernel/Makefile | 4 ++-- 10 files changed, 22 insertions(+), 67 deletions(-) (limited to 'scripts') diff --git a/.gitignore b/.gitignore index 7587ef56b92d..8f5422cba6e2 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ *.lz4 *.lzma *.lzo +*.mod *.mod.c *.o *.o.* diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 5eba889ea84d..9f4392876099 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -30,6 +30,7 @@ *.lzo *.mo *.moc +*.mod *.mod.c *.o *.o.* diff --git a/Makefile b/Makefile index d9103e731187..6308c8cea121 100644 --- a/Makefile +++ b/Makefile @@ -486,11 +486,6 @@ export KBUILD_AFLAGS_MODULE KBUILD_CFLAGS_MODULE KBUILD_LDFLAGS_MODULE export KBUILD_AFLAGS_KERNEL KBUILD_CFLAGS_KERNEL export KBUILD_ARFLAGS -# When compiling out-of-tree modules, put MODVERDIR in the module -# tree rather than in the kernel tree. The kernel tree might -# even be read-only. -export MODVERDIR := $(if $(KBUILD_EXTMOD),$(firstword $(KBUILD_EXTMOD))/).tmp_versions - # Files to ignore in find ... statements export RCS_FIND_IGNORE := \( -name SCCS -o -name BitKeeper -o -name .svn -o \ @@ -1029,8 +1024,8 @@ vmlinux-deps := $(KBUILD_LDS) $(KBUILD_VMLINUX_OBJS) $(KBUILD_VMLINUX_LIBS) # Recurse until adjust_autoksyms.sh is satisfied PHONY += autoksyms_recursive -autoksyms_recursive: $(vmlinux-deps) ifdef CONFIG_TRIM_UNUSED_KSYMS +autoksyms_recursive: $(vmlinux-deps) modules.order $(Q)$(CONFIG_SHELL) $(srctree)/scripts/adjust_autoksyms.sh \ "$(MAKE) -f $(srctree)/Makefile vmlinux" endif @@ -1113,7 +1108,6 @@ endif prepare1: prepare3 outputmakefile asm-generic $(version_h) $(autoksyms_h) \ include/generated/utsrelease.h - $(cmd_crmodverdir) archprepare: archheaders archscripts prepare1 scripts @@ -1371,7 +1365,7 @@ endif # CONFIG_MODULES # make distclean Remove editor backup files, patch leftover files and the like # Directories & files removed with 'make clean' -CLEAN_DIRS += $(MODVERDIR) include/ksym +CLEAN_DIRS += include/ksym CLEAN_FILES += modules.builtin.modinfo # Directories & files removed with 'make mrproper' @@ -1641,7 +1635,6 @@ PHONY += $(clean-dirs) clean $(clean-dirs): $(Q)$(MAKE) $(clean)=$(patsubst _clean_%,%,$@) -clean: rm-dirs := $(MODVERDIR) clean: rm-files := $(KBUILD_EXTMOD)/Module.symvers PHONY += help @@ -1655,8 +1648,6 @@ help: @echo '' PHONY += prepare -prepare: - $(cmd_crmodverdir) endif # KBUILD_EXTMOD clean: $(clean-dirs) @@ -1667,7 +1658,7 @@ clean: $(clean-dirs) -o -name '*.ko.*' \ -o -name '*.dtb' -o -name '*.dtb.S' -o -name '*.dt.yaml' \ -o -name '*.dwo' -o -name '*.lst' \ - -o -name '*.su' \ + -o -name '*.su' -o -name '*.mod' \ -o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \ -o -name '*.lex.c' -o -name '*.tab.[ch]' \ -o -name '*.asn1.[ch]' \ @@ -1794,11 +1785,6 @@ quiet_cmd_depmod = DEPMOD $(KERNELRELEASE) cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \ $(KERNELRELEASE) -# Create temporary dir for module support files -# clean it up only when building all modules -cmd_crmodverdir = $(Q)mkdir -p $(MODVERDIR) \ - $(if $(KBUILD_MODULES),; rm -f $(MODVERDIR)/*) - # read saved command lines for existing targets existing-targets := $(wildcard $(sort $(targets))) diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 4ac4ca21a30a..cde5675340ba 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -353,23 +353,13 @@ config DEBUG_SECTION_MISMATCH which results in the code/data being placed in specific sections. The section mismatch analysis is always performed after a full kernel build, and enabling this option causes the following - additional steps to occur: + additional step to occur: - Add the option -fno-inline-functions-called-once to gcc commands. When inlining a function annotated with __init in a non-init function, we would lose the section information and thus the analysis would not catch the illegal reference. This option tells gcc to inline less (but it does result in a larger kernel). - - Run the section mismatch analysis for each module/built-in.a file. - When we run the section mismatch analysis on vmlinux.o, we - lose valuable information about where the mismatch was - introduced. - Running the analysis for each module/built-in.a file - tells where the mismatch happens much closer to the - source. The drawback is that the same mismatch is - reported at least twice. - - Enable verbose reporting from modpost in order to help resolve - the section mismatches that are reported. config SECTION_MISMATCH_WARN_ONLY bool "Make section mismatch errors non-fatal" diff --git a/scripts/Makefile.build b/scripts/Makefile.build index be32a3752de4..c6dfcc028f56 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -67,8 +67,6 @@ ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif -# We keep a list of all modules in $(MODVERDIR) - __build: $(if $(KBUILD_BUILTIN),$(builtin-target) $(lib-target) $(extra-y)) \ $(if $(KBUILD_MODULES),$(obj-m) $(modorder-target)) \ $(subdir-ym) $(always) @@ -87,11 +85,6 @@ ifneq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),) cmd_checkdoc = $(srctree)/scripts/kernel-doc -none $< endif -# Do section mismatch analysis for each module/built-in.a -ifdef CONFIG_DEBUG_SECTION_MISMATCH - cmd_secanalysis = ; scripts/mod/modpost $@ -endif - # Compile C sources (.c) # --------------------------------------------------------------------------- @@ -278,13 +271,11 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) -# Single-part modules are special since we need to mark them in $(MODVERDIR) - $(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) @{ echo $(@:.o=.ko); echo $@; \ - $(cmd_undef_syms); } > $(MODVERDIR)/$(@F:.o=.mod) + $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) quiet_cmd_cc_lst_c = MKLST $@ cmd_cc_lst_c = $(CC) $(c_flags) -g -c -o $*.o $< && \ @@ -461,12 +452,12 @@ endif # module is turned into a multi object module, $^ will contain header file # dependencies recorded in the .*.cmd file. quiet_cmd_link_multi-m = LD [M] $@ -cmd_link_multi-m = $(LD) $(ld_flags) -r -o $@ $(filter %.o,$^) $(cmd_secanalysis) + cmd_link_multi-m = $(LD) $(ld_flags) -r -o $@ $(filter %.o,$^) $(multi-used-m): FORCE $(call if_changed,link_multi-m) @{ echo $(@:.o=.ko); echo $(filter %.o,$^); \ - $(cmd_undef_syms); } > $(MODVERDIR)/$(@F:.o=.mod) + $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) targets += $(multi-used-m) diff --git a/scripts/Makefile.modpost b/scripts/Makefile.modpost index 5841508ffca9..6b19c1a4eae5 100644 --- a/scripts/Makefile.modpost +++ b/scripts/Makefile.modpost @@ -6,8 +6,8 @@ # Stage one of module building created the following: # a) The individual .o files used for the module # b) A .o file which is the .o files above linked together -# c) A .mod file in $(MODVERDIR)/, listing the name of the -# the preliminary .o file, plus all .o files +# c) A .mod file, listing the name of the preliminary .o file, +# plus all .o files # d) modules.order, which lists all the modules # Stage 2 is handled by this file and does the following diff --git a/scripts/adjust_autoksyms.sh b/scripts/adjust_autoksyms.sh index aab4e299d7a2..2e4a7320bfb4 100755 --- a/scripts/adjust_autoksyms.sh +++ b/scripts/adjust_autoksyms.sh @@ -8,8 +8,7 @@ # # Create/update the include/generated/autoksyms.h file from the list -# of all module's needed symbols as recorded on the third line of -# .tmp_versions/*.mod files. +# of all module's needed symbols as recorded on the third line of *.mod files. # # For each symbol being added or removed, the corresponding dependency # file's timestamp is updated to force a rebuild of the affected source @@ -47,13 +46,10 @@ cat > "$new_ksyms_file" << EOT */ EOT -[ "$(ls -A "$MODVERDIR")" ] && -for mod in "$MODVERDIR"/*.mod; do - sed -n -e '3{s/ /\n/g;/^$/!p;}' "$mod" -done | sort -u | -while read sym; do - echo "#define __KSYM_${sym} 1" -done >> "$new_ksyms_file" +sed 's/ko$/mod/' modules.order | +xargs -n1 sed -n -e '3{s/ /\n/g;/^$/!p;}' -- | +sort -u | +sed -e 's/\(.*\)/#define __KSYM_\1 1/' >> "$new_ksyms_file" # Special case for modversions (see modpost.c) if [ -n "$CONFIG_MODVERSIONS" ]; then diff --git a/scripts/mod/sumversion.c b/scripts/mod/sumversion.c index 0f6dcb4011a8..166f3fa247a9 100644 --- a/scripts/mod/sumversion.c +++ b/scripts/mod/sumversion.c @@ -396,21 +396,11 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) unsigned long len; struct md4_ctx md; char *sources, *end, *fname; - const char *basename; char filelist[PATH_MAX + 1]; - char *modverdir = getenv("MODVERDIR"); - if (!modverdir) - modverdir = "."; - - /* Source files for module are in .tmp_versions/modname.mod, - after the first line. */ - if (strrchr(modname, '/')) - basename = strrchr(modname, '/') + 1; - else - basename = modname; - snprintf(filelist, sizeof(filelist), "%s/%.*s.mod", modverdir, - (int) strlen(basename) - 2, basename); + /* objects for a module are listed in the second line of *.mod file. */ + snprintf(filelist, sizeof(filelist), "%.*smod", + (int)strlen(modname) - 1, modname); file = grab_file(filelist, &len); if (!file) diff --git a/scripts/package/mkspec b/scripts/package/mkspec index 2d29df4a0a53..8640c278f1aa 100755 --- a/scripts/package/mkspec +++ b/scripts/package/mkspec @@ -29,7 +29,7 @@ fi PROVIDES="$PROVIDES kernel-$KERNELRELEASE" __KERNELRELEASE=$(echo $KERNELRELEASE | sed -e "s/-/_/g") -EXCLUDES="$RCS_TAR_IGNORE --exclude=.tmp_versions --exclude=*vmlinux* \ +EXCLUDES="$RCS_TAR_IGNORE --exclude=*vmlinux* --exclude=*.mod \ --exclude=*.o --exclude=*.ko --exclude=*.cmd --exclude=Documentation \ --exclude=.config.old --exclude=.missing-syscalls.d --exclude=*.s" diff --git a/tools/power/cpupower/debug/kernel/Makefile b/tools/power/cpupower/debug/kernel/Makefile index c23e5a6ceb7e..7b5c43684be1 100644 --- a/tools/power/cpupower/debug/kernel/Makefile +++ b/tools/power/cpupower/debug/kernel/Makefile @@ -12,8 +12,8 @@ default: $(MAKE) -C $(KDIR) M=$(CURDIR) clean: - - rm -rf *.o *.ko .tmp-versions .*.cmd .*.mod.* *.mod.c - - rm -rf .tmp_versions* Module.symvers modules.order + - rm -rf *.o *.ko .*.cmd .*.mod.* *.mod.c + - rm -rf Module.symvers modules.order install: default install -d $(KMISC) -- cgit v1.2.3 From 60ae1b194b4548102fea0f5091af83b478f2352b Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:17:58 +0900 Subject: kbuild: remove the first line of *.mod files The current format of *.mod is like this: line 1: directory path to the .ko file line 2: a list of objects linked into this module line 3: unresolved symbols (only when CONFIG_TRIM_UNUSED_KSYMS=y) Now that *.mod and *.ko are created in the same directory, the line 1 provides no valuable information. It can be derived by replacing the extension .mod with .ko. In fact, nobody uses the first line any more. Cut down the first line. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 4 ++-- scripts/adjust_autoksyms.sh | 4 ++-- scripts/mod/sumversion.c | 9 ++------- 3 files changed, 6 insertions(+), 11 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index c6dfcc028f56..9f37f203882f 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -274,7 +274,7 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) - @{ echo $(@:.o=.ko); echo $@; \ + @{ echo $@; \ $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) quiet_cmd_cc_lst_c = MKLST $@ @@ -456,7 +456,7 @@ quiet_cmd_link_multi-m = LD [M] $@ $(multi-used-m): FORCE $(call if_changed,link_multi-m) - @{ echo $(@:.o=.ko); echo $(filter %.o,$^); \ + @{ echo $(filter %.o,$^); \ $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) diff --git a/scripts/adjust_autoksyms.sh b/scripts/adjust_autoksyms.sh index 2e4a7320bfb4..a904bf1f5e67 100755 --- a/scripts/adjust_autoksyms.sh +++ b/scripts/adjust_autoksyms.sh @@ -8,7 +8,7 @@ # # Create/update the include/generated/autoksyms.h file from the list -# of all module's needed symbols as recorded on the third line of *.mod files. +# of all module's needed symbols as recorded on the second line of *.mod files. # # For each symbol being added or removed, the corresponding dependency # file's timestamp is updated to force a rebuild of the affected source @@ -47,7 +47,7 @@ cat > "$new_ksyms_file" << EOT EOT sed 's/ko$/mod/' modules.order | -xargs -n1 sed -n -e '3{s/ /\n/g;/^$/!p;}' -- | +xargs -n1 sed -n -e '2{s/ /\n/g;/^$/!p;}' -- | sort -u | sed -e 's/\(.*\)/#define __KSYM_\1 1/' >> "$new_ksyms_file" diff --git a/scripts/mod/sumversion.c b/scripts/mod/sumversion.c index 166f3fa247a9..63062024ce0e 100644 --- a/scripts/mod/sumversion.c +++ b/scripts/mod/sumversion.c @@ -398,7 +398,7 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) char *sources, *end, *fname; char filelist[PATH_MAX + 1]; - /* objects for a module are listed in the second line of *.mod file. */ + /* objects for a module are listed in the first line of *.mod file. */ snprintf(filelist, sizeof(filelist), "%.*smod", (int)strlen(modname) - 1, modname); @@ -407,13 +407,8 @@ void get_src_version(const char *modname, char sum[], unsigned sumlen) /* not a module or .mod file missing - ignore */ return; - sources = strchr(file, '\n'); - if (!sources) { - warn("malformed versions file for %s\n", modname); - goto release; - } + sources = file; - sources++; end = strchr(sources, '\n'); if (!end) { warn("bad ending versions file for %s\n", modname); -- cgit v1.2.3 From 9f69a496f1001bd27c484da43da30b2cdc8e06ed Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Wed, 17 Jul 2019 15:18:00 +0900 Subject: kbuild: split out *.mod out of {single,multi}-used-m rules Currently, *.mod is created as a side-effect of obj-m. Split out *.mod as a dedicated build rule, which allows to unify the %.c -> %.o rule, and remove the single-used-m rule. This also makes the incremental build of allmodconfig faster because it saves $(NM) invocation when there is no change in the module. Signed-off-by: Masahiro Yamada --- scripts/Makefile.build | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/Makefile.build b/scripts/Makefile.build index 9f37f203882f..0d434d0afc0b 100644 --- a/scripts/Makefile.build +++ b/scripts/Makefile.build @@ -67,8 +67,10 @@ ifeq ($(CONFIG_MODULES)$(need-modorder),y1) modorder-target := $(obj)/modules.order endif +mod-targets := $(patsubst %.o, %.mod, $(obj-m)) + __build: $(if $(KBUILD_BUILTIN),$(builtin-target) $(lib-target) $(extra-y)) \ - $(if $(KBUILD_MODULES),$(obj-m) $(modorder-target)) \ + $(if $(KBUILD_MODULES),$(obj-m) $(mod-targets) $(modorder-target)) \ $(subdir-ym) $(always) @: @@ -261,7 +263,7 @@ endef # List module undefined symbols (or empty line if not enabled) ifdef CONFIG_TRIM_UNUSED_KSYMS -cmd_undef_syms = $(NM) $@ | sed -n 's/^ *U //p' | xargs echo +cmd_undef_syms = $(NM) $< | sed -n 's/^ *U //p' | xargs echo else cmd_undef_syms = echo endif @@ -271,11 +273,15 @@ $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE $(call cmd,force_checksrc) $(call if_changed_rule,cc_o_c) -$(single-used-m): $(obj)/%.o: $(src)/%.c $(recordmcount_source) $(objtool_dep) FORCE - $(call cmd,force_checksrc) - $(call if_changed_rule,cc_o_c) - @{ echo $@; \ - $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) +cmd_mod = { \ + echo $(if $($*-objs)$($*-y)$($*-m), $(addprefix $(obj)/, $($*-objs) $($*-y) $($*-m)), $(@:.mod=.o)); \ + $(cmd_undef_syms); \ + } > $@ + +$(obj)/%.mod: $(obj)/%.o FORCE + $(call if_changed,mod) + +targets += $(mod-targets) quiet_cmd_cc_lst_c = MKLST $@ cmd_cc_lst_c = $(CC) $(c_flags) -g -c -o $*.o $< && \ @@ -456,8 +462,6 @@ quiet_cmd_link_multi-m = LD [M] $@ $(multi-used-m): FORCE $(call if_changed,link_multi-m) - @{ echo $(filter %.o,$^); \ - $(cmd_undef_syms); } > $(patsubst %.o,%.mod,$@) $(call multi_depend, $(multi-used-m), .o, -objs -y -m) targets += $(multi-used-m) -- cgit v1.2.3