diff options
Diffstat (limited to 'Documentation')
53 files changed, 5229 insertions, 372 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index a667eb1fc26..7f1730f1a1a 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -633,12 +633,27 @@ covers RTL which is used frequently with assembly language in the kernel. Kernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use crippled -words like "dont" and use "do not" or "don't" instead. +words like "dont"; use "do not" or "don't" instead. Make the messages +concise, clear, and unambiguous. Kernel messages do not have to be terminated with a period. Printing numbers in parentheses (%d) adds no value and should be avoided. +There are a number of driver model diagnostic macros in <linux/device.h> +which you should use to make sure messages are matched to the right device +and driver, and are tagged with the right level: dev_err(), dev_warn(), +dev_info(), and so forth. For messages that aren't associated with a +particular device, <linux/kernel.h> defines pr_debug() and pr_info(). + +Coming up with good debugging messages can be quite a challenge; and once +you have them, they can be a huge help for remote troubleshooting. Such +messages should be compiled out when the DEBUG symbol is not defined (that +is, by default they are not included). When you use dev_dbg() or pr_debug(), +that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG. +A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the +ones already enabled by DEBUG. + Chapter 14: Allocating memory @@ -790,4 +805,5 @@ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ -- -Last updated on 2006-December-06. +Last updated on 2007-July-13. + diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 6fd1646d320..08687e45e19 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -15,11 +15,11 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ ### # The build process is as follows (targets): -# (xmldocs) -# file.tmpl --> file.xml +--> file.ps (psdocs) -# +--> file.pdf (pdfdocs) -# +--> DIR=file (htmldocs) -# +--> man/ (mandocs) +# (xmldocs) [by docproc] +# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] +# +--> file.pdf (pdfdocs) [by db2pdf or xmlto] +# +--> DIR=file (htmldocs) [by xmlto] +# +--> man/ (mandocs) [by xmlto] # for PDF and PS output you can choose between xmlto and docbook-utils tools diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index fd2ef4d29b6..eb42bf9847c 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -159,7 +159,6 @@ X!Ilib/string.c !Earch/i386/lib/usercopy.c </sect1> <sect1><title>More Memory Management Functions</title> -!Iinclude/linux/rmap.h !Emm/readahead.c !Emm/filemap.c !Emm/memory.c @@ -408,6 +407,10 @@ X!Edrivers/pnp/system.c !Edrivers/pnp/manager.c !Edrivers/pnp/support.c </sect1> + <sect1><title>Userspace IO devices</title> +!Edrivers/uio/uio.c +!Iinclude/linux/uio_driver.h + </sect1> </chapter> <chapter id="blkdev"> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl new file mode 100644 index 00000000000..e3bb29a8d8d --- /dev/null +++ b/Documentation/DocBook/uio-howto.tmpl @@ -0,0 +1,611 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []> + +<book id="index"> +<bookinfo> +<title>The Userspace I/O HOWTO</title> + +<author> + <firstname>Hans-Jürgen</firstname> + <surname>Koch</surname> + <authorblurb><para>Linux developer, Linutronix</para></authorblurb> + <affiliation> + <orgname> + <ulink url="http://www.linutronix.de">Linutronix</ulink> + </orgname> + + <address> + <email>hjk@linutronix.de</email> + </address> + </affiliation> +</author> + +<pubdate>2006-12-11</pubdate> + +<abstract> + <para>This HOWTO describes concept and usage of Linux kernel's + Userspace I/O system.</para> +</abstract> + +<revhistory> + <revision> + <revnumber>0.3</revnumber> + <date>2007-04-29</date> + <authorinitials>hjk</authorinitials> + <revremark>Added section about userspace drivers.</revremark> + </revision> + <revision> + <revnumber>0.2</revnumber> + <date>2007-02-13</date> + <authorinitials>hjk</authorinitials> + <revremark>Update after multiple mappings were added.</revremark> + </revision> + <revision> + <revnumber>0.1</revnumber> + <date>2006-12-11</date> + <authorinitials>hjk</authorinitials> + <revremark>First draft.</revremark> + </revision> +</revhistory> +</bookinfo> + +<chapter id="aboutthisdoc"> +<?dbhtml filename="about.html"?> +<title>About this document</title> + +<sect1 id="copyright"> +<?dbhtml filename="copyright.html"?> +<title>Copyright and License</title> +<para> + Copyright (c) 2006 by Hans-Jürgen Koch.</para> +<para> +This documentation is Free Software licensed under the terms of the +GPL version 2. +</para> +</sect1> + +<sect1 id="translations"> +<?dbhtml filename="translations.html"?> +<title>Translations</title> + +<para>If you know of any translations for this document, or you are +interested in translating it, please email me +<email>hjk@linutronix.de</email>. +</para> +</sect1> + +<sect1 id="preface"> +<title>Preface</title> + <para> + For many types of devices, creating a Linux kernel driver is + overkill. All that is really needed is some way to handle an + interrupt and provide access to the memory space of the + device. The logic of controlling the device does not + necessarily have to be within the kernel, as the device does + not need to take advantage of any of other resources that the + kernel provides. One such common class of devices that are + like this are for industrial I/O cards. + </para> + <para> + To address this situation, the userspace I/O system (UIO) was + designed. For typical industrial I/O cards, only a very small + kernel module is needed. The main part of the driver will run in + user space. This simplifies development and reduces the risk of + serious bugs within a kernel module. + </para> +</sect1> + +<sect1 id="thanks"> +<title>Acknowledgments</title> + <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of + Linutronix, who have not only written most of the UIO code, but also + helped greatly writing this HOWTO by giving me all kinds of background + information.</para> +</sect1> + +<sect1 id="feedback"> +<title>Feedback</title> + <para>Find something wrong with this document? (Or perhaps something + right?) I would love to hear from you. Please email me at + <email>hjk@linutronix.de</email>.</para> +</sect1> +</chapter> + +<chapter id="about"> +<?dbhtml filename="about.html"?> +<title>About UIO</title> + +<para>If you use UIO for your card's driver, here's what you get:</para> + +<itemizedlist> +<listitem> + <para>only one small kernel module to write and maintain.</para> +</listitem> +<listitem> + <para>develop the main part of your driver in user space, + with all the tools and libraries you're used to.</para> +</listitem> +<listitem> + <para>bugs in your driver won't crash the kernel.</para> +</listitem> +<listitem> + <para>updates of your driver can take place without recompiling + the kernel.</para> +</listitem> +<listitem> + <para>if you need to keep some parts of your driver closed source, + you can do so without violating the GPL license on the kernel.</para> +</listitem> +</itemizedlist> + +<sect1 id="how_uio_works"> +<title>How UIO works</title> + <para> + Each UIO device is accessed through a device file and several + sysfs attribute files. The device file will be called + <filename>/dev/uio0</filename> for the first device, and + <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> + and so on for subsequent devices. + </para> + + <para><filename>/dev/uioX</filename> is used to access the + address space of the card. Just use + <function>mmap()</function> to access registers or RAM + locations of your card. + </para> + + <para> + Interrupts are handled by reading from + <filename>/dev/uioX</filename>. A blocking + <function>read()</function> from + <filename>/dev/uioX</filename> will return as soon as an + interrupt occurs. You can also use + <function>select()</function> on + <filename>/dev/uioX</filename> to wait for an interrupt. The + integer value read from <filename>/dev/uioX</filename> + represents the total interrupt count. You can use this number + to figure out if you missed some interrupts. + </para> + + <para> + To handle interrupts properly, your custom kernel module can + provide its own interrupt handler. It will automatically be + called by the built-in handler. + </para> + + <para> + For cards that don't generate interrupts but need to be + polled, there is the possibility to set up a timer that + triggers the interrupt handler at configurable time intervals. + See <filename>drivers/uio/uio_dummy.c</filename> for an + example of this technique. + </para> + + <para> + Each driver provides attributes that are used to read or write + variables. These attributes are accessible through sysfs + files. A custom kernel driver module can add its own + attributes to the device owned by the uio driver, but not added + to the UIO device itself at this time. This might change in the + future if it would be found to be useful. + </para> + + <para> + The following standard attributes are provided by the UIO + framework: + </para> +<itemizedlist> +<listitem> + <para> + <filename>name</filename>: The name of your device. It is + recommended to use the name of your kernel module for this. + </para> +</listitem> +<listitem> + <para> + <filename>version</filename>: A version string defined by your + driver. This allows the user space part of your driver to deal + with different versions of the kernel module. + </para> +</listitem> +<listitem> + <para> + <filename>event</filename>: The total number of interrupts + handled by the driver since the last time the device node was + read. + </para> +</listitem> +</itemizedlist> +<para> + These attributes appear under the + <filename>/sys/class/uio/uioX</filename> directory. Please + note that this directory might be a symlink, and not a real + directory. Any userspace code that accesses it must be able + to handle this. +</para> +<para> + Each UIO device can make one or more memory regions available for + memory mapping. This is necessary because some industrial I/O cards + require access to more than one PCI memory region in a driver. +</para> +<para> + Each mapping has its own directory in sysfs, the first mapping + appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. + Subsequent mappings create directories <filename>map1/</filename>, + <filename>map2/</filename>, and so on. These directories will only + appear if the size of the mapping is not 0. +</para> +<para> + Each <filename>mapX/</filename> directory contains two read-only files + that show start address and size of the memory: +</para> +<itemizedlist> +<listitem> + <para> + <filename>addr</filename>: The address of memory that can be mapped. + </para> +</listitem> +<listitem> + <para> + <filename>size</filename>: The size, in bytes, of the memory + pointed to by addr. + </para> +</listitem> +</itemizedlist> + +<para> + From userspace, the different mappings are distinguished by adjusting + the <varname>offset</varname> parameter of the + <function>mmap()</function> call. To map the memory of mapping N, you + have to use N times the page size as your offset: +</para> +<programlisting format="linespecific"> +offset = N * getpagesize(); +</programlisting> + +</sect1> +</chapter> + +<chapter id="using-uio_dummy" xreflabel="Using uio_dummy"> +<?dbhtml filename="using-uio_dummy.html"?> +<title>Using uio_dummy</title> + <para> + Well, there is no real use for uio_dummy. Its only purpose is + to test most parts of the UIO system (everything except + hardware interrupts), and to serve as an example for the + kernel module that you will have to write yourself. + </para> + +<sect1 id="what_uio_dummy_does"> +<title>What uio_dummy does</title> + <para> + The kernel module <filename>uio_dummy.ko</filename> creates a + device that uses a timer to generate periodic interrupts. The + interrupt handler does nothing but increment a counter. The + driver adds two custom attributes, <varname>count</varname> + and <varname>freq</varname>, that appear under + <filename>/sys/devices/platform/uio_dummy/</filename>. + </para> + + <para> + The attribute <varname>count</varname> can be read and + written. The associated file + <filename>/sys/devices/platform/uio_dummy/count</filename> + appears as a normal text file and contains the total number of + timer interrupts. If you look at it (e.g. using + <function>cat</function>), you'll notice it is slowly counting + up. + </para> + + <para> + The attribute <varname>freq</varname> can be read and written. + The content of + <filename>/sys/devices/platform/uio_dummy/freq</filename> + represents the number of system timer ticks between two timer + interrupts. The default value of <varname>freq</varname> is + the value of the kernel variable <varname>HZ</varname>, which + gives you an interval of one second. Lower values will + increase the frequency. Try the following: + </para> +<programlisting format="linespecific"> +cd /sys/devices/platform/uio_dummy/ +echo 100 > freq +</programlisting> + <para> + Use <function>cat count</function> to see how the interrupt + frequency changes. + </para> +</sect1> +</chapter> + +<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> +<?dbhtml filename="custom_kernel_module.html"?> +<title>Writing your own kernel module</title> + <para> + Please have a look at <filename>uio_dummy.c</filename> as an + example. The following paragraphs explain the different + sections of this file. + </para> + +<sect1 id="uio_info"> +<title>struct uio_info</title> + <para> + This structure tells the framework the details of your driver, + Some of the members are required, others are optional. + </para> + +<itemizedlist> +<listitem><para> +<varname>char *name</varname>: Required. The name of your driver as +it will appear in sysfs. I recommend using the name of your module for this. +</para></listitem> + +<listitem><para> +<varname>char *version</varname>: Required. This string appears in +<filename>/sys/class/uio/uioX/version</filename>. +</para></listitem> + +<listitem><para> +<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you +have memory that can be mapped with <function>mmap()</function>. For each +mapping you need to fill one of the <varname>uio_mem</varname> structures. +See the description below for details. +</para></listitem> + +<listitem><para> +<varname>long irq</varname>: Required. If your hardware generates an +interrupt, it's your modules task to determine the irq number during +initialization. If you don't have a hardware generated interrupt but +want to trigger the interrupt handler in some other way, set +<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. The +uio_dummy module does this as it triggers the event mechanism in a timer +routine. If you had no interrupt at all, you could set +<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this +rarely makes sense. +</para></listitem> + +<listitem><para> +<varname>unsigned long irq_flags</varname>: Required if you've set +<varname>irq</varname> to a hardware interrupt number. The flags given +here will be used in the call to <function>request_irq()</function>. +</para></listitem> + +<listitem><para> +<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct +*vma)</varname>: Optional. If you need a special +<function>mmap()</function> function, you can set it here. If this +pointer is not NULL, your <function>mmap()</function> will be called +instead of the built-in one. +</para></listitem> + +<listitem><para> +<varname>int (*open)(struct uio_info *info, struct inode *inode) +</varname>: Optional. You might want to have your own +<function>open()</function>, e.g. to enable interrupts only when your +device is actually used. +</para></listitem> + +<listitem><para> +<varname>int (*release)(struct uio_info *info, struct inode *inode) +</varname>: Optional. If you define your own +<function>open()</function>, you will probably also want a custom +<function>release()</function> function. +</para></listitem> +</itemizedlist> + +<para> +Usually, your device will have one or more memory regions that can be mapped +to user space. For each region, you have to set up a +<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. +Here's a description of the fields of <varname>struct uio_mem</varname>: +</para> + +<itemizedlist> +<listitem><para> +<varname>int memtype</varname>: Required if the mapping is used. Set this to +<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your +card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical +memory (e.g. allocated with <function>kmalloc()</function>). There's also +<varname>UIO_MEM_VIRTUAL</varname> for virtual memory. +</para></listitem> + +<listitem><para> +<varname>unsigned long addr</varname>: Required if the mapping is used. +Fill in the address of your memory block. This address is the one that +appears in sysfs. +</para></listitem> + +<listitem><para> +<varname>unsigned long size</varname>: Fill in the size of the +memory block that <varname>addr</varname> points to. If <varname>size</varname> +is zero, the mapping is considered unused. Note that you +<emphasis>must</emphasis> initialize <varname>size</varname> with zero for +all unused mappings. +</para></listitem> + +<listitem><para> +<varname>void *internal_addr</varname>: If you have to access this memory +region from within your kernel module, you will want to map it internally by +using something like <function>ioremap()</function>. Addresses +returned by this function cannot be mapped to user space, so you must not +store it in <varname>addr</varname>. Use <varname>internal_addr</varname> +instead to remember such an address. +</para></listitem> +</itemizedlist> + +<para> +Please do not touch the <varname>kobj</varname> element of +<varname>struct uio_mem</varname>! It is used by the UIO framework +to set up sysfs files for this mapping. Simply leave it alone. +</para> +</sect1> + +<sect1 id="adding_irq_handler"> +<title>Adding an interrupt handler</title> + <para> + What you need to do in your interrupt handler depends on your + hardware and on how you want to handle it. You should try to + keep the amount of code in your kernel interrupt handler low. + If your hardware requires no action that you + <emphasis>have</emphasis> to perform after each interrupt, + then your handler can be empty.</para> <para>If, on the other + hand, your hardware <emphasis>needs</emphasis> some action to + be performed after each interrupt, then you + <emphasis>must</emphasis> do it in your kernel module. Note + that you cannot rely on the userspace part of your driver. Your + userspace program can terminate at any time, possibly leaving + your hardware in a state where proper interrupt handling is + still required. + </para> + + <para> + There might also be applications where you want to read data + from your hardware at each interrupt and buffer it in a piece + of kernel memory you've allocated for that purpose. With this + technique you could avoid loss of data if your userspace + program misses an interrupt. + </para> + + <para> + A note on shared interrupts: Your driver should support + interrupt sharing whenever this is possible. It is possible if + and only if your driver can detect whether your hardware has + triggered the interrupt or not. This is usually done by looking + at an interrupt status register. If your driver sees that the + IRQ bit is actually set, it will perform its actions, and the + handler returns IRQ_HANDLED. If the driver detects that it was + not your hardware that caused the interrupt, it will do nothing + and return IRQ_NONE, allowing the kernel to call the next + possible interrupt handler. + </para> + + <para> + If you decide not to support shared interrupts, your card + won't work in computers with no free interrupts. As this + frequently happens on the PC platform, you can save yourself a + lot of trouble by supporting interrupt sharing. + </para> +</sect1> + +</chapter> + +<chapter id="userspace_driver" xreflabel="Writing a driver in user space"> +<?dbhtml filename="userspace_driver.html"?> +<title>Writing a driver in userspace</title> + <para> + Once you have a working kernel module for your hardware, you can + write the userspace part of your driver. You don't need any special + libraries, your driver can be written in any reasonable language, + you can use floating point numbers and so on. In short, you can + use all the tools and libraries you'd normally use for writing a + userspace application. + </para> + +<sect1 id="getting_uio_information"> +<title>Getting information about your UIO device</title> + <para> + Information about all UIO devices is available in sysfs. The + first thing you should do in your driver is check + <varname>name</varname> and <varname>version</varname> to + make sure your talking to the right device and that its kernel + driver has the version you expect. + </para> + <para> + You should also make sure that the memory mapping you need + exists and has the size you expect. + </para> + <para> + There is a tool called <varname>lsuio</varname> that lists + UIO devices and their attributes. It is available here: + </para> + <para> + <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> + http://www.osadl.org/projects/downloads/UIO/user/</ulink> + </para> + <para> + With <varname>lsuio</varname> you can quickly check if your + kernel module is loaded and which attributes it exports. + Have a look at the manpage for details. + </para> + <para> + The source code of <varname>lsuio</varname> can serve as an + example for getting information about an UIO device. + The file <filename>uio_helper.c</filename> contains a lot of + functions you could use in your userspace driver code. + </para> +</sect1> + +<sect1 id="mmap_device_memory"> +<title>mmap() device memory</title> + <para> + After you made sure you've got the right device with the + memory mappings you need, all you have to do is to call + <function>mmap()</function> to map the device's memory + to userspace. + </para> + <para> + The parameter <varname>offset</varname> of the + <function>mmap()</function> call has a special meaning + for UIO devices: It is used to select which mapping of + your device you want to map. To map the memory of + mapping N, you have to use N times the page size as + your offset: + </para> +<programlisting format="linespecific"> + offset = N * getpagesize(); +</programlisting> + <para> + N starts from zero, so if you've got only one memory + range to map, set <varname>offset = 0</varname>. + A drawback of this technique is that memory is always + mapped beginning with its start address. + </para> +</sect1> + +<sect1 id="wait_for_interrupts"> +<title>Waiting for interrupts</title> + <para> + After you successfully mapped your devices memory, you + can access it like an ordinary array. Usually, you will + perform some initialization. After that, your hardware + starts working and will generate an interrupt as soon + as it's finished, has some data available, or needs your + attention because an error occured. + </para> + <para> + <filename>/dev/uioX</filename> is a read-only file. A + <function>read()</function> will always block until an + interrupt occurs. There is only one legal value for the + <varname>count</varname> parameter of + <function>read()</function>, and that is the size of a + signed 32 bit integer (4). Any other value for + <varname>count</varname> causes <function>read()</function> + to fail. The signed 32 bit integer read is the interrupt + count of your device. If the value is one more than the value + you read the last time, everything is OK. If the difference + is greater than one, you missed interrupts. + </para> + <para> + You can also use <function>select()</function> on + <filename>/dev/uioX</filename>. + </para> +</sect1> + +</chapter> + +<appendix id="app1"> +<title>Further information</title> +<itemizedlist> + <listitem><para> + <ulink url="http://www.osadl.org"> + OSADL homepage.</ulink> + </para></listitem> + <listitem><para> + <ulink url="http://www.linutronix.de"> + Linutronix homepage.</ulink> + </para></listitem> +</itemizedlist> +</appendix> + +</book> diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 98e2701c746..f8cc3f8ed15 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -249,6 +249,9 @@ process is as follows: release a new -rc kernel every week. - Process continues until the kernel is considered "ready", the process should last around 6 weeks. + - A list of known regressions present in each -rc release is + tracked at the following URI: + http://kernelnewbies.org/known_regressions It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: diff --git a/Documentation/connector/cn_test.c b/Documentation/connector/cn_test.c index 3e73231695b..be7af146dd3 100644 --- a/Documentation/connector/cn_test.c +++ b/Documentation/connector/cn_test.c @@ -124,9 +124,8 @@ static void cn_test_timer_func(unsigned long __data) struct cn_msg *m; char data[32]; - m = kmalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); + m = kzalloc(sizeof(*m) + sizeof(data), GFP_ATOMIC); if (m) { - memset(m, 0, sizeof(*m) + sizeof(data)); memcpy(&m->id, &cn_test_id, sizeof(m->id)); m->seq = cn_test_timer_counter; diff --git a/Documentation/console/console.txt b/Documentation/console/console.txt index d3e17447321..877a1b26cc3 100644 --- a/Documentation/console/console.txt +++ b/Documentation/console/console.txt @@ -29,7 +29,7 @@ In newer kernels, the following are also available: If sysfs is enabled, the contents of /sys/class/vtconsole can be examined. This shows the console backends currently registered by the -system which are named vtcon<n> where <n> is an integer fro 0 to 15. Thus: +system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus: ls /sys/class/vtconsole . .. vtcon0 vtcon1 diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 6c8d8f27db3..8569072fa38 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -207,7 +207,7 @@ responsibility. This is usually non-issue because bus ops and resource allocations already do the job. For an example of single-instance devres type, read pcim_iomap_table() -in lib/iomap.c. +in lib/devres.c. All devres interface functions can be called without context if the right gfp mask is given. diff --git a/Documentation/drivers/edac/edac.txt b/Documentation/drivers/edac/edac.txt index 3c5a9e4297b..a5c36842ece 100644 --- a/Documentation/drivers/edac/edac.txt +++ b/Documentation/drivers/edac/edac.txt @@ -2,22 +2,42 @@ EDAC - Error Detection And Correction -Written by Doug Thompson <norsk5@xmission.com> +Written by Doug Thompson <dougthompson@xmission.com> 7 Dec 2005 +17 Jul 2007 Updated -EDAC was written by: - Thayne Harbaugh, - modified by Dave Peterson, Doug Thompson, et al, - from the bluesmoke.sourceforge.net project. +EDAC is maintained and written by: + Doug Thompson, Dave Jiang, Dave Peterson et al, + original author: Thayne Harbaugh, + +Contact: + website: bluesmoke.sourceforge.net + mailing list: bluesmoke-devel@lists.sourceforge.net + +"bluesmoke" was the name for this device driver when it was "out-of-tree" +and maintained at sourceforge.net. When it was pushed into 2.6.16 for the +first time, it was renamed to 'EDAC'. + +The bluesmoke project at sourceforge.net is now utilized as a 'staging area' +for EDAC development, before it is sent upstream to kernel.org + +At the bluesmoke/EDAC project site, is a series of quilt patches against +recent kernels, stored in a SVN respository. For easier downloading, there +is also a tarball snapshot available. ============================================================================ EDAC PURPOSE The 'edac' kernel module goal is to detect and report errors that occur -within the computer system. In the initial release, memory Correctable Errors -(CE) and Uncorrectable Errors (UE) are the primary errors being harvested. +within the computer system running under linux. + +MEMORY + +In the initial release, memory Correctable Errors (CE) and Uncorrectable +Errors (UE) are the primary errors being harvested. These types of errors +are harvested by the 'edac_mc' class of device. Detecting CE events, then harvesting those events and reporting them, CAN be a predictor of future UE events. With CE events, the system can @@ -25,9 +45,27 @@ continue to operate, but with less safety. Preventive maintenance and proactive part replacement of memory DIMMs exhibiting CEs can reduce the likelihood of the dreaded UE events and system 'panics'. +NON-MEMORY + +A new feature for EDAC, the edac_device class of device, was added in +the 2.6.23 version of the kernel. + +This new device type allows for non-memory type of ECC hardware detectors +to have their states harvested and presented to userspace via the sysfs +interface. + +Some architectures have ECC detectors for L1, L2 and L3 caches, along with DMA +engines, fabric switches, main data path switches, interconnections, +and various other hardware data paths. If the hardware reports it, then +a edac_device device probably can be constructed to harvest and present +that to userspace. + + +PCI BUS SCANNING In addition, PCI Bus Parity and SERR Errors are scanned for on PCI devices in order to determine if errors are occurring on data transfers. + The presence of PCI Parity errors must be examined with a grain of salt. There are several add-in adapters that do NOT follow the PCI specification with regards to Parity generation and reporting. The specification says @@ -35,11 +73,17 @@ the vendor should tie the parity status bits to 0 if they do not intend to generate parity. Some vendors do not do this, and thus the parity bit can "float" giving false positives. -[There are patches in the kernel queue which will allow for storage of -quirks of PCI devices reporting false parity positives. The 2.6.18 -kernel should have those patches included. When that becomes available, -then EDAC will be patched to utilize that information to "skip" such -devices.] +In the kernel there is a pci device attribute located in sysfs that is +checked by the EDAC PCI scanning code. If that attribute is set, +PCI parity/error scannining is skipped for that device. The attribute +is: + + broken_parity_status + +as is located in /sys/devices/pci<XXX>/0000:XX:YY.Z directorys for +PCI devices. + +FUTURE HARDWARE SCANNING EDAC will have future error detectors that will be integrated with EDAC or added to it, in the following list: @@ -57,13 +101,14 @@ and the like. ============================================================================ EDAC VERSIONING -EDAC is composed of a "core" module (edac_mc.ko) and several Memory +EDAC is composed of a "core" module (edac_core.ko) and several Memory Controller (MC) driver modules. On a given system, the CORE is loaded and one MC driver will be loaded. Both the CORE and -the MC driver have individual versions that reflect current release -level of their respective modules. Thus, to "report" on what version -a system is running, one must report both the CORE's and the -MC driver's versions. +the MC driver (or edac_device driver) have individual versions that reflect +current release level of their respective modules. + +Thus, to "report" on what version a system is running, one must report both +the CORE's and the MC driver's versions. LOADING @@ -88,8 +133,9 @@ EDAC sysfs INTERFACE EDAC presents a 'sysfs' interface for control, reporting and attribute reporting purposes. -EDAC lives in the /sys/devices/system/edac directory. Within this directory -there currently reside 2 'edac' components: +EDAC lives in the /sys/devices/system/edac directory. + +Within this directory there currently reside 2 'edac' components: mc memory controller(s) system pci PCI control and status system @@ -188,7 +234,7 @@ In directory 'mc' are EDAC system overall control and attribute files: Panic on UE control file: - 'panic_on_ue' + 'edac_mc_panic_on_ue' An uncorrectable error will cause a machine panic. This is usually desirable. It is a bad idea to continue when an uncorrectable error @@ -199,12 +245,12 @@ Panic on UE control file: LOAD TIME: module/kernel parameter: panic_on_ue=[0|1] - RUN TIME: echo "1" >/sys/devices/system/edac/mc/panic_on_ue + RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_panic_on_ue Log UE control file: - 'log_ue' + 'edac_mc_log_ue' Generate kernel messages describing uncorrectable errors. These errors are reported through the system message log system. UE statistics @@ -212,12 +258,12 @@ Log UE control file: LOAD TIME: module/kernel parameter: log_ue=[0|1] - RUN TIME: echo "1" >/sys/devices/system/edac/mc/log_ue + RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ue Log CE control file: - 'log_ce' + 'edac_mc_log_ce' Generate kernel messages describing correctable errors. These errors are reported through the system message log system. @@ -225,12 +271,12 @@ Log CE control file: LOAD TIME: module/kernel parameter: log_ce=[0|1] - RUN TIME: echo "1" >/sys/devices/system/edac/mc/log_ce + RUN TIME: echo "1" >/sys/devices/system/edac/mc/edac_mc_log_ce Polling period control file: - 'poll_msec' + 'edac_mc_poll_msec' The time period, in milliseconds, for polling for error information. Too small a value wastes resources. Too large a value might delay @@ -241,7 +287,7 @@ Polling period control file: LOAD TIME: module/kernel parameter: poll_msec=[0|1] - RUN TIME: echo "1000" >/sys/devices/system/edac/mc/poll_msec + RUN TIME: echo "1000" >/sys/devices/system/edac/mc/edac_mc_poll_msec ============================================================================ @@ -587,3 +633,95 @@ Parity Count: ======================================================================= + + +EDAC_DEVICE type of device + +In the header file, edac_core.h, there is a series of edac_device structures +and APIs for the EDAC_DEVICE. + +User space access to an edac_device is through the sysfs interface. + +At the location /sys/devices/system/edac (sysfs) new edac_device devices will +appear. + +There is a three level tree beneath the above 'edac' directory. For example, +the 'test_device_edac' device (found at the bluesmoke.sourceforget.net website) +installs itself as: + + /sys/devices/systm/edac/test-instance + +in this directory are various controls, a symlink and one or more 'instance' +directorys. + +The standard default controls are: + + log_ce boolean to log CE events + log_ue boolean to log UE events + panic_on_ue boolean to 'panic' the system if an UE is encountered + (default off, can be set true via startup script) + poll_msec time period between POLL cycles for events + +The test_device_edac device adds at least one of its own custom control: + + test_bits which in the current test driver does nothing but + show how it is installed. A ported driver can + add one or more such controls and/or attributes + for specific uses. + One out-of-tree driver uses controls here to allow + for ERROR INJECTION operations to hardware + injection registers + +The symlink points to the 'struct dev' that is registered for this edac_device. + +INSTANCES + +One or more instance directories are present. For the 'test_device_edac' case: + + test-instance0 + + +In this directory there are two default counter attributes, which are totals of +counter in deeper subdirectories. + + ce_count total of CE events of subdirectories + ue_count total of UE events of subdirectories + +BLOCKS + +At the lowest directory level is the 'block' directory. There can be 0, 1 +or more blocks specified in each instance. + + test-block0 + + +In this directory the default attributes are: + + ce_count which is counter of CE events for this 'block' + of hardware being monitored + ue_count which is counter of UE events for this 'block' + of hardware being monitored + + +The 'test_device_edac' device adds 4 attributes and 1 control: + + test-block-bits-0 for every POLL cycle this counter + is incremented + test-block-bits-1 every 10 cycles, this counter is bumped once, + and test-block-bits-0 is set to 0 + test-block-bits-2 every 100 cycles, this counter is bumped once, + and test-block-bits-1 is set to 0 + test-block-bits-3 every 1000 cycles, this counter is bumped once, + and test-block-bits-2 is set to 0 + + + reset-counters writing ANY thing to this control will + reset all the above counters. + + +Use of the 'test_device_edac' driver should any others to create their own +unique drivers for their hardware systems. + +The 'test_device_edac' sample driver is located at the +bluesmoke.sourceforge.net project site for EDAC. + diff --git a/Documentation/dvb/bt8xx.txt b/Documentation/dvb/bt8xx.txt index 4e7614e606c..ecb47adda06 100644 --- a/Documentation/dvb/bt8xx.txt +++ b/Documentation/dvb/bt8xx.txt @@ -9,19 +9,29 @@ for accessing the i2c bus and the gpio pins of the bt8xx chipset. Please see Documentation/dvb/cards.txt => o Cards based on the Conexant Bt8xx PCI bridge: Compiling kernel please enable: -a.)"Device drivers" => "Multimedia devices" => "Video For Linux" => "BT848 Video For Linux" -b.)"Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" - => "DVB for Linux" "DVB Core Support" "Bt8xx based PCI Cards" +a.)"Device drivers" => "Multimedia devices" => "Video For Linux" => "Enable Video for Linux API 1 (DEPRECATED)" +b.)"Device drivers" => "Multimedia devices" => "Video For Linux" => "Video Capture Adapters" => "BT848 Video For Linux" +c.)"Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" => "DVB for Linux" "DVB Core Support" "Bt8xx based PCI Cards" -2) Loading Modules -================== +Please use the following options with care as deselection of drivers which are in fact necessary +may result in DVB devices that cannot be tuned due to lack of driver support: +You can save RAM by deselecting every frontend module that your DVB card does not need. + +First please remove the static dependency of DVB card drivers on all frontend modules for all possible card variants by enabling: +d.) "Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" + => "DVB for Linux" "DVB Core Support" "Load and attach frontend modules as needed" -In default cases bttv is loaded automatically. -To load the backend either place dvb-bt8xx in etc/modules, or apply manually: +If you know the frontend driver that your card needs please enable: +e.)"Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" + => "DVB for Linux" "DVB Core Support" "Customise DVB Frontends" => "Customise the frontend modules to build" + Then please select your card-specific frontend module. - $ modprobe dvb-bt8xx +2) Loading Modules +================== -All frontends will be loaded automatically. +Regular case: If the bttv driver detects a bt8xx-based DVB card, all frontend and backend modules will be loaded automatically. +Exceptions are: +- Old TwinHan DST cards or clones with or without CA slot and not containing an Eeprom. People running udev please see Documentation/dvb/udev.txt. In the following cases overriding the PCI type detection for dvb-bt8xx might be necessary: @@ -30,7 +40,6 @@ In the following cases overriding the PCI type detection for dvb-bt8xx might be ------------------------------ $ modprobe bttv card=113 - $ modprobe dvb-bt8xx $ modprobe dst Useful parameters for verbosity level and debugging the dst module: @@ -65,10 +74,9 @@ DViCO FusionHDTV 5 Lite: 135 Notice: The order of the card ID should be uprising: Example: $ modprobe bttv card=113 card=135 - $ modprobe dvb-bt8xx For a full list of card ID's please see Documentation/video4linux/CARDLIST.bttv. -In case of further problems send questions to the mailing list: www.linuxdvb.org. +In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org. Authors: Richard Walker, Jamie Honan, diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 4820366b6ae..b4d306ae923 100644 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -24,7 +24,8 @@ use IO::Handle; @components = ( "sp8870", "sp887x", "tda10045", "tda10046", "tda10046lifeview", "av7110", "dec2000t", "dec2540t", "dec3000s", "vp7041", "dibusb", "nxt2002", "nxt2004", - "or51211", "or51132_qam", "or51132_vsb", "bluebird"); + "or51211", "or51132_qam", "or51132_vsb", "bluebird", + "opera1"); # Check args syntax() if (scalar(@ARGV) != 1); @@ -56,7 +57,7 @@ syntax(); sub sp8870 { my $sourcefile = "tt_Premium_217g.zip"; - my $url = "http://www.technotrend.de/new/217g/$sourcefile"; + my $url = "http://www.softwarepatch.pl/9999ccd06a4813cb827dbb0005071c71/$sourcefile"; my $hash = "53970ec17a538945a6d8cb608a7b3899"; my $outfile = "dvb-fe-sp8870.fw"; my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); @@ -210,6 +211,45 @@ sub dec3000s { $outfile; } +sub opera1{ + my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 0); + + checkstandard(); + my $fwfile1="dvb-usb-opera1-fpga-01.fw"; + my $fwfile2="dvb-usb-opera-01.fw"; + extract("2830SCap2.sys", 0x62e8, 55024, "$tmpdir/opera1-fpga.fw"); + extract("2830SLoad2.sys",0x3178,0x3685-0x3178,"$tmpdir/fw1part1"); + extract("2830SLoad2.sys",0x0980,0x3150-0x0980,"$tmpdir/fw1part2"); + delzero("$tmpdir/fw1part1","$tmpdir/fw1part1-1"); + delzero("$tmpdir/fw1part2","$tmpdir/fw1part2-1"); + verify("$tmpdir/fw1part1-1","5e0909858fdf0b5b09ad48b9fe622e70"); + verify("$tmpdir/fw1part2-1","d6e146f321427e931df2c6fcadac37a1"); + verify("$tmpdir/opera1-fpga.fw","0f8133f5e9051f5f3c1928f7e5a1b07d"); + + my $RES1="\x01\x92\x7f\x00\x01\x00"; + my $RES0="\x01\x92\x7f\x00\x00\x00"; + my $DAT1="\x01\x00\xe6\x00\x01\x00"; + my $DAT0="\x01\x00\xe6\x00\x00\x00"; + open FW,">$tmpdir/opera.fw"; + print FW "$RES1"; + print FW "$DAT1"; + print FW "$RES1"; + print FW "$DAT1"; + appendfile(FW,"$tmpdir/fw1part1-1"); + print FW "$RES0"; + print FW "$DAT0"; + print FW "$RES1"; + print FW "$DAT1"; + appendfile(FW,"$tmpdir/fw1part2-1"); + print FW "$RES1"; + print FW "$DAT1"; + print FW "$RES0"; + print FW "$DAT0"; + copy ("$tmpdir/opera1-fpga.fw",$fwfile1); + copy ("$tmpdir/opera.fw",$fwfile2); + + $fwfile1.",".$fwfile2; +} sub vp7041 { my $sourcefile = "2.422.zip"; @@ -440,6 +480,25 @@ sub appendfile { close(INFILE); } +sub delzero{ + my ($infile,$outfile) =@_; + + open INFILE,"<$infile"; + open OUTFILE,">$outfile"; + while (1){ + $rcount=sysread(INFILE,$buf,22); + $len=ord(substr($buf,0,1)); + print OUTFILE substr($buf,0,1); + print OUTFILE substr($buf,2,$len+3); + last if ($rcount<1); + printf OUTFILE "%c",0; +#print $len." ".length($buf)."\n"; + + } + close(INFILE); + close(OUTFILE); +} + sub syntax() { print STDERR "syntax: get_dvb_firmware <component>\n"; print STDERR "Supported components:\n"; diff --git a/Documentation/dvb/opera-firmware.txt b/Documentation/dvb/opera-firmware.txt new file mode 100644 index 00000000000..93e784c2607 --- /dev/null +++ b/Documentation/dvb/opera-firmware.txt @@ -0,0 +1,27 @@ +To extract the firmware for the Opera DVB-S1 USB-Box +you need to copy the files: + +2830SCap2.sys +2830SLoad2.sys + +from the windriver disk into this directory. + +Then run + +./get_dvb_firware opera1 + +and after that you have 2 files: + +dvb-usb-opera-01.fw +dvb-usb-opera1-fpga-01.fw + +in here. + +Copy them into /lib/firmware/ . + +After that the driver can load the firmware +(if you have enabled firmware loading +in kernel config and have hotplug running). + + +Marco Gittler <g.marco@freenet.de>
\ No newline at end of file diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index d05e6243b4d..c175eedadb5 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -26,9 +26,7 @@ Who: Hans Verkuil <hverkuil@xs4all.nl> and --------------------------- -What: /sys/devices/.../power/state - dev->power.power_state - dpm_runtime_{suspend,resume)() +What: dev->power.power_state When: July 2007 Why: Broken design for runtime control over driver power states, confusing driver-internal runtime power management with: mechanisms to support @@ -53,6 +51,7 @@ Who: David Miller <davem@davemloft.net> What: Video4Linux API 1 ioctls and video_decoder.h from Video devices. When: December 2006 Files: include/linux/video_decoder.h +Check: include/linux/video_decoder.h Why: V4L1 AP1 was replaced by V4L2 API. during migration from 2.4 to 2.6 series. The old API have lots of drawbacks and don't provide enough means to work with all video and audio standards. The newer API is @@ -86,7 +85,7 @@ Who: Dominik Brodowski <linux@brodo.de> What: remove EXPORT_SYMBOL(kernel_thread) When: August 2006 Files: arch/*/kernel/*_ksyms.c -Funcs: kernel_thread +Check: kernel_thread Why: kernel_thread is a low-level implementation detail. Drivers should use the <linux/kthread.h> API instead which shields them from implementation details and provides a higherlevel interface that @@ -137,6 +136,15 @@ Who: Greg Kroah-Hartman <gregkh@suse.de> --------------------------- +What: vm_ops.nopage +When: Soon, provided in-kernel callers have been converted +Why: This interface is replaced by vm_ops.fault, but it has been around + forever, is used by a lot of drivers, and doesn't cost much to + maintain. +Who: Nick Piggin <npiggin@suse.de> + +--------------------------- + What: Interrupt only SA_* flags When: September 2007 Why: The interrupt related SA_* flags are replaced by IRQF_* to move them @@ -156,15 +164,6 @@ Who: Kay Sievers <kay.sievers@suse.de> --------------------------- -What: i2c-isa -When: December 2006 -Why: i2c-isa is a non-sense and doesn't fit in the device driver - model. Drivers relying on it are better implemented as platform - drivers. -Who: Jean Delvare <khali@linux-fr.org> - ---------------------------- - What: i2c_adapter.list When: July 2007 Why: Superfluous, this list duplicates the one maintained by the driver @@ -181,24 +180,11 @@ Who: Adrian Bunk <bunk@stusta.de> --------------------------- -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. +When: July 2008 +Why: ACPI sysfs conversion should be finished by January 2008. + ACPI procfs interface will be removed in July 2008 so that + there is enough time for the user space to catch up. Who: Zhang Rui <rui.zhang@intel.com> --------------------------- @@ -310,3 +296,13 @@ Why: The arch/powerpc tree is the merged architecture for ppc32 and ppc64 Who: linuxppc-dev@ozlabs.org --------------------------- + +What: mthca driver's MSI support +When: January 2008 +Files: drivers/infiniband/hw/mthca/*.[ch] +Why: All mthca hardware also supports MSI-X, which provides + strictly more functionality than MSI. So there is no point in + having both MSI-X and MSI support in the driver. +Who: Roland Dreier <rolandd@cisco.com> + +--------------------------- diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index d866551be03..f0f825808ca 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -510,13 +510,24 @@ More details about quota locking can be found in fs/dquot.c. prototypes: void (*open)(struct vm_area_struct*); void (*close)(struct vm_area_struct*); + int (*fault)(struct vm_area_struct*, struct vm_fault *); struct page *(*nopage)(struct vm_area_struct*, unsigned long, int *); + int (*page_mkwrite)(struct vm_area_struct *, struct page *); locking rules: - BKL mmap_sem + BKL mmap_sem PageLocked(page) open: no yes close: no yes +fault: no yes nopage: no yes +page_mkwrite: no yes no + + ->page_mkwrite() is called when a previously read-only page is +about to become writeable. The file system is responsible for +protecting against truncate races. Once appropriate action has been +taking to lock out truncate, the page range should be verified to be +within i_size. The page mapping should also be checked that it is not +NULL. ================================================================================ Dubious stuff diff --git a/Documentation/filesystems/configfs/configfs_example.c b/Documentation/filesystems/configfs/configfs_example.c index e56d49264b3..25151fd5c2c 100644 --- a/Documentation/filesystems/configfs/configfs_example.c +++ b/Documentation/filesystems/configfs/configfs_example.c @@ -277,11 +277,10 @@ static struct config_item *simple_children_make_item(struct config_group *group, { struct simple_child *simple_child; - simple_child = kmalloc(sizeof(struct simple_child), GFP_KERNEL); + simple_child = kzalloc(sizeof(struct simple_child), GFP_KERNEL); if (!simple_child) return NULL; - memset(simple_child, 0, sizeof(struct simple_child)); config_item_init_type_name(&simple_child->item, name, &simple_child_type); @@ -364,12 +363,11 @@ static struct config_group *group_children_make_group(struct config_group *group { struct simple_children *simple_children; - simple_children = kmalloc(sizeof(struct simple_children), + simple_children = kzalloc(sizeof(struct simple_children), GFP_KERNEL); if (!simple_children) return NULL; - memset(simple_children, 0, sizeof(struct simple_children)); config_group_init_type_name(&simple_children->group, name, &simple_children_type); diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index ebffdffb3d9..4a37e25e694 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -42,6 +42,7 @@ Table of Contents 2.12 /proc/<pid>/oom_adj - Adjust the oom-killer score 2.13 /proc/<pid>/oom_score - Display current oom-killer score 2.14 /proc/<pid>/io - Display the IO accounting fields + 2.15 /proc/<pid>/coredump_filter - Core dump filtering settings ------------------------------------------------------------------------------ Preface @@ -1065,6 +1066,13 @@ check the amount of free space (value is in seconds). Default settings are: 4, resume it if we have a value of 3 or more percent; consider information about the amount of free space valid for 30 seconds +audit_argv_kb +------------- + +The file contains a single value denoting the limit on the argv array size +for execve (in KiB). This limit is only applied when system call auditing for +execve is enabled, otherwise the value is ignored. + ctrl-alt-del ------------ @@ -2177,4 +2185,41 @@ those 64-bit counters, process A could see an intermediate result. More information about this can be found within the taskstats documentation in Documentation/accounting. +2.15 /proc/<pid>/coredump_filter - Core dump filtering settings +--------------------------------------------------------------- +When a process is dumped, all anonymous memory is written to a core file as +long as the size of the core file isn't limited. But sometimes we don't want +to dump some memory segments, for example, huge shared memory. Conversely, +sometimes we want to save file-backed memory segments into a core file, not +only the individual files. + +/proc/<pid>/coredump_filter allows you to customize which memory segments +will be dumped when the <pid> process is dumped. coredump_filter is a bitmask +of memory types. If a bit of the bitmask is set, memory segments of the +corresponding memory type are dumped, otherwise they are not dumped. + +The following 4 memory types are supported: + - (bit 0) anonymous private memory + - (bit 1) anonymous shared memory + - (bit 2) file-backed private memory + - (bit 3) file-backed shared memory + + Note that MMIO pages such as frame buffer are never dumped and vDSO pages + are always dumped regardless of the bitmask status. + +Default value of coredump_filter is 0x3; this means all anonymous memory +segments are dumped. + +If you don't want to dump all shared memory segments attached to pid 1234, +write 1 to the process's proc file. + + $ echo 0x1 > /proc/1234/coredump_filter + +When a new process is created, the process inherits the bitmask status from its +parent. It is useful to set up coredump_filter before the program runs. +For example: + + $ echo 0x7 > /proc/self/coredump_filter + $ ./some_program + ------------------------------------------------------------------------------ diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 36af58eba13..218a8650f48 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -75,6 +75,9 @@ using the include file: If you stick to this convention then it'll be easier for other developers to see what your code is doing, and help maintain it. +Note that these operations include I/O barriers on platforms which need to +use them; drivers don't need to add them explicitly. + Identifying GPIOs ----------------- diff --git a/Documentation/hwmon/abituguru b/Documentation/hwmon/abituguru index b2c0d61b39a..87ffa0f5ec7 100644 --- a/Documentation/hwmon/abituguru +++ b/Documentation/hwmon/abituguru @@ -2,7 +2,7 @@ Kernel driver abituguru ======================= Supported chips: - * Abit uGuru revision 1-3 (Hardware Monitor part only) + * Abit uGuru revision 1 & 2 (Hardware Monitor part only) Prefix: 'abituguru' Addresses scanned: ISA 0x0E0 Datasheet: Not available, this driver is based on reverse engineering. @@ -20,8 +20,8 @@ Supported chips: uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) uGuru 2.2.0.0 ~ 2.2.0.6 (AA8 Fatal1ty) uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) - uGuru 3.0.0.0 ~ 3.0.1.2 (AW8, AL8, NI8) - uGuru 4.xxxxx? (AT8 32X) (2) + uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, + AW9D-MAX) (2) 1) For revisions 2 and 3 uGuru's the driver can autodetect the sensortype (Volt or Temp) for bank1 sensors, for revision 1 uGuru's this doesnot always work. For these uGuru's the autodection can @@ -30,8 +30,9 @@ Supported chips: bank1_types=1,1,0,0,0,0,0,2,0,0,0,0,2,0,0,1 You may also need to specify the fan_sensors option for these boards fan_sensors=5 - 2) The current version of the abituguru driver is known to NOT work - on these Motherboards + 2) There is a seperate abituguru3 driver for these motherboards, + the abituguru (without the 3 !) driver will not work on these + motherboards (and visa versa)! Authors: Hans de Goede <j.w.r.degoede@hhs.nl>, @@ -43,8 +44,10 @@ Module Parameters ----------------- * force: bool Force detection. Note this parameter only causes the - detection to be skipped, if the uGuru can't be read - the module initialization (insmod) will still fail. + detection to be skipped, and thus the insmod to + succeed. If the uGuru can't be read the actual hwmon + driver will not load and thus no hwmon device will get + registered. * bank1_types: int[] Bank1 sensortype autodetection override: -1 autodetect (default) 0 volt sensor @@ -69,13 +72,15 @@ dmesg | grep abituguru Description ----------- -This driver supports the hardware monitoring features of the Abit uGuru chip -found on Abit uGuru featuring motherboards (most modern Abit motherboards). +This driver supports the hardware monitoring features of the first and +second revision of the Abit uGuru chip found on Abit uGuru featuring +motherboards (most modern Abit motherboards). -The uGuru chip in reality is a Winbond W83L950D in disguise (despite Abit -claiming it is "a new microprocessor designed by the ABIT Engineers"). -Unfortunatly this doesn't help since the W83L950D is a generic -microcontroller with a custom Abit application running on it. +The first and second revision of the uGuru chip in reality is a Winbond +W83L950D in disguise (despite Abit claiming it is "a new microprocessor +designed by the ABIT Engineers"). Unfortunatly this doesn't help since the +W83L950D is a generic microcontroller with a custom Abit application running +on it. Despite Abit not releasing any information regarding the uGuru, Olle Sandberg <ollebull@gmail.com> has managed to reverse engineer the sensor part diff --git a/Documentation/hwmon/abituguru3 b/Documentation/hwmon/abituguru3 new file mode 100644 index 00000000000..fa598aac22f --- /dev/null +++ b/Documentation/hwmon/abituguru3 @@ -0,0 +1,65 @@ +Kernel driver abituguru3 +======================== + +Supported chips: + * Abit uGuru revision 3 (Hardware Monitor part, reading only) + Prefix: 'abituguru3' + Addresses scanned: ISA 0x0E0 + Datasheet: Not available, this driver is based on reverse engineering. + Note: + The uGuru is a microcontroller with onboard firmware which programs + it to behave as a hwmon IC. There are many different revisions of the + firmware and thus effectivly many different revisions of the uGuru. + Below is an incomplete list with which revisions are used for which + Motherboards: + uGuru 1.00 ~ 1.24 (AI7, KV8-MAX3, AN7) + uGuru 2.0.0.0 ~ 2.0.4.2 (KV8-PRO) + uGuru 2.1.0.0 ~ 2.1.2.8 (AS8, AV8, AA8, AG8, AA8XE, AX8) + uGuru 2.3.0.0 ~ 2.3.0.9 (AN8) + uGuru 3.0.0.0 ~ 3.0.x.x (AW8, AL8, AT8, NI8 SLI, AT8 32X, AN8 32X, + AW9D-MAX) + The abituguru3 driver is only for revison 3.0.x.x motherboards, + this driver will not work on older motherboards. For older + motherboards use the abituguru (without the 3 !) driver. + +Authors: + Hans de Goede <j.w.r.degoede@hhs.nl>, + (Initial reverse engineering done by Louis Kruger) + + +Module Parameters +----------------- + +* force: bool Force detection. Note this parameter only causes the + detection to be skipped, and thus the insmod to + succeed. If the uGuru can't be read the actual hwmon + driver will not load and thus no hwmon device will get + registered. +* verbose: bool Should the driver be verbose? + 0/off/false normal output + 1/on/true + verbose error reporting (default) + Default: 1 (the driver is still in the testing phase) + +Description +----------- + +This driver supports the hardware monitoring features of the third revision of +the Abit uGuru chip, found on recent Abit uGuru featuring motherboards. + +The 3rd revision of the uGuru chip in reality is a Winbond W83L951G. +Unfortunatly this doesn't help since the W83L951G is a generic microcontroller +with a custom Abit application running on it. + +Despite Abit not releasing any information regarding the uGuru revision 3, +Louis Kruger has managed to reverse engineer the sensor part of the uGuru. +Without his work this driver would not have been possible. + +Known Issues +------------ + +The voltage and frequency control parts of the Abit uGuru are not supported, +neither is writing any of the sensor settings and writing / reading the +fanspeed control registers (FanEQ) + +If you encounter any problems please mail me <j.w.r.degoede@hhs.nl> and +include the output of: "dmesg | grep abituguru" diff --git a/Documentation/hwmon/dme1737 b/Documentation/hwmon/dme1737 new file mode 100644 index 00000000000..1a0f3d64ab8 --- /dev/null +++ b/Documentation/hwmon/dme1737 @@ -0,0 +1,257 @@ +Kernel driver dme1737 +===================== + +Supported chips: + * SMSC DME1737 and compatibles (like Asus A8000) + Prefix: 'dme1737' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: Provided by SMSC upon request and under NDA + +Authors: + Juerg Haefliger <juergh@gmail.com> + + +Module Parameters +----------------- + +* force_start: bool Enables the monitoring of voltage, fan and temp inputs + and PWM output control functions. Using this parameter + shouldn't be required since the BIOS usually takes care + of this. + +Note that there is no need to use this parameter if the driver loads without +complaining. The driver will say so if it is necessary. + + +Description +----------- + +This driver implements support for the hardware monitoring capabilities of the +SMSC DME1737 and Asus A8000 (which are the same) Super-I/O chips. This chip +features monitoring of 3 temp sensors temp[1-3] (2 remote diodes and 1 +internal), 7 voltages in[0-6] (6 external and 1 internal) and 6 fan speeds +fan[1-6]. Additionally, the chip implements 5 PWM outputs pwm[1-3,5-6] for +controlling fan speeds both manually and automatically. + +Fan[3-6] and pwm[3,5-6] are optional features and their availability is +dependent on the configuration of the chip. The driver will detect which +features are present during initialization and create the sysfs attributes +accordingly. + + +Voltage Monitoring +------------------ + +The voltage inputs are sampled with 12-bit resolution and have internal +scaling resistors. The values returned by the driver therefore reflect true +millivolts and don't need scaling. The voltage inputs are mapped as follows +(the last column indicates the input ranges): + + in0: +5VTR (+5V standby) 0V - 6.64V + in1: Vccp (processor core) 0V - 3V + in2: VCC (internal +3.3V) 0V - 4.38V + in3: +5V 0V - 6.64V + in4: +12V 0V - 16V + in5: VTR (+3.3V standby) 0V - 4.38V + in6: Vbat (+3.0V) 0V - 4.38V + +Each voltage input has associated min and max limits which trigger an alarm +when crossed. + + +Temperature Monitoring +---------------------- + +Temperatures are measured with 12-bit resolution and reported in millidegree +Celsius. The chip also features offsets for all 3 temperature inputs which - +when programmed - get added to the input readings. The chip does all the +scaling by itself and the driver therefore reports true temperatures that don't +need any user-space adjustments. The temperature inputs are mapped as follows +(the last column indicates the input ranges): + + temp1: Remote diode 1 (3904 type) temperature -127C - +127C + temp2: DME1737 internal temperature -127C - +127C + temp3: Remote diode 2 (3904 type) temperature -127C - +127C + +Each temperature input has associated min and max limits which trigger an alarm +when crossed. Additionally, each temperature input has a fault attribute that +returns 1 when a faulty diode or an unconnected input is detected and 0 +otherwise. + + +Fan Monitoring +-------------- + +Fan RPMs are measured with 16-bit resolution. The chip provides inputs for 6 +fan tachometers. All 6 inputs have an associated min limit which triggers an +alarm when crossed. Fan inputs 1-4 provide type attributes that need to be set +to the number of pulses per fan revolution that the connected tachometer +generates. Supported values are 1, 2, and 4. Fan inputs 5-6 only support fans +that generate 2 pulses per revolution. Fan inputs 5-6 also provide a max +attribute that needs to be set to the maximum attainable RPM (fan at 100% duty- +cycle) of the input. The chip adjusts the sampling rate based on this value. + + +PWM Output Control +------------------ + +This chip features 5 PWM outputs. PWM outputs 1-3 are associated with fan +inputs 1-3 and PWM outputs 5-6 are associated with fan inputs 5-6. PWM outputs +1-3 can be configured to operate either in manual or automatic mode by setting +the appropriate enable attribute accordingly. PWM outputs 5-6 can only operate +in manual mode, their enable attributes are therefore read-only. When set to +manual mode, the fan speed is set by writing the duty-cycle value to the +appropriate PWM attribute. In automatic mode, the PWM attribute returns the +current duty-cycle as set by the fan controller in the chip. All PWM outputs +support the setting of the output frequency via the freq attribute. + +In automatic mode, the chip supports the setting of the PWM ramp rate which +defines how fast the PWM output is adjusting to changes of the associated +temperature input. Associating PWM outputs to temperature inputs is done via +temperature zones. The chip features 3 zones whose assignments to temperature +inputs is static and determined during initialization. These assignments can +be retrieved via the zone[1-3]_auto_channels_temp attributes. Each PWM output +is assigned to one (or hottest of multiple) temperature zone(s) through the +pwm[1-3]_auto_channels_zone attributes. Each PWM output has 3 distinct output +duty-cycles: full, low, and min. Full is internally hard-wired to 255 (100%) +and low and min can be programmed via pwm[1-3]_auto_point1_pwm and +pwm[1-3]_auto_pwm_min, respectively. The thermal thresholds of the zones are +programmed via zone[1-3]_auto_point[1-3]_temp and +zone[1-3]_auto_point1_temp_hyst: + + pwm[1-3]_auto_point2_pwm full-speed duty-cycle (255, i.e., 100%) + pwm[1-3]_auto_point1_pwm low-speed duty-cycle + pwm[1-3]_auto_pwm_min min-speed duty-cycle + + zone[1-3]_auto_point3_temp full-speed temp (all outputs) + zone[1-3]_auto_point2_temp full-speed temp + zone[1-3]_auto_point1_temp low-speed temp + zone[1-3]_auto_point1_temp_hyst min-speed temp + +The chip adjusts the output duty-cycle linearly in the range of auto_point1_pwm +to auto_point2_pwm if the temperature of the associated zone is between +auto_point1_temp and auto_point2_temp. If the temperature drops below the +auto_point1_temp_hyst value, the output duty-cycle is set to the auto_pwm_min +value which only supports two values: 0 or auto_point1_pwm. That means that the +fan either turns completely off or keeps spinning with the low-speed +duty-cycle. If any of the temperatures rise above the auto_point3_temp value, +all PWM outputs are set to 100% duty-cycle. + +Following is another representation of how the chip sets the output duty-cycle +based on the temperature of the associated thermal zone: + + Duty-Cycle Duty-Cycle + Temperature Rising Temp Falling Temp + ----------- ----------- ------------ + full-speed full-speed full-speed + + < linearly adjusted duty-cycle > + + low-speed low-speed low-speed + min-speed low-speed + min-speed min-speed min-speed + min-speed min-speed + + +Sysfs Attributes +---------------- + +Following is a list of all sysfs attributes that the driver provides, their +permissions and a short description: + +Name Perm Description +---- ---- ----------- +cpu0_vid RO CPU core reference voltage in + millivolts. +vrm RW Voltage regulator module version + number. + +in[0-6]_input RO Measured voltage in millivolts. +in[0-6]_min RW Low limit for voltage input. +in[0-6]_max RW High limit for voltage input. +in[0-6]_alarm RO Voltage input alarm. Returns 1 if + voltage input is or went outside the + associated min-max range, 0 otherwise. + +temp[1-3]_input RO Measured temperature in millidegree + Celsius. +temp[1-3]_min RW Low limit for temp input. +temp[1-3]_max RW High limit for temp input. +temp[1-3]_offset RW Offset for temp input. This value will + be added by the chip to the measured + temperature. +temp[1-3]_alarm RO Alarm for temp input. Returns 1 if temp + input is or went outside the associated + min-max range, 0 otherwise. +temp[1-3]_fault RO Temp input fault. Returns 1 if the chip + detects a faulty thermal diode or an + unconnected temp input, 0 otherwise. + +zone[1-3]_auto_channels_temp RO Temperature zone to temperature input + mapping. This attribute is a bitfield + and supports the following values: + 1: temp1 + 2: temp2 + 4: temp3 +zone[1-3]_auto_point1_temp_hyst RW Auto PWM temp point1 hysteresis. The + output of the corresponding PWM is set + to the pwm_auto_min value if the temp + falls below the auto_point1_temp_hyst + value. +zone[1-3]_auto_point[1-3]_temp RW Auto PWM temp points. Auto_point1 is + the low-speed temp, auto_point2 is the + full-speed temp, and auto_point3 is the + temp at which all PWM outputs are set + to full-speed (100% duty-cycle). + +fan[1-6]_input RO Measured fan speed in RPM. +fan[1-6]_min RW Low limit for fan input. +fan[1-6]_alarm RO Alarm for fan input. Returns 1 if fan + input is or went below the associated + min value, 0 otherwise. +fan[1-4]_type RW Type of attached fan. Expressed in + number of pulses per revolution that + the fan generates. Supported values are + 1, 2, and 4. +fan[5-6]_max RW Max attainable RPM at 100% duty-cycle. + Required for chip to adjust the + sampling rate accordingly. + +pmw[1-3,5-6] RO/RW Duty-cycle of PWM output. Supported + values are 0-255 (0%-100%). Only + writeable if the associated PWM is in + manual mode. +pwm[1-3]_enable RW Enable of PWM outputs 1-3. Supported + values are: + 0: turned off (output @ 100%) + 1: manual mode + 2: automatic mode +pwm[5-6]_enable RO Enable of PWM outputs 5-6. Always + returns 1 since these 2 outputs are + hard-wired to manual mode. +pmw[1-3,5-6]_freq RW Frequency of PWM output. Supported + values are in the range 11Hz-30000Hz + (default is 25000Hz). +pmw[1-3]_ramp_rate RW Ramp rate of PWM output. Determines how + fast the PWM duty-cycle will change + when the PWM is in automatic mode. + Expressed in ms per PWM step. Supported + values are in the range 0ms-206ms + (default is 0, which means the duty- + cycle changes instantly). +pwm[1-3]_auto_channels_zone RW PWM output to temperature zone mapping. + This attribute is a bitfield and + supports the following values: + 1: zone1 + 2: zone2 + 4: zone3 + 6: highest of zone[2-3] + 7: highest of zone[1-3] +pwm[1-3]_auto_pwm_min RW Auto PWM min pwm. Minimum PWM duty- + cycle. Supported values are 0 or + auto_point1_pwm. +pwm[1-3]_auto_point1_pwm RW Auto PWM pwm point. Auto_point1 is the + low-speed duty-cycle. +pwm[1-3]_auto_point2_pwm RO Auto PWM pwm point. Auto_point2 is the + full-speed duty-cycle which is hard- + wired to 255 (100% duty-cycle). diff --git a/Documentation/hwmon/f71805f b/Documentation/hwmon/f71805f index bfd0f154959..94e0d2cbd3d 100644 --- a/Documentation/hwmon/f71805f +++ b/Documentation/hwmon/f71805f @@ -5,11 +5,11 @@ Supported chips: * Fintek F71805F/FG Prefix: 'f71805f' Addresses scanned: none, address read from Super I/O config space - Datasheet: Provided by Fintek on request + Datasheet: Available from the Fintek website * Fintek F71872F/FG Prefix: 'f71872f' Addresses scanned: none, address read from Super I/O config space - Datasheet: Provided by Fintek on request + Datasheet: Available from the Fintek website Author: Jean Delvare <khali@linux-fr.org> @@ -128,7 +128,9 @@ it. When the PWM method is used, you can select the operating frequency, from 187.5 kHz (default) to 31 Hz. The best frequency depends on the fan model. As a rule of thumb, lower frequencies seem to give better -control, but may generate annoying high-pitch noise. Fintek recommends +control, but may generate annoying high-pitch noise. So a frequency just +above the audible range, such as 25 kHz, may be a good choice; if this +doesn't give you good linear control, try reducing it. Fintek recommends not going below 1 kHz, as the fan tachometers get confused by lower frequencies as well. @@ -136,16 +138,23 @@ When the DC method is used, Fintek recommends not going below 5 V, which corresponds to a pwm value of 106 for the driver. The driver doesn't enforce this limit though. -Three different fan control modes are supported: +Three different fan control modes are supported; the mode number is written +to the pwm<n>_enable file. -* Manual mode - You ask for a specific PWM duty cycle or DC voltage. +* 1: Manual mode + You ask for a specific PWM duty cycle or DC voltage by writing to the + pwm<n> file. -* Fan speed mode - You ask for a specific fan speed. This mode assumes that pwm1 - corresponds to fan1, pwm2 to fan2 and pwm3 to fan3. +* 2: Temperature mode + You define 3 temperature/fan speed trip points using the + pwm<n>_auto_point<m>_temp and _fan files. These define a staircase + relationship between temperature and fan speed with two additional points + interpolated between the values that you define. When the temperature + is below auto_point1_temp the fan is switched off. -* Temperature mode - You define 3 temperature/fan speed trip points, and the fan speed is - adjusted depending on the measured temperature, using interpolation. - This mode is not yet supported by the driver. +* 3: Fan speed mode + You ask for a specific fan speed by writing to the fan<n>_target file. + +Both of the automatic modes require that pwm1 corresponds to fan1, pwm2 to +fan2 and pwm3 to fan3. Temperature mode also requires that temp1 corresponds +to pwm1 and fan1, etc. diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index c0528d6f9ac..81ecc7e41c5 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 @@ -12,11 +12,12 @@ Supported chips: Addresses scanned: from Super I/O config space (8 I/O ports) Datasheet: Publicly available at the ITE website http://www.ite.com.tw/ - * IT8716F + * IT8716F/IT8726F Prefix: 'it8716' Addresses scanned: from Super I/O config space (8 I/O ports) Datasheet: Publicly available at the ITE website http://www.ite.com.tw/product_info/file/pc/IT8716F_V0.3.ZIP + http://www.ite.com.tw/product_info/file/pc/IT8726F_V0.3.pdf * IT8718F Prefix: 'it8718' Addresses scanned: from Super I/O config space (8 I/O ports) @@ -68,7 +69,7 @@ Description ----------- This driver implements support for the IT8705F, IT8712F, IT8716F, -IT8718F and SiS950 chips. +IT8718F, IT8726F and SiS950 chips. These chips are 'Super I/O chips', supporting floppy disks, infrared ports, joysticks and other miscellaneous stuff. For hardware monitoring, they @@ -97,6 +98,10 @@ clock divider mess) but not compatible with the older chips and revisions. For now, the driver only uses the 16-bit mode on the IT8716F and IT8718F. +The IT8726F is just bit enhanced IT8716F with additional hardware +for AMD power sequencing. Therefore the chip will appear as IT8716F +to userspace applications. + Temperatures are measured in degrees Celsius. An alarm is triggered once when the Overtemperature Shutdown limit is crossed. diff --git a/Documentation/hwmon/lm90 b/Documentation/hwmon/lm90 index 438cb24cee5..aa4a0ec2008 100644 --- a/Documentation/hwmon/lm90 +++ b/Documentation/hwmon/lm90 @@ -48,6 +48,18 @@ Supported chips: Addresses scanned: I2C 0x4c, 0x4d (unsupported 0x4e) Datasheet: Publicly available at the Maxim website http://www.maxim-ic.com/quick_view2.cfm/qv_pk/2578 + * Maxim MAX6680 + Prefix: 'max6680' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 + * Maxim MAX6681 + Prefix: 'max6680' + Addresses scanned: I2C 0x18, 0x19, 0x1a, 0x29, 0x2a, 0x2b, + 0x4c, 0x4d and 0x4e + Datasheet: Publicly available at the Maxim website + http://www.maxim-ic.com/quick_view2.cfm/qv_pk/3370 Author: Jean Delvare <khali@linux-fr.org> @@ -59,11 +71,15 @@ Description The LM90 is a digital temperature sensor. It senses its own temperature as well as the temperature of up to one external diode. It is compatible with many other devices such as the LM86, the LM89, the LM99, the ADM1032, -the MAX6657, MAX6658 and the MAX6659 all of which are supported by this driver. -Note that there is no easy way to differentiate between the last three -variants. The extra address and features of the MAX6659 are not supported by -this driver. Additionally, the ADT7461 is supported if found in ADM1032 -compatibility mode. +the MAX6657, MAX6658, MAX6659, MAX6680 and the MAX6681 all of which are +supported by this driver. + +Note that there is no easy way to differentiate between the MAX6657, +MAX6658 and MAX6659 variants. The extra address and features of the +MAX6659 are not supported by this driver. The MAX6680 and MAX6681 only +differ in their pinout, therefore they obviously can't (and don't need to) +be distinguished. Additionally, the ADT7461 is supported if found in +ADM1032 compatibility mode. The specificity of this family of chipsets over the ADM1021/LM84 family is that it features critical limits with hysteresis, and an @@ -93,18 +109,22 @@ ADM1032: * ALERT is triggered by open remote sensor. * SMBus PEC support for Write Byte and Receive Byte transactions. -ADT7461 +ADT7461: * Extended temperature range (breaks compatibility) * Lower resolution for remote temperature MAX6657 and MAX6658: * Remote sensor type selection -MAX6659 +MAX6659: * Selectable address * Second critical temperature limit * Remote sensor type selection +MAX6680 and MAX6681: + * Selectable address + * Remote sensor type selection + All temperature values are given in degrees Celsius. Resolution is 1.0 degree for the local temperature, 0.125 degree for the remote temperature. @@ -141,7 +161,7 @@ SMBus Read Byte, and PEC will work properly. Additionally, the ADM1032 doesn't support SMBus Send Byte with PEC. Instead, it will try to write the PEC value to the register (because the SMBus Send Byte transaction with PEC is similar to a Write Byte transaction -without PEC), which is not what we want. Thus, PEC is explicitely disabled +without PEC), which is not what we want. Thus, PEC is explicitly disabled on SMBus Send Byte transactions in the lm90 driver. PEC on byte data transactions represents a significant increase in bandwidth diff --git a/Documentation/hwmon/lm93 b/Documentation/hwmon/lm93 new file mode 100644 index 00000000000..4e4a1dc1d2d --- /dev/null +++ b/Documentation/hwmon/lm93 @@ -0,0 +1,412 @@ +Kernel driver lm93 +================== + +Supported chips: + * National Semiconductor LM93 + Prefix 'lm93' + Addresses scanned: I2C 0x2c-0x2e + Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf + +Author: + Mark M. Hoffman <mhoffman@lightlink.com> + Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com> + Adapted to 2.6.20 by Carsten Emde <ce@osadl.org> + Modified for mainline integration by Hans J. Koch <hjk@linutronix.de> + +Module Parameters +----------------- + +(specific to LM93) +* init: integer + Set to non-zero to force some initializations (default is 0). +* disable_block: integer + A "0" allows SMBus block data transactions if the host supports them. A "1" + disables SMBus block data transactions. The default is 0. +* vccp_limit_type: integer array (2) + Configures in7 and in8 limit type, where 0 means absolute and non-zero + means relative. "Relative" here refers to "Dynamic Vccp Monitoring using + VID" from the datasheet. It greatly simplifies the interface to allow + only one set of limits (absolute or relative) to be in operation at a + time (even though the hardware is capable of enabling both). There's + not a compelling use case for enabling both at once, anyway. The default + is "0,0". +* vid_agtl: integer + A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max. + A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max. + (The latter setting is referred to as AGTL+ Compatible in the datasheet.) + I.e. this parameter controls the VID pin input thresholds; if your VID + inputs are not working, try changing this. The default value is "0". + +(common among sensor drivers) +* force: short array (min = 1, max = 48) + List of adapter,address pairs to assume to be present. Autodetection + of the target device will still be attempted. Use one of the more + specific force directives below if this doesn't detect the device. +* force_lm93: short array (min = 1, max = 48) + List of adapter,address pairs which are unquestionably assumed to contain + a 'lm93' chip +* ignore: short array (min = 1, max = 48) + List of adapter,address pairs not to scan +* ignore_range: short array (min = 1, max = 48) + List of adapter,start-addr,end-addr triples not to scan +* probe: short array (min = 1, max = 48) + List of adapter,address pairs to scan additionally +* probe_range: short array (min = 1, max = 48) + List of adapter,start-addr,end-addr triples to scan additionally + + +Hardware Description +-------------------- + +(from the datasheet) + +The LM93, hardware monitor, has a two wire digital interface compatible with +SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote +diode connected transistors as well as its own die and 16 power supply +voltages. To set fan speed, the LM93 has two PWM outputs that are each +controlled by up to four temperature zones. The fancontrol algorithm is lookup +table based. The LM93 includes a digital filter that can be invoked to smooth +temperature readings for better control of fan speed. The LM93 has four +tachometer inputs to measure fan speed. Limit and status registers for all +measured values are included. The LM93 builds upon the functionality of +previous motherboard management ASICs and uses some of the LM85 s features +(i.e. smart tachometer mode). It also adds measurement and control support +for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual +processor Xeon class motherboard with a minimum of external components. + + +Driver Description +------------------ + +This driver implements support for the National Semiconductor LM93. + + +User Interface +-------------- + +#PROCHOT: + +The LM93 can monitor two #PROCHOT signals. The results are found in the +sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max, +and prochot2_max. prochot1_max and prochot2_max contain the user limits +for #PROCHOT1 and #PROCHOT2, respectively. prochot1 and prochot2 contain +the current readings for the most recent complete time interval. The +value of prochot1_avg and prochot2_avg is something like a 2 period +exponential moving average (but not quite - check the datasheet). Note +that this third value is calculated by the chip itself. All values range +from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%. + +The monitoring intervals for the two #PROCHOT signals is also configurable. +These intervals can be found in the sysfs files prochot1_interval and +prochot2_interval. The values in these files specify the intervals for +#P1_PROCHOT and #P2_PROCHOT, respectively. Selecting a value not in this +list will cause the driver to use the next largest interval. The available +intervals are: + +#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372 + +It is possible to configure the LM93 to logically short the two #PROCHOT +signals. I.e. when #P1_PROCHOT is asserted, the LM93 will automatically +assert #P2_PROCHOT, and vice-versa. This mode is enabled by writing a +non-zero integer to the sysfs file prochot_short. + +The LM93 can also override the #PROCHOT pins by driving a PWM signal onto +one or both of them. When overridden, the signal has a period of 3.56 mS, +a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and +a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle). + +The sysfs files prochot1_override and prochot2_override contain boolean +intgers which enable or disable the override function for #P1_PROCHOT and +#P2_PROCHOT, respectively. The sysfs file prochot_override_duty_cycle +contains a value controlling the duty cycle for the PWM signal used when +the override function is enabled. This value ranges from 0 to 15, with 0 +indicating minimum duty cycle and 15 indicating maximum. + +#VRD_HOT: + +The LM93 can monitor two #VRD_HOT signals. The results are found in the +sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for +which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These +files are read-only. + +Smart Tach Mode: + +(from the datasheet) + + If a fan is driven using a low-side drive PWM, the tachometer + output of the fan is corrupted. The LM93 includes smart tachometer + circuitry that allows an accurate tachometer reading to be + achieved despite the signal corruption. In smart tach mode all + four signals are measured within 4 seconds. + +Smart tach mode is enabled by the driver by writing 1 or 2 (associating the +the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach. A zero +will disable the function for that fan. Note that Smart tach mode cannot be +enabled if the PWM output frequency is 22500 Hz (see below). + +Manual PWM: + +The LM93 has a fixed or override mode for the two PWM outputs (although, there +are still some conditions that will override even this mode - see section +15.10.6 of the datasheet for details.) The sysfs files pwm1_override +and pwm2_override are used to enable this mode; each is a boolean integer +where 0 disables and 1 enables the manual control mode. The sysfs files pwm1 +and pwm2 are used to set the manual duty cycle; each is an integer (0-255) +where 0 is 0% duty cycle, and 255 is 100%. Note that the duty cycle values +are constrained by the hardware. Selecting a value which is not available +will cause the driver to use the next largest value. Also note: when manual +PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty +cycle chosen by the h/w. + +PWM Output Frequency: + +The LM93 supports several different frequencies for the PWM output channels. +The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The +frequency values are constrained by the hardware. Selecting a value which is +not available will cause the driver to use the next largest value. Also note +that this parameter has implications for the Smart Tach Mode (see above). + +PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 (h/w default) + +Automatic PWM: + +The LM93 is capable of complex automatic fan control, with many different +points of configuration. To start, each PWM output can be bound to any +combination of eight control sources. The final PWM is the largest of all +individual control sources to which the PWM output is bound. + +The eight control sources are: temp1-temp4 (aka "zones" in the datasheet), +#PROCHOT 1 & 2, and #VRDHOT 1 & 2. The bindings are expressed as a bitmask +in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and + a "0" disables it. The h/w default is 0x0f (all temperatures bound). + + 0x01 - Temp 1 + 0x02 - Temp 2 + 0x04 - Temp 3 + 0x08 - Temp 4 + 0x10 - #PROCHOT 1 + 0x20 - #PROCHOT 2 + 0x40 - #VRDHOT 1 + 0x80 - #VRDHOT 2 + +The function y = f(x) takes a source temperature x to a PWM output y. This +function of the LM93 is derived from a base temperature and a table of 12 +temperature offsets. The base temperature is expressed in degrees C in the +sysfs files temp<n>_auto_base. The offsets are expressed in cumulative +degrees C, with the value of offset <i> for temperature value <n> being +contained in the file temp<n>_auto_offset<i>. E.g. if the base temperature +is 40C: + + offset # temp<n>_auto_offset<i> range pwm + 1 0 - 25.00% + 2 0 - 28.57% + 3 1 40C - 41C 32.14% + 4 1 41C - 42C 35.71% + 5 2 42C - 44C 39.29% + 6 2 44C - 46C 42.86% + 7 2 48C - 50C 46.43% + 8 2 50C - 52C 50.00% + 9 2 52C - 54C 53.57% + 10 2 54C - 56C 57.14% + 11 2 56C - 58C 71.43% + 12 2 58C - 60C 85.71% + > 60C 100.00% + +Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments. + +There is an independent base temperature for each temperature channel. Note, +however, there are only two tables of offsets: one each for temp[12] and +temp[34]. Therefore, any change to e.g. temp1_auto_offset<i> will also +affect temp2_auto_offset<i>. + +The LM93 can also apply hysteresis to the offset table, to prevent unwanted +oscillation between two steps in the offsets table. These values are found in +the sysfs files temp<n>_auto_offset_hyst. The value in this file has the +same representation as in temp<n>_auto_offset<i>. + +If a temperature reading falls below the base value for that channel, the LM93 +will use the minimum PWM value. These values are found in the sysfs files +temp<n>_auto_pwm_min. Note, there are only two minimums: one each for temp[12] +and temp[34]. Therefore, any change to e.g. temp1_auto_pwm_min will also +affect temp2_auto_pwm_min. + +PWM Spin-Up Cycle: + +A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to +some value > 0%. The LM93 supports a minimum duty cycle during spin-up. These +values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this +file has the same representation as other PWM duty cycle values. The +duration of the spin-up cycle is also configurable. These values are found in +the sysfs files pwm<n>_auto_spinup_time. The value in this file is +the spin-up time in seconds. The available spin-up times are constrained by +the hardware. Selecting a value which is not available will cause the driver +to use the next largest value. + +Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0, + 2.0, 4.0 + +#PROCHOT and #VRDHOT PWM Ramping: + +If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output +channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete +steps. The duration of each step is configurable. There are two files, with +one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp. +The available ramp times are constrained by the hardware. Selecting a value +which is not available will cause the driver to use the next largest value. + +Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals + +Fan Boost: + +For each temperature channel, there is a boost temperature: if the channel +exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%. +This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost. +There is also a hysteresis temperature for this function: after the boost +limit is reached, the temperature channel must drop below this value before +the boost function is disabled. This temperature is also expressed in degrees +C in the sysfs files temp<n>_auto_boost_hyst. + +GPIO Pins: + +The LM93 can monitor the logic level of four dedicated GPIO pins as well as the +four tach input pins. GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively. +All eight GPIOs are read by reading the bitmask in the sysfs file gpio. The +LSB is GPIO0, and the MSB is GPIO7. + + +LM93 Unique sysfs Files +----------------------- + + file description + ------------------------------------------------------------- + + prochot<n> current #PROCHOT % + + prochot<n>_avg moving average #PROCHOT % + + prochot<n>_max limit #PROCHOT % + + prochot_short enable or disable logical #PROCHOT pin short + + prochot<n>_override force #PROCHOT assertion as PWM + + prochot_override_duty_cycle + duty cycle for the PWM signal used when + #PROCHOT is overridden + + prochot<n>_interval #PROCHOT PWM sampling interval + + vrdhot<n> 0 means negated, 1 means asserted + + fan<n>_smart_tach enable or disable smart tach mode + + pwm<n>_auto_channels select control sources for PWM outputs + + pwm<n>_auto_spinup_min minimum duty cycle during spin-up + + pwm<n>_auto_spinup_time duration of spin-up + + pwm_auto_prochot_ramp ramp time per step when #PROCHOT asserted + + pwm_auto_vrdhot_ramp ramp time per step when #VRDHOT asserted + + temp<n>_auto_base temperature channel base + + temp<n>_auto_offset[1-12] + temperature channel offsets + + temp<n>_auto_offset_hyst + temperature channel offset hysteresis + + temp<n>_auto_boost temperature channel boost (PWMs to 100%) limit + + temp<n>_auto_boost_hyst temperature channel boost hysteresis + + gpio input state of 8 GPIO pins; read-only + + +Sample Configuration File +------------------------- + +Here is a sample LM93 chip config for sensors.conf: + +---------- cut here ---------- +chip "lm93-*" + +# VOLTAGE INPUTS + + # labels and scaling based on datasheet recommendations + label in1 "+12V1" + compute in1 @ * 12.945, @ / 12.945 + set in1_min 12 * 0.90 + set in1_max 12 * 1.10 + + label in2 "+12V2" + compute in2 @ * 12.945, @ / 12.945 + set in2_min 12 * 0.90 + set in2_max 12 * 1.10 + + label in3 "+12V3" + compute in3 @ * 12.945, @ / 12.945 + set in3_min 12 * 0.90 + set in3_max 12 * 1.10 + + label in4 "FSB_Vtt" + + label in5 "3GIO" + + label in6 "ICH_Core" + + label in7 "Vccp1" + + label in8 "Vccp2" + + label in9 "+3.3V" + set in9_min 3.3 * 0.90 + set in9_max 3.3 * 1.10 + + label in10 "+5V" + set in10_min 5.0 * 0.90 + set in10_max 5.0 * 1.10 + + label in11 "SCSI_Core" + + label in12 "Mem_Core" + + label in13 "Mem_Vtt" + + label in14 "Gbit_Core" + + # Assuming R1/R2 = 4.1143, and 3.3V reference + # -12V = (4.1143 + 1) * (@ - 3.3) + 3.3 + label in15 "-12V" + compute in15 @ * 5.1143 - 13.57719, (@ + 13.57719) / 5.1143 + set in15_min -12 * 0.90 + set in15_max -12 * 1.10 + + label in16 "+3.3VSB" + set in16_min 3.3 * 0.90 + set in16_max 3.3 * 1.10 + +# TEMPERATURE INPUTS + + label temp1 "CPU1" + label temp2 "CPU2" + label temp3 "LM93" + +# TACHOMETER INPUTS + + label fan1 "Fan1" + set fan1_min 3000 + label fan2 "Fan2" + set fan2_min 3000 + label fan3 "Fan3" + set fan3_min 3000 + label fan4 "Fan4" + set fan4_min 3000 + +# PWM OUTPUTS + + label pwm1 "CPU1" + label pwm2 "CPU2" + diff --git a/Documentation/hwmon/smsc47b397 b/Documentation/hwmon/smsc47b397 index 20682f15ae4..3a43b694892 100644 --- a/Documentation/hwmon/smsc47b397 +++ b/Documentation/hwmon/smsc47b397 @@ -4,6 +4,7 @@ Kernel driver smsc47b397 Supported chips: * SMSC LPC47B397-NC * SMSC SCH5307-NS + * SMSC SCH5317 Prefix: 'smsc47b397' Addresses scanned: none, address read from Super I/O config space Datasheet: In this file @@ -18,8 +19,8 @@ The following specification describes the SMSC LPC47B397-NC[1] sensor chip provided by Craig Kelly (In-Store Broadcast Network) and edited/corrected by Mark M. Hoffman <mhoffman@lightlink.com>. -[1] And SMSC SCH5307-NS, which has a different device ID but is otherwise -compatible. +[1] And SMSC SCH5307-NS and SCH5317, which have different device IDs but are +otherwise compatible. * * * * * @@ -131,7 +132,7 @@ OUT DX,AL The registers of interest for identifying the SIO on the dc7100 are Device ID (0x20) and Device Rev (0x21). -The Device ID will read 0x6F (for SCH5307-NS, 0x81) +The Device ID will read 0x6F (0x81 for SCH5307-NS, and 0x85 for SCH5317) The Device Rev currently reads 0x01 Obtaining the HWM Base Address. diff --git a/Documentation/hwmon/sysfs-interface b/Documentation/hwmon/sysfs-interface index a9a18ad0d17..b3a9e1b9dbd 100644 --- a/Documentation/hwmon/sysfs-interface +++ b/Documentation/hwmon/sysfs-interface @@ -172,11 +172,10 @@ pwm[1-*] Pulse width modulation fan control. 255 is max or 100%. pwm[1-*]_enable - Switch PWM on and off. - Not always present even if pwmN is. - 0: turn off - 1: turn on in manual mode - 2+: turn on in automatic mode + Fan speed control method: + 0: no fan speed control (i.e. fan at full speed) + 1: manual fan speed control enabled (using pwm[1-*]) + 2+: automatic fan speed control enabled Check individual chip documentation files for automatic mode details. RW @@ -343,9 +342,9 @@ to notify open diodes, unconnected fans etc. where the hardware supports it. When this boolean has value 1, the measurement for that channel should not be trusted. -in[0-*]_input_fault -fan[1-*]_input_fault -temp[1-*]_input_fault +in[0-*]_fault +fan[1-*]_fault +temp[1-*]_fault Input fault condition 0: no fault occured 1: fault condition diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf index 030fac6cec7..ccc2bcb6106 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf @@ -22,9 +22,9 @@ This driver implements support for the Winbond W83627EHF, W83627EHG, and W83627DHG super I/O chips. We will refer to them collectively as Winbond chips. The chips implement three temperature sensors, five fan rotation -speed sensors, ten analog voltage sensors (only nine for the 627DHG), alarms -with beep warnings (control unimplemented), and some automatic fan regulation -strategies (plus manual fan control mode). +speed sensors, ten analog voltage sensors (only nine for the 627DHG), one +VID (6 pins), alarms with beep warnings (control unimplemented), and +some automatic fan regulation strategies (plus manual fan control mode). Temperatures are measured in degrees Celsius and measurement resolution is 1 degC for temp1 and 0.5 degC for temp2 and temp3. An alarm is triggered when diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO new file mode 100644 index 00000000000..b2446a09087 --- /dev/null +++ b/Documentation/ja_JP/HOWTO @@ -0,0 +1,650 @@ +NOTE: +This is Japanese translated version of "Documentation/HOWTO". +This one is maintained by Tsugikazu Shibata <tshibata@ab.jp.nec.com> +and JF Project team <www.linux.or.jp/JF>. +If you find difference with original file or problem in translation, +please contact maintainer of this file or JF project. + +Please also note that purpose of this file is easier to read for non +English natives and not to be intended to fork. So, if you have any +comments or updates of this file, please try to update Original(English) +file at first. + +Last Updated: 2007/06/04 +================================== +これは、 +linux-2.6.21/Documentation/HOWTO +の和訳です。 + +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日： 2007/06/04 +翻訳者： Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> +校正者： 松倉さん <nbh--mats at nifty dot com> + 小林 雅典さん (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> + 武井伸光さん、<takei at webmasters dot gr dot jp> + かねこさん (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> + 野口さん (Kenji Noguchi) <tokyo246 at gmail dot com> + 河内さん (Takayoshi Kochi) <t-kochi at bq dot jp dot nec dot com> + 岩本さん (iwamoto) <iwamoto.kn at ncos dot nec dot co dot jp> +================================== + +Linux カーネル開発のやり方 +------------------------------- + +これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した +ドキュメントです。ここには Linux カーネル開発者になるための方法と +Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて +います。カーネルプログラミングに関する技術的な項目に関することは何も含 +めないようにしていますが、カーネル開発者となるための正しい方向に向かう +手助けになります。 + +もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン +トの最後にリストしたメンテナーにパッチを送ってください。 + +はじめに +--------- + +あなたは Linux カーネルの開発者になる方法を学びたいのでしょうか？ そ +れともあなたは上司から「このデバイスの Linux ドライバを書くように」と +言われているのでしょうか？ +この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働 +くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。 +また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も +説明しようと試みています。 + +カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている +以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー +ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの +でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり +ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの +ではありませんが、少なくともリファレンスとしてはいい本です。 + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + -『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + - 『新・詳説 C 言語 H&S リファレンス』 + (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク] + +カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル +は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って +います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー +スタンディング環境です。そのため、C の標準で使えないものもあります。任 +意の long long の除算や浮動小数点は使えません。 +ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう +なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ +レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を +みてください。 + +あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ +とに留意してください。そのコミュニティは、コーディング、スタイル、 +開発手順について高度な標準を持つ、多様な人の集まりです。 +地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと +をベースにしながら、これらの標準は長い時間をかけて築かれてきました。 +これらはきちんと文書化されていますから、事前にこれらの標準についてでき +るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ +せてくれると思わないでください。 + +法的問題 +------------ + +Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま +す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在 +する、COPYING のファイルをみてください。もしライセンスについてさらに質 +問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ +法律家に相談してください。メーリングリストの人達は法律家ではなく、法的 +問題については彼らの声明はあてにするべきではありません。 + +GPL に関する共通の質問や回答については、以下を参照してください。 + http://www.gnu.org/licenses/gpl-faq.html + +ドキュメント +------------ + +Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ +らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。 +新しい機能がカーネルに追加される場合、その機能の使い方について説明した +新しいドキュメントファイルも追加することを勧めます。 +カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの +変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 +をマニュアルページのメンテナ mtk-manpages@gmx.net に送ることを勧めます。 + +以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で +す- + + README + このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注 + configure )し、生成(訳注 build )するために必要なことは何かが書かれ + ています。カーネルに関して初めての人はここからスタートするとよいで + しょう。 + + Documentation/Changes + このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最 + 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい + ます。 + + Documentation/CodingStyle + これは Linux カーネルのコーディングスタイルと背景にある理由を記述 + しています。全ての新しいコードはこのドキュメントにあるガイドライン + に従っていることを期待されています。大部分のメンテナーはこれらのルー + ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード + だけをレビューします。 + + Documentation/SubmittingPatches + Documentation/SubmittingDrivers + これらのファイルには、どうやってうまくパッチを作って投稿するかに + ついて非常に詳しく書かれており、以下を含みます(これだけに限らない + けれども) + - Email に含むこと + - Email の形式 + - だれに送るか + これらのルールに従えばうまくいくことを保証することではありません + が (すべてのパッチは内容とスタイルについて精査を受けるので)、 + ルールに従わなければ間違いなくうまくいかないでしょう。 + この他にパッチを作る方法についてのよくできた記述は- + + "The Perfect Patch" + http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + Documentation/stable_api_nonsense.txt + このファイルはカーネルの中に不変のAPIを持たないことにした意識的な + 決断の背景にある理由について書かれています。以下のようなことを含 + んでいます- + - サブシステムとの間に層を作ること(コンパチビリティのため?) + - オペレーティングシステム間のドライバの移植性 + - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更 + を妨げる) + このドキュメントは Linux 開発の思想を理解するのに非常に重要です。 + そして、他のOSでの開発者が Linux に移る時にとても重要です。 + + Documentation/SecurityBugs + もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ + のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を + 支援してください。 + + Documentation/ManagementStyle + このドキュメントは Linux カーネルのメンテナー達がどう行動するか、 + 彼らの手法の背景にある共有されている精神について記述しています。こ + れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも） + 重要です。なぜならこのドキュメントは、カーネルメンテナー達の独特な + 行動についての多くの誤解や混乱を解消するからです。 + + Documentation/stable_kernel_rules.txt + このファイルはどのように stable カーネルのリリースが行われるかのルー + ルが記述されています。そしてこれらのリリースの中のどこかで変更を取 + り入れてもらいたい場合に何をすればいいかが示されています。 + + Documentation/kernel-docs.txt + カーネル開発に付随する外部ドキュメントのリストです。もしあなたが + 探しているものがカーネル内のドキュメントでみつからなかった場合、 + このリストをあたってみてください。 + + Documentation/applying-patches.txt + パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに + 適用するのかについて正確に記述した良い入門書です。 + +カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自 +身でもっています。これにはカーネル内 API のすべての記述や、どう正しく +ロックをかけるかの規則が含まれます。このドキュメントは +Documentation/DocBook/ ディレクトリに作られ、以下のように + make pdfdocs + make psdocs + make htmldocs + make mandocs +コマンドを実行するとメインカーネルのソースディレクトリから +それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。 + +カーネル開発者になるには +--------------------------- + +もしあなたが、Linux カーネル開発について何も知らないならば、 +KernelNewbies プロジェクトを見るべきです + http://kernelnewbies.org + +このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関 +するほとんどどんな種類の質問もできます (既に回答されているようなことを +聞く前にまずはアーカイブを調べてください)。 +またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux +カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ +ります。 + +web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ +リーにあるもの無いものの両方)の基本的な管理情報があります。 +ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接 +的な基本情報も記述されています。 + +あなたがどこからスタートしてよいかわからないが、Linux カーネル開発コミュ +ニティに参加して何かすることをさがしている場合には、Linux kernel +Janitor's プロジェクトにいけばよいでしょう - + http://janitor.kernelnewbies.org/ +ここはそのようなスタートをするのにうってつけの場所です。ここには、 +Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな +らない、単純な問題のリストが記述されています。このプロジェクトに関わる +開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入 +れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ +ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。 + +もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入 +れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル +メンターズプロジェクトはそのような皆さんを助けるためにできました。 +ここにはメーリングリストがあり、以下から参照できます + http://selenic.com/mailman/listinfo/kernel-mentors + +実際に Linux カーネルのコードについて修正を加える前に、どうやってその +コードが動作するのかを理解することが必要です。そのためには、特別なツー +ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど +のトリッキーな部分は十分にコメントしてありますから)。そういうツールで +特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、 +自己参照方式で、索引がついた web 形式で、ソースコードを参照することが +できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり +ます- + http://sosdg.org/~coywolf/lxr/ + +開発プロセス +----------------------- + +Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン +チ」と多数のサブシステム毎のカーネルブランチから構成されます。 +これらのブランチとは- + - メインの 2.6.x カーネルツリー + - 2.6.x.y -stable カーネルツリー + - 2.6.x -git カーネルパッチ + - 2.6.x -mm カーネルパッチ + - サブシステム毎のカーネルツリーとパッチ + +2.6.x カーネルツリー +----------------- + +2.6.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org +の pub/linux/kernel/v2.6/ ディレクトリに存在します。この開発プロセスは +以下のとおり- + + - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、 + この期間中に、メンテナー達は Linus に大きな差分を送ることができま + す。このような差分は通常 -mm カーネルに数週間含まれてきたパッチで + す。 大きな変更は git(カーネルのソース管理ツール、詳細は + http://git.or.cz/ 参照) を使って送るのが好ましいやり方ですが、パッ + チファイルの形式のまま送るのでも十分です。 + + - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定 + 性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと + はできません。新しいドライバ(もしくはファイルシステム)のパッチは + -rc1 の後で受け付けられることもあることを覚えておいてください。な + ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え + ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、 + Linus へパッチを送付するのに git を使うこともできますが、パッチは + レビューのために、パブリックなメーリングリストへも同時に送る必要が + あります。 + + - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分 + に安定した状態にあると判断したときにリリースされます。目標は毎週新 + しい -rc カーネルをリリースすることです。 + + - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま + す。このプロセスはだいたい 6週間継続します。 + +Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ +て書いたことをここで言っておくことは価値があります- + 「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現 + 実に認識されたバグの状況によりリリースされるのであり、前もって決めら + れた計画によってリリースされるものではないからです。」 + +2.6.x.y -stable カーネルツリー +--------------------------- + +バージョンに4つ目の数字がついたカーネルは -stable カーネルです。これに +は、2.6.x カーネルで見つかったセキュリティ問題や重大な後戻りに対する比 +較的小さい重要な修正が含まれます。 + +これは、開発/実験的バージョンのテストに協力することに興味が無く、 +最新の安定したカーネルを使いたいユーザに推奨するブランチです。 + +もし、2.6.x.y カーネルが存在しない場合には、番号が一番大きい 2.6.x +が最新の安定版カーネルです。 + +2.6.x.y は "stable" チーム <stable@kernel.org> でメンテされており、だ +いたい隔週でリリースされています。 + +カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ +イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ +リースプロセスがどう動くかが記述されています。 + +2.6.x -git パッチ +------------------ + +git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ +ショットがあります。(だから -git という名前がついています)。これらのパッ +チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ +れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的 +に生成されるので、より実験的です。 + +2.6.x -mm カーネルパッチ +------------------------ + +Andrew Morton によってリリースされる実験的なカーネルパッチ群です。 +Andrew は個別のサブシステムカーネルツリーとパッチを全て集めてきて +linux-kernel メーリングリストで収集された多数のパッチと同時に一つにま +とめます。 +このツリーは新機能とパッチが検証される場となります。ある期間の間パッチ +が -mm に入って価値を証明されたら、Andrew やサブシステムメンテナが、メ +インラインへ入れるように Linus にプッシュします。 + +メインカーネルツリーに含めるために Linus に送る前に、すべての新しいパッ +チが -mm ツリーでテストされることが強く推奨されます。 + +これらのカーネルは安定して動作すべきシステムとして使うのには適切ではあ +りませんし、カーネルブランチの中でももっとも動作にリスクが高いものです。 + +もしあなたが、カーネル開発プロセスの支援をしたいと思っているのであれば、 +どうぞこれらのカーネルリリースをテストに使ってみて、そしてもし問題があ +れば、またもし全てが正しく動作したとしても、linux-kernel メーリングリ +ストにフィードバックを提供してください。 + +すべての他の実験的パッチに加えて、これらのカーネルは通常リリース時点で +メインラインの -git カーネルに含まれる全ての変更も含んでいます。 + +-mm カーネルは決まったスケジュールではリリースされません、しかし通常幾 +つかの -mm カーネル (1 から 3 が普通）が各-rc カーネルの間にリリースさ +れます。 + +サブシステム毎のカーネルツリーとパッチ +------------------------------------------- + +カーネルの様々な領域で何が起きているかを見られるようにするため、多くの +カーネルサブシステム開発者は彼らの開発ツリーを公開しています。これらの +ツリーは説明したように -mm カーネルリリースに入れ込まれます。 + +以下はさまざまなカーネルツリーの中のいくつかのリスト- + + git ツリー- + - Kbuild の開発ツリー、Sam Ravnborg <sam@ravnborg.org> + kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git + + - ACPI の開発ツリー、 Len Brown <len.brown@intel.com> + kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git + + - Block の開発ツリー、Jens Axboe <axboe@suse.de> + kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git + + - DRM の開発ツリー、Dave Airlie <airlied@linux.ie> + kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git + + - ia64 の開発ツリー、Tony Luck <tony.luck@intel.com> + kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + + - ieee1394 の開発ツリー、Jody McIntyre <scjody@modernduck.com> + kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git + + - infiniband, Roland Dreier <rolandd@cisco.com> + kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git + + - libata, Jeff Garzik <jgarzik@pobox.com> + kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git + + - ネットワークドライバ, Jeff Garzik <jgarzik@pobox.com> + kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git + + - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net> + kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git + + - SCSI, James Bottomley <James.Bottomley@SteelEye.com> + kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git + + その他の git カーネルツリーは http://kernel.org/git に一覧表がありま + す。 + + quilt ツリー- + - USB, PCI ドライバコアと I2C, Greg Kroah-Hartman <gregkh@suse.de> + kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ + +バグレポート +------------- + +bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する +場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。 +どう kernel bugzilla を使うかの詳細は、以下を参照してください- + http://test.kernel.org/bugzilla/faq.html + +メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ +ルバグらしいものについてどうレポートするかの良いテンプレートであり、問 +題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳 +細が書かれています。 + +メーリングリスト +------------- + +上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分 +は Linux kernel メーリングリストに参加しています。このリストの登録/脱 +退の方法については以下を参照してください- + http://vger.kernel.org/vger-lists.html#linux-kernel + +このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ +れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば- + http://dir.gmane.org/gmane.linux.kernel + +リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索 +することを是非やってください。多数の事がすでに詳細に渡って議論されて +おり、アーカイブにのみ記録されています。 + +大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス +トを持っています。個々のグループがどんなリストを持っているかは、 +MAINTAINERS ファイルにリストがありますので参照してください。 + +多くのリストは kernel.org でホストされています。これらの情報は以下にあ +ります- + http://vger.kernel.org/vger-lists.html + +メーリングリストを使う場合、良い行動習慣に従うようにしましょう。 +少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の +シンプルなガイドラインを示しています- + http://www.albion.com/netiquette/ + +もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは +だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を +しないように、また、メーリングリストのアドレスだけにリプライすることの +ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー +ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し +てこの状態を変えようとしないように。人々はそのようなことは好みません。 + +今までのメールでのやりとりとその間のあなたの発言はそのまま残し、 +"John Kernlehacker wrote ...:" の行をあなたのリプライの先頭行にして、 +メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで +す。 + +もしパッチをメールに付ける場合は、Documentaion/SubmittingPatches に提 +示されているように、それは プレーンな可読テキストにすることを忘れない +ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま +せん- +彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす +るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう +に確認した方がいいです。最初の良いテストとしては、自分にメールを送って +みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな +ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ +きです。 + +とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ +さい。 + +コミュニティと共に働くこと +-------------------------- + +カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること +です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術 +的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ +うか? + - 批判 + - コメント + - 変更の要求 + - パッチの正当性の証明要求 + - 沈黙 + +思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ +なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら +を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ +きでないかを明確で簡潔な理由の説明を提供してください。 +もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて +見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度 +投稿してください。 + +あなたがやるべきでないものは? + - 質問なしにあなたのパッチが受け入れられると想像すること + - 守りに入ること + - コメントを無視すること + - 要求された変更を何もしないでパッチを出し直すこと + +可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく +らい有益なのかについては常に異なる意見があります。あなたは協調的である +べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ +うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ +だけの価値があるとすすんで証明するようにしなければなりません。 +正しい解決に向かって進もうという意志がある限り、間違うことがあっても許 +容されることを忘れないでください。 + +あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ +とも普通のことです。これはあなたのパッチが受け入れられないということで +は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま +せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば +いいのです。 + +カーネルコミュニティと企業組織のちがい +----------------------------------------------------------------- + +カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で +動いています。以下は問題を避けるためにできるとよいことののリストです- + + あなたの提案する変更について言うときのうまい言い方： + + - "これは複数の問題を解決します" + - "これは2000行のコードを削除します" + - "以下のパッチは、私が言おうとしていることを説明するものです" + - "私はこれを5つの異なるアーキテクチャでテストしたのですが..." + - "以下は一連の小さなパッチ群ですが..." + - "これは典型的なマシンでの性能を向上させます.." + + やめた方がいい悪い言い方： + + - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ + - 私はこれを20年もの間やってきた、だから + - これは、私の会社が金儲けをするために必要だ + - これは我々のエンタープライズ向け商品ラインのためである + - これは 私が自分のアイディアを記述した、1000ページの設計資料である + - 私はこれについて、6ケ月作業している。 + - 以下は ... に関する5000行のパッチです + - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です... + - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある + +カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労 +働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。 +email と irc を第一のコミュニケーションの形とする一つの利点は、性別や +民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受 +容します。なぜなら、email アドレスによってのみあなたが認識されるからで +す。 +国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた +は人の名前で性別を想像できないからです。ある男性が アンドレアという名 +前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、 +それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は +Patricia (主に女性名)や Patrick (主に男性名)の略称)。 +Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前 +向きな経験をもっています。 + +言葉の壁は英語が得意でない一部の人には問題になります。 +メーリングリストの中できちんとアイディアを交換するには、相当うまく英語 +を操れる必要があることもあります。そのため、あなたは自分のメール +を送る前に英語で意味が通じているかをチェックすることをお薦めします。 + +変更を分割する +--------------------- + +Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ +とはありません。変更は正確に説明される必要があり、議論され、小さい、個 +別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて +きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと +ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい +ることにフィードバックを得られます。これは、コミュニティからみれば、あ +なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の +ゴミ捨て場として使っているのではない、と感じられるでしょう。 +しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは +やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ +くなければなりません。 + +パッチを分割する理由は以下です- + +1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー + ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか + らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。し + かし、500行のパッチは、正しいことをレビューするのに数時間かかるかも + しれません(時間はパッチのサイズなどにより指数関数に比例してかかりま + す) + 小さいパッチは何かあったときにデバッグもとても簡単になります。パッ + チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお + かしくなった後で)解剖するのに比べればとても簡単です。 + +2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす + る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。 + +以下はカーネル開発者の Al Viro のたとえ話しです： + + "生徒の数学の宿題を採点する先生のことを考えてみてください、先 + 生は生徒が解に到達するまでの試行錯誤をみたいとは思わないでしょ + う。先生は簡潔な最高の解をみたいのです。良い生徒はこれを知って + おり、そして最終解の前の中間作業を提出することは決してないので + す" + カーネル開発でもこれは同じです。メンテナー達とレビューア達は、 + 問題を解決する解の背後になる思考プロセスをみたいとは思いません。 + 彼らは単純であざやかな解決方法をみたいのです。 + +あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を +議論することのバランスをキープするのは難しいかもしれません。 +ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ +うにするのもいいですが、変更点を小さい部分に分割して全体ではまだ完成し +ていない仕事を(部分的に)取り込んでもらえるようにすることもいいことです。 + +また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め +てもらうように送っても、それは受け付けられないことを理解してください。 + +あなたの変更を正当化する +------------------- + +あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな +いかを Linux コミュニティに知らせることはとても重要です。新機能は必要 +性と有用性で正当化されなければなりません。 + +あなたの変更の説明 +-------------------- + +あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ +いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ +れ、いつも皆がみられるように保管されます。これは次のような項目を含め、 +パッチを完全に記述するべきです- + + - なぜ変更が必要か + - パッチ全体の設計アプローチ + - 実装の詳細 + - テスト結果 + +これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ +ントの ChangeLog セクションをみてください- + "The Perfect Patch" + http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + +これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに +は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた +めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可 +能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同 +じところからスタートしたのですから。 + +Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process" +(http://linux.tar.bz/articles/2.6-development_process)セクショ +ンをこのテキストの原型にすることを許可してくれました。 +Rundy Dunlap と Gerrit Huizenga はメーリングリストでやるべきこととやっ +てはいけないことのリストを提供してくれました。 +以下の人々のレビュー、コメント、貢献に感謝。 +Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi +Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard +彼らの支援なしでは、このドキュメントはできなかったでしょう。 + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt new file mode 100644 index 00000000000..b3f2b27f088 --- /dev/null +++ b/Documentation/ja_JP/stable_api_nonsense.txt @@ -0,0 +1,263 @@ +NOTE: +This is a Japanese translated version of +"Documentation/stable_api_nonsense.txt". +This one is maintained by +IKEDA, Munehiro <m-ikeda@ds.jp.nec.com> +and JF Project team <http://www.linux.or.jp/JF/>. +If you find difference with original file or problem in translation, +please contact the maintainer of this file or JF project. + +Please also note that purpose of this file is easier to read for non +English natives and not to be intended to fork. So, if you have any +comments or updates of this file, please try to update +Original(English) file at first. + +================================== +これは、 +linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳 +です。 +翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > +翻訳日 ： 2007/06/11 +原著作者: Greg Kroah-Hartman < greg at kroah dot com > +翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com > +校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp > + Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp > +================================== + + + +Linux カーネルのドライバインターフェース +（あなたの質問すべてに対する回答とその他諸々） + +Greg Kroah-Hartman <greg at kroah dot com> + + +この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義 +されていないのか、またはなぜ不変のカーネルインターフェースを持たな +いのか、ということを説明するために書かれた。ここでの話題は「カーネ +ル内部の」インターフェースについてであり、ユーザー空間とのインター +フェースではないことを理解してほしい。カーネルとユーザー空間とのイ +ンターフェースとはアプリケーションプログラムが使用するものであり、 +つまりシステムコールのインターフェースがこれに当たる。これは今まで +長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か +より前のカーネルを使ってビルドした古いプログラムを持っているが、そ +れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン +ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼 +してよいものの一つである。 + + +要旨 +---- + +あなたは不変のカーネルインターフェースが必要だと考えているかもしれ +ないが、実際のところはそうではない。あなたは必要としているものが分 +かっていない。あなたが必要としているものは安定して動作するドライバ +であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得 +ることができる。ドライバがメインのカーネルツリーに含まれていると、 +他にも多くの良いことがある。それは、Linux をより強固で、安定な、成 +熟したオペレーティングシステムにすることができるということだ。これ +こそ、そもそもあなたが Linux を使う理由のはずだ。 + + +はじめに +-------- + +カーネル内部のインターフェース変更を心配しなければならないドライバ +を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、 +そのようなドライバがどんなインターフェースを使っているかなど知らな +いし、そんなドライバのことなど全く気にもかけていない。 + + +まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの +みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ +コードでそれを読み込むためのラッパー部分のみソースコードが公開され +ているとか、その他用語は何であれ GPL の下にソースコードがリリース +されていないカーネルドライバに関する法的な問題について、私は「いか +なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ +である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問 +題について述べることにする。（法的な問題を軽視しているわけではない。 +それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が +ある） + +訳注(1) +「使い物にならない代物」の原文は "blob" + + +さてここでは、バイナリカーネルインターフェースについてと、ソースレ +ベルでのインターフェースの不変性について、という二つの話題を取り上 +げる。この二つは互いに依存する関係にあるが、まずはバイナリインター +フェースについて議論を行いやっつけてしまおう。 + + +バイナリカーネルインターフェース +-------------------------------- + +もしソースレベルでのインターフェースが不変ならば、バイナリインター +フェースも当然のように不変である、というのは正しいだろうか？正しく +ない。Linux カーネルに関する以下の事実を考えてみてほしい。 + - あなたが使用するＣコンパイラのバージョンによって、カーネル内部 + の構造体の配置構造は異なったものになる。また、関数は異なった方 + 法でカーネルに含まれることになるかもしれない（例えばインライン + 関数として扱われたり、扱われなかったりする）。個々の関数がどの + ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ + ィングが異なるというのは非常に重要である。 + - あなたがカーネルのビルドオプションをどのように設定するかによっ + て、カーネルには広い範囲で異なった事態が起こり得る。 + - データ構造は異なるデータフィールドを持つかもしれない + - いくつかの関数は全く実装されていない状態になり得る + （例：SMP向けではないビルドでは、いくつかのロックは中身が + カラにコンパイルされる） + - カーネル内のメモリは、異なった方法で配置され得る。これはビ + ルドオプションに依存している。 + - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。 + あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで + 正常に動作させる方法はない。 + + +ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ +Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで +も、あなたはこれらいくつもの問題に直面することになる。ある特定の +Linux ディストリビューションの、ある特定のリリースバージョン用にモ +ジュールを提供しようと思っただけでも、これらの問題を引き起こすには +十分である。にも関わらず Linux ディストリビューションの数と、サ +ポートするディストリビューションのリリース数を掛け算し、それら一つ +一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ +ションの違いという悪夢にすぐさま悩まされることになる。また、ディス +トリビューションの各リリースバージョンには、異なるハードウェア（プ +ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ +ルが含まれているということも理解して欲しい。従って、ある一つのリ +リースバージョンだけのためにモジュールを作成する場合でも、あなたは +何バージョンものモジュールを用意しなければならない。 + + +信じて欲しい。このような方法でサポートを続けようとするなら、あなた +はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身 +をもって学んだのだ・・・ + + +不変のカーネルソースレベルインターフェース +------------------------------------------ + +メインカーネルツリーに含まれていない Linux カーネルドライバを継続 +してサポートしていこうとしている人たちとの議論においては、これは極 +めて「引火性の高い」話題である。[訳注(2)] + +訳注(2) +「引火性の高い」の原文は "volatile"。 +volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり +やすい」「移り気な」という意味がある。 +「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ +を、「（カーネルのソースレベルインターフェースは）移ろい行くもので +ある」ということを連想させる "volatile" という単語で表現している。 + + +Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め +ることがない。その中でカーネル開発者達は、現状のインターフェースに +あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン +ターフェースがより正しく動作するように修正を行う。その過程で関数の +名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし +れず、関数の引数は検討しなおされるかもしれない。そのような場合、引 +き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー +スを使用している個所も全て同時に修正される。 + + +具体的な例として、カーネル内の USB インターフェースを挙げる。USB +サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果 +インターフェースが変更された。これらの書き直しはいくつかの異なった +問題を修正するために行われた。 + - 同期的データストリームが非同期に変更された。これにより多数のド + ライバを単純化でき、全てのドライバのスループットが向上した。今 + やほとんど全ての USB デバイスは、考えられる最高の速度で動作し + ている。 + - USB ドライバが USB サブシステムのコアから行う、データパケット + 用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ + れたデッドロック条件を回避するため、全ての USB ドライバはより + 多くの情報を USB コアに提供しなければならないようになっている。 + + +このできごとは、数多く存在するクローズソースのオペレーティングシス +テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース +をメンテナンスしなければならない。古いインターフェースが残ることで、 +新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発 +を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ +らされることになる。 + + +上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で +あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ +ベルでインターフェースの不変性を保証しなければならないとしたら、新 +しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ +ンテナンスするという余計な仕事を USB の開発者にさせなければならな +い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ +て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。 + + +セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ +ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正 +される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ +ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ +れたインターフェースを使用する全てのドライバもまた変更された。これ +により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ +れる。もし内部インターフェースの変更が許されないとしたら、このよう +にセキュリティ問題を修正し、将来再発しないことを保証することなど不 +可能なのだ。 + + +カーネルのインターフェースは時が経つにつれクリーンナップを受ける。 +誰も使っていないインターフェースは削除される。これにより、可能な限 +りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り +テストされることを保証しているのだ。（使われていないインターフェー +スの妥当性をテストすることは不可能と言っていいだろう） + + + +これから何をすべきか +----------------------- + +では、もしメインのカーネルツリーに含まれない Linux カーネルドライ +バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全 +てのディストリビューションの全てのカーネルバージョン向けにバイナリ +のドライバを供給することは悪夢であり、カーネルインターフェースの変 +更を追いかけ続けることもまた過酷な仕事だ。 + + +答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ +い。（ここで言及しているのは、GPL に従って公開されるドライバのこと +だということに注意してほしい。あなたのコードがそれに該当しないなら +ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew +と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ +こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン +ターフェースが変更された場合、変更を行った開発者によってドライバも +修正されることになるだろう。あなたはほとんど労力を払うことなしに、 +常にビルド可能できちんと動作するドライバを手に入れることができる。 + + +ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効 +果がある。 + - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ + ナンスコストは下がる。 + - あなたのドライバに他の開発者が機能を追加してくれる。 + - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。 + - 誰かがあなたのドライバにある改善点を見つけてくれる。 + - 外部インターフェースが変更されドライバの更新が必要になった場合、 + 誰かがあなたの代わりに更新してくれる。 + - ドライバを入れてくれとディストロに頼まなくても、そのドライバは + 全ての Linux ディストリビューションに自動的に含まれてリリース + される。 + + +Linux では、他のどのオペレーティングシステムよりも数多くのデバイス +が「そのまま」使用できるようになった。また Linux は、どのオペレー +ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの +デバイスを使用することができるようにもなった。このように、Linux の +開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい +くだろう。:) + + + +------ + +この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David +Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読 +と助言を頂きました。感謝申し上げます。 + diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index bb5306e9a5c..e08ef8759a0 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -501,6 +501,20 @@ more details, with real examples. The third parameter may be a text as in this example, but it may also be an expanded variable or a macro. + cc-fullversion + cc-fullversion is useful when the exact version of gcc is needed. + One typical use-case is when a specific GCC version is broken. + cc-fullversion points out a more specific version than cc-version does. + + Example: + #arch/powerpc/Makefile + $(Q)if test "$(call cc-fullversion)" = "040200" ; then \ + echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \ + false ; \ + fi + + In this example for a specific GCC version the build will error out explaining + to the user why it stops. === 4 Host Program support diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 9a541486fb7..fb80e9ffea6 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1154,6 +1154,8 @@ and is between 256 and 4096 characters. It is defined in the file nointroute [IA-64] + nojitter [IA64] Disables jitter checking for ITC timers. + nolapic [IA-32,APIC] Do not enable or use the local APIC. nolapic_timer [IA-32,APIC] Do not use the local APIC timer. @@ -1880,11 +1882,14 @@ and is between 256 and 4096 characters. It is defined in the file usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. - vdso= [IA-32,SH] + vdso= [IA-32,SH,x86-64] vdso=2: enable compat VDSO (default with COMPAT_VDSO) vdso=1: enable VDSO (default) vdso=0: disable VDSO mapping + vector= [IA-64,SMP] + vector=percpu: enable percpu vector domain + video= [FB] Frame buffer configuration See Documentation/fb/modedb.txt. diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index da5404ab756..cb12ae175aa 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -247,12 +247,6 @@ control to Kprobes.) If the probed function is declared asmlinkage, fastcall, or anything else that affects how args are passed, the handler's declaration must match. -NOTE: A macro JPROBE_ENTRY is provided to handle architecture-specific -aliasing of jp->entry. In the interest of portability, it is advised -to use: - - jp->entry = JPROBE_ENTRY(handler); - register_jprobe() returns 0 on success, or a negative errno otherwise. 4.3 register_kretprobe @@ -518,7 +512,7 @@ long jdo_fork(unsigned long clone_flags, unsigned long stack_start, } static struct jprobe my_jprobe = { - .entry = JPROBE_ENTRY(jdo_fork) + .entry = jdo_fork }; static int __init jprobe_init(void) diff --git a/Documentation/lguest/Makefile b/Documentation/lguest/Makefile new file mode 100644 index 00000000000..b9b9427376e --- /dev/null +++ b/Documentation/lguest/Makefile @@ -0,0 +1,27 @@ +# This creates the demonstration utility "lguest" which runs a Linux guest. + +# For those people that have a separate object dir, look there for .config +KBUILD_OUTPUT := ../.. +ifdef O + ifeq ("$(origin O)", "command line") + KBUILD_OUTPUT := $(O) + endif +endif +# We rely on CONFIG_PAGE_OFFSET to know where to put lguest binary. +include $(KBUILD_OUTPUT)/.config +LGUEST_GUEST_TOP := ($(CONFIG_PAGE_OFFSET) - 0x08000000) + +CFLAGS:=-Wall -Wmissing-declarations -Wmissing-prototypes -O3 \ + -static -DLGUEST_GUEST_TOP="$(LGUEST_GUEST_TOP)" -Wl,-T,lguest.lds +LDLIBS:=-lz + +all: lguest.lds lguest + +# The linker script on x86 is so complex the only way of creating one +# which will link our binary in the right place is to mangle the +# default one. +lguest.lds: + $(LD) --verbose | awk '/^==========/ { PRINT=1; next; } /SIZEOF_HEADERS/ { gsub(/0x[0-9A-F]*/, "$(LGUEST_GUEST_TOP)") } { if (PRINT) print $$0; }' > $@ + +clean: + rm -f lguest.lds lguest diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c new file mode 100644 index 00000000000..1432b502a2d --- /dev/null +++ b/Documentation/lguest/lguest.c @@ -0,0 +1,1012 @@ +/* Simple program to layout "physical" memory for new lguest guest. + * Linked high to avoid likely physical memory. */ +#define _LARGEFILE64_SOURCE +#define _GNU_SOURCE +#include <stdio.h> +#include <string.h> +#include <unistd.h> +#include <err.h> +#include <stdint.h> +#include <stdlib.h> +#include <elf.h> +#include <sys/mman.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <sys/wait.h> +#include <fcntl.h> +#include <stdbool.h> +#include <errno.h> +#include <ctype.h> +#include <sys/socket.h> +#include <sys/ioctl.h> +#include <sys/time.h> +#include <time.h> +#include <netinet/in.h> +#include <net/if.h> +#include <linux/sockios.h> +#include <linux/if_tun.h> +#include <sys/uio.h> +#include <termios.h> +#include <getopt.h> +#include <zlib.h> +typedef unsigned long long u64; +typedef uint32_t u32; +typedef uint16_t u16; +typedef uint8_t u8; +#include "../../include/linux/lguest_launcher.h" +#include "../../include/asm-i386/e820.h" + +#define PAGE_PRESENT 0x7 /* Present, RW, Execute */ +#define NET_PEERNUM 1 +#define BRIDGE_PFX "bridge:" +#ifndef SIOCBRADDIF +#define SIOCBRADDIF 0x89a2 /* add interface to bridge */ +#endif + +static bool verbose; +#define verbose(args...) \ + do { if (verbose) printf(args); } while(0) +static int waker_fd; + +struct device_list +{ + fd_set infds; + int max_infd; + + struct device *dev; + struct device **lastdev; +}; + +struct device +{ + struct device *next; + struct lguest_device_desc *desc; + void *mem; + + /* Watch this fd if handle_input non-NULL. */ + int fd; + bool (*handle_input)(int fd, struct device *me); + + /* Watch DMA to this key if handle_input non-NULL. */ + unsigned long watch_key; + u32 (*handle_output)(int fd, const struct iovec *iov, + unsigned int num, struct device *me); + + /* Device-specific data. */ + void *priv; +}; + +static int open_or_die(const char *name, int flags) +{ + int fd = open(name, flags); + if (fd < 0) + err(1, "Failed to open %s", name); + return fd; +} + +static void *map_zeroed_pages(unsigned long addr, unsigned int num) +{ + static int fd = -1; + + if (fd == -1) + fd = open_or_die("/dev/zero", O_RDONLY); + + if (mmap((void *)addr, getpagesize() * num, + PROT_READ|PROT_WRITE|PROT_EXEC, MAP_FIXED|MAP_PRIVATE, fd, 0) + != (void *)addr) + err(1, "Mmaping %u pages of /dev/zero @%p", num, (void *)addr); + return (void *)addr; +} + +/* Find magic string marking entry point, return entry point. */ +static unsigned long entry_point(void *start, void *end, + unsigned long page_offset) +{ + void *p; + + for (p = start; p < end; p++) + if (memcmp(p, "GenuineLguest", strlen("GenuineLguest")) == 0) + return (long)p + strlen("GenuineLguest") + page_offset; + + err(1, "Is this image a genuine lguest?"); +} + +/* Returns the entry point */ +static unsigned long map_elf(int elf_fd, const Elf32_Ehdr *ehdr, + unsigned long *page_offset) +{ + void *addr; + Elf32_Phdr phdr[ehdr->e_phnum]; + unsigned int i; + unsigned long start = -1UL, end = 0; + + /* Sanity checks. */ + if (ehdr->e_type != ET_EXEC + || ehdr->e_machine != EM_386 + || ehdr->e_phentsize != sizeof(Elf32_Phdr) + || ehdr->e_phnum < 1 || ehdr->e_phnum > 65536U/sizeof(Elf32_Phdr)) + errx(1, "Malformed elf header"); + + if (lseek(elf_fd, ehdr->e_phoff, SEEK_SET) < 0) + err(1, "Seeking to program headers"); + if (read(elf_fd, phdr, sizeof(phdr)) != sizeof(phdr)) + err(1, "Reading program headers"); + + *page_offset = 0; + /* We map the loadable segments at virtual addresses corresponding + * to their physical addresses (our virtual == guest physical). */ + for (i = 0; i < ehdr->e_phnum; i++) { + if (phdr[i].p_type != PT_LOAD) + continue; + + verbose("Section %i: size %i addr %p\n", + i, phdr[i].p_memsz, (void *)phdr[i].p_paddr); + + /* We expect linear address space. */ + if (!*page_offset) + *page_offset = phdr[i].p_vaddr - phdr[i].p_paddr; + else if (*page_offset != phdr[i].p_vaddr - phdr[i].p_paddr) + errx(1, "Page offset of section %i different", i); + + if (phdr[i].p_paddr < start) + start = phdr[i].p_paddr; + if (phdr[i].p_paddr + phdr[i].p_filesz > end) + end = phdr[i].p_paddr + phdr[i].p_filesz; + + /* We map everything private, writable. */ + addr = mmap((void *)phdr[i].p_paddr, + phdr[i].p_filesz, + PROT_READ|PROT_WRITE|PROT_EXEC, + MAP_FIXED|MAP_PRIVATE, + elf_fd, phdr[i].p_offset); + if (addr != (void *)phdr[i].p_paddr) + err(1, "Mmaping vmlinux seg %i gave %p not %p", + i, addr, (void *)phdr[i].p_paddr); + } + + return entry_point((void *)start, (void *)end, *page_offset); +} + +/* This is amazingly reliable. */ +static unsigned long intuit_page_offset(unsigned char *img, unsigned long len) +{ + unsigned int i, possibilities[256] = { 0 }; + + for (i = 0; i + 4 < len; i++) { + /* mov 0xXXXXXXXX,%eax */ + if (img[i] == 0xA1 && ++possibilities[img[i+4]] > 3) + return (unsigned long)img[i+4] << 24; + } + errx(1, "could not determine page offset"); +} + +static unsigned long unpack_bzimage(int fd, unsigned long *page_offset) +{ + gzFile f; + int ret, len = 0; + void *img = (void *)0x100000; + + f = gzdopen(fd, "rb"); + while ((ret = gzread(f, img + len, 65536)) > 0) + len += ret; + if (ret < 0) + err(1, "reading image from bzImage"); + + verbose("Unpacked size %i addr %p\n", len, img); + *page_offset = intuit_page_offset(img, len); + + return entry_point(img, img + len, *page_offset); +} + +static unsigned long load_bzimage(int fd, unsigned long *page_offset) +{ + unsigned char c; + int state = 0; + + /* Ugly brute force search for gzip header. */ + while (read(fd, &c, 1) == 1) { + switch (state) { + case 0: + if (c == 0x1F) + state++; + break; + case 1: + if (c == 0x8B) + state++; + else + state = 0; + break; + case 2 ... 8: + state++; + break; + case 9: + lseek(fd, -10, SEEK_CUR); + if (c != 0x03) /* Compressed under UNIX. */ + state = -1; + else + return unpack_bzimage(fd, page_offset); + } + } + errx(1, "Could not find kernel in bzImage"); +} + +static unsigned long load_kernel(int fd, unsigned long *page_offset) +{ + Elf32_Ehdr hdr; + + if (read(fd, &hdr, sizeof(hdr)) != sizeof(hdr)) + err(1, "Reading kernel"); + + if (memcmp(hdr.e_ident, ELFMAG, SELFMAG) == 0) + return map_elf(fd, &hdr, page_offset); + + return load_bzimage(fd, page_offset); +} + +static inline unsigned long page_align(unsigned long addr) +{ + return ((addr + getpagesize()-1) & ~(getpagesize()-1)); +} + +/* initrd gets loaded at top of memory: return length. */ +static unsigned long load_initrd(const char *name, unsigned long mem) +{ + int ifd; + struct stat st; + unsigned long len; + void *iaddr; + + ifd = open_or_die(name, O_RDONLY); + if (fstat(ifd, &st) < 0) + err(1, "fstat() on initrd '%s'", name); + + len = page_align(st.st_size); + iaddr = mmap((void *)mem - len, st.st_size, + PROT_READ|PROT_EXEC|PROT_WRITE, + MAP_FIXED|MAP_PRIVATE, ifd, 0); + if (iaddr != (void *)mem - len) + err(1, "Mmaping initrd '%s' returned %p not %p", + name, iaddr, (void *)mem - len); + close(ifd); + verbose("mapped initrd %s size=%lu @ %p\n", name, st.st_size, iaddr); + return len; +} + +static unsigned long setup_pagetables(unsigned long mem, + unsigned long initrd_size, + unsigned long page_offset) +{ + u32 *pgdir, *linear; + unsigned int mapped_pages, i, linear_pages; + unsigned int ptes_per_page = getpagesize()/sizeof(u32); + + /* If we can map all of memory above page_offset, we do so. */ + if (mem <= -page_offset) + mapped_pages = mem/getpagesize(); + else + mapped_pages = -page_offset/getpagesize(); + + /* Each linear PTE page can map ptes_per_page pages. */ + linear_pages = (mapped_pages + ptes_per_page-1)/ptes_per_page; + + /* We lay out top-level then linear mapping immediately below initrd */ + pgdir = (void *)mem - initrd_size - getpagesize(); + linear = (void *)pgdir - linear_pages*getpagesize(); + + for (i = 0; i < mapped_pages; i++) + linear[i] = ((i * getpagesize()) | PAGE_PRESENT); + + /* Now set up pgd so that this memory is at page_offset */ + for (i = 0; i < mapped_pages; i += ptes_per_page) { + pgdir[(i + page_offset/getpagesize())/ptes_per_page] + = (((u32)linear + i*sizeof(u32)) | PAGE_PRESENT); + } + + verbose("Linear mapping of %u pages in %u pte pages at %p\n", + mapped_pages, linear_pages, linear); + + return (unsigned long)pgdir; +} + +static void concat(char *dst, char *args[]) +{ + unsigned int i, len = 0; + + for (i = 0; args[i]; i++) { + strcpy(dst+len, args[i]); + strcat(dst+len, " "); + len += strlen(args[i]) + 1; + } + /* In case it's empty. */ + dst[len] = '\0'; +} + +static int tell_kernel(u32 pgdir, u32 start, u32 page_offset) +{ + u32 args[] = { LHREQ_INITIALIZE, + LGUEST_GUEST_TOP/getpagesize(), /* Just below us */ + pgdir, start, page_offset }; + int fd; + + fd = open_or_die("/dev/lguest", O_RDWR); + if (write(fd, args, sizeof(args)) < 0) + err(1, "Writing to /dev/lguest"); + return fd; +} + +static void set_fd(int fd, struct device_list *devices) +{ + FD_SET(fd, &devices->infds); + if (fd > devices->max_infd) + devices->max_infd = fd; +} + +/* When input arrives, we tell the kernel to kick lguest out with -EAGAIN. */ +static void wake_parent(int pipefd, int lguest_fd, struct device_list *devices) +{ + set_fd(pipefd, devices); + + for (;;) { + fd_set rfds = devices->infds; + u32 args[] = { LHREQ_BREAK, 1 }; + + select(devices->max_infd+1, &rfds, NULL, NULL, NULL); + if (FD_ISSET(pipefd, &rfds)) { + int ignorefd; + if (read(pipefd, &ignorefd, sizeof(ignorefd)) == 0) + exit(0); + FD_CLR(ignorefd, &devices->infds); + } else + write(lguest_fd, args, sizeof(args)); + } +} + +static int setup_waker(int lguest_fd, struct device_list *device_list) +{ + int pipefd[2], child; + + pipe(pipefd); + child = fork(); + if (child == -1) + err(1, "forking"); + + if (child == 0) { + close(pipefd[1]); + wake_parent(pipefd[0], lguest_fd, device_list); + } + close(pipefd[0]); + + return pipefd[1]; +} + +static void *_check_pointer(unsigned long addr, unsigned int size, + unsigned int line) +{ + if (addr >= LGUEST_GUEST_TOP || addr + size >= LGUEST_GUEST_TOP) + errx(1, "%s:%i: Invalid address %li", __FILE__, line, addr); + return (void *)addr; +} +#define check_pointer(addr,size) _check_pointer(addr, size, __LINE__) + +/* Returns pointer to dma->used_len */ +static u32 *dma2iov(unsigned long dma, struct iovec iov[], unsigned *num) +{ + unsigned int i; + struct lguest_dma *udma; + + udma = check_pointer(dma, sizeof(*udma)); + for (i = 0; i < LGUEST_MAX_DMA_SECTIONS; i++) { + if (!udma->len[i]) + break; + + iov[i].iov_base = check_pointer(udma->addr[i], udma->len[i]); + iov[i].iov_len = udma->len[i]; + } + *num = i; + return &udma->used_len; +} + +static u32 *get_dma_buffer(int fd, void *key, + struct iovec iov[], unsigned int *num, u32 *irq) +{ + u32 buf[] = { LHREQ_GETDMA, (u32)key }; + unsigned long udma; + u32 *res; + + udma = write(fd, buf, sizeof(buf)); + if (udma == (unsigned long)-1) + return NULL; + + /* Kernel stashes irq in ->used_len. */ + res = dma2iov(udma, iov, num); + *irq = *res; + return res; +} + +static void trigger_irq(int fd, u32 irq) +{ + u32 buf[] = { LHREQ_IRQ, irq }; + if (write(fd, buf, sizeof(buf)) != 0) + err(1, "Triggering irq %i", irq); +} + +static void discard_iovec(struct iovec *iov, unsigned int *num) +{ + static char discard_buf[1024]; + *num = 1; + iov->iov_base = discard_buf; + iov->iov_len = sizeof(discard_buf); +} + +static struct termios orig_term; +static void restore_term(void) +{ + tcsetattr(STDIN_FILENO, TCSANOW, &orig_term); +} + +struct console_abort +{ + int count; + struct timeval start; +}; + +/* We DMA input to buffer bound at start of console page. */ +static bool handle_console_input(int fd, struct device *dev) +{ + u32 irq = 0, *lenp; + int len; + unsigned int num; + struct iovec iov[LGUEST_MAX_DMA_SECTIONS]; + struct console_abort *abort = dev->priv; + + lenp = get_dma_buffer(fd, dev->mem, iov, &num, &irq); + if (!lenp) { + warn("console: no dma buffer!"); + discard_iovec(iov, &num); + } + + len = readv(dev->fd, iov, num); + if (len <= 0) { + warnx("Failed to get console input, ignoring console."); + len = 0; + } + + if (lenp) { + *lenp = len; + trigger_irq(fd, irq); + } + + /* Three ^C within one second? Exit. */ + if (len == 1 && ((char *)iov[0].iov_base)[0] == 3) { + if (!abort->count++) + gettimeofday(&abort->start, NULL); + else if (abort->count == 3) { + struct timeval now; + gettimeofday(&now, NULL); + if (now.tv_sec <= abort->start.tv_sec+1) { + /* Make sure waker is not blocked in BREAK */ + u32 args[] = { LHREQ_BREAK, 0 }; + close(waker_fd); + write(fd, args, sizeof(args)); + exit(2); + } + abort->count = 0; + } + } else + abort->count = 0; + + if (!len) { + restore_term(); + return false; + } + return true; +} + +static u32 handle_console_output(int fd, const struct iovec *iov, + unsigned num, struct device*dev) +{ + return writev(STDOUT_FILENO, iov, num); +} + +static u32 handle_tun_output(int fd, const struct iovec *iov, + unsigned num, struct device *dev) +{ + /* Now we've seen output, we should warn if we can't get buffers. */ + *(bool *)dev->priv = true; + return writev(dev->fd, iov, num); +} + +static unsigned long peer_offset(unsigned int peernum) +{ + return 4 * peernum; +} + +static bool handle_tun_input(int fd, struct device *dev) +{ + u32 irq = 0, *lenp; + int len; + unsigned num; + struct iovec iov[LGUEST_MAX_DMA_SECTIONS]; + + lenp = get_dma_buffer(fd, dev->mem+peer_offset(NET_PEERNUM), iov, &num, + &irq); + if (!lenp) { + if (*(bool *)dev->priv) + warn("network: no dma buffer!"); + discard_iovec(iov, &num); + } + + len = readv(dev->fd, iov, num); + if (len <= 0) + err(1, "reading network"); + if (lenp) { + *lenp = len; + trigger_irq(fd, irq); + } + verbose("tun input packet len %i [%02x %02x] (%s)\n", len, + ((u8 *)iov[0].iov_base)[0], ((u8 *)iov[0].iov_base)[1], + lenp ? "sent" : "discarded"); + return true; +} + +static u32 handle_block_output(int fd, const struct iovec *iov, + unsigned num, struct device *dev) +{ + struct lguest_block_page *p = dev->mem; + u32 irq, *lenp; + unsigned int len, reply_num; + struct iovec reply[LGUEST_MAX_DMA_SECTIONS]; + off64_t device_len, off = (off64_t)p->sector * 512; + + device_len = *(off64_t *)dev->priv; + + if (off >= device_len) + err(1, "Bad offset %llu vs %llu", off, device_len); + if (lseek64(dev->fd, off, SEEK_SET) != off) + err(1, "Bad seek to sector %i", p->sector); + + verbose("Block: %s at offset %llu\n", p->type ? "WRITE" : "READ", off); + + lenp = get_dma_buffer(fd, dev->mem, reply, &reply_num, &irq); + if (!lenp) + err(1, "Block request didn't give us a dma buffer"); + + if (p->type) { + len = writev(dev->fd, iov, num); + if (off + len > device_len) { + ftruncate(dev->fd, device_len); + errx(1, "Write past end %llu+%u", off, len); + } + *lenp = 0; + } else { + len = readv(dev->fd, reply, reply_num); + *lenp = len; + } + + p->result = 1 + (p->bytes != len); + trigger_irq(fd, irq); + return 0; +} + +static void handle_output(int fd, unsigned long dma, unsigned long key, + struct device_list *devices) +{ + struct device *i; + u32 *lenp; + struct iovec iov[LGUEST_MAX_DMA_SECTIONS]; + unsigned num = 0; + + lenp = dma2iov(dma, iov, &num); + for (i = devices->dev; i; i = i->next) { + if (i->handle_output && key == i->watch_key) { + *lenp = i->handle_output(fd, iov, num, i); + return; + } + } + warnx("Pending dma %p, key %p", (void *)dma, (void *)key); +} + +static void handle_input(int fd, struct device_list *devices) +{ + struct timeval poll = { .tv_sec = 0, .tv_usec = 0 }; + + for (;;) { + struct device *i; + fd_set fds = devices->infds; + + if (select(devices->max_infd+1, &fds, NULL, NULL, &poll) == 0) + break; + + for (i = devices->dev; i; i = i->next) { + if (i->handle_input && FD_ISSET(i->fd, &fds)) { + if (!i->handle_input(fd, i)) { + FD_CLR(i->fd, &devices->infds); + /* Tell waker to ignore it too... */ + write(waker_fd, &i->fd, sizeof(i->fd)); + } + } + } + } +} + +static struct lguest_device_desc *new_dev_desc(u16 type, u16 features, + u16 num_pages) +{ + static unsigned long top = LGUEST_GUEST_TOP; + struct lguest_device_desc *desc; + + desc = malloc(sizeof(*desc)); + desc->type = type; + desc->num_pages = num_pages; + desc->features = features; + desc->status = 0; + if (num_pages) { + top -= num_pages*getpagesize(); + map_zeroed_pages(top, num_pages); + desc->pfn = top / getpagesize(); + } else + desc->pfn = 0; + return desc; +} + +static struct device *new_device(struct device_list *devices, + u16 type, u16 num_pages, u16 features, + int fd, + bool (*handle_input)(int, struct device *), + unsigned long watch_off, + u32 (*handle_output)(int, + const struct iovec *, + unsigned, + struct device *)) +{ + struct device *dev = malloc(sizeof(*dev)); + + /* Append to device list. */ + *devices->lastdev = dev; + dev->next = NULL; + devices->lastdev = &dev->next; + + dev->fd = fd; + if (handle_input) + set_fd(dev->fd, devices); + dev->desc = new_dev_desc(type, features, num_pages); + dev->mem = (void *)(dev->desc->pfn * getpagesize()); + dev->handle_input = handle_input; + dev->watch_key = (unsigned long)dev->mem + watch_off; + dev->handle_output = handle_output; + return dev; +} + +static void setup_console(struct device_list *devices) +{ + struct device *dev; + + if (tcgetattr(STDIN_FILENO, &orig_term) == 0) { + struct termios term = orig_term; + term.c_lflag &= ~(ISIG|ICANON|ECHO); + tcsetattr(STDIN_FILENO, TCSANOW, &term); + atexit(restore_term); + } + + /* We don't currently require a page for the console. */ + dev = new_device(devices, LGUEST_DEVICE_T_CONSOLE, 0, 0, + STDIN_FILENO, handle_console_input, + LGUEST_CONSOLE_DMA_KEY, handle_console_output); + dev->priv = malloc(sizeof(struct console_abort)); + ((struct console_abort *)dev->priv)->count = 0; + verbose("device %p: console\n", + (void *)(dev->desc->pfn * getpagesize())); +} + +static void setup_block_file(const char *filename, struct device_list *devices) +{ + int fd; + struct device *dev; + off64_t *device_len; + struct lguest_block_page *p; + + fd = open_or_die(filename, O_RDWR|O_LARGEFILE|O_DIRECT); + dev = new_device(devices, LGUEST_DEVICE_T_BLOCK, 1, + LGUEST_DEVICE_F_RANDOMNESS, + fd, NULL, 0, handle_block_output); + device_len = dev->priv = malloc(sizeof(*device_len)); + *device_len = lseek64(fd, 0, SEEK_END); + p = dev->mem; + + p->num_sectors = *device_len/512; + verbose("device %p: block %i sectors\n", + (void *)(dev->desc->pfn * getpagesize()), p->num_sectors); +} + +/* We use fnctl locks to reserve network slots (autocleanup!) */ +static unsigned int find_slot(int netfd, const char *filename) +{ + struct flock fl; + + fl.l_type = F_WRLCK; + fl.l_whence = SEEK_SET; + fl.l_len = 1; + for (fl.l_start = 0; + fl.l_start < getpagesize()/sizeof(struct lguest_net); + fl.l_start++) { + if (fcntl(netfd, F_SETLK, &fl) == 0) + return fl.l_start; + } + errx(1, "No free slots in network file %s", filename); +} + +static void setup_net_file(const char *filename, + struct device_list *devices) +{ + int netfd; + struct device *dev; + + netfd = open(filename, O_RDWR, 0); + if (netfd < 0) { + if (errno == ENOENT) { + netfd = open(filename, O_RDWR|O_CREAT, 0600); + if (netfd >= 0) { + char page[getpagesize()]; + memset(page, 0, sizeof(page)); + write(netfd, page, sizeof(page)); + } + } + if (netfd < 0) + err(1, "cannot open net file '%s'", filename); + } + + dev = new_device(devices, LGUEST_DEVICE_T_NET, 1, + find_slot(netfd, filename)|LGUEST_NET_F_NOCSUM, + -1, NULL, 0, NULL); + + /* We overwrite the /dev/zero mapping with the actual file. */ + if (mmap(dev->mem, getpagesize(), PROT_READ|PROT_WRITE, + MAP_FIXED|MAP_SHARED, netfd, 0) != dev->mem) + err(1, "could not mmap '%s'", filename); + verbose("device %p: shared net %s, peer %i\n", + (void *)(dev->desc->pfn * getpagesize()), filename, + dev->desc->features & ~LGUEST_NET_F_NOCSUM); +} + +static u32 str2ip(const char *ipaddr) +{ + unsigned int byte[4]; + + sscanf(ipaddr, "%u.%u.%u.%u", &byte[0], &byte[1], &byte[2], &byte[3]); + return (byte[0] << 24) | (byte[1] << 16) | (byte[2] << 8) | byte[3]; +} + +/* adapted from libbridge */ +static void add_to_bridge(int fd, const char *if_name, const char *br_name) +{ + int ifidx; + struct ifreq ifr; + + if (!*br_name) + errx(1, "must specify bridge name"); + + ifidx = if_nametoindex(if_name); + if (!ifidx) + errx(1, "interface %s does not exist!", if_name); + + strncpy(ifr.ifr_name, br_name, IFNAMSIZ); + ifr.ifr_ifindex = ifidx; + if (ioctl(fd, SIOCBRADDIF, &ifr) < 0) + err(1, "can't add %s to bridge %s", if_name, br_name); +} + +static void configure_device(int fd, const char *devname, u32 ipaddr, + unsigned char hwaddr[6]) +{ + struct ifreq ifr; + struct sockaddr_in *sin = (struct sockaddr_in *)&ifr.ifr_addr; + + memset(&ifr, 0, sizeof(ifr)); + strcpy(ifr.ifr_name, devname); + sin->sin_family = AF_INET; + sin->sin_addr.s_addr = htonl(ipaddr); + if (ioctl(fd, SIOCSIFADDR, &ifr) != 0) + err(1, "Setting %s interface address", devname); + ifr.ifr_flags = IFF_UP; + if (ioctl(fd, SIOCSIFFLAGS, &ifr) != 0) + err(1, "Bringing interface %s up", devname); + + if (ioctl(fd, SIOCGIFHWADDR, &ifr) != 0) + err(1, "getting hw address for %s", devname); + + memcpy(hwaddr, ifr.ifr_hwaddr.sa_data, 6); +} + +static void setup_tun_net(const char *arg, struct device_list *devices) +{ + struct device *dev; + struct ifreq ifr; + int netfd, ipfd; + u32 ip; + const char *br_name = NULL; + + netfd = open_or_die("/dev/net/tun", O_RDWR); + memset(&ifr, 0, sizeof(ifr)); + ifr.ifr_flags = IFF_TAP | IFF_NO_PI; + strcpy(ifr.ifr_name, "tap%d"); + if (ioctl(netfd, TUNSETIFF, &ifr) != 0) + err(1, "configuring /dev/net/tun"); + ioctl(netfd, TUNSETNOCSUM, 1); + + /* You will be peer 1: we should create enough jitter to randomize */ + dev = new_device(devices, LGUEST_DEVICE_T_NET, 1, + NET_PEERNUM|LGUEST_DEVICE_F_RANDOMNESS, netfd, + handle_tun_input, peer_offset(0), handle_tun_output); + dev->priv = malloc(sizeof(bool)); + *(bool *)dev->priv = false; + + ipfd = socket(PF_INET, SOCK_DGRAM, IPPROTO_IP); + if (ipfd < 0) + err(1, "opening IP socket"); + + if (!strncmp(BRIDGE_PFX, arg, strlen(BRIDGE_PFX))) { + ip = INADDR_ANY; + br_name = arg + strlen(BRIDGE_PFX); + add_to_bridge(ipfd, ifr.ifr_name, br_name); + } else + ip = str2ip(arg); + + /* We are peer 0, ie. first slot. */ + configure_device(ipfd, ifr.ifr_name, ip, dev->mem); + + /* Set "promisc" bit: we want every single packet. */ + *((u8 *)dev->mem) |= 0x1; + + close(ipfd); + + verbose("device %p: tun net %u.%u.%u.%u\n", + (void *)(dev->desc->pfn * getpagesize()), + (u8)(ip>>24), (u8)(ip>>16), (u8)(ip>>8), (u8)ip); + if (br_name) + verbose("attached to bridge: %s\n", br_name); +} + +/* Now we know how much memory we have, we copy in device descriptors */ +static void map_device_descriptors(struct device_list *devs, unsigned long mem) +{ + struct device *i; + unsigned int num; + struct lguest_device_desc *descs; + + /* Device descriptor array sits just above top of normal memory */ + descs = map_zeroed_pages(mem, 1); + + for (i = devs->dev, num = 0; i; i = i->next, num++) { + if (num == LGUEST_MAX_DEVICES) + errx(1, "too many devices"); + verbose("Device %i: %s\n", num, + i->desc->type == LGUEST_DEVICE_T_NET ? "net" + : i->desc->type == LGUEST_DEVICE_T_CONSOLE ? "console" + : i->desc->type == LGUEST_DEVICE_T_BLOCK ? "block" + : "unknown"); + descs[num] = *i->desc; + free(i->desc); + i->desc = &descs[num]; + } +} + +static void __attribute__((noreturn)) +run_guest(int lguest_fd, struct device_list *device_list) +{ + for (;;) { + u32 args[] = { LHREQ_BREAK, 0 }; + unsigned long arr[2]; + int readval; + + /* We read from the /dev/lguest device to run the Guest. */ + readval = read(lguest_fd, arr, sizeof(arr)); + + if (readval == sizeof(arr)) { + handle_output(lguest_fd, arr[0], arr[1], device_list); + continue; + } else if (errno == ENOENT) { + char reason[1024] = { 0 }; + read(lguest_fd, reason, sizeof(reason)-1); + errx(1, "%s", reason); + } else if (errno != EAGAIN) + err(1, "Running guest failed"); + handle_input(lguest_fd, device_list); + if (write(lguest_fd, args, sizeof(args)) < 0) + err(1, "Resetting break"); + } +} + +static struct option opts[] = { + { "verbose", 0, NULL, 'v' }, + { "sharenet", 1, NULL, 's' }, + { "tunnet", 1, NULL, 't' }, + { "block", 1, NULL, 'b' }, + { "initrd", 1, NULL, 'i' }, + { NULL }, +}; +static void usage(void) +{ + errx(1, "Usage: lguest [--verbose] " + "[--sharenet=<filename>|--tunnet=(<ipaddr>|bridge:<bridgename>)\n" + "|--block=<filename>|--initrd=<filename>]...\n" + "<mem-in-mb> vmlinux [args...]"); +} + +int main(int argc, char *argv[]) +{ + unsigned long mem, pgdir, start, page_offset, initrd_size = 0; + int c, lguest_fd; + struct device_list device_list; + void *boot = (void *)0; + const char *initrd_name = NULL; + + device_list.max_infd = -1; + device_list.dev = NULL; + device_list.lastdev = &device_list.dev; + FD_ZERO(&device_list.infds); + + while ((c = getopt_long(argc, argv, "v", opts, NULL)) != EOF) { + switch (c) { + case 'v': + verbose = true; + break; + case 's': + setup_net_file(optarg, &device_list); + break; + case 't': + setup_tun_net(optarg, &device_list); + break; + case 'b': + setup_block_file(optarg, &device_list); + break; + case 'i': + initrd_name = optarg; + break; + default: + warnx("Unknown argument %s", argv[optind]); + usage(); + } + } + if (optind + 2 > argc) + usage(); + + /* We need a console device */ + setup_console(&device_list); + + /* First we map /dev/zero over all of guest-physical memory. */ + mem = atoi(argv[optind]) * 1024 * 1024; + map_zeroed_pages(0, mem / getpagesize()); + + /* Now we load the kernel */ + start = load_kernel(open_or_die(argv[optind+1], O_RDONLY), + &page_offset); + + /* Write the device descriptors into memory. */ + map_device_descriptors(&device_list, mem); + + /* Map the initrd image if requested */ + if (initrd_name) { + initrd_size = load_initrd(initrd_name, mem); + *(unsigned long *)(boot+0x218) = mem - initrd_size; + *(unsigned long *)(boot+0x21c) = initrd_size; + *(unsigned char *)(boot+0x210) = 0xFF; + } + + /* Set up the initial linar pagetables. */ + pgdir = setup_pagetables(mem, initrd_size, page_offset); + + /* E820 memory map: ours is a simple, single region. */ + *(char*)(boot+E820NR) = 1; + *((struct e820entry *)(boot+E820MAP)) + = ((struct e820entry) { 0, mem, E820_RAM }); + /* Command line pointer and command line (at 4096) */ + *(void **)(boot + 0x228) = boot + 4096; + concat(boot + 4096, argv+optind+2); + /* Paravirt type: 1 == lguest */ + *(int *)(boot + 0x23c) = 1; + + lguest_fd = tell_kernel(pgdir, start, page_offset); + waker_fd = setup_waker(lguest_fd, &device_list); + + run_guest(lguest_fd, &device_list); +} diff --git a/Documentation/lguest/lguest.txt b/Documentation/lguest/lguest.txt new file mode 100644 index 00000000000..821617bd6c0 --- /dev/null +++ b/Documentation/lguest/lguest.txt @@ -0,0 +1,129 @@ +Rusty's Remarkably Unreliable Guide to Lguest + - or, A Young Coder's Illustrated Hypervisor +http://lguest.ozlabs.org + +Lguest is designed to be a minimal hypervisor for the Linux kernel, for +Linux developers and users to experiment with virtualization with the +minimum of complexity. Nonetheless, it should have sufficient +features to make it useful for specific tasks, and, of course, you are +encouraged to fork and enhance it. + +Features: + +- Kernel module which runs in a normal kernel. +- Simple I/O model for communication. +- Simple program to create new guests. +- Logo contains cute puppies: http://lguest.ozlabs.org + +Developer features: + +- Fun to hack on. +- No ABI: being tied to a specific kernel anyway, you can change anything. +- Many opportunities for improvement or feature implementation. + +Running Lguest: + +- Lguest runs the same kernel as guest and host. You can configure + them differently, but usually it's easiest not to. + + You will need to configure your kernel with the following options: + + CONFIG_HIGHMEM64G=n ("High Memory Support" "64GB")[1] + CONFIG_TUN=y/m ("Universal TUN/TAP device driver support") + CONFIG_EXPERIMENTAL=y ("Prompt for development and/or incomplete code/drivers") + CONFIG_PARAVIRT=y ("Paravirtualization support (EXPERIMENTAL)") + CONFIG_LGUEST=y/m ("Linux hypervisor example code") + + and I recommend: + CONFIG_HZ=100 ("Timer frequency")[2] + +- A tool called "lguest" is available in this directory: type "make" + to build it. If you didn't build your kernel in-tree, use "make + O=<builddir>". + +- Create or find a root disk image. There are several useful ones + around, such as the xm-test tiny root image at + http://xm-test.xensource.com/ramdisks/initrd-1.1-i386.img + + For more serious work, I usually use a distribution ISO image and + install it under qemu, then make multiple copies: + + dd if=/dev/zero of=rootfile bs=1M count=2048 + qemu -cdrom image.iso -hda rootfile -net user -net nic -boot d + +- "modprobe lg" if you built it as a module. + +- Run an lguest as root: + + Documentation/lguest/lguest 64m vmlinux --tunnet=192.168.19.1 --block=rootfile root=/dev/lgba + + Explanation: + 64m: the amount of memory to use. + + vmlinux: the kernel image found in the top of your build directory. You + can also use a standard bzImage. + + --tunnet=192.168.19.1: configures a "tap" device for networking with this + IP address. + + --block=rootfile: a file or block device which becomes /dev/lgba + inside the guest. + + root=/dev/lgba: this (and anything else on the command line) are + kernel boot parameters. + +- Configuring networking. I usually have the host masquerade, using + "iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE" and "echo 1 > + /proc/sys/net/ipv4/ip_forward". In this example, I would configure + eth0 inside the guest at 192.168.19.2. + + Another method is to bridge the tap device to an external interface + using --tunnet=bridge:<bridgename>, and perhaps run dhcp on the guest + to obtain an IP address. The bridge needs to be configured first: + this option simply adds the tap interface to it. + + A simple example on my system: + + ifconfig eth0 0.0.0.0 + brctl addbr lg0 + ifconfig lg0 up + brctl addif lg0 eth0 + dhclient lg0 + + Then use --tunnet=bridge:lg0 when launching the guest. + + See http://linux-net.osdl.org/index.php/Bridge for general information + on how to get bridging working. + +- You can also create an inter-guest network using + "--sharenet=<filename>": any two guests using the same file are on + the same network. This file is created if it does not exist. + +Lguest I/O model: + +Lguest uses a simplified DMA model plus shared memory for I/O. Guests +can communicate with each other if they share underlying memory +(usually by the lguest program mmaping the same file), but they can +use any non-shared memory to communicate with the lguest process. + +Guests can register DMA buffers at any key (must be a valid physical +address) using the LHCALL_BIND_DMA(key, dmabufs, num<<8|irq) +hypercall. "dmabufs" is the physical address of an array of "num" +"struct lguest_dma": each contains a used_len, and an array of +physical addresses and lengths. When a transfer occurs, the +"used_len" field of one of the buffers which has used_len 0 will be +set to the length transferred and the irq will fire. + +Using an irq value of 0 unbinds the dma buffers. + +To send DMA, the LHCALL_SEND_DMA(key, dma_physaddr) hypercall is used, +and the bytes used is written to the used_len field. This can be 0 if +noone else has bound a DMA buffer to that key or some other error. +DMA buffers bound by the same guest are ignored. + +Cheers! +Rusty Russell rusty@rustcorp.com.au. + +[1] These are on various places on the TODO list, waiting for you to + get annoyed enough at the limitation to fix it. +[2] Lguest is not yet tickless when idle. See [1]. diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.txt index af1a282c71a..04dc1cf9d21 100644 --- a/Documentation/power/freezing-of-tasks.txt +++ b/Documentation/power/freezing-of-tasks.txt @@ -155,6 +155,8 @@ Suppose, however, that the firmware file is located on a filesystem accessible only through another device that hasn't been resumed yet. In that case, request_firmware() will fail regardless of whether or not the freezing of tasks is used. Consequently, the problem is not really related to the freezing of -tasks, since it generally exists anyway. [The solution to this particular -problem is to keep the firmware in memory after it's loaded for the first time -and upload if from memory to the device whenever necessary.] +tasks, since it generally exists anyway. + +A driver must have all firmwares it may need in RAM before suspend() is called. +If keeping them is not practical, for example due to their size, they must be +requested early enough using the suspend notifier API described in notifiers.txt. diff --git a/Documentation/power/notifiers.txt b/Documentation/power/notifiers.txt new file mode 100644 index 00000000000..9293e4bc857 --- /dev/null +++ b/Documentation/power/notifiers.txt @@ -0,0 +1,50 @@ +Suspend notifiers + (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL + +There are some operations that device drivers may want to carry out in their +.suspend() routines, but shouldn't, because they can cause the hibernation or +suspend to fail. For example, a driver may want to allocate a substantial amount +of memory (like 50 MB) in .suspend(), but that shouldn't be done after the +swsusp's memory shrinker has run. + +Also, there may be some operations, that subsystems want to carry out before a +hibernation/suspend or after a restore/resume, requiring the system to be fully +functional, so the drivers' .suspend() and .resume() routines are not suitable +for this purpose. For example, device drivers may want to upload firmware to +their devices after a restore from a hibernation image, but they cannot do it by +calling request_firmware() from their .resume() routines (user land processes +are frozen at this point). The solution may be to load the firmware into +memory before processes are frozen and upload it from there in the .resume() +routine. Of course, a hibernation notifier may be used for this purpose. + +The subsystems that have such needs can register suspend notifiers that will be +called upon the following events by the suspend core: + +PM_HIBERNATION_PREPARE The system is going to hibernate or suspend, tasks will + be frozen immediately. + +PM_POST_HIBERNATION The system memory state has been restored from a + hibernation image or an error occured during the + hibernation. Device drivers' .resume() callbacks have + been executed and tasks have been thawed. + +PM_SUSPEND_PREPARE The system is preparing for a suspend. + +PM_POST_SUSPEND The system has just resumed or an error occured during + the suspend. Device drivers' .resume() callbacks have + been executed and tasks have been thawed. + +It is generally assumed that whatever the notifiers do for +PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously, +operations performed for PM_SUSPEND_PREPARE should be reversed for +PM_POST_SUSPEND. Additionally, all of the notifiers are called for +PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and +all of the notifiers are called for PM_POST_SUSPEND if one of them fails for +PM_SUSPEND_PREPARE. + +The hibernation and suspend notifiers are called with pm_mutex held. They are +defined in the usual way, but their last argument is meaningless (it is always +NULL). To register and/or unregister a suspend notifier use the functions +register_pm_notifier() and unregister_pm_notifier(), respectively, defined in +include/linux/suspend.h . If you don't need to unregister the notifier, you can +also use the pm_notifier() macro defined in include/linux/suspend.h . diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index 0c243482209..76733a3962f 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -1250,6 +1250,12 @@ platforms are moved over to use the flattened-device-tree model. network device. This is used by the bootwrapper to interpret MAC addresses passed by the firmware when no information other than indices is available to associate an address with a device. + - phy-connection-type : a string naming the controller/PHY interface type, + i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii", + "tbi", or "rtbi". This property is only really needed if the connection + is of type "rgmii-id", as all other connection types are detected by + hardware. + Example: diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 355ff0a2bb7..241e26c4ff9 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -467,7 +467,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. above explicitly. The power-management is supported. - + + Module snd-cs5530 + _________________ + + Module for Cyrix/NatSemi Geode 5530 chip. + Module snd-cs5535audio ---------------------- @@ -759,6 +764,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. model - force the model name position_fix - Fix DMA pointer (0 = auto, 1 = none, 2 = POSBUF, 3 = FIFO size) + probe_mask - Bitmask to probe codecs (default = -1, meaning all slots) single_cmd - Use single immediate commands to communicate with codecs (for debugging only) enable_msi - Enable Message Signaled Interrupt (MSI) (default = off) @@ -803,6 +809,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. hp-3013 HP machines (3013-variant) fujitsu Fujitsu S7020 acer Acer TravelMate + will Will laptops (PB V7900) + replacer Replacer 672V basic fixed pin assignment (old default model) auto auto-config reading BIOS (default) @@ -811,16 +819,31 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. hp-bpc HP xw4400/6400/8400/9400 laptops hp-bpc-d7000 HP BPC D7000 benq Benq ED8 + benq-t31 Benq T31 hippo Hippo (ATI) with jack detection, Sony UX-90s hippo_1 Hippo (Benq) with jack detection + sony-assamd Sony ASSAMD basic fixed pin assignment w/o SPDIF auto auto-config reading BIOS (default) + ALC268 + 3stack 3-stack model + auto auto-config reading BIOS (default) + + ALC662 + 3stack-dig 3-stack (2-channel) with SPDIF + 3stack-6ch 3-stack (6-channel) + 3stack-6ch-dig 3-stack (6-channel) with SPDIF + 6stack-dig 6-stack with SPDIF + lenovo-101e Lenovo laptop + auto auto-config reading BIOS (default) + ALC882/885 3stack-dig 3-jack with SPDIF I/O 6stack-dig 6-jack digital with SPDIF I/O arima Arima W820Di1 macpro MacPro support + imac24 iMac 24'' with jack detection w2jc ASUS W2JC auto auto-config reading BIOS (default) @@ -832,9 +855,15 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 6stack-dig-demo 6-jack digital for Intel demo board acer Acer laptops (Travelmate 3012WTMi, Aspire 5600, etc) medion Medion Laptops + medion-md2 Medion MD2 targa-dig Targa/MSI targa-2ch-dig Targs/MSI with 2-channel laptop-eapd 3-jack with SPDIF I/O and EAPD (Clevo M540JE, M550JE) + lenovo-101e Lenovo 101E + lenovo-nb0763 Lenovo NB0763 + lenovo-ms7195-dig Lenovo MS7195 + 6stack-hp HP machines with 6stack (Nettle boards) + 3stack-hp HP machines with 3stack (Lucknow, Samba boards) auto auto-config reading BIOS (default) ALC861/660 @@ -853,7 +882,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 3stack-dig 3-jack with SPDIF OUT 6stack-dig 6-jack with SPDIF OUT 3stack-660 3-jack (for ALC660VD) + 3stack-660-digout 3-jack with SPDIF OUT (for ALC660VD) lenovo Lenovo 3000 C200 + dallas Dallas laptops auto auto-config reading BIOS (default) CMI9880 @@ -864,12 +895,26 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. allout 5-jack in back, 2-jack in front, SPDIF out auto auto-config reading BIOS (default) + AD1882 + 3stack 3-stack mode (default) + 6stack 6-stack mode + + AD1884 + N/A + AD1981 basic 3-jack (default) hp HP nx6320 thinkpad Lenovo Thinkpad T60/X60/Z60 toshiba Toshiba U205 + AD1983 + N/A + + AD1984 + basic default configuration + thinkpad Lenovo Thinkpad T61/X61 + AD1986A 6stack 6-jack, separate surrounds (default) 3stack 3-stack, shared surrounds @@ -907,11 +952,18 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. ref Reference board 3stack D945 3stack 5stack D945 5stack + SPDIF - macmini Intel Mac Mini - macbook Intel Mac Book - macbook-pro-v1 Intel Mac Book Pro 1st generation - macbook-pro Intel Mac Book Pro 2nd generation - imac-intel Intel iMac + dell Dell XPS M1210 + intel-mac-v1 Intel Mac Type 1 + intel-mac-v2 Intel Mac Type 2 + intel-mac-v3 Intel Mac Type 3 + intel-mac-v4 Intel Mac Type 4 + intel-mac-v5 Intel Mac Type 5 + macmini Intel Mac Mini (equivalent with type 3) + macbook Intel Mac Book (eq. type 5) + macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3) + macbook-pro Intel Mac Book Pro 2nd generation (eq. type 3) + imac-intel Intel iMac (eq. type 2) + imac-intel-20 Intel iMac (newer version) (eq. type 3) STAC9202/9250/9251 ref Reference board, base config @@ -956,6 +1008,17 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. from the irq. Remember this is a last resort, and should be avoided as much as possible... + MORE NOTES ON "azx_get_response timeout" PROBLEMS: + On some hardwares, you may need to add a proper probe_mask option + to avoid the "azx_get_response timeout" problem above, instead. + This occurs when the access to non-existing or non-working codec slot + (likely a modem one) causes a stall of the communication via HD-audio + bus. You can see which codec slots are probed by enabling + CONFIG_SND_DEBUG_DETECT, or simply from the file name of the codec + proc files. Then limit the slots to probe by probe_mask option. + For example, probe_mask=1 means to probe only the first slot, and + probe_mask=4 means only the third slot. + The power-management is supported. Module snd-hdsp diff --git a/Documentation/sound/alsa/Audiophile-Usb.txt b/Documentation/sound/alsa/Audiophile-Usb.txt index e40cce83327..2ad5e6306c4 100644 --- a/Documentation/sound/alsa/Audiophile-Usb.txt +++ b/Documentation/sound/alsa/Audiophile-Usb.txt @@ -1,4 +1,4 @@ - Guide to using M-Audio Audiophile USB with ALSA and Jack v1.3 + Guide to using M-Audio Audiophile USB with ALSA and Jack v1.5 ======================================================== Thibault Le Meur <Thibault.LeMeur@supelec.fr> @@ -6,8 +6,19 @@ This document is a guide to using the M-Audio Audiophile USB (tm) device with ALSA and JACK. +History +======= +* v1.4 - Thibault Le Meur (2007-07-11) + - Added Low Endianness nature of 16bits-modes + found by Hakan Lennestal <Hakan.Lennestal@brfsodrahamn.se> + - Modifying document structure +* v1.5 - Thibault Le Meur (2007-07-12) + - Added AC3/DTS passthru info + + 1 - Audiophile USB Specs and correct usage ========================================== + This part is a reminder of important facts about the functions and limitations of the device. @@ -25,18 +36,18 @@ The device has 4 audio interfaces, and 2 MIDI ports: The internal DAC/ADC has the following characteristics: * sample depth of 16 or 24 bits * sample rate from 8kHz to 96kHz -* Two ports can't use different sample depths at the same time. Moreover, the -Audiophile USB documentation gives the following Warning: "Please exit any -audio application running before switching between bit depths" +* Two interfaces can't use different sample depths at the same time. +Moreover, the Audiophile USB documentation gives the following Warning: +"Please exit any audio application running before switching between bit depths" Due to the USB 1.1 bandwidth limitation, a limited number of interfaces can be activated at the same time depending on the audio mode selected: - * 16-bit/48kHz ==> 4 channels in/4 channels out + * 16-bit/48kHz ==> 4 channels in + 4 channels out - Ai+Ao+Di+Do - * 24-bit/48kHz ==> 4 channels in/2 channels out, - or 2 channels in/4 channels out + * 24-bit/48kHz ==> 4 channels in + 2 channels out, + or 2 channels in + 4 channels out - Ai+Ao+Do or Ai+Di+Ao or Ai+Di+Do or Di+Ao+Do - * 24-bit/96kHz ==> 2 channels in, or 2 channels out (half duplex only) + * 24-bit/96kHz ==> 2 channels in _or_ 2 channels out (half duplex only) - Ai or Ao or Di or Do Important facts about the Digital interface: @@ -52,44 +63,56 @@ source is connected synchronization error (for instance sound played at an odd sample rate) -2 - Audiophile USB support in ALSA -================================== +2 - Audiophile USB MIDI support in ALSA +======================================= -2.1 - MIDI ports ----------------- -The Audiophile USB MIDI ports will be automatically supported once the +The Audiophile USB MIDI ports will be automatically supported once the following modules have been loaded: * snd-usb-audio * snd-seq-midi No additional setting is required. -2.2 - Audio ports ------------------ + +3 - Audiophile USB Audio support in ALSA +======================================== Audio functions of the Audiophile USB device are handled by the snd-usb-audio module. This module can work in a default mode (without any device-specific parameter), or in an "advanced" mode with the device-specific parameter called "device_setup". -2.2.1 - Default Alsa driver mode - -The default behavior of the snd-usb-audio driver is to parse the device -capabilities at startup and enable all functions inside the device (including -all ports at any supported sample rates and sample depths). This approach -has the advantage to let the driver easily switch from sample rates/depths -automatically according to the need of the application claiming the device. - -In this case the Audiophile ports are mapped to alsa pcm devices in the -following way (I suppose the device's index is 1): +3.1 - Default Alsa driver mode +------------------------------ + +The default behavior of the snd-usb-audio driver is to list the device +capabilities at startup and activate the required mode when required +by the applications: for instance if the user is recording in a +24bit-depth-mode and immediately after wants to switch to a 16bit-depth mode, +the snd-usb-audio module will reconfigure the device on the fly. + +This approach has the advantage to let the driver automatically switch from sample +rates/depths automatically according to the user's needs. However, those who +are using the device under windows know that this is not how the device is meant to +work: under windows applications must be closed before using the m-audio control +panel to switch the device working mode. Thus as we'll see in next section, this +Default Alsa driver mode can lead to device misconfigurations. + +Let's get back to the Default Alsa driver mode for now. In this case the +Audiophile interfaces are mapped to alsa pcm devices in the following +way (I suppose the device's index is 1): * hw:1,0 is Ao in playback and Di in capture * hw:1,1 is Do in playback and Ai in capture * hw:1,2 is Do in AC3/DTS passthrough mode -You must note as well that the device uses Big Endian byte encoding so that -supported audio format are S16_BE for 16-bit depth modes and S24_3BE for -24-bits depth mode. One exception is the hw:1,2 port which is Little Endian -compliant and thus uses S16_LE. +In this mode, the device uses Big Endian byte-encoding so that +supported audio format are S16_BE for 16-bit depth modes and S24_3BE for +24-bits depth mode. + +One exception is the hw:1,2 port which was reported to be Little Endian +compliant (supposedly supporting S16_LE) but processes in fact only S16_BE streams. +This has been fixed in kernel 2.6.23 and above and now the hw:1,2 interface +is reported to be big endian in this default driver mode. Examples: * playing a S24_3BE encoded raw file to the Ao port @@ -98,22 +121,26 @@ Examples: % arecord -D hw:1,1 -c2 -t raw -r48000 -fS24_3BE test.raw * playing a S16_BE encoded raw file to the Do port % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test.raw + * playing an ac3 sample file to the Do port + % aplay -D hw:1,2 --channels=6 ac3_S16_BE_encoded_file.raw -If you're happy with the default Alsa driver setup and don't experience any +If you're happy with the default Alsa driver mode and don't experience any issue with this mode, then you can skip the following chapter. -2.2.2 - Advanced module setup +3.2 - Advanced module setup +--------------------------- Due to the hardware constraints described above, the device initialization made by the Alsa driver in default mode may result in a corrupted state of the device. For instance, a particularly annoying issue is that the sound captured -from the Ai port sounds distorted (as if boosted with an excessive high volume -gain). +from the Ai interface sounds distorted (as if boosted with an excessive high +volume gain). For people having this problem, the snd-usb-audio module has a new module -parameter called "device_setup". +parameter called "device_setup" (this parameter was introduced in kernel +release 2.6.17) -2.2.2.1 - Initializing the working mode of the Audiophile USB +3.2.1 - Initializing the working mode of the Audiophile USB As far as the Audiophile USB device is concerned, this value let the user specify: @@ -121,33 +148,57 @@ specify: * the sample rate * whether the Di port is used or not -Here is a list of supported device_setup values for this device: - * device_setup=0x00 (or omitted) - - Alsa driver default mode - - maintains backward compatibility with setups that do not use this - parameter by not introducing any change - - results sometimes in corrupted sound as described earlier +When initialized with "device_setup=0x00", the snd-usb-audio module has +the same behaviour as when the parameter is omitted (see paragraph "Default +Alsa driver mode" above) + +Others modes are described in the following subsections. + +3.2.1.1 - 16-bit modes + +The two supported modes are: + * device_setup=0x01 - 16bits 48kHz mode with Di disabled - Ai,Ao,Do can be used at the same time - hw:1,0 is not available in capture mode - hw:1,2 is not available + * device_setup=0x11 - 16bits 48kHz mode with Di enabled - Ai,Ao,Di,Do can be used at the same time - hw:1,0 is available in capture mode - hw:1,2 is not available + +In this modes the device operates only at 16bits-modes. Before kernel 2.6.23, +the devices where reported to be Big-Endian when in fact they were Little-Endian +so that playing a file was a matter of using: + % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test_S16_LE.raw +where "test_S16_LE.raw" was in fact a little-endian sample file. + +Thanks to Hakan Lennestal (who discovered the Little-Endiannes of the device in +these modes) a fix has been committed (expected in kernel 2.6.23) and +Alsa now reports Little-Endian interfaces. Thus playing a file now is as simple as +using: + % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_LE test_S16_LE.raw + +3.2.1.2 - 24-bit modes + +The three supported modes are: + * device_setup=0x09 - 24bits 48kHz mode with Di disabled - Ai,Ao,Do can be used at the same time - hw:1,0 is not available in capture mode - hw:1,2 is not available + * device_setup=0x19 - 24bits 48kHz mode with Di enabled - 3 ports from {Ai,Ao,Di,Do} can be used at the same time - hw:1,0 is available in capture mode and an active digital source must be connected to Di - hw:1,2 is not available + * device_setup=0x0D or 0x10 - 24bits 96kHz mode - Di is enabled by default for this mode but does not need to be connected @@ -155,34 +206,64 @@ Here is a list of supported device_setup values for this device: - Only 1 port from {Ai,Ao,Di,Do} can be used at the same time - hw:1,0 is available in captured mode - hw:1,2 is not available + +In these modes the device is only Big-Endian compliant (see "Default Alsa driver +mode" above for an aplay command example) + +3.2.1.3 - AC3 w/ DTS passthru mode + +Thanks to Hakan Lennestal, I now have a report saying that this mode works. + * device_setup=0x03 - 16bits 48kHz mode with only the Do port enabled - - AC3 with DTS passthru (not tested) + - AC3 with DTS passthru - Caution with this setup the Do port is mapped to the pcm device hw:1,0 -2.2.2.2 - Setting and switching configurations with the device_setup parameter +The command line used to playback the AC3/DTS encoded .wav-files in this mode: + % aplay -D hw:1,0 --channels=6 ac3_S16_LE_encoded_file.raw + +3.2.2 - How to use the device_setup parameter +---------------------------------------------- The parameter can be given: + * By manually probing the device (as root): # modprobe -r snd-usb-audio # modprobe snd-usb-audio index=1 device_setup=0x09 + * Or while configuring the modules options in your modules configuration file - For Fedora distributions, edit the /etc/modprobe.conf file: alias snd-card-1 snd-usb-audio options snd-usb-audio index=1 device_setup=0x09 -IMPORTANT NOTE WHEN SWITCHING CONFIGURATION: -------------------------------------------- - * You may need to _first_ initialize the module with the correct device_setup - parameter and _only_after_ turn on the Audiophile USB device - * This is especially true when switching the sample depth: +CAUTION when initializaing the device +------------------------------------- + + * Correct initialization on the device requires that device_setup is given to + the module BEFORE the device is turned on. So, if you use the "manual probing" + method described above, take care to power-on the device AFTER this initialization. + + * Failing to respect this will lead in a misconfiguration of the device. In this case + turn off the device, unproble the snd-usb-audio module, then probe it again with + correct device_setup parameter and then (and only then) turn on the device again. + + * If you've correctly initialized the device in a valid mode and then want to switch + to another mode (possibly with another sample-depth), please use also the following + procedure: - first turn off the device - de-register the snd-usb-audio module (modprobe -r) - change the device_setup parameter by changing the device_setup option in /etc/modprobe.conf - turn on the device + * A workaround for this last issue has been applied to kernel 2.6.23, but it may not + be enough to ensure the 'stability' of the device initialization. -2.2.2.3 - Audiophile USB's device_setup structure +3.2.3 - Technical details for hackers +------------------------------------- +This section is for hackers, wanting to understand details about the device +internals and how Alsa supports it. + +3.2.3.1 - Audiophile USB's device_setup structure If you want to understand the device_setup magic numbers for the Audiophile USB, you need some very basic understanding of binary computation. However, @@ -228,12 +309,12 @@ Caution: - choosing b2 will prepare all interfaces for 24bits/96kHz but you'll only be able to use one at the same time -2.2.3 - USB implementation details for this device +3.2.3.2 - USB implementation details for this device You may safely skip this section if you're not interested in driver -development. +hacking. -This section describes some internal aspects of the device and summarize the +This section describes some internal aspects of the device and summarizes the data I got by usb-snooping the windows and Linux drivers. The M-Audio Audiophile USB has 7 USB Interfaces: @@ -293,43 +374,45 @@ parse_audio_endpoints function uses a quirk called "audiophile_skip_setting_quirk" in order to prevent AltSettings not corresponding to device_setup from being registered in the driver. -3 - Audiophile USB and Jack support +4 - Audiophile USB and Jack support =================================== This section deals with support of the Audiophile USB device in Jack. -The main issue regarding this support is that the device is Big Endian -compliant. -3.1 - Using the plug alsa plugin --------------------------------- +There are 2 main potential issues when using Jackd with the device: +* support for Big-Endian devices in 24-bit modes +* support for 4-in / 4-out channels + +4.1 - Direct support in Jackd +----------------------------- -Jack doesn't directly support big endian devices. Thus, one way to have support -for this device with Alsa is to use the Alsa "plug" converter. +Jack supports big endian devices only in recent versions (thanks to +Andreas Steinmetz for his first big-endian patch). I can't remember +extacly when this support was released into jackd, let's just say that +with jackd version 0.103.0 it's almost ok (just a small bug is affecting +16bits Big-Endian devices, but since you've read carefully the above +paragraphs, you're now using kernel >= 2.6.23 and your 16bits devices +are now Little Endians ;-) ). + +You can run jackd with the following command for playback with Ao and +record with Ai: + % jackd -R -dalsa -Phw:1,0 -r48000 -p128 -n2 -D -Chw:1,1 + +4.2 - Using Alsa plughw +----------------------- +If you don't have a recent Jackd installed, you can downgrade to using +the Alsa "plug" converter. For instance here is one way to run Jack with 2 playback channels on Ao and 2 capture channels from Ai: % jackd -R -dalsa -dplughw:1 -r48000 -p256 -n2 -D -Cplughw:1,1 - However you may see the following warning message: "You appear to be using the ALSA software "plug" layer, probably a result of using the "default" ALSA device. This is less efficient than it could be. Consider using a hardware device instead rather than using the plug layer." -3.2 - Patching alsa to use direct pcm device --------------------------------------------- -A patch for Jack by Andreas Steinmetz adds support for Big Endian devices. -However it has not been included in the CVS tree. - -You can find it at the following URL: -http://sourceforge.net/tracker/index.php?func=detail&aid=1289682&group_id=39687& -atid=425939 - -After having applied the patch you can run jackd with the following command -line: - % jackd -R -dalsa -Phw:1,0 -r48000 -p128 -n2 -D -Chw:1,1 - -3.2 - Getting 2 input and/or output interfaces in Jack +4.3 - Getting 2 input and/or output interfaces in Jack ------------------------------------------------------ As you can see, starting the Jack server this way will only enable 1 stereo @@ -339,6 +422,7 @@ This is due to the following restrictions: * Jack can only open one capture device and one playback device at a time * The Audiophile USB is seen as 2 (or three) Alsa devices: hw:1,0, hw:1,1 (and optionally hw:1,2) + If you want to get Ai+Di and/or Ao+Do support with Jack, you would need to combine the Alsa devices into one logical "complex" device. @@ -348,13 +432,11 @@ It is related to another device (ice1712) but can be adapted to suit the Audiophile USB. Enabling multiple Audiophile USB interfaces for Jackd will certainly require: -* patching Jack with the previously mentioned "Big Endian" patch -* patching Jackd with the MMAP_COMPLEX patch (see the ice1712 page) -* patching the alsa-lib/src/pcm/pcm_multi.c file (see the ice1712 page) +* Making sure your Jackd version has the MMAP_COMPLEX patch (see the ice1712 page) +* (maybe) patching the alsa-lib/src/pcm/pcm_multi.c file (see the ice1712 page) * define a multi device (combination of hw:1,0 and hw:1,1) in your .asoundrc file * start jackd with this device -I had no success in testing this for now, but this may be due to my OS -configuration. If you have any success with this kind of setup, please -drop me an email. +I had no success in testing this for now, if you have any success with this kind +of setup, please drop me an email. diff --git a/Documentation/sound/alsa/OSS-Emulation.txt b/Documentation/sound/alsa/OSS-Emulation.txt index ec2a02541d5..bfa0c9aacb4 100644 --- a/Documentation/sound/alsa/OSS-Emulation.txt +++ b/Documentation/sound/alsa/OSS-Emulation.txt @@ -278,6 +278,21 @@ current mixer configuration by reading and writing the whole file image. +Duplex Streams +============== + +Note that when attempting to use a single device file for playback and +capture, the OSS API provides no way to set the format, sample rate or +number of channels different in each direction. Thus + io_handle = open("device", O_RDWR) +will only function correctly if the values are the same in each direction. + +To use different values in the two directions, use both + input_handle = open("device", O_RDONLY) + output_handle = open("device", O_WRONLY) +and set the values for the corresponding handle. + + Unsupported Features ==================== diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt index 9e6b94face4..6711fbcf408 100644 --- a/Documentation/thinkpad-acpi.txt +++ b/Documentation/thinkpad-acpi.txt @@ -1,11 +1,11 @@ ThinkPad ACPI Extras Driver - Version 0.14 - April 21st, 2007 + Version 0.15 + July 1st, 2007 Borislav Deianov <borislav@users.sf.net> - Henrique de Moraes Holschuh <hmh@hmh.eng.br> - http://ibm-acpi.sf.net/ + Henrique de Moraes Holschuh <hmh@hmh.eng.br> + http://ibm-acpi.sf.net/ This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It @@ -134,54 +134,68 @@ end of this document. Changes to the sysfs interface done by the kernel subsystems are not documented here, nor are they tracked by this attribute. +Changes to the thinkpad-acpi sysfs interface are only considered +non-experimental when they are submitted to Linux mainline, at which +point the changes in this interface are documented and interface_version +may be updated. If you are using any thinkpad-acpi features not yet +sent to mainline for merging, you do so on your own risk: these features +may disappear, or be implemented in a different and incompatible way by +the time they are merged in Linux mainline. + +Changes that are backwards-compatible by nature (e.g. the addition of +attributes that do not change the way the other attributes work) do not +always warrant an update of interface_version. Therefore, one must +expect that an attribute might not be there, and deal with it properly +(an attribute not being there *is* a valid way to make it clear that a +feature is not available in sysfs). + Hot keys -------- procfs: /proc/acpi/ibm/hotkey sysfs device attribute: hotkey_* -Without this driver, only the Fn-F4 key (sleep button) generates an -ACPI event. With the driver loaded, the hotkey feature enabled and the -mask set (see below), the various hot keys generate ACPI events in the +In a ThinkPad, the ACPI HKEY handler is responsible for comunicating +some important events and also keyboard hot key presses to the operating +system. Enabling the hotkey functionality of thinkpad-acpi signals the +firmware that such a driver is present, and modifies how the ThinkPad +firmware will behave in many situations. + +When the hotkey feature is enabled and the hot key mask is set (see +below), the various hot keys either generate ACPI events in the following format: ibm/hotkey HKEY 00000080 0000xxxx -The last four digits vary depending on the key combination pressed. -All labeled Fn-Fx key combinations generate distinct events. In -addition, the lid microswitch and some docking station buttons may -also generate such events. - -The bit mask allows some control over which hot keys generate ACPI -events. Not all bits in the mask can be modified. Not all bits that -can be modified do anything. Not all hot keys can be individually -controlled by the mask. Most recent ThinkPad models honor the -following bits (assuming the hot keys feature has been enabled): - - key bit behavior when set behavior when unset - - Fn-F3 always generates ACPI event - Fn-F4 always generates ACPI event - Fn-F5 0010 generate ACPI event enable/disable Bluetooth - Fn-F7 0040 generate ACPI event switch LCD and external display - Fn-F8 0080 generate ACPI event expand screen or none - Fn-F9 0100 generate ACPI event none - Fn-F12 always generates ACPI event - -Some models do not support all of the above. For example, the T30 does -not support Fn-F5 and Fn-F9. Other models do not support the mask at -all. On those models, hot keys cannot be controlled individually. - -Note that enabling ACPI events for some keys prevents their default -behavior. For example, if events for Fn-F5 are enabled, that key will -no longer enable/disable Bluetooth by itself. This can still be done -from an acpid handler for the ibm/hotkey event. - -Note also that not all Fn key combinations are supported through -ACPI. For example, on the X40, the brightness, volume and "Access IBM" -buttons do not generate ACPI events even with this driver. They *can* -be used through the "ThinkPad Buttons" utility, see -http://www.nongnu.org/tpb/ +or events over the input layer. The input layer support accepts the +standard IOCTLs to remap the keycodes assigned to each hotkey. + +When the input device is open, the driver will suppress any ACPI hot key +events that get translated into a meaningful input layer event, in order +to avoid sending duplicate events to userspace. Hot keys that are +mapped to KEY_RESERVED in the keymap are not translated, and will always +generate an ACPI ibm/hotkey HKEY event, and no input layer events. + +The hot key bit mask allows some control over which hot keys generate +events. If a key is "masked" (bit set to 0 in the mask), the firmware +will handle it. If it is "unmasked", it signals the firmware that +thinkpad-acpi would prefer to handle it, if the firmware would be so +kind to allow it (and it often doesn't!). + +Not all bits in the mask can be modified. Not all bits that can be +modified do anything. Not all hot keys can be individually controlled +by the mask. Some models do not support the mask at all, and in those +models, hot keys cannot be controlled individually. The behaviour of +the mask is, therefore, higly dependent on the ThinkPad model. + +Note that unmasking some keys prevents their default behavior. For +example, if Fn+F5 is unmasked, that key will no longer enable/disable +Bluetooth by itself. + +Note also that not all Fn key combinations are supported through ACPI. +For example, on the X40, the brightness, volume and "Access IBM" buttons +do not generate ACPI events even with this driver. They *can* be used +through the "ThinkPad Buttons" utility, see http://www.nongnu.org/tpb/ procfs notes: @@ -189,9 +203,9 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file: echo enable > /proc/acpi/ibm/hotkey -- enable the hot keys feature echo disable > /proc/acpi/ibm/hotkey -- disable the hot keys feature - echo 0xffff > /proc/acpi/ibm/hotkey -- enable all possible hot keys - echo 0x0000 > /proc/acpi/ibm/hotkey -- disable all possible hot keys - ... any other 4-hex-digit mask ... + echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys + echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys + ... any other 8-hex-digit mask ... echo reset > /proc/acpi/ibm/hotkey -- restore the original mask sysfs notes: @@ -202,7 +216,7 @@ sysfs notes: key feature status will be restored to this value. 0: hot keys were disabled - 1: hot keys were enabled + 1: hot keys were enabled (unusual) hotkey_bios_mask: Returns the hot keys mask when thinkpad-acpi was loaded. @@ -217,9 +231,182 @@ sysfs notes: 1: enables the hot keys feature / feature enabled hotkey_mask: - bit mask to enable ACPI event generation for each hot - key (see above). Returns the current status of the hot - keys mask, and allows one to modify it. + bit mask to enable driver-handling and ACPI event + generation for each hot key (see above). Returns the + current status of the hot keys mask, and allows one to + modify it. + + hotkey_all_mask: + bit mask that should enable event reporting for all + supported hot keys, when echoed to hotkey_mask above. + Unless you know which events need to be handled + passively (because the firmware *will* handle them + anyway), do *not* use hotkey_all_mask. Use + hotkey_recommended_mask, instead. You have been warned. + + hotkey_recommended_mask: + bit mask that should enable event reporting for all + supported hot keys, except those which are always + handled by the firmware anyway. Echo it to + hotkey_mask above, to use. + + hotkey_radio_sw: + if the ThinkPad has a hardware radio switch, this + attribute will read 0 if the switch is in the "radios + disabled" postition, and 1 if the switch is in the + "radios enabled" position. + +input layer notes: + +A Hot key is mapped to a single input layer EV_KEY event, possibly +followed by an EV_MSC MSC_SCAN event that shall contain that key's scan +code. An EV_SYN event will always be generated to mark the end of the +event block. + +Do not use the EV_MSC MSC_SCAN events to process keys. They are to be +used as a helper to remap keys, only. They are particularly useful when +remapping KEY_UNKNOWN keys. + +The events are available in an input device, with the following id: + + Bus: BUS_HOST + vendor: 0x1014 (PCI_VENDOR_ID_IBM) or + 0x17aa (PCI_VENDOR_ID_LENOVO) + product: 0x5054 ("TP") + version: 0x4101 + +The version will have its LSB incremented if the keymap changes in a +backwards-compatible way. The MSB shall always be 0x41 for this input +device. If the MSB is not 0x41, do not use the device as described in +this section, as it is either something else (e.g. another input device +exported by a thinkpad driver, such as HDAPS) or its functionality has +been changed in a non-backwards compatible way. + +Adding other event types for other functionalities shall be considered a +backwards-compatible change for this input device. + +Thinkpad-acpi Hot Key event map (version 0x4101): + +ACPI Scan +event code Key Notes + +0x1001 0x00 FN+F1 - +0x1002 0x01 FN+F2 IBM: battery (rare) + Lenovo: Screen lock + +0x1003 0x02 FN+F3 Many IBM models always report + this hot key, even with hot keys + disabled or with Fn+F3 masked + off + IBM: screen lock + Lenovo: battery + +0x1004 0x03 FN+F4 Sleep button (ACPI sleep button + semanthics, i.e. sleep-to-RAM). + It is always generate some kind + of event, either the hot key + event or a ACPI sleep button + event. The firmware may + refuse to generate further FN+F4 + key presses until a S3 or S4 ACPI + sleep cycle is performed or some + time passes. + +0x1005 0x04 FN+F5 Radio. Enables/disables + the internal BlueTooth hardware + and W-WAN card if left in control + of the firmware. Does not affect + the WLAN card. + Should be used to turn on/off all + radios (bluetooth+W-WAN+WLAN), + really. + +0x1006 0x05 FN+F6 - + +0x1007 0x06 FN+F7 Video output cycle. + Do you feel lucky today? + +0x1008 0x07 FN+F8 IBM: toggle screen expand + Lenovo: configure ultranav + +0x1009 0x08 FN+F9 - + .. .. .. +0x100B 0x0A FN+F11 - + +0x100C 0x0B FN+F12 Sleep to disk. You are always + supposed to handle it yourself, + either through the ACPI event, + or through a hotkey event. + The firmware may refuse to + generate further FN+F4 key + press events until a S3 or S4 + ACPI sleep cycle is performed, + or some time passes. + +0x100D 0x0C FN+BACKSPACE - +0x100E 0x0D FN+INSERT - +0x100F 0x0E FN+DELETE - + +0x1010 0x0F FN+HOME Brightness up. This key is + always handled by the firmware + in IBM ThinkPads, even when + unmasked. Just leave it alone. + For Lenovo ThinkPads with a new + BIOS, it has to be handled either + by the ACPI OSI, or by userspace. +0x1011 0x10 FN+END Brightness down. See brightness + up for details. + +0x1012 0x11 FN+PGUP Thinklight toggle. This key is + always handled by the firmware, + even when unmasked. + +0x1013 0x12 FN+PGDOWN - + +0x1014 0x13 FN+SPACE Zoom key + +0x1015 0x14 VOLUME UP Internal mixer volume up. This + key is always handled by the + firmware, even when unmasked. + NOTE: Lenovo seems to be changing + this. +0x1016 0x15 VOLUME DOWN Internal mixer volume up. This + key is always handled by the + firmware, even when unmasked. + NOTE: Lenovo seems to be changing + this. +0x1017 0x16 MUTE Mute internal mixer. This + key is always handled by the + firmware, even when unmasked. + +0x1018 0x17 THINKPAD Thinkpad/Access IBM/Lenovo key + +0x1019 0x18 unknown +.. .. .. +0x1020 0x1F unknown + +The ThinkPad firmware does not allow one to differentiate when most hot +keys are pressed or released (either that, or we don't know how to, yet). +For these keys, the driver generates a set of events for a key press and +immediately issues the same set of events for a key release. It is +unknown by the driver if the ThinkPad firmware triggered these events on +hot key press or release, but the firmware will do it for either one, not +both. + +If a key is mapped to KEY_RESERVED, it generates no input events at all, +and it may generate a legacy thinkpad-acpi ACPI hotkey event. + +If a key is mapped to KEY_UNKNOWN, it generates an input event that +includes an scan code, and it may also generate a legacy thinkpad-acpi +ACPI hotkey event. + +If a key is mapped to anything else, it will only generate legacy +thinkpad-acpi ACPI hotkey events if nobody has opened the input device. + +Non hot-key ACPI HKEY event map: +0x5001 Lid closed +0x5002 Lid opened +0x7000 Radio Switch may have changed state Bluetooth @@ -437,27 +624,34 @@ CMOS control procfs: /proc/acpi/ibm/cmos sysfs device attribute: cmos_command -This feature is used internally by the ACPI firmware to control the -ThinkLight on most newer ThinkPad models. It may also control LCD -brightness, sounds volume and more, but only on some models. +This feature is mostly used internally by the ACPI firmware to keep the legacy +CMOS NVRAM bits in sync with the current machine state, and to record this +state so that the ThinkPad will retain such settings across reboots. + +Some of these commands actually perform actions in some ThinkPad models, but +this is expected to disappear more and more in newer models. As an example, in +a T43 and in a X40, commands 12 and 13 still control the ThinkLight state for +real, but commands 0 to 2 don't control the mixer anymore (they have been +phased out) and just update the NVRAM. The range of valid cmos command numbers is 0 to 21, but not all have an effect and the behavior varies from model to model. Here is the behavior on the X40 (tpb is the ThinkPad Buttons utility): - 0 - no effect but tpb reports "Volume down" - 1 - no effect but tpb reports "Volume up" - 2 - no effect but tpb reports "Mute on" - 3 - simulate pressing the "Access IBM" button - 4 - LCD brightness up - 5 - LCD brightness down - 11 - toggle screen expansion - 12 - ThinkLight on - 13 - ThinkLight off - 14 - no effect but tpb reports ThinkLight status change + 0 - Related to "Volume down" key press + 1 - Related to "Volume up" key press + 2 - Related to "Mute on" key press + 3 - Related to "Access IBM" key press + 4 - Related to "LCD brightness up" key pess + 5 - Related to "LCD brightness down" key press + 11 - Related to "toggle screen expansion" key press/function + 12 - Related to "ThinkLight on" + 13 - Related to "ThinkLight off" + 14 - Related to "ThinkLight" key press (toggle thinklight) The cmos command interface is prone to firmware split-brain problems, as -in newer ThinkPads it is just a compatibility layer. +in newer ThinkPads it is just a compatibility layer. Do not use it, it is +exported just as a debug tool. LED control -- /proc/acpi/ibm/led --------------------------------- @@ -516,23 +710,15 @@ Temperature sensors procfs: /proc/acpi/ibm/thermal sysfs device attributes: (hwmon) temp*_input -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 on older -ThinkPads, and it has experimental support for up to sixteen different -sensors on newer ThinkPads. - -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. +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 on older +ThinkPads, and up to sixteen different sensors on newer ThinkPads. For example, on the X40, a typical output may be: temperatures: 42 42 45 41 36 -128 33 -128 -EXPERIMENTAL: On the T43/p, a typical output may be: +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 @@ -562,7 +748,8 @@ 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 +10: Clock-generator, mini-pci card and 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 @@ -681,6 +868,12 @@ cannot be controlled. The backlight control has eight levels, ranging from 0 to 7. Some of the levels may not be distinct. +There are two interfaces to the firmware for brightness control, EC and CMOS. +To select which one should be used, use the brightness_mode module parameter: +brightness_mode=1 selects EC mode, brightness_mode=2 selects CMOS mode, +brightness_mode=3 selects both EC and CMOS. The driver tries to autodetect +which interface to use. + Procfs notes: The available commands are: @@ -976,3 +1169,9 @@ Sysfs interface changelog: 0x000100: Initial sysfs support, as a single platform driver and device. +0x000200: Hot key support for 32 hot keys, and radio slider switch + support. +0x010000: Hot keys are now handled by default over the input + layer, the radio switch generates input event EV_RADIO, + and the driver enables hot key handling by default in + the firmware. diff --git a/Documentation/time_interpolators.txt b/Documentation/time_interpolators.txt deleted file mode 100644 index e3b60854fbc..00000000000 --- a/Documentation/time_interpolators.txt +++ /dev/null @@ -1,41 +0,0 @@ -Time Interpolators ------------------- - -Time interpolators are a base of time calculation between timer ticks and -allow an accurate determination of time down to the accuracy of the time -source in nanoseconds. - -The architecture specific code typically provides gettimeofday and -settimeofday under Linux. The time interpolator provides both if an arch -defines CONFIG_TIME_INTERPOLATION. The arch still must set up timer tick -operations and call the necessary functions to advance the clock. - -With the time interpolator a standardized interface exists for time -interpolation between ticks. The provided logic is highly scalable -and has been tested in SMP situations of up to 512 CPUs. - -If CONFIG_TIME_INTERPOLATION is defined then the architecture specific code -(or the device drivers - like HPET) may register time interpolators. -These are typically defined in the following way: - -static struct time_interpolator my_interpolator { - .frequency = MY_FREQUENCY, - .source = TIME_SOURCE_MMIO32, - .shift = 8, /* scaling for higher accuracy */ - .drift = -1, /* Unknown drift */ - .jitter = 0 /* time source is stable */ -}; - -void time_init(void) -{ - .... - /* Initialization of the timer *. - my_interpolator.address = &my_timer; - register_time_interpolator(&my_interpolator); - .... -} - -For more details see include/linux/timex.h and kernel/timer.c. - -Christoph Lameter <christoph@lameter.com>, October 31, 2004 - diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv index b60639130a5..177159c5f4c 100644 --- a/Documentation/video4linux/CARDLIST.bttv +++ b/Documentation/video4linux/CARDLIST.bttv @@ -66,7 +66,7 @@ 65 -> Lifeview FlyVideo 2000S LR90 66 -> Terratec TValueRadio [153b:1135,153b:ff3b] 67 -> IODATA GV-BCTV4/PCI [10fc:4050] - 68 -> 3Dfx VoodooTV FM (Euro), VoodooTV 200 (USA) [121a:3000,10b4:2637] + 68 -> 3Dfx VoodooTV FM (Euro) [10b4:2637] 69 -> Active Imaging AIMMS 70 -> Prolink Pixelview PV-BT878P+ (Rev.4C,8E) 71 -> Lifeview FlyVideo 98EZ (capture only) LR51 [1851:1851] @@ -145,3 +145,5 @@ 144 -> MagicTV 145 -> SSAI Security Video Interface [4149:5353] 146 -> SSAI Ultrasound Video Interface [414a:5353] +147 -> VoodooTV 200 (USA) [121a:3000] +148 -> DViCO FusionHDTV 2 [dbc0:d200] diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88 index 60f838beb9c..82ac8250e97 100644 --- a/Documentation/video4linux/CARDLIST.cx88 +++ b/Documentation/video4linux/CARDLIST.cx88 @@ -55,3 +55,4 @@ 54 -> Norwood Micro TV Tuner 55 -> Shenzhen Tungsten Ages Tech TE-DTV-250 / Swann OEM [c180:c980] 56 -> Hauppauge WinTV-HVR1300 DVB-T/Hybrid MPEG Encoder [0070:9600,0070:9601,0070:9602] + 57 -> ADS Tech Instant Video PCI [1421:0390] diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 712e8c8333c..3f8aeab50a1 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -114,3 +114,4 @@ 113 -> Elitegroup ECS TVP3XP FM1246 Tuner Card (PAL,FM) [1019:4cb6] 114 -> KWorld DVB-T 210 [17de:7250] 115 -> Sabrent PCMCIA TV-PCB05 [0919:2003] +116 -> 10MOONS TM300 TV Card [1131:2304] diff --git a/Documentation/video4linux/CARDLIST.tuner b/Documentation/video4linux/CARDLIST.tuner index 44134f04b82..a88c02d2380 100644 --- a/Documentation/video4linux/CARDLIST.tuner +++ b/Documentation/video4linux/CARDLIST.tuner @@ -40,7 +40,7 @@ tuner=38 - Philips PAL/SECAM multi (FM1216ME MK3) tuner=39 - LG NTSC (newer TAPC series) tuner=40 - HITACHI V7-J180AT tuner=41 - Philips PAL_MK (FI1216 MK) -tuner=42 - Philips 1236D ATSC/NTSC dual in +tuner=42 - Philips FCV1236D ATSC/NTSC dual in tuner=43 - Philips NTSC MK3 (FM1236MK3 or FM1236/F) tuner=44 - Philips 4 in 1 (ATI TV Wonder Pro/Conexant) tuner=45 - Microtune 4049 FM5 @@ -72,3 +72,4 @@ tuner=70 - Samsung TCPN 2121P30A tuner=71 - Xceive xc3028 tuner=72 - Thomson FE6600 tuner=73 - Samsung TCPG 6121P30A +tuner=75 - Philips TEA5761 FM Radio diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt index 279717c96f6..1ffad19ce89 100644 --- a/Documentation/video4linux/sn9c102.txt +++ b/Documentation/video4linux/sn9c102.txt @@ -436,7 +436,7 @@ HV7131D Hynix Semiconductor | Yes No No No HV7131R Hynix Semiconductor | No Yes Yes Yes MI-0343 Micron Technology | Yes No No No MI-0360 Micron Technology | No Yes Yes Yes -OV7630 OmniVision Technologies | Yes Yes No No +OV7630 OmniVision Technologies | Yes Yes Yes Yes OV7660 OmniVision Technologies | No No Yes Yes PAS106B PixArt Imaging | Yes No No No PAS202B PixArt Imaging | Yes Yes No No @@ -583,6 +583,7 @@ order): - Bertrik Sikken, who reverse-engineered and documented the Huffman compression algorithm used in the SN9C101, SN9C102 and SN9C103 controllers and implemented the first decoder; +- Ronny Standke for the donation of a webcam; - Mizuno Takafumi for the donation of a webcam; - an "anonymous" donator (who didn't want his name to be revealed) for the donation of a webcam. diff --git a/Documentation/video4linux/zr364xx.txt b/Documentation/video4linux/zr364xx.txt index c76992d0ff4..4d9a0c33f2f 100644 --- a/Documentation/video4linux/zr364xx.txt +++ b/Documentation/video4linux/zr364xx.txt @@ -62,4 +62,4 @@ Vendor Product Distributor Model 0x0784 0x0040 Traveler Slimline X5 0x06d6 0x0034 Trust Powerc@m 750 0x0a17 0x0062 Pentax Optio 50L - +0x06d6 0x003b Trust Powerc@m 970Z diff --git a/Documentation/x86_64/boot-options.txt b/Documentation/x86_64/boot-options.txt index 6177d881983..945311840a1 100644 --- a/Documentation/x86_64/boot-options.txt +++ b/Documentation/x86_64/boot-options.txt @@ -14,9 +14,11 @@ Machine check mce=nobootlog Disable boot machine check logging. mce=tolerancelevel (number) - 0: always panic, 1: panic if deadlock possible, - 2: try to avoid panic, 3: never panic or exit (for testing) - default is 1 + 0: always panic on uncorrected errors, log corrected errors + 1: panic or SIGBUS on uncorrected errors, log corrected errors + 2: SIGBUS or log uncorrected errors, log corrected errors + 3: never panic or SIGBUS, log all errors (for testing only) + Default is 1 Can be also set using sysfs which is preferable. nomce (for compatibility with i386): same as mce=off @@ -134,12 +136,6 @@ Non Executable Mappings SMP - nosmp Only use a single CPU - - maxcpus=NUMBER only use upto NUMBER CPUs - - cpumask=MASK only use cpus with bits set in mask - additional_cpus=NUM Allow NUM more CPUs for hotplug (defaults are specified by the BIOS, see Documentation/x86_64/cpu-hotplug-spec) diff --git a/Documentation/x86_64/machinecheck b/Documentation/x86_64/machinecheck index feaeaf6f6e4..a05e58e7b15 100644 --- a/Documentation/x86_64/machinecheck +++ b/Documentation/x86_64/machinecheck @@ -49,12 +49,14 @@ tolerant Since machine check exceptions can happen any time it is sometimes risky for the kernel to kill a process because it defies normal kernel locking rules. The tolerance level configures - how hard the kernel tries to recover even at some risk of deadlock. - - 0: always panic, - 1: panic if deadlock possible, - 2: try to avoid panic, - 3: never panic or exit (for testing only) + how hard the kernel tries to recover even at some risk of + deadlock. Higher tolerant values trade potentially better uptime + with the risk of a crash or even corruption (for tolerant >= 3). + + 0: always panic on uncorrected errors, log corrected errors + 1: panic or SIGBUS on uncorrected errors, log corrected errors + 2: SIGBUS or log uncorrected errors, log corrected errors + 3: never panic or SIGBUS, log all errors (for testing only) Default: 1 diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO new file mode 100644 index 00000000000..48fc67bfbe3 --- /dev/null +++ b/Documentation/zh_CN/HOWTO @@ -0,0 +1,536 @@ +Chinese translated version of Documentation/HOWTO + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer, if this translation is outdated +or there is problem with translation. + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> +Chinese maintainer: Li Yang <leoli@freescale.com> +--------------------------------------------------------------------- +Documentation/HOWTO 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> +中文版维护者： 李阳 Li Yang <leoli@freescale.com> +中文版翻译者： 李阳 Li Yang <leoli@freescale.com> +中文版校译者： 钟宇 TripleX Chung <xxx.phy@gmail.com> + 陈琦 Maggie Chen <chenqi@beyondsoft.com> + 王聪 Wang Cong <xiyou.wangcong@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + +如何参与Linux内核开发 +--------------------- + +这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你 +成为一名Linux内核开发者，并且学会如何同Linux内核开发社区合作。它尽可能不 +包括任何关于内核编程的技术细节，但会给你指引一条获得这些知识的正确途径。 + +如果这篇文章中的任何内容不再适用，请给文末列出的文件维护者发送补丁。 + + +入门 +---- + +你想了解如何成为一名Linux内核开发者？或者老板吩咐你“给这个设备写个Linux +驱动程序”？这篇文章的目的就是教会你达成这些目标的全部诀窍，它将描述你需 +要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区 +为何这样运作。 + +Linux内核大部分是由C语言写成的，一些体系结构相关的代码用到了汇编语言。要 +参与内核开发，你必须精通C语言。除非你想为某个架构开发底层代码，否则你并 +不需要了解（任何体系结构的）汇编语言。下面列举的书籍虽然不能替代扎实的C +语言教育和多年的开发经验，但如果需要的话，做为参考还是不错的： + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + 《C程序设计语言（第2版·新版）》（徐宝文 李志 译）[机械工业出版社] + - "Practical C Programming" by Steve Oualline [O'Reilly] + 《实用C语言编程（第三版）》（郭大海 译）[中国电力出版社] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + 《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社] + +Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些 +标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以 +并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许 +使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目 +前还没有明确的参考资料可以解释它们。请查阅gcc信息页（使用“info gcc”命令 +显示）获得一些这方面信息。 + +请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成， +他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的， +适应于地理上分散的大型开发团队。它们已经被很好得整理成档，建议你在开发 +之前尽可能多的学习这些标准，而不要期望别人来适应你或者你公司的行为方式。 + + +法律问题 +-------- + +Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的。要了解这种许可 +的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系 +律师，而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师，不要期 +望他们的话有法律效力。 + +对于GPL的常见问题和解答，请访问以下链接： + http://www.gnu.org/licenses/gpl-faq.html + + +文档 +---- + +Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着 +不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文 +档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信 +息或手册页(manpages)的补丁发到mtk-manpages@gmx.net，以向手册页(manpages) +的维护者解释这些变化。 + +以下是内核代码中需要阅读的文档： + README + 文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的 + 新用户应该从这里开始。 + + Documentation/Changes + 文件给出了用来编译和使用内核所需要的最小软件包列表。 + + Documentation/CodingStyle + 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规 + 范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格 + 的代码。 + + Documentation/SubmittingPatches + Documentation/SubmittingDrivers + 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： + - 邮件内容 + - 邮件格式 + - 选择收件人 + 遵守这些规定并不能保证提交成功（因为所有补丁需要通过严格的内容和风格 + 审查），但是忽视他们几乎就意味着失败。 + + 其他关于如何正确地生成补丁的优秀文档包括： + "The Perfect Patch" + http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + Documentation/stable_api_nonsense.txt + 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 + 性： + - 子系统中间层（为了兼容性？） + - 在不同操作系统间易于移植的驱动程序 + - 减缓（甚至阻止）内核代码的快速变化 + 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系 + 统转移到Linux的人来说也很重要。 + + Documentation/SecurityBugs + 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来 + 提醒其他内核开发者并帮助解决这个问题。 + + Documentation/ManagementStyle + 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对 + 它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的 + 普遍误解与迷惑。 + + Documentation/stable_kernel_rules.txt + 解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。 + + Documentation/kernel-docs.txt + 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找 + 的内容，可以查看这些文档。 + + Documentation/applying-patches.txt + 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 + +内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 +妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内 +核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 +页等不同格式的文档： + make pdfdocs + make psdocs + make htmldocs + make mandocs + + +如何成为内核开发者 +------------------ +如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划： + http://kernelnewbies.org +它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得 +查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得 +实时反馈的IRC聊天频道，以及大量对于学习Linux内核开发相当有帮助的文档。 + +网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目（包括内核 +中的和单独维护的）。它还提供了一些基本的帮助信息，比如如何编译内核和打补 +丁。 + +如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问 +“Linux内核房管员”计划： + http://janitor.kernelnewbies.org/ +这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新 +整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁 +集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方 +向性的指点。 + +如果你已经有一些现成的代码想要放到内核中，但是需要一些帮助来使它们拥有正 +确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它 +是一个邮件列表，地址如下： + http://selenic.com/mailman/listinfo/kernel-mentors + +在真正动手修改内核代码之前，理解要修改的代码如何运作是必需的。要达到这个 +目的，没什么办法比直接读代码更有效了（大多数花招都会有相应的注释），而且 +一些特制的工具还可以提供帮助。例如，“Linux代码交叉引用”项目就是一个值得 +特别推荐的帮助工具，它将源代码显示在有编目和索引的网页上。其中一个更新及 +时的内核源码库，可以通过以下地址访问： + http://sosdg.org/~coywolf/lxr/ + + +开发流程 +-------- + +目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这 +些分支包括： + - 2.6.x主内核源码树 + - 2.6.x.y -stable内核源码树 + - 2.6.x -git内核补丁集 + - 2.6.x -mm内核补丁集 + - 子系统相关的内核源码树和补丁集 + + +2.6.x内核主源码树 +----------------- +2.6.x内核是由Linus Torvalds（Linux的创造者）亲自维护的。你可以在 +kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步 +骤： + - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里 + 维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个 + 星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具 + ，更多的信息可以在http://git.or.cz/获取），不过使用普通补丁也是可以 + 的。 + - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的 + 新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有 + 可能在-rc1后被接受是因为这样的修改完全独立，不会影响其他的代码，所以 + 没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁，不过所 + 有的补丁需要同时被发送到相应的公众邮件列表以征询意见。 + - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试 + 时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。 + - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是 + 6个星期。 + +关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说： + “没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定 + 的，而不是根据一个事先制定好的时间表。” + + +2.6.x.y -stable（稳定版）内核源码树 +----------------------------------- +由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本 +内核的相对较小且至关重要的修补，这些修补针对安全性问题或者严重的内核退步。 + +这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或 +者实验版的用户。 + +如果没有2.6.x.y版本内核存在，那么最新的2.6.x版本内核就相当于是当前的稳定 +版内核。 + +2.6.x.y版本由“稳定版”小组（邮件地址<stable@kernel.org>）维护，一般隔周发 +布新版本。 + +内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定 +版内核接受的修改类型以及发布的流程。 + + +2.6.x -git补丁集 +---------------- +Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这 +些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码 +树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正 +健全。 + + +2.6.x -mm补丁集 +--------------- +这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码 +和补丁拼凑到一起，并且加入了大量从linux-kernel邮件列表中采集的补丁。这个 +源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew +或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。 + +在将所有新补丁发给Linus以集成到主内核源码树之前，我们非常鼓励先把这些补 +丁放在-mm版内核源码树中进行测试。 + +这些内核版本不适合在需要稳定运行的系统上运行，因为运行它们比运行任何其他 +内核分支都更具有风险。 + +如果你想为内核开发进程提供帮助，请尝试并使用这些内核版本，并在 +linux-kernel邮件列表中提供反馈，告诉大家你遇到了问题还是一切正常。 + +通常-mm版补丁集不光包括这些额外的试验性补丁，还包括发布时-git版主源码树 +中的改动。 + +-mm版内核没有固定的发布周期，但是通常在每两个-rc版内核发布之间都会有若干 +个-mm版内核发布（一般是1至3个）。 + + +子系统相关内核源码树和补丁集 +---------------------------- +相当一部分内核子系统开发者会公开他们自己的开发源码树，以便其他人能了解内 +核的不同领域正在发生的事情。如上所述，这些源码树会被集成到-mm版本内核中。 + +下面是目前可用的一些内核源码树的列表： + 通过git管理的源码树： + - Kbuild开发源码树， Sam Ravnborg <sam@ravnborg.org> + git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git + + - ACPI开发源码树, Len Brown <len.brown@intel.com> + git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git + + - 块设备开发源码树, Jens Axboe <axboe@suse.de> + git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git + + - DRM开发源码树, Dave Airlie <airlied@linux.ie> + git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git + + - ia64开发源码树, Tony Luck <tony.luck@intel.com> + git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + + - ieee1394开发源码树, Jody McIntyre <scjody@modernduck.com> + git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git + + - infiniband开发源码树, Roland Dreier <rolandd@cisco.com> + git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git + + - libata开发源码树, Jeff Garzik <jgarzik@pobox.com> + git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git + + - 网络驱动程序开发源码树, Jeff Garzik <jgarzik@pobox.com> + git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git + + - pcmcia开发源码树, Dominik Brodowski <linux@dominikbrodowski.net> + git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git + + - SCSI开发源码树, James Bottomley <James.Bottomley@SteelEye.com> + git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git + + 使用quilt管理的补丁集： + - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman <gregkh@suse.de> + kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ + - x86-64, 部分i386, Andi Kleen <ak@suse.de> + ftp.firstfloor.org:/pub/ak/x86_64/quilt/ + + 其他内核源码树可以在http://git.kernel.org的列表中和MAINTAINERS文件里 + 找到。 + +报告bug +------- + +bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用 +户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问： + http://test.kernel.org/bugzilla/faq.html + +内核源码主目录中的REPORTING-BUGS文件里有一个很好的模板。它指导用户如何报 +告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。 + + +利用bug报告 +----------- + +练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变 +得更加稳定，还可以学会如何解决实际问题从而提高自己的技能，并且让其他开发 +者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法，因为并不是很多 +人都喜欢浪费时间去修改别人报告的bug。 + +要尝试修改已知的bug，请访问http://bugzilla.kernel.org网址。如果你想获得 +最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里） +或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。 + + http://lists.osdl.org/mailman/listinfo/bugme-new + http://lists.osdl.org/mailman/listinfo/bugme-janitors + + +邮件列表 +-------- + +正如上面的文档所描述，大多数的骨干内核开发者都加入了Linux Kernel邮件列 +表。如何订阅和退订列表的细节可以在这里找到： + http://vger.kernel.org/vger-lists.html#linux-kernel +网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些 +存档。比如： + http://dir.gmane.org/gmane.linux.kernel +在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细 +讨论过的问题只在邮件列表的存档中可以找到。 + +大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从 +MAINTAINERS文件中可以找到不同话题对应的邮件列表。 + +很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到： + http://vger.kernel.org/vger-lists.html + +在使用这些邮件列表时，请记住保持良好的行为习惯。下面的链接提供了与这些列 +表（或任何其它邮件列表）交流的一些简单规则，虽然内容有点滥竽充数。 + http://www.albion.com/netiquette/ + +当有很多人回复你的邮件时，邮件的抄送列表会变得很长。请不要将任何人从抄送 +列表中删除，除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同 +一封邮件接收两次（一封来自发送者一封来自邮件列表），而不要试图通过添加一 +些奇特的邮件头来解决这个问题，人们不会喜欢的。 + +记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……” +这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。 + +如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如 +Documentation/SubmittingPatches文档中所述）。内核开发者们不希望遇到附件 +或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保 +你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件 +发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请 +调整或者更换你的邮件发送程序直到它正确工作为止。 + +总而言之，请尊重其他的邮件列表订阅者。 + + +同内核社区合作 +---------------- + +内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的 +时候，它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢？ + - 批评 + - 评论 + - 要求修改 + - 要求证明修改的必要性 + - 沉默 + +要记住，这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论， +从技术层面评估它们，然后要么重写你的补丁要么简明扼要地论证修改是不必要 +的。如果你发的邮件没有得到任何回应，请过几天后再试一次，因为有时信件会湮 +没在茫茫信海中。 + +你不应该做的事情： + - 期望自己的补丁不受任何质疑就直接被接受 + - 翻脸 + - 忽略别人的评论 + - 没有按照别人的要求做任何修改就重新提交 + +在一个努力追寻最好技术方案的社区里，对于一个补丁有多少好处总会有不同的见 +解。你必须要抱着合作的态度，愿意改变自己的观点来适应内核的风格。或者至少 +愿意去证明你的想法是有价值的。记住，犯错误是允许的，只要你愿意朝着正确的 +方案去努力。 + +如果你的第一个补丁换来的是一堆修改建议，这是很正常的。这并不代表你的补丁 +不会被接受，也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发 +送你的补丁。 + +内核社区和公司文化的差异 +------------------------ + +内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例 +子，可以帮助你避免某些可能发生问题： + 用这些话介绍你的修改提案会有好处： + - 它同时解决了多个问题 + - 它删除了2000行代码 + - 这是补丁，它已经解释了我想要说明的 + - 我在5种不同的体系结构上测试过它…… + - 这是一系列小补丁用来…… + - 这个修改提高了普通机器的性能…… + + 应该避免如下的说法： + - 我们在AIX/ptx/Solaris就是这么做的，所以这么做肯定是好的…… + - 我做这行已经20年了，所以…… + - 为了我们公司赚钱考虑必须这么做 + - 这是我们的企业产品线所需要的 + - 这里是描述我观点的1000页设计文档 + - 这是一个5000行的补丁用来…… + - 我重写了现在乱七八糟的代码，这就是…… + - 我被规定了最后期限，所以这个补丁需要立刻被接受 + +另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交 +流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视 +将会更少。Linux内核的工作环境更能接受妇女和少数族群，因为每个人在别人眼 +里只是一个邮件地址。国际化也帮助了公平的实现，因为你无法通过姓名来判断人 +的性别。男人有可能叫李丽，女人也有可能叫王刚。大多数在Linux内核上工作过 +并表达过看法的女性对在linux上工作的经历都给出了正面的评价。 + +对于一些不习惯使用英语的人来说，语言可能是一个引起问题的障碍。在邮件列表 +中要正确地表达想法必需良好地掌握语言，所以建议你在发送邮件之前最好检查一 +下英文写得是否正确。 + + +拆分修改 +-------- + +Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且 +拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最 +开始的阶段就让大家知道，这样你就可以及时获得对你正在进行的开发的反馈。这 +样也会让社区觉得你是在和他们协作，而不是仅仅把他们当作倾销新功能的对象。 +无论如何，你不要一次性地向邮件列表发送50封信，你的补丁序列应该永远用不到 +这么多。 + +将补丁拆开的原因如下： + +1) 小的补丁更有可能被接受，因为它们不需要太多的时间和精力去验证其正确性。 + 一个5行的补丁，可能在维护者看了一眼以后就会被接受。而500行的补丁则 + 需要数个小时来审查其正确性（所需时间随补丁大小增加大约呈指数级增长）。 + + 当出了问题的时候，小的补丁也会让调试变得非常容易。一个一个补丁地回溯 + 将会比仔细剖析一个被打上的大补丁（这个补丁破坏了其他东西）容易得多。 + +2）不光发送小的补丁很重要，在提交之前重新编排、化简（或者仅仅重新排列） + 补丁也是很重要的。 + +这里有内核开发者Al Viro打的一个比方： + “想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得 + 到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的 + 解答。好学生了解这点，绝不会把最终解决之前的中间方案提交上去。” + + 内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思 + 考过程。他们只希望看到简单和优雅的解决方案。 + +直接给出一流的解决方案，和社区一起协作讨论尚未完成的工作，这两者之间似乎 +很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈；同时也要 +保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部 +分可能会先被接收。 + +必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修 +复。 + + +证明修改的必要性 +---------------- +除了将补丁拆成小块，很重要的一点是让Linux社区了解他们为什么需要这样修改。 +你必须证明新功能是有人需要的并且是有用的。 + + +记录修改 +-------- + +当你发送补丁的时候，需要特别留意邮件正文的内容。因为这里的信息将会做为补 +丁的修改记录(ChangeLog)，会被一直保留以备大家查阅。它需要完全地描述补丁， +包括： + - 为什么需要这个修改 + - 补丁的总体设计 + - 实现细节 + - 测试结果 + +想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节： + “The Perfect Patch” + http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt + + +这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是 +一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。 +很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。 + + +--------------- +感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章 +(http://linux.tar.bz/articles/2.6-development_process)，感谢Randy +Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna +Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, +Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian +Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael +Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助，这篇文档是不可 +能完成的。 + + + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt new file mode 100644 index 00000000000..c26a27d1ee7 --- /dev/null +++ b/Documentation/zh_CN/stable_api_nonsense.txt @@ -0,0 +1,157 @@ +Chinese translated version of Documentation/stable_api_nonsense.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have problem +communicating in English you can also ask the Chinese maintainer for help. +Contact the Chinese maintainer, if this translation is outdated or there +is problem with translation. + +Maintainer: Greg Kroah-Hartman <greg@kroah.com> +Chinese maintainer: TripleX Chung <zhongyu@18mail.cn> +--------------------------------------------------------------------- +Documentation/stable_api_nonsense.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> +中文版维护者： 钟宇 TripleX Chung <zhongyu@18mail.cn> +中文版翻译者： 钟宇 TripleX Chung <zhongyu@18mail.cn> +中文版校译者： 李阳 Li Yang <leoli@freescale.com> +以下为正文 +--------------------------------------------------------------------- + +写作本文档的目的，是为了解释为什么Linux既没有二进制内核接口，也没有稳定 +的内核接口。这里所说的内核接口，是指内核里的接口，而不是内核和用户空间 +的接口。内核到用户空间的接口，是提供给应用程序使用的系统调用，系统调用 +在历史上几乎没有过变化，将来也不会有变化。我有一些老应用程序是在0.9版本 +或者更早版本的内核上编译的，在使用2.6版本内核的Linux发布上依然用得很好 +。用户和应用程序作者可以将这个接口看成是稳定的。 + + +执行纲要 +-------- + +你也许以为自己想要稳定的内核接口，但是你不清楚你要的实际上不是它。你需 +要的其实是稳定的驱动程序，而你只有将驱动程序放到公版内核的源代码树里， +才有可能达到这个目的。而且这样做还有很多其它好处，正是因为这些好处使得 +Linux能成为强壮，稳定，成熟的操作系统，这也是你最开始选择Linux的原因。 + + +入门 +----- + +只有那些写驱动程序的“怪人”才会担心内核接口的改变，对广大用户来说，既 +看不到内核接口，也不需要去关心它。 + +首先，我不打算讨论关于任何非GPL许可的内核驱动的法律问题，这些非GPL许可 +的驱动程序包括不公开源代码，隐藏源代码，二进制或者是用源代码包装，或者 +是其它任何形式的不能以GPL许可公开源代码的驱动程序。如果有法律问题，请咨 +询律师，我只是一个程序员，所以我只打算探讨技术问题（不是小看法律问题， +法律问题很实际，并且需要一直关注）。 + +既然只谈技术问题，我们就有了下面两个主题：二进制内核接口和稳定的内核源 +代码接口。这两个问题是互相关联的，让我们先解决掉二进制接口的问题。 + + +二进制内核接口 +-------------- +假如我们有一个稳定的内核源代码接口，那么自然而然的，我们就拥有了稳定的 +二进制接口，是这样的吗？错。让我们看看关于Linux内核的几点事实： + - 取决于所用的C编译器的版本，不同的内核数据结构里的结构体的对齐方 +式会有差别，代码中不同函数的表现形式也不一样（函数是不是被inline编译取 +决于编译器行为）。不同的函数的表现形式并不重要，但是数据结构内部的对齐 +方式很关键。 + - 取决于内核的配置选项，不同的选项会让内核的很多东西发生改变： + - 同一个结构体可能包含不同的成员变量 + - 有的函数可能根本不会被实现（比如编译的时候没有选择SMP支持 +，一些锁函数就会被定义成空函数）。 + - 内核使用的内存会以不同的方式对齐，这取决于不同的内核配置选 +项。 + - Linux可以在很多的不同体系结构的处理器上运行。在某个体系结构上编 +译好的二进制驱动程序，不可能在另外一个体系结构上正确的运行。 + +对于一个特定的内核，满足这些条件并不难，使用同一个C编译器和同样的内核配 +置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发布的特定版本提 +供驱动程序，是完全可以满足需求的。但是如果你要给不同发布的不同版本都发 +布一个驱动程序，就需要在每个发布上用不同的内核设置参数都编译一次内核， +这简直跟噩梦一样。而且还要注意到，每个Linux发布还提供不同的Linux内核， +这些内核都针对不同的硬件类型进行了优化（有很多种不同的处理器，还有不同 +的内核设置选项）。所以每发布一次驱动程序，都需要提供很多不同版本的内核 +模块。 + +相信我，如果你真的要采取这种发布方式，一定会慢慢疯掉，我很久以前就有过 +深刻的教训... + + +稳定的内核源代码接口 +-------------------- + +如果有人不将他的内核驱动程序，放入公版内核的源代码树，而又想让驱动程序 +一直保持在最新的内核中可用，那么这个话题将会变得没完没了。 + 内核开发是持续而且快节奏的，从来都不会慢下来。内核开发人员在当前接口中 +找到bug，或者找到更好的实现方式。一旦发现这些，他们就很快会去修改当前的 +接口。修改接口意味着，函数名可能会改变，结构体可能被扩充或者删减，函数 +的参数也可能发生改变。一旦接口被修改，内核中使用这些接口的地方需要同时 +修正，这样才能保证所有的东西继续工作。 + +举一个例子，内核的USB驱动程序接口在USB子系统的整个生命周期中，至少经历 +了三次重写。这些重写解决以下问题： + - 把数据流从同步模式改成非同步模式，这个改动减少了一些驱动程序的 +复杂度，提高了所有USB驱动程序的吞吐率，这样几乎所有的USB设备都能以最大 +速率工作了。 + - 修改了USB核心代码中为USB驱动分配数据包内存的方式，所有的驱动都 +需要提供更多的参数给USB核心，以修正了很多已经被记录在案的死锁。 + +这和一些封闭源代码的操作系统形成鲜明的对比，在那些操作系统上，不得不额 +外的维护旧的USB接口。这导致了一个可能性，新的开发者依然会不小心使用旧的 +接口，以不恰当的方式编写代码，进而影响到操作系统的稳定性。 + 在上面的例子中，所有的开发者都同意这些重要的改动，在这样的情况下修改代 +价很低。如果Linux保持一个稳定的内核源代码接口，那么就得创建一个新的接口 +；旧的，有问题的接口必须一直维护，给Linux USB开发者带来额外的工作。既然 +所有的Linux USB驱动的作者都是利用自己的时间工作，那么要求他们去做毫无意 +义的免费额外工作，是不可能的。 + 安全问题对Linux来说十分重要。一个安全问题被发现，就会在短时间内得到修 +正。在很多情况下，这将导致Linux内核中的一些接口被重写，以从根本上避免安 +全问题。一旦接口被重写，所有使用这些接口的驱动程序，必须同时得到修正， +以确定安全问题已经得到修复并且不可能在未来还有同样的安全问题。如果内核 +内部接口不允许改变，那么就不可能修复这样的安全问题，也不可能确认这样的 +安全问题以后不会发生。 +开发者一直在清理内核接口。如果一个接口没有人在使用了，它就会被删除。这 +样可以确保内核尽可能的小，而且所有潜在的接口都会得到尽可能完整的测试 +（没有人使用的接口是不可能得到良好的测试的）。 + + +要做什么 +------- + +如果你写了一个Linux内核驱动，但是它还不在Linux源代码树里，作为一个开发 +者，你应该怎么做？为每个发布的每个版本提供一个二进制驱动，那简直是一个 +噩梦，要跟上永远处于变化之中的内核接口，也是一件辛苦活。 +很简单，让你的驱动进入内核源代码树（要记得我们在谈论的是以GPL许可发行 +的驱动，如果你的代码不符合GPL，那么祝你好运，你只能自己解决这个问题了， +你这个吸血鬼<把Andrew和Linus对吸血鬼的定义链接到这里>）。当你的代码加入 +公版内核源代码树之后，如果一个内核接口改变，你的驱动会直接被修改接口的 +那个人修改。保证你的驱动永远都可以编译通过，并且一直工作，你几乎不需要 +做什么事情。 + +把驱动放到内核源代码树里会有很多的好处： + - 驱动的质量会提升，而维护成本（对原始作者来说）会下降。 + - 其他人会给驱动添加新特性。 + - 其他人会找到驱动中的bug并修复。 + - 其他人会在驱动中找到性能优化的机会。 + - 当外部的接口的改变需要修改驱动程序的时候，其他人会修改驱动程序 +。 + - 不需要联系任何发行商，这个驱动会自动的随着所有的Linux发布一起发 +布。 + +和别的操作系统相比，Linux为更多不同的设备提供现成的驱动，而且能在更多不 +同体系结构的处理器上支持这些设备。这个经过考验的开发模式，必然是错不了 +的 :) + +------------- +感谢 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love, and Nishanth Aravamudan 对于本文档早期版本的评审和建议。 + +英文版维护者： Greg Kroah-Hartman <greg@kroah.com> |