diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/DocBook/libata.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/SubmitChecklist | 4 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 6 | ||||
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 7 | ||||
| -rw-r--r-- | Documentation/filesystems/9p.txt | 20 | ||||
| -rw-r--r-- | Documentation/filesystems/ntfs.txt | 2 | ||||
| -rw-r--r-- | Documentation/hwmon/w83793 | 8 | ||||
| -rw-r--r-- | Documentation/i386/boot.txt | 3 | ||||
| -rw-r--r-- | Documentation/kdump/kdump.txt | 49 | ||||
| -rw-r--r-- | Documentation/pci.txt | 702 | ||||
| -rw-r--r-- | Documentation/powerpc/mpc52xx-device-tree-bindings.txt | 6 | ||||
| -rw-r--r-- | Documentation/scsi/aacraid.txt | 66 | ||||
| -rw-r--r-- | Documentation/usb/CREDITS | 2 |
13 files changed, 670 insertions, 207 deletions
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index 07a635590b3..e2e24b4778d 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -883,7 +883,7 @@ and other resources, etc. </chapter> <chapter id="ataExceptions"> - <title>ATA errors & exceptions</title> + <title>ATA errors and exceptions</title> <para> This chapter tries to identify what error/exception conditions exist diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 2270efa1015..bfbb2718a27 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -72,3 +72,7 @@ kernel patches. If the new code is substantial, addition of subsystem-specific fault injection might be appropriate. + +22: Newly-added code has been compiled with `gcc -W'. This will generate + lots of noise, but is good for finding bugs like "warning: comparison + between signed and unsigned". diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 302d148c2e1..b0d0043f7c4 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -134,9 +134,9 @@ Do not send more than 15 patches at once to the vger mailing lists!!! Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets -a lot of e-mail, so typically you should do your best to -avoid- sending -him e-mail. +Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. +He gets a lot of e-mail, so typically you should do your best to -avoid- +sending him e-mail. Patches which are bug fixes, are "obvious" changes, or similarly require little discussion should be sent or CC'd to Linus. Patches diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index fc532395d11..0ba6af02cda 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -318,3 +318,10 @@ Why: /proc/acpi/button has been replaced by events to the input layer Who: Len Brown <len.brown@intel.com> --------------------------- + +What: JFFS (version 1) +When: 2.6.21 +Why: Unmaintained for years, superceded by JFFS2 for years. +Who: Jeff Garzik <jeff@garzik.org> + +--------------------------- diff --git a/Documentation/filesystems/9p.txt b/Documentation/filesystems/9p.txt index 43b89c214d2..4d075a4558f 100644 --- a/Documentation/filesystems/9p.txt +++ b/Documentation/filesystems/9p.txt @@ -73,8 +73,22 @@ OPTIONS RESOURCES ========= -The Linux version of the 9p server is now maintained under the npfs project -on sourceforge (http://sourceforge.net/projects/npfs). +Our current recommendation is to use Inferno (http://www.vitanuova.com/inferno) +as the 9p server. You can start a 9p server under Inferno by issuing the +following command: + ; styxlisten -A tcp!*!564 export '#U*' + +The -A specifies an unauthenticated export. The 564 is the port # (you may +have to choose a higher port number if running as a normal user). The '#U*' +specifies exporting the root of the Linux name space. You may specify a +subset of the namespace by extending the path: '#U*'/tmp would just export +/tmp. For more information, see the Inferno manual pages covering styxlisten +and export. + +A Linux version of the 9p server is now maintained under the npfs project +on sourceforge (http://sourceforge.net/projects/npfs). There is also a +more stable single-threaded version of the server (named spfs) available from +the same CVS repository. There are user and developer mailing lists available through the v9fs project on sourceforge (http://sourceforge.net/projects/v9fs). @@ -96,5 +110,5 @@ STATUS The 2.6 kernel support is working on PPC and x86. -PLEASE USE THE SOURCEFORGE BUG-TRACKER TO REPORT PROBLEMS. +PLEASE USE THE KERNEL BUGZILLA TO REPORT PROBLEMS. (http://bugzilla.kernel.org) diff --git a/Documentation/filesystems/ntfs.txt b/Documentation/filesystems/ntfs.txt index 13ba649bda7..81779068b09 100644 --- a/Documentation/filesystems/ntfs.txt +++ b/Documentation/filesystems/ntfs.txt @@ -457,6 +457,8 @@ ChangeLog Note, a technical ChangeLog aimed at kernel hackers is in fs/ntfs/ChangeLog. +2.1.28: + - Fix a deadlock. 2.1.27: - Implement page migration support so the kernel can move memory used by NTFS files and directories around for management purposes. diff --git a/Documentation/hwmon/w83793 b/Documentation/hwmon/w83793 index 45e5408340e..51171a83165 100644 --- a/Documentation/hwmon/w83793 +++ b/Documentation/hwmon/w83793 @@ -45,18 +45,14 @@ This driver implements support for Winbond W83793G/W83793R chips. temp5-6 have a 1 degree Celsiis resolution. * Temperature sensor types - Temp1-4 have 3 possible types. It can be read from (and written to) + Temp1-4 have 2 possible types. It can be read from (and written to) temp[1-4]_type. - - If the value of 0, the related temperature channel stops - monitoring. - If the value is 3, it starts monitoring using a remote termal diode (default). - - If the value is 5, it starts monitoring using the temperature sensor - in AMD CPU and get result by AMDSI. - If the value is 6, it starts monitoring using the temperature sensor in Intel CPU and get result by PECI. Temp5-6 can be connected to external thermistors (value of - temp[5-6]_type is 4). They can also be disabled (value is 0). + temp[5-6]_type is 4). * Alarm mechanism For voltage sensors, an alarm triggers if the measured value is below diff --git a/Documentation/i386/boot.txt b/Documentation/i386/boot.txt index 9575de300a6..38fe1f03fb1 100644 --- a/Documentation/i386/boot.txt +++ b/Documentation/i386/boot.txt @@ -2,7 +2,7 @@ ---------------------------- H. Peter Anvin <hpa@zytor.com> - Last update 2006-11-17 + Last update 2007-01-26 On the i386 platform, the Linux kernel uses a rather complicated boot convention. This has evolved partially due to historical aspects, as @@ -186,6 +186,7 @@ filled out, however: 7 GRuB 8 U-BOOT 9 Xen + A Gujin Please contact <hpa@zytor.com> if you need a bootloader ID value assigned. diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 5af6676a88f..07330681834 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -17,7 +17,7 @@ You can use common Linux commands, such as cp and scp, to copy the memory image to a dump file on the local disk, or across the network to a remote system. -Kdump and kexec are currently supported on the x86, x86_64, ppc64 and IA64 +Kdump and kexec are currently supported on the x86, x86_64, ppc64 and ia64 architectures. When the system kernel boots, it reserves a small section of memory for @@ -61,7 +61,12 @@ Install kexec-tools 2) Download the kexec-tools user-space package from the following URL: -http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools-testing-20061214.tar.gz +http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools-testing.tar.gz + +This is a symlink to the latest version, which at the time of writing is +20061214, the only release of kexec-tools-testing so far. As other versions +are made released, the older onese will remain available at +http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/ Note: Latest kexec-tools-testing git tree is available at @@ -71,11 +76,11 @@ http://www.kernel.org/git/?p=linux/kernel/git/horms/kexec-tools-testing.git;a=su 3) Unpack the tarball with the tar command, as follows: - tar xvpzf kexec-tools-testing-20061214.tar.gz + tar xvpzf kexec-tools-testing.tar.gz -4) Change to the kexec-tools-1.101 directory, as follows: +4) Change to the kexec-tools directory, as follows: - cd kexec-tools-testing-20061214 + cd kexec-tools-testing-VERSION 5) Configure the package, as follows: @@ -224,7 +229,23 @@ Dump-capture kernel config options (Arch Dependent, ppc64) Dump-capture kernel config options (Arch Dependent, ia64) ---------------------------------------------------------- -(To be filled) + +- No specific options are required to create a dump-capture kernel + for ia64, other than those specified in the arch idependent section + above. This means that it is possible to use the system kernel + as a dump-capture kernel if desired. + + The crashkernel region can be automatically placed by the system + kernel at run time. This is done by specifying the base address as 0, + or omitting it all together. + + crashkernel=256M@0 + or + crashkernel=256M + + If the start address is specified, note that the start address of the + kernel will be aligned to 64Mb, so if the start address is not then + any space below the alignment point will be wasted. Boot into System Kernel @@ -243,6 +264,10 @@ Boot into System Kernel On ppc64, use "crashkernel=128M@32M". + On ia64, 256M@256M is a generous value that typically works. + The region may be automatically placed on ia64, see the + dump-capture kernel config option notes above. + Load the Dump-capture Kernel ============================ @@ -261,7 +286,8 @@ For x86_64: For ppc64: - Use vmlinux For ia64: - (To be filled) + - Use vmlinux or vmlinuz.gz + If you are using a uncompressed vmlinux image then use following command to load dump-capture kernel. @@ -277,18 +303,19 @@ to load dump-capture kernel. --initrd=<initrd-for-dump-capture-kernel> \ --append="root=<root-dev> <arch-specific-options>" +Please note, that --args-linux does not need to be specified for ia64. +It is planned to make this a no-op on that architecture, but for now +it should be omitted + Following are the arch specific command line options to be used while loading dump-capture kernel. -For i386 and x86_64: +For i386, x86_64 and ia64: "init 1 irqpoll maxcpus=1" For ppc64: "init 1 maxcpus=1 noirqdistrib" -For IA64 - (To be filled) - Notes on loading the dump-capture kernel: diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 2b395e47896..fd5028eca13 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -1,142 +1,231 @@ - How To Write Linux PCI Drivers - by Martin Mares <mj@ucw.cz> on 07-Feb-2000 + How To Write Linux PCI Drivers + + by Martin Mares <mj@ucw.cz> on 07-Feb-2000 + updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The world of PCI is vast and it's full of (mostly unpleasant) surprises. -Different PCI devices have different requirements and different bugs -- -because of this, the PCI support layer in Linux kernel is not as trivial -as one would wish. This short pamphlet tries to help all potential driver -authors find their way through the deep forests of PCI handling. +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, "features"), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of "Linux Device Drivers" +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to "bit rot". +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. + 0. Structure of PCI drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There exist two kinds of PCI drivers: new-style ones (which leave most of -probing for devices to the PCI layer and support online insertion and removal -of devices [thus supporting PCI, hot-pluggable PCI and CardBus in a single -driver]) and old-style ones which just do all the probing themselves. Unless -you have a very good reason to do so, please don't use the old way of probing -in any new code. After the driver finds the devices it wishes to operate -on (either the old or the new way), it needs to perform the following steps: +PCI drivers "discover" PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching "description" will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: Enable the device - Access device configuration space - Discover resources (addresses and IRQ numbers) provided by the device - Allocate these resources - Communicate with the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines + +When done using the device, and perhaps the module needs to be unloaded, +the driver needs to take the follow steps: + Disable the device from generating IRQs + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and coherent) + Unregister from other subsystems (e.g. scsi or netdev) + Release MMIO/IOP resources Disable the device -Most of these topics are covered by the following sections, for the rest -look at <linux/pci.h>, it's hopefully well commented. +Most of these topics are covered in the following sections. +For the rest look at LDD3 or <linux/pci.h> . If the PCI subsystem is not configured (CONFIG_PCI is not set), most of -the functions described below are defined as inline functions either completely -empty or just returning an appropriate error codes to avoid lots of ifdefs -in the drivers. +the PCI functions described below are defined as inline functions either +completely empty or just returning an appropriate error codes to avoid +lots of ifdefs in the drivers. + -1. New-style drivers -~~~~~~~~~~~~~~~~~~~~ -The new-style drivers just call pci_register_driver during their initialization -with a pointer to a structure describing the driver (struct pci_driver) which -contains: +1. pci_register_driver() call +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - name Name of the driver +PCI device drivers call pci_register_driver() during their +initialization with a pointer to a structure describing the driver +(struct pci_driver): + + field name Description + ---------- ------------------------------------------------------ id_table Pointer to table of device ID's the driver is interested in. Most drivers should export this table using MODULE_DEVICE_TABLE(pci,...). - probe Pointer to a probing function which gets called (during - execution of pci_register_driver for already existing - devices or later if a new device gets inserted) for all - PCI devices which match the ID table and are not handled - by the other drivers yet. This function gets passed a - pointer to the pci_dev structure representing the device - and also which entry in the ID table did the device - match. It returns zero when the driver has accepted the - device or an error code (negative number) otherwise. - This function always gets called from process context, - so it can sleep. - remove Pointer to a function which gets called whenever a - device being handled by this driver is removed (either - during deregistration of the driver or when it's - manually pulled out of a hot-pluggable slot). This - function always gets called from process context, so it - can sleep. - save_state Save a device's state before it's suspend. + + probe This probing function gets called (during execution + of pci_register_driver() for already existing + devices or later if a new device gets inserted) for + all PCI devices which match the ID table and are not + "owned" by the other drivers yet. This function gets + passed a "struct pci_dev *" for each device whose + entry in the ID table matches the device. The probe + function returns zero when the driver chooses to + take "ownership" of the device or an error code + (negative number) otherwise. + The probe function always gets called from process + context, so it can sleep. + + remove The remove() function gets called whenever a device + being handled by this driver is removed (either during + deregistration of the driver or when it's manually + pulled out of a hot-pluggable slot). + The remove function always gets called from process + context, so it can sleep. + suspend Put device into low power state. + suspend_late Put device into low power state. + + resume_early Wake device from low power state. resume Wake device from low power state. + + (Please see Documentation/power/pci.txt for descriptions + of PCI Power Management and the related functions.) + enable_wake Enable device to generate wake events from a low power state. - (Please see Documentation/power/pci.txt for descriptions - of PCI Power Management and the related functions) + shutdown Hook into reboot_notifier_list (kernel/sys.c). + Intended to stop any idling DMA operations. + Useful for enabling wake-on-lan (NIC) or changing + the power state of a device before reboot. + e.g. drivers/net/e100.c. + + err_handler See Documentation/pci-error-recovery.txt + + multithread_probe Enable multi-threaded probe/scan. Driver must + provide its own locking/syncronization for init + operations if this is enabled. + -The ID table is an array of struct pci_device_id ending with a all-zero entry. -Each entry consists of: +The ID table is an array of struct pci_device_id entries ending with an +all-zero entry. Each entry consists of: + + vendor,device Vendor and device ID to match (or PCI_ANY_ID) - vendor, device Vendor and device ID to match (or PCI_ANY_ID) subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) - subdevice - class, Device class to match. The class_mask tells which bits - class_mask of the class are honored during the comparison. + subdevice, + + class Device class, subclass, and "interface" to match. + See Appendix D of the PCI Local Bus Spec or + include/linux/pci_ids.h for a full list of classes. + Most drivers do not need to specify class/class_mask + as vendor/device is normally sufficient. + + class_mask limit which sub-fields of the class field are compared. + See drivers/scsi/sym53c8xx_2/ for example of usage. + driver_data Data private to the driver. + Most drivers don't need to use driver_data field. + Best practice is to use driver_data as an index + into a static list of equivalent device types, + instead of using it as a pointer. -Most drivers don't need to use the driver_data field. Best practice -for use of driver_data is to use it as an index into a static list of -equivalent device types, not to use it as a pointer. -Have a table entry {PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID} -to have probe() called for every PCI device known to the system. +Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up +a pci_device_id table. -New PCI IDs may be added to a device driver at runtime by writing -to the file /sys/bus/pci/drivers/{driver}/new_id. When added, the -driver will probe for all devices it can support. +New PCI IDs may be added to a device driver pci_ids table at runtime +as shown below: echo "vendor device subvendor subdevice class class_mask driver_data" > \ - /sys/bus/pci/drivers/{driver}/new_id -where all fields are passed in as hexadecimal values (no leading 0x). -Users need pass only as many fields as necessary; vendor, device, -subvendor, and subdevice fields default to PCI_ANY_ID (FFFFFFFF), -class and classmask fields default to 0, and driver_data defaults to -0UL. Device drivers must initialize use_driver_data in the dynids struct -in their pci_driver struct prior to calling pci_register_driver in order -for the driver_data field to get passed to the driver. Otherwise, only a -0 is passed in that field. +/sys/bus/pci/drivers/{driver}/new_id + +All fields are passed in as hexadecimal values (no leading 0x). +Users need pass only as many fields as necessary: + o vendor, device, subvendor, and subdevice fields default + to PCI_ANY_ID (FFFFFFFF), + o class and classmask fields default to 0 + o driver_data defaults to 0UL. + +Once added, the driver probe routine will be invoked for any unclaimed +PCI devices listed in its (newly updated) pci_ids list. When the driver exits, it just calls pci_unregister_driver() and the PCI layer automatically calls the remove hook for all devices handled by the driver. + +1.1 "Attributes" for driver functions/data + Please mark the initialization and cleanup functions where appropriate (the corresponding macros are defined in <linux/init.h>): __init Initialization code. Thrown away after the driver initializes. __exit Exit code. Ignored for non-modular drivers. - __devinit Device initialization code. Identical to __init if - the kernel is not compiled with CONFIG_HOTPLUG, normal - function otherwise. + + + __devinit Device initialization code. + Identical to __init if the kernel is not compiled + with CONFIG_HOTPLUG, normal function otherwise. __devexit The same for __exit. -Tips: - The module_init()/module_exit() functions (and all initialization - functions called only from these) should be marked __init/exit. - The struct pci_driver shouldn't be marked with any of these tags. - The ID table array should be marked __devinitdata. - The probe() and remove() functions (and all initialization - functions called only from these) should be marked __devinit/exit. - If you are sure the driver is not a hotplug driver then use only - __init/exit __initdata/exitdata. +Tips on when/where to use the above attributes: + o The module_init()/module_exit() functions (and all + initialization functions called _only_ from these) + should be marked __init/__exit. - Pointers to functions marked as __devexit must be created using - __devexit_p(function_name). That will generate the function - name or NULL if the __devexit function will be discarded. + o Do not mark the struct pci_driver. + o The ID table array should be marked __devinitdata. -2. How to find PCI devices manually (the old style) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -PCI drivers not using the pci_register_driver() interface search -for PCI devices manually using the following constructs: + o The probe() and remove() functions should be marked __devinit + and __devexit respectively. All initialization functions + exclusively called by the probe() routine, can be marked __devinit. + Ditto for remove() and __devexit. + + o If mydriver_probe() is marked with __devinit(), then all address + references to mydriver_probe must use __devexit_p(mydriver_probe) + (in the struct pci_driver declaration for example). + __devexit_p() will generate the function name _or_ NULL if the + function will be discarded. For an example, see drivers/net/tg3.c. + + o Do NOT mark a function if you are not sure which mark to use. + Better to not mark the function than mark the function wrong. + + + +2. How to find PCI devices manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PCI drivers should have a really good reason for not using the +pci_register_driver() interface to search for PCI devices. +The main reason PCI devices are controlled by multiple drivers +is because one PCI device implements several different HW services. +E.g. combined serial/parallel port/floppy controller. + +A manual search may be performed using the following constructs: Searching by vendor and device ID: @@ -150,87 +239,311 @@ Searching by class ID (iterate in a similar way): Searching by both vendor/device and subsystem vendor/device ID: - pci_get_subsys(VENDOR_ID, DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). + pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). - You can use the constant PCI_ANY_ID as a wildcard replacement for +You can use the constant PCI_ANY_ID as a wildcard replacement for VENDOR_ID or DEVICE_ID. This allows searching for any device from a specific vendor, for example. - These functions are hotplug-safe. They increment the reference count on +These functions are hotplug-safe. They increment the reference count on the pci_dev that they return. You must eventually (possibly at module unload) decrement the reference count on these devices by calling pci_dev_put(). -3. Enabling and disabling devices -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Before you do anything with the device you've found, you need to enable -it by calling pci_enable_device() which enables I/O and memory regions of -the device, allocates an IRQ if necessary, assigns missing resources if -needed and wakes up the device if it was in suspended state. Please note -that this function can fail. - If you want to use the device in bus mastering mode, call pci_set_master() -which enables the bus master bit in PCI_COMMAND register and also fixes -the latency timer value if it's set to something bogus by the BIOS. +3. Device Initialization Steps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As noted in the introduction, most PCI drivers need the following steps +for device initialization: - If you want to use the PCI Memory-Write-Invalidate transaction, + Enable the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines. + +The driver can access PCI config space registers at any time. +(Well, almost. When running BIST, config space can go away...but +that will just result in a PCI Bus Master Abort and config reads +will return garbage). + + +3.1 Enable the PCI device +~~~~~~~~~~~~~~~~~~~~~~~~~ +Before touching any device registers, the driver needs to enable +the PCI device by calling pci_enable_device(). This will: + o wake up the device if it was in suspended state, + o allocate I/O and memory regions of the device (if BIOS did not), + o allocate an IRQ (if BIOS did not). + +NOTE: pci_enable_device() can fail! Check the return value. +NOTE2: Also see pci_enable_device_bars() below. Drivers can + attempt to enable only a subset of BARs they need. + +[ OS BUG: we don't check resource allocations before enabling those + resources. The sequence would make more sense if we called + pci_request_resources() before calling pci_enable_device(). + Currently, the device drivers can't detect the bug when when two + devices have been allocated the same range. This is not a common + problem and unlikely to get fixed soon. + + This has been discussed before but not changed as of 2.6.19: + http://lkml.org/lkml/2006/3/2/194 +] + +pci_set_master() will enable DMA by setting the bus master bit +in the PCI_COMMAND register. It also fixes the latency timer value if +it's set to something bogus by the BIOS. + +If the PCI device can use the PCI Memory-Write-Invalidate transaction, call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval and also ensures that the cache line size register is set correctly. -Make sure to check the return value of pci_set_mwi(), not all architectures -may support Memory-Write-Invalidate. +Check the return value of pci_set_mwi() as not all architectures +or chip-sets may support Memory-Write-Invalidate. + + +3.2 Request MMIO/IOP resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Memory (MMIO), and I/O port addresses should NOT be read directly +from the PCI device config space. Use the values in the pci_dev structure +as the PCI "bus address" might have been remapped to a "host physical" +address by the arch/chip-set specific kernel support. - If your driver decides to stop using the device (e.g., there was an -error while setting it up or the driver module is being unloaded), it -should call pci_disable_device() to deallocate any IRQ resources, disable -PCI bus-mastering, etc. You should not do anything with the device after +See Documentation/IO-mapping.txt for how to access device registers +or device memory. + +The device driver needs to call pci_request_region() to verify +no other device is already using the same address resource. +Conversely, drivers should call pci_release_region() AFTER calling pci_disable_device(). +The idea is to prevent two devices colliding on the same address range. + +[ See OS BUG comment above. Currently (2.6.19), The driver can only + determine MMIO and IO Port resource availability _after_ calling + pci_enable_device(). ] + +Generic flavors of pci_request_region() are request_mem_region() +(for MMIO ranges) and request_region() (for IO Port ranges). +Use these for address resources that are not described by "normal" PCI +BARs. + +Also see pci_request_selected_regions() below. + + +3.3 Set the DMA mask size +~~~~~~~~~~~~~~~~~~~~~~~~~ +[ If anything below doesn't make sense, please refer to + Documentation/DMA-API.txt. This section is just a reminder that + drivers need to indicate DMA capabilities of the device and is not + an authoritative source for DMA interfaces. ] + +While all drivers should explicitly indicate the DMA capability +(e.g. 32 or 64 bit) of the PCI bus master, devices with more than +32-bit bus master capability for streaming data need the driver +to "register" this capability by calling pci_set_dma_mask() with +appropriate parameters. In general this allows more efficient DMA +on systems where System RAM exists above 4G _physical_ address. + +Drivers for all PCI-X and PCIe compliant devices must call +pci_set_dma_mask() as they are 64-bit DMA devices. + +Similarly, drivers must also "register" this capability if the device +can directly address "consistent memory" in System RAM above 4G physical +address by calling pci_set_consistent_dma_mask(). +Again, this includes drivers for all PCI-X and PCIe compliant devices. +Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are +64-bit DMA capable for payload ("streaming") data but not control +("consistent") data. + + +3.4 Setup shared control data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) +memory. See Documentation/DMA-API.txt for a full description of +the DMA APIs. This section is just a reminder that it needs to be done +before enabling DMA on the device. + + +3.5 Initialize device registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers will need specific "capability" fields programmed +or other "vendor specific" register initialized or reset. +E.g. clearing pending interrupts. + + +3.6 Register IRQ handler +~~~~~~~~~~~~~~~~~~~~~~~~ +While calling request_irq() is the the last step described here, +this is often just another intermediate step to initialize a device. +This step can often be deferred until the device is opened for use. + +All interrupt handlers for IRQ lines should be registered with IRQF_SHARED +and use the devid to map IRQs to devices (remember that all PCI IRQ lines +can be shared). + +request_irq() will associate an interrupt handler and device handle +with an interrupt number. Historically interrupt numbers represent +IRQ lines which run from the PCI device to the Interrupt controller. +With MSI and MSI-X (more below) the interrupt number is a CPU "vector". + +request_irq() also enables the interrupt. Make sure the device is +quiesced and does not have any interrupts pending before registering +the interrupt handler. + +MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" +which deliver interrupts to the CPU via a DMA write to a Local APIC. +The fundamental difference between MSI and MSI-X is how multiple +"vectors" get allocated. MSI requires contiguous blocks of vectors +while MSI-X can allocate several individual ones. + +MSI capability can be enabled by calling pci_enable_msi() or +pci_enable_msix() before calling request_irq(). This causes +the PCI support to program CPU vector data into the PCI device +capability registers. + +If your PCI device supports both, try to enable MSI-X first. +Only one can be enabled at a time. Many architectures, chip-sets, +or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix +will fail. This is important to note since many drivers have +two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs. +They choose which handler to register with request_irq() based on the +return value from pci_enable_msi/msix(). + +There are (at least) two really good reasons for using MSI: +1) MSI is an exclusive interrupt vector by definition. + This means the interrupt handler doesn't have to verify + its device caused the interrupt. + +2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed + to be visible to the host CPU(s) when the MSI is delivered. This + is important for both data coherency and avoiding stale control data. + This guarantee allows the driver to omit MMIO reads to flush + the DMA stream. + +See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples +of MSI/MSI-X usage. + + + +4. PCI device shutdown +~~~~~~~~~~~~~~~~~~~~~~~ + +When a PCI device driver is being unloaded, most of the following +steps need to be performed: + + Disable the device from generating IRQs |