diff options
Diffstat (limited to 'Documentation')
28 files changed, 1238 insertions, 360 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 0ad6dcb5d45..9069189e78e 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -682,6 +682,24 @@ result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. + Chapter 17: Don't re-invent the kernel macros + +The header file include/linux/kernel.h contains a number of macros that +you should use, rather than explicitly coding some variant of them yourself. +For example, if you need to calculate the length of an array, take advantage +of the macro + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +There are also min() and max() macros that do strict type checking if you +need them. Feel free to peruse that header file to see what else is already +defined that you shouldn't reproduce in your code. + + Appendix I: References diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 36526a1e76d..867608ab3ca 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -53,8 +53,8 @@ installmandocs: mandocs ### #External programs used -KERNELDOC = scripts/kernel-doc -DOCPROC = scripts/basic/docproc +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/basic/docproc XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl #XMLTOFLAGS += --skip-validation 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/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt index dda7ecdde87..28d014714ab 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt @@ -76,6 +76,15 @@ Machines A S3C2410 based PDA from Acer. There is a Wiki page at http://handhelds.org/moin/moin.cgi/AcerN30Documentation . + AML M5900 + + American Microsystems' M5900 + + Nex Vision Nexcoder + Nex Vision Otom + + Two machines by Nex Vision + Adding New Machines ------------------- @@ -115,6 +124,10 @@ RTC Support for the onboard RTC unit, including alarm function. + This has recently been upgraded to use the new RTC core, + and the module has been renamed to rtc-s3c to fit in with + the new rtc naming scheme. + Watchdog -------- @@ -128,7 +141,7 @@ NAND The current kernels now have support for the s3c2410 NAND controller. If there are any problems the latest linux-mtd - CVS can be found from http://www.linux-mtd.infradead.org/ + code can be found from http://www.linux-mtd.infradead.org/ Serial @@ -168,6 +181,21 @@ Suspend to RAM See Suspend.txt for more information. +SPI +--- + + SPI drivers are available for both the in-built hardware + (although there is no DMA support yet) and a generic + GPIO based solution. + + +LEDs +---- + + There is support for GPIO based LEDs via a platform driver + in the LED subsystem. + + Platform Data ------------- diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index c6c9a9c10d7..3adaace328a 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -946,6 +946,13 @@ elevator_merged_fn called when a request in the scheduler has been scheduler for example, to reposition the request if its sorting order has changed. +elevator_allow_merge_fn called whenever the block layer determines + that a bio can be merged into an existing + request safely. The io scheduler may still + want to stop a merge at this point if it + results in some sort of conflict internally, + this hook allows it to do that. + elevator_dispatch_fn fills the dispatch queue with ready requests. I/O schedulers are free to postpone requests by not filling the dispatch queue unless @force diff --git a/Documentation/cachetlb.txt b/Documentation/cachetlb.txt index 73e794f0ff0..debf6813934 100644 --- a/Documentation/cachetlb.txt +++ b/Documentation/cachetlb.txt @@ -373,14 +373,15 @@ maps this page at its virtual address. likely that you will need to flush the instruction cache for copy_to_user_page(). - void flush_anon_page(struct page *page, unsigned long vmaddr) + void flush_anon_page(struct vm_area_struct *vma, struct page *page, + unsigned long vmaddr) When the kernel needs to access the contents of an anonymous page, it calls this function (currently only get_user_pages()). Note: flush_dcache_page() deliberately doesn't work for an anonymous page. The default implementation is a nop (and should remain so for all coherent architectures). For incoherent architectures, it should flush - the cache of the page at vmaddr in the current user process. + the cache of the page at vmaddr. void flush_kernel_dcache_page(struct page *page) When the kernel needs to modify a user page is has obtained diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 30f3c8c9c12..b3d1ce7e3ba 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -226,6 +226,23 @@ Who: Jean Delvare <khali@linux-fr.org> --------------------------- +What: i2c_adapter.dev + i2c_adapter.list +When: July 2007 +Why: Superfluous, given i2c_adapter.class_dev: + * The "dev" was a stand-in for the physical device node that legacy + drivers would not have; but now it's almost always present. Any + remaining legacy drivers must upgrade (they now trigger warnings). + * The "list" duplicates class device children. + The delay in removing this is so upgraded lm_sensors and libsensors + can get deployed. (Removal causes minor changes in the sysfs layout, + notably the location of the adapter type name and parenting the i2c + client hardware directly from their controller.) +Who: Jean Delvare <khali@linux-fr.org>, + David Brownell <dbrownell@users.sourceforge.net> + +--------------------------- + What: IPv4 only connection tracking/NAT/helpers When: 2.6.22 Why: The new layer 3 independant connection tracking replaces the old @@ -256,3 +273,63 @@ Why: Speedstep-centrino driver with ACPI hooks and acpi-cpufreq driver are Who: Venkatesh Pallipadi <venkatesh.pallipadi@intel.com> --------------------------- + +<<<<<<< test:Documentation/feature-removal-schedule.txt +What: ACPI hotkey driver (CONFIG_ACPI_HOTKEY) +When: 2.6.21 +Why: hotkey.c was an attempt to consolidate multiple drivers that use + ACPI to implement hotkeys. However, hotkeys are not documented + in the ACPI specification, so the drivers used undocumented + vendor-specific hooks and turned out to be more different than + the same. + + Further, the keys and the features supplied by each platform + are different, so there will always be a need for + platform-specific drivers. + + So the new plan is to delete hotkey.c and instead, work on the + platform specific drivers to try to make them look the same + to the user when they supply the same features. + + hotkey.c has always depended on CONFIG_EXPERIMENTAL + +Who: Len Brown <len.brown@intel.com> + +--------------------------- + +What: /sys/firmware/acpi/namespace +When: 2.6.21 +Why: The ACPI namespace is effectively the symbol list for + the BIOS. The device names are completely arbitrary + and have no place being exposed to user-space. + + For those interested in the BIOS ACPI namespace, + the BIOS can be extracted and disassembled with acpidump + and iasl as documented in the pmtools package here: + http://ftp.kernel.org/pub/linux/kernel/people/lenb/acpi/utils +Who: Len Brown <len.brown@intel.com> + +--------------------------- + +What: ACPI procfs interface +When: July 2007 +Why: After ACPI sysfs conversion, ACPI attributes will be duplicated + in sysfs and the ACPI procfs interface should be removed. +Who: Zhang Rui <rui.zhang@intel.com> + +--------------------------- + +What: /proc/acpi/button +When: August 2007 +Why: /proc/acpi/button has been replaced by events to the input layer + since 2.6.20. +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/Locking b/Documentation/filesystems/Locking index 790ef6fbe49..28bfea75bcf 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -171,6 +171,7 @@ prototypes: int (*releasepage) (struct page *, int); int (*direct_IO)(int, struct kiocb *, const struct iovec *iov, loff_t offset, unsigned long nr_segs); + int (*launder_page) (struct page *); locking rules: All except set_page_dirty may block @@ -188,6 +189,7 @@ bmap: yes invalidatepage: no yes releasepage: no yes direct_IO: no +launder_page: no yes ->prepare_write(), ->commit_write(), ->sync_page() and ->readpage() may be called from the request handler (/dev/loop). @@ -281,6 +283,12 @@ buffers from the page in preparation for freeing it. It returns zero to indicate that the buffers are (or may be) freeable. If ->releasepage is zero, the kernel assumes that the fs has no private interest in the buffers. + ->launder_page() may be called prior to releasing a page if +it is still found to be dirty. It returns zero if the page was successfully +cleaned, or an error value if not. Note that in order to prevent the page +getting mapped back in and redirtied, it needs to be kept locked +across the entire operation. + Note: currently almost all instances of address_space methods are using BKL for internal serialization and that's one of the worst sources of contention. Normally they are calling library functions (in fs/buffer.c) diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.txt index 345392c4cae..397a41adb4c 100644 --- a/Documentation/filesystems/fuse.txt +++ b/Documentation/filesystems/fuse.txt @@ -94,8 +94,8 @@ Mount options filesystem is free to implement it's access policy or leave it to the underlying file access mechanism (e.g. in case of network filesystems). This option enables permission checking, restricting - access based on file mode. This is option is usually useful - together with the 'allow_other' mount option. + access based on file mode. It is usually useful together with the + 'allow_other' mount option. 'allow_other' 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/ibm-acpi.txt b/Documentation/ibm-acpi.txt index e50595bfd8e..0132d363feb 100644 --- a/Documentation/ibm-acpi.txt +++ b/Documentation/ibm-acpi.txt @@ -398,25 +398,67 @@ Temperature sensors -- /proc/acpi/ibm/thermal Most ThinkPads include six or more separate temperature sensors but only expose the CPU temperature through the standard ACPI methods. -This feature shows readings from up to eight different sensors. Some -readings may not be valid, e.g. may show large negative values. For -example, on the X40, a typical output may be: +This feature shows readings from up to eight different sensors on older +ThinkPads, and it has experimental support for up to sixteen different +sensors on newer ThinkPads. Readings from sensors that are not available +return -128. +No commands can be written to this file. + +EXPERIMENTAL: The 16-sensors feature is marked EXPERIMENTAL because the +implementation directly accesses hardware registers and may not work as +expected. USE WITH CAUTION! To use this feature, you need to supply the +experimental=1 parameter when loading the module. When EXPERIMENTAL +mode is enabled, reading the first 8 sensors on newer ThinkPads will +also use an new experimental thermal sensor access mode. + +For example, on the X40, a typical output may be: temperatures: 42 42 45 41 36 -128 33 -128 -Thomas Gruber took his R51 apart and traced all six active sensors in -his laptop (the location of sensors may vary on other models): +EXPERIMENTAL: On the T43/p, a typical output may be: +temperatures: 48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128 + +The mapping of thermal sensors to physical locations varies depending on +system-board model (and thus, on ThinkPad model). + +http://thinkwiki.org/wiki/Thermal_Sensors is a public wiki page that +tries to track down these locations for various models. + +Most (newer?) models seem to follow this pattern: 1: CPU -2: Mini PCI Module -3: HDD +2: (depends on model) +3: (depends on model) 4: GPU -5: Battery -6: N/A -7: Battery -8: N/A +5: Main battery: main sensor +6: Bay battery: main sensor +7: Main battery: secondary sensor +8: Bay battery: secondary sensor +9-15: (depends on model) + +For the R51 (source: Thomas Gruber): +2: Mini-PCI +3: Internal HDD + +For the T43, T43/p (source: Shmidoax/Thinkwiki.org) +http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p +2: System board, left side (near PCMCIA slot), reported as HDAPS temp +3: PCMCIA slot +9: MCH (northbridge) to DRAM Bus +10: ICH (southbridge), under Mini-PCI card, under touchpad +11: Power regulator, underside of system board, below F2 key + +The A31 has a very atypical layout for the thermal sensors +(source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31) +1: CPU +2: Main Battery: main sensor +3: Power Converter +4: Bay Battery: main sensor +5: MCH (northbridge) +6: PCMCIA/ambient +7: Main Battery: secondary sensor +8: Bay Battery: secondary sensor -No commands can be written to this file. EXPERIMENTAL: Embedded controller register dump -- /proc/acpi/ibm/ecdump ------------------------------------------------------------------------ @@ -529,27 +571,57 @@ directly accesses hardware registers and may not work as expected. USE WITH CAUTION! To use this feature, you need to supply the experimental=1 parameter when loading the module. -This feature attempts to show the current fan speed. The speed is read -directly from the hardware registers of the embedded controller. This -is known to work on later R, T and X series ThinkPads but may show a -bogus value on other models. +This feature attempts to show the current fan speed, control mode and +other fan data that might be available. The speed is read directly +from the hardware registers of the embedded controller. This is known +to work on later R, T and X series ThinkPads but may show a bogus +value on other models. + +Most ThinkPad fans work in "levels". Level 0 stops the fan. The higher +the level, the higher the fan speed, although adjacent levels often map +to the same fan speed. 7 is the highest level, where the fan reaches +the maximum recommended speed. Level "auto" means the EC changes the +fan level according to some internal algorithm, usually based on +readings from the thermal sensors. Level "disengaged" means the EC +disables the speed-locked closed-loop fan control, and drives the fan as +fast as it can go, which might exceed hardware limits, so use this level +with caution. + +The fan usually ramps up or down slowly from one speed to another, +and it is normal for the EC to take several seconds to react to fan +commands. The fan may be enabled or disabled with the following commands: echo enable >/proc/acpi/ibm/fan echo disable >/proc/acpi/ibm/fan +Placing a fan on level 0 is the same as disabling it. Enabling a fan +will try to place it in a safe level if it is too slow or disabled. + WARNING WARNING WARNING: do not leave the fan disabled unless you are -monitoring the temperature sensor readings and you are ready to enable -it if necessary to avoid overheating. +monitoring all of the temperature sensor readings and you are ready to +enable it if necessary to avoid overheating. -The fan only runs if it's enabled *and* the various temperature -sensors which control it read high enough. On the X40, this seems to -depend on the CPU and HDD temperatures. Specifically, the fan is -turned on when either the CPU temperature climbs to 56 degrees or the -HDD temperature climbs to 46 degrees. The fan is turned off when the -CPU temperature drops to 49 degrees and the HDD temperature drops to -41 degrees. These thresholds cannot currently be controlled. +An enabled fan in level "auto" may stop spinning if the EC decides the +ThinkPad is cool enough and doesn't need the extra airflow. This is +normal, and the EC will spin the fan up if the varios thermal readings +rise too much. + +On the X40, this seems to depend on the CPU and HDD temperatures. +Specifically, the fan is turned on when either the CPU temperature +climbs to 56 degrees or the HDD temperature climbs to 46 degrees. The +fan is turned off when the CPU temperature drops to 49 degrees and the +HDD temperature drops to 41 degrees. These thresholds cannot +currently be controlled. + +The fan level can be controlled with the command: + + echo 'level <level>' > /proc/acpi/ibm/thermal + +Where <level> is an integer from 0 to 7, or one of the words "auto" +or "disengaged" (without the quotes). Not all ThinkPads support the +"auto" and "disengaged" levels. On the X31 and X40 (and ONLY on those models), the fan speed can be controlled to a certain degree. Once the fan is running, it can be @@ -562,12 +634,9 @@ about 3700 to about 7350. Values outside this range either do not have any effect or the fan speed eventually settles somewhere in that range. The fan cannot be stopped or started with this command. -On the 570, temperature readings are not available through this -feature and the fan control works a little differently. The fan speed -is reported in levels from 0 (off) to 7 (max) and can be controlled -with the following command: - - echo 'level <level>' > /proc/acpi/ibm/thermal +The ThinkPad's ACPI DSDT code will reprogram the fan on its own when +certain conditions are met. It will override any fan programming done +through ibm-acpi. EXPERIMENTAL: WAN -- /proc/acpi/ibm/wan --------------------------------------- @@ -601,6 +670,26 @@ example: modprobe ibm_acpi hotkey=enable,0xffff video=auto_disable +The ibm-acpi kernel driver can be programmed to revert the fan level +to a safe setting if userspace does not issue one of the fan commands: +"enable", "disable", "level" or "watchdog" within a configurable +ammount of time. To do this, use the "watchdog" command. + + echo 'watchdog <interval>' > /proc/acpi/ibm/fan + +Interval is the ammount of time in seconds to wait for one of the +above mentioned fan commands before reseting the fan level to a safe +one. If set to zero, the watchdog is disabled (default). When the +watchdog timer runs out, it does the exact equivalent of the "enable" +fan command. + +Note that the watchdog timer stops after it enables the fan. It will +be rearmed again automatically (using the same interval) when one of +the above mentioned fan commands is received. The fan watchdog is, +therefore, not suitable to protect against fan mode changes made +through means other than the "enable", "disable", and "level" fan +commands. + Example Configuration --------------------- diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 99f2d4d4bf7..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, and ppc64 +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 @@ -54,59 +54,69 @@ memory," in two ways: Setup and Installation ====================== -Install kexec-tools and the Kdump patch ---------------------------------------- +Install kexec-tools +------------------- 1) Login as the root user. 2) Download the kexec-tools user-space package from the following URL: - http://www.xmission.com/~ebiederm/files/kexec/kexec-tools-1.101.tar.gz +http://www.kernel.org/pub/linux/kernel/people/horms/kexec-tools/kexec-tools-testing.tar.gz -3) Unpack the tarball with the tar command, as follows: - - tar xvpzf kexec-tools-1.101.tar.gz - -4) Download the latest consolidated Kdump patch from the following URL: +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/ - http://lse.sourceforge.net/kdump/ +Note: Latest kexec-tools-testing git tree is available at - (This location is being used until all the user-space Kdump patches - are integrated with the kexec-tools package.) +git://git.kernel.org/pub/scm/linux/kernel/git/horms/kexec-tools-testing.git +or +http://www.kernel.org/git/?p=linux/kernel/git/horms/kexec-tools-testing.git;a=summary -5) Change to the kexec-tools-1.101 directory, as follows: +3) Unpack the tarball with the tar command, as follows: - cd kexec-tools-1.101 + tar xvpzf kexec-tools-testing.tar.gz -6) Apply the consolidated patch to the kexec-tools-1.101 source tree - with the patch command, as follows. (Modify the path to the downloaded - patch as necessary.) +4) Change to the kexec-tools directory, as follows: - patch -p1 < /path-to-kdump-patch/kexec-tools-1.101-kdump.patch + cd kexec-tools-testing-VERSION -7) Configure the package, as follows: +5) Configure the package, as follows: ./configure -8) Compile the package, as follows: +6) Compile the package, as follows: make -9) Install the package, as follows: +7) Install the package, as follows: make install -Download and build the system and dump-capture kernels ------------------------------------------------------- +Build the system and dump-capture kernels +----------------------------------------- +There are two possible methods of using Kdump. + +1) Build a separate custom dump-capture kernel for capturing the + kernel core dump. -Download the mainline (vanilla) kernel source code (2.6.13-rc1 or newer) -from http://www.kernel.org. Two kernels must be built: a system kernel -and a dump-capture kernel. Use the following steps to configure these -kernels with the necessary kexec and Kdump features: +2) Or use the system kernel binary itself as dump-capture kernel and there is + no need to build a separate dump-capture kernel. This is possible + only with the architecutres which support a relocatable kernel. As + of today i386 and ia64 architectures support relocatable kernel. -System kernel -------------- +Building a relocatable kernel is advantageous from the point of view that +one does not have to build a second kernel for capturing the dump. But +at the same time one might want to build a custom dump capture kernel +suitable to his needs. + +Following are the configuration setting required for system and +dump-capture kernels for enabling kdump support. + +System kernel config options +---------------------------- 1) Enable "kexec system call" in "Processor type and features." @@ -132,88 +142,182 @@ System kernel analysis tools require a vmlinux with debug symbols in order to read and analyze a dump file. -4) Make and install the kernel and its modules. Update the boot loader - (such as grub, yaboot, or lilo) configuration files as necessary. +Dump-capture kernel config options (Arch Independent) +----------------------------------------------------- -5) Boot the system kernel with the boot parameter "crashkernel=Y@X", - where Y specifies how much memory to reserve for the dump-capture kernel - and X specifies the beginning of this reserved memory. For example, - "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory - starting at physical address 0x01000000 for the dump-capture kernel. - - On x86 and x86_64, use "crashkernel=64M@16M". - - On ppc64, use "crashkernel=128M@32M". +1) Enable "kernel crash dumps" support under "Processor type and + features": + CONFIG_CRASH_DUMP=y -The dump-capture kernel ------------------------ +2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems". -1) Under "General setup," append "-kdump" to the current string in - "Local version." + CONFIG_PROC_VMCORE=y + (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.) -2) On x86, enable high memory support under "Processor type and +Dump-capture kernel config options (Arch Dependent, i386) +-------------------------------------------------------- +1) On x86, enable high memory support under "Processor type and features": CONFIG_HIGHMEM64G=y or CONFIG_HIGHMEM4G -3) On x86 and x86_64, disable symmetric multi-processing support +2) On x86 and x86_64, disable symmetric multi-processing support under "Processor type and features": CONFIG_SMP=n + (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line when loading the dump-capture kernel, see section "Load the Dump-capture Kernel".) -4) On ppc64, disable NUMA support and enable EMBEDDED support: +3) If one wants to build and use a relocatable kernel, + Enable "Build a relocatable kernel" support under "Processor type and + features" - CONFIG_NUMA=n - CONFIG_EMBEDDED=y - CONFIG_EEH=N for the dump-capture kernel + CONFIG_RELOCATABLE=y -5) Enable "kernel crash dumps" support under "Processor type and - features": +4) Use a suitable value for "Physical address where the kernel is + loaded" (under "Processor type and features"). This only appears when + "kernel crash dumps" is enabled. A suitable value depends upon + whether kernel is relocatable or not. + + If you are using a relocatable kernel use CONFIG_PHYSICAL_START=0x100000 + This will compile the kernel for physical address 1MB, but given the fact + kernel is relocatable, it can be run from any physical address hence + kexec boot loader will load it in memory region reserved for dump-capture + kernel. + + Otherwise it should be the start of memory region reserved for + second kernel using boot parameter "crashkernel=Y@X". Here X is + start of memory region reserved for dump-capture kernel. + Generally X is 16MB (0x1000000). So you can set + CONFIG_PHYSICAL_START=0x1000000 + +5) Make and install the kernel and its modules. DO NOT add this kernel + to the boot loader configuration files. - CONFIG_CRASH_DUMP=y +Dump-capture kernel config options (Arch Dependent, x86_64) +---------------------------------------------------------- +1) On x86 and x86_64, disable symmetric multi-processing support + under "Processor type and features": -6) Use a suitable value for "Physical address where the kernel is + CONFIG_SMP=n + + (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line + when loading the dump-capture kernel, see section "Load the Dump-capture + Kernel".) + +2) Use a suitable value for "Physical address where the kernel is loaded" (under "Processor type and features"). This only appears when "kernel crash dumps" is enabled. By default this value is 0x1000000 (16MB). It should be the same as X in the "crashkernel=Y@X" boot - parameter discussed above. + parameter. - On x86 and x86_64, use "CONFIG_PHYSICAL_START=0x1000000". + For x86_64, normally "CONFIG_PHYSICAL_START=0x1000000". - On ppc64 the value is automatically set at 32MB when - CONFIG_CRASH_DUMP is set. +3) Make and install the kernel and its modules. DO NOT add this kernel + to the boot loader configuration files. -6) Optionally enable "/proc/vmcore support" under "Filesystems" -> - "Pseudo filesystems". +Dump-capture kernel config options (Arch Dependent, ppc64) +---------------------------------------------------------- - CONFIG_PROC_VMCORE=y - (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.) - -7) Make and install the kernel and its modules. DO NOT add this kernel +- Make and install the kernel and its modules. DO NOT add this kernel to the boot loader configuration files. +Dump-capture kernel config options (Arch Dependent, ia64) +---------------------------------------------------------- + +- 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 +======================= + +1) Make and install the kernel and its modules. Update the boot loader + (such as grub, yaboot, or lilo) configuration files as necessary. + +2) Boot the system kernel with the boot parameter "crashkernel=Y@X", + where Y specifies how much memory to reserve for the dump-capture kernel + and X specifies the beginning of this reserved memory. For example, + "crashkernel=64M@16M" tells the system kernel to reserve 64 MB of memory + starting at physical address 0x01000000 (16MB) for the dump-capture kernel. + + On x86 and x86_64, use "crashkernel=64M@16M". + + 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 ============================ -After booting to the system kernel, load the dump-capture kernel using -the following command: +After booting to the system kernel, dump-capture kernel needs to be +loaded. + +Based on the architecture and type of image (relocatable or not), one +can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz +of dump-capture kernel. Following is the summary. + +For i386: + - Use vmlinux if kernel is not relocatable. + - Use bzImage/vmlinuz if kernel is relocatable. +For x86_64: + - Use vmlinux +For ppc64: + - Use vmlinux +For ia64: + - Use vmlinux or vmlinuz.gz + - kexec -p <dump-capture-kernel> \ +If you are using a uncompressed vmlinux image then use following command +to load dump-capture kernel. + + kexec -p <dump-capture-kernel-vmlinux-image> \ --initrd=<initrd-for-dump-capture-kernel> --args-linux \ - --append="root=<root-dev> init 1 irqpoll" + --append="root=<root-dev> <arch-specific-options>" +If you are using a compressed bzImage/vmlinuz, then use following command +to load dump-capture kernel. -Notes on loading the dump-capture kernel: + kexec -p <dump-capture-kernel-bzImage> \ + --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. -* <dump-capture-kernel> must be a vmlinux image (that is, an - uncompressed ELF image). bzImage does not work at this time. +For i386, x86_64 and ia64: + "init 1 irqpoll maxcpus=1" + +For ppc64: + "init 1 maxcpus=1 noirqdistrib" + + +Notes on loading the dump-capture kernel: * By default, the ELF headers are stored in ELF64 format to support systems with more than 4GB memory. The --elf32-core-headers option can @@ -231,6 +335,9 @@ Notes on loading the dump-capture kernel: * "init 1" boots the dump-capture kernel into single-user mode without networking. If you want networking, use "init 3." +* We generally don' have to bring up a SMP kernel just to capture the + dump. Hence generally it is useful either to build a UP dump-capture + kernel or specify maxcpus=1 option while loading dump-capture kernel. Kernel Panic ============ diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index ef69c75780b..25d29851710 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1714,6 +1714,14 @@ and is between 256 and 4096 characters. It is defined in the file uart6850= [HW,OSS] Format: <io>,<irq> + uhci-hcd.ignore_oc= + [USB] Ignore overcurrent events (default N). + Some badly-designed motherboards generate lots of + bogus events, for ports that aren't wired to + anything. Set this parameter to avoid log spamming. + Note that genuine overcurrent events won't be + reported either. + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. 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 + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and consistent) + Unregister from other subsystems (e.g. scsi or netdev) + Disable device from responding to MMIO/IO Port addresses + Release MMIO/IO Port resource(s) + + +4.1 Stop IRQs on the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How to do this is chip/device specific. If it's not done, it opens +the possibility of a "screaming interrupt" if (and only if) +the IRQ is shared with another device. + +When the shared IRQ handler is "unhooked", the remaining devices +using the same IRQ line will still need the IRQ enabled. Thus if the +"unhooked" device asserts IRQ line, the system will respond assuming +it was one of the remaining devices asserted the IRQ line. Since none +of the other devices will handle the IRQ, the system will "hang" until +it decides the IRQ isn't going to get handled and masks the IRQ (100,000 +iterations later). Once the shared IRQ is masked, the remaining devices +will stop functioning properly. Not a nice situation. + +This is another reason to use MSI or MSI-X if it's available. +MSI and MSI-X are defined to be exclusive interrupts and thus +are not susceptible to the "screaming interrupt" problem. + + +4.2 Release the IRQ +~~~~~~~~~~~~~~~~~~~ +Once the device is quiesced (no more IRQs), one can call free_irq(). +This function will return control once any pending IRQs are handled, +"unhook" the drivers IRQ handler from that IRQ, and finally release +the IRQ if no one else is using it. + + +4.3 Stop all DMA activity +~~~~~~~~~~~~~~~~~~~~~~~~~ +It's extremely important to stop all DMA operations BEFORE attempting +to deallocate DMA control data. Failure to do so can result in memory +corruption, hangs, and on some chip-sets a hard crash. -4. How to access PCI config space +Stopping DMA after stopping the IRQs can avoid races where the +IRQ handler might restart DMA engines. + +While this step sounds obvious and trivial, several "mature" drivers +didn't get this step right in the past. + + +4.4 Release DMA buffers +~~~~~~~~~~~~~~~~~~~~~~~ +Once DMA is stopped, clean up streaming DMA first. +I.e. unmap data buffers and return buffers to "upstream" +owners if there is one. + +Then clean up "consistent" buffers which contain the control data. + +See Documentation/DMA-API.txt for details on unmapping interfaces. + + +4.5 Unregister from other subsystems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most low level PCI device drivers support some other subsystem +like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your +driver isn't losing resources from that other subsystem. +If this happens, typically the symptom is an Oops (panic) when +the subsystem attempts to call into a driver that has been unloaded. + + +4.6 Disable Device from responding to MMIO/IO Port addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +io_unmap() MMIO or IO Port resources and then call pci_disable_device(). +This is the symmetric opposite of pci_enable_device(). +Do not access device registers after calling pci_disable_device(). + + +4.7 Release MMIO/IO Port Resource(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Call pci_release_region() to mark the MMIO or IO Port range as available. +Failure to do so usually results in the inability to reload the driver. + + + +5. How to access PCI config space ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - You can use pci_(read|write)_config_(byte|word|dword) to access the config + +You can use pci_(read|write)_config_(byte|word|dword) to access the config space of a device represented by struct pci_dev *. All these functions return 0 when successful or an error code (PCIBIOS_...) which can be translated to a text string by pcibios_strerror. Most drivers expect that accesses to valid PCI devices don't fail. - If you don't have a struct pci_dev available, you can call +If you don't have a struct pci_dev available, you can call pci_bus_(read|write)_config_(byte|word|dword) to access a given device and function on that bus. - If you access fields in the standard portion of the config header, please +If you access fields in the standard portion of the config header, please use symbolic names of locations and bits declared in <linux/pci.h>. - If you need to access Extended PCI Capability registers, just call +If you need to access Extended PCI Capability registers, just call pci_find_capability() for the particular capability and it will find the corresponding register block for you. -5. Addresses and interrupts -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Memory and port addresses and interrupt numbers should NOT be read from the -config space. You should use the values in the pci_dev structure as they might -have been remapped by the kernel. - - See Documentation/IO-mapping.txt for how to access device memory. - - The device driver needs to call pci_request_region() to make sure -no other device is already using the same resource. The driver is expected -to determine MMIO and IO Port resource availability _before_ calling -pci_enable_device(). 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. - -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 -interfaces (e.g. BAR). - - All interrupt handlers should be registered with IRQF_SHARED and use the devid -to map IRQs to devices (remember that all PCI interrupts are shared). - 6. Other interesting functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + pci_find_slot() Find pci_dev corresponding to given bus and slot numbers. pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) @@ -247,11 +560,12 @@ pci_set_mwi() Enable Memory-Write-Invalidate transactions. pci_clear_mwi() Disable Memory-Write-Invalidate transactions. + 7. Miscellaneous hints ~~~~~~~~~~~~~~~~~~~~~~ -When displaying PCI slot names to the user (for example when a driver wants -to tell the user what card has it found), please use pci_name(pci_dev) -for this purpose. + +When displaying PCI device names to the user (for example when a driver wants +to tell the user what card has it found), please use pci_name(pci_dev). Always refer to the PCI devices by a pointer to the pci_dev structure. All PCI layer functions use this identification and it's the only @@ -259,31 +573,113 @@ reasonable one. Don't use bus/slot/function numbers except for very special purposes -- on systems with multiple primary buses their semantics can be pretty complex. -If you're going to use PCI bus mastering DMA, take a look at -Documentation/DMA-mapping.txt. - Don't try to turn on Fast Back to Back writes in your driver. All devices on the bus need to be capable of doing it, so this is something which needs to be handled by platform and generic code, not individual drivers. + 8. Vendor and device identifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For the future, let's avoid adding device ids to include/linux/pci_ids.h. -PCI_VENDOR_ID_xxx for vendors, and a hex constant for device ids. +One is not not required to add new device ids to include/linux/pci_ids.h. +Please add PCI_VENDOR_ID_xxx for vendors and a hex constant for device ids. + +PCI_VENDOR_ID_xxx constants are re-used. The device ids are arbitrary +hex numbers (vendor controlled) and normally used only in a single +location, the pci_device_id table. + +Please DO submit new vendor/device ids to pciids.sourceforge.net project. + -Rationale: PCI_VENDOR_ID_xxx constants are re-used, but device ids are not. - Further, device ids are arbitrary hex numbers, normally used only in a - single location, the pci_device_id table. 9. Obsolete functions ~~~~~~~~~~~~~~~~~~~~~ + There are several functions which you might come across when trying to port an old driver to the new PCI interface. They are no longer present in the kernel as they aren't compatible with hotplug or PCI domains or having sane locking. -pci_find_device() Superseded by pci_get_device() -pci_find_subsys() Superseded by pci_get_subsys() -pci_find_slot() Superseded by pci_get_slot() +pci_find_device() Superseded by pci_get_device() +pci_find_subsys() Superseded by pci_get_subsys() +pci_find_slot() Superseded by pci_get_slot() + + +The alternative is the traditional PCI device driver that walks PCI +device lists. This is still possible but discouraged. + + + +10. pci_enable_device_bars() and Legacy I/O Port space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Large servers may not be able to provide I/O port resources to all PCI +devices. I/O Port space is only 64KB on Intel Architecture[1] and is +likely also fragmented since the I/O base register of PCI-to-PCI +bridge will usually be aligned to a 4KB boundary[2]. On such systems, +pci_enable_device() and pci_request_region() will fail when +attempting to enable I/O Port regions that don't have I/O Port +resources assigned. + +Fortunately, many PCI devices which request I/O Port resources also +provide access to the same registers via MMIO BARs. These devices can +be handled without using I/O port space and the drivers typically +offer a CONFIG_ option to only use MMIO regions +(e.g. CONFIG_TULIP_MMIO). PCI devices typically provide I/O port +interface for legacy OSes and will work when I/O port resources are not +assigned. The "PCI Local Bus Specification Revision 3.0" discusses +this on p.44, "IMPLEMENTATION NOTE". + +If your PCI device driver doesn't need I/O port resources assigned to +I/O Port BARs, you should use pci_enable_device_bars() instead of +pci_enable_device() in order not to enable I/O port regions for the +corresponding devices. In addition, you should use +pci_request_selected_regions() and pci_release_selected_regions() +instead of pci_request_regions()/pci_release_regions() in order not to +request/release I/O port regions for the corresponding devices. + +[1] Some systems support 64KB I/O port space per PCI segment. +[2] Some PCI-to-PCI bridges support optional 1KB aligned I/O base. + + + +11. MMIO Space and "Write Posting" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Converting a driver from using I/O Port space to using MMIO space +often requires some additional changes. Specifically, "write posting" +needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) +already do this. I/O Port space guarantees write transactions reach the PCI +device before the CPU can continue. Writes to MMIO space allow the CPU +to continue before the transaction reaches the PCI device. HW weenies +call this "Write Posting" because the write completion is "posted" to +the CPU before the transaction has reached its destination. + +Thus, timing sensitive code should add readl() where the CPU is +expected to wait before doing other work. The classic "bit banging" +sequence works fine for I/O Port space: + + for (i = 8; --i; val >>= 1) { + outb(val & 1, ioport_reg); /* write bit */ + udelay(10); + } + +The same sequence for MMIO space should be: + + for (i = 8; --i; val >>= 1) { + writeb(val & 1, mmio_reg); /* write bit */ + readb(safe_mmio_reg); /* flush posted write */ + udelay(10); + } + +It is important that "safe_mmio_reg" not have any side effects that +interferes with the correct operation of the device. + +Another case to watch out for is when resetting a PCI device. Use PCI +Configuration space reads to flush the writel(). This will gracefully +handle the PCI master abort on all platforms if the PCI device is +expected to not respond to a readl(). Most x86 platforms will allow +MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage +(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). + diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index b3bd36668db..33994271cb3 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -1703,29 +1703,32 @@ platforms are moved over to use the flattened-device-tree model. Required properties: - device_type : has to be "rom" - - compatible : Should specify what this ROM device is compatible with - (i.e. "onenand"). Currently, this is most likely to be "direct-mapped" - (which corresponds to the MTD physmap mapping driver). - - regs : Offset and length of the register set (or memory mapping) for + - compatible : Should specify what this flash device is compatible with. + Currently, this is most likely to be "direct-mapped" (which + corresponds to the MTD physmap mapping driver). + - reg : Offset and length of the register set (or memory mapping) for the device. + - bank-width : Width of the flash data bus in bytes. Required + for the NOR flashes (compatible == "direct-mapped" and others) ONLY. Recommended properties : - - bank-width : Width of the flash data bus in bytes. Required - for the NOR flashes (compatible == "direct-mapped" and others) ONLY. - partitions : Several pairs of 32-bit values where the first value is partition's offset from the start of the device and the second one is partition size in bytes with LSB used to signify a read only - partititon (so, the parition size should always be an even number). + partition (so, the parition size should always be an even number). - partition-names : The list of concatenated zero terminated strings representing the partition names. + - probe-type : The type of probe which should be done for the chip + (JEDEC vs CFI actually). Valid ONLY for NOR flashes. Example: flash@ff000000 { device_type = "rom"; compatible = "direct-mapped"; - regs = <ff000000 01000000>; + probe-type = "CFI"; + reg = <ff000000 01000000>; bank-width = <4>; partitions = <00000000 00f80000 00f80000 00080001>; diff --git a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt index d077d764f82..69f016f02bb 100644 --- a/Documentation/powerpc/mpc52xx-device-tree-bindings.txt +++ b/Documentation/powerpc/mpc52xx-device-tree-bindings.txt @@ -4,6 +4,12 @@ MPC52xx Device Tree Bindings (c) 2006 Secret Lab Technologies Ltd Grant Likely <grant.likely at secretlab.ca> +********** DRAFT *********** +* WARNING: Do not depend on the stability of these bindings just yet. +* The MPC5200 device tree conventions are still in flux +* Keep an eye on the linuxppc-dev mailing list for more details +********** DRAFT *********** + I - Introduction ================ Boards supported by the arch/powerpc architecture require device tree be @@ -157,8 +163,8 @@ rtc@<addr> rtc *-rtc Real time clock mscan@<addr> mscan *-mscan CAN bus controller pci@<addr> pci *-pci PCI bridge serial@<addr> serial *-psc-uart PSC in serial mode -i2s@<addr> i2s *-psc-i2s PSC in i2s mode -ac97@<addr> ac97 *-psc-ac97 PSC in ac97 mode +i2s@<addr> sound *-psc-i2s PSC in i2s mode +ac97@<addr> sound *-psc-ac97 PSC in ac97 mode spi@<addr> spi *-psc-spi PSC in spi mode irda@<addr> irda *-psc-irda PSC in IrDA mode spi@<addr> spi *-spi MPC52xx spi device diff --git a/Documentation/scsi/aacraid.txt b/Documentation/scsi/aacraid.txt index 3367130e64f..dc8e44fc650 100644 --- a/Documentation/scsi/aacraid.txt +++ b/Documentation/scsi/aacraid.txt @@ -11,43 +11,42 @@ the original). Supported Cards/Chipsets ------------------------- PCI ID (pci.ids) OEM Product - 9005:0283:9005:0283 Adaptec Catapult (3210S with arc firmware) - 9005:0284:9005:0284 Adaptec Tomcat (3410S with arc firmware) 9005:0285:9005:0285 Adaptec 2200S (Vulcan) 9005:0285:9005:0286 Adaptec 2120S (Crusader) 9005:0285:9005:0287 Adaptec 2200S (Vulcan-2m) 9005:0285:9005:0288 Adaptec 3230S (Harrier) 9005:0285:9005:0289 Adaptec 3240S (Tornado) 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk) - 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) + 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) 9005:0286:9005:028c Adaptec 2230S (Lancer) 9005:0286:9005:028c Adaptec 2230SLP (Lancer) 9005:0286:9005:028d Adaptec 2130S (Lancer) 9005:0285:9005:028e Adaptec 2020SA (Skyhawk) - 9005:0285:9005:028f Adaptec 2025SA (Terminator) + 9005:0285:9005:028f Adaptec 2025SA (Terminator) 9005:0285:9005:0290 Adaptec 2410SA (Jaguar) - 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) - 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) + 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) + 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) 9005:0285:9005:0296 Adaptec 2240S (SabreExpress) 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8) - 9005:0285:9005:0294 Adaptec Prowler - 9005:0285:9005:0297 Adaptec 4005SAS (AvonPark) - 9005:0285:9005:0298 Adaptec 4000SAS (BlackBird) + 9005:0285:9005:0297 Adaptec 4005 (AvonPark) + 9005:0285:9005:0298 Adaptec 4000 (BlackBird) 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X) 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E) 9005:0286:9005:029b Adaptec 2820SA (Intruder) 9005:0286:9005:029c Adaptec 2620SA (Intruder) 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release) - 9005:0286:9005:02a2 Adaptec 3800SAS (Hurricane44) - 9005:0286:9005:02a7 Adaptec 3805SAS (Hurricane80) - 9005:0286:9005:02a8 Adaptec 3400SAS (Hurricane40) - 9005:0286:9005:02ac Adaptec 1800SAS (Typhoon44) - 9005:0286:9005:02b3 Adaptec 2400SAS (Hurricane40lm) - 9005:0285:9005:02b5 Adaptec ASR5800 (Voodoo44) - 9005:0285:9005:02b6 Adaptec ASR5805 (Voodoo80) - 9005:0285:9005:02b7 Adaptec ASR5808 (Voodoo08) + 9005:0286:9005:02ac Adaptec 1800 (Typhoon44) + 9005:0285:9005:02b5 Adaptec 5445 (Voodoo44) + 9005:0285:9005:02b6 Adaptec 5805 (Voodoo80) + 9005:0285:9005:02b7 Adaptec 5085 (Voodoo08) + 9005:0285:9005:02bb Adaptec 3405 (Marauder40LP) + 9005:0285:9005:02bc Adaptec 3805 (Marauder80LP) + 9005:0285:9005:02c7 Adaptec 3085 (Marauder08ELP) + 9005:0285:9005:02bd Adaptec 31205 (Marauder120) + 9005:0285:9005:02be Adaptec 31605 (Marauder160) + 9005:0285:9005:02c3 Adaptec 51205 (Voodoo120) + 9005:0285:9005:02c4 Adaptec 51605 (Voodoo160) 1011:0046:9005:0364 Adaptec 5400S (Mustang) - 1011:0046:9005:0365 Adaptec 5400S (Mustang) 9005:0287:9005:0800 Adaptec Themisto (Jupiter) 9005:0200:9005:0200 Adaptec Themisto (Jupiter) 9005:0286:9005:0800 Adaptec Callisto (Jupiter) @@ -68,21 +67,32 @@ Supported Cards/Chipsets 9005:0285:17aa:0287 Legend S230 (Vulcan) 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar) 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark) - 9005:0285:1014:0312 IBM ServeRAID 8i (AvonParkLite) 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite) 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora) - 9005:0286:1014:034d IBM ServeRAID 8s (Hurricane) - 9005:0286:9005:029e ICP ICP9024R0 (Lancer) - 9005:0286:9005:029f ICP ICP9014R0 (Lancer) + 9005:0285:1014:034d IBM ServeRAID 8s (Marauder-E) + 9005:0286:9005:029e ICP ICP9024RO (Lancer) + 9005:0286:9005:029f ICP ICP9014RO (Lancer) 9005:0286:9005:02a0 ICP ICP9047MA (Lancer) 9005:0286:9005:02a1 ICP ICP9087MA (Lancer) - 9005:0286:9005:02a3 ICP ICP5445AU (Hurricane44) - 9005:0286:9005:02a4 ICP ICP9085LI (Marauder-X) - 9005:0286:9005:02a5 ICP ICP5085BR (Marauder-E) + 9005:0285:9005:02a4 ICP ICP9085LI (Marauder-X) + 9005:0285:9005:02a5 ICP ICP5085BR (Marauder-E) 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6) - 9005:0286:9005:02a9 ICP ICP5085AU (Hurricane80) - 9005:0286:9005:02aa ICP ICP5045AU (Hurricane40) - 9005:0286:9005:02b4 ICP ICP5045AL (Hurricane40lm) + 9005:0285:9005:02b2 ICP (Voodoo 8 internal 8 external) + 9005:0285:9005:02b8 ICP ICP5445SL (Voodoo44) + 9005:0285:9005:02b9 ICP ICP5085SL (Voodoo80) + 9005:0285:9005:02ba ICP ICP5805SL (Voodoo08) + 9005:0285:9005:02bf ICP ICP5045BL (Marauder40LP) + 9005:0285:9005:02c0 ICP ICP5085BL (Marauder80LP) + 9005:0285:9005:02c8 ICP ICP5805BL (Marauder08ELP) + 9005:0285:9005:02c1 ICP ICP5125BR (Marauder120) + 9005:0285:9005:02c2 ICP ICP5165BR (Marauder160) + 9005:0285:9005:02c5 ICP ICP5125SL (Voodoo120) + 9005:0285:9005:02c6 ICP ICP5165SL (Voodoo160) + 9005:0286:9005:02ab (Typhoon40) + 9005:0286:9005:02ad (Aurora ARK) + 9005:0286:9005:02ae (Aurora Lite ARK) + 9005:0285:9005:02b0 (Sunrise Lake ARK) + 9005:0285:9005:02b1 Adaptec (Voodoo 8 internal 8 external) People ------------------------- diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 077fbe25ebf..ccd0a953953 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl @@ -927,7 +927,7 @@ <informalexample> <programlisting> <![CDATA[ - struct mychip *chip = (struct mychip *)card->private_data; + struct mychip *chip = card->private_data; ]]> </programlisting> </informalexample> @@ -1095,7 +1095,7 @@ /* release the irq */ if (chip->irq >= 0) - free_irq(chip->irq, (void *)chip); + free_irq(chip->irq, chip); /* release the i/o ports & memory */ pci_release_regions(chip->pci); /* disable the PCI entry */ @@ -1148,7 +1148,7 @@ } chip->port = pci_resource_start(pci, 0); if (request_irq(pci->irq, snd_mychip_interrupt, - IRQF_DISABLED|IRQF_SHARED, "My Chip", chip)) { + IRQF_SHARED, "My Chip", chip)) { printk(KERN_ERR "cannot grab irq %d\n", pci->irq); snd_mychip_free(chip); return -EBUSY; @@ -1387,7 +1387,7 @@ <programlisting> <![CDATA[ if (chip->irq >= 0) - free_irq(chip->irq, (void *)chip); + free_irq(chip->irq, chip); ]]> </programlisting> </informalexample> diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index e0188a23fd5..61613166981 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -1,6 +1,6 @@ Linux Magic System Request Key Hacks -Documentation for sysrq.c version 1.15 -Last update: $Date: 2001/01/28 10:15:59 $ +Documentation for sysrq.c +Last update: 2007-JAN-06 * What is the magic SysRq key? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -35,7 +35,7 @@ You can set the value in the file by the following command: Note that the value of /proc/sys/kernel/sysrq influences only the invocation via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always -allowed. +allowed (by a user with admin privileges). * How do I use the magic SysRq key? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -58,7 +58,7 @@ On PowerPC - Press 'ALT - Print Screen (or F13) - <command key>, On other - If you know of the key combos for other architectures, please let me know so I can add them to this section. -On all - write a character to /proc/sysrq-trigger. eg: +On all - write a character to /proc/sysrq-trigger. e.g.: echo t > /proc/sysrq-trigger @@ -74,6 +74,8 @@ On all - write a character to /proc/sysrq-trigger. eg: 'c' - Will perform a kexec reboot in order to take a crashdump. +'d' - Shows all locks that are held. + 'o' - Will shut your system off (if configured and supported). 's' - Will attempt to sync all mounted filesystems. @@ -87,38 +89,43 @@ On all - write a character to /proc/sysrq-trigger. eg: 'm' - Will dump current memory info to your console. +'n' - Used to make RT tasks nice-able + 'v' - Dumps Voyager SMP processor info to your console. +'w' - Dumps tasks that are in uninterruptable (blocked) state. + +'x' - Used by xmon interface on ppc/powerpc platforms. + '0'-'9' - Sets the console log level, controlling which kernel messages will be printed to your console. ('0', for example would make it so that only emergency messages like PANICs or OOPSes would make it to your console.) -'f' - Will call oom_kill to kill a memory hog process +'f' - Will call oom_kill to kill a memory hog process. 'e' - Send a SIGTERM to all processes, except for init. -'i' - Send a SIGKILL to all processes, except for init. +'g' - Used by kgdb on ppc platforms. -'l' - Send a SIGKILL to all processes, INCLUDING init. (Your system - will be non-functional after this.) +'i' - Send a SIGKILL to all processes, except for init. -'h' - Will display help ( actually any other key than those listed +'h' - Will display help (actually any other key than those listed above will display help. but 'h' is easy to remember :-) * Okay, so what can I use them for? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Well, un'R'aw is very handy when your X server or a svgalib program crashes. -sa'K' (Secure Access Key) is useful when you want to be sure there are no -trojan program is running at console and which could grab your password -when you would try to login. It will kill all programs on given console -and thus letting you make sure that the login prompt you see is actually +sa'K' (Secure Access Key) is useful when you want to be sure there is no +trojan program running at console which could grab your password +when you would try to login. It will kill all programs on given console, +thus letting you make sure that the login prompt you see is actually the one from init, not some trojan program. IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT IMPORTANT: such. :IMPORTANT - It seems other find it useful as (System Attention Key) which is + It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) @@ -139,8 +146,8 @@ OK or Done message...) Again, the unmount (remount read-only) hasn't taken place until you see the "OK" and "Done" message appear on the screen. -The loglevel'0'-'9' is useful when your console is being flooded with -kernel messages you do not want to see. Setting '0' will prevent all but +The loglevels '0'-'9' are useful when your console is being flooded with +kernel messages you do not want to see. Selecting '0' will prevent all but the most urgent kernel messages from reaching your console. (They will still be logged if syslogd/klogd are alive, though.) @@ -152,7 +159,7 @@ processes. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That happens to me, also. I've found that tapping shift, alt, and control on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (ie, something like alt-sysrq-z). Switching to another +will fix the problem. (i.e., something like alt-sysrq-z). Switching to another virtual console (ALT+Fn) and then back again should also help. * I hit SysRq, but nothing seems to happen, what's wrong? @@ -174,11 +181,11 @@ handler function you will use, B) a help_msg string, that will print when SysRQ prints help, and C) an action_msg string, that will print right before your handler is called. Your handler must conform to the prototype in 'sysrq.h'. -After the sysrq_key_op is created, you can call the macro -register_sysrq_key(int key, struct sysrq_key_op *op_p) that is defined in -sysrq.h, this will register the operation pointed to by 'op_p' at table -key 'key', if that slot in the table is blank. At module unload time, you must -call the macro unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which +After the sysrq_key_op is created, you can call the kernel function +register_sysrq_key(int key, struct sysrq_key_op *op_p); this will +register the operation pointed to by 'op_p' at table key 'key', +if that slot in the table is blank. At module unload time, you must call +the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which will remove the key op pointed to by 'op_p' from the key 'key', if and only if it is currently registered in that slot. This is in case the slot has been overwritten since you registered it. @@ -186,15 +193,12 @@ overwritten since you registered it. The Magic SysRQ system works by registering key operations against a key op lookup table, which is defined in 'drivers/char/sysrq.c'. This key table has a number of operations registered into it at compile time, but is mutable, -and 4 functions are exported for interface to it: __sysrq_lock_table, -__sysrq_unlock_table, __sysrq_get_key_op, and __sysrq_put_key_op. The -functions __sysrq_swap_key_ops and __sysrq_swap_key_ops_nolock are defined -in the header itself, and the REGISTER and UNREGISTER macros are built from -these. More complex (and dangerous!) manipulations of the table are possible -using these functions, but you must be careful to always lock the table before -you read or write from it, and to unlock it again when you are done. (And of -course, to never ever leave an invalid pointer in the table). Null pointers in -the table are always safe :) +and 2 functions are exported for interface to it: + register_sysrq_key and unregister_sysrq_key. +Of course, never ever leave an invalid pointer in the table. I.e., when +your module that called register_sysrq_key() exits, it must call +unregister_sysrq_key() to clean up the sysrq key table entry that it used. +Null pointers in the table are always safe. :) If for some reason you feel the need to call the handle_sysrq function from within a function called by handle_sysrq, you must be aware that you are in diff --git a/Documentation/tty.txt b/Documentation/tty.txt index dab56604745..5f799e612e0 100644 --- a/Documentation/tty.txt +++ b/Documentation/tty.txt @@ -39,28 +39,37 @@ Line Discipline Methods TTY side interfaces: +open() - Called when the line discipline is attached to + the terminal. No other call into the line + discipline for this tty will occur until it + completes successfully. Can sleep. + close() - This is called on a terminal when the line discipline is being unplugged. At the point of execution no further users will enter the ldisc code for this tty. Can sleep. -open() - Called when the line discipline is attached to - the terminal. No other call into the line - discipline for this tty will occur until it - completes successfully. Can sleep. +hangup() - Called when the tty line is hung up. + The line discipline should cease I/O to the tty. + No further calls into the ldisc code will occur. + Can sleep. write() - A process is writing data through the line discipline. Multiple write calls are serialized by the tty layer for the ldisc. May sleep. -flush_buffer() - May be called at any point between open and close. +flush_buffer() - (optional) May be called at any point between + open and close, and instructs the line discipline + to empty its input buffer. -chars_in_buffer() - Report the number of bytes in the buffer. +chars_in_buffer() - (optional) Report the number of bytes in the input + buffer. -set_termios() - Called on termios structure changes. The caller - passes the old termios data and the current data - is in the tty. Called under the termios semaphore so - allowed to sleep. Serialized against itself only. +set_termios() - (optional) Called on termios structure changes. + The caller passes the old termios data and the + current data is in the tty. Called under the + termios semaphore so allowed to sleep. Serialized + against itself only. read() - Move data from the line discipline to the user. Multiple read calls may occur in parallel and the @@ -92,6 +101,88 @@ write_wakeup() - May be called at any point between open and close. this function. In such a situation defer it. +Driver Access + +Line discipline methods can call the following methods of the underlying +hardware driver through the function pointers within the tty->driver +structure: + +write() Write a block of characters to the tty device. + Returns the number of characters accepted. + +put_char() Queues a character for writing to the tty device. + If there is no room in the queue, the character is + ignored. + +flush_chars() (Optional) If defined, must be called after + queueing characters with put_char() in order to + start transmission. + +write_room() Returns the numbers of characters the tty driver + will accept for queueing to be written. + +ioctl() Invoke device specific ioctl. + Expects data pointers to refer to userspace. + Returns ENOIOCTLCMD for unrecognized ioctl numbers. + +set_termios() Notify the tty driver that the device's termios + settings have changed. New settings are in + tty->termios. Previous settings should be passed in + the "old" argument. + +throttle() Notify the tty driver that input buffers for the + line discipline are close to full, and it should + somehow signal that no more characters should be + sent to the tty. + +unthrottle() Notify the tty driver that characters can now be + sent to the tty without fear of overrunning the + input buffers of the line disciplines. + +stop() Ask the tty driver to stop outputting characters + to the tty device. + +start() Ask the tty driver to resume sending characters + to the tty device. + +hangup() Ask the tty driver to hang up the tty device. + +break_ctl() (Optional) Ask the tty driver to turn on or off + BREAK status on the RS-232 port. If state is -1, + then the BREAK status should be turned on; if + state is 0, then BREAK should be turned off. + If this routine is not implemented, use ioctls + TIOCSBRK / TIOCCBRK instead. + +wait_until_sent() Waits until the device has written out all of the + characters in its transmitter FIFO. + +send_xchar() Send a high-priority XON/XOFF character to the device. + + +Flags + +Line discipline methods have access to tty->flags field containing the +following interesting flags: + +TTY_THROTTLED Driver input is throttled. The ldisc should call + tty->driver->unthrottle() in order to resume + reception when it is ready to process more data. + +TTY_DO_WRITE_WAKEUP If set, causes the driver to call the ldisc's + write_wakeup() method in order to resume + transmission when it can accept more data + to transmit. + +TTY_IO_ERROR If set, causes all subsequent userspace read/write + calls on the tty to fail, returning -EIO. + +TTY_OTHER_CLOSED Device is a pty and the other side has closed. + +TTY_NO_WRITE_SPLIT Prevent driver from splitting up writes into + smaller chunks. + + Locking Callers to the line discipline functions from the tty layer are required to diff --git a/Documentation/usb/CREDITS b/Documentation/usb/CREDITS index 01e7f857ef3..27a721635f9 100644 --- a/Documentation/usb/CREDITS +++ b/Documentation/usb/CREDITS @@ -21,7 +21,7 @@ difficult to maintain, add yourself with a patch if desired. Bill Ryder <bryder@sgi.com> Thomas Sailer <sailer@ife.ee.ethz.ch> Gregory P. Smith <greg@electricrain.com> - Linus Torvalds <torvalds@osdl.org> + Linus Torvalds <torvalds@linux-foundation.org> Roman Weissgaerber <weissg@vienna.at> <Kazuki.Yasumatsu@fujixerox.co.jp> diff --git a/Documentation/usb/acm.txt b/Documentation/usb/acm.txt index 737d6104c3f..17f5c2e1a57 100644 --- a/Documentation/usb/acm.txt +++ b/Documentation/usb/acm.txt @@ -46,6 +46,10 @@ Abstract Control Model (USB CDC ACM) specification. 3Com USR ISDN Pro TA + Some cell phones also connect via USB. I know the following phones work: + + SonyEricsson K800i + Unfortunately many modems and most ISDN TAs use proprietary interfaces and thus won't work with this drivers. Check for ACM compliance before buying. diff --git a/Documentation/x86_64/boot-options.txt b/Documentation/x86_64/boot-options.txt index dbdcaf68e3e..5c86ed6f044 100644 --- a/Documentation/x86_64/boot-options.txt +++ b/Documentation/x86_64/boot-options.txt @@ -52,6 +52,10 @@ APICs apicmaintimer. Useful when your PIT timer is totally broken. + disable_8254_timer / enable_8254_timer + Enable interrupt 0 timer routing over the 8254 in addition to over + the IO-APIC. The kernel tries to set a sensible default. + Early Console syntax: earlyprintk=vga |