diff options
Diffstat (limited to 'Documentation')
130 files changed, 5443 insertions, 1394 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index c3014df..6e9c405 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -14,6 +14,7 @@ Following translations are available on the WWW: - this file. ABI/ - info on kernel <-> userspace ABI and relative interface stability. + BUG-HUNTING - brute force method of doing binary search of patches to find bug. Changes @@ -66,6 +67,8 @@ VGA-softcursor.txt - how to change your VGA cursor from a blinking underscore. accounting/ - documentation on accounting and taskstats. +acpi/ + - info on ACPI-specific hooks in the kernel. aoe/ - description of AoE (ATA over Ethernet) along with config examples. applying-patches.txt @@ -126,18 +129,16 @@ devices.txt - plain ASCII listing of all the nodes in /dev/ with major minor #'s. digiepca.txt - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards. -dnotify.txt - - info about directory notification in Linux. dontdiff - file containing a list of files that should never be diff'ed. driver-model/ - directory with info about Linux driver model. -drivers/ - - directory with driver documentation (currently only EDAC). dvb/ - info on Linux Digital Video Broadcast (DVB) subsystem. early-userspace/ - info about initramfs, klibc, and userspace early during boot. +edac.txt + - information on EDAC - Error Detection And Correction eisa.txt - info on EISA bus support. exception.txt @@ -154,7 +155,7 @@ firmware_class/ - request_firmware() hotplug interface info. floppy.txt - notes and driver options for the floppy disk driver. -fujitsu/ +frv/ - Fujitsu FR-V Linux documentation. gpio.txt - overview of GPIO (General Purpose Input/Output) access conventions. @@ -334,20 +335,8 @@ rtc.txt - notes on how to use the Real Time Clock (aka CMOS clock) driver. s390/ - directory with info on using Linux on the IBM S390. -sched-arch.txt - - CPU Scheduler implementation hints for architecture specific code. -sched-coding.txt - - reference for various scheduler-related methods in the O(1) scheduler. -sched-design.txt - - goals, design and implementation of the Linux O(1) scheduler. -sched-design-CFS.txt - - goals, design and implementation of the Complete Fair Scheduler. -sched-domains.txt - - information on scheduling domains. -sched-nice-design.txt - - How and why the scheduler's nice levels are implemented. -sched-stats.txt - - information on schedstats (Linux Scheduler Statistics). +scheduler/ + - directory with info on the scheduler. scsi/ - directory with info on Linux scsi support. serial/ @@ -360,12 +349,8 @@ sgi-visws.txt - short blurb on the SGI Visual Workstations. sh/ - directory with info on porting Linux to a new architecture. -sharedsubtree.txt - - a description of shared subtrees for namespaces. smart-config.txt - description of the Smart Config makefile feature. -smp.txt - - a few notes on symmetric multi-processing. sony-laptop.txt - Sony Notebook Control Driver (SNC) Readme. sonypi.txt diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 9734577..11a3c16 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -52,3 +52,36 @@ Description: facility is inherently dangerous, it is disabled by default for all devices except hubs. For more information, see Documentation/usb/persist.txt. + +What: /sys/bus/usb/device/.../power/connected_duration +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file + is present. When read, it returns the total time (in msec) + that the USB device has been connected to the machine. This + file is read-only. +Users: + PowerTOP <power@bughost.org> + http://www.lesswatts.org/projects/powertop/ + +What: /sys/bus/usb/device/.../power/active_duration +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file + is present. When read, it returns the total time (in msec) + that the USB device has been active, i.e. not in a suspended + state. This file is read-only. + + Tools can use this file and the connected_duration file to + compute the percentage of time that a device has been active. + For example, + echo $((100 * `cat active_duration` / `cat connected_duration`)) + will give an integer percentage. Note that this does not + account for counter wrap. +Users: + PowerTOP <power@bughost.org> + http://www.lesswatts.org/projects/powertop/ diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi new file mode 100644 index 0000000..9470ed9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -0,0 +1,99 @@ +What: /sys/firmware/acpi/interrupts/ +Date: February 2008 +Contact: Len Brown <lenb@kernel.org> +Description: + All ACPI interrupts are handled via a single IRQ, + the System Control Interrupt (SCI), which appears + as "acpi" in /proc/interrupts. + + However, one of the main functions of ACPI is to make + the platform understand random hardware without + special driver support. So while the SCI handles a few + well known (fixed feature) interrupts sources, such + as the power button, it can also handle a variable + number of a "General Purpose Events" (GPE). + + A GPE vectors to a specified handler in AML, which + can do a anything the BIOS writer wants from + OS context. GPE 0x12, for example, would vector + to a level or edge handler called _L12 or _E12. + The handler may do its business and return. + Or the handler may send send a Notify event + to a Linux device driver registered on an ACPI device, + such as a battery, or a processor. + + To figure out where all the SCI's are coming from, + /sys/firmware/acpi/interrupts contains a file listing + every possible source, and the count of how many + times it has triggered. + + $ cd /sys/firmware/acpi/interrupts + $ grep . * + error:0 + ff_gbl_lock:0 + ff_pmtimer:0 + ff_pwr_btn:0 + ff_rt_clk:0 + ff_slp_btn:0 + gpe00:0 + gpe01:0 + gpe02:0 + gpe03:0 + gpe04:0 + gpe05:0 + gpe06:0 + gpe07:0 + gpe08:0 + gpe09:174 + gpe0A:0 + gpe0B:0 + gpe0C:0 + gpe0D:0 + gpe0E:0 + gpe0F:0 + gpe10:0 + gpe11:60 + gpe12:0 + gpe13:0 + gpe14:0 + gpe15:0 + gpe16:0 + gpe17:0 + gpe18:0 + gpe19:7 + gpe1A:0 + gpe1B:0 + gpe1C:0 + gpe1D:0 + gpe1E:0 + gpe1F:0 + gpe_all:241 + sci:241 + + sci - The total number of times the ACPI SCI + has claimed an interrupt. + + gpe_all - count of SCI caused by GPEs. + + gpeXX - count for individual GPE source + + ff_gbl_lock - Global Lock + + ff_pmtimer - PM Timer + + ff_pwr_btn - Power Button + + ff_rt_clk - Real Time Clock + + ff_slp_btn - Sleep Button + + error - an interrupt that can't be accounted for above. + + Root has permission to clear any of these counters. Eg. + # echo 0 > gpe11 + + All counters can be cleared by clearing the total "sci": + # echo 0 > sci + + None of these counters has an effect on the function + of the system, they are simply statistics. diff --git a/Documentation/ABI/testing/sysfs-kernel-uids b/Documentation/ABI/testing/sysfs-kernel-uids index 648d65d..28f1469 100644 --- a/Documentation/ABI/testing/sysfs-kernel-uids +++ b/Documentation/ABI/testing/sysfs-kernel-uids @@ -11,4 +11,4 @@ Description: example would be, if User A has shares = 1024 and user B has shares = 2048, User B will get twice the CPU bandwidth user A will. For more details refer - Documentation/sched-design-CFS.txt + Documentation/scheduler/sched-design-CFS.txt diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING index 35f5bd2..65022a8 100644 --- a/Documentation/BUG-HUNTING +++ b/Documentation/BUG-HUNTING @@ -53,7 +53,7 @@ Finding it the old way [Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] -This is how to track down a bug if you know nothing about kernel hacking. +This is how to track down a bug if you know nothing about kernel hacking. It's a brute force approach but it works pretty well. You need: @@ -66,12 +66,12 @@ You will then do: . Rebuild a revision that you believe works, install, and verify that. . Do a binary search over the kernels to figure out which one - introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but + introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but you know that 1.3.69 does. Pick a kernel in the middle and build that, like 1.3.50. Build & test; if it works, pick the mid point between .50 and .69, else the mid point between .28 and .50. . You'll narrow it down to the kernel that introduced the bug. You - can probably do better than this but it gets tricky. + can probably do better than this but it gets tricky. . Narrow it down to a subdirectory @@ -81,27 +81,27 @@ You will then do: directories: Copy the non-working directory next to the working directory - as "dir.63". + as "dir.63". One directory at time, try moving the working directory to - "dir.62" and mv dir.63 dir"time, try + "dir.62" and mv dir.63 dir"time, try mv dir dir.62 mv dir.63 dir find dir -name '*.[oa]' -print | xargs rm -f And then rebuild and retest. Assuming that all related - changes were contained in the sub directory, this should - isolate the change to a directory. + changes were contained in the sub directory, this should + isolate the change to a directory. Problems: changes in header files may have occurred; I've - found in my case that they were self explanatory - you may + found in my case that they were self explanatory - you may or may not want to give up when that happens. . Narrow it down to a file - You can apply the same technique to each file in the directory, - hoping that the changes in that file are self contained. - + hoping that the changes in that file are self contained. + . Narrow it down to a routine - You can take the old file and the new file and manually create @@ -130,7 +130,7 @@ You will then do: that makes the difference. Finally, you take all the info that you have, kernel revisions, bug -description, the extent to which you have narrowed it down, and pass +description, the extent to which you have narrowed it down, and pass that off to whomever you believe is the maintainer of that section. A post to linux.dev.kernel isn't such a bad idea if you've done some work to narrow it down. @@ -214,6 +214,23 @@ And recompile the kernel with CONFIG_DEBUG_INFO enabled: gdb vmlinux (gdb) p vt_ioctl (gdb) l *(0x<address of vt_ioctl> + 0xda8) +or, as one command + (gdb) l *(vt_ioctl + 0xda8) + +If you have a call trace, such as :- +>Call Trace: +> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 +> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e +> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee +> ... +this shows the problem in the :jbd: module. You can load that module in gdb +and list the relevant code. + gdb fs/jbd/jbd.ko + (gdb) p log_wait_commit + (gdb) l *(0x<address> + 0xa3) +or + (gdb) l *(log_wait_commit + 0xa3) + Another very useful option of the Kernel Hacking section in menuconfig is Debug memory allocations. This will help you see whether data has been diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index 4215f69..3a882d9 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -172,7 +172,7 @@ <listitem><para>Chiplevel hardware encapsulation</para></listitem> </orderedlist> </para> - <sect1> + <sect1 id="Interrupt_control_flow"> <title>Interrupt control flow</title> <para> Each interrupt is described by an interrupt descriptor structure @@ -190,7 +190,7 @@ referenced by the assigned chip descriptor structure. </para> </sect1> - <sect1> + <sect1 id="Highlevel_Driver_API"> <title>Highlevel Driver API</title> <para> The highlevel Driver API consists of following functions: @@ -210,7 +210,7 @@ See the autogenerated function documentation for details. </para> </sect1> - <sect1> + <sect1 id="Highlevel_IRQ_flow_handlers"> <title>Highlevel IRQ flow handlers</title> <para> The generic layer provides a set of pre-defined irq-flow methods: @@ -224,9 +224,9 @@ specific) are assigned to specific interrupts by the architecture either during bootup or during device initialization. </para> - <sect2> + <sect2 id="Default_flow_implementations"> <title>Default flow implementations</title> - <sect3> + <sect3 id="Helper_functions"> <title>Helper functions</title> <para> The helper functions call the chip primitives and @@ -267,9 +267,9 @@ noop(irq) </para> </sect3> </sect2> - <sect2> + <sect2 id="Default_flow_handler_implementations"> <title>Default flow handler implementations</title> - <sect3> + <sect3 id="Default_Level_IRQ_flow_handler"> <title>Default Level IRQ flow handler</title> <para> handle_level_irq provides a generic implementation @@ -284,7 +284,7 @@ desc->chip->end(); </programlisting> </para> </sect3> - <sect3> + <sect3 id="Default_Edge_IRQ_flow_handler"> <title>Default Edge IRQ flow handler</title> <para> handle_edge_irq provides a generic implementation @@ -311,7 +311,7 @@ desc->chip->end(); </programlisting> </para> </sect3> - <sect3> + <sect3 id="Default_simple_IRQ_flow_handler"> <title>Default simple IRQ flow handler</title> <para> handle_simple_irq provides a generic implementation @@ -328,7 +328,7 @@ handle_IRQ_event(desc->action); </programlisting> </para> </sect3> - <sect3> + <sect3 id="Default_per_CPU_flow_handler"> <title>Default per CPU flow handler</title> <para> handle_percpu_irq provides a generic implementation @@ -349,7 +349,7 @@ desc->chip->end(); </para> </sect3> </sect2> - <sect2> + <sect2 id="Quirks_and_optimizations"> <title>Quirks and optimizations</title> <para> The generic functions are intended for 'clean' architectures and chips, @@ -358,7 +358,7 @@ desc->chip->end(); overriding the highlevel irq-flow handler. </para> </sect2> - <sect2> + <sect2 id="Delayed_interrupt_disable"> <title>Delayed interrupt disable</title> <para> This per interrupt selectable feature, which was introduced by Russell @@ -380,7 +380,7 @@ desc->chip->end(); </para> </sect2> </sect1> - <sect1> + <sect1 id="Chiplevel_hardware_encapsulation"> <title>Chiplevel hardware encapsulation</title> <para> The chip level hardware descriptor structure irq_chip diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 77436d7..059aaf2 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -165,6 +165,7 @@ X!Ilib/string.c !Emm/vmalloc.c !Imm/page_alloc.c !Emm/mempool.c +!Emm/dmapool.c !Emm/page-writeback.c !Emm/truncate.c </sect1> @@ -371,7 +372,6 @@ X!Iinclude/linux/device.h !Edrivers/base/class.c !Edrivers/base/firmware_class.c !Edrivers/base/transport_class.c -!Edrivers/base/dmapool.c <!-- Cannot be included, because attribute_container_add_class_device_adapter and attribute_container_classdev_to_container diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 01825ee..2e9d6b4 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -717,7 +717,7 @@ used, and when it gets full, throws out the least used one. <para> For our first example, we assume that all operations are in user context (ie. from system calls), so we can sleep. This means we can -use a semaphore to protect the cache and all the objects within +use a mutex to protect the cache and all the objects within it. Here's the code: </para> @@ -725,7 +725,7 @@ it. Here's the code: #include <linux/list.h> #include <linux/slab.h> #include <linux/string.h> -#include <asm/semaphore.h> +#include <linux/mutex.h> #include <asm/errno.h> struct object @@ -737,7 +737,7 @@ struct object }; /* Protects the cache, cache_num, and the objects within it */ -static DECLARE_MUTEX(cache_lock); +static DEFINE_MUTEX(cache_lock); static LIST_HEAD(cache); static unsigned int cache_num = 0; #define MAX_CACHE_SIZE 10 @@ -789,17 +789,17 @@ int cache_add(int id, const char *name) obj->id = id; obj->popularity = 0; - down(&cache_lock); + mutex_lock(&cache_lock); __cache_add(obj); - up(&cache_lock); + mutex_unlock(&cache_lock); return 0; } void cache_delete(int id) { - down(&cache_lock); + mutex_lock(&cache_lock); __cache_delete(__cache_find(id)); - up(&cache_lock); + mutex_unlock(&cache_lock); } int cache_find(int id, char *name) @@ -807,13 +807,13 @@ int cache_find(int id, char *name) struct object *obj; int ret = -ENOENT; - down(&cache_lock); + mutex_lock(&cache_lock); obj = __cache_find(id); if (obj) { ret = 0; strcpy(name, obj->name); } - up(&cache_lock); + mutex_unlock(&cache_lock); return ret; } </programlisting> @@ -853,7 +853,7 @@ The change is shown below, in standard patch format: the int popularity; }; --static DECLARE_MUTEX(cache_lock); +-static DEFINE_MUTEX(cache_lock); +static spinlock_t cache_lock = SPIN_LOCK_UNLOCKED; static LIST_HEAD(cache); static unsigned int cache_num = 0; @@ -870,22 +870,22 @@ The change is shown below, in standard patch format: the obj->id = id; obj->popularity = 0; -- down(&cache_lock); +- mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); __cache_add(obj); -- up(&cache_lock); +- mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return 0; } void cache_delete(int id) { -- down(&cache_lock); +- mutex_lock(&cache_lock); + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); __cache_delete(__cache_find(id)); -- up(&cache_lock); +- mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); } @@ -895,14 +895,14 @@ The change is shown below, in standard patch format: the int ret = -ENOENT; + unsigned long flags; -- down(&cache_lock); +- mutex_lock(&cache_lock); + spin_lock_irqsave(&cache_lock, flags); obj = __cache_find(id); if (obj) { ret = 0; strcpy(name, obj->name); } -- up(&cache_lock); +- mutex_unlock(&cache_lock); + spin_unlock_irqrestore(&cache_lock, flags); return ret; } diff --git a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl index f638221..fe7664c 100644 --- a/Documentation/DocBook/lsm.tmpl +++ b/Documentation/DocBook/lsm.tmpl @@ -33,7 +33,7 @@ </authorgroup> </articleinfo> -<sect1><title>Introduction</title> +<sect1 id="Introduction"><title>Introduction</title> <para> In March 2001, the National Security Agency (NSA) gave a presentation diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index 957cf5c..8e14585 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -80,7 +80,7 @@ struct member has a short description which is marked with an [XXX] identifier. The following chapters explain the meaning of those identifiers. </para> - <sect1> + <sect1 id="Function_identifiers_XXX"> <title>Function identifiers [XXX]</title> <para> The functions are marked with [XXX] identifiers in the short @@ -115,7 +115,7 @@ </para></listitem> </itemizedlist> </sect1> - <sect1> + <sect1 id="Struct_member_identifiers_XXX"> <title>Struct member identifiers [XXX]</title> <para> The struct members are marked with [XXX] identifiers in the @@ -159,7 +159,7 @@ basic functions and fill out some really board dependent members in the nand chip description structure. </para> - <sect1> + <sect1 id="Basic_defines"> <title>Basic defines</title> <para> At least you have to provide a mtd structure and @@ -185,7 +185,7 @@ static struct nand_chip board_chip; static unsigned long baseaddr; </programlisting> </sect1> - <sect1> + <sect1 id="Partition_defines"> <title>Partition defines</title> <para> If you want to divide your device into partitions, then @@ -204,7 +204,7 @@ static struct mtd_partition partition_info[] = { }; </programlisting> </sect1> - <sect1> + <sect1 id="Hardware_control_functions"> <title>Hardware control function</title> <para> The hardware control function provides access to the @@ -246,7 +246,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) } </programlisting> </sect1> - <sect1> + <sect1 id="Device_ready_function"> <title>Device ready function</title> <para> If the hardware interface has the ready busy pin of the NAND chip connected to a @@ -257,7 +257,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd) the function must not be defined and the function pointer this->dev_ready is set to NULL. </para> </sect1> - <sect1> + <sect1 id="Init_function"> <title>Init function</title> <para> The init function allocates memory and sets up all the board @@ -325,7 +325,7 @@ out: module_init(board_init); </programlisting> </sect1> - <sect1> + <sect1 id="Exit_function"> <title>Exit function</title> <para> The exit function is only neccecary if the driver is @@ -359,7 +359,7 @@ module_exit(board_cleanup); driver. For a list of functions which can be overridden by the board driver see the documentation of the nand_chip structure. </para> - <sect1> + <sect1 id="Multiple_chip_control"> <title>Multiple chip control</title> <para> The nand driver can control chip arrays. Therefor the @@ -419,9 +419,9 @@ static void board_select_chip (struct mtd_info *mtd, int chip) } </programlisting> </sect1> - <sect1> + <sect1 id="Hardware_ECC_support"> <title>Hardware ECC support</title> - <sect2> + <sect2 id="Functions_and_constants"> <title>Functions and constants</title> <para> The nand driver supports three different types of @@ -475,7 +475,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) </itemizedlist> </para> </sect2> - <sect2> + <sect2 id="Hardware_ECC_with_syndrome_calculation"> <title>Hardware ECC with syndrome calculation</title> <para> Many hardware ECC implementations provide Reed-Solomon @@ -500,7 +500,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) </para> </sect2> </sect1> - <sect1> + <sect1 id="Bad_Block_table_support"> <title>Bad block table support</title> <para> Most NAND chips mark the bad blocks at a defined @@ -552,7 +552,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) allows faster access than always checking the bad block information on the flash chip itself. </para> - <sect2> + <sect2 id="Flash_based_tables"> <title>Flash based tables</title> <para> It may be desired or neccecary to keep a bad block table in FLASH. @@ -587,7 +587,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) </itemizedlist> </para> </sect2> - <sect2> + <sect2 id="User_defined_tables"> <title>User defined tables</title> <para> User defined tables are created by filling out a @@ -676,7 +676,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip) </para> </sect2> </sect1> - <sect1> + <sect1 id="Spare_area_placement"> <title>Spare area (auto)placement</title> <para> The nand driver implements different possibilities for @@ -730,7 +730,7 @@ struct nand_oobinfo { </para></listitem> </itemizedlist> </para> - <sect2> + <sect2 id="Placement_defined_by_fs_driver"> <title>Placement defined by fs driver</title> <para> The calling function provides a pointer to a nand_oobinfo @@ -760,7 +760,7 @@ struct nand_oobinfo { done according to the given scheme in the nand_oobinfo structure. </para> </sect2> - <sect2> + <sect2 id="Automatic_placement"> <title>Automatic placement</title> <para> Automatic placement uses the built in defaults to place the @@ -774,7 +774,7 @@ struct nand_oobinfo { done according to the default builtin scheme. </para> </sect2> - <sect2> + <sect2 id="User_space_placement_selection"> <title>User space placement selection</title> <para> All non ecc functions like mtd->read and mtd->write use an internal @@ -789,9 +789,9 @@ struct nand_oobinfo { </para> </sect2> </sect1> - <sect1> + <sect1 id="Spare_area_autoplacement_default"> <title>Spare area autoplacement default schemes</title> - <sect2> + <sect2 id="pagesize_256"> <title>256 byte pagesize</title> <informaltable><tgroup cols="3"><tbody> <row> @@ -843,7 +843,7 @@ pages this byte is reserved</entry> </row> </tbody></tgroup></informaltable> </sect2> - <sect2> + <sect2 id="pagesize_512"> <title>512 byte pagesize</title> <informaltable><tgroup cols="3"><tbody> <row> @@ -906,7 +906,7 @@ in this page</entry> </row> </tbody></tgroup></informaltable> </sect2> - <sect2> + <sect2 id="pagesize_2048"> <title>2048 byte pagesize</title> <informaltable><tgroup cols="3"><tbody> <row> @@ -1126,9 +1126,9 @@ in this page</entry> <para> This chapter describes the constants which might be relevant for a driver developer. </para> - <sect1> + <sect1 id="Chip_option_constants"> <title>Chip option constants</title> - <sect2> + <sect2 id="Constants_for_chip_id_table"> <title>Constants for chip id table</title> <para> These constants are defined in nand.h. They are ored together to describe @@ -1153,7 +1153,7 @@ in this page</entry> </programlisting> </para> </sect2> - <sect2> + <sect2 id="Constants_for_runtime_options"> <title>Constants for runtime options</title> <para> These constants are defined in nand.h. They are ored together to describe @@ -1171,7 +1171,7 @@ in this page</entry> </sect2> </sect1> - <sect1> + <sect1 id="EEC_selection_constants"> <title>ECC selection constants</title> <para> Use these constants to select the ECC algorithm. @@ -1192,7 +1192,7 @@ in this page</entry> </para> </sect1> - <sect1> + <sect1 id="Hardware_control_related_constants"> <title>Hardware control related constants</title> <para> These constants describe the requested hardware access function when @@ -1218,7 +1218,7 @@ in this page</entry> </para> </sect1> - <sect1> + <sect1 id="Bad_block_table_constants"> <title>Bad block table related constants</title> <para> These constants describe the options used for bad block diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl index 2de84dc..1fd6a1e 100644 --- a/Documentation/DocBook/procfs-guide.tmpl +++ b/Documentation/DocBook/procfs-guide.tmpl @@ -85,7 +85,7 @@ - <preface> + <preface id="Preface"> <title>Preface</title> <para> @@ -230,7 +230,7 @@ - <sect1> + <sect1 id="Creating_a_symlink"> <title>Creating a symlink</title> <funcsynopsis> @@ -254,7 +254,7 @@ </para> </sect1> - <sect1> + <sect1 id="Creating_a_directory"> <title>Creating a directory</title> <funcsynopsis> @@ -274,7 +274,7 @@ - <sect1> + <sect1 id="Removing_an_entry"> <title>Removing an entry</title> <funcsynopsis> @@ -340,7 +340,7 @@ entry->write_proc = write_proc_foo; - <sect1> + <sect1 id="Reading_data"> <title>Reading data</title> <para> @@ -448,7 +448,7 @@ entry->write_proc = write_proc_foo; - <sect1> + <sect1 id="Writing_data"> <title>Writing data</title> <para> @@ -579,7 +579,7 @@ int foo_read_func(char *page, char **start, off_t off, - <sect1> + <sect1 id="Modules"> <title>Modules</title> <para> @@ -599,7 +599,7 @@ entry->owner = THIS_MODULE; - <sect1> + <sect1 id="Mode_and_ownership"> <title>Mode and ownership</title> <para> diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl index 1becf27..b9e143e 100644 --- a/Documentation/DocBook/rapidio.tmpl +++ b/Documentation/DocBook/rapidio.tmpl @@ -77,11 +77,11 @@ <chapter id="bugs"> <title>Known Bugs and Limitations</title> - <sect1> + <sect1 id="known_bugs"> <title>Bugs</title> <para>None. ;)</para> </sect1> - <sect1> + <sect1 id="Limitations"> <title>Limitations</title> <para> <orderedlist> @@ -100,7 +100,7 @@ on devices, request/map memory region resources, and manage mailboxes/doorbells. </para> - <sect1> + <sect1 id="Functions"> <title>Functions</title> !Iinclude/linux/rio_drv.h !Edrivers/rapidio/rio-driver.c @@ -116,26 +116,26 @@ subsystem. </para> - <sect1><title>Structures</title> + <sect1 id="Structures"><title>Structures</title> !Iinclude/linux/rio.h </sect1> - <sect1><title>Enumeration and Discovery</title> + <sect1 id="Enumeration_and_Discovery"><title>Enumeration and Discovery</title> !Idrivers/rapidio/rio-scan.c </sect1> - <sect1><title>Driver functionality</title> + <sect1 id="Driver_functionality"><title>Driver functionality</title> !Idrivers/rapidio/rio.c !Idrivers/rapidio/rio-access.c </sect1> - <sect1><title>Device model support</title> + <sect1 id="Device_model_support"><title>Device model support</title> !Idrivers/rapidio/rio-driver.c </sect1> - <sect1><title>Sysfs support</title> + <sect1 id="Sysfs_support"><title>Sysfs support</title> !Idrivers/rapidio/rio-sysfs.c </sect1> - <sect1><title>PPC32 support</title> -!Iarch/ppc/kernel/rio.c -!Earch/ppc/syslib/ppc85xx_rio.c -!Iarch/ppc/syslib/ppc85xx_rio.c + <sect1 id="PPC32_support"><title>PPC32 support</title> +!Iarch/powerpc/kernel/rio.c +!Earch/powerpc/sysdev/fsl_rio.c +!Iarch/powerpc/sysdev/fsl_rio.c </sect1> </chapter> diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl index 3d2f31b..4acc732 100644 --- a/Documentation/DocBook/s390-drivers.tmpl +++ b/Documentation/DocBook/s390-drivers.tmpl @@ -59,7 +59,7 @@ <title>Introduction</title> <para> This document describes the interfaces available for device drivers that - drive s390 based channel attached devices. This includes interfaces for + drive s390 based channel attached I/O devices. This includes interfaces for interaction with the hardware and interfaces for interacting with the common driver core. Those interfaces are provided by the s390 common I/O layer. @@ -86,9 +86,10 @@ The ccw bus typically contains the majority of devices available to a s390 system. Named after the channel command word (ccw), the basic command structure used to address its devices, the ccw bus contains - so-called channel attached devices. They are addressed via subchannels, - visible on the css bus. A device driver, however, will never interact - with the subchannel directly, but only via the device on the ccw bus, + so-called channel attached devices. They are addressed via I/O + subchannels, visible on the css bus. A device driver for + channel-attached devices, however, will never interact with the + subchannel directly, but only via the I/O device on the ccw bus, the ccw device. </para> <sect1 id="channelIO"> @@ -116,7 +117,6 @@ !Iinclude/asm-s390/ccwdev.h !Edrivers/s390/cio/device.c !Edrivers/s390/cio/device_ops.c -!Edrivers/s390/cio/airq.c </sect1> <sect1 id="cmf"> <title>The channel-measurement facility</title> @@ -147,4 +147,15 @@ </sect1> </chapter> + <chapter id="genericinterfaces"> + <title>Generic interfaces</title> + <para> + Some interfaces are available to other drivers that do not necessarily + have anything to do with the busses described above, but still are + indirectly using basic infrastructure in the common I/O layer. + One example is the support for adapter interrupts. + </para> +!Edrivers/s390/cio/airq.c + </chapter> + </book> diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl index f299ab1..10a150a 100644 --- a/Documentation/DocBook/scsi.tmpl +++ b/Documentation/DocBook/scsi.tmpl @@ -12,7 +12,7 @@ <surname>Bottomley</surname> <affiliation> <address> - <email>James.Bottomley@steeleye.com</email> + <email>James.Bottomley@hansenpartnership.com</email> </address> </affiliation> </author> diff --git a/Documentation/DocBook/videobook.tmpl b/Documentation/DocBook/videobook.tmpl index b3d93ee..8981779 100644 --- a/Documentation/DocBook/videobook.tmpl +++ b/Documentation/DocBook/videobook.tmpl @@ -170,7 +170,7 @@ int __init myradio_init(struct video_init *v) <para> The types available are </para> - <table frame="all"><title>Device Types</title> + <table frame="all" id="Device_Types"><title>Device Types</title> <tgroup cols="3" align="left"> <tbody> <row> @@ -291,7 +291,7 @@ static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) allows the applications to find out what sort of a card they have found and to figure out what they want to do about it. The fields in the structure are </para> - <table frame="all"><title>struct video_capability fields</title> + <table frame="all" id="video_capability_fields"><title>struct video_capability fields</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -365,7 +365,7 @@ static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) <para> The video_tuner structure has the following fields </para> - <table frame="all"><title>struct video_tuner fields</title> + <table frame="all" id="video_tuner_fields"><title>struct video_tuner fields</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -398,7 +398,7 @@ static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) </tgroup> </table> - <table frame="all"><title>struct video_tuner flags</title> + <table frame="all" id="video_tuner_flags"><title>struct video_tuner flags</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -421,7 +421,7 @@ static int radio_ioctl(struct video_device *dev, unsigned int cmd, void *arg) </tgroup> </table> - <table frame="all"><title>struct video_tuner modes</title> + <table frame="all" id="video_tuner_modes"><title>struct video_tuner modes</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -572,7 +572,7 @@ static int current_volume=0; <para> Then we fill in the video_audio structure. This has the following format </para> - <table frame="all"><title>struct video_audio fields</title> + <table frame="all" id="video_audio_fields"><title>struct video_audio fields</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -607,7 +607,7 @@ static int current_volume=0; </tgroup> </table> - <table frame="all"><title>struct video_audio flags</title> + <table frame="all" id="video_audio_flags"><title>struct video_audio flags</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -625,7 +625,7 @@ static int current_volume=0; </tgroup> </table> - <table frame="all"><title>struct video_audio modes</title> + <table frame="all" id="video_audio_modes"><title>struct video_audio modes</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -775,7 +775,7 @@ module_exit(cleanup); </para> </sect1> </chapter> - <chapter> + <chapter id="Video_Capture_Devices"> <title>Video Capture Devices</title> <sect1 id="introvid"> <title>Video Capture Device Types</title> @@ -855,7 +855,7 @@ static struct video_device my_camera We use the extra video capability flags that did not apply to the radio interface. The video related flags are </para> - <table frame="all"><title>Capture Capabilities</title> + <table frame="all" id="Capture_Capabilities"><title>Capture Capabilities</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1195,7 +1195,7 @@ static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) inputs to the video card). Our example card has a single camera input. The fields in the structure are </para> - <table frame="all"><title>struct video_channel fields</title> + <table frame="all" id="video_channel_fields"><title>struct video_channel fields</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1218,7 +1218,7 @@ static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) </tbody> </tgroup> </table> - <table frame="all"><title>struct video_channel flags</title> + <table frame="all" id="video_channel_flags"><title>struct video_channel flags</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1229,7 +1229,7 @@ static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) </tbody> </tgroup> </table> - <table frame="all"><title>struct video_channel types</title> + <table frame="all" id="video_channel_types"><title>struct video_channel types</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1242,7 +1242,7 @@ static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) </tbody> </tgroup> </table> - <table frame="all"><title>struct video_channel norms</title> + <table frame="all" id="video_channel_norms"><title>struct video_channel norms</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1328,7 +1328,7 @@ static int camera_ioctl(struct video_device *dev, unsigned int cmd, void *arg) for every other pixel in the image. The other common formats the interface defines are </para> - <table frame="all"><title>Framebuffer Encodings</title> + <table frame="all" id="Framebuffer_Encodings"><title>Framebuffer Encodings</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1466,7 +1466,7 @@ static struct video_buffer capture_fb; display. The video_window structure is used to describe the way the image should be displayed. </para> - <table frame="all"><title>struct video_window fields</title> + <table frame="all" id="video_window_fields"><title>struct video_window fields</title> <tgroup cols="2" align="left"> <tbody> <row> @@ -1503,7 +1503,7 @@ static struct video_buffer capture_fb; <para> Each clip is a struct video_clip which has the following fields </para> - <table frame="all"><title>video_clip fields</title> + <table frame="all" id="video_clip_fields"><title>video_clip fields</title> <tgroup cols="2" align="left"> <tbody> <row> diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl index a507876..42c75ba 100644 --- a/Documentation/DocBook/z8530book.tmpl +++ b/Documentation/DocBook/z8530book.tmpl @@ -77,7 +77,7 @@ </para> </chapter> - <chapter> + <chapter id="Driver_Modes"> <title>Driver Modes</title> <para> The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices @@ -108,7 +108,7 @@ </para> </chapter> - <chapter> + <chapter id="Using_the_Z85230_driver"> <title>Using the Z85230 driver</title> <para> The Z85230 driver provides the back end interface to your board. To @@ -174,7 +174,7 @@ </para> </chapter> - <chapter> + <chapter id="Attaching_Network_Interfaces"> <title>Attaching Network Interfaces</title> <para> If you wish to use the network interface facilities of the driver, @@ -216,7 +216,7 @@ </para> </chapter> - <chapter> + <chapter id="Configuring_And_Activating_The_Port"> <title>Configuring And Activating The Port</title> <para> The Z85230 driver provides helper functions and tables to load the @@ -300,7 +300,7 @@ </para> </chapter> - <chapter> + <chapter id="Network_Layer_Functions"> <title>Network Layer Functions</title> <para> The Z8530 layer provides functions to queue packets for @@ -327,7 +327,7 @@ </para> </chapter> - <chapter> + <chapter id="Porting_The_Z8530_Driver"> <title>Porting The Z8530 Driver</title> <para> The Z8530 driver is written to be portable. In DMA mode it makes diff --git a/Documentation/Smack.txt b/Documentation/Smack.txt new file mode 100644 index 0000000..989c2fc --- /dev/null +++ b/Documentation/Smack.txt @@ -0,0 +1,493 @@ + + + "Good for you, you've decided to clean the elevator!" + - The Elevator, from Dark Star + +Smack is the the Simplified Mandatory Access Control Kernel. +Smack is a kernel based implementation of mandatory access +control that includes simplicity in its primary design goals. + +Smack is not the only Mandatory Access Control scheme +available for Linux. Those new to Mandatory Access Control +are encouraged to compare Smack with the other mechanisms +available to determine which is best suited to the problem +at hand. + +Smack consists of three major components: + - The kernel + - A start-up script and a few modified applications + - Configuration data + +The kernel component of Smack is implemented as a Linux +Security Modules (LSM) module. It requires netlabel and +works best with file systems that support extended attributes, +although xattr support is not strictly required. +It is safe to run a Smack kernel under a "vanilla" distribution. +Smack kernels use the CIPSO IP option. Some network +configurations are intolerant of IP options and can impede +access to systems that use them as Smack does. + +The startup script etc-init.d-smack should be installed +in /etc/init.d/smack and should be invoked early in the +start-up process. On Fedora rc5.d/S02smack is recommended. +This script ensures that certain devices have the correct +Smack attributes and loads the Smack configuration if +any is defined. This script invokes two programs that +ensure configuration data is properly formatted. These +programs are /usr/sbin/smackload and /usr/sin/smackcipso. +The system will run just fine without these programs, +but it will be difficult to set access rules properly. + +A version of "ls" that provides a "-M" option to display +Smack labels on long listing is available. + +A hacked version of sshd that allows network logins by users +with specific Smack labels is available. This version does +not work for scp. You must set the /etc/ssh/sshd_config +line: + UsePrivilegeSeparation no + +The format of /etc/smack/usr is: + + username smack + +In keeping with the intent of Smack, configuration data is +minimal and not strictly required. The most important +configuration step is mounting the smackfs pseudo filesystem. + +Add this line to /etc/fstab: + + smackfs /smack smackfs smackfsdef=* 0 0 + +and create the /smack directory for mounting. + +Smack uses extended attributes (xattrs) to store file labels. +The command to set a Smack label on a file is: + + # attr -S -s SMACK64 -V "value" path + +NOTE: Smack labels are limited to 23 characters. The attr command + does not enforce this restriction and can be used to set + invalid Smack labels on files. + +If you don't do anything special all users will get the floor ("_") +label when they log in. If you do want to log in via the hacked ssh +at other labels use the attr command to set the smack value on the +home directory and it's contents. + +You can add access rules in /etc/smack/accesses. They take the form: + + subjectlabel objectlabel access + +access is a combination of the letters rwxa which specify the +kind of access permitted a subject with subjectlabel on an +object with objectlabel. If there is no rule no access is allowed. + +A process can see the smack label it is running with by +reading /proc/self/attr/current. A privileged process can +set the process smack by writing there. + +Look for additional programs on http://schaufler-ca.com + +From the Smack Whitepaper: + +The Simplified Mandatory Access Control Kernel + +Casey Schaufler +casey@schaufler-ca.com + +Mandatory Access Control + +Computer systems employ a variety of schemes to constrain how information is +shared among the people and services using the machine. Some of these schemes +allow the program or user to decide what other programs or users are allowed +access to pieces of data. These schemes are called discretionary access +control mechanisms because the access control is specified at the discretion +of the user. Other schemes do not leave the decision regarding what a user or +program can access up to users or programs. These schemes are called mandatory +access control mechanisms because you don't have a choice regarding the users +or programs that have access to pieces of data. + +Bell & LaPadula + +From the middle of the 1980's until the turn of the century Mandatory Access +Control (MAC) was very closely associated with the Bell & LaPadula security +model, a mathematical description of the United States Department of Defense +policy for marking paper documents. MAC in this form enjoyed a following +within the Capital Beltway and Scandinavian supercomputer centers but was +often sited as failing to address general needs. + +Domain Type Enforcement + +Around the turn of the century Domain Type Enforcement (DTE) became popular. +This scheme organizes users, programs, and data into domains that are +protected from each other. This scheme has been widely deployed as a component +of popular Linux distributions. The administrative overhead required to +maintain this scheme and the detailed understanding of the whole system +necessary to provide a secure domain mapping leads to the scheme being +disabled or used in limited ways in the majority of cases. + +Smack + +Smack is a Mandatory Access Control mechanism designed to provide useful MAC +while avoiding the pitfalls of its predecessors. The limitations of Bell & +LaPadula are addressed by providing a scheme whereby access can be controlled +according to the requirements of the system and its purpose rather than those +imposed by an arcane government policy. The complexity of Domain Type +Enforcement and avoided by defining access controls in terms of the access +modes already in use. + +Smack Terminology + +The jargon used to talk about Smack will be familiar to those who have dealt +with other MAC systems and shouldn't be too difficult for the uninitiated to +pick up. There are four terms that are used in a specific way and that are +especially important: + + Subject: A subject is an active entity on the computer system. + On Smack a subject is a task, which is in turn the basic unit + of execution. + + Object: An object is a passive entity on the computer system. + On Smack files of all types, IPC, and tasks can be objects. + + Access: Any attempt by a subject to put information into or get + information from an object is an access. + + Label: Data that identifies the Mandatory Access Control + characteristics of a subject or an object. + +These definitions are consistent with the traditional use in the security +community. There are also some terms from Linux that are likely to crop up: + + Capability: A task that possesses a capability has permission to + violate an aspect of the system security policy, as identified by + the specific capability. A task that possesses one or more + capabilities is a privileged task, whereas a task with no + capabilities is an unprivileged task. + + Privilege: A task that is allowed to violate the system security + policy is said to have privilege. As of this writing a task can + have privilege either by possessing capabilities or by having an + effective user of root. + +Smack Basics + +Smack is an extension to a Linux system. It enforces additional restrictions +on what subjects can access which objects, based on the labels attached to +each of the subject and the object. + +Labels + +Smack labels are ASCII character strings, one to twenty-three characters in +length. Single character labels using special characters, that being anything +other than a letter or digit, are reserved for use by the Smack development +team. Smack labels are unstructured, case sensitive, and the only operation +ever performed on them is comparison for equality. Smack labels cannot +contain unprintable characters or the "/" (slash) character. + +There are some predefined labels: + + _ Pronounced "floor", a single underscore character. + ^ Pronounced "hat", a single circumflex character. + * Pronounced "star", a single asterisk character. + ? Pronounced "huh", a single question mark character. + +Every task on a Smack system is assigned a label. System tasks, such as +init(8) and systems daemons, are run with the floor ("_") label. User tasks +are assigned labels according to the specification found in the +/etc/smack/user configuration file. + +Access Rules + +Smack uses the traditional access modes of Linux. These modes are read, +execute, write, and occasionally append. There are a few cases where the +access mode may not be obvious. These include: + + Signals: A signal is a write operation from the subject task to + the object task. + Internet Domain IPC: Transmission of a packet is considered a + write operation from the source task to the destination task. + +Smack restricts access based on the label attached to a subject and the label +attached to the object it is trying to access. The rules enforced are, in +order: + + 1. Any access requested by a task labeled "*" is denied. + 2. A read or execute access requested by a task labeled "^" + is permitted. + 3. A read or execute access requested on an object labeled "_" + is permitted. + 4. Any access requested on an object labeled "*" is permitted. + 5. Any access requested by a task on an object with the same + label is permitted. + 6. Any access requested that is explicitly defined in the loaded + rule set is permitted. + 7. Any other access is denied. + +Smack Access Rules + +With the isolation provided by Smack access separation is simple. There are +many interesting cases where limited access by subjects to objects with +different labels is desired. One example is the familiar spy model of +sensitivity, where a scientist working on a highly classified project would be +able to read documents of lower classifications and anything she writes will +be "born" highly classified. To accommodate such schemes Smack includes a +mechanism for specifying rules allowing access between labels. + +Access Rule Format + +The format of an access rule is: + + subject-label object-label access + +Where subject-label is the Smack label of the task, object-label is the Smack +label of the thing being accessed, and access is a string specifying the sort +of access allowed. The Smack labels are limited to 23 characters. The access +specification is searched for letters that describe access modes: + + a: indicates that append access should be granted. + r: indicates that read access should be granted. + w: indicates that write access should be granted. + x: indicates that execute access should be granted. + +Uppercase values for the specification letters are allowed as well. +Access mode specifications can be in any order. Examples of acceptable rules +are: + + TopSecret Secret rx + Secret Unclass R + Manager Game x + User HR w + New Old rRrRr + Closed Off - + +Examples of unacceptable rules are: + + Top Secret Secret rx + Ace Ace r + Odd spells waxbeans + +Spaces are not allowed in labels. Since a subject always has access to files +with the same label specifying a rule for that case is pointless. Only +valid letters (rwxaRWXA) and the dash ('-') character are allowed in +access specifications. The dash is a placeholder, so "a-r" is the same +as "ar". A lone dash is used to specify that no access should be allowed. + +Applying Access Rules + +The developers of Linux rarely define new sorts of things, usually importing +schemes and concepts from other systems. Most often, the other systems are +variants of Unix. Unix has many endearing properties, but consistency of +access control models is not one of them. Smack strives to treat accesses as +uniformly as is sensible while keeping with the spirit of the underlying +mechanism. + +File system objects including files, directories, named pipes, symbolic links, +and devices require access permissions that closely match those used by mode +bit access. To open a file for reading read access is required on the file. To +search a directory requires execute access. Creating a file with write access +requires both read and write access on the containing directory. Deleting a +file requires read and write access to the file and to the containing +directory. It is possible that a user may be able to see that a file exists +but not any of its attributes by the circumstance of having read access to the +containing directory but not to the differently labeled file. This is an +artifact of the file name being data in the directory, not a part of the file. + +IPC objects, message queues, semaphore sets, and memory segments exist in flat +namespaces and access requests are only required to match the object in +question. + +Process objects reflect tasks on the system and the Smack label used to access +them is the same Smack label that the task would use for its own access +attempts. Sending a signal via the kill() system call is a write operation +from the signaler to the recipient. Debugging a process requires both reading +and writing. Creating a new task is an internal operation that results in two +tasks with identical Smack labels and requires no access checks. + +Sockets are data structures attached to processes and sending a packet from +one process to another requires that the sender have write access to the +receiver. The receiver is not required to have read access to the sender. + +Setting Access Rules + +The configuration file /etc/smack/accesses contains the rules to be set at +system startup. The contents are written to the special file /smack/load. +Rules can be written to /smack/load at any time and take effect immediately. +For any pair of subject and object labels there can be only one rule, with the +most recently specified overriding any earlier specification. + +The program smackload is provided to ensure data is formatted +properly when written to /smack/load. This program reads lines +of the form + + subjectlabel objectlabel mode. + +Task Attribute + +The Smack label of a process can be read from /proc/<pid>/attr/current. A +process can read its own Smack label from /proc/self/attr/current. A +privileged process can change its own Smack label by writing to +/proc/self/attr/current but not the label of another process. + +File Attribute + +The Smack label of a filesystem object is stored as an extended attribute +named SMACK64 on the file. This attribute is in the security namespace. It can +only be changed by a process with privilege. + +Privilege + +A process with CAP_MAC_OVERRIDE is privileged. + +Smack Networking + +As mentioned before, Smack enforces access control on network protocol +transmissions. Every packet sent by a Smack process is tagged with its Smack +label. This is done by adding a CIPSO tag to the header of the IP packet. Each +packet received is expected to have a CIPSO tag that identifies the label and +if it lacks such a tag the network ambient label is assumed. Before the packet +is delivered a check is made to determine that a subject with the label on the +packet has write access to the receiving process and if that is not the case +the packet is dropped. + +CIPSO Configuration + +It is normally unnecessary to specify the CIPSO configuration. The default +values used by the system handle all internal cases. Smack will compose CIPSO +label values to match the Smack labels being used without administrative +intervention. Unlabeled packets that come into the system will be given the +ambient label. + +Smack requires configuration in the case where packets from a system that is +not smack that speaks CIPSO may be encountered. Usually this will be a Trusted +Solaris system, but there are other, less widely deployed systems out there. +CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level, +and a category set with each packet. The DOI is intended to identify a group +of systems that use compatible labeling schemes, and the DOI specified on the +smack system must match that of the remote system or packets will be +discarded. The DOI is 3 by default. The value can be read from /smack/doi and +can be changed by writing to /smack/doi. + +The label and category set are mapped to a Smack label as defined in +/etc/smack/cipso. + +A Smack/CIPSO mapping has the form: + + smack level [category [category]*] + +Smack does not expect the level or category sets to be related in any +particular way and does not assume or assign accesses based on them. Some +examples of mappings: + + TopSecret 7 + TS:A,B 7 1 2 + SecBDE 5 2 4 6 + RAFTERS 7 12 26 + +The ":" and "," characters are permitted in a Smack label but have no special +meaning. + +The mapping of Smack labels to CIPSO values is defined by writing to +/smack/cipso. Again, the format of data written to this special file +is highly restrictive, so the program smackcipso is provided to +ensure the writes are done properly. This program takes mappings +on the standard input and sends them to /smack/cipso properly. + +In addition to explicit mappings Smack supports direct CIPSO mappings. One +CIPSO level is used to indicate that the category set passed in the packet is +in fact an encoding of the Smack label. The level used is 250 by default. The +value can be read from /smack/direct and changed by writing to /smack/direct. + +Socket Attributes + +There are two attributes that are associated with sockets. These attributes +can only be set by privileged tasks, but any task can read them for their own +sockets. + + SMACK64IPIN: The Smack label of the task object. A privileged + program that will enforce policy may set this to the star label. + + SMACK64IPOUT: The Smack label transmitted with outgoing packets. + A privileged program may set this to match the label of another + task with which it hopes to communicate. + +Writing Applications for Smack + +There are three sorts of applications that will run on a Smack system. How an +application interacts with Smack will determine what it will have to do to +work properly under Smack. + +Smack Ignorant Applications + +By far the majority of applications have no reason whatever to care about the +unique properties of Smack. Since invoking a program has no impact on the +Smack label associated with the process the only concern likely to arise is +whether the process has execute access to the program. + +Smack Relevant Applications + +Some programs can be improved by teaching them about Smack, but do not make +any security decisions themselves. The utility ls(1) is one example of such a +program. + +Smack Enforcing Applications + +These are special programs that not only know about Smack, but participate in +the enforcement of system policy. In most cases these are the programs that +set up user sessions. There are also network services that provide information +to processes running with various labels. + +File System Interfaces + +Smack maintains labels on file system objects using extended attributes. The +Smack label of a file, directory, or other file system object can be obtained +using getxattr(2). + + len = getxattr("/", "security.SMACK64", value, sizeof (value)); + +will put the Smack label of the root directory into value. A privileged +process can set the Smack label of a file system object with setxattr(2). + + len = strlen("Rubble"); + rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0); + +will set the Smack label of /foo to "Rubble" if the program has appropriate +privilege. + +Socket Interfaces + +The socket attributes can be read using fgetxattr(2). + +A privileged process can set the Smack label of outgoing packets with +fsetxattr(2). + + len = strlen("Rubble"); + rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0); + +will set the Smack label "Rubble" on packets going out from the socket if the +program has appropriate privilege. + + rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0); + +will set the Smack label "*" as the object label against which incoming +packets will be checked if the program has appropriate privilege. + +Administration + +Smack supports some mount options: + + smackfsdef=label: specifies the label to give files that lack + the Smack label extended attribute. + + smackfsroot=label: specifies the label to assign the root of the + file system if it lacks the Smack extended attribute. + + smackfshat=label: specifies a label that must have read access to + all labels set on the filesystem. Not yet enforced. + + smackfsfloor=label: specifies a label to which all labels set on the + filesystem must have read access. Not yet enforced. + +These mount options apply to all file system types. + diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 681e2b3..08a1ed1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -220,20 +220,8 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. - -WARNING: Some mailers like Mozilla send your messages with ----- message header ---- -Content-Type: text/plain; charset=us-ascii; format=flowed ----- message header ---- -The problem is that "format=flowed" makes some of the mailers -on receiving side to replace TABs with spaces and do similar -changes. Thus the patches from you can look corrupted. - -To fix this just make your mozilla defaults/pref/mailnews.js file to look like: -pref("mailnews.send_plaintext_flowed", false); // RFC 2646======= -pref("mailnews.display.disable_format_flowed_support", true); - - +See Documentation/email-clients.txt for hints about configuring +your e-mail client so that it sends your patches untouched. 8) E-mail size. diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index d6cb1a8..40121b5 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -168,7 +168,7 @@ int get_family_id(int sd) char buf[256]; } ans; - int id, rc; + int id = 0, rc; struct nlattr *na; int rep_len; @@ -209,7 +209,7 @@ void print_delayacct(struct taskstats *t) void task_context_switch_counts(struct taskstats *t) { printf("\n\nTask %15s%15s\n" - " %15lu%15lu\n", + " %15llu%15llu\n", "voluntary", "nonvoluntary", t->nvcsw, t->nivcsw); } @@ -399,7 +399,7 @@ int main(int argc, char *argv[]) goto done; } - PRINTF("nlmsghdr size=%d, nlmsg_len=%d, rep_len=%d\n", + PRINTF("nlmsghdr size=%zu, nlmsg_len=%d, rep_len=%d\n", sizeof(struct nlmsghdr), msg.n.nlmsg_len, rep_len); diff --git a/Documentation/acpi/dsdt-override.txt b/Documentation/acpi/dsdt-override.txt new file mode 100644 index 0000000..5008f25 --- /dev/null +++ b/Documentation/acpi/dsdt-override.txt @@ -0,0 +1,15 @@ +Linux supports two methods of overriding the BIOS DSDT: + +CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel. + +CONFIG_ACPI_CUSTOM_DSDT_INITRD adds the image to the initrd. + +When to use these methods is described in detail on the +Linux/ACPI home page: +http://www.lesswatts.org/projects/acpi/overridingDSDT.php + +Note that if both options are used, the DSDT supplied +by the INITRD method takes precedence. + +Documentation/initramfs-add-dsdt.sh is provided for convenience +for use with the CONFIG_ACPI_CUSTOM_DSDT_INITRD method. diff --git a/Documentation/acpi/initramfs-add-dsdt.sh b/Documentation/acpi/initramfs-add-dsdt.sh new file mode 100755 index 0000000..17ef6e8 --- /dev/null +++ b/Documentation/acpi/initramfs-add-dsdt.sh @@ -0,0 +1,43 @@ +#!/bin/bash +# Adds a DSDT file to the initrd (if it's an initramfs) +# first argument is the name of archive +# second argument is the name of the file to add +# The file will be copied as /DSDT.aml + +# 20060126: fix "Premature end of file" with some old cpio (Roland Robic) +# 20060205: this time it should really work + +# check the arguments +if [ $# -ne 2 ]; then + program_name=$(basename $0) + echo "\ +$program_name: too few arguments +Usage: $program_name initrd-name.img DSDT-to-add.aml +Adds a DSDT file to an initrd (in initramfs format) + + initrd-name.img: filename of the initrd in initramfs format + DSDT-to-add.aml: filename of the DSDT file to add + " 1>&2 + exit 1 +fi + +# we should check it's an initramfs + +tempcpio=$(mktemp -d) +# cleanup on exit, hangup, interrupt, quit, termination +trap 'rm -rf $tempcpio' 0 1 2 3 15 + +# extract the archive +gunzip -c "$1" > "$tempcpio"/initramfs.cpio || exit 1 + +# copy the DSDT file at the root of the directory so that we can call it "/DSDT.aml" +cp -f "$2" "$tempcpio"/DSDT.aml + +# add the file +cd "$tempcpio" +(echo DSDT.aml | cpio --quiet -H newc -o -A -O "$tempcpio"/initramfs.cpio) || exit 1 +cd "$OLDPWD" + +# re-compress the archive +gzip -c "$tempcpio"/initramfs.cpio > "$1" + diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt new file mode 100644 index 0000000..f6efb1e --- /dev/null +++ b/Documentation/acpi/method-tracing.txt @@ -0,0 +1,26 @@ +/sys/module/acpi/parameters/: + +trace_method_name + The AML method name that the user wants to trace + +trace_debug_layer + The temporary debug_layer used when tracing the method. + Using 0xffffffff by default if it is 0. + +trace_debug_level + The temporary debug_level used when tracing the method. + Using 0x00ffffff by default if it is 0. + +trace_state + The status of the tracing feature. + + "enabled" means this feature is enabled + and the AML method is traced every time it's executed. + + "1" means this feature is enabled and the AML method + will only be traced during the next execution. + + "disabled" means this feature is disabled. + Users can enable/disable this debug tracing feature by + "echo string > /sys/module/acpi/parameters/trace_state". + "string" should be one of "enable", "disable" and "1". diff --git a/Documentation/aoe/mkdevs.sh b/Documentation/aoe/mkdevs.sh index 97374aa..44c0ab7 100644 --- a/Documentation/aoe/mkdevs.sh +++ b/Documentation/aoe/mkdevs.sh @@ -29,6 +29,8 @@ rm -f $dir/interfaces mknod -m 0200 $dir/interfaces c $MAJOR 4 rm -f $dir/revalidate mknod -m 0200 $dir/revalidate c $MAJOR 5 +rm -f $dir/flush +mknod -m 0200 $dir/flush c $MAJOR 6 export n_partitions mkshelf=`echo $0 | sed 's!mkdevs!mkshelf!'` diff --git a/Documentation/aoe/udev-install.sh b/Documentation/aoe/udev-install.sh index 6449911..15e86f5 100644 --- a/Documentation/aoe/udev-install.sh +++ b/Documentation/aoe/udev-install.sh @@ -23,7 +23,10 @@ fi # /etc/udev/rules.d # rules_d="`sed -n '/^udev_rules=/{ s!udev_rules=!!; s!\"!!g; p; }' $conf`" -if test -z "$rules_d" || test ! -d "$rules_d"; then +if test -z "$rules_d" ; then + rules_d=/etc/udev/rules.d +fi +if test ! -d "$rules_d"; then echo "$me Error: cannot find udev rules directory" 1>&2 exit 1 fi diff --git a/Documentation/aoe/udev.txt b/Documentation/aoe/udev.txt index a7ed1dc..8686e78 100644 --- a/Documentation/aoe/udev.txt +++ b/Documentation/aoe/udev.txt @@ -1,6 +1,7 @@ # These rules tell udev what device nodes to create for aoe support. -# They may be installed along the following lines (adjusted to what -# you see on your system). +# They may be installed along the following lines. Check the section +# 8 udev manpage to see whether your udev supports SUBSYSTEM, and +# whether it uses one or two equal signs for SUBSYSTEM and KERNEL. # # ecashin@makki ~$ su # Password: @@ -15,10 +16,11 @@ # # aoe char devices -SUBSYSTEM="aoe", KERNEL="discover", NAME="etherd/%k", GROUP="disk", MODE="0220" -SUBSYSTEM="aoe", KERNEL="err", NAME="etherd/%k", GROUP="disk", MODE="0440" -SUBSYSTEM="aoe", KERNEL="interfaces", NAME="etherd/%k", GROUP="disk", MODE="0220" -SUBSYSTEM="aoe", KERNEL="revalidate", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="discover", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="err", NAME="etherd/%k", GROUP="disk", MODE="0440" +SUBSYSTEM=="aoe", KERNEL=="interfaces", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="revalidate", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="flush", NAME="etherd/%k", GROUP="disk", MODE="0220" # aoe block devices -KERNEL="etherd*", NAME="%k", GROUP="disk" +KERNEL=="etherd*", NAME="%k", GROUP="disk" diff --git a/Documentation/arm/Sharp-LH/IOBarrier b/Documentation/arm/Sharp-LH/IOBarrier index c0d8853..2e953e2 100644 --- a/Documentation/arm/Sharp-LH/IOBarrier +++ b/Documentation/arm/Sharp-LH/IOBarrier @@ -32,7 +32,7 @@ BARRIER IO before the access to the SMC chip because the AEN latch only needs occurs after the SMC IO write cycle. The routines that implement this work-around make an additional concession which is to disable interrupts during the IO sequence. Other hardware devices -(the LogicPD CPLD) have registers in the same the physical memory +(the LogicPD CPLD) have registers in the same physical memory region as the SMC chip. An interrupt might allow an access to one of those registers while SMC IO is being performed. diff --git a/Documentation/cgroups.txt b/Documentation/cgroups.txt index 98a26f8..42d7c4c 100644 --- a/Documentation/cgroups.txt +++ b/Documentation/cgroups.txt @@ -456,7 +456,7 @@ methods are create/destroy. Any others that are null are presumed to be successful no-ops. struct cgroup_subsys_state *create(struct cgroup *cont) -LL=cgroup_mutex +(cgroup_mutex held by caller) Called to create a subsystem state object for a cgroup. The subsystem should allocate its subsystem state object for the passed @@ -471,14 +471,19 @@ it's the root of the hierarchy) and may be an appropriate place for initialization code. void destroy(struct cgroup *cont) -LL=cgroup_mutex +(cgroup_mutex held by caller) -The cgroup system is about to destroy the passed cgroup; the -subsystem should do any necessary cleanup +The cgroup system is about to destroy the passed cgroup; the subsystem +should do any necessary cleanup and free its subsystem state +object. By the time this method is called, the cgroup has already been +unlinked from the file system and from the child list of its parent; +cgroup->parent is still valid. (Note - can also be called for a +newly-created cgroup if an error occurs after this subsystem's +create() method has been called for the new cgroup). int can_attach(struct cgroup_subsys *ss, struct cgroup *cont, struct task_struct *task) -LL=cgroup_mutex +(cgroup_mutex held by caller) Called prior to moving a task into a cgroup; if the subsystem returns an error, this will abort the attach operation. If a NULL @@ -489,25 +494,20 @@ remain valid while the caller holds cgroup_mutex. void attach(struct cgroup_subsys *ss, struct cgroup *cont, struct cgroup *old_cont, struct task_struct *task) -LL=cgroup_mutex - Called after the task has been attached to the cgroup, to allow any post-attachment activity that requires memory allocations or blocking. void fork(struct cgroup_subsy *ss, struct task_struct *task) -LL=callback_mutex, maybe read_lock(tasklist_lock) Called when a task is forked into a cgroup. Also called during registration for all existing tasks. void exit(struct cgroup_subsys *ss, struct task_struct *task) -LL=callback_mutex Called during task exit int populate(struct cgroup_subsys *ss, struct cgroup *cont) -LL=none Called after creation of a cgroup to allow a subsystem to populate the cgroup directory with file entries. The subsystem should make @@ -524,7 +524,7 @@ example in cpusets, no task may attach before 'cpus' and 'mems' are set up. void bind(struct cgroup_subsys *ss, struct cgroup *root) -LL=callback_mutex +(cgroup_mutex held by caller) Called when a cgroup subsystem is rebound to a different hierarchy and root cgroup. Currently this will only involve movement between diff --git a/Documentation/controllers/memory.txt b/Documentation/controllers/memory.txt new file mode 100644 index 0000000..b5bbea9 --- /dev/null +++ b/Documentation/controllers/memory.txt @@ -0,0 +1,279 @@ +Memory Controller + +Salient features + +a. Enable control of both RSS (mapped) and Page Cache (unmapped) pages +b. The infrastructure allows easy addition of other types of memory to control +c. Provides *zero overhead* for non memory controller users +d. Provides a double LRU: global memory pressure causes reclaim from the + global LRU; a cgroup on hitting a limit, reclaims from the per + cgroup LRU + +NOTE: Swap Cache (unmapped) is not accounted now. + +Benefits and Purpose of the memory controller + +The memory controller isolates the memory behaviour of a group of tasks +from the rest of the system. The article on LWN [12] mentions some probable +uses of the memory controller. The memory controller can be used to + +a. Isolate an application or a group of applications + Memory hungry applications can be isolated and limited to a smaller + amount of memory. +b. Create a cgroup with limited amount of memory, this can be used + as a good alternative to booting with mem=XXXX. +c. Virtualization solutions can control the amount of memory they want + to assign to a virtual machine instance. +d. A CD/DVD burner could control the amount of memory used by the + rest of the system to ensure that burning does not fail due to lack + of available memory. +e. There are several other use cases, find one or use the controller just + for fun (to learn and hack on the VM subsystem). + +1. History + +The memory controller has a long history. A request for comments for the memory +controller was posted by Balbir Singh [1]. At the time the RFC was posted +there were several implementations for memory control. The goal of the +RFC was to build consensus and agreement for the minimal features required +for memory control. The first RSS controller was posted by Balbir Singh[2] +in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the +RSS controller. At OLS, at the resource management BoF, everyone suggested +that we handle both page cache and RSS together. Another request was raised +to allow user space handling of OOM. The current memory controller is +at version 6; it combines both mapped (RSS) and unmapped Page +Cache Control [11]. + +2. Memory Control + +Memory is a unique resource in the sense that it is present in a limited +amount. If a task requires a lot of CPU processing, the task can spread +its processing over a period of hours, days, months or years, but with +memory, the same physical memory needs to be reused to accomplish the task. + +The memory controller implementation has been divided into phases. These +are: + +1. Memory controller +2. mlock(2) controller +3. Kernel user memory accounting and slab control +4. user mappings length controller + +The memory controller is the first controller developed. + +2.1. Design + +The core of the design is a counter called the res_counter. The res_counter +tracks the current memory usage and limit of the group of processes associated +with the controller. Each cgroup has a memory controller specific data +structure (mem_cgroup) associated with it. + +2.2. Accounting + + +--------------------+ + | mem_cgroup | + | (res_counter) | + +--------------------+ + / ^ \ + / | \ + +---------------+ | +---------------+ + | mm_struct | |.... | mm_struct | + | | | | | + +---------------+ | +---------------+ + | + + --------------+ + | + +---------------+ +------+--------+ + | page +----------> page_cgroup| + | | | | + +---------------+ +---------------+ + + (Figure 1: Hierarchy of Accounting) + + +Figure 1 shows the important aspects of the controller + +1. Accounting happens per cgroup +2. Each mm_struct knows about which cgroup it belongs to +3. Each page has a pointer to the page_cgroup, which in turn knows the + cgroup it belongs to + +The accounting is done as follows: mem_cgroup_charge() is invoked to setup +the necessary data structures and check if the cgroup that is being charged +is over its limit. If it is then reclaim is invoked on the cgroup. +More details can be found in the reclaim section of this document. +If everything goes well, a page meta-data-structure called page_cgroup is +allocated and associated with the page. This routine also adds the page to +the per cgroup LRU. + +2.2.1 Accounting details + +All mapped pages (RSS) and unmapped user pages (Page Cache) are accounted. +RSS pages are accounted at the time of page_add_*_rmap() unless they've already +been accounted for earlier. A file page will be accounted for as Page Cache; +it's mapped into the page tables of a process, duplicate accounting is carefully +avoided. Page Cache pages are accounted at the time of add_to_page_cache(). +The corresponding routines that remove a page from the page tables or removes +a page from Page Cache is used to decrement the accounting counters of the +cgroup. + +2.3 Shared Page Accounting + +Shared pages are accounted on the basis of the first touch approach. The +cgroup that first touches a page is accounted for the page. The principle +behind this approach is that a cgroup that aggressively uses a shared +page will eventually get charged for it (once it is uncharged from +the cgroup that brought it in -- this will happen on memory pressure). + +2.4 Reclaim + +Each cgroup maintains a per cgroup LRU that consists of an active +and inactive list. When a cgroup goes over its limit, we first try +to reclaim memory from the cgroup so as to make space for the new +pages that the cgroup has touched. If the reclaim is unsuccessful, +an OOM routine is invoked to select and kill the bulkiest task in the +cgroup. + +The reclaim algorithm has not been modified for cgroups, except that +pages that are selected for reclaiming come from the per cgroup LRU +list. + +2. Locking + +The memory controller uses the following hierarchy + +1. zone->lru_lock is used for selecting pages to be isolated +2. mem->per_zone->lru_lock protects the per cgroup LRU (per zone) +3. lock_page_cgroup() is used to protect page->page_cgroup + +3. User Interface + +0. Configuration + +a. Enable CONFIG_CGROUPS +b. Enable CONFIG_RESOURCE_COUNTERS +c. Enable CONFIG_CGROUP_MEM_CONT + +1. Prepare the cgroups +# mkdir -p /cgroups +# mount -t cgroup none /cgroups -o memory + +2. Make the new group and move bash into it +# mkdir /cgroups/0 +# echo $$ > /cgroups/0/tasks + +Since now we're in the 0 cgroup, +We can alter the memory limit: +# echo -n 4M > /cgroups/0/memory.limit_in_bytes + +NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, +mega or gigabytes. + +# cat /cgroups/0/memory.limit_in_bytes +4194304 Bytes + +NOTE: The interface has now changed to display the usage in bytes +instead of pages + +We can check the usage: +# cat /cgroups/0/memory.usage_in_bytes +1216512 Bytes + +A successful write to this file does not guarantee a successful set of +this limit to the value written into the file. This can be due to a +number of factors, such as rounding up to page boundaries or the total +availability of memory on the system. The user is required to re-read +this file after a write to guarantee the value committed by the kernel. + +# echo -n 1 > memory.limit_in_bytes +# cat memory.limit_in_bytes +4096 Bytes + +The memory.failcnt field gives the number of times that the cgroup limit was +exceeded. + +The memory.stat file gives accounting information. Now, the number of +caches, RSS and Active pages/Inactive pages are shown. + +The memory.force_empty gives an interface to drop *all* charges by force. + +# echo -n 1 > memory.force_empty + +will drop all charges in cgroup. Currently, this is maintained for test. + +4. Testing + +Balbir posted lmbench, AIM9, LTP and vmmstress results [10] and [11]. +Apart from that v6 has been tested with several applications and regular +daily use. The controller has also been tested on the PPC64, x86_64 and +UML platforms. + +4.1 Troubleshooting + +Sometimes a user might find that the application under a cgroup is +terminated. There are several causes for this: + +1. The cgroup limit is too low (just too low to do anything useful) +2. The user is using anonymous memory and swap is turned off or too low + +A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of +some of the pages cached in the cgroup (page cache pages). + +4.2 Task migration + +When a task migrates from one cgroup to another, it's charge is not +carried forward. The pages allocated from the original cgroup still +remain charged to it, the charge is dropped when the page is freed or +reclaimed. + +4.3 Removing a cgroup + +A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a +cgroup might have some charge associated with it, even though all +tasks have migrated away from it. Such charges are automatically dropped at +rmdir() if there are no tasks. + +4.4 Choosing what to account -- Page Cache (unmapped) vs RSS (mapped)? + +The type of memory accounted by the cgroup can be limited to just +mapped pages by writing "1" to memory.control_type field + +echo -n 1 > memory.control_type + +5. TODO + +1. Add support for accounting huge pages (as a separate controller) +2. Make per-cgroup scanner reclaim not-shared pages first +3. Teach controller to account for shared-pages +4. Start reclamation when the limit is lowered +5. Start reclamation in the background when the limit is + not yet hit but the usage is getting closer + +Summary + +Overall, the memory controller has been a stable controller and has been +commented and discussed quite extensively in the community. + +References + +1. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ +2. Singh, Balbir. Memory Controller (RSS Control), + http://lwn.net/Articles/222762/ +3. Emelianov, Pavel. Resource controllers based on process cgroups + http://lkml.org/lkml/2007/3/6/198 +4. Emelianov, Pavel. RSS controller based on process cgroups (v2) + http://lkml.org/lkml/2007/4/9/74 +5. Emelianov, Pavel. RSS controller based on process cgroups (v3) + http://lkml.org/lkml/2007/5/30/244 +6. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/ +7. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control + subsystem (v3), http://lwn.net/Articles/235534/ +8. Singh, Balbir. RSS controller V2 test results (lmbench), + http://lkml.org/lkml/2007/5/17/232 +9. Singh, Balbir. RSS controller V2 AIM9 results + http://lkml.org/lkml/2007/5/18/1 +10. Singh, Balbir. Memory controller v6 results, + http://lkml.org/lkml/2007/8/19/36 +11. Singh, Balbir. Memory controller v6, http://lkml.org/lkml/2007/8/17/69 +12. Corbet, Jonathan, Controlling memory use in cgroups, + http://lwn.net/Articles/243795/ diff --git a/Documentation/cpusets.txt b/Documentation/cpusets.txt index 141bef1..43db6fe 100644 --- a/Documentation/cpusets.txt +++ b/Documentation/cpusets.txt @@ -523,21 +523,14 @@ from one cpuset to another, then the kernel will adjust the tasks memory placement, as above, the next time that the kernel attempts to allocate a page of memory for that task. -If a cpuset has its CPUs modified, then each task using that -cpuset does _not_ change its behavior automatically. In order to -minimize the impact on the critical scheduling code in the kernel, -tasks will continue to use their prior CPU placement until they -are rebound to their cpuset, by rewriting their pid to the 'tasks' -file of their cpuset. If a task had been bound to some subset of its -cpuset using the sched_setaffinity() call, and if any of that subset -is still allowed in its new cpuset settings, then the task will be -restricted to the intersection of the CPUs it was allowed on before, -and its new cpuset CPU placement. If, on the other hand, there is -no overlap between a tasks prior placement and its new cpuset CPU -placement, then the task will be allowed to run on any CPU allowed -in its new cpuset. If a task is moved from one cpuset to another, -its CPU placement is updated in the same way as if the tasks pid is -rewritten to the 'tasks' file of its current cpuset. +If a cpuset has its 'cpus' modified, then each task in that cpuset +will have its allowed CPU placement changed immediately. Similarly, +if a tasks pid is written to a cpusets 'tasks' file, in either its +current cpuset or another cpuset, then its allowed CPU placement is +changed immediately. If such a task had been bound to some subset +of its cpuset using the sched_setaffinity() call, the task will be +allowed to run on any CPU allowed in its new cpuset, negating the +affect of the prior sched_setaffinity() call. In summary, the memory placement of a task whose cpuset is changed is updated by the kernel, on the next allocation of a page for that task, diff --git a/Documentation/debugging-modules.txt b/Documentation/debugging-modules.txt index 24029f6..172ad4a 100644 --- a/Documentation/debugging-modules.txt +++ b/Documentation/debugging-modules.txt @@ -16,3 +16,7 @@ echo 'echo "$@" >> /tmp/modprobe.log' >> /tmp/modprobe echo 'exec /sbin/modprobe "$@"' >> /tmp/modprobe chmod a+x /tmp/modprobe echo /tmp/modprobe > /proc/sys/kernel/modprobe + +Note that the above applies only when the *kernel* is requesting +that the module be loaded -- it won't have any effect if that module +is being loaded explicitly using "modprobe" from userspace. diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.txt index 2a97320..83009fdc 100644 --- a/Documentation/driver-model/platform.txt +++ b/Documentation/driver-model/platform.txt @@ -122,15 +122,15 @@ None the less, there are some APIs to support such legacy drivers. Avoid using these calls except with such hotplug-deficient drivers. struct platform_device *platform_device_alloc( - char *name, unsigned id); + const char *name, int id); You can use platform_device_alloc() to dynamically allocate a device, which you will then initialize with resources and platform_device_register(). A better solution is usually: struct platform_device *platform_device_register_simple( - char *name, unsigned id, - struct resource *res, unsigned nres); + const char *name, int id, + struct resource *res, unsigned int nres); You can use platform_device_register_simple() as a one-step call to allocate and register a device. diff --git a/Documentation/drivers/edac/edac.txt b/Documentation/edac.txt index a5c36842e..a5c36842e 100644 --- a/Documentation/drivers/edac/edac.txt +++ b/Documentation/edac.txt diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 113165b..2ebb94d 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -170,7 +170,6 @@ Sylpheed (GUI) - Works well for inlining text (or using attachments). - Allows use of an external editor. -- Not good for IMAP. - Is slow on large folders. - Won't do TLS SMTP auth over a non-SSL connection. - Has a helpful ruler bar in the compose window. diff --git a/Documentation/fb/deferred_io.txt b/Documentation/fb/deferred_io.txt index 63883a8..7483283 100644 --- a/Documentation/fb/deferred_io.txt +++ b/Documentation/fb/deferred_io.txt @@ -7,10 +7,10 @@ IO. The following example may be a useful explanation of how one such setup works: - userspace app like Xfbdev mmaps framebuffer -- deferred IO and driver sets up nopage and page_mkwrite handlers +- deferred IO and driver sets up fault and page_mkwrite handlers - userspace app tries to write to mmaped vaddress -- we get pagefault and reach nopage handler -- nopage handler finds and returns physical page +- we get pagefault and reach fault handler +- fault handler finds and returns physical page - we get page_mkwrite where we add this page to a list - schedule a workqueue task to be run after a delay - app continues writing to that page with no additional cost. this is diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 181bff0..ce9503c 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -6,14 +6,6 @@ be removed from this file. --------------------------- -What: MXSER -When: December 2007 -Why: Old mxser driver is obsoleted by the mxser_new. Give it some time yet - and remove it. -Who: Jiri Slaby <jirislaby@gmail.com> - ---------------------------- - What: dev->power.power_state When: July 2007 Why: Broken design for runtime control over driver power states, confusing @@ -107,17 +99,6 @@ Who: Eric Biederman <ebiederm@xmission.com> --------------------------- -What: a.out interpreter support for ELF executables -When: 2.6.25 -Files: fs/binfmt_elf.c -Why: Using a.out interpreters for ELF executables was a feature for - transition from a.out to ELF. But now it is unlikely to be still - needed anymore and removing it would simplify the hairy ELF - loader code. -Who: Andi Kleen <ak@suse.de> - ---------------------------- - What: remove EXPORT_SYMBOL(kernel_thread) When: August 2006 Files: arch/*/kernel/*_ksyms.c @@ -156,22 +137,6 @@ Who: Arjan van de Ven <arjan@linux.intel.com> --------------------------- -What: USB driver API moves to EXPORT_SYMBOL_GPL -When: February 2008 -Files: include/linux/usb.h, drivers/usb/core/driver.c -Why: The USB subsystem has changed a lot over time, and it has been - possible to create userspace USB drivers using usbfs/libusb/gadgetfs - that operate as fast as the USB bus allows. Because of this, the USB - subsystem will not be allowing closed source kernel drivers to - register with it, after this grace period is over. If anyone needs - any help in converting their closed source drivers over to use the - userspace filesystems, please contact the - linux-usb-devel@lists.sourceforge.net mailing list, and the developers - there will be glad to help you out. -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 @@ -216,21 +181,6 @@ Who: Len Brown <len.brown@intel.com> --------------------------- -What: 'time' kernel boot parameter -When: January 2008 -Why: replaced by 'printk.time=<value>' so that printk timestamps can be - enabled or disabled as needed -Who: Randy Dunlap <randy.dunlap@oracle.com> - ---------------------------- - -What: drivers depending on OSS_OBSOLETE -When: options in 2.6.23, code in 2.6.25 -Why: obsolete OSS drivers -Who: Adrian Bunk <bunk@stusta.de> - ---------------------------- - What: libata spindown skipping and warning When: Dec 2008 Why: Some halt(8) implementations synchronize caches for and spin diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 1de155e..e68021c 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -32,6 +32,8 @@ directory-locking - info about the locking scheme used for directory operations. dlmfs.txt - info on the userspace interface to the OCFS2 DLM. +dnotify.txt + - info about directory notification in Linux. ecryptfs.txt - docs on eCryptfs: stacked cryptographic filesystem for Linux. ext2.txt @@ -80,6 +82,8 @@ relay.txt - info on relay, for efficient streaming from kernel to user space. romfs.txt - description of the ROMFS filesystem. +sharedsubtree.txt + - a description of shared subtrees for namespaces. smbfs.txt - info on using filesystems with the SMB protocol (Win 3.11 and NT). spufs.txt diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 37c10cb..42d4b30 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -90,7 +90,6 @@ of the locking scheme for directory operations. prototypes: struct inode *(*alloc_inode)(struct super_block *sb); void (*destroy_inode)(struct inode *); - void (*read_inode) (struct inode *); void (*dirty_inode) (struct inode *); int (*write_inode) (struct inode *, int); void (*put_inode) (struct inode *); @@ -114,7 +113,6 @@ locking rules: BKL s_lock s_umount alloc_inode: no no no destroy_inode: no -read_inode: no (see below) dirty_inode: no (must not sleep) write_inode: no put_inode: no @@ -133,7 +131,6 @@ show_options: no (vfsmount->sem) quota_read: no no no (see below) quota_write: no no no (see below) -->read_inode() is not a method - it's a callback used in iget(). ->remount_fs() will have the s_umount lock if it's already mounted. When called from get_sb_single, it does NOT have the s_umount lock. ->quota_read() and ->quota_write() functions are both guaranteed to diff --git a/Documentation/filesystems/configfs/configfs.txt b/Documentation/filesystems/configfs/configfs.txt index d1b9825..44c97e6 100644 --- a/Documentation/filesystems/configfs/configfs.txt +++ b/Documentation/filesystems/configfs/configfs.txt @@ -377,7 +377,7 @@ more explicit to have a method whereby userspace sees this divergence. Rather than have a group where some items behave differently than others, configfs provides a method whereby one or many subgroups are automatically created inside the parent at its creation. Thus, -mkdir("parent) results in "parent", "parent/subgroup1", up through +mkdir("parent") results in "parent", "parent/subgroup1", up through "parent/subgroupN". Items of type 1 can now be created in "parent/subgroup1", and items of type N can be created in "parent/subgroupN". diff --git a/Documentation/dnotify.txt b/Documentation/filesystems/dnotify.txt index 6984fca..9f5d338 100644 --- a/Documentation/dnotify.txt +++ b/Documentation/filesystems/dnotify.txt @@ -69,24 +69,24 @@ Example #include <signal.h> #include <stdio.h> #include <unistd.h> - + static volatile int event_fd; - + static void handler(int sig, siginfo_t *si, void *data) { event_fd = si->si_fd; } - + int main(void) { struct sigaction act; int fd; - + act.sa_sigaction = handler; sigemptyset(&act.sa_mask); act.sa_flags = SA_SIGINFO; sigaction(SIGRTMIN + 1, &act, NULL); - + fd = open(".", O_RDONLY); fcntl(fd, F_SETSIG, SIGRTMIN + 1); fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT); diff --git a/Documentation/filesystems/isofs.txt b/Documentation/filesystems/isofs.txt index 758e504..6973b98 100644 --- a/Documentation/filesystems/isofs.txt +++ b/Documentation/filesystems/isofs.txt @@ -24,6 +24,7 @@ Mount options unique to the isofs filesystem. map=normal Map non-Rock Ridge filenames to lower case map=acorn As map=normal but also apply Acorn extensions if present mode=xxx Sets the permissions on files to xxx + dmode=xxx Sets the permissions on directories to xxx nojoliet Ignore Joliet extensions if they are present. norock Ignore Rock Ridge extensions if they are present. hide Completely strip hidden files from the file system. diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index dac45c9..92b888d 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -1,6 +1,6 @@ Changes since 2.5.0: ---- +--- [recommended] New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(), @@ -10,7 +10,7 @@ Use them. (sb_find_get_block() replaces 2.4's get_hash_table()) ---- +--- [recommended] New methods: ->alloc_inode() and ->destroy_inode(). @@ -28,14 +28,14 @@ Declare Use FOO_I(inode) instead of &inode->u.foo_inode_i; -Add foo_alloc_inode() and foo_destory_inode() - the former should allocate +Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate foo_inode_info and return the address of ->vfs_inode, the latter should free FOO_I(inode) (see in-tree filesystems for examples). Make them ->alloc_inode and ->destroy_inode in your super_operations. -Keep in mind that now you need explicit initialization of private data - -typically in ->read_inode() and after getting an inode from new_inode(). +Keep in mind that now you need explicit initialization of private data +typically between calling iget_locked() and unlocking the inode. At some point that will become mandatory. @@ -173,10 +173,10 @@ should be a non-blocking function that initializes those parts of a newly created inode to allow the test function to succeed. 'data' is passed as an opaque value to both test and set functions. -When the inode has been created by iget5_locked(), it will be returned with -the I_NEW flag set and will still be locked. read_inode has not been -called so the file system still has to finalize the initialization. Once -the inode is initialized it must be unlocked by calling unlock_new_inode(). +When the inode has been created by iget5_locked(), it will be returned with the +I_NEW flag set and will still be locked. The filesystem then needs to finalize +the initialization. Once the inode is initialized it must be unlocked by +calling unlock_new_inode(). The filesystem is responsible for setting (and possibly testing) i_ino when appropriate. There is also a simpler iget_locked function that @@ -184,11 +184,19 @@ just takes the superblock and inode number as arguments and does the test and set for you. e.g. - inode = iget_locked(sb, ino); - if (inode->i_state & I_NEW) { - read_inode_from_disk(inode); - unlock_new_inode(inode); - } + inode = iget_locked(sb, ino); + if (inode->i_state & I_NEW) { + err = read_inode_from_disk(inode); + if (err < 0) { + iget_failed(inode); + return err; + } + unlock_new_inode(inode); + } + +Note that if the process of setting up a new inode fails, then iget_failed() +should be called on the inode to render it dead, and an appropriate error +should be passed back to the caller. --- [recommended] diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 4413a2d..5681e2f 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -216,6 +216,7 @@ Table 1-3: Contents of the stat files (as of 2.6.22-rc3) priority priority level nice nice level num_threads number of threads + it_real_value (obsolete, always 0) start_time time the process started after system boot vsize virtual memory size rss resident set memory size @@ -1028,6 +1029,14 @@ nr_inodes Denotes the number of inodes the system has allocated. This number will grow and shrink dynamically. +nr_open +------- + +Denotes the maximum number of file-handles a process can +allocate. Default value is 1024*1024 (1048576) which should be +enough for most machines. Actual limit depends on RLIMIT_NOFILE +resource limit. + nr_free_inodes -------------- @@ -1134,13 +1143,6 @@ 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 ------------ @@ -1321,13 +1323,28 @@ for writeout by the pdflush daemons. It is expressed in 100'ths of a second. Data which has been dirty in-memory for longer than this interval will be written out next time a pdflush daemon wakes up. +highmem_is_dirtyable +-------------------- + +Only present if CONFIG_HIGHMEM is set. + +This defaults to 0 (false), meaning that the ratios set above are calculated +as a percentage of lowmem only. This protects against excessive scanning +in page reclaim, swapping and general VM distress. + +Setting this to 1 can be useful on 32 bit machines where you want to make +random changes within an MMAPed file that is larger than your available +lowmem without causing large quantities of random IO. Is is safe if the +behavior of all programs running on the machine is known and memory will +not be otherwise stressed. + legacy_va_layout ---------------- If non-zero, this sysctl disables the new 32-bit mmap mmap layout - the kernel will use the legacy (2.4) layout for all processes. -lower_zone_protection +lowmem_reserve_ratio --------------------- For some specialised workloads on highmem machines it is dangerous for @@ -1347,25 +1364,71 @@ captured into pinned user memory. mechanism will also defend that region from allocations which could use highmem or lowmem). -The `lower_zone_protection' tunable determines how aggressive the kernel is -in defending these lower zones. The default value is zero - no -protection at all. +The `lowmem_reserve_ratio' tunable determines how aggressive the kernel is +in defending these lower zones. If you have a machine which uses highmem or ISA DMA and your applications are using mlock(), or if you are running with no swap then -you probably should increase the lower_zone_protection setting. - -The units of this tunable are fairly vague. It is approximately equal -to "megabytes," so setting lower_zone_protection=100 will protect around 100 -megabytes of the lowmem zone from user allocations. It will also make -those 100 megabytes unavailable for use by applications and by -pagecache, so there is a cost. - -The effects of this tunable may be observed by monitoring -/proc/meminfo:LowFree. Write a single huge file and observe the point -at which LowFree ceases to fall. - -A reasonable value for lower_zone_protection is 100. +you probably should change the lowmem_reserve_ratio setting. + +The lowmem_reserve_ratio is an array. You can see them by reading this file. +- +% cat /proc/sys/vm/lowmem_reserve_ratio +256 256 32 +- +Note: # of this elements is one fewer than number of zones. Because the highest + zone's value is not necessary for following calculation. + +But, these values are not used directly. The kernel calculates # of protection +pages for each zones from them. These are shown as array of protection pages +in /proc/zoneinfo like followings. (This is an example of x86-64 box). +Each zone has an array of protection pages like this. + +- +Node 0, zone DMA + pages free 1355 + min 3 + low 3 + high 4 + : + : + numa_other 0 + protection: (0, 2004, 2004, 2004) + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + pagesets + cpu: 0 pcp: 0 + : +- +These protections are added to score to judge whether this zone should be used +for page allocation or should be reclaimed. + +In this example, if normal pages (index=2) are required to this DMA zone and +pages_high is used for watermark, the kernel judges this zone should not be +used because pages_free(1355) is smaller than watermark + protection[2] +(4 + 2004 = 2008). If this protection value is 0, this zone would be used for +normal page requirement. If requirement is DMA zone(index=0), protection[0] +(=0) is used. + +zone[i]'s protection[j] is calculated by following exprssion. + +(i < j): + zone[i]->protection[j] + = (total sums of present_pages from zone[i+1] to zone[j] on the node) + / lowmem_reserve_ratio[i]; +(i = j): + (should not be protected. = 0; +(i > j): + (not necessary, but looks 0) + +The default values of lowmem_reserve_ratio[i] are + 256 (if zone[i] means DMA or DMA32 zone) + 32 (others). +As above expression, they are reciprocal number of ratio. +256 means 1/256. # of protection pages becomes about "0.39%" of total present +pages of higher zones on the node. + +If you would like to protect more pages, smaller values are effective. +The minimum value is 1 (1/1 -> 100%). page-cluster ------------ @@ -1919,11 +1982,6 @@ max_size Maximum size of the routing cache. Old entries will be purged once the cache reached has this size. -max_delay, min_delay --------------------- - -Delays for flushing the routing cache. - redirect_load, redirect_number ------------------------------ diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt index 339c6a4..7be232b 100644 --- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt +++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt @@ -118,7 +118,7 @@ All this differs from the old initrd in several ways: with the new root (cd /newmount; mount --move . /; chroot .), attach stdin/stdout/stderr to the new /dev/console, and exec the new init. - Since this is a remarkably persnickity process (and involves deleting + Since this is a remarkably persnickety process (and involves deleting commands before you can run them), the klibc package introduced a helper program (utils/run_init.c) to do all this for you. Most other packages (such as busybox) have named this command "switch_root". diff --git a/Documentation/filesystems/relay.txt b/Documentation/filesystems/relay.txt index 18d23f9..094f2d2 100644 --- a/Documentation/filesystems/relay.txt +++ b/Documentation/filesystems/relay.txt @@ -140,7 +140,7 @@ close() decrements the channel buffer's refcount. When the refcount In order for a user application to make use of relay files, the host filesystem must be mounted. For example, - mount -t debugfs debugfs /debug + mount -t debugfs debugfs /sys/kernel/debug NOTE: the host filesystem doesn't need to be mounted for kernel clients to create or use channels - it only needs to be diff --git a/Documentation/sharedsubtree.txt b/Documentation/filesystems/sharedsubtree.txt index 7365400..7365400 100644 --- a/Documentation/sharedsubtree.txt +++ b/Documentation/filesystems/sharedsubtree.txt diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 9d019d3..81e5be6 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -151,7 +151,7 @@ The get_sb() method has the following arguments: const char *dev_name: the device name we are mounting. void *data: arbitrary mount options, usually comes as an ASCII - string + string (see "Mount Options" section) struct vfsmount *mnt: a vfs-internal representation of a mount point @@ -182,7 +182,7 @@ A fill_super() method implementation has the following arguments: must initialize this properly. void *data: arbitrary mount options, usually comes as an ASCII - string + string (see "Mount Options" section) int silent: whether or not to be silent on error @@ -203,8 +203,6 @@ struct super_operations { struct inode *(*alloc_inode)(struct super_block *sb); void (*destroy_inode)(struct inode *); - void (*read_inode) (struct inode *); - void (*dirty_inode) (struct inode *); int (*write_inode) (struct inode *, int); void (*put_inode) (struct inode *); @@ -242,15 +240,6 @@ or bottom half). ->alloc_inode was defined and simply undoes anything done by ->alloc_inode. - read_inode: this method is called to read a specific inode from the - mounted filesystem. The i_ino member in the struct inode is - initialized by the VFS to indicate which inode to read. Other - members are filled in by this method. - - You can set this to NULL and use iget5_locked() instead of iget() - to read inodes. This is necessary for filesystems for which the - inode number is not sufficient to identify an inode. - dirty_inode: this method is called by the VFS to mark an inode dirty. write_inode: this method is called when the VFS needs to write an @@ -302,15 +291,16 @@ or bottom half). umount_begin: called when the VFS is unmounting a filesystem. - show_options: called by the VFS to show mount options for /proc/<pid>/mounts. + show_options: called by the VFS to show mount options for + /proc/<pid>/mounts. (see "Mount Options" section) quota_read: called by the VFS to read from filesystem quota file. quota_write: called by the VFS to write to filesystem quota file. -The read_inode() method is responsible for filling in the "i_op" -field. This is a pointer to a "struct inode_operations" which -describes the methods that can be performed on individual inodes. +Whoever sets up the inode is responsible for filling in the "i_op" field. This +is a pointer to a "struct inode_operations" which describes the methods that +can be performed on individual inodes. The Inode Object @@ -980,6 +970,49 @@ manipulate dentries: For further information on dentry locking, please refer to the document Documentation/filesystems/dentry-locking.txt. +Mount Options +============= + +Parsing options +--------------- + +On mount and remount the filesystem is passed a string containing a +comma separated list of mount options. The options can have either of +these forms: + + option + option=value + +The <linux/parser.h> header defines an API that helps parse these +options. There are plenty of examples on how to use it in existing +filesystems. + +Showing options +--------------- + +If a filesystem accepts mount options, it must define show_options() +to show all the currently active options. The rules are: + + - options MUST be shown which are not default or their values differ + from the default + + - options MAY be shown which are enabled by default or have their + default value + +Options used only internally between a mount helper and the kernel +(such as file descriptors), or which only have an effect during the +mounting (such as ones controlling the creation of a journal) are exempt +from the above rules. + +The underlying reason for the above rules is to make sure, that a +mount can be accurately replicated (e.g. umounting and mounting again) +based on the information found in /proc/mounts. + +A simple method of saving options at mount/remount time and showing +them is provided with the save_mount_options() and +generic_show_options() helper functions. Please note, that using +these may have drawbacks. For more info see header comments for these +functions in fs/namespace.c. Resources ========= diff --git a/Documentation/fujitsu/frv/README.txt b/Documentation/frv/README.txt index a984faa..a984faa 100644 --- a/Documentation/fujitsu/frv/README.txt +++ b/Documentation/frv/README.txt diff --git a/Documentation/fujitsu/frv/atomic-ops.txt b/Documentation/frv/atomic-ops.txt index 96638e9..96638e9 100644 --- a/Documentation/fujitsu/frv/atomic-ops.txt +++ b/Documentation/frv/atomic-ops.txt diff --git a/Documentation/fujitsu/frv/booting.txt b/Documentation/frv/booting.txt index 4e22905..ace200b 100644 --- a/Documentation/fujitsu/frv/booting.txt +++ b/Documentation/frv/booting.txt @@ -177,5 +177,5 @@ separated by spaces: (*) vdc=... This option configures the MB93493 companion chip visual display - driver. Please see Documentation/fujitsu/mb93493/vdc.txt for more + driver. Please see Documentation/frv/mb93493/vdc.txt for more information. diff --git a/Documentation/fujitsu/frv/clock.txt b/Documentation/frv/clock.txt index c72d350..c72d350 100644 --- a/Documentation/fujitsu/frv/clock.txt +++ b/Documentation/frv/clock.txt diff --git a/Documentation/fujitsu/frv/configuring.txt b/Documentation/frv/configuring.txt index 36e76a2..36e76a2 100644 --- a/Documentation/fujitsu/frv/configuring.txt +++ b/Documentation/frv/configuring.txt diff --git a/Documentation/fujitsu/frv/features.txt b/Documentation/frv/features.txt index fa20c0e..fa20c0e 100644 --- a/Documentation/fujitsu/frv/features.txt +++ b/Documentation/frv/features.txt diff --git a/Documentation/fujitsu/frv/gdbinit b/Documentation/frv/gdbinit index 51517b6..51517b6 100644 --- a/Documentation/fujitsu/frv/gdbinit +++ b/Documentation/frv/gdbinit diff --git a/Documentation/fujitsu/frv/gdbstub.txt b/Documentation/frv/gdbstub.txt index b92bfd9..b92bfd9 100644 --- a/Documentation/fujitsu/frv/gdbstub.txt +++ b/Documentation/frv/gdbstub.txt diff --git a/Documentation/fujitsu/frv/kernel-ABI.txt b/Documentation/frv/kernel-ABI.txt index aaa1cec..aaa1cec 100644 --- a/Documentation/fujitsu/frv/kernel-ABI.txt +++ b/Documentation/frv/kernel-ABI.txt diff --git a/Documentation/fujitsu/frv/mmu-layout.txt b/Documentation/frv/mmu-layout.txt index db10250..db10250 100644 --- a/Documentation/fujitsu/frv/mmu-layout.txt +++ b/Documentation/frv/mmu-layout.txt diff --git a/Documentation/gpio.txt b/Documentation/gpio.txt index 6bc2ba2..8da724e 100644 --- a/Documentation/gpio.txt +++ b/Documentation/gpio.txt @@ -32,7 +32,7 @@ The exact capabilities of GPIOs vary between systems. Common options: - Input values are likewise readable (1, 0). Some chips support readback of pins configured as "output", which is very useful in such "wire-OR" cases (to support bidirectional signaling). GPIO controllers may have - input de-glitch logic, sometimes with software controls. + input de-glitch/debounce logic, sometimes with software controls. - Inputs can often be used as IRQ signals, often edge triggered but sometimes level triggered. Such IRQs may be configurable as system @@ -60,10 +60,13 @@ used on a board that's wired differently. Only least-common-denominator functionality can be very portable. Other features are platform-specific, and that can be critical for glue logic. -Plus, this doesn't define an implementation framework, just an interface. +Plus, this doesn't require any implementation framework, just an interface. One platform might implement it as simple inline functions accessing chip registers; another might implement it by delegating through abstractions -used for several very different kinds of GPIO controller. +used for several very different kinds of GPIO controller. (There is some +optional code supporting such an implementation strategy, described later +in this document, but drivers acting as clients to the GPIO interface must +not care how it's implemented.) That said, if the convention is supported on their platform, drivers should use it when possible. Platforms should declare GENERIC_GPIO support in @@ -121,6 +124,11 @@ before tasking is enabled, as part of early board setup. For output GPIOs, the value provided becomes the initial output value. This helps avoid signal glitching during system startup. +For compatibility with legacy interfaces to GPIOs, setting the direction +of a GPIO implicitly requests that GPIO (see below) if it has not been +requested already. That compatibility may be removed in the future; +explicitly requesting GPIOs is strongly preferred. + Setting the direction can fail if the GPIO number is invalid, or when that particular GPIO can't be used in that mode. It's generally a bad idea to rely on boot firmware to have set the direction correctly, since @@ -133,6 +141,7 @@ Spinlock-Safe GPIO access ------------------------- Most GPIO controllers can be accessed with memory read/write instructions. That doesn't need to sleep, and can safely be done from inside IRQ handlers. +(That includes hardirq contexts on RT kernels.) Use these calls to access such GPIOs: @@ -145,7 +154,7 @@ Use these calls to access such GPIOs: The values are boolean, zero for low, nonzero for high. When reading the value of an output pin, the value returned should be what's seen on the pin ... that won't always match the specified output value, because of -issues including wire-OR and output latencies. +issues including open-drain signaling and output latencies. The get/set calls have no error returns because "invalid GPIO" should have been reported earlier from gpio_direction_*(). However, note that not all @@ -170,7 +179,8 @@ get to the head of a queue to transmit a command and get its response. This requires sleeping, which can't be done from inside IRQ handlers. Platforms that support this type of GPIO distinguish them from other GPIOs -by returning nonzero from this call: +by returning nonzero from this call (which requires a valid GPIO number, +either explicitly or implicitly requested): int gpio_cansleep(unsigned gpio); @@ -209,8 +219,11 @@ before tasking is enabled, as part of early board setup. These calls serve two basic purposes. One is marking the signals which are actually in use as GPIOs, for better diagnostics; systems may have several hundred potential GPIOs, but often only a dozen are used on any -given board. Another is to catch conflicts between drivers, reporting -errors when drivers wrongly think they have exclusive use of that signal. +given board. Another is to catch conflicts, identifying errors when +(a) two or more drivers wrongly think they have exclusive use of that +signal, or (b) something wrongly believes it's safe to remove drivers +needed to manage a signal that's in active use. That is, requesting a +GPIO can serve as a kind of lock. These two calls are optional because not not all current Linux platforms offer such functionality in their GPIO support; a valid implementation @@ -223,6 +236,9 @@ Note that requesting a GPIO does NOT cause it to be configured in any way; it just marks that GPIO as in use. Separate code must handle any pin setup (e.g. controlling which pin the GPIO uses, pullup/pulldown). +Also note that it's your responsibility to have stopped using a GPIO +before you free it. + GPIOs mapped to IRQs -------------------- @@ -238,7 +254,7 @@ map between them using calls like: Those return either the corresponding number in the other namespace, or else a negative errno code if the mapping can't be done. (For example, -some GPIOs can't used as IRQs.) It is an unchecked error to use a GPIO +some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO number that wasn't set up as an input using gpio_direction_input(), or to use an IRQ number that didn't originally come from gpio_to_irq(). @@ -299,17 +315,110 @@ Related to multiplexing is configuration and enabling of the pullups or pulldowns integrated on some platforms. Not all platforms support them, or support them in the same way; and any given board might use external pullups (or pulldowns) so that the on-chip ones should not be used. +(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.) There are other system-specific mechanisms that are not specified here, like the aforementioned options for input de-glitching and wire-OR output. Hardware may support reading or writing GPIOs in gangs, but that's usually configuration dependent: for GPIOs sharing the same bank. (GPIOs are commonly grouped in banks of 16 or 32, with a given SOC having several such -banks.) Some systems can trigger IRQs from output GPIOs. Code relying on -such mechanisms will necessarily be nonportable. +banks.) Some systems can trigger IRQs from output GPIOs, or read values +from pins not managed as GPIOs. Code relying on such mechanisms will +necessarily be nonportable. -Dynamic definition of GPIOs is not currently supported; for example, as +Dynamic definition of GPIOs is not currently standard; for example, as a side effect of configuring an add-on board with some GPIO expanders. These calls are purely for kernel space, but a userspace API could be built -on top of it. +on top of them. + + +GPIO implementor's framework (OPTIONAL) +======================================= +As noted earlier, there is an optional implementation framework making it +easier for platforms to support different kinds of GPIO controller using +the same programming interface. + +As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file +will be found there. That will list all the controllers registered through +this framework, and the state of the GPIOs currently in use. + + +Controller Drivers: gpio_chip +----------------------------- +In this framework each GPIO controller is packaged as a "struct gpio_chip" +with information common to each controller of that type: + + - methods to establish GPIO direction + - methods used to access GPIO values + - flag saying whether calls to its methods may sleep + - optional debugfs dump method (showing extra state like pullup config) + - label for diagnostics + +There is also per-instance data, which may come from device.platform_data: +the number of its first GPIO, and how many GPIOs it exposes. + +The code implementing a gpio_chip should support multiple instances of the +controller, possibly using the driver model. That code will configure each +gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be +rare; use gpiochip_remove() when it is unavoidable. + +Most often a gpio_chip is part of an instance-specific structure with state +not exposed by the GPIO interfaces, such as addressing, power management, +and more. Chips such as codecs will have complex non-GPIO state, + +Any debugfs dump method should normally ignore signals which haven't been +requested as GPIOs. They can use gpiochip_is_requested(), which returns +either NULL or the label associated with that GPIO when it was requested. + + +Platform Support +---------------- +To support this framework, a platform's Kconfig will "select HAVE_GPIO_LIB" +and arrange that its <asm/gpio.h> includes <asm-generic/gpio.h> and defines +three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). +They may also want to provide a custom value for ARCH_NR_GPIOS. + +Trivial implementations of those functions can directly use framework +code, which always dispatches through the gpio_chip: + + #define gpio_get_value __gpio_get_value + #define gpio_set_value __gpio_set_value + #define gpio_cansleep __gpio_cansleep + +Fancier implementations could instead define those as inline functions with +logic optimizing access to specific SOC-based GPIOs. For example, if the +referenced GPIO is the constant "12", getting or setting its value could +cost as little as two or three instructions, never sleeping. When such an +optimization is not possible those calls must delegate to the framework +code, costing at least a few dozen instructions. For bitbanged I/O, such +instruction savings can be significant. + +For SOCs, platform-specific code defines and registers gpio_chip instances +for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to +match chip vendor documentation, and directly match board schematics. They +may well start at zero and go up to a platform-specific limit. Such GPIOs +are normally integrated into platform initialization to make them always be +available, from arch_initcall() or earlier; they can often serve as IRQs. + + +Board Support +------------- +For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi +function devices, FPGAs or CPLDs -- most often board-specific code handles +registering controller devices and ensures that their drivers know what GPIO +numbers to use with gpiochip_add(). Their numbers often start right after +platform-specific GPIOs. + +For example, board setup code could create structures identifying the range +of GPIOs that chip will expose, and passes them to each GPIO expander chip +using platform_data. Then the chip driver's probe() routine could pass that +data to gpiochip_add(). + +Initialization order can be important. For example, when a device relies on +an I2C-based GPIO, its probe() routine should only be called after that GPIO +becomes available. That may mean the device should not be registered until +calls for that GPIO can work. One way to address such dependencies is for +such gpio_chip controllers to provide setup() and teardown() callbacks to +board specific code; those board specific callbacks would register devices +once all the necessary resources are available. diff --git a/Documentation/hwmon/ads7828 b/Documentation/hwmon/ads7828 new file mode 100644 index 0000000..75bc4be --- /dev/null +++ b/Documentation/hwmon/ads7828 @@ -0,0 +1,36 @@ +Kernel driver ads7828 +===================== + +Supported chips: + * Texas Instruments/Burr-Brown ADS7828 + Prefix: 'ads7828' + Addresses scanned: I2C 0x48, 0x49, 0x4a, 0x4b + Datasheet: Publicly available at the Texas Instruments website : + http://focus.ti.com/lit/ds/symlink/ads7828.pdf + +Authors: + Steve Hardy <steve@linuxrealtime.co.uk> + +Module Parameters +----------------- + +* se_input: bool (default Y) + Single ended operation - set to N for differential mode +* int_vref: bool (default Y) + Operate with the internal 2.5V reference - set to N for external reference +* vref_mv: int (default 2500) + If using an external reference, set this to the reference voltage in mV + +Description +----------- + +This driver implements support for the Texas Instruments ADS7828. + +This device is a 12-bit 8-channel A-D converter. + +It can operate in single ended mode (8 +ve inputs) or in differential mode, +where 4 differential pairs can be measured. + +The chip also has the facility to use an external voltage reference. This +may be required if your hardware supplies the ADS7828 from a 5V supply, see +the datasheet for more details. diff --git a/Documentation/hwmon/it87 b/Documentation/hwmon/it87 index 5b704a4..f4ce1fd 100644 --- a/Documentation/hwmon/it87 +++ b/Documentation/hwmon/it87 @@ -30,7 +30,7 @@ Supported chips: Datasheet: No longer be available Authors: - Christophe Gauthron <chrisg@0-in.com> + Christophe Gauthron Jean Delvare <khali@linux-fr.org> diff --git a/Documentation/hwmon/lm78 b/Documentation/hwmon/lm78 index dfc318a..60932e2 100644 --- a/Documentation/hwmon/lm78 +++ b/Documentation/hwmon/lm78 @@ -4,12 +4,12 @@ Kernel driver lm78 Supported chips: * National Semiconductor LM78 / LM78-J Prefix: 'lm78' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) Datasheet: Publicly available at the National Semiconductor website http://www.national.com/ * National Semiconductor LM79 Prefix: 'lm79' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) Datasheet: Publicly available at the National Semiconductor website http://www.national.com/ diff --git a/Documentation/hwmon/lm87 b/Documentation/hwmon/lm87 index c952c57..ec27aa1 100644 --- a/Documentation/hwmon/lm87 +++ b/Documentation/hwmon/lm87 @@ -4,8 +4,12 @@ Kernel driver lm87 Supported chips: * National Semiconductor LM87 Prefix: 'lm87' - Addresses scanned: I2C 0x2c - 0x2f + Addresses scanned: I2C 0x2c - 0x2e Datasheet: http://www.national.com/pf/LM/LM87.html + * Analog Devices ADM1024 + Prefix: 'adm1024' + Addresses scanned: I2C 0x2c - 0x2e + Datasheet: http://www.analog.com/en/prod/0,2877,ADM1024,00.html Authors: Frodo Looijaard <frodol@dds.nl>, @@ -19,11 +23,12 @@ Authors: Description ----------- -This driver implements support for the National Semiconductor LM87. +This driver implements support for the National Semiconductor LM87 +and the Analog Devices ADM1024. The LM87 implements up to three temperature sensors, up to two fan rotation speed sensors, up to seven voltage sensors, alarms, and some -miscellaneous stuff. +miscellaneous stuff. The ADM1024 is fully compatible. Temperatures are measured in degrees Celsius. Each input has a high and low alarm settings. A high limit produces an alarm when the value diff --git a/Documentation/hwmon/userspace-tools b/Documentation/hwmon/userspace-tools index 19900a8..9865aee 100644 --- a/Documentation/hwmon/userspace-tools +++ b/Documentation/hwmon/userspace-tools @@ -14,7 +14,7 @@ Lm-sensors Core set of utilities that will allow you to obtain health information, setup monitoring limits etc. You can get them on their homepage -http://www.lm-sensors.nu/ or as a package from your Linux distribution. +http://www.lm-sensors.org/ or as a package from your Linux distribution. If from website: Get lm-sensors from project web site. Please note, you need only userspace diff --git a/Documentation/hwmon/w83627ehf b/Documentation/hwmon/w83627ehf index ccc2bcb..d6e1ae3 100644 --- a/Documentation/hwmon/w83627ehf +++ b/Documentation/hwmon/w83627ehf @@ -23,8 +23,9 @@ 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), one -VID (6 pins), alarms with beep warnings (control unimplemented), and -some automatic fan regulation strategies (plus manual fan control mode). +VID (6 pins for the 627EHF/EHG, 8 pins for the 627DHG), 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/hwmon/w83627hf b/Documentation/hwmon/w83627hf index 7922319..880a59f 100644 --- a/Documentation/hwmon/w83627hf +++ b/Documentation/hwmon/w83627hf @@ -73,5 +73,4 @@ doesn't help, you may just ignore the bogus VID reading with no harm done. For further information on this driver see the w83781d driver documentation. -[1] http://www2.lm-sensors.nu/~lm78/cvs/browse.cgi/lm_sensors2/doc/vid - +[1] http://www.lm-sensors.org/browser/lm-sensors/trunk/doc/vid diff --git a/Documentation/hwmon/w83781d b/Documentation/hwmon/w83781d index b1e9f80..6f800a0 100644 --- a/Documentation/hwmon/w83781d +++ b/Documentation/hwmon/w83781d @@ -4,20 +4,16 @@ Kernel driver w83781d Supported chips: * Winbond W83781D Prefix: 'w83781d' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83781d.pdf * Winbond W83782D Prefix: 'w83782d' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) + Addresses scanned: I2C 0x28 - 0x2f, ISA 0x290 (8 I/O ports) Datasheet: http://www.winbond.com/PDF/sheet/w83782d.pdf * Winbond W83783S Prefix: 'w83783s' Addresses scanned: I2C 0x2d Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/w83783s.pdf - * Winbond W83627HF - Prefix: 'w83627hf' - Addresses scanned: I2C 0x20 - 0x2f, ISA 0x290 (8 I/O ports) - Datasheet: http://www.winbond.com/PDF/sheet/w83627hf.pdf * Asus AS99127F Prefix: 'as99127f' Addresses scanned: I2C 0x28 - 0x2f @@ -50,20 +46,18 @@ force_subclients=bus,caddr,saddr,saddr Description ----------- -This driver implements support for the Winbond W83781D, W83782D, W83783S, -W83627HF chips, and the Asus AS99127F chips. We will refer to them -collectively as W8378* chips. +This driver implements support for the Winbond W83781D, W83782D, W83783S +chips, and the Asus AS99127F chips. We will refer to them collectively as +W8378* chips. There is quite some difference between these chips, but they are similar enough that it was sensible to put them together in one driver. -The W83627HF chip is assumed to be identical to the ISA W83782D. The Asus chips are similar to an I2C-only W83782D. Chip #vin #fanin #pwm #temp wchipid vendid i2c ISA as99127f 7 3 0 3 0x31 0x12c3 yes no as99127f rev.2 (type_name = as99127f) 0x31 0x5ca3 yes no w83781d 7 3 0 3 0x10-1 0x5ca3 yes yes -w83627hf 9 3 2 3 0x21 0x5ca3 yes yes(LPC) w83782d 9 3 2-4 3 0x30 0x5ca3 yes yes w83783s 5-6 3 2 1-2 0x40 0x5ca3 yes no @@ -143,9 +137,9 @@ Individual alarm and beep bits: 0x000400: in6 0x000800: fan3 0x001000: chassis -0x002000: temp3 (W83782D and W83627HF only) -0x010000: in7 (W83782D and W83627HF only) -0x020000: in8 (W83782D and W83627HF only) +0x002000: temp3 (W83782D only) +0x010000: in7 (W83782D only) +0x020000: in8 (W83782D only) If an alarm triggers, it will remain triggered until the hardware register is read at least once. This means that the cause for the alarm may diff --git a/Documentation/hwmon/w83l786ng b/Documentation/hwmon/w83l786ng new file mode 100644 index 0000000..d8f55d7 --- /dev/null +++ b/Documentation/hwmon/w83l786ng @@ -0,0 +1,54 @@ +Kernel driver w83l786ng +===================== + +Supported chips: + * Winbond W83L786NG/W83L786NR + Prefix: 'w83l786ng' + Addresses scanned: I2C 0x2e - 0x2f + Datasheet: http://www.winbond-usa.com/products/winbond_products/pdfs/PCIC/W83L786NRNG09.pdf + +Author: Kevin Lo <kevlo@kevlo.org> + + +Module Parameters +----------------- + +* reset boolean + (default 0) + Use 'reset=1' to reset the chip (via index 0x40, bit 7). The default + behavior is no chip reset to preserve BIOS settings + + +Description +----------- + +This driver implements support for Winbond W83L786NG/W83L786NR chips. + +The driver implements two temperature sensors, two fan rotation speed +sensors, and three voltage sensors. + +Temperatures are measured in degrees Celsius and measurement resolution is 1 +degC for temp1 and temp2. + +Fan rotation speeds are reported in RPM (rotations per minute). Fan readings +readings can be divided by a programmable divider (1, 2, 4, 8, 16, 32, 64 +or 128 for fan 1/2) to give the readings more range or accuracy. + +Voltage sensors (also known as IN sensors) report their values in millivolts. +An alarm is triggered if the voltage has crossed a programmable minimum +or maximum limit. + +/sys files +---------- + +pwm[1-2] - this file stores PWM duty cycle or DC value (fan speed) in range: + 0 (stop) to 255 (full) +pwm[1-2]_enable - this file controls mode of fan/temperature control: + * 0 Manual Mode + * 1 Thermal Cruise + * 2 Smart Fan II + * 4 FAN_SET +pwm[1-2]_mode - Select PWM of DC mode + * 0 DC + * 1 PWM +tolerance[1-2] - Value in degrees of Celsius (degC) for +- T diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4 index cf6b6cb..ef1efa7 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4 @@ -95,4 +95,4 @@ of all affected systems, so the only safe solution was to prevent access to the SMBus on all IBM systems (detected using DMI data.) For additional information, read: -http://www2.lm-sensors.nu/~lm78/cvs/lm_sensors2/README.thinkpad +http://www.lm-sensors.org/browser/lm-sensors/trunk/README.thinkpad diff --git a/Documentation/i2c/chips/pca9539 b/Documentation/i2c/chips/pca9539 index c4fce6a..1d81c53 100644 --- a/Documentation/i2c/chips/pca9539 +++ b/Documentation/i2c/chips/pca9539 @@ -1,6 +1,9 @@ Kernel driver pca9539 ===================== +NOTE: this driver is deprecated and will be dropped soon, use +drivers/gpio/pca9539.c instead. + Supported chips: * Philips PCA9539 Prefix: 'pca9539' diff --git a/Documentation/ia64/aliasing-test.c b/Documentation/ia64/aliasing-test.c index 773a814..d23610f 100644 --- a/Documentation/ia64/aliasing-test.c +++ b/Documentation/ia64/aliasing-test.c @@ -16,6 +16,7 @@ #include <fcntl.h> #include <fnmatch.h> #include <string.h> +#include <sys/ioctl.h> #include <sys/mman.h> #include <sys/stat.h> #include <unistd.h> @@ -65,7 +66,7 @@ int scan_tree(char *path, char *file, off_t offset, size_t length, int touch) { struct dirent **namelist; char *name, *path2; - int i, n, r, rc, result = 0; + int i, n, r, rc = 0, result = 0; struct stat buf; n = scandir(path, &namelist, 0, alphasort); @@ -113,7 +114,7 @@ skip: free(namelist[i]); } free(namelist); - return rc; + return result; } char buf[1024]; @@ -149,7 +150,7 @@ int scan_rom(char *path, char *file) { struct dirent **namelist; char *name, *path2; - int i, n, r, rc, result = 0; + int i, n, r, rc = 0, result = 0; struct stat buf; n = scandir(path, &namelist, 0, alphasort); @@ -180,7 +181,7 @@ int scan_rom(char *path, char *file) * important thing is that no MCA happened. */ if (rc > 0) - fprintf(stderr, "PASS: %s read %ld bytes\n", path2, rc); + fprintf(stderr, "PASS: %s read %d bytes\n", path2, rc); else { fprintf(stderr, "PASS: %s not readable\n", path2); return rc; @@ -201,10 +202,10 @@ skip: free(namelist[i]); } free(namelist); - return rc; + return result; } -int main() +int main(void) { int rc; @@ -256,4 +257,6 @@ int main() scan_tree("/proc/bus/pci", "??.?", 0xA0000, 0x20000, 0); scan_tree("/proc/bus/pci", "??.?", 0xC0000, 0x40000, 1); scan_tree("/proc/bus/pci", "??.?", 0, 1024*1024, 0); + + return rc; } diff --git a/Documentation/ide/ChangeLog.ide-cd.1994-2004 b/Documentation/ide/ChangeLog.ide-cd.1994-2004 new file mode 100644 index 0000000..190d17b --- /dev/null +++ b/Documentation/ide/ChangeLog.ide-cd.1994-2004 @@ -0,0 +1,268 @@ +/* + * 1.00 Oct 31, 1994 -- Initial version. + * 1.01 Nov 2, 1994 -- Fixed problem with starting request in + * cdrom_check_status. + * 1.03 Nov 25, 1994 -- leaving unmask_intr[] as a user-setting (as for disks) + * (from mlord) -- minor changes to cdrom_setup() + * -- renamed ide_dev_s to ide_drive_t, enable irq on command + * 2.00 Nov 27, 1994 -- Generalize packet command interface; + * add audio ioctls. + * 2.01 Dec 3, 1994 -- Rework packet command interface to handle devices + * which send an interrupt when ready for a command. + * 2.02 Dec 11, 1994 -- Cache the TOC in the driver. + * Don't use SCMD_PLAYAUDIO_TI; it's not included + * in the current version of ATAPI. + * Try to use LBA instead of track or MSF addressing + * when possible. + * Don't wait for READY_STAT. + * 2.03 Jan 10, 1995 -- Rewrite block read routines to handle block sizes + * other than 2k and to move multiple sectors in a + * single transaction. + * 2.04 Apr 21, 1995 -- Add work-around for Creative Labs CD220E drives. + * Thanks to Nick Saw <cwsaw@pts7.pts.mot.com> for + * help in figuring this out. Ditto for Acer and + * Aztech drives, which seem to have the same problem. + * 2.04b May 30, 1995 -- Fix to match changes in ide.c version 3.16 -ml + * 2.05 Jun 8, 1995 -- Don't attempt to retry after an illegal request + * or data protect error. + * Use HWIF and DEV_HWIF macros as in ide.c. + * Always try to do a request_sense after + * a failed command. + * Include an option to give textual descriptions + * of ATAPI errors. + * Fix a bug in handling the sector cache which + * showed up if the drive returned data in 512 byte + * blocks (like Pioneer drives). Thanks to + * Richard Hirst <srh@gpt.co.uk> for diagnosing this. + * Properly supply the page number field in the + * MODE_SELECT command. + * PLAYAUDIO12 is broken on the Aztech; work around it. + * 2.05x Aug 11, 1995 -- lots of data structure renaming/restructuring in ide.c + * (my apologies to Scott, but now ide-cd.c is independent) + * 3.00 Aug 22, 1995 -- Implement CDROMMULTISESSION ioctl. + * Implement CDROMREADAUDIO ioctl (UNTESTED). + * Use input_ide_data() and output_ide_data(). + * Add door locking. + * Fix usage count leak in cdrom_open, which happened + * when a read-write mount was attempted. + * Try to load the disk on open. + * Implement CDROMEJECT_SW ioctl (off by default). + * Read total cdrom capacity during open. + * Rearrange logic in cdrom_decode_status. Issue + * request sense commands for failed packet commands + * from here instead of from cdrom_queue_packet_command. + * Fix a race condition in retrieving error information. + * Suppress printing normal unit attention errors and + * some drive not ready errors. + * Implement CDROMVOLREAD ioctl. + * Implement CDROMREADMODE1/2 ioctls. + * Fix race condition in setting up interrupt handlers + * when the `serialize' option is used. + * 3.01 Sep 2, 1995 -- Fix ordering of reenabling interrupts in + * cdrom_queue_request. + * Another try at using ide_[input,output]_data. + * 3.02 Sep 16, 1995 -- Stick total disk capacity in partition table as well. + * Make VERBOSE_IDE_CD_ERRORS dump failed command again. + * Dump out more information for ILLEGAL REQUEST errs. + * Fix handling of errors occurring before the + * packet command is transferred. + * Fix transfers with odd bytelengths. + * 3.03 Oct 27, 1995 -- Some Creative drives have an id of just `CD'. + * `DCI-2S10' drives are broken too. + * 3.04 Nov 20, 1995 -- So are Vertos drives. + * 3.05 Dec 1, 1995 -- Changes to go with overhaul of ide.c and ide-tape.c + * 3.06 Dec 16, 1995 -- Add support needed for partitions. + * More workarounds for Vertos bugs (based on patches + * from Holger Dietze <dietze@aix520.informatik.uni-leipzig.de>). + * Try to eliminate byteorder assumptions. + * Use atapi_cdrom_subchnl struct definition. + * Add STANDARD_ATAPI compilation option. + * 3.07 Jan 29, 1996 -- More twiddling for broken drives: Sony 55D, + * Vertos 300. + * Add NO_DOOR_LOCKING configuration option. + * Handle drive_cmd requests w/NULL args (for hdparm -t). + * Work around sporadic Sony55e audio play problem. + * 3.07a Feb 11, 1996 -- check drive->id for NULL before dereferencing, to fix + * problem with "hde=cdrom" with no drive present. -ml + * 3.08 Mar 6, 1996 -- More Vertos workarounds. + * 3.09 Apr 5, 1996 -- Add CDROMCLOSETRAY ioctl. + * Switch to using MSF addressing for audio commands. + * Reformat to match kernel tabbing style. + * Add CDROM_GET_UPC ioctl. + * 3.10 Apr 10, 1996 -- Fix compilation error with STANDARD_ATAPI. + * 3.11 Apr 29, 1996 -- Patch from Heiko Eißfeldt <heiko@colossus.escape.de> + * to remove redundant verify_area calls. + * 3.12 May 7, 1996 -- Rudimentary changer support. Based on patches + * from Gerhard Zuber <zuber@berlin.snafu.de>. + * Let open succeed even if there's no loaded disc. + * 3.13 May 19, 1996 -- Fixes for changer code. + * 3.14 May 29, 1996 -- Add work-around for Vertos 600. + * (From Hennus Bergman <hennus@sky.ow.nl>.) + * 3.15 July 2, 1996 -- Added support for Sanyo 3 CD changers + * from Ben Galliart <bgallia@luc.edu> with + * special help from Jeff Lightfoot + * <jeffml@pobox.com> + * 3.15a July 9, 1996 -- Improved Sanyo 3 CD changer identification + * 3.16 Jul 28, 1996 -- Fix from Gadi to reduce kernel stack usage for ioctl. + * 3.17 Sep 17, 1996 -- Tweak audio reads for some drives. + * Start changing CDROMLOADFROMSLOT to CDROM_SELECT_DISC. + * 3.18 Oct 31, 1996 -- Added module and DMA support. + * + * 4.00 Nov 5, 1996 -- New ide-cd maintainer, + * Erik B. Andersen <andersee@debian.org> + * -- Newer Creative drives don't always set the error + * register correctly. Make sure we see media changes + * regardless. + * -- Integrate with generic cdrom driver. + * -- CDROMGETSPINDOWN and CDROMSETSPINDOWN ioctls, based on + * a patch from Ciro Cattuto <>. + * -- Call set_device_ro. + * -- Implement CDROMMECHANISMSTATUS and CDROMSLOTTABLE + * ioctls, based on patch by Erik Andersen + * -- Add some probes of drive capability during setup. + * + * 4.01 Nov 11, 1996 -- Split into ide-cd.c and ide-cd.h + * -- Removed CDROMMECHANISMSTATUS and CDROMSLOTTABLE + * ioctls in favor of a generalized approach + * using the generic cdrom driver. + * -- Fully integrated with the 2.1.X kernel. + * -- Other stuff that I forgot (lots of changes) + * + * 4.02 Dec 01, 1996 -- Applied patch from Gadi Oxman <gadio@netvision.net.il> + * to fix the drive door locking problems. + * + * 4.03 Dec 04, 1996 -- Added DSC overlap support. + * 4.04 Dec 29, 1996 -- Added CDROMREADRAW ioclt based on patch + * by Ales Makarov (xmakarov@sun.felk.cvut.cz) + * + * 4.05 Nov 20, 1997 -- Modified to print more drive info on init + * Minor other changes + * Fix errors on CDROMSTOP (If you have a "Dolphin", + * you must define IHAVEADOLPHIN) + * Added identifier so new Sanyo CD-changer works + * Better detection if door locking isn't supported + * + * 4.06 Dec 17, 1997 -- fixed endless "tray open" messages -ml + * 4.07 Dec 17, 1997 -- fallback to set pc->stat on "tray open" + * 4.08 Dec 18, 1997 -- spew less noise when tray is empty + * -- fix speed display for ACER 24X, 18X + * 4.09 Jan 04, 1998 -- fix handling of the last block so we return + * an end of file instead of an I/O error (Gadi) + * 4.10 Jan 24, 1998 -- fixed a bug so now changers can change to a new + * slot when there is no disc in the current slot. + * -- Fixed a memory leak where info->changer_info was + * malloc'ed but never free'd when closing the device. + * -- Cleaned up the global namespace a bit by making more + * functions static that should already have been. + * 4.11 Mar 12, 1998 -- Added support for the CDROM_SELECT_SPEED ioctl + * based on a patch for 2.0.33 by Jelle Foks + * <jelle@scintilla.utwente.nl>, a patch for 2.0.33 + * by Toni Giorgino <toni@pcape2.pi.infn.it>, the SCSI + * version, and my own efforts. -erik + * -- Fixed a stupid bug which egcs was kind enough to + * inform me of where "Illegal mode for this track" + * was never returned due to a comparison on data + * types of limited range. + * 4.12 Mar 29, 1998 -- Fixed bug in CDROM_SELECT_SPEED so write speed is + * now set ionly for CD-R and CD-RW drives. I had + * removed this support because it produced errors. + * It produced errors _only_ for non-writers. duh. + * 4.13 May 05, 1998 -- Suppress useless "in progress of becoming ready" + * messages, since this is not an error. + * -- Change error messages to be const + * -- Remove a "\t" which looks ugly in the syslogs + * 4.14 July 17, 1998 -- Change to pointing to .ps version of ATAPI spec + * since the .pdf version doesn't seem to work... + * -- Updated the TODO list to something more current. + * + * 4.15 Aug 25, 1998 -- Updated ide-cd.h to respect mechine endianess, + * patch thanks to "Eddie C. Dost" <ecd@skynet.be> + * + * 4.50 Oct 19, 1998 -- New maintainers! + * Jens Axboe <axboe@image.dk> + * Chris Zwilling <chris@cloudnet.com> + * + * 4.51 Dec 23, 1998 -- Jens Axboe <axboe@image.dk> + * - ide_cdrom_reset enabled since the ide subsystem + * handles resets fine now. <axboe@image.dk> + * - Transfer size fix for Samsung CD-ROMs, thanks to + * "Ville Hallik" <ville.hallik@mail.ee>. + * - other minor stuff. + * + * 4.52 Jan 19, 1999 -- Jens Axboe <axboe@image.dk> + * - Detect DVD-ROM/RAM drives + * + * 4.53 Feb 22, 1999 - Include other model Samsung and one Goldstar + * drive in transfer size limit. + * - Fix the I/O error when doing eject without a medium + * loaded on some drives. + * - CDROMREADMODE2 is now implemented through + * CDROMREADRAW, since many drives don't support + * MODE2 (even though ATAPI 2.6 says they must). + * - Added ignore parameter to ide-cd (as a module), eg + * insmod ide-cd ignore='hda hdb' + * Useful when using ide-cd in conjunction with + * ide-scsi. TODO: non-modular way of doing the + * same. + * + * 4.54 Aug 5, 1999 - Support for MMC2 class commands through the generic + * packet interface to cdrom.c. + * - Unified audio ioctl support, most of it. + * - cleaned up various deprecated verify_area(). + * - Added ide_cdrom_packet() as the interface for + * the Uniform generic_packet(). + * - bunch of other stuff, will fill in logs later. + * - report 1 slot for non-changers, like the other + * cd-rom drivers. don't report select disc for + * non-changers as well. + * - mask out audio playing, if the device can't do it. + * + * 4.55 Sep 1, 1999 - Eliminated the rest of the audio ioctls, except + * for CDROMREADTOC[ENTRY|HEADER]. Some of the drivers + * use this independently of the actual audio handling. + * They will disappear later when I get the time to + * do it cleanly. + * - Minimize the TOC reading - only do it when we + * know a media change has occurred. + * - Moved all the CDROMREADx ioctls to the Uniform layer. + * - Heiko Eißfeldt <heiko@colossus.escape.de> supplied + * some fixes for CDI. + * - CD-ROM leaving door locked fix from Andries + * Brouwer <Andries.Brouwer@cwi.nl> + * - Erik Andersen <andersen@xmission.com> unified + * commands across the various drivers and how + * sense errors are handled. + * + * 4.56 Sep 12, 1999 - Removed changer support - it is now in the + * Uniform layer. + * - Added partition based multisession handling. + * - Mode sense and mode select moved to the + * Uniform layer. + * - Fixed a problem with WPI CDS-32X drive - it + * failed the capabilities + * + * 4.57 Apr 7, 2000 - Fixed sense reporting. + * - Fixed possible oops in ide_cdrom_get_last_session() + * - Fix locking mania and make ide_cdrom_reset relock + * - Stop spewing errors to log when magicdev polls with + * TEST_UNIT_READY on some drives. + * - Various fixes from Tobias Ringstrom: + * tray if it was locked prior to the reset. + * - cdrom_read_capacity returns one frame too little. + * - Fix real capacity reporting. + * + * 4.58 May 1, 2000 - Clean up ACER50 stuff. + * - Fix small problem with ide_cdrom_capacity + * + * 4.59 Aug 11, 2000 - Fix changer problem in cdrom_read_toc, we weren't + * correctly sensing a disc change. + * - Rearranged some code + * - Use extended sense on drives that support it for + * correctly reporting tray status -- from + * Michael D Johnson <johnsom@orst.edu> + * 4.60 Dec 17, 2003 - Add mt rainier support + * - Bump timeout for packet commands, matches sr + * - Odd stuff + * 4.61 Jan 22, 2004 - support hardware sector sizes other than 2kB, + * Pascal Schmidt <der.eremit@email.de> + */ diff --git a/Documentation/ide/ChangeLog.ide-floppy.1996-2002 b/Documentation/ide/ChangeLog.ide-floppy.1996-2002 new file mode 100644 index 0000000..46c19ef --- /dev/null +++ b/Documentation/ide/ChangeLog.ide-floppy.1996-2002 @@ -0,0 +1,63 @@ +/* + * Many thanks to Lode Leroy <Lode.Leroy@www.ibase.be>, who tested so many + * ALPHA patches to this driver on an EASYSTOR LS-120 ATAPI floppy drive. + * + * Ver 0.1 Oct 17 96 Initial test version, mostly based on ide-tape.c. + * Ver 0.2 Oct 31 96 Minor changes. + * Ver 0.3 Dec 2 96 Fixed error recovery bug. + * Ver 0.4 Jan 26 97 Add support for the HDIO_GETGEO ioctl. + * Ver 0.5 Feb 21 97 Add partitions support. + * Use the minimum of the LBA and CHS capacities. + * Avoid hwgroup->rq == NULL on the last irq. + * Fix potential null dereferencing with DEBUG_LOG. + * Ver 0.8 Dec 7 97 Increase irq timeout from 10 to 50 seconds. + * Add media write-protect detection. + * Issue START command only if TEST UNIT READY fails. + * Add work-around for IOMEGA ZIP revision 21.D. + * Remove idefloppy_get_capabilities(). + * Ver 0.9 Jul 4 99 Fix a bug which might have caused the number of + * bytes requested on each interrupt to be zero. + * Thanks to <shanos@es.co.nz> for pointing this out. + * Ver 0.9.sv Jan 6 01 Sam Varshavchik <mrsam@courier-mta.com> + * Implement low level formatting. Reimplemented + * IDEFLOPPY_CAPABILITIES_PAGE, since we need the srfp + * bit. My LS-120 drive barfs on + * IDEFLOPPY_CAPABILITIES_PAGE, but maybe it's just me. + * Compromise by not reporting a failure to get this + * mode page. Implemented four IOCTLs in order to + * implement formatting. IOCTls begin with 0x4600, + * 0x46 is 'F' as in Format. + * Jan 9 01 Userland option to select format verify. + * Added PC_SUPPRESS_ERROR flag - some idefloppy drives + * do not implement IDEFLOPPY_CAPABILITIES_PAGE, and + * return a sense error. Suppress error reporting in + * this particular case in order to avoid spurious + * errors in syslog. The culprit is + * idefloppy_get_capability_page(), so move it to + * idefloppy_begin_format() so that it's not used + * unless absolutely necessary. + * If drive does not support format progress indication + * monitor the dsc bit in the status register. + * Also, O_NDELAY on open will allow the device to be + * opened without a disk available. This can be used to + * open an unformatted disk, or get the device capacity. + * Ver 0.91 Dec 11 99 Added IOMEGA Clik! drive support by + * <paul@paulbristow.net> + * Ver 0.92 Oct 22 00 Paul Bristow became official maintainer for this + * driver. Included Powerbook internal zip kludge. + * Ver 0.93 Oct 24 00 Fixed bugs for Clik! drive + * no disk on insert and disk change now works + * Ver 0.94 Oct 27 00 Tidied up to remove strstr(Clik) everywhere + * Ver 0.95 Nov 7 00 Brought across to kernel 2.4 + * Ver 0.96 Jan 7 01 Actually in line with release version of 2.4.0 + * including set_bit patch from Rusty Russell + * Ver 0.97 Jul 22 01 Merge 0.91-0.96 onto 0.9.sv for ac series + * Ver 0.97.sv Aug 3 01 Backported from 2.4.7-ac3 + * Ver 0.98 Oct 26 01 Split idefloppy_transfer_pc into two pieces to + * fix a lost interrupt problem. It appears the busy + * bit was being deasserted by my IOMEGA ATAPI ZIP 100 + * drive before the drive was actually ready. + * Ver 0.98a Oct 29 01 Expose delay value so we can play. + * Ver 0.99 Feb 24 02 Remove duplicate code, modify clik! detection code + * to support new PocketZip drives + */ diff --git a/Documentation/ide/ChangeLog.ide-tape.1995-2002 b/Documentation/ide/ChangeLog.ide-tape.1995-2002 new file mode 100644 index 0000000..877fac8 --- /dev/null +++ b/Documentation/ide/ChangeLog.ide-tape.1995-2002 @@ -0,0 +1,257 @@ +/* + * Ver 0.1 Nov 1 95 Pre-working code :-) + * Ver 0.2 Nov 23 95 A short backup (few megabytes) and restore procedure + * was successful ! (Using tar cvf ... on the block + * device interface). + * A longer backup resulted in major swapping, bad + * overall Linux performance and eventually failed as + * we received non serial read-ahead requests from the + * buffer cache. + * Ver 0.3 Nov 28 95 Long backups are now possible, thanks to the + * character device interface. Linux's responsiveness + * and performance doesn't seem to be much affected + * from the background backup procedure. + * Some general mtio.h magnetic tape operations are + * now supported by our character device. As a result, + * popular tape utilities are starting to work with + * ide tapes :-) + * The following configurations were tested: + * 1. An IDE ATAPI TAPE shares the same interface + * and irq with an IDE ATAPI CDROM. + * 2. An IDE ATAPI TAPE shares the same interface + * and irq with a normal IDE disk. + * Both configurations seemed to work just fine ! + * However, to be on the safe side, it is meanwhile + * recommended to give the IDE TAPE its own interface + * and irq. + * The one thing which needs to be done here is to + * add a "request postpone" feature to ide.c, + * so that we won't have to wait for the tape to finish + * performing a long media access (DSC) request (such + * as a rewind) before we can access the other device + * on the same interface. This effect doesn't disturb + * normal operation most of the time because read/write + * requests are relatively fast, and once we are + * performing one tape r/w request, a lot of requests + * from the other device can be queued and ide.c will + * service all of them after this single tape request. + * Ver 1.0 Dec 11 95 Integrated into Linux 1.3.46 development tree. + * On each read / write request, we now ask the drive + * if we can transfer a constant number of bytes + * (a parameter of the drive) only to its buffers, + * without causing actual media access. If we can't, + * we just wait until we can by polling the DSC bit. + * This ensures that while we are not transferring + * more bytes than the constant referred to above, the + * interrupt latency will not become too high and + * we won't cause an interrupt timeout, as happened + * occasionally in the previous version. + * While polling for DSC, the current request is + * postponed and ide.c is free to handle requests from + * the other device. This is handled transparently to + * ide.c. The hwgroup locking method which was used + * in the previous version was removed. + * Use of new general features which are provided by + * ide.c for use with atapi devices. + * (Programming done by Mark Lord) + * Few potential bug fixes (Again, suggested by Mark) + * Single character device data transfers are now + * not limited in size, as they were before. + * We are asking the tape about its recommended + * transfer unit and send a larger data transfer + * as several transfers of the above size. + * For best results, use an integral number of this + * basic unit (which is shown during driver + * initialization). I will soon add an ioctl to get + * this important parameter. + * Our data transfer buffer is allocated on startup, + * rather than before each data transfer. This should + * ensure that we will indeed have a data buffer. + * Ver 1.1 Dec 14 95 Fixed random problems which occurred when the tape + * shared an interface with another device. + * (poll_for_dsc was a complete mess). + * Removed some old (non-active) code which had + * to do with supporting buffer cache originated + * requests. + * The block device interface can now be opened, so + * that general ide driver features like the unmask + * interrupts flag can be selected with an ioctl. + * This is the only use of the block device interface. + * New fast pipelined operation mode (currently only on + * writes). When using the pipelined mode, the + * throughput can potentially reach the maximum + * tape supported throughput, regardless of the + * user backup program. On my tape drive, it sometimes + * boosted performance by a factor of 2. Pipelined + * mode is enabled by default, but since it has a few + * downfalls as well, you may want to disable it. + * A short explanation of the pipelined operation mode + * is available below. + * Ver 1.2 Jan 1 96 Eliminated pipelined mode race condition. + * Added pipeline read mode. As a result, restores + * are now as fast as backups. + * Optimized shared interface behavior. The new behavior + * typically results in better IDE bus efficiency and + * higher tape throughput. + * Pre-calculation of the expected read/write request + * service time, based on the tape's parameters. In + * the pipelined operation mode, this allows us to + * adjust our polling frequency to a much lower value, + * and thus to dramatically reduce our load on Linux, + * without any decrease in performance. + * Implemented additional mtio.h operations. + * The recommended user block size is returned by + * the MTIOCGET ioctl. + * Additional minor changes. + * Ver 1.3 Feb 9 96 Fixed pipelined read mode bug which prevented the + * use of some block sizes during a restore procedure. + * The character device interface will now present a + * continuous view of the media - any mix of block sizes + * during a backup/restore procedure is supported. The + * driver will buffer the requests internally and + * convert them to the tape's recommended transfer + * unit, making performance almost independent of the + * chosen user block size. + * Some improvements in error recovery. + * By cooperating with ide-dma.c, bus mastering DMA can + * now sometimes be used with IDE tape drives as well. + * Bus mastering DMA has the potential to dramatically + * reduce the CPU's overhead when accessing the device, + * and can be enabled by using hdparm -d1 on the tape's + * block device interface. For more info, read the + * comments in ide-dma.c. + * Ver 1.4 Mar 13 96 Fixed serialize support. + * Ver 1.5 Apr 12 96 Fixed shared interface operation, broken in 1.3.85. + * Fixed pipelined read mode inefficiency. + * Fixed nasty null dereferencing bug. + * Ver 1.6 Aug 16 96 Fixed FPU usage in the driver. + * Fixed end of media bug. + * Ver 1.7 Sep 10 96 Minor changes for the CONNER CTT8000-A model. + * Ver 1.8 Sep 26 96 Attempt to find a better balance between good + * interactive response and high system throughput. + * Ver 1.9 Nov 5 96 Automatically cross encountered filemarks rather + * than requiring an explicit FSF command. + * Abort pending requests at end of media. + * MTTELL was sometimes returning incorrect results. + * Return the real block size in the MTIOCGET ioctl. + * Some error recovery bug fixes. + * Ver 1.10 Nov 5 96 Major reorganization. + * Reduced CPU overhead a bit by eliminating internal + * bounce buffers. + * Added module support. + * Added multiple tape drives support. + * Added partition support. + * Rewrote DSC handling. + * Some portability fixes. + * Removed ide-tape.h. + * Additional minor changes. + * Ver 1.11 Dec 2 96 Bug fix in previous DSC timeout handling. + * Use ide_stall_queue() for DSC overlap. + * Use the maximum speed rather than the current speed + * to compute the request service time. + * Ver 1.12 Dec 7 97 Fix random memory overwriting and/or last block data + * corruption, which could occur if the total number + * of bytes written to the tape was not an integral + * number of tape blocks. + * Add support for INTERRUPT DRQ devices. + * Ver 1.13 Jan 2 98 Add "speed == 0" work-around for HP COLORADO 5GB + * Ver 1.14 Dec 30 98 Partial fixes for the Sony/AIWA tape drives. + * Replace cli()/sti() with hwgroup spinlocks. + * Ver 1.15 Mar 25 99 Fix SMP race condition by replacing hwgroup + * spinlock with private per-tape spinlock. + * Ver 1.16 Sep 1 99 Add OnStream tape support. + * Abort read pipeline on EOD. + * Wait for the tape to become ready in case it returns + * "in the process of becoming ready" on open(). + * Fix zero padding of the last written block in + * case the tape block size is larger than PAGE_SIZE. + * Decrease the default disconnection time to tn. + * Ver 1.16e Oct 3 99 Minor fixes. + * Ver 1.16e1 Oct 13 99 Patches by Arnold Niessen, + * niessen@iae.nl / arnold.niessen@philips.com + * GO-1) Undefined code in idetape_read_position + * according to Gadi's email + * AJN-1) Minor fix asc == 11 should be asc == 0x11 + * in idetape_issue_packet_command (did effect + * debugging output only) + * AJN-2) Added more debugging output, and + * added ide-tape: where missing. I would also + * like to add tape->name where possible + * AJN-3) Added different debug_level's + * via /proc/ide/hdc/settings + * "debug_level" determines amount of debugging output; + * can be changed using /proc/ide/hdx/settings + * 0 : almost no debugging output + * 1 : 0+output errors only + * 2 : 1+output all sensekey/asc + * 3 : 2+follow all chrdev related procedures + * 4 : 3+follow all procedures + * 5 : 4+include pc_stack rq_stack info + * 6 : 5+USE_COUNT updates + * AJN-4) Fixed timeout for retension in idetape_queue_pc_tail + * from 5 to 10 minutes + * AJN-5) Changed maximum number of blocks to skip when + * reading tapes with multiple consecutive write + * errors from 100 to 1000 in idetape_get_logical_blk + * Proposed changes to code: + * 1) output "logical_blk_num" via /proc + * 2) output "current_operation" via /proc + * 3) Either solve or document the fact that `mt rewind' is + * required after reading from /dev/nhtx to be + * able to rmmod the idetape module; + * Also, sometimes an application finishes but the + * device remains `busy' for some time. Same cause ? + * Proposed changes to release-notes: + * 4) write a simple `quickstart' section in the + * release notes; I volunteer if you don't want to + * 5) include a pointer to video4linux in the doc + * to stimulate video applications + * 6) release notes lines 331 and 362: explain what happens + * if the application data rate is higher than 1100 KB/s; + * similar approach to lower-than-500 kB/s ? + * 7) 6.6 Comparison; wouldn't it be better to allow different + * strategies for read and write ? + * Wouldn't it be better to control the tape buffer + * contents instead of the bandwidth ? + * 8) line 536: replace will by would (if I understand + * this section correctly, a hypothetical and unwanted situation + * is being described) + * Ver 1.16f Dec 15 99 Change place of the secondary OnStream header frames. + * Ver 1.17 Nov 2000 / Jan 2001 Marcel Mol, marcel@mesa.nl + * - Add idetape_onstream_mode_sense_tape_parameter_page + * function to get tape capacity in frames: tape->capacity. + * - Add support for DI-50 drives( or any DI- drive). + * - 'workaround' for read error/blank block around block 3000. + * - Implement Early warning for end of media for Onstream. + * - Cosmetic code changes for readability. + * - Idetape_position_tape should not use SKIP bit during + * Onstream read recovery. + * - Add capacity, logical_blk_num and first/last_frame_position + * to /proc/ide/hd?/settings. + * - Module use count was gone in the Linux 2.4 driver. + * Ver 1.17a Apr 2001 Willem Riede osst@riede.org + * - Get drive's actual block size from mode sense block descriptor + * - Limit size of pipeline + * Ver 1.17b Oct 2002 Alan Stern <stern@rowland.harvard.edu> + * Changed IDETAPE_MIN_PIPELINE_STAGES to 1 and actually used + * it in the code! + * Actually removed aborted stages in idetape_abort_pipeline + * instead of just changing the command code. + * Made the transfer byte count for Request Sense equal to the + * actual length of the data transfer. + * Changed handling of partial data transfers: they do not + * cause DMA errors. + * Moved initiation of DMA transfers to the correct place. + * Removed reference to unallocated memory. + * Made __idetape_discard_read_pipeline return the number of + * sectors skipped, not the number of stages. + * Replaced errant kfree() calls with __idetape_kfree_stage(). + * Fixed off-by-one error in testing the pipeline length. + * Fixed handling of filemarks in the read pipeline. + * Small code optimization for MTBSF and MTBSFM ioctls. + * Don't try to unlock the door during device close if is + * already unlocked! + * Cosmetic fixes to miscellaneous debugging output messages. + * Set the minimum /proc/ide/hd?/settings values for "pipeline", + * "pipeline_min", and "pipeline_max" to 1. + */ diff --git a/Documentation/ide/ide-tape.txt b/Documentation/ide/ide-tape.txt new file mode 100644 index 0000000..658f271 --- /dev/null +++ b/Documentation/ide/ide-tape.txt @@ -0,0 +1,146 @@ +/* + * IDE ATAPI streaming tape driver. + * + * This driver is a part of the Linux ide driver. + * + * The driver, in co-operation with ide.c, basically traverses the + * request-list for the block device interface. The character device + * interface, on the other hand, creates new requests, adds them + * to the request-list of the block device, and waits for their completion. + * + * Pipelined operation mode is now supported on both reads and writes. + * + * The block device major and minor numbers are determined from the + * tape's relative position in the ide interfaces, as explained in ide.c. + * + * The character device interface consists of the following devices: + * + * ht0 major 37, minor 0 first IDE tape, rewind on close. + * ht1 major 37, minor 1 second IDE tape, rewind on close. + * ... + * nht0 major 37, minor 128 first IDE tape, no rewind on close. + * nht1 major 37, minor 129 second IDE tape, no rewind on close. + * ... + * + * The general magnetic tape commands compatible interface, as defined by + * include/linux/mtio.h, is accessible through the character device. + * + * General ide driver configuration options, such as the interrupt-unmask + * flag, can be configured by issuing an ioctl to the block device interface, + * as any other ide device. + * + * Our own ide-tape ioctl's can be issued to either the block device or + * the character device interface. + * + * Maximal throughput with minimal bus load will usually be achieved in the + * following scenario: + * + * 1. ide-tape is operating in the pipelined operation mode. + * 2. No buffering is performed by the user backup program. + * + * Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive. + * + * Here are some words from the first releases of hd.c, which are quoted + * in ide.c and apply here as well: + * + * | Special care is recommended. Have Fun! + * + * + * An overview of the pipelined operation mode. + * + * In the pipelined write mode, we will usually just add requests to our + * pipeline and return immediately, before we even start to service them. The + * user program will then have enough time to prepare the next request while + * we are still busy servicing previous requests. In the pipelined read mode, + * the situation is similar - we add read-ahead requests into the pipeline, + * before the user even requested them. + * + * The pipeline can be viewed as a "safety net" which will be activated when + * the system load is high and prevents the user backup program from keeping up + * with the current tape speed. At this point, the pipeline will get + * shorter and shorter but the tape will still be streaming at the same speed. + * Assuming we have enough pipeline stages, the system load will hopefully + * decrease before the pipeline is completely empty, and the backup program + * will be able to "catch up" and refill the pipeline again. + * + * When using the pipelined mode, it would be best to disable any type of + * buffering done by the user program, as ide-tape already provides all the + * benefits in the kernel, where it can be done in a more efficient way. + * As we will usually not block the user program on a request, the most + * efficient user code will then be a simple read-write-read-... cycle. + * Any additional logic will usually just slow down the backup process. + * + * Using the pipelined mode, I get a constant over 400 KBps throughput, + * which seems to be the maximum throughput supported by my tape. + * + * However, there are some downfalls: + * + * 1. We use memory (for data buffers) in proportional to the number + * of pipeline stages (each stage is about 26 KB with my tape). + * 2. In the pipelined write mode, we cheat and postpone error codes + * to the user task. In read mode, the actual tape position + * will be a bit further than the last requested block. + * + * Concerning (1): + * + * 1. We allocate stages dynamically only when we need them. When + * we don't need them, we don't consume additional memory. In + * case we can't allocate stages, we just manage without them + * (at the expense of decreased throughput) so when Linux is + * tight in memory, we will not pose additional difficulties. + * + * 2. The maximum number of stages (which is, in fact, the maximum + * amount of memory) which we allocate is limited by the compile + * time parameter IDETAPE_MAX_PIPELINE_STAGES. + * + * 3. The maximum number of stages is a controlled parameter - We + * don't start from the user defined maximum number of stages + * but from the lower IDETAPE_MIN_PIPELINE_STAGES (again, we + * will not even allocate this amount of stages if the user + * program can't handle the speed). We then implement a feedback + * loop which checks if the pipeline is empty, and if it is, we + * increase the maximum number of stages as necessary until we + * reach the optimum value which just manages to keep the tape + * busy with minimum allocated memory or until we reach + * IDETAPE_MAX_PIPELINE_STAGES. + * + * Concerning (2): + * + * In pipelined write mode, ide-tape can not return accurate error codes + * to the user program since we usually just add the request to the + * pipeline without waiting for it to be serviced. In case an error + * occurs, I will report it on the next user request. + * + * In the pipelined read mode, subsequent read requests or forward + * filemark spacing will perform correctly, as we preserve all blocks + * and filemarks which we encountered during our excess read-ahead. + * + * For accurate tape positioning and error reporting, disabling + * pipelined mode might be the best option. + * + * You can enable/disable/tune the pipelined operation mode by adjusting + * the compile time parameters below. + * + * + * Possible improvements. + * + * 1. Support for the ATAPI overlap protocol. + * + * In order to maximize bus throughput, we currently use the DSC + * overlap method which enables ide.c to service requests from the + * other device while the tape is busy executing a command. The + * DSC overlap method involves polling the tape's status register + * for the DSC bit, and servicing the other device while the tape + * isn't ready. + * + * In the current QIC development standard (December 1995), + * it is recommended that new tape drives will *in addition* + * implement the ATAPI overlap protocol, which is used for the + * same purpose - efficient use of the IDE bus, but is interrupt + * driven and thus has much less CPU overhead. + * + * ATAPI overlap is likely to be supported in most new ATAPI + * devices, including new ATAPI cdroms, and thus provides us + * a method by which we can achieve higher throughput when + * sharing a (fast) ATA-2 disk with any (slow) new ATAPI device. + */ diff --git a/Documentation/initrd.txt b/Documentation/initrd.txt index 74f68b3..1ba84f3 100644 --- a/Documentation/initrd.txt +++ b/Documentation/initrd.txt @@ -85,7 +85,7 @@ involve special block devices or loopbacks; you merely create a directory on disk with the desired initrd content, cd to that directory, and run (as an example): -find . | cpio --quiet -c -o | gzip -9 -n > /boot/imagefile.img +find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img Examining the contents of an existing image file is just as simple: diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt index 47fc868..81905e8 100644 --- a/Documentation/input/input-programming.txt +++ b/Documentation/input/input-programming.txt @@ -22,7 +22,7 @@ static struct input_dev *button_dev; static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) { - input_report_key(button_dev, BTN_1, inb(BUTTON_PORT) & 1); + input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1); input_sync(button_dev); } diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/ja_JP/stable_kernel_rules.txt new file mode 100644 index 0000000..17d8751 --- /dev/null +++ b/Documentation/ja_JP/stable_kernel_rules.txt @@ -0,0 +1,79 @@ +NOTE: +This is Japanese translated version of "Documentation/stable_kernel_rules.txt". +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 do no intended to fork. So, if you have any +comment or update of this file, please try to update Original(English) +file at first. + +================================== +ããã¯ã +linux-2.6.24/Documentation/stable_kernel_rules.txt +ã®å訳ã§ãã + +翻訳å£ä½ï¼ JF ããã¸ã§ã¯ã < http://www.linux.or.jp/JF/ > +翻訳æ¥ï¼ 2007/12/30 +翻訳è
ï¼ Tsugikazu Shibata <tshibata at ab dot jp dot nec dot com> +æ ¡æ£è
ï¼ æ¦äºä¼¸å
ããã<takei at webmasters dot gr dot jp> + ããããã (Seiji Kaneko) <skaneko at a2 dot mbn dot or dot jp> + å°æ é
å
¸ãã (Masanori Kobayasi) <zap03216 at nifty dot ne dot jp> + éå£ãã (Kenji Noguchi) <tokyo246 at gmail dot com> + ç¥å®®ä¿¡å¤ªéãã <jin at libjingu dot jp> +================================== + +ãã£ã¨ç¥ãããã£ã Linux 2.6 -stable ãªãªã¼ã¹ã®å
¨ã¦ + +"-stable" ããªã¼ã«ã©ã®ãããªç¨®é¡ã®ããããåãå
¥ããããããã©ã®ãã㪠+ãã®ãåãå
¥ããããªãããã«ã¤ãã¦ã®è¦å- + + - æããã«æ£ããããã¹ãããã¦ãããã®ã§ãªããã°ãªããªãã + - æè(å¤æ´è¡ã®åå¾)ãå«ã㦠100 è¡ãã大ããã¦ã¯ãããªãã + - ãã ä¸åã®ãã¨ã ããä¿®æ£ãã¦ããã¹ãã + - çãæ©ã¾ãã¦ããæ¬ç©ã®ãã°ãä¿®æ£ããªããã°ãªããªãã("ããã¯ãã°ã§ + ãããããããªãã..." ã®ãããªãã®ã§ã¯ãªã) + - ãã«ãã¨ã©ã¼(CONFIG_BROKENã«ãªã£ã¦ãããã®ãé¤ã), oops, ãã³ã°ããã¼ + ã¿ç ´å£ãç¾å®ã®ã»ãã¥ãªãã£åé¡ããã®ä» "ãããããã¯ãã¡ã ã"ã¨ãã + ãããªãã®ãä¿®æ£ããªããã°ãªããªããçãè¨ãã°ãé大ãªåé¡ã + - ã©ã®ããã«ç«¶åç¶æ
ãçºçãããã®èª¬æãä¸ç·ã«æ¸ããã¦ããªãéãã + "çè«çã«ã¯ç«¶åç¶æ
ã«ãªã"ãããªãã®ã¯ä¸å¯ã + - ãããªãäºç´°ãªä¿®æ£ãå«ãããã¨ã¯ã§ããªãã(ã¹ãã«ã®ä¿®æ£ã空ç½ã®ã¯ãªã¼ + ã³ã¢ãããªã©) + - 対å¿ãããµãã·ã¹ãã ã¡ã³ãããåãå
¥ãããã®ã§ãªããã°ãªããªãã + - Documentation/SubmittingPatches ã®è¦åã«å¾ã£ããã®ã§ãªããã°ãªããªãã + +-stable ããªã¼ã«ããããéä»ããæç¶ã- + + - ä¸è¨ã®è¦åã«å¾ã£ã¦ãããã確èªããå¾ã«ãstable@kernel.org ã«ããã + ãéãã + - éä¿¡è
ã¯ãããããã¥ã¼ã«åãä»ããããéã«ã¯ ACK ããå´ä¸ãããå ´å + ã«ã¯ NAK ãåãåãããã®åå¿ã¯éçºè
ãã¡ã®ã¹ã±ã¸ã¥ã¼ã«ã«ãã£ã¦ãæ° + æ¥ãããå ´åãããã + - ããåãåããããããããã¯ä»ã®éçºè
ãã¡ã®ã¬ãã¥ã¼ã®ããã« + -stable ãã¥ã¼ã«è¿½å ãããã + - ã»ãã¥ãªãã£ãããã¯ãã®ã¨ã¤ãªã¢ã¹ (stable@kernel.org) ã«éãããã¹ + ãã§ã¯ãªãã代ããã« security@kernel.org ã®ã¢ãã¬ã¹ã«éãããã + +ã¬ãã¥ã¼ãµã¤ã¯ã«- + + - -stable ã¡ã³ãããã¬ãã¥ã¼ãµã¤ã¯ã«ã決ããã¨ãããããã¯ã¬ãã¥ã¼å§ + å¡ä¼ã¨ããããå½±é¿ããé åã®ã¡ã³ãã(æä¾è
ããã®é åã®ã¡ã³ããã§ç¡ + ãéã)ã«éãããlinux-kernel ã¡ã¼ãªã³ã°ãªã¹ãã«CCãããã + - ã¬ãã¥ã¼å§å¡ä¼ã¯ 48æéã®éã« ACK ã NAK ãåºãã + - ããããããå§å¡ä¼ã®ã¡ã³ãããå´ä¸ããããã¡ã³ããéãã¡ã³ããæ°ä» + ããªãã£ãåé¡ãæã¡ããããlinux-kernel ã¡ã³ãããããã«ç°è°ãå±ã + ãå ´åã«ã¯ããããã¯ãã¥ã¼ããåé¤ãããã + - ã¬ãã¥ã¼ãµã¤ã¯ã«ã®æå¾ã«ãACK ãåãããããã¯ææ°ã® -stable ãªãªã¼ + ã¹ã«è¿½å ããããã®å¾ã«æ°ãã -stable ãªãªã¼ã¹ãè¡ãããã + - ã»ãã¥ãªãã£ãããã¯ãé常ã®ã¬ãã¥ã¼ãµã¤ã¯ã«ãéãããã»ãã¥ãªã㣠+ ã«ã¼ãã«ãã¼ã ããç´æ¥ -stable ããªã¼ã«åãä»ããããã + ãã®æç¶ãã®è©³ç´°ã«ã¤ãã¦ã¯ kernel security ãã¼ã ã«åãåããããã¨ã + +ã¬ãã¥ã¼å§å¡ä¼- + + - ãã®å§å¡ä¼ã¯ããã®ã¿ã¹ã¯ã«ã¤ãã¦æ´»åããå¤ãã®ãã©ã³ãã£ã¢ã¨ãå°æ°ã® + éãã©ã³ãã£ã¢ã®ã«ã¼ãã«éçºè
éã§æ§æããã¦ããã + diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 92c40d1..a4fc7fc 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -147,8 +147,10 @@ and is between 256 and 4096 characters. It is defined in the file default: 0 acpi_sleep= [HW,ACPI] Sleep options - Format: { s3_bios, s3_mode } - See Documentation/power/video.txt + Format: { s3_bios, s3_mode, s3_beep } + See Documentation/power/video.txt for s3_bios and s3_mode. + s3_beep is for debugging; it makes the PC's speaker beep + as soon as the kernel's real-mode entry point is called. acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode Format: { level | edge | high | low } @@ -168,8 +170,16 @@ and is between 256 and 4096 characters. It is defined in the file acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA Format: <irq>,<irq>... + acpi_new_pts_ordering [HW,ACPI] + Enforce the ACPI 2.0 ordering of the _PTS control + method wrt putting devices into low power states + default: pre ACPI 2.0 ordering of _PTS + acpi_no_auto_ssdt [HW,ACPI] Disable automatic loading of SSDT + acpi_no_initrd_override [KNL,ACPI] + Disable loading custom ACPI tables from the initramfs + acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS Format: To spoof as Windows 98: ="Microsoft Windows" @@ -544,7 +554,7 @@ and is between 256 and 4096 characters. It is defined in the file 1 will print _a lot_ more information - normally only useful to kernel developers. - decnet= [HW,NET] + decnet.addr= [HW,NET] Format: <area>[,<node>] See also Documentation/networking/decnet.txt. @@ -775,6 +785,9 @@ and is between 256 and 4096 characters. It is defined in the file loop use the MONITOR/MWAIT idle loop anyways. Performance should be the same as idle=poll. + ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem + Claim all unknown PCI IDE storage controllers. + ignore_loglevel [KNL] Ignore loglevel setting - this will print /all/ kernel messages to the console. Useful for debugging. @@ -1556,14 +1569,17 @@ and is between 256 and 4096 characters. It is defined in the file ramdisk_size= [RAM] Sizes of RAM disks in kilobytes See Documentation/ramdisk.txt. - rcu.blimit= [KNL,BOOT] Set maximum number of finished - RCU callbacks to process in one batch. + rcupdate.blimit= [KNL,BOOT] + Set maximum number of finished RCU callbacks to process + in one batch. - rcu.qhimark= [KNL,BOOT] Set threshold of queued + rcupdate.qhimark= [KNL,BOOT] + Set threshold of queued RCU callbacks over which batch limiting is disabled. - rcu.qlowmark= [KNL,BOOT] Set threshold of queued - RCU callbacks below which batch limiting is re-enabled. + rcupdate.qlowmark= [KNL,BOOT] + Set threshold of queued RCU callbacks below which + batch limiting is re-enabled. rdinit= [KNL] Format: <full_path> @@ -1883,9 +1899,6 @@ and is between 256 and 4096 characters. It is defined in the file st= [HW,SCSI] SCSI tape parameters (buffers, etc.) See Documentation/scsi/st.txt. - st0x= [HW,SCSI] - See header of drivers/scsi/seagate.c. - sti= [PARISC,HW] Format: <num> Set the STI (builtin display/keyboard on the HP-PARISC @@ -1960,9 +1973,6 @@ and is between 256 and 4096 characters. It is defined in the file <deci-seconds>: poll all this frequency 0: no polling (default) - time Show timing data prefixed to each printk message line - [deprecated, see 'printk.time'] - tipar.timeout= [HW,PPT] Set communications timeout in tenths of a second (default 15). @@ -1970,9 +1980,6 @@ and is between 256 and 4096 characters. It is defined in the file tipar.delay= [HW,PPT] Set inter-bit delay in microseconds (default 10). - tmc8xx= [HW,SCSI] - See header of drivers/scsi/seagate.c. - tmscsim= [HW,SCSI] See comment before function dc390_setup() in drivers/scsi/tmscsim.c. diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 53a6389..30c1017 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -96,7 +96,9 @@ or in registers (e.g., for x86_64 or for an i386 fastcall function). The jprobe will work in either case, so long as the handler's prototype matches that of the probed function. -1.3 How Does a Return Probe Work? +1.3 Return Probes + +1.3.1 How Does a Return Probe Work? When you call register_kretprobe(), Kprobes establishes a kprobe at the entry to the function. When the probed function is called and this @@ -107,9 +109,9 @@ At boot time, Kprobes registers a kprobe at the trampoline. When the probed function executes its return instruction, control passes to the trampoline and that probe is hit. Kprobes' trampoline -handler calls the user-specified handler associated with the kretprobe, -then sets the saved instruction pointer to the saved return address, -and that's where execution resumes upon return from the trap. +handler calls the user-specified return handler associated with the +kretprobe, then sets the saved instruction pointer to the saved return +address, and that's where execution resumes upon return from the trap. While the probed function is executing, its return address is stored in an object of type kretprobe_instance. Before calling @@ -131,6 +133,30 @@ zero when the return probe is registered, and is incremented every time the probed function is entered but there is no kretprobe_instance object available for establishing the return probe. +1.3.2 Kretprobe entry-handler + +Kretprobes also provides an optional user-specified handler which runs +on function entry. This handler is specified by setting the entry_handler +field of the kretprobe struct. Whenever the kprobe placed by kretprobe at the +function entry is hit, the user-defined entry_handler, if any, is invoked. +If the entry_handler returns 0 (success) then a corresponding return handler +is guaranteed to be called upon function return. If the entry_handler +returns a non-zero error then Kprobes leaves the return address as is, and +the kretprobe has no further effect for that particular function instance. + +Multiple entry and return handler invocations are matched using the unique +kretprobe_instance object associated with them. Additionally, a user +may also specify per return-instance private data to be part of each +kretprobe_instance object. This is especially useful when sharing private +data between corresponding user entry and return handlers. The size of each +private data object can be specified at kretprobe registration time by +setting the data_size field of the kretprobe struct. This data can be +accessed through the data field of each kretprobe_instance object. + +In case probed function is entered but there is no kretprobe_instance +object available, then in addition to incrementing the nmissed count, +the user entry_handler invocation is also skipped. + 2. Architectures Supported Kprobes, jprobes, and return probes are implemented on the following @@ -274,6 +300,8 @@ of interest: - ret_addr: the return address - rp: points to the corresponding kretprobe object - task: points to the corresponding task struct +- data: points to per return-instance private data; see "Kretprobe + entry-handler" for details. The regs_return_value(regs) macro provides a simple abstraction to extract the return value from the appropriate register as defined by @@ -556,23 +584,52 @@ report failed calls to sys_open(). #include <linux/kernel.h> #include <linux/module.h> #include <linux/kprobes.h> +#include <linux/ktime.h> + +/* per-instance private data */ +struct my_data { + ktime_t entry_stamp; +}; static const char *probed_func = "sys_open"; -/* Return-probe handler: If the probed function fails, log the return value. */ -static int ret_handler(struct kretprobe_instance *ri, struct pt_regs *regs) +/* Timestamp function entry. */ +static int entry_handler(struct kretprobe_instance *ri, struct pt_regs *regs) +{ + struct my_data *data; + + if(!current->mm) + return 1; /* skip kernel threads */ + + data = (struct my_data *)ri->data; + data->entry_stamp = ktime_get(); + return 0; +} + +/* If the probed function failed, log the return value and duration. + * Duration may turn out to be zero consistently, depending upon the + * granularity of time accounting on the platform. */ +static int return_handler(struct kretprobe_instance *ri, struct pt_regs *regs) { int retval = regs_return_value(regs); + struct my_data *data = (struct my_data *)ri->data; + s64 delta; + ktime_t now; + if (retval < 0) { - printk("%s returns %d\n", probed_func, retval); + now = ktime_get(); + delta = ktime_to_ns(ktime_sub(now, data->entry_stamp)); + printk("%s: return val = %d (duration = %lld ns)\n", + probed_func, retval, delta); } return 0; } static struct kretprobe my_kretprobe = { - .handler = ret_handler, - /* Probe up to 20 instances concurrently. */ - .maxactive = 20 + .handler = return_handler, + .entry_handler = entry_handler, + .data_size = sizeof(struct my_data), + .maxactive = 20, /* probe up to 20 instances concurrently */ }; static int __init kretprobe_init(void) @@ -584,7 +641,7 @@ static int __init kretprobe_init(void) printk("register_kretprobe failed, returned %d\n", ret); return -1; } - printk("Planted return probe at %p\n", my_kretprobe.kp.addr); + printk("Kretprobe active on %s\n", my_kretprobe.kp.symbol_name); return 0; } @@ -594,7 +651,7 @@ static void __exit kretprobe_exit(void) printk("kretprobe unregistered\n"); /* nmissed > 0 suggests that maxactive was set too low. */ printk("Missed probing %d instances of %s\n", - my_kretprobe.nmissed, probed_func); + my_kretprobe.nmissed, probed_func); } module_init(kretprobe_init) diff --git a/Documentation/kref.txt b/Documentation/kref.txt index f38b59d..130b6e8 100644 --- a/Documentation/kref.txt +++ b/Documentation/kref.txt @@ -141,10 +141,10 @@ The last rule (rule 3) is the nastiest one to handle. Say, for instance, you have a list of items that are each kref-ed, and you wish to get the first one. You can't just pull the first item off the list and kref_get() it. That violates rule 3 because you are not already -holding a valid pointer. You must add locks or semaphores. For -instance: +holding a valid pointer. You must add a mutex (or some other lock). +For instance: -static DECLARE_MUTEX(sem); +static DEFINE_MUTEX(mutex); static LIST_HEAD(q); struct my_data { @@ -155,12 +155,12 @@ struct my_data static struct my_data *get_entry() { struct my_data *entry = NULL; - down(&sem); + mutex_lock(&mutex); if (!list_empty(&q)) { entry = container_of(q.next, struct my_q_entry, link); kref_get(&entry->refcount); } - up(&sem); + mutex_unlock(&mutex); return entry; } @@ -174,9 +174,9 @@ static void release_entry(struct kref *ref) static void put_entry(struct my_data *entry) { - down(&sem); + mutex_lock(&mutex); kref_put(&entry->refcount, release_entry); - up(&sem); + mutex_unlock(&mutex); } The kref_put() return value is useful if you do not want to hold the @@ -191,13 +191,13 @@ static void release_entry(struct kref *ref) static void put_entry(struct my_data *entry) { - down(&sem); + mutex_lock(&mutex); if (kref_put(&entry->refcount, release_entry)) { list_del(&entry->link); - up(&sem); + mutex_unlock(&mutex); kfree(entry); } else - up(&sem); + mutex_unlock(&mutex); } This is really more useful if you have to call other routines as part diff --git a/Documentation/leds-class.txt b/Documentation/leds-class.txt index 8c35c04..56757c7 100644 --- a/Documentation/leds-class.txt +++ b/Documentation/leds-class.txt @@ -39,12 +39,33 @@ LED Device Naming Is currently of the form: -"devicename:colour" +"devicename:colour:function" There have been calls for LED properties such as colour to be exported as individual led class attributes. As a solution which doesn't incur as much overhead, I suggest these become part of the device name. The naming scheme -above leaves scope for further attributes should they be needed. +above leaves scope for further attributes should they be needed. If sections +of the name don't apply, just leave that section blank. + + +Hardware accelerated blink of LEDs +================================== + +Some LEDs can be programmed to blink without any CPU interaction. To +support this feature, a LED driver can optionally implement the +blink_set() function (see <linux/leds.h>). If implemeted, triggers can +attempt to use it before falling back to software timers. The blink_set() +function should return 0 if the blink setting is supported, or -EINVAL +otherwise, which means that LED blinking will be handled by software. + +The blink_set() function should choose a user friendly blinking +value if it is called with *delay_on==0 && *delay_off==0 parameters. In +this case the driver should give back the chosen value through delay_on +and delay_off parameters to the leds subsystem. + +Any call to the brightness_set() callback function should cancel the +previously programmed hardware blinking function so setting the brightness +to 0 can also cancel the blinking of the LED. Known Issues @@ -55,10 +76,6 @@ would cause nightmare dependency issues. I see this as a minor issue compared to the benefits the simple trigger functionality brings. The rest of the LED subsystem can be modular. -Some leds can be programmed to flash in hardware. As this isn't a generic -LED device property, this should be exported as a device specific sysfs -attribute rather than part of the class if this functionality is required. - Future Development ================== diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c index 6c8a238..0f23d67f 100644 --- a/Documentation/lguest/lguest.c +++ b/Documentation/lguest/lguest.c @@ -34,6 +34,8 @@ #include <zlib.h> #include <assert.h> #include <sched.h> +#include <limits.h> +#include <stddef.h> #include "linux/lguest_launcher.h" #include "linux/virtio_config.h" #include "linux/virtio_net.h" @@ -99,13 +101,11 @@ struct device_list /* The descriptor page for the devices. */ u8 *descpage; - /* The tail of the last descriptor. */ - unsigned int desc_used; - /* A single linked list of devices. */ struct device *dev; - /* ... And an end pointer so we can easily append new devices */ - struct device **lastdev; + /* And a pointer to the last device for easy append and also for + * configuration appending. */ + struct device *lastdev; }; /* The list of Guest devices, based on command line arguments. */ @@ -191,7 +191,14 @@ static void *_convert(struct iovec *iov, size_t size, size_t align, #define cpu_to_le64(v64) (v64) #define le16_to_cpu(v16) (v16) #define le32_to_cpu(v32) (v32) -#define le64_to_cpu(v32) (v64) +#define le64_to_cpu(v64) (v64) + +/* The device virtqueue descriptors are followed by feature bitmasks. */ +static u8 *get_feature_bits(struct device *dev) +{ + return (u8 *)(dev->desc + 1) + + dev->desc->num_vq * sizeof(struct lguest_vqconfig); +} /*L:100 The Launcher code itself takes us out into userspace, that scary place * where pointers run wild and free! Unfortunately, like most userspace @@ -914,21 +921,58 @@ static void enable_fd(int fd, struct virtqueue *vq) write(waker_fd, &vq->dev->fd, sizeof(vq->dev->fd)); } +/* Resetting a device is fairly easy. */ +static void reset_device(struct device *dev) +{ + struct virtqueue *vq; + + verbose("Resetting device %s\n", dev->name); + /* Clear the status. */ + dev->desc->status = 0; + + /* Clear any features they've acked. */ + memset(get_feature_bits(dev) + dev->desc->feature_len, 0, + dev->desc->feature_len); + + /* Zero out the virtqueues. */ + for (vq = dev->vq; vq; vq = vq->next) { + memset(vq->vring.desc, 0, + vring_size(vq->config.num, getpagesize())); + vq->last_avail_idx = 0; + } +} + /* This is the generic routine we call when the Guest uses LHCALL_NOTIFY. */ static void handle_output(int fd, unsigned long addr) { struct device *i; struct virtqueue *vq; - /* Check each virtqueue. */ + /* Check each device and virtqueue. */ for (i = devices.dev; i; i = i->next) { + /* Notifications to device descriptors reset the device. */ + if (from_guest_phys(addr) == i->desc) { + reset_device(i); + return; + } + + /* Notifications to virtqueues mean output has occurred. */ for (vq = i->vq; vq; vq = vq->next) { - if (vq->config.pfn == addr/getpagesize() - && vq->handle_output) { - verbose("Output to %s\n", vq->dev->name); - vq->handle_output(fd, vq); + if (vq->config.pfn != addr/getpagesize()) + continue; + + /* Guest should acknowledge (and set features!) before + * using the device. */ + if (i->desc->status == 0) { + warnx("%s gave early output", i->name); return; } + + if (strcmp(vq->dev->name, "console") != 0) + verbose("Output to %s\n", vq->dev->name); + if (vq->handle_output) + vq->handle_output(fd, vq); + return; } } @@ -986,54 +1030,44 @@ static void handle_input(int fd) * * All devices need a descriptor so the Guest knows it exists, and a "struct * device" so the Launcher can keep track of it. We have common helper - * routines to allocate them. - * - * This routine allocates a new "struct lguest_device_desc" from descriptor - * table just above the Guest's normal memory. It returns a pointer to that - * descriptor. */ -static struct lguest_device_desc *new_dev_desc(u16 type) -{ - struct lguest_device_desc *d; + * routines to allocate and manage them. */ - /* We only have one page for all the descriptors. */ - if (devices.desc_used + sizeof(*d) > getpagesize()) - errx(1, "Too many devices"); - - /* We don't need to set config_len or status: page is 0 already. */ - d = (void *)devices.descpage + devices.desc_used; - d->type = type; - devices.desc_used += sizeof(*d); - - return d; +/* The layout of the device page is a "struct lguest_device_desc" followed by a + * number of virtqueue descriptors, then two sets of feature bits, then an + * array of configuration bytes. This routine returns the configuration + * pointer. */ +static u8 *device_config(const struct device *dev) +{ + return (void *)(dev->desc + 1) + + dev->desc->num_vq * sizeof(struct lguest_vqconfig) + + dev->desc->feature_len * 2; } -/* Each device descriptor is followed by some configuration information. - * Each configuration field looks like: u8 type, u8 len, [... len bytes...]. - * - * This routine adds a new field to an existing device's descriptor. It only - * works for the last device, but that's OK because that's how we use it. */ -static void add_desc_field(struct device *dev, u8 type, u8 len, const void *c) +/* This routine allocates a new "struct lguest_device_desc" from descriptor + * table page just above the Guest's normal memory. It returns a pointer to + * that descriptor. */ +static struct lguest_device_desc *new_dev_desc(u16 type) { - /* This is the last descriptor, right? */ - assert(devices.descpage + devices.desc_used - == (u8 *)(dev->desc + 1) + dev->desc->config_len); + struct lguest_device_desc d = { .type = type }; + void *p; - /* We only have one page of device descriptions. */ - if (devices.desc_used + 2 + len > getpagesize()) - errx(1, "Too many devices"); + /* Figure out where the next device config is, based on the last one. */ + if (devices.lastdev) + p = device_config(devices.lastdev) + + devices.lastdev->desc->config_len; + else + p = devices.descpage; - /* Copy in the new config header: type then length. */ - devices.descpage[devices.desc_used++] = type; - devices.descpage[devices.desc_used++] = len; - memcpy(devices.descpage + devices.desc_used, c, len); - devices.desc_used += len; + /* We only have one page for all the descriptors. */ + if (p + sizeof(d) > (void *)devices.descpage + getpagesize()) + errx(1, "Too many devices"); - /* Update the device descriptor length: two byte head then data. */ - dev->desc->config_len += 2 + len; + /* p might not be aligned, so we memcpy in. */ + return memcpy(p, &d, sizeof(d)); } -/* This routine adds a virtqueue to a device. We specify how many descriptors - * the virtqueue is to have. */ +/* Each device descriptor is followed by the description of its virtqueues. We + * specify how many descriptors the virtqueue is to have. */ static void add_virtqueue(struct device *dev, unsigned int num_descs, void (*handle_output)(int fd, struct virtqueue *me)) { @@ -1059,9 +1093,15 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, /* Initialize the vring. */ vring_init(&vq->vring, num_descs, p, getpagesize()); - /* Add the configuration information to this device's descriptor. */ - add_desc_field(dev, VIRTIO_CONFIG_F_VIRTQUEUE, - sizeof(vq->config), &vq->config); + /* Append virtqueue to this device's descriptor. We use + * device_config() to get the end of the device's current virtqueues; + * we check that we haven't added any config or feature information + * yet, otherwise we'd be overwriting them. */ + assert(dev->desc->config_len == 0 && dev->desc->feature_len == 0); + memcpy(device_config(dev), &vq->config, sizeof(vq->config)); + dev->desc->num_vq++; + + verbose("Virtqueue page %#lx\n", to_guest_phys(p)); /* Add to tail of list, so dev->vq is first vq, dev->vq->next is * second. */ @@ -1072,11 +1112,41 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs, * virtqueue. */ vq->handle_output = handle_output; - /* Set the "Don't Notify Me" flag if we don't have a handler */ + /* As an optimization, set the advisory "Don't Notify Me" flag if we + * don't have a handler */ if (!handle_output) vq->vring.used->flags = VRING_USED_F_NO_NOTIFY; } +/* The first half of the feature bitmask is for us to advertise features. The + * second half if for the Guest to accept features. */ +static void add_feature(struct device *dev, unsigned bit) +{ + u8 *features = get_feature_bits(dev); + + /* We can't extend the feature bits once we've added config bytes */ + if (dev->desc->feature_len <= bit / CHAR_BIT) { + assert(dev->desc->config_len == 0); + dev->desc->feature_len = (bit / CHAR_BIT) + 1; + } + + features[bit / CHAR_BIT] |= (1 << (bit % CHAR_BIT)); +} + +/* This routine sets the configuration fields for an existing device's + * descriptor. It only works for the last device, but that's OK because that's + * how we use it. */ +static void set_config(struct device *dev, unsigned len, const void *conf) +{ + /* Check we haven't overflowed our single page. */ + if (device_config(dev) + len > devices.descpage + getpagesize()) + errx(1, "Too many devices"); + + /* Copy in the config information, and store the length. */ + memcpy(device_config(dev), conf, len); + dev->desc->config_len = len; +} + /* This routine does all the creation and setup of a new device, including * calling new_dev_desc() to allocate the descriptor and device memory. */ static struct device *new_device(const char *name, u16 type, int fd, @@ -1084,14 +1154,6 @@ static struct device *new_device(const char *name, u16 type, int fd, { struct device *dev = malloc(sizeof(*dev)); - /* Append to device list. Prepending to a single-linked list is - * easier, but the user expects the devices to be arranged on the bus - * in command-line order. The first network device on the command line - * is eth0, the first block device /dev/vda, etc. */ - *devices.lastdev = dev; - dev->next = NULL; - devices.lastdev = &dev->next; - /* Now we populate the fields one at a time. */ dev->fd = fd; /* If we have an input handler for this file descriptor, then we add it @@ -1102,6 +1164,17 @@ static struct device *new_device(const char *name, u16 type, int fd, dev->handle_input = handle_input; dev->name = name; dev->vq = NULL; + + /* Append to device list. Prepending to a single-linked list is + * easier, but the user expects the devices to be arranged on the bus + * in command-line order. The first network device on the command line + * is eth0, the first block device /dev/vda, etc. */ + if (devices.lastdev) + devices.lastdev->next = dev; + else + devices.dev = dev; + devices.lastdev = dev; + return dev; } @@ -1226,7 +1299,7 @@ static void setup_tun_net(const char *arg) int netfd, ipfd; u32 ip; const char *br_name = NULL; - u8 hwaddr[6]; + struct virtio_net_config conf; /* We open the /dev/net/tun device and tell it we want a tap device. A * tap device is like a tun device, only somehow different. To tell @@ -1265,12 +1338,13 @@ static void setup_tun_net(const char *arg) ip = str2ip(arg); /* Set up the tun device, and get the mac address for the interface. */ - configure_device(ipfd, ifr.ifr_name, ip, hwaddr); + configure_device(ipfd, ifr.ifr_name, ip, conf.mac); /* Tell Guest what MAC address to use. */ - add_desc_field(dev, VIRTIO_CONFIG_NET_MAC_F, sizeof(hwaddr), hwaddr); + add_feature(dev, VIRTIO_NET_F_MAC); + set_config(dev, sizeof(conf), &conf); - /* We don't seed the socket any more; setup is done. */ + /* We don't need the socket any more; setup is done. */ close(ipfd); verbose("device %u: tun net %u.%u.%u.%u\n", @@ -1458,8 +1532,7 @@ static void setup_block_file(const char *filename) struct device *dev; struct vblk_info *vblk; void *stack; - u64 cap; - unsigned int val; + struct virtio_blk_config conf; /* This is the pipe the I/O thread will use to tell us I/O is done. */ pipe(p); @@ -1477,14 +1550,18 @@ static void setup_block_file(const char *filename) vblk->fd = open_or_die(filename, O_RDWR|O_LARGEFILE); vblk->len = lseek64(vblk->fd, 0, SEEK_END); + /* We support barriers. */ + add_feature(dev, VIRTIO_BLK_F_BARRIER); + /* Tell Guest how many sectors this device has. */ - cap = cpu_to_le64(vblk->len / 512); - add_desc_field(dev, VIRTIO_CONFIG_BLK_F_CAPACITY, sizeof(cap), &cap); + conf.capacity = cpu_to_le64(vblk->len / 512); /* Tell Guest not to put in too many descriptors at once: two are used * for the in and out elements. */ - val = cpu_to_le32(VIRTQUEUE_NUM - 2); - add_desc_field(dev, VIRTIO_CONFIG_BLK_F_SEG_MAX, sizeof(val), &val); + add_feature(dev, VIRTIO_BLK_F_SEG_MAX); + conf.seg_max = cpu_to_le32(VIRTQUEUE_NUM - 2); + + set_config(dev, sizeof(conf), &conf); /* The I/O thread writes to this end of the pipe when done. */ vblk->done_fd = p[1]; @@ -1505,7 +1582,7 @@ static void setup_block_file(const char *filename) close(vblk->workpipe[0]); verbose("device %u: virtblock %llu sectors\n", - devices.device_num, cap); + devices.device_num, le64_to_cpu(conf.capacity)); } /* That's the end of device setup. :*/ @@ -1610,12 +1687,12 @@ int main(int argc, char *argv[]) /* First we initialize the device list. Since console and network * device receive input from a file descriptor, we keep an fdset * (infds) and the maximum fd number (max_infd) with the head of the - * list. We also keep a pointer to the last device, for easy appending - * to the list. Finally, we keep the next interrupt number to hand out - * (1: remember that 0 is used by the timer). */ + * list. We also keep a pointer to the last device. Finally, we keep + * the next interrupt number to hand out (1: remember that 0 is used by + * the timer). */ FD_ZERO(&devices.infds); devices.max_infd = -1; - devices.lastdev = &devices.dev; + devices.lastdev = NULL; devices.next_irq = 1; cpu_id = 0; diff --git a/Documentation/md.txt b/Documentation/md.txt index 5818628..396cdd9 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -416,6 +416,16 @@ also have sectors in total that could need to be processed. The two numbers are separated by a '/' thus effectively showing one value, a fraction of the process that is complete. + A 'select' on this attribute will return when resync completes, + when it reaches the current sync_max (below) and possibly at + other times. + + sync_max + This is a number of sectors at which point a resync/recovery + process will pause. When a resync is active, the value can + only ever be increased, never decreased. The value of 'max' + effectively disables the limit. + sync_speed This shows the current actual speed, in K/sec, of the current diff --git a/Documentation/mn10300/ABI.txt b/Documentation/mn10300/ABI.txt new file mode 100644 index 0000000..1fef1f0 --- /dev/null +++ b/Documentation/mn10300/ABI.txt @@ -0,0 +1,149 @@ + ========================= + MN10300 FUNCTION CALL ABI + ========================= + +======= +GENERAL +======= + +The MN10300/AM33 kernel runs in little-endian mode; big-endian mode is not +supported. + +The stack grows downwards, and should always be 32-bit aligned. There are +separate stack pointer registers for userspace and the kernel. + + +================ +ARGUMENT PASSING +================ + +The first two arguments (assuming up to 32-bits per argument) to a function are +passed in the D0 and D1 registers respectively; all other arguments are passed +on the stack. + +If 64-bit arguments are being passed, then they are never split between +registers and the stack. If the first argument is a 64-bit value, it will be +passed in D0:D1. If the first argument is not a 64-bit value, but the second +is, the second will be passed entirely on the stack and D1 will be unused. + +Arguments smaller than 32-bits are not coelesced within a register or a stack +word. For example, two byte-sized arguments will always be passed in separate +registers or word-sized stack slots. + + +================= +CALLING FUNCTIONS +================= + +The caller must allocate twelve bytes on the stack for the callee's use before +it inserts a CALL instruction. The CALL instruction will write into the TOS +word, but won't actually modify the stack pointer; similarly, the RET +instruction reads from the TOS word of the stack, but doesn't move the stack +pointer beyond it. + + + Stack: + | | + | | + |---------------| SP+20 + | 4th Arg | + |---------------| SP+16 + | 3rd Arg | + |---------------| SP+12 + | D1 Save Slot | + |---------------| SP+8 + | D0 Save Slot | + |---------------| SP+4 + | Return Addr | + |---------------| SP + | | + | | + + +The caller must leave space on the stack (hence an allocation of twelve bytes) +in which the callee may store the first two arguments. + + +============ +RETURN VALUE +============ + +The return value is passed in D0 for an integer (or D0:D1 for a 64-bit value), +or A0 for a pointer. + +If the return value is a value larger than 64-bits, or is a structure or an +array, then a hidden first argument will be passed to the callee by the caller: +this will point to a piece of memory large enough to hold the result of the +function. In this case, the callee will return the value in that piece of +memory, and no value will be returned in D0 or A0. + + +=================== +REGISTER CLOBBERING +=================== + +The values in certain registers may be clobbered by the callee, and other +values must be saved: + + Clobber: D0-D1, A0-A1, E0-E3 + Save: D2-D3, A2-A3, E4-E7, SP + +All other non-supervisor-only registers are clobberable (such as MDR, MCRL, +MCRH). + + +================= +SPECIAL REGISTERS +================= + +Certain ordinary registers may carry special usage for the compiler: + + A3: Frame pointer + E2: TLS pointer + + +========== +KERNEL ABI +========== + +The kernel may use a slightly different ABI internally. + + (*) E2 + + If CONFIG_MN10300_CURRENT_IN_E2 is defined, then the current task pointer + will be kept in the E2 register, and that register will be marked + unavailable for the compiler to use as a scratch register. + + Normally the kernel uses something like: + + MOV SP,An + AND 0xFFFFE000,An + MOV (An),Rm // Rm holds current + MOV (yyy,Rm) // Access current->yyy + + To find the address of current; but since this option permits current to + be carried globally in an register, it can use: + + MOV (yyy,E2) // Access current->yyy + + instead. + + +=============== +SYSTEM CALL ABI +=============== + +System calls are called with the following convention: + + REGISTER ENTRY EXIT + =============== ======================= ======================= + D0 Syscall number Return value + A0 1st syscall argument Saved + D1 2nd syscall argument Saved + A3 3rd syscall argument Saved + A2 4th syscall argument Saved + D3 5th syscall argument Saved + D2 6th syscall argument Saved + +All other registers are saved. The layout is a consequence of the way the MOVM +instruction stores registers onto the stack. diff --git a/Documentation/mn10300/compartmentalisation.txt b/Documentation/mn10300/compartmentalisation.txt new file mode 100644 index 0000000..8958b51 --- /dev/null +++ b/Documentation/mn10300/compartmentalisation.txt @@ -0,0 +1,60 @@ + ========================================= + PART-SPECIFIC SOURCE COMPARTMENTALISATION + ========================================= + +The sources for various parts are compartmentalised at two different levels: + + (1) Processor level + + The "processor level" is a CPU core plus the other on-silicon + peripherals. + + Processor-specific header files are divided among directories in a similar + way to the CPU level: + + (*) include/asm-mn10300/proc-mn103e010/ + + Support for the AM33v2 CPU core. + + The appropriate processor is selected by a CONFIG_MN10300_PROC_YYYY option + from the "Processor support" choice menu in the arch/mn10300/Kconfig file. + + + (2) Unit level + + The "unit level" is a processor plus all the external peripherals + controlled by that processor. + + Unit-specific header files are divided among directories in a similar way + to the CPU level; not only that, but specific sources may also be + segregated into separate directories under the arch directory: + + (*) include/asm-mn10300/unit-asb2303/ + (*) arch/mn10300/unit-asb2303/ + + Support for the ASB2303 board with an ASB2308 daughter board. + + (*) include/asm-mn10300/unit-asb2305/ + (*) arch/mn10300/unit-asb2305/ + + Support for the ASB2305 board. + + The appropriate processor is selected by a CONFIG_MN10300_UNIT_ZZZZ option + from the "Unit type" choice menu in the arch/mn10300/Kconfig file. + + +============ +COMPILE TIME +============ + +When the kernel is compiled, symbolic links will be made in the asm header file +directory for this arch: + + include/asm-mn10300/proc => include/asm-mn10300/proc-YYYY/ + include/asm-mn10300/unit => include/asm-mn10300/unit-ZZZZ/ + +So that the header files contained in those directories can be accessed without +lots of #ifdef-age. + +The appropriate arch/mn10300/unit-ZZZZ directory will also be entered by the +compilation process; all other unit-specific directories will be ignored. diff --git a/Documentation/networking/decnet.txt b/Documentation/networking/decnet.txt index badb748..d896895 100644 --- a/Documentation/networking/decnet.txt +++ b/Documentation/networking/decnet.txt @@ -60,7 +60,7 @@ operation of the local communications in any other way though. The kernel command line takes options looking like the following: - decnet=1,2 + decnet.addr=1,2 the two numbers are the node address 1,2 = 1.2 For 2.2.xx kernels and early 2.3.xx kernels, you must use a comma when specifying the diff --git a/Documentation/networking/xfrm_proc.txt b/Documentation/networking/xfrm_proc.txt index 53c1a58..d0d8baf 100644 --- a/Documentation/networking/xfrm_proc.txt +++ b/Documentation/networking/xfrm_proc.txt @@ -26,8 +26,9 @@ XfrmInStateProtoError: e.g. SA key is wrong XfrmInStateModeError: Transformation mode specific error -XfrmInSeqOutOfWindow: - Sequence out of window +XfrmInStateSeqError: + Sequence error + i.e. Sequence number is out of window XfrmInStateExpired: State is expired XfrmInStateMismatch: @@ -60,6 +61,9 @@ XfrmOutStateProtoError: Transformation protocol specific error XfrmOutStateModeError: Transformation mode specific error +XfrmOutStateSeqError: + Sequence error + i.e. Sequence number overflow XfrmOutStateExpired: State is expired XfrmOutPolBlock: diff --git a/Documentation/pci.txt b/Documentation/pci.txt index 7754f5a..72b20c6 100644 --- a/Documentation/pci.txt +++ b/Documentation/pci.txt @@ -274,8 +274,6 @@ the PCI device by calling pci_enable_device(). This will: o allocate an IRQ (if BIOS did not). NOTE: pci_enable_device() can fail! Check the return value. -NOTE2: Also see pci_enable_device_bars() below. Drivers can - attempt to enable only a subset of BARs they need. [ OS BUG: we don't check resource allocations before enabling those resources. The sequence would make more sense if we called @@ -605,40 +603,7 @@ device lists. This is still possible but discouraged. -10. pci_enable_device_bars() and Legacy I/O Port space -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Large servers may not be able to provide I/O port resources to all PCI -devices. I/O Port space is only 64KB on Intel Architecture[1] and is -likely also fragmented since the I/O base register of PCI-to-PCI -bridge will usually be aligned to a 4KB boundary[2]. On such systems, -pci_enable_device() and pci_request_region() will fail when -attempting to enable I/O Port regions that don't have I/O Port -resources assigned. - -Fortunately, many PCI devices which request I/O Port resources also -provide access to the same registers via MMIO BARs. These devices can -be handled without using I/O port space and the drivers typically -offer a CONFIG_ option to only use MMIO regions -(e.g. CONFIG_TULIP_MMIO). PCI devices typically provide I/O port -interface for legacy OSes and will work when I/O port resources are not -assigned. The "PCI Local Bus Specification Revision 3.0" discusses -this on p.44, "IMPLEMENTATION NOTE". - -If your PCI device driver doesn't need I/O port resources assigned to -I/O Port BARs, you should use pci_enable_device_bars() instead of -pci_enable_device() in order not to enable I/O port regions for the -corresponding devices. In addition, you should use -pci_request_selected_regions() and pci_release_selected_regions() -instead of pci_request_regions()/pci_release_regions() in order not to -request/release I/O port regions for the corresponding devices. - -[1] Some systems support 64KB I/O port space per PCI segment. -[2] Some PCI-to-PCI bridges support optional 1KB aligned I/O base. - - - -11. MMIO Space and "Write Posting" +10. MMIO Space and "Write Posting" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Converting a driver from using I/O Port space to using MMIO space diff --git a/Documentation/pcmcia/driver-changes.txt b/Documentation/pcmcia/driver-changes.txt index 4739c5c..96f155e 100644 --- a/Documentation/pcmcia/driver-changes.txt +++ b/Documentation/pcmcia/driver-changes.txt @@ -33,8 +33,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors: and can be used (e.g. for SET_NETDEV_DEV) by using handle_to_dev(client_handle_t * handle). -* Convert internal I/O port addresses to unsigned long (as of 2.6.11) - ioaddr_t should be replaced by kio_addr_t in PCMCIA card drivers. +* Convert internal I/O port addresses to unsigned int (as of 2.6.11) + ioaddr_t should be replaced by unsigned int in PCMCIA card drivers. * irq_mask and irq_list parameters (as of 2.6.11) The irq_mask and irq_list parameters should no longer be used in diff --git a/Documentation/pm_qos_interface.txt b/Documentation/pm_qos_interface.txt new file mode 100644 index 0000000..49adb1a --- /dev/null +++ b/Documentation/pm_qos_interface.txt @@ -0,0 +1,59 @@ +PM quality of Service interface. + +This interface provides a kernel and user mode interface for registering +performance expectations by drivers, subsystems and user space applications on +one of the parameters. + +Currently we have {cpu_dma_latency, network_latency, network_throughput} as the +initial set of pm_qos parameters. + +The infrastructure exposes multiple misc device nodes one per implemented +parameter. The set of parameters implement is defined by pm_qos_power_init() +and pm_qos_params.h. This is done because having the available parameters +being runtime configurable or changeable from a driver was seen as too easy to +abuse. + +For each parameter a list of performance requirements is maintained along with +an aggregated target value. The aggregated target value is updated with +changes to the requirement list or elements of the list. Typically the +aggregated target value is simply the max or min of the requirement values held +in the parameter list elements. + +From kernel mode the use of this interface is simple: +pm_qos_add_requirement(param_id, name, target_value): +Will insert a named element in the list for that identified PM_QOS parameter +with the target value. Upon change to this list the new target is recomputed +and any registered notifiers are called only if the target value is now +different. + +pm_qos_update_requirement(param_id, name, new_target_value): +Will search the list identified by the param_id for the named list element and +then update its target value, calling the notification tree if the aggregated +target is changed. with that name is already registered. + +pm_qos_remove_requirement(param_id, name): +Will search the identified list for the named element and remove it, after +removal it will update the aggregate target and call the notification tree if +the target was changed as a result of removing the named requirement. + + +From user mode: +Only processes can register a pm_qos requirement. To provide for automatic +cleanup for process the interface requires the process to register its +parameter requirements in the following way: + +To register the default pm_qos target for the specific parameter, the process +must open one of /dev/[cpu_dma_latency, network_latency, network_throughput] + +As long as the device node is held open that process has a registered +requirement on the parameter. The name of the requirement is "process_<PID>" +derived from the current->pid from within the open system call. + +To change the requested target value the process needs to write a s32 value to +the open device node. This translates to a pm_qos_update_requirement call. + +To remove the user mode request for a target value simply close the device +node. + + + diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.txt index 57aef2f..1555001 100644 --- a/Documentation/power/basic-pm-debugging.txt +++ b/Documentation/power/basic-pm-debugging.txt @@ -1,45 +1,111 @@ -Debugging suspend and resume +Debugging hibernation and suspend (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL -1. Testing suspend to disk (STD) +1. Testing hibernation (aka suspend to disk or STD) -To verify that the STD works, you can try to suspend in the "reboot" mode: +To check if hibernation works, you can try to hibernate in the "reboot" mode: # echo reboot > /sys/power/disk # echo disk > /sys/power/state -and the system should suspend, reboot, resume and get back to the command prompt -where you have started the transition. If that happens, the STD is most likely -to work correctly, but you need to repeat the test at least a couple of times in -a row for confidence. This is necessary, because some problems only show up on -a second attempt at suspending and resuming the system. You should also test -the "platform" and "shutdown" modes of suspend: +and the system should create a hibernation image, reboot, resume and get back to +the command prompt where you have started the transition. If that happens, +hibernation is most likely to work correctly. Still, you need to repeat the +test at least a couple of times in a row for confidence. [This is necessary, +because some problems only show up on a second attempt at suspending and +resuming the system.] Moreover, hibernating in the "reboot" and "shutdown" +modes causes the PM core to skip some platform-related callbacks which on ACPI +systems might be necessary to make hibernation work. Thus, if you machine fails +to hibernate or resume in the "reboot" mode, you should try the "platform" mode: # echo platform > /sys/power/disk # echo disk > /sys/power/state -or +which is the default and recommended mode of hibernation. + +Unfortunately, the "platform" mode of hibernation does not work on some systems +with broken BIOSes. In such cases the "shutdown" mode of hibernation might +work: # echo shutdown > /sys/power/disk # echo disk > /sys/power/state -in which cases you will have to press the power button to make the system -resume. If that does not work, you will need to identify what goes wrong. +(it is similar to the "reboot" mode, but it requires you to press the power +button to make the system resume). + +If neither "platform" nor "shutdown" hibernation mode works, you will need to +identify what goes wrong. + +a) Test modes of hibernation + +To find out why hibernation fails on your system, you can use a special testing +facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then, +there is the file /sys/power/pm_test that can be used to make the hibernation +core run in a test mode. There are 5 test modes available: + +freezer +- test the freezing of processes + +devices +- test the freezing of processes and suspending of devices -a) Test mode of STD +platform +- test the freezing of processes, suspending of devices and platform + global control methods(*) -To verify if there are any drivers that cause problems you can run the STD -in the test mode: +processors +- test the freezing of processes, suspending of devices, platform + global control methods(*) and the disabling of nonboot CPUs -# echo test > /sys/power/disk +core +- test the freezing of processes, suspending of devices, platform global + control methods(*), the disabling of nonboot CPUs and suspending of + platform/system devices + +(*) the platform global control methods are only available on ACPI systems + and are only tested if the hibernation mode is set to "platform" + +To use one of them it is necessary to write the corresponding string to +/sys/power/pm_test (eg. "devices" to test the freezing of processes and +suspending devices) and issue the standard hibernation commands. For example, +to use the "devices" test mode along with the "platform" mode of hibernation, +you should do the following: + +# echo devices > /sys/power/pm_test +# echo platform > /sys/power/disk # echo disk > /sys/power/state -in which case the system should freeze tasks, suspend devices, disable nonboot -CPUs (if any), wait for 5 seconds, enable nonboot CPUs, resume devices, thaw -tasks and return to your command prompt. If that fails, most likely there is -a driver that fails to either suspend or resume (in the latter case the system -may hang or be unstable after the test, so please take that into consideration). -To find this driver, you can carry out a binary search according to the rules: +Then, the kernel will try to freeze processes, suspend devices, wait 5 seconds, +resume devices and thaw processes. If "platform" is written to +/sys/power/pm_test , then after suspending devices the kernel will additionally +invoke the global control methods (eg. ACPI global control methods) used to +prepare the platform firmware for hibernation. Next, it will wait 5 seconds and +invoke the platform (eg. ACPI) global methods used to cancel hibernation etc. + +Writing "none" to /sys/power/pm_test causes the kernel to switch to the normal +hibernation/suspend operations. Also, when open for reading, /sys/power/pm_test +contains a space-separated list of all available tests (including "none" that +represents the normal functionality) in which the current test level is +indicated by square brackets. + +Generally, as you can see, each test level is more "invasive" than the previous +one and the "core" level tests the hardware and drivers as deeply as possible +without creating a hibernation image. Obviously, if the "devices" test fails, +the "platform" test will fail as well and so on. Thus, as a rule of thumb, you +should try the test modes starting from "freezer", through "devices", "platform" +and "processors" up to "core" (repeat the test on each level a couple of times +to make sure that any random factors are avoided). + +If the "freezer" test fails, there is a task that cannot be frozen (in that case +it usually is possible to identify the offending task by analysing the output of +dmesg obtained after the failing test). Failure at this level usually means +that there is a problem with the tasks freezer subsystem that should be +reported. + +If the "devices" test fails, most likely there is a driver that cannot suspend +or resume its device (in the latter case the system may hang or become unstable +after the test, so please take that into consideration). To find this driver, +you can carry out a binary search according to the rules: - if the test fails, unload a half of the drivers currently loaded and repeat (that would probably involve rebooting the system, so always note what drivers have been loaded before the test), @@ -47,23 +113,46 @@ have been loaded before the test), recently and repeat. Once you have found the failing driver (there can be more than just one of -them), you have to unload it every time before the STD transition. In that case -please make sure to report the problem with the driver. - -It is also possible that a cycle can still fail after you have unloaded -all modules. In that case, you would want to look in your kernel configuration -for the drivers that can be compiled as modules (testing again with them as -modules), and possibly also try boot time options such as "noapic" or "noacpi". +them), you have to unload it every time before hibernation. In that case please +make sure to report the problem with the driver. + +It is also possible that the "devices" test will still fail after you have +unloaded all modules. In that case, you may want to look in your kernel +configuration for the drivers that can be compiled as modules (and test again +with these drivers compiled as modules). You may also try to use some special +kernel command line options such as "noapic", "noacpi" or even "acpi=off". + +If the "platform" test fails, there is a problem with the handling of the +platform (eg. ACPI) firmware on your system. In that case the "platform" mode +of hibernation is not likely to work. You can try the "shutdown" mode, but that +is rather a poor man's workaround. + +If the "processors" test fails, the disabling/enabling of nonboot CPUs does not +work (of course, this only may be an issue on SMP systems) and the problem +should be reported. In that case you can also try to switch the nonboot CPUs +off and on using the /sys/devices/system/cpu/cpu*/online sysfs attributes and +see if that works. + +If the "core" test fails, which means that suspending of the system/platform +devices has failed (these devices are suspended on one CPU with interrupts off), +the problem is most probably hardware-related and serious, so it should be +reported. + +A failure of any of the "platform", "processors" or "core" tests may cause your +system to hang or become unstable, so please beware. Such a failure usually +indicates a serious problem that very well may be related to the hardware, but +please report it anyway. b) Testing minimal configuration -If the test mode of STD works, you can boot the system with "init=/bin/bash" -and attempt to suspend in the "reboot", "shutdown" and "platform" modes. If -that does not work, there probably is a problem with a driver statically -compiled into the kernel and you can try to compile more drivers as modules, -so that they can be tested individually. Otherwise, there is a problem with a -modular driver and you can find it by loading a half of the modules you normally -use and binary searching in accordance with the algorithm: +If all of the hibernation test modes work, you can boot the system with the +"init=/bin/bash" command line parameter and attempt to hibernate in the +"reboot", "shutdown" and "platform" modes. If that does not work, there +probably is a problem with a driver statically compiled into the kernel and you +can try to compile more drivers as modules, so that they can be tested +individually. Otherwise, there is a problem with a modular driver and you can +find it by loading a half of the modules you normally use and binary searching +in accordance with the algorithm: - if there are n modules loaded and the attempt to suspend and resume fails, unload n/2 of the modules and try again (that would probably involve rebooting the system), @@ -71,19 +160,19 @@ the system), load n/2 modules more and try again. Again, if you find the offending module(s), it(they) must be unloaded every time -before the STD transition, and please report the problem with it(them). +before hibernation, and please report the problem with it(them). c) Advanced debugging -In case the STD does not work on your system even in the minimal configuration -and compiling more drivers as modules is not practical or some modules cannot -be unloaded, you can use one of the more advanced debugging techniques to find -the problem. First, if there is a serial port in your box, you can boot the -kernel with the 'no_console_suspend' parameter and try to log kernel -messages using the serial console. This may provide you with some information -about the reasons of the suspend (resume) failure. Alternatively, it may be -possible to use a FireWire port for debugging with firescope -(ftp://ftp.firstfloor.org/pub/ak/firescope/). On i386 it is also possible to +In case that hibernation does not work on your system even in the minimal +configuration and compiling more drivers as modules is not practical or some +modules cannot be unloaded, you can use one of the more advanced debugging +techniques to find the problem. First, if there is a serial port in your box, +you can boot the kernel with the 'no_console_suspend' parameter and try to log +kernel messages using the serial console. This may provide you with some +information about the reasons of the suspend (resume) failure. Alternatively, +it may be possible to use a FireWire port for debugging with firescope +(ftp://ftp.firstfloor.org/pub/ak/firescope/). On x86 it is also possible to use the PM_TRACE mechanism documented in Documentation/s2ram.txt . 2. Testing suspend to RAM (STR) @@ -91,16 +180,25 @@ use the PM_TRACE mechanism documented in Documentation/s2ram.txt . To verify that the STR works, it is generally more convenient to use the s2ram tool available from http://suspend.sf.net and documented at http://en.opensuse.org/s2ram . However, before doing that it is recommended to -carry out the procedure described in section 1. - -Assume you have resolved the problems with the STD and you have found some -failing drivers. These drivers are also likely to fail during the STR or -during the resume, so it is better to unload them every time before the STR -transition. Now, you can follow the instructions at -http://en.opensuse.org/s2ram to test the system, but if it does not work -"out of the box", you may need to boot it with "init=/bin/bash" and test -s2ram in the minimal configuration. In that case, you may be able to search -for failing drivers by following the procedure analogous to the one described in -1b). If you find some failing drivers, you will have to unload them every time -before the STR transition (ie. before you run s2ram), and please report the -problems with them. +carry out STR testing using the facility described in section 1. + +Namely, after writing "freezer", "devices", "platform", "processors", or "core" +into /sys/power/pm_test (available if the kernel is compiled with +CONFIG_PM_DEBUG set) the suspend code will work in the test mode corresponding +to given string. The STR test modes are defined in the same way as for +hibernation, so please refer to Section 1 for more information about them. In +particular, the "core" test allows you to test everything except for the actual +invocation of the platform firmware in order to put the system into the sleep +state. + +Among other things, the testing with the help of /sys/power/pm_test may allow +you to identify drivers that fail to suspend or resume their devices. They +should be unloaded every time before an STR transition. + +Next, you can follow the instructions at http://en.opensuse.org/s2ram to test +the system, but if it does not work "out of the box", you may need to boot it +with "init=/bin/bash" and test s2ram in the minimal configuration. In that +case, you may be able to search for failing drivers by following the procedure +analogous to the one described in section 1. If you find some failing drivers, +you will have to unload them every time before an STR transition (ie. before +you run s2ram), and please report the problems with them. diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt index d0e79d5..c53d263 100644 --- a/Documentation/power/devices.txt +++ b/Documentation/power/devices.txt @@ -502,52 +502,3 @@ If the CPU can have a "cpufreq" driver, there also may be opportunities to shift to lower voltage settings and reduce the power cost of executing a given number of instructions. (Without voltage adjustment, it's rare for cpufreq to save much power; the cost-per-instruction must go down.) - - -/sys/devices/.../power/state files -================================== -For now you can also test some of this functionality using sysfs. - - DEPRECATED: USE "power/state" ONLY FOR DRIVER TESTING, AND - AVOID USING dev->power.power_state IN DRIVERS. - - THESE WILL BE REMOVED. IF THE "power/state" FILE GETS REPLACED, - IT WILL BECOME SOMETHING COUPLED TO THE BUS OR DRIVER. - -In each device's directory, there is a 'power' directory, which contains -at least a 'state' file. The value of this field is effectively boolean, -PM_EVENT_ON or PM_EVENT_SUSPEND. - - * Reading from this file displays a value corresponding to - the power.power_state.event field. All nonzero values are - displayed as "2", corresponding to a low power state; zero - is displayed as "0", corresponding to normal operation. - - * Writing to this file initiates a transition using the - specified event code number; only '0', '2', and '3' are - accepted (without a newline); '2' and '3' are both - mapped to PM_EVENT_SUSPEND. - -On writes, the PM core relies on that recorded event code and the device/bus -capabilities to determine whether it uses a partial suspend() or resume() -sequence to change things so that the recorded event corresponds to the -numeric parameter. - - - If the bus requires the irqs-disabled suspend_late()/resume_early() - phases, writes fail because those operations are not supported here. - - - If the recorded value is the expected value, nothing is done. - - - If the recorded value is nonzero, the device is partially resumed, - using the bus.resume() and/or class.resume() methods. - - - If the target value is nonzero, the device is partially suspended, - using the class.suspend() and/or bus.suspend() methods and the - PM_EVENT_SUSPEND message. - -Drivers have no way to tell whether their suspend() and resume() calls -have come through the sysfs power/state file or as part of entering a -system sleep state, except that when accessed through sysfs the normal -parent/child sequencing rules are ignored. Drivers (such as bus, bridge, -or hub drivers) which expose child devices may need to enforce those rules -on their own. diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.txt index e4bdcae..7f7a737 100644 --- a/Documentation/power/drivers-testing.txt +++ b/Documentation/power/drivers-testing.txt @@ -6,9 +6,9 @@ Testing suspend and resume support in device drivers Unfortunately, to effectively test the support for the system-wide suspend and resume transitions in a driver, it is necessary to suspend and resume a fully functional system with this driver loaded. Moreover, that should be done -several times, preferably several times in a row, and separately for the suspend -to disk (STD) and the suspend to RAM (STR) transitions, because each of these -cases involves different ordering of operations and different interactions with +several times, preferably several times in a row, and separately for hibernation +(aka suspend to disk or STD) and suspend to RAM (STR), because each of these +cases involves slightly different operations and different interactions with the machine's BIOS. Of course, for this purpose the test system has to be known to suspend and @@ -22,20 +22,24 @@ for more information about the debugging of suspend/resume functionality. Once you have resolved the suspend/resume-related problems with your test system without the new driver, you are ready to test it: -a) Build the driver as a module, load it and try the STD in the test mode (see: -Documents/power/basic-pm-debugging.txt, 1a)). +a) Build the driver as a module, load it and try the test modes of hibernation + (see: Documents/power/basic-pm-debugging.txt, 1). -b) Load the driver and attempt to suspend to disk in the "reboot", "shutdown" -and "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1). +b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and + "platform" modes (see: Documents/power/basic-pm-debugging.txt, 1). -c) Compile the driver directly into the kernel and try the STD in the test mode. +c) Compile the driver directly into the kernel and try the test modes of + hibernation. -d) Attempt to suspend to disk with the driver compiled directly into the kernel -in the "reboot", "shutdown" and "platform" modes. +d) Attempt to hibernate with the driver compiled directly into the kernel + in the "reboot", "shutdown" and "platform" modes. -e) Attempt to suspend to RAM using the s2ram tool with the driver loaded (see: -Documents/power/basic-pm-debugging.txt, 2). As far as the STR tests are -concerned, it should not matter whether or not the driver is built as a module. +e) Try the test modes of suspend (see: Documents/power/basic-pm-debugging.txt, + 2). [As far as the STR tests are concerned, it should not matter whether or + not the driver is built as a module.] + +f) Attempt to suspend to RAM using the s2ram tool with the driver loaded + (see: Documents/power/basic-pm-debugging.txt, 2). Each of the above tests should be repeated several times and the STD tests should be mixed with the STR tests. If any of them fails, the driver cannot be diff --git a/Documentation/power/notifiers.txt b/Documentation/power/notifiers.txt index 9293e4b..ae1b7ec 100644 --- a/Documentation/power/notifiers.txt +++ b/Documentation/power/notifiers.txt @@ -28,6 +28,14 @@ PM_POST_HIBERNATION The system memory state has been restored from a hibernation. Device drivers' .resume() callbacks have been executed and tasks have been thawed. +PM_RESTORE_PREPARE The system is going to restore a hibernation image. + If all goes well the restored kernel will issue a + PM_POST_HIBERNATION notification. + +PM_POST_RESTORE An error occurred during the hibernation restore. + 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 diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index aea7e92..9d60ab7 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -386,6 +386,11 @@ before suspending; then remount them after resuming. There is a work-around for this problem. For more information, see Documentation/usb/persist.txt. +Q: Can I suspend-to-disk using a swap partition under LVM? + +A: No. You can suspend successfully, but you'll not be able to +resume. uswsusp should be able to work with LVM. See suspend.sf.net. + Q: I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were compiled with the similar configuration files. Anyway I found that suspend to disk (and resume) is much slower on 2.6.16 compared to diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index e00c6cf..7b99636 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -14,7 +14,7 @@ are going to develop your own suspend/resume utilities. The interface consists of a character device providing the open(), release(), read(), and write() operations as well as several ioctl() -commands defined in kernel/power/power.h. The major and minor +commands defined in include/linux/suspend_ioctls.h . The major and minor numbers of the device are, respectively, 10 and 231, and they can be read from /sys/class/misc/snapshot/dev. @@ -27,17 +27,17 @@ once at a time. The ioctl() commands recognized by the device are: SNAPSHOT_FREEZE - freeze user space processes (the current process is - not frozen); this is required for SNAPSHOT_ATOMIC_SNAPSHOT + not frozen); this is required for SNAPSHOT_CREATE_IMAGE and SNAPSHOT_ATOMIC_RESTORE to succeed SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE -SNAPSHOT_ATOMIC_SNAPSHOT - create a snapshot of the system memory; the +SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the last argument of ioctl() should be a pointer to an int variable, the value of which will indicate whether the call returned after creating the snapshot (1) or after restoring the system memory state from it (0) (after resume the system finds itself finishing the - SNAPSHOT_ATOMIC_SNAPSHOT ioctl() again); after the snapshot + SNAPSHOT_CREATE_IMAGE ioctl() again); after the snapshot has been created the read() operation can be used to transfer it out of the kernel @@ -49,39 +49,37 @@ SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the SNAPSHOT_FREE - free memory allocated for the snapshot image -SNAPSHOT_SET_IMAGE_SIZE - set the preferred maximum size of the image +SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image (the kernel will do its best to ensure the image size will not exceed this number, but if it turns out to be impossible, the kernel will create the smallest image possible) -SNAPSHOT_AVAIL_SWAP - return the amount of available swap in bytes (the last - argument should be a pointer to an unsigned int variable that will +SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image + +SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the + last argument should be a pointer to an unsigned int variable that will contain the result if the call is successful). -SNAPSHOT_GET_SWAP_PAGE - allocate a swap page from the resume partition +SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition (the last argument should be a pointer to a loff_t variable that will contain the swap page offset if the call is successful) -SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated with - SNAPSHOT_GET_SWAP_PAGE - -SNAPSHOT_SET_SWAP_FILE - set the resume partition (the last ioctl() argument - should specify the device's major and minor numbers in the old - two-byte format, as returned by the stat() function in the .st_rdev - member of the stat structure) +SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by + SNAPSHOT_ALLOC_SWAP_PAGE SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE> units) from the beginning of the partition at which the swap header is located (the last ioctl() argument should point to a struct - resume_swap_area, as defined in kernel/power/power.h, containing the - resume device specification, as for the SNAPSHOT_SET_SWAP_FILE ioctl(), - and the offset); for swap partitions the offset is always 0, but it is - different to zero for swap files (please see - Documentation/swsusp-and-swap-files.txt for details). - The SNAPSHOT_SET_SWAP_AREA ioctl() is considered as a replacement for - SNAPSHOT_SET_SWAP_FILE which is regarded as obsolete. It is - recommended to always use this call, because the code to set the resume - partition may be removed from future kernels + resume_swap_area, as defined in kernel/power/suspend_ioctls.h, + containing the resume device specification and the offset); for swap + partitions the offset is always 0, but it is different from zero for + swap files (see Documentation/swsusp-and-swap-files.txt for details). + +SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support, + depending on the argument value (enable, if the argument is nonzero) + +SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation + state (eg. ACPI S4) using the platform (eg. ACPI) driver SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to immediately enter the suspend-to-RAM state, so this call must always @@ -93,24 +91,6 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to to resume the system from RAM if there's enough battery power or restore its state on the basis of the saved suspend image otherwise) -SNAPSHOT_PMOPS - enable the usage of the hibernation_ops->prepare, - hibernate_ops->enter and hibernation_ops->finish methods (the in-kernel - swsusp knows these as the "platform method") which are needed on many - machines to (among others) speed up the resume by letting the BIOS skip - some steps or to let the system recognise the correct state of the - hardware after the resume (in particular on many machines this ensures - that unplugged AC adapters get correctly detected and that kacpid does - not run wild after the resume). The last ioctl() argument can take one - of the three values, defined in kernel/power/power.h: - PMOPS_PREPARE - make the kernel carry out the - hibernation_ops->prepare() operation - PMOPS_ENTER - make the kernel power off the system by calling - hibernation_ops->enter() - PMOPS_FINISH - make the kernel carry out the - hibernation_ops->finish() operation - Note that the actual constants are misnamed because they surface - internal kernel implementation details that have changed. - The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time @@ -122,7 +102,7 @@ The device's write() operation is used for uploading the system memory snapshot into the kernel. It has the same limitations as the read() operation. The release() operation frees all memory allocated for the snapshot image -and all swap pages allocated with SNAPSHOT_GET_SWAP_PAGE (if any). +and all swap pages allocated with SNAPSHOT_ALLOC_SWAP_PAGE (if any). Thus it is not necessary to use either SNAPSHOT_FREE or SNAPSHOT_FREE_SWAP_PAGES before closing the device (in fact it will also unfreeze user space processes frozen by SNAPSHOT_UNFREEZE if they are @@ -133,16 +113,12 @@ snapshot image from/to the kernel will use a swap parition, called the resume partition, or a swap file as storage space (if a swap file is used, the resume partition is the partition that holds this file). However, this is not really required, as they can use, for example, a special (blank) suspend partition or -a file on a partition that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and +a file on a partition that is unmounted before SNAPSHOT_CREATE_IMAGE and mounted afterwards. -These utilities SHOULD NOT make any assumptions regarding the ordering of -data within the snapshot image, except for the image header that MAY be -assumed to start with an swsusp_info structure, as specified in -kernel/power/power.h. This structure MAY be used by the userland utilities -to obtain some information about the snapshot image, such as the size -of the snapshot image, including the metadata and the header itself, -contained in the .size member of swsusp_info. +These utilities MUST NOT make any assumptions regarding the ordering of +data within the snapshot image. The contents of the image are entirely owned +by the kernel and its structure may be changed in future kernel releases. The snapshot image MUST be written to the kernel unaltered (ie. all of the image data, metadata and header MUST be written in _exactly_ the same amount, form @@ -159,7 +135,7 @@ means, such as checksums, to ensure the integrity of the snapshot image. The suspending and resuming utilities MUST lock themselves in memory, preferrably using mlockall(), before calling SNAPSHOT_FREEZE. -The suspending utility MUST check the value stored by SNAPSHOT_ATOMIC_SNAPSHOT +The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE in the memory location pointed to by the last argument of ioctl() and proceed in accordance with it: 1. If the value is 1 (ie. the system memory snapshot has just been @@ -173,7 +149,7 @@ in accordance with it: image has been saved. (b) The suspending utility SHOULD NOT attempt to perform any file system operations (including reads) on the file systems - that were mounted before SNAPSHOT_ATOMIC_SNAPSHOT has been + that were mounted before SNAPSHOT_CREATE_IMAGE has been called. However, it MAY mount a file system that was not mounted at that time and perform some operations on it (eg. use it for saving the image). diff --git a/Documentation/power_supply_class.txt b/Documentation/power_supply_class.txt index 9758cf4..a8686e5 100644 --- a/Documentation/power_supply_class.txt +++ b/Documentation/power_supply_class.txt @@ -87,6 +87,10 @@ batteries use voltage for very approximated calculation of capacity. Battery driver also can use this attribute just to inform userspace about maximal and minimal voltage thresholds of a given battery. +VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that +these ones should be used if hardware could only guess (measure and +retain) the thresholds of a given power supply. + CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when battery considered full/empty. @@ -100,8 +104,6 @@ age)". I.e. these attributes represents real thresholds, not design values. ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. CAPACITY - capacity in percents. -CAPACITY_LEVEL - capacity level. This corresponds to -POWER_SUPPLY_CAPACITY_LEVEL_*. TEMP - temperature of the power supply. TEMP_AMBIENT - ambient temperature. diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt index b5e46ef..7b4e8a7 100644 --- a/Documentation/powerpc/booting-without-of.txt +++ b/Documentation/powerpc/booting-without-of.txt @@ -57,6 +57,7 @@ Table of Contents n) 4xx/Axon EMAC ethernet nodes o) Xilinx IP cores p) Freescale Synchronous Serial Interface + q) USB EHCI controllers VII - Specifying interrupt information for devices 1) interrupts property @@ -2577,6 +2578,20 @@ platforms are moved over to use the flattened-device-tree model. Requred properties: - current-speed : Baud rate of uartlite + v) Xilinx hwicap + + Xilinx hwicap devices provide access to the configuration logic + of the FPGA through the Internal Configuration Access Port + (ICAP). The ICAP enables partial reconfiguration of the FPGA, + readback of the configuration information, and some control over + 'warm boots' of the FPGA fabric. + + Required properties: + - xlnx,family : The family of the FPGA, necessary since the + capabilities of the underlying ICAP hardware + differ between different families. May be + 'virtex2p', 'virtex4', or 'virtex5'. + p) Freescale Synchronous Serial Interface The SSI is a serial device that communicates with audio codecs. It can @@ -2775,6 +2790,33 @@ platforms are moved over to use the flattened-device-tree model. interrupt-parent = < &ipic >; }; + q) USB EHCI controllers + + Required properties: + - compatible : should be "usb-ehci". + - reg : should contain at least address and length of the standard EHCI + register set for the device. Optional platform-dependent registers + (debug-port or other) can be also specified here, but only after + definition of standard EHCI registers. + - interrupts : one EHCI interrupt should be described here. + If device registers are implemented in big endian mode, the device + node should have "big-endian-regs" property. + If controller implementation operates with big endian descriptors, + "big-endian-desc" property should be specified. + If both big endian registers and descriptors are used by the controller + implementation, "big-endian" property can be specified instead of having + both "big-endian-regs" and "big-endian-desc". + + Example (Sequoia 440EPx): + ehci@e0000300 { + compatible = "ibm,usb-ehci-440epx", "usb-ehci"; + interrupt-parent = <&UIC0>; + interrupts = <1a 4>; + reg = <0 e0000300 90 0 e0000390 70>; + big-endian; + }; + + More devices will be defined as this spec matures. VII - Specifying interrupt information for devices diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index e20b19c..8deffcd 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -182,8 +182,8 @@ driver returns ENOIOCTLCMD. Some common examples: since the frequency is stored in the irq_freq member of the rtc_device structure. Your driver needs to initialize the irq_freq member during init. Make sure you check the requested frequency is in range of your - hardware in the irq_set_freq function. If you cannot actually change - the frequency, just return -ENOTTY. + hardware in the irq_set_freq function. If it isn't, return -EINVAL. If + you cannot actually change the frequency, do not define irq_set_freq. If all else fails, check out the rtc-test.c driver! @@ -268,8 +268,8 @@ int main(int argc, char **argv) /* This read will block */ retval = read(fd, &data, sizeof(unsigned long)); if (retval == -1) { - perror("read"); - exit(errno); + perror("read"); + exit(errno); } fprintf(stderr, " %d",i); fflush(stderr); @@ -326,11 +326,11 @@ test_READ: rtc_tm.tm_sec %= 60; rtc_tm.tm_min++; } - if (rtc_tm.tm_min == 60) { + if (rtc_tm.tm_min == 60) { rtc_tm.tm_min = 0; rtc_tm.tm_hour++; } - if (rtc_tm.tm_hour == 24) + if (rtc_tm.tm_hour == 24) rtc_tm.tm_hour = 0; retval = ioctl(fd, RTC_ALM_SET, &rtc_tm); @@ -407,8 +407,8 @@ test_PIE: "\n...Periodic IRQ rate is fixed\n"); goto done; } - perror("RTC_IRQP_SET ioctl"); - exit(errno); + perror("RTC_IRQP_SET ioctl"); + exit(errno); } fprintf(stderr, "\n%ldHz:\t", tmp); @@ -417,27 +417,27 @@ test_PIE: /* Enable periodic interrupts */ retval = ioctl(fd, RTC_PIE_ON, 0); if (retval == -1) { - perror("RTC_PIE_ON ioctl"); - exit(errno); + perror("RTC_PIE_ON ioctl"); + exit(errno); } for (i=1; i<21; i++) { - /* This blocks */ - retval = read(fd, &data, sizeof(unsigned long)); - if (retval == -1) { - perror("read"); - exit(errno); - } - fprintf(stderr, " %d",i); - fflush(stderr); - irqcount++; + /* This blocks */ + retval = read(fd, &data, sizeof(unsigned long)); + if (retval == -1) { + perror("read"); + exit(errno); + } + fprintf(stderr, " %d",i); + fflush(stderr); + irqcount++; } /* Disable periodic interrupts */ retval = ioctl(fd, RTC_PIE_OFF, 0); if (retval == -1) { - perror("RTC_PIE_OFF ioctl"); - exit(errno); + perror("RTC_PIE_OFF ioctl"); + exit(errno); } } diff --git a/Documentation/scheduler/00-INDEX b/Documentation/scheduler/00-INDEX new file mode 100644 index 0000000..b5f5ca0 --- /dev/null +++ b/Documentation/scheduler/00-INDEX @@ -0,0 +1,16 @@ +00-INDEX + - this file. +sched-arch.txt + - CPU Scheduler implementation hints for architecture specific code. +sched-coding.txt + - reference for various scheduler-related methods in the O(1) scheduler. +sched-design.txt + - goals, design and implementation of the Linux O(1) scheduler. +sched-design-CFS.txt + - goals, design and implementation of the Complete Fair Scheduler. +sched-domains.txt + - information on scheduling domains. +sched-nice-design.txt + - How and why the scheduler's nice levels are implemented. +sched-stats.txt + - information on schedstats (Linux Scheduler Statistics). diff --git a/Documentation/sched-arch.txt b/Documentation/scheduler/sched-arch.txt index 941615a..941615a 100644 --- a/Documentation/sched-arch.txt +++ b/Documentation/scheduler/sched-arch.txt diff --git a/Documentation/sched-coding.txt b/Documentation/scheduler/sched-coding.txt index cbd8db7..cbd8db7 100644 --- a/Documentation/sched-coding.txt +++ b/Documentation/scheduler/sched-coding.txt diff --git a/Documentation/sched-design-CFS.txt b/Documentation/scheduler/sched-design-CFS.txt index 88bcb87..88bcb87 100644 --- a/Documentation/sched-design-CFS.txt +++ b/Documentation/scheduler/sched-design-CFS.txt diff --git a/Documentation/sched-design.txt b/Documentation/scheduler/sched-design.txt index 1605bf0..1605bf0 100644 --- a/Documentation/sched-design.txt +++ b/Documentation/scheduler/sched-design.txt diff --git a/Documentation/sched-domains.txt b/Documentation/scheduler/sched-domains.txt index a9e990a..a9e990a 100644 --- a/Documentation/sched-domains.txt +++ b/Documentation/scheduler/sched-domains.txt diff --git a/Documentation/sched-nice-design.txt b/Documentation/scheduler/sched-nice-design.txt index e2bae5a..e2bae5a 100644 --- a/Documentation/sched-nice-design.txt +++ b/Documentation/scheduler/sched-nice-design.txt diff --git a/Documentation/sched-stats.txt b/Documentation/scheduler/sched-stats.txt index 442e14d..442e14d 100644 --- a/Documentation/sched-stats.txt +++ b/Documentation/scheduler/sched-stats.txt diff --git a/Documentation/scsi/ChangeLog.arcmsr b/Documentation/scsi/ChangeLog.arcmsr index cd8403a..de2bcac 100644 --- a/Documentation/scsi/ChangeLog.arcmsr +++ b/Documentation/scsi/ChangeLog.arcmsr @@ -68,4 +68,45 @@ ** 2. modify the arcmsr_pci_slot_reset function ** 3. modify the arcmsr_pci_ers_disconnect_forepart function ** 4. modify the arcmsr_pci_ers_need_reset_forepart function +** 1.20.00.15 09/27/2007 Erich Chen & Nick Cheng +** 1. add arcmsr_enable_eoi_mode() on adapter Type B +** 2. add readl(reg->iop2drv_doorbell_reg) in arcmsr_handle_hbb_isr() +** in case of the doorbell interrupt clearance is cached +** 1.20.00.15 10/01/2007 Erich Chen & Nick Cheng +** 1. modify acb->devstate[i][j] +** as ARECA_RAID_GOOD instead of +** ARECA_RAID_GONE in arcmsr_alloc_ccb_pool +** 1.20.00.15 11/06/2007 Erich Chen & Nick Cheng +** 1. add conditional declaration for +** arcmsr_pci_error_detected() and +** arcmsr_pci_slot_reset +** 1.20.00.15 11/23/2007 Erich Chen & Nick Cheng +** 1.check if the sg list member number +** exceeds arcmsr default limit in arcmsr_build_ccb() +** 2.change the returned value type of arcmsr_build_ccb() +** from "void" to "int" +** 3.add the conditional check if arcmsr_build_ccb() +** returns FAILED +** 1.20.00.15 12/04/2007 Erich Chen & Nick Cheng +** 1. modify arcmsr_drain_donequeue() to ignore unknown +** command and let kernel process command timeout. +** This could handle IO request violating max. segments +** while Linux XFS over DM-CRYPT. +** Thanks to Milan Broz's comments <mbroz@redhat.com> +** 1.20.00.15 12/24/2007 Erich Chen & Nick Cheng +** 1.fix the portability problems +** 2.fix type B where we should _not_ iounmap() acb->pmu; +** it's not ioremapped. +** 3.add return -ENOMEM if ioremap() fails +** 4.transfer IS_SG64_ADDR w/ cpu_to_le32() +** in arcmsr_build_ccb +** 5. modify acb->devstate[i][j] as ARECA_RAID_GONE instead of +** ARECA_RAID_GOOD in arcmsr_alloc_ccb_pool() +** 6.fix arcmsr_cdb->Context as (unsigned long)arcmsr_cdb +** 7.add the checking state of +** (outbound_intstatus & ARCMSR_MU_OUTBOUND_HANDLE_INT) == 0 +** in arcmsr_handle_hba_isr +** 8.replace pci_alloc_consistent()/pci_free_consistent() with kmalloc()/kfree() in arcmsr_iop_message_xfer() +** 9. fix the release of dma memory for type B in arcmsr_free_ccb_pool() +** 10.fix the arcmsr_polling_hbb_ccbdone() ************************************************************************** diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 6f70f2b..a6d5354 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -1407,7 +1407,7 @@ Credits ======= The following people have contributed to this document: Mike Anderson <andmike at us dot ibm dot com> - James Bottomley <James dot Bottomley at steeleye dot com> + James Bottomley <James dot Bottomley at hansenpartnership dot com> Patrick Mansfield <patmans at us dot ibm dot com> Christoph Hellwig <hch at infradead dot org> Doug Ledford <dledford at redhat dot com> diff --git a/Documentation/smp.txt b/Documentation/smp.txt deleted file mode 100644 index 82fc50b..0000000 --- a/Documentation/smp.txt +++ /dev/null @@ -1,22 +0,0 @@ -To set up SMP - -Configure the kernel and answer Y to CONFIG_SMP. - -If you are using LILO, it is handy to have both SMP and non-SMP -kernel images on hand. Edit /etc/lilo.conf to create an entry -for another kernel image called "linux-smp" or something. - -The next time you compile the kernel, when running a SMP kernel, -edit linux/Makefile and change "MAKE=make" to "MAKE=make -jN" -(where N = number of CPU + 1, or if you have tons of memory/swap - you can just use "-j" without a number). Feel free to experiment -with this one. - -Of course you should time how long each build takes :-) -Example: - make config - time -v sh -c 'make clean install modules modules_install' - -If you are using some Compaq MP compliant machines you will need to set -the operating system in the BIOS settings to "Unixware" - don't ask me -why Compaqs don't work otherwise. diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 4b48c2e..e985cf5 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -57,7 +57,9 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. - Default: 1 - For auto-loading more than one card, specify this option together with snd-card-X aliases. - + slots - Reserve the slot index for the given driver. + This option takes multiple strings. + See "Module Autoloading Support" section for details. Module snd-pcm-oss ------------------ @@ -148,13 +150,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips. - port - port # for AD1816A chip (PnP setup) - mpu_port - port # for MPU-401 UART (PnP setup) - fm_port - port # for OPL3 (PnP setup) - irq - IRQ # for AD1816A chip (PnP setup) - mpu_irq - IRQ # for MPU-401 UART (PnP setup) - dma1 - first DMA # for AD1816A chip (PnP setup) - dma2 - second DMA # for AD1816A chip (PnP setup) clockfreq - Clock frequency for AD1816A chip (default = 0, 33000Hz) This module supports multiple cards, autoprobe and PnP. @@ -201,14 +196,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips. - port - port # for ALS100 (SB16) chip (PnP setup) - irq - IRQ # for ALS100 (SB16) chip (PnP setup) - dma8 - 8-bit DMA # for ALS100 (SB16) chip (PnP setup) - dma16 - 16-bit DMA # for ALS100 (SB16) chip (PnP setup) - mpu_port - port # for MPU-401 UART (PnP setup) - mpu_irq - IRQ # for MPU-401 (PnP setup) - fm_port - port # for OPL3 FM (PnP setup) - This module supports multiple cards, autoprobe and PnP. The power-management is supported. @@ -302,15 +289,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only). - port - port # for AZT2320 chip (PnP setup) - wss_port - port # for WSS (PnP setup) - mpu_port - port # for MPU-401 UART (PnP setup) - fm_port - FM port # for AZT2320 chip (PnP setup) - irq - IRQ # for AZT2320 (WSS) chip (PnP setup) - mpu_irq - IRQ # for MPU-401 UART (PnP setup) - dma1 - 1st DMA # for AZT2320 (WSS) chip (PnP setup) - dma2 - 2nd DMA # for AZT2320 (WSS) chip (PnP setup) - This module supports multiple cards, PnP and autoprobe. The power-management is supported. @@ -350,6 +328,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on C-Media CMI8330 ISA chips. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + wssport - port # for CMI8330 chip (WSS) wssirq - IRQ # for CMI8330 chip (WSS) wssdma - first DMA # for CMI8330 chip (WSS) @@ -404,6 +386,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on CS4232/CS4232A ISA chips. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for CS4232 chip (PnP setup - 0x534) cport - control port # for CS4232 chip (PnP setup - 0x120,0x210,0xf00) mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable @@ -412,10 +398,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - IRQ # for MPU-401 UART (9,11,12,15) dma1 - first DMA # for CS4232 chip (0,1,3) dma2 - second DMA # for Yamaha CS4232 chip (0,1,3), -1 = disable - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) This module supports multiple cards. This module does not support autoprobe - thus main port must be specified!!! Other ports are optional. + (if ISA PnP is not used) thus main port must be specified!!! Other ports are + optional. The power-management is supported. @@ -425,6 +411,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on CS4235/CS4236/CS4236B/CS4237B/ CS4238B/CS4239 ISA chips. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for CS4236 chip (PnP setup - 0x534) cport - control port # for CS4236 chip (PnP setup - 0x120,0x210,0xf00) mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable @@ -433,7 +423,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. mpu_irq - IRQ # for MPU-401 UART (9,11,12,15) dma1 - first DMA # for CS4236 chip (0,1,3) dma2 - second DMA # for CS4236 chip (0,1,3), -1 = disable - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) This module supports multiple cards. This module does not support autoprobe (if ISA PnP is not used) thus main port and control port must be @@ -503,13 +492,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP only) - port - Port # (PnP setup) - mpu_port - Port # for MPU-401 (PnP setup) - fm_port - Port # for FM OPL-3 (PnP setup) - irq - IRQ # (PnP setup) - mpu_irq - IRQ # for MPU-401 (PnP setup) - dma8 - DMA # (PnP setup) - This module supports multiple cards. This module is enabled only with ISA PnP support. @@ -607,10 +589,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on ESS ES968 chip (PnP only). - port - port # for ES968 (SB8) chip (PnP setup) - irq - IRQ # for ES968 (SB8) chip (PnP setup) - dma1 - DMA # for ES968 (SB8) chip (PnP setup) - This module supports multiple cards, PnP and autoprobe. The power-management is supported. @@ -633,13 +611,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for ESS AudioDrive ES-18xx sound cards. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for ES-18xx chip (0x220,0x240,0x260) mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) fm_port - port # for FM (optional, not used) irq - IRQ # for ES-18xx chip (5,7,9,10) dma1 - first DMA # for ES-18xx chip (0,1,3) dma2 - first DMA # for ES-18xx chip (0,1,3) - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) This module supports multiple cards, ISA PnP and autoprobe (without MPU-401 port if native ISA PnP routines are not used). @@ -763,9 +744,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. VIA VT8251/VT8237A, SIS966, ULI M5461 + [Multiple options for each card instance] 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 (global) options] single_cmd - Use single immediate commands to communicate with codecs (for debugging only) enable_msi - Enable Message Signaled Interrupt (MSI) (default = off) @@ -774,8 +758,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. power_save_controller - Reset HD-audio controller in power-saving mode (default = on) - This module supports one card and autoprobe. - + This module supports multiple cards and autoprobe. + Each codec may have a model table for different configurations. If your machine isn't listed there, the default (usually minimal) configuration is set up. You can pass "model=<name>" option to @@ -817,17 +801,23 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. will Will laptops (PB V7900) replacer Replacer 672V basic fixed pin assignment (old default model) + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y auto auto-config reading BIOS (default) ALC262 fujitsu Fujitsu Laptop hp-bpc HP xw4400/6400/8400/9400 laptops hp-bpc-d7000 HP BPC D7000 + hp-tc-t5735 HP Thin Client T5735 + hp-rp5700 HP RP5700 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 + ultra Samsung Q1 Ultra Vista model basic fixed pin assignment w/o SPDIF auto auto-config reading BIOS (default) @@ -835,6 +825,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 3stack 3-stack model toshiba Toshiba A205 acer Acer laptops + dell Dell OEM laptops (Vostro 1200) + test for testing/debugging purpose, almost all controls can + adjusted. Appearing only when compiled with + $CONFIG_SND_DEBUG=y auto auto-config reading BIOS (default) ALC662 @@ -843,6 +837,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. 3stack-6ch-dig 3-stack (6-channel) with SPDIF 6stack-dig 6-stack with SPDIF lenovo-101e Lenovo laptop + eeepc-p701 ASUS Eeepc P701 + eeepc-ep20 ASUS Eeepc EP20 auto auto-config reading BIOS (default) ALC882/885 @@ -877,6 +873,8 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. haier-w66 Haier W66 6stack-hp HP machines with 6stack (Nettle boards) 3stack-hp HP machines with 3stack (Lucknow, Samba boards) + 6stack-dell Dell machines with 6stack (Inspiron 530) + mitac Mitac 8252D auto auto-config reading BIOS (default) ALC861/660 @@ -928,6 +926,7 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. AD1984 basic default configuration thinkpad Lenovo Thinkpad T61/X61 + dell Dell T3400 AD1986A 6stack 6-jack, separate surrounds (default) @@ -947,7 +946,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. auto auto-config reading BIOS (default) Conexant 5045 - laptop Laptop config + laptop-hpsense Laptop with HP sense (old model laptop) + laptop-micsense Laptop with Mic sense (old model fujitsu) + laptop-hpmicsense Laptop with HP and Mic senses + benq Benq R55E test for testing/debugging purpose, almost all controls can be adjusted. Appearing only when compiled with $CONFIG_SND_DEBUG=y @@ -960,6 +962,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. can be adjusted. Appearing only when compiled with $CONFIG_SND_DEBUG=y + Conexant 5051 + laptop Basic Laptop config (default) + hp HP Spartan laptop + STAC9200 ref Reference board dell-d21 Dell (unknown) @@ -1091,6 +1097,15 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. See hdspm.txt for details. + Module snd-hifier + ----------------- + + Module for the MediaTek/TempoTec HiFier Fantasia sound card. + + This module supports autoprobe and multiple cards. + + Power management is _not_ supported. + Module snd-ice1712 ------------------ @@ -1156,11 +1171,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. * Chaintech 9CJS * Chaintech AV-710 * Shuttle SN25P + * Onkyo SE-90PCI + * Onkyo SE-200PCI model - Use the given board model, one of the following: revo51, revo71, amp2000, prodigy71, prodigy71lt, prodigy192, aureon51, aureon71, universe, ap192, - k8x800, phase22, phase28, ms300, av710 + k8x800, phase22, phase28, ms300, av710, se200pci, + se90pci This module supports multiple cards and autoprobe. @@ -1257,15 +1275,19 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Gravis UltraSound PnP, Dynasonic 3-D/Pro, STB Sound Rage 32 and other sound cards based on AMD InterWave (tm) chip. - port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) - irq - IRQ # for InterWave chip (3,5,9,11,12,15) - dma1 - DMA # for InterWave chip (0,1,3,5,6,7) - dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default) pcm_voices - reserved PCM voices for the synthesizer (default 2) effect - 1 = InterWave effects enable (default 0); requires 8 voices + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + + port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) + irq - IRQ # for InterWave chip (3,5,9,11,12,15) + dma1 - DMA # for InterWave chip (0,1,3,5,6,7) + dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) This module supports multiple cards, autoprobe and ISA PnP. @@ -1276,16 +1298,20 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. and other sound cards based on AMD InterWave (tm) chip with TEA6330T circuit for extended control of bass, treble and master volume. - port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) - port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380) - irq - IRQ # for InterWave chip (3,5,9,11,12,15) - dma1 - DMA # for InterWave chip (0,1,3,5,6,7) - dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default) pcm_voices - reserved PCM voices for the synthesizer (default 2) effect - 1 = InterWave effects enable (default 0); requires 8 voices + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + + port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) + port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380) + irq - IRQ # for InterWave chip (3,5,9,11,12,15) + dma1 - DMA # for InterWave chip (0,1,3,5,6,7) + dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) This module supports multiple cards, autoprobe and ISA PnP. @@ -1473,6 +1499,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Yamaha OPL3-SA2/SA3 sound cards. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - control port # for OPL3-SA chip (0x370) sb_port - SB port # for OPL3-SA chip (0x220,0x240) wss_port - WSS port # for OPL3-SA chip (0x530,0xe80,0xf40,0x604) @@ -1481,7 +1511,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # for OPL3-SA chip (5,7,9,10) dma1 - first DMA # for Yamaha OPL3-SA chip (0,1,3) dma2 - second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) This module supports multiple cards and ISA PnP. It does not support autoprobe (if ISA PnP is not used) thus all ports must be specified!!! @@ -1494,6 +1523,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on OPTi 82c92x and Analog Devices AD1848 chips. Module works with OAK Mozart cards as well. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for WSS chip (0x530,0xe80,0xf40,0x604) mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) fm_port - port # for OPL3 device (0x388) @@ -1508,6 +1541,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on OPTi 82c92x and Crystal CS4231 chips. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for WSS chip (0x530,0xe80,0xf40,0x604) mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) fm_port - port # for OPL3 device (0x388) @@ -1523,6 +1560,10 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for sound cards based on OPTi 82c93x chips. + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for WSS chip (0x530,0xe80,0xf40,0x604) mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) fm_port - port # for OPL3 device (0x388) @@ -1533,6 +1574,22 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module supports only one card, autoprobe and PnP. + Module snd-oxygen + ----------------- + + Module for sound cards based on the C-Media CMI8788 chip: + * Asound A-8788 + * AuzenTech X-Meridian + * Bgears b-Enspirer + * Club3D Theatron DTS + * HT-Omega Claro + * Razer Barracuda AC-1 + * Sondigo Inferno + + This module supports autoprobe and multiple cards. + + Power management is _not_ supported. + Module snd-pcxhr ---------------- @@ -1647,6 +1704,12 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. SoundBlaster AWE 32 (PnP), SoundBlaster AWE 64 PnP + mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default) + csp - ASP/CSP chip support - 0 = disable (default), 1 = enable + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + port - port # for SB DSP 4.x chip (0x220,0x240,0x260) mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disable awe_port - base port # for EMU8000 synthesizer (0x620,0x640,0x660) @@ -1654,9 +1717,6 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. irq - IRQ # for SB DSP 4.x chip (5,7,9,10) dma8 - 8-bit DMA # for SB DSP 4.x chip (0,1,3) dma16 - 16-bit DMA # for SB DSP 4.x chip (5,6,7) - mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default) - csp - ASP/CSP chip support - 0 = disable (default), 1 = enable - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) This module supports multiple cards, autoprobe and ISA PnP. @@ -1739,18 +1799,21 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. Module for Turtle Beach Maui, Tropez and Tropez+ sound cards. + use_cs4232_midi - Use CS4232 MPU-401 interface + (inaccessibly located inside your computer) + isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) + + with isapnp=0, the following options are available: + cs4232_pcm_port - Port # for CS4232 PCM interface. cs4232_pcm_irq - IRQ # for CS4232 PCM interface (5,7,9,11,12,15). cs4232_mpu_port - Port # for CS4232 MPU-401 interface. cs4232_mpu_irq - IRQ # for CS4232 MPU-401 interface (9,11,12,15). - use_cs4232_midi - Use CS4232 MPU-401 interface - (inaccessibly located inside your computer) ics2115_port - Port # for ICS2115 ics2115_irq - IRQ # for ICS2115 fm_port - FM OPL-3 Port # dma1 - DMA1 # for CS4232 PCM interface. dma2 - DMA2 # for CS4232 PCM interface. - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) The below are options for wavefront_synth features: wf_raw - Assume that we need to boot the OS (default:no) @@ -1965,6 +2028,16 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. This module supports multiple cards. + Module snd-virtuoso + ------------------- + + Module for sound cards based on the Asus AV200 chip, i.e., + Xonar D2 and Xonar D2X. + + This module supports autoprobe and multiple cards. + + Power management is _not_ supported. + Module snd-vx222 ---------------- @@ -2135,6 +2208,23 @@ alias sound-slot-1 snd-ens1371 In this example, the interwave card is always loaded as the first card (index 0) and ens1371 as the second (index 1). +Alternative (and new) way to fixate the slot assignment is to use +"slots" option of snd module. In the case above, specify like the +following: + +options snd slots=snd-interwave,snd-ens1371 + +Then, the first slot (#0) is reserved for snd-interwave driver, and +the second (#1) for snd-ens1371. You can omit index option in each +driver if slots option is used (although you can still have them at +the same time as long as they don't conflict). + +The slots option is especially useful for avoiding the possible +hot-plugging and the resultant slot conflict. For example, in the +case above again, the first two slots are already reserved. If any +other driver (e.g. snd-usb-audio) is loaded before snd-interwave or +snd-ens1371, it will be assigned to the third or later slot. + ALSA PCM devices to OSS devices mapping ======================================= diff --git a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl index 2c3fc3c..b03df4d4 100644 --- a/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/sound/alsa/DocBook/writing-an-alsa-driver.tmpl @@ -18,7 +18,7 @@ </affiliation> </author> - <date>September 10, 2007</date> + <date>Oct 15, 2007</date> <edition>0.3.7</edition> <abstract> @@ -67,7 +67,7 @@ This document describes how to write an <ulink url="http://www.alsa-project.org/"><citetitle> ALSA (Advanced Linux Sound Architecture)</citetitle></ulink> - driver. The document focuses mainly on the PCI soundcard. + driver. The document focuses mainly on PCI soundcards. In the case of other device types, the API might be different, too. However, at least the ALSA kernel API is consistent, and therefore it would be still a bit help for @@ -75,23 +75,23 @@ </para> <para> - The target of this document is ones who already have enough - skill of C language and have the basic knowledge of linux - kernel programming. This document doesn't explain the general - topics of linux kernel codes and doesn't cover the detail of - implementation of each low-level driver. It describes only how is + This document targets people who already have enough + C language skills and have basic linux kernel programming + knowledge. This document doesn't explain the general + topic of linux kernel coding and doesn't cover low-level + driver implementation details. It only describes the standard way to write a PCI sound driver on ALSA. </para> <para> - If you are already familiar with the older ALSA ver.0.5.x, you - can check the drivers such as <filename>es1938.c</filename> or - <filename>maestro3.c</filename> which have also almost the same + If you are already familiar with the older ALSA ver.0.5.x API, you + can check the drivers such as <filename>sound/pci/es1938.c</filename> or + <filename>sound/pci/maestro3.c</filename> which have also almost the same code-base in the ALSA 0.5.x tree, so you can compare the differences. </para> <para> - This document is still a draft version. Any feedbacks and + This document is still a draft version. Any feedback and corrections, please!! </para> </preface> @@ -106,7 +106,7 @@ <section id="file-tree-general"> <title>General</title> <para> - The ALSA drivers are provided in the two ways. + The ALSA drivers are provided in two ways. </para> <para> @@ -114,15 +114,14 @@ ALSA's ftp site, and another is the 2.6 (or later) Linux kernel tree. To synchronize both, the ALSA driver tree is split into two different trees: alsa-kernel and alsa-driver. The former - contains purely the source codes for the Linux 2.6 (or later) + contains purely the source code for the Linux 2.6 (or later) tree. This tree is designed only for compilation on 2.6 or later environment. The latter, alsa-driver, contains many subtle - files for compiling the ALSA driver on the outside of Linux - kernel like configure script, the wrapper functions for older, - 2.2 and 2.4 kernels, to adapt the latest kernel API, + files for compiling ALSA drivers outside of the Linux kernel tree, + wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API, and additional drivers which are still in development or in tests. The drivers in alsa-driver tree will be moved to - alsa-kernel (eventually 2.6 kernel tree) once when they are + alsa-kernel (and eventually to the 2.6 kernel tree) when they are finished and confirmed to work fine. </para> @@ -168,7 +167,7 @@ <section id="file-tree-core-directory"> <title>core directory</title> <para> - This directory contains the middle layer, that is, the heart + This directory contains the middle layer which is the heart of ALSA drivers. In this directory, the native ALSA modules are stored. The sub-directories contain different modules and are dependent upon the kernel config. @@ -181,7 +180,7 @@ The codes for PCM and mixer OSS emulation modules are stored in this directory. The rawmidi OSS emulation is included in the ALSA rawmidi code since it's quite small. The sequencer - code is stored in core/seq/oss directory (see + code is stored in <filename>core/seq/oss</filename> directory (see <link linkend="file-tree-core-directory-seq-oss"><citetitle> below</citetitle></link>). </para> @@ -200,7 +199,7 @@ <section id="file-tree-core-directory-seq"> <title>core/seq</title> <para> - This and its sub-directories are for the ALSA + This directory and its sub-directories are for the ALSA sequencer. This directory contains the sequencer core and primary sequencer modules such like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when @@ -229,22 +228,22 @@ <title>include directory</title> <para> This is the place for the public header files of ALSA drivers, - which are to be exported to the user-space, or included by + which are to be exported to user-space, or included by several files at different directories. Basically, the private header files should not be placed in this directory, but you may - still find files there, due to historical reason :) + still find files there, due to historical reasons :) </para> </section> <section id="file-tree-drivers-directory"> <title>drivers directory</title> <para> - This directory contains the codes shared among different drivers - on the different architectures. They are hence supposed not to be + This directory contains code shared among different drivers + on different architectures. They are hence supposed not to be architecture-specific. For example, the dummy pcm driver and the serial MIDI driver are found in this directory. In the sub-directories, - there are the codes for components which are independent from + there is code for components which are independent from bus and cpu architectures. </para> @@ -271,7 +270,7 @@ <para> Although there is a standard i2c layer on Linux, ALSA has its - own i2c codes for some cards, because the soundcard needs only a + own i2c code for some cards, because the soundcard needs only a simple operation and the standard i2c API is too complicated for such a purpose. </para> @@ -292,28 +291,28 @@ <para> So far, there is only Emu8000/Emu10k1 synth driver under - synth/emux sub-directory. + the <filename>synth/emux</filename> sub-directory. </para> </section> <section id="file-tree-pci-directory"> <title>pci directory</title> <para> - This and its sub-directories hold the top-level card modules - for PCI soundcards and the codes specific to the PCI BUS. + This directory and its sub-directories hold the top-level card modules + for PCI soundcards and the code specific to the PCI BUS. </para> <para> - The drivers compiled from a single file is stored directly on - pci directory, while the drivers with several source files are - stored on its own sub-directory (e.g. emu10k1, ice1712). + The drivers compiled from a single file are stored directly + in the pci directory, while the drivers with several source files are + stored on their own sub-directory (e.g. emu10k1, ice1712). </para> </section> <section id="file-tree-isa-directory"> <title>isa directory</title> <para> - This and its sub-directories hold the top-level card modules + This directory and its sub-directories hold the top-level card modules for ISA soundcards. </para> </section> @@ -321,16 +320,16 @@ <section id="file-tree-arm-ppc-sparc-directories"> <title>arm, ppc, and sparc directories</title> <para> - These are for the top-level card modules which are - specific to each given architecture. + They are used for top-level card modules which are + specific to one of these architectures. </para> </section> <section id="file-tree-usb-directory"> <title>usb directory</title> <para> - This contains the USB-audio driver. On the latest version, the - USB MIDI driver is integrated together with usb-audio driver. + This directory contains the USB-audio driver. In the latest version, the + USB MIDI driver is integrated in the usb-audio driver. </para> </section> @@ -338,16 +337,17 @@ <title>pcmcia directory</title> <para> The PCMCIA, especially PCCard drivers will go here. CardBus - drivers will be on pci directory, because its API is identical - with the standard PCI cards. + drivers will be in the pci directory, because their API is identical + to that of standard PCI cards. </para> </section> <section id="file-tree-oss-directory"> <title>oss directory</title> <para> - The OSS/Lite source files are stored here on Linux 2.6 (or - later) tree. (In the ALSA driver tarball, it's empty, of course :) + The OSS/Lite source files are stored here in Linux 2.6 (or + later) tree. In the ALSA driver tarball, this directory is empty, + of course :) </para> </section> </chapter> @@ -362,7 +362,7 @@ <section id="basic-flow-outline"> <title>Outline</title> <para> - The minimum flow of PCI soundcard is like the following: + The minimum flow for PCI soundcards is as follows: <itemizedlist> <listitem><para>define the PCI ID table (see the section @@ -370,9 +370,13 @@ </citetitle></link>).</para></listitem> <listitem><para>create <function>probe()</function> callback.</para></listitem> <listitem><para>create <function>remove()</function> callback.</para></listitem> - <listitem><para>create pci_driver table which contains the three pointers above.</para></listitem> - <listitem><para>create <function>init()</function> function just calling <function>pci_register_driver()</function> to register the pci_driver table defined above.</para></listitem> - <listitem><para>create <function>exit()</function> function to call <function>pci_unregister_driver()</function> function.</para></listitem> + <listitem><para>create a <structname>pci_driver</structname> structure + containing the three pointers above.</para></listitem> + <listitem><para>create an <function>init()</function> function just calling + the <function>pci_register_driver()</function> to register the pci_driver table + defined above.</para></listitem> + <listitem><para>create an <function>exit()</function> function to call + the <function>pci_unregister_driver()</function> function.</para></listitem> </itemizedlist> </para> </section> @@ -382,15 +386,14 @@ <para> The code example is shown below. Some parts are kept unimplemented at this moment but will be filled in the - succeeding sections. The numbers in comment lines of - <function>snd_mychip_probe()</function> function are the - markers. + next sections. The numbers in the comment lines of the + <function>snd_mychip_probe()</function> function + refer to details explained in the following section. <example> - <title>Basic Flow for PCI Drivers Example</title> + <title>Basic Flow for PCI Drivers - Example</title> <programlisting> <![CDATA[ - #include <sound/driver.h> #include <linux/init.h> #include <linux/pci.h> #include <linux/slab.h> @@ -398,6 +401,7 @@ #include <sound/initval.h> /* module parameters (see "Module Parameters") */ + /* SNDRV_CARDS: maximum number of cards supported by this module */ static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; @@ -405,13 +409,13 @@ /* definition of the chip-specific record */ struct mychip { struct snd_card *card; - /* rest of implementation will be in the section - * "PCI Resource Managements" + /* the rest of the implementation will be in section + * "PCI Resource Management" */ }; /* chip-specific destructor - * (see "PCI Resource Managements") + * (see "PCI Resource Management") */ static int snd_mychip_free(struct mychip *chip) { @@ -442,7 +446,7 @@ *rchip = NULL; /* check PCI availability here - * (see "PCI Resource Managements") + * (see "PCI Resource Management") */ .... @@ -454,7 +458,7 @@ chip->card = card; /* rest of initialization here; will be implemented - * later, see "PCI Resource Managements" + * later, see "PCI Resource Management" */ .... @@ -521,7 +525,7 @@ return 0; } - /* destructor -- see "Destructor" sub-section */ + /* destructor -- see the "Destructor" sub-section */ static void __devexit snd_mychip_remove(struct pci_dev *pci) { snd_card_free(pci_get_drvdata(pci)); @@ -536,16 +540,16 @@ <section id="basic-flow-constructor"> <title>Constructor</title> <para> - The real constructor of PCI drivers is probe callback. The - probe callback and other component-constructors which are called - from probe callback should be defined with - <parameter>__devinit</parameter> prefix. You - cannot use <parameter>__init</parameter> prefix for them, + The real constructor of PCI drivers is the <function>probe</function> callback. + The <function>probe</function> callback and other component-constructors which are called + from the <function>probe</function> callback should be defined with + the <parameter>__devinit</parameter> prefix. You + cannot use the <parameter>__init</parameter> prefix for them, because any PCI device could be a hotplug device. </para> <para> - In the probe callback, the following scheme is often used. + In the <function>probe</function> callback, the following scheme is often used. </para> <section id="basic-flow-constructor-device-index"> @@ -570,7 +574,7 @@ </para> <para> - At each time probe callback is called, check the + Each time the <function>probe</function> callback is called, check the availability of the device. If not available, simply increment the device index and returns. dev will be incremented also later (<link @@ -594,7 +598,7 @@ </para> <para> - The detail will be explained in the section + The details will be explained in the section <link linkend="card-management-card-instance"><citetitle> Management of Cards and Components</citetitle></link>. </para> @@ -619,9 +623,9 @@ </programlisting> </informalexample> - The detail will be explained in the section <link + The details will be explained in the section <link linkend="pci-resource"><citetitle>PCI Resource - Managements</citetitle></link>. + Management</citetitle></link>. </para> </section> @@ -640,7 +644,7 @@ </informalexample> The driver field holds the minimal ID string of the - chip. This is referred by alsa-lib's configurator, so keep it + chip. This is used by alsa-lib's configurator, so keep it simple but unique. Even the same driver can have different driver IDs to distinguish the functionality of each chip type. @@ -648,7 +652,7 @@ <para> The shortname field is a string shown as more verbose - name. The longname field contains the information which is + name. The longname field contains the information shown in <filename>/proc/asound/cards</filename>. </para> </section> @@ -703,7 +707,7 @@ </informalexample> In the above, the card record is stored. This pointer is - referred in the remove callback and power-management + used in the remove callback and power-management callbacks, too. </para> </section> @@ -746,7 +750,6 @@ <informalexample> <programlisting> <![CDATA[ - #include <sound/driver.h> #include <linux/init.h> #include <linux/pci.h> #include <linux/slab.h> @@ -757,22 +760,22 @@ </informalexample> where the last one is necessary only when module options are - defined in the source file. If the codes are split to several - files, the file without module options don't need them. + defined in the source file. If the code is split into several + files, the files without module options don't need them. </para> <para> - In addition to them, you'll need - <filename><linux/interrupt.h></filename> for the interrupt - handling, and <filename><asm/io.h></filename> for the i/o - access. If you use <function>mdelay()</function> or + In addition to these headers, you'll need + <filename><linux/interrupt.h></filename> for interrupt + handling, and <filename><asm/io.h></filename> for I/O + access. If you use the <function>mdelay()</function> or <function>udelay()</function> functions, you'll need to include - <filename><linux/delay.h></filename>, too. + <filename><linux/delay.h></filename> too. </para> <para> - The ALSA interfaces like PCM or control API are defined in other - header files as <filename><sound/xxx.h></filename>. + The ALSA interfaces like the PCM and control APIs are defined in other + <filename><sound/xxx.h></filename> header files. They have to be included after <filename><sound/core.h></filename>. </para> @@ -795,12 +798,12 @@ <para> A card record is the headquarters of the soundcard. It manages - the list of whole devices (components) on the soundcard, such as + the whole list of devices (components) on the soundcard, such as PCM, mixers, MIDI, synthesizer, and so on. Also, the card record holds the ID and the name strings of the card, manages the root of proc files, and controls the power-management states and hotplug disconnections. The component list on the card - record is used to manage the proper releases of resources at + record is used to manage the correct release of resources at destruction. </para> @@ -824,9 +827,8 @@ <constant>THIS_MODULE</constant>), and the size of extra-data space. The last argument is used to allocate card->private_data for the - chip-specific data. Note that this data - <emphasis>is</emphasis> allocated by - <function>snd_card_new()</function>. + chip-specific data. Note that these data + are allocated by <function>snd_card_new()</function>. </para> </section> @@ -834,10 +836,10 @@ <title>Components</title> <para> After the card is created, you can attach the components - (devices) to the card instance. On ALSA driver, a component is + (devices) to the card instance. In an ALSA driver, a component is represented as a struct <structname>snd_device</structname> object. A component can be a PCM instance, a control interface, a raw - MIDI interface, etc. Each of such instances has one component + MIDI interface, etc. Each such instance has one component entry. </para> @@ -859,7 +861,7 @@ (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the callback pointers (<parameter>&ops</parameter>). The device-level defines the type of components and the order of - registration and de-registration. For most of components, the + registration and de-registration. For most components, the device-level is already defined. For a user-defined component, you can use <constant>SNDRV_DEV_LOWLEVEL</constant>. </para> @@ -867,13 +869,13 @@ <para> This function itself doesn't allocate the data space. The data must be allocated manually beforehand, and its pointer is passed - as the argument. This pointer is used as the identifier - (<parameter>chip</parameter> in the above example) for the - instance. + as the argument. This pointer is used as the + (<parameter>chip</parameter> identifier in the above example) + for the instance. </para> <para> - Each ALSA pre-defined component such as ac97 or pcm calls + Each pre-defined ALSA component such as ac97 and pcm calls <function>snd_device_new()</function> inside its constructor. The destructor for each component is defined in the callback pointers. Hence, you don't need to take care of @@ -881,19 +883,19 @@ </para> <para> - If you would like to create your own component, you need to - set the destructor function to dev_free callback in - <parameter>ops</parameter>, so that it can be released - automatically via <function>snd_card_free()</function>. The - example will be shown later as an implementation of a - chip-specific data. + If you wish to create your own component, you need to + set the destructor function to the dev_free callback in + the <parameter>ops</parameter>, so that it can be released + automatically via <function>snd_card_free()</function>. + The next example will show an implementation of chip-specific + data. </para> </section> <section id="card-management-chip-specific"> <title>Chip-Specific Data</title> <para> - The chip-specific information, e.g. the i/o port address, its + Chip-specific information, e.g. the I/O port address, its resource pointer, or the irq number, is stored in the chip-specific record. @@ -909,13 +911,14 @@ </para> <para> - In general, there are two ways to allocate the chip record. + In general, there are two ways of allocating the chip record. </para> <section id="card-management-chip-specific-snd-card-new"> <title>1. Allocating via <function>snd_card_new()</function>.</title> <para> - As mentioned above, you can pass the extra-data-length to the 4th argument of <function>snd_card_new()</function>, i.e. + As mentioned above, you can pass the extra-data-length + to the 4th argument of <function>snd_card_new()</function>, i.e. <informalexample> <programlisting> @@ -925,7 +928,7 @@ </programlisting> </informalexample> - whether struct <structname>mychip</structname> is the type of the chip record. + struct <structname>mychip</structname> is the type of the chip record. </para> <para> @@ -1037,8 +1040,8 @@ <title>Registration and Release</title> <para> After all components are assigned, register the card instance - by calling <function>snd_card_register()</function>. The access - to the device files are enabled at this point. That is, before + by calling <function>snd_card_register()</function>. Access + to the device files is enabled at this point. That is, before <function>snd_card_register()</function> is called, the components are safely inaccessible from external side. If this call fails, exit the probe function after releasing the card via @@ -1047,7 +1050,7 @@ <para> For releasing the card instance, you can call simply - <function>snd_card_free()</function>. As already mentioned, all + <function>snd_card_free()</function>. As mentioned earlier, all components are released automatically by this call. </para> @@ -1055,7 +1058,7 @@ As further notes, the destructors (both <function>snd_mychip_dev_free</function> and <function>snd_mychip_free</function>) cannot be defined with - <parameter>__devexit</parameter> prefix, because they may be + the <parameter>__devexit</parameter> prefix, because they may be called from the constructor, too, at the false path. </para> @@ -1071,20 +1074,20 @@ <!-- ****************************************************** --> -<!-- PCI Resource Managements --> +<!-- PCI Resource Management --> <!-- ****************************************************** --> <chapter id="pci-resource"> - <title>PCI Resource Managements</title> + <title>PCI Resource Management</title> <section id="pci-resource-example"> <title>Full Code Example</title> <para> - In this section, we'll finish the chip-specific constructor, - destructor and PCI entries. The example code is shown first, + In this section, we'll complete the chip-specific constructor, + destructor and PCI entries. Example code is shown first, below. <example> - <title>PCI Resource Managements Example</title> + <title>PCI Resource Management Example</title> <programlisting> <![CDATA[ struct mychip { @@ -1103,7 +1106,7 @@ /* release the irq */ if (chip->irq >= 0) free_irq(chip->irq, chip); - /* release the i/o ports & memory */ + /* release the I/O ports & memory */ pci_release_regions(chip->pci); /* disable the PCI entry */ pci_disable_device(chip->pci); @@ -1196,13 +1199,13 @@ .remove = __devexit_p(snd_mychip_remove), }; - /* initialization of the module */ + /* module initialization */ static int __init alsa_card_mychip_init(void) { return pci_register_driver(&driver); } - /* clean up the module */ + /* module clean up */ static void __exit alsa_card_mychip_exit(void) { pci_unregister_driver(&driver); @@ -1228,10 +1231,10 @@ </para> <para> - In the case of PCI devices, you have to call at first - <function>pci_enable_device()</function> function before + In the case of PCI devices, you first have to call + the <function>pci_enable_device()</function> function before allocating resources. Also, you need to set the proper PCI DMA - mask to limit the accessed i/o range. In some cases, you might + mask to limit the accessed I/O range. In some cases, you might need to call <function>pci_set_master()</function> function, too. </para> @@ -1261,15 +1264,15 @@ <section id="pci-resource-resource-allocation"> <title>Resource Allocation</title> <para> - The allocation of I/O ports and irqs are done via standard kernel + The allocation of I/O ports and irqs is done via standard kernel functions. Unlike ALSA ver.0.5.x., there are no helpers for that. And these resources must be released in the destructor function (see below). Also, on ALSA 0.9.x, you don't need to - allocate (pseudo-)DMA for PCI like ALSA 0.5.x. + allocate (pseudo-)DMA for PCI like in ALSA 0.5.x. </para> <para> - Now assume that this PCI device has an I/O port with 8 bytes + Now assume that the PCI device has an I/O port with 8 bytes and an interrupt. Then struct <structname>mychip</structname> will have the following fields: @@ -1288,7 +1291,7 @@ </para> <para> - For an i/o port (and also a memory region), you need to have + For an I/O port (and also a memory region), you need to have the resource pointer for the standard resource management. For an irq, you have to keep only the irq number (integer). But you need to initialize this number as -1 before actual allocation, @@ -1299,7 +1302,7 @@ </para> <para> - The allocation of an i/o port is done like this: + The allocation of an I/O port is done like this: <informalexample> <programlisting> @@ -1318,12 +1321,12 @@ <para> <!-- obsolete --> - It will reserve the i/o port region of 8 bytes of the given + It will reserve the I/O port region of 8 bytes of the given PCI device. The returned value, chip->res_port, is allocated via <function>kmalloc()</function> by <function>request_region()</function>. The pointer must be - released via <function>kfree()</function>, but there is some - problem regarding this. This issue will be explained more below. + released via <function>kfree()</function>, but there is a + problem with this. This issue will be explained later. </para> <para> @@ -1351,8 +1354,8 @@ </para> <para> - On the PCI bus, the interrupts can be shared. Thus, - <constant>IRQF_SHARED</constant> is given as the interrupt flag of + On the PCI bus, interrupts can be shared. Thus, + <constant>IRQF_SHARED</constant> is used as the interrupt flag of <function>request_irq()</function>. </para> @@ -1364,7 +1367,7 @@ </para> <para> - I won't define the detail of the interrupt handler at this + I won't give details about the interrupt handler at this point, but at least its appearance can be explained now. The interrupt handler looks usually like the following: @@ -1386,11 +1389,11 @@ Now let's write the corresponding destructor for the resources above. The role of destructor is simple: disable the hardware (if already activated) and release the resources. So far, we - have no hardware part, so the disabling is not written here. + have no hardware part, so the disabling code is not written here. </para> <para> - For releasing the resources, <quote>check-and-release</quote> + To release the resources, the <quote>check-and-release</quote> method is a safer way. For the interrupt, do like this: <informalexample> @@ -1410,7 +1413,7 @@ <para> When you requested I/O ports or memory regions via <function>pci_request_region()</function> or - <function>pci_request_regions()</function> like this example, + <function>pci_request_regions()</function> like in this example, release the resource(s) using the corresponding function, <function>pci_release_region()</function> or <function>pci_release_regions()</function>. @@ -1429,7 +1432,7 @@ or <function>request_mem_region</function>, you can release it via <function>release_resource()</function>. Suppose that you keep the resource pointer returned from <function>request_region()</function> - in chip->res_port, the release procedure looks like below: + in chip->res_port, the release procedure looks like: <informalexample> <programlisting> @@ -1442,7 +1445,7 @@ <para> Don't forget to call <function>pci_disable_device()</function> - before all finished. + before the end. </para> <para> @@ -1459,14 +1462,14 @@ <para> Again, remember that you cannot - set <parameter>__devexit</parameter> prefix for this destructor. + use the <parameter>__devexit</parameter> prefix for this destructor. </para> <para> - We didn't implement the hardware-disabling part in the above. + We didn't implement the hardware disabling part in the above. If you need to do this, please note that the destructor may be called even before the initialization of the chip is completed. - It would be better to have a flag to skip the hardware-disabling + It would be better to have a flag to skip hardware disabling if the hardware was not initialized yet. </para> @@ -1475,14 +1478,14 @@ <function>snd_device_new()</function> with <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is called at the last. That is, it is assured that all other - components like PCMs and controls have been already released. - You don't have to call stopping PCMs, etc. explicitly, but just - stop the hardware in the low-level. + components like PCMs and controls have already been released. + You don't have to stop PCMs, etc. explicitly, but just + call low-level hardware stopping. </para> <para> The management of a memory-mapped region is almost as same as - the management of an i/o port. You'll need three fields like + the management of an I/O port. You'll need three fields like the following: <informalexample> @@ -1561,8 +1564,8 @@ <section id="pci-resource-entries"> <title>PCI Entries</title> <para> - So far, so good. Let's finish the rest of missing PCI - stuffs. At first, we need a + So far, so good. Let's finish the missing PCI + stuff. At first, we need a <structname>pci_device_id</structname> table for this chipset. It's a table of PCI vendor/device ID number, and some masks. @@ -1588,13 +1591,13 @@ <para> The first and second fields of - <structname>pci_device_id</structname> struct are the vendor and - device IDs. If you have nothing special to filter the matching - devices, you can use the rest of fields like above. The last - field of <structname>pci_device_id</structname> struct is a + the <structname>pci_device_id</structname> structure are the vendor and + device IDs. If you have no reason to filter the matching + devices, you can leave the remaining fields as above. The last + field of the <structname>pci_device_id</structname> struct contains private data for this entry. You can specify any value here, for - example, to tell the type of different operations per each - device IDs. Such an example is found in intel8x0 driver. + example, to define specific operations for supported device IDs. + Such an example is found in the intel8x0 driver. </para> <para> @@ -1621,10 +1624,10 @@ <para> The <structfield>probe</structfield> and - <structfield>remove</structfield> functions are what we already - defined in - the previous sections. The <structfield>remove</structfield> should - be defined with + <structfield>remove</structfield> functions have already + been defined in the previous sections. + The <structfield>remove</structfield> function should + be defined with the <function>__devexit_p()</function> macro, so that it's not defined for built-in (and non-hot-pluggable) case. The <structfield>name</structfield> @@ -1665,8 +1668,7 @@ <para> Oh, one thing was forgotten. If you have no exported symbols, - you need to declare it on 2.2 or 2.4 kernels (on 2.6 kernels - it's not necessary, though). + you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). <informalexample> <programlisting> @@ -1698,7 +1700,7 @@ <para> For accessing to the PCM layer, you need to include - <filename><sound/pcm.h></filename> above all. In addition, + <filename><sound/pcm.h></filename> first. In addition, <filename><sound/pcm_params.h></filename> might be needed if you access to some functions related with hw_param. </para> @@ -1707,21 +1709,21 @@ Each card device can have up to four pcm instances. A pcm instance corresponds to a pcm device file. The limitation of number of instances comes only from the available bit size of - the linux's device number. Once when 64bit device number is - used, we'll have more available pcm instances. + the Linux's device numbers. Once when 64bit device number is + used, we'll have more pcm instances available. </para> <para> A pcm instance consists of pcm playback and capture streams, and each pcm stream consists of one or more pcm substreams. Some - soundcard supports the multiple-playback function. For example, + soundcards support multiple playback functions. For example, emu10k1 has a PCM playback of 32 stereo substreams. In this case, at each open, a free substream is (usually) automatically chosen and opened. Meanwhile, when only one substream exists and it was - already opened, the succeeding open will result in the blocking - or the error with <constant>EAGAIN</constant> according to the - file open mode. But you don't have to know the detail in your - driver. The PCM middle layer will take all such jobs. + already opened, the successful open will either block + or error with <constant>EAGAIN</constant> according to the + file open mode. But you don't have to care about such details in your + driver. The PCM middle layer will take care of such work. </para> </section> @@ -1944,7 +1946,7 @@ <section id="pcm-interface-constructor"> <title>Constructor</title> <para> - A pcm instance is allocated by <function>snd_pcm_new()</function> + A pcm instance is allocated by the <function>snd_pcm_new()</function> function. It would be better to create a constructor for pcm, namely, @@ -1971,23 +1973,23 @@ </para> <para> - The <function>snd_pcm_new()</function> function takes the four + The <function>snd_pcm_new()</function> function takes four arguments. The first argument is the card pointer to which this pcm is assigned, and the second is the ID string. </para> <para> The third argument (<parameter>index</parameter>, 0 in the - above) is the index of this new pcm. It begins from zero. When - you will create more than one pcm instances, specify the + above) is the index of this new pcm. It begins from zero. If + you create more than one pcm instances, specify the different numbers in this argument. For example, <parameter>index</parameter> = 1 for the second PCM device. </para> <para> The fourth and fifth arguments are the number of substreams - for playback and capture, respectively. Here both 1 are given in - the above example. When no playback or no capture is available, + for playback and capture, respectively. Here 1 is used for + both arguments. When no playback or capture substreams are available, pass 0 to the corresponding argument. </para> @@ -2045,13 +2047,13 @@ </programlisting> </informalexample> - Each of callbacks is explained in the subsection + All the callbacks are described in the <link linkend="pcm-interface-operators"><citetitle> - Operators</citetitle></link>. + Operators</citetitle></link> subsection. </para> <para> - After setting the operators, most likely you'd like to + After setting the operators, you probably will want to pre-allocate the buffer. For the pre-allocation, simply call the following: @@ -2065,8 +2067,8 @@ </programlisting> </informalexample> - It will allocate up to 64kB buffer as default. The details of - buffer management will be described in the later section <link + It will allocate a buffer up to 64kB as default. + Buffer management details will be described in the later section <link linkend="buffer-and-memory"><citetitle>Buffer and Memory Management</citetitle></link>. </para> @@ -2095,13 +2097,13 @@ <para> The destructor for a pcm instance is not always necessary. Since the pcm device will be released by the middle - layer code automatically, you don't have to call destructor + layer code automatically, you don't have to call the destructor explicitly. </para> <para> - The destructor would be necessary when you created some - special records internally and need to release them. In such a + The destructor would be necessary if you created + special records internally and needed to release them. In such a case, set the destructor function to pcm->private_free: @@ -2141,16 +2143,15 @@ When the PCM substream is opened, a PCM runtime instance is allocated and assigned to the substream. This pointer is accessible via <constant>substream->runtime</constant>. - This runtime pointer holds the various information; it holds - the copy of hw_params and sw_params configurations, the buffer - pointers, mmap records, spinlocks, etc. Almost everything you - need for controlling the PCM can be found there. + This runtime pointer holds most information you need + to control the PCM: the copy of hw_params and sw_params configurations, the buffer + pointers, mmap records, spinlocks, etc. </para> <para> The definition of runtime instance is found in - <filename><sound/pcm.h></filename>. Here is the - copy from the file. + <filename><sound/pcm.h></filename>. Here are + the contents of this file: <informalexample> <programlisting> <![CDATA[ @@ -2185,7 +2186,6 @@ struct _snd_pcm_runtime { struct timespec tstamp_mode; /* mmap timestamp is updated */ unsigned int period_step; unsigned int sleep_min; /* min ticks to sleep */ - snd_pcm_uframes_t xfer_align; /* xfer size need to be a multiple */ snd_pcm_uframes_t start_threshold; snd_pcm_uframes_t stop_threshold; snd_pcm_uframes_t silence_threshold; /* Silence filling happens when @@ -2244,7 +2244,7 @@ struct _snd_pcm_runtime { <para> For the operators (callbacks) of each sound driver, most of these records are supposed to be read-only. Only the PCM - middle-layer changes / updates these info. The exceptions are + middle-layer changes / updates them. The exceptions are the hardware description (hw), interrupt callbacks (transfer_ack_xxx), DMA buffer information, and the private data. Besides, if you use the standard buffer allocation @@ -2285,7 +2285,7 @@ struct _snd_pcm_runtime { </para> <para> - Typically, you'll have a hardware descriptor like below: + Typically, you'll have a hardware descriptor as below: <informalexample> <programlisting> <![CDATA[ @@ -2320,10 +2320,10 @@ struct _snd_pcm_runtime { <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you have to specify whether the mmap is supported and which interleaved format is supported. - When the mmap is supported, add + When the is supported, add the <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the hardware supports the interleaved or the non-interleaved - format, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or + formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must be set, respectively. If both are supported, you can set both, too. @@ -2331,7 +2331,7 @@ struct _snd_pcm_runtime { <para> In the above example, <constant>MMAP_VALID</constant> and - <constant>BLOCK_TRANSFER</constant> are specified for OSS mmap + <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap mode. Usually both are set. Of course, <constant>MMAP_VALID</constant> is set only if the mmap is really supported. @@ -2345,11 +2345,11 @@ struct _snd_pcm_runtime { <quote>pause</quote> operation, while the <constant>RESUME</constant> bit means that the pcm supports the full <quote>suspend/resume</quote> operation. - If <constant>PAUSE</constant> flag is set, + If the <constant>PAUSE</constant> flag is set, the <structfield>trigger</structfield> callback below must handle the corresponding (pause push/release) commands. The suspend/resume trigger commands can be defined even without - <constant>RESUME</constant> flag. See <link + the <constant>RESUME</constant> flag. See <link linkend="power-management"><citetitle> Power Management</citetitle></link> section for details. </para> @@ -2382,7 +2382,7 @@ struct _snd_pcm_runtime { <constant>CONTINUOUS</constant> bit additionally. The pre-defined rate bits are provided only for typical rates. If your chip supports unconventional rates, you need to add - <constant>KNOT</constant> bit and set up the hardware + the <constant>KNOT</constant> bit and set up the hardware constraint manually (explained later). </para> </listitem> @@ -2390,8 +2390,8 @@ struct _snd_pcm_runtime { <listitem> <para> <structfield>rate_min</structfield> and - <structfield>rate_max</structfield> define the minimal and - maximal sample rate. This should correspond somehow to + <structfield>rate_max</structfield> define the minimum and + maximum sample rate. This should correspond somehow to <structfield>rates</structfield> bits. </para> </listitem> @@ -2400,7 +2400,7 @@ struct _snd_pcm_runtime { <para> <structfield>channel_min</structfield> and <structfield>channel_max</structfield> - define, as you might already expected, the minimal and maximal + define, as you might already expected, the minimum and maximum number of channels. </para> </listitem> @@ -2408,21 +2408,21 @@ struct _snd_pcm_runtime { <listitem> <para> <structfield>buffer_bytes_max</structfield> defines the - maximal buffer size in bytes. There is no + maximum buffer size in bytes. There is no <structfield>buffer_bytes_min</structfield> field, since - it can be calculated from the minimal period size and the - minimal number of periods. + it can be calculated from the minimum period size and the + minimum number of periods. Meanwhile, <structfield>period_bytes_min</structfield> and - define the minimal and maximal size of the period in bytes. + define the minimum and maximum size of the period in bytes. <structfield>periods_max</structfield> and - <structfield>periods_min</structfield> define the maximal and - minimal number of periods in the buffer. + <structfield>periods_min</structfield> define the maximum and + minimum number of periods in the buffer. </para> <para> - The <quote>period</quote> is a term, that corresponds to - fragment in the OSS world. The period defines the size at - which the PCM interrupt is generated. This size strongly + The <quote>period</quote> is a term that corresponds to + a fragment in the OSS world. The period defines the size at + which a PCM interrupt is generated. This size strongly depends on the hardware. Generally, the smaller period size will give you more interrupts, that is, more controls. @@ -2435,8 +2435,8 @@ struct _snd_pcm_runtime { <listitem> <para> There is also a field <structfield>fifo_size</structfield>. - This specifies the size of the hardware FIFO, but it's not - used currently in the driver nor in the alsa-lib. So, you + This specifies the size of the hardware FIFO, but currently it + is neither used in the driver nor in the alsa-lib. So, you can ignore this field. </para> </listitem> @@ -2450,7 +2450,7 @@ struct _snd_pcm_runtime { Ok, let's go back again to the PCM runtime records. The most frequently referred records in the runtime instance are the PCM configurations. - The PCM configurations are stored on runtime instance + The PCM configurations are stored in the runtime instance after the application sends <type>hw_params</type> data via alsa-lib. There are many fields copied from hw_params and sw_params structs. For example, @@ -2461,11 +2461,11 @@ struct _snd_pcm_runtime { <para> One thing to be noted is that the configured buffer and period - sizes are stored in <quote>frames</quote> in the runtime + sizes are stored in <quote>frames</quote> in the runtime. In the ALSA world, 1 frame = channels * samples-size. For conversion between frames and bytes, you can use the - helper functions, <function>frames_to_bytes()</function> and - <function>bytes_to_frames()</function>. + <function>frames_to_bytes()</function> and + <function>bytes_to_frames()</function> helper functions. <informalexample> <programlisting> <![CDATA[ @@ -2515,7 +2515,7 @@ struct _snd_pcm_runtime { <structfield>dma_area</structfield> is necessary when the buffer is mmapped. If your driver doesn't support mmap, this field is not necessary. <structfield>dma_addr</structfield> - is also not mandatory. You can use + is also optional. You can use <structfield>dma_private</structfield> as you like, too. </para> </section> @@ -2524,14 +2524,14 @@ struct _snd_pcm_runtime { <title>Running Status</title> <para> The running status can be referred via <constant>runtime->status</constant>. - This is the pointer to struct <structname>snd_pcm_mmap_status</structname> + This is the pointer to the struct <structname>snd_pcm_mmap_status</structname> record. For example, you can get the current DMA hardware pointer via <constant>runtime->status->hw_ptr</constant>. </para> <para> The DMA application pointer can be referred via - <constant>runtime->control</constant>, which points + <constant>runtime->control</constant>, which points to the struct <structname>snd_pcm_mmap_control</structname> record. However, accessing directly to this value is not recommended. </para> @@ -2542,14 +2542,14 @@ struct _snd_pcm_runtime { <para> You can allocate a record for the substream and store it in <constant>runtime->private_data</constant>. Usually, this - done in + is done in <link linkend="pcm-interface-operators-open-callback"><citetitle> the open callback</citetitle></link>. Don't mix this with <constant>pcm->private_data</constant>. - The <constant>pcm->private_data</constant> usually points the + The <constant>pcm->private_data</constant> usually points to the chip instance assigned statically at the creation of PCM, while the - <constant>runtime->private_data</constant> points a dynamic - data created at the PCM open callback. + <constant>runtime->private_data</constant> points to a dynamic + data structure created at the PCM open callback. <informalexample> <programlisting> @@ -2579,7 +2579,7 @@ struct _snd_pcm_runtime { <para> The field <structfield>transfer_ack_begin</structfield> and <structfield>transfer_ack_end</structfield> are called at - the beginning and the end of + the beginning and at the end of <function>snd_pcm_period_elapsed()</function>, respectively. </para> </section> @@ -2589,17 +2589,18 @@ struct _snd_pcm_runtime { <section id="pcm-interface-operators"> <title>Operators</title> <para> - OK, now let me explain the detail of each pcm callback + OK, now let me give details about each pcm callback (<parameter>ops</parameter>). In general, every callback must - return 0 if successful, or a negative number with the error - number such as <constant>-EINVAL</constant> at any - error. + return 0 if successful, or a negative error number + such as <constant>-EINVAL</constant>. To choose an appropriate + error number, it is advised to check what value other parts of + the kernel return when the same kind of request fails. </para> <para> The callback function takes at least the argument with - <structname>snd_pcm_substream</structname> pointer. For retrieving the - chip record from the given substream instance, you can use the + <structname>snd_pcm_substream</structname> pointer. To retrieve + the chip record from the given substream instance, you can use the following macro. <informalexample> @@ -2616,7 +2617,7 @@ struct _snd_pcm_runtime { The macro reads <constant>substream->private_data</constant>, which is a copy of <constant>pcm->private_data</constant>. You can override the former if you need to assign different data - records per PCM substream. For example, cmi8330 driver assigns + records per PCM substream. For example, the cmi8330 driver assigns different private_data for playback and capture directions, because it uses two different codecs (SB- and AD-compatible) for different directions. @@ -2709,7 +2710,7 @@ struct _snd_pcm_runtime { <section id="pcm-interface-operators-ioctl-callback"> <title>ioctl callback</title> <para> - This is used for any special action to pcm ioctls. But + This is used for any special call to pcm ioctls. But usually you can pass a generic ioctl callback, <function>snd_pcm_lib_ioctl</function>. </para> @@ -2726,9 +2727,6 @@ struct _snd_pcm_runtime { ]]> </programlisting> </informalexample> - - This and <structfield>hw_free</structfield> callbacks exist - only on ALSA 0.9.x. </para> <para> @@ -2740,13 +2738,13 @@ struct _snd_pcm_runtime { </para> <para> - Many hardware set-up should be done in this callback, + Many hardware setups should be done in this callback, including the allocation of buffers. </para> <para> Parameters to be initialized are retrieved by - <function>params_xxx()</function> macros. For allocating a + <function>params_xxx()</function> macros. To allocate buffer, you can call a helper function, <informalexample> @@ -2772,8 +2770,8 @@ struct _snd_pcm_runtime { </para> <para> - Thus, you need to take care not to allocate the same buffers - many times, which will lead to memory leak! Calling the + Thus, you need to be careful not to allocate the same buffers + many times, which will lead to memory leaks! Calling the helper function above many times is OK. It will release the previous buffer automatically when it was already allocated. </para> @@ -2782,7 +2780,7 @@ struct _snd_pcm_runtime { Another note is that this callback is non-atomic (schedulable). This is important, because the <structfield>trigger</structfield> callback - is atomic (non-schedulable). That is, mutex or any + is atomic (non-schedulable). That is, mutexes or any schedule-related functions are not available in <structfield>trigger</structfield> callback. Please see the subsection @@ -2843,15 +2841,15 @@ struct _snd_pcm_runtime { <quote>prepared</quote>. You can set the format type, sample rate, etc. here. The difference from <structfield>hw_params</structfield> is that the - <structfield>prepare</structfield> callback will be called at each + <structfield>prepare</structfield> callback will be called each time <function>snd_pcm_prepare()</function> is called, i.e. when - recovered after underruns, etc. + recovering after underruns, etc. </para> <para> - Note that this callback became non-atomic since the recent version. - You can use schedule-related functions safely in this callback now. + Note that this callback is now non-atomic. + You can use schedule-related functions safely in this callback. </para> <para> @@ -2871,7 +2869,7 @@ struct _snd_pcm_runtime { <para> Be careful that this callback will be called many times at - each set up, too. + each setup, too. </para> </section> @@ -2893,7 +2891,7 @@ struct _snd_pcm_runtime { Which action is specified in the second argument, <constant>SNDRV_PCM_TRIGGER_XXX</constant> in <filename><sound/pcm.h></filename>. At least, - <constant>START</constant> and <constant>STOP</constant> + the <constant>START</constant> and <constant>STOP</constant> commands must be defined in this callback. <informalexample> @@ -2915,8 +2913,8 @@ struct _snd_pcm_runtime { </para> <para> - When the pcm supports the pause operation (given in info - field of the hardware table), <constant>PAUSE_PUSE</constant> + When the pcm supports the pause operation (given in the info + field of the hardware table), the <constant>PAUSE_PUSE</constant> and <constant>PAUSE_RELEASE</constant> commands must be handled here, too. The former is the command to pause the pcm, and the latter to restart the pcm again. @@ -2925,21 +2923,21 @@ struct _snd_pcm_runtime { <para> When the pcm supports the suspend/resume operation, regardless of full or partial suspend/resume support, - <constant>SUSPEND</constant> and <constant>RESUME</constant> + the <constant>SUSPEND</constant> and <constant>RESUME</constant> commands must be handled, too. These commands are issued when the power-management status is changed. Obviously, the <constant>SUSPEND</constant> and - <constant>RESUME</constant> - do suspend and resume of the pcm substream, and usually, they - are identical with <constant>STOP</constant> and + <constant>RESUME</constant> commands + suspend and resume the pcm substream, and usually, they + are identical to the <constant>STOP</constant> and <constant>START</constant> commands, respectively. - See <link linkend="power-management"><citetitle> + See the <link linkend="power-management"><citetitle> Power Management</citetitle></link> section for details. </para> <para> As mentioned, this callback is atomic. You cannot call - the function going to sleep. + functions which may sleep. The trigger callback should be as minimal as possible, just really triggering the DMA. The other stuff should be initialized hw_params and prepare callbacks properly @@ -2960,8 +2958,8 @@ struct _snd_pcm_runtime { This callback is called when the PCM middle layer inquires the current hardware position on the buffer. The position must - be returned in frames (which was in bytes on ALSA 0.5.x), - ranged from 0 to buffer_size - 1. + be returned in frames, + ranging from 0 to buffer_size - 1. </para> <para> @@ -2983,7 +2981,7 @@ struct _snd_pcm_runtime { <para> These callbacks are not mandatory, and can be omitted in most cases. These callbacks are used when the hardware buffer - cannot be on the normal memory space. Some chips have their + cannot be in the normal memory space. Some chips have their own buffer on the hardware which is not mappable. In such a case, you have to transfer the data manually from the memory buffer to the hardware buffer. Or, if the buffer is @@ -3018,8 +3016,8 @@ struct _snd_pcm_runtime { <title>page callback</title> <para> - This callback is also not mandatory. This callback is used - mainly for the non-contiguous buffer. The mmap calls this + This callback is optional too. This callback is used + mainly for non-contiguous buffers. The mmap calls this callback to get the page address. Some examples will be explained in the later section <link linkend="buffer-and-memory"><citetitle>Buffer and Memory @@ -3035,7 +3033,7 @@ struct _snd_pcm_runtime { role of PCM interrupt handler in the sound driver is to update the buffer position and to tell the PCM middle layer when the buffer position goes across the prescribed period size. To - inform this, call <function>snd_pcm_period_elapsed()</function> + inform this, call the <function>snd_pcm_period_elapsed()</function> function. </para> @@ -3072,7 +3070,7 @@ struct _snd_pcm_runtime { </para> <para> - A typical coding would be like: + Typical code would be like: <example> <title>Interrupt Handler Case #1</title> @@ -3101,21 +3099,21 @@ struct _snd_pcm_runtime { </section> <section id="pcm-interface-interrupt-handler-timer"> - <title>High-frequent timer interrupts</title> + <title>High frequency timer interrupts</title> <para> - This is the case when the hardware doesn't generate interrupts - at the period boundary but do timer-interrupts at the fixed + This happense when the hardware doesn't generate interrupts + at the period boundary but issues timer interrupts at a fixed timer rate (e.g. es1968 or ymfpci drivers). In this case, you need to check the current hardware - position and accumulates the processed sample length at each - interrupt. When the accumulated size overcomes the period + position and accumulate the processed sample length at each + interrupt. When the accumulated size exceeds the period size, call <function>snd_pcm_period_elapsed()</function> and reset the accumulator. </para> <para> - A typical coding would be like the following. + Typical code would be like the following. <example> <title>Interrupt Handler Case #2</title> @@ -3178,32 +3176,33 @@ struct _snd_pcm_runtime { <section id="pcm-interface-atomicity"> <title>Atomicity</title> <para> - One of the most important (and thus difficult to debug) problem - on the kernel programming is the race condition. - On linux kernel, usually it's solved via spin-locks or - semaphores. In general, if the race condition may - happen in the interrupt handler, it's handled as atomic, and you - have to use spinlock for protecting the critical session. If it - never happens in the interrupt and it may take relatively long - time, you should use semaphore. + One of the most important (and thus difficult to debug) problems + in kernel programming are race conditions. + In the Linux kernel, they are usually avoided via spin-locks, mutexes + or semaphores. In general, if a race condition can happen + in an interrupt handler, it has to be managed atomically, and you + have to use a spinlock to protect the critical session. If the + critical section is not in interrupt handler code and + if taking a relatively long time to execute is acceptable, you + should use mutexes or semaphores instead. </para> <para> As already seen, some pcm callbacks are atomic and some are - not. For example, <parameter>hw_params</parameter> callback is + not. For example, the <parameter>hw_params</parameter> callback is non-atomic, while <parameter>trigger</parameter> callback is atomic. This means, the latter is called already in a spinlock held by the PCM middle layer. Please take this atomicity into - account when you use a spinlock or a semaphore in the callbacks. + account when you choose a locking scheme in the callbacks. </para> <para> In the atomic callbacks, you cannot use functions which may call <function>schedule</function> or go to - <function>sleep</function>. The semaphore and mutex do sleep, + <function>sleep</function>. Semaphores and mutexes can sleep, and hence they cannot be used inside the atomic callbacks (e.g. <parameter>trigger</parameter> callback). - For taking a certain delay in such a callback, please use + To implement some delay in such a callback, please use <function>udelay()</function> or <function>mdelay()</function>. </para> @@ -3257,7 +3256,7 @@ struct _snd_pcm_runtime { <para> There are many different constraints. - Look in <filename>sound/pcm.h</filename> for a complete list. + Look at <filename>sound/pcm.h</filename> for a complete list. You can even define your own constraint rules. For example, let's suppose my_chip can manage a substream of 1 channel if and only if the format is S16_LE, otherwise it supports any format @@ -3346,7 +3345,7 @@ struct _snd_pcm_runtime { </para> <para> - I won't explain more details here, rather I + I won't give more details here, rather I would like to say, <quote>Luke, use the source.</quote> </para> </section> @@ -3364,10 +3363,9 @@ struct _snd_pcm_runtime { <title>General</title> <para> The control interface is used widely for many switches, - sliders, etc. which are accessed from the user-space. Its most - important use is the mixer interface. In other words, on ALSA - 0.9.x, all the mixer stuff is implemented on the control kernel - API (while there was an independent mixer kernel API on 0.5.x). + sliders, etc. which are accessed from user-space. Its most + important use is the mixer interface. In other words, since ALSA + 0.9.x, all the mixer stuff is implemented on the control kernel API. </para> <para> @@ -3379,14 +3377,15 @@ struct _snd_pcm_runtime { <para> The control API is defined in <filename><sound/control.h></filename>. - Include this file if you add your own controls. + Include this file if you want to add your own controls. </para> </section> <section id="control-interface-definition"> <title>Definition of Controls</title> <para> - For creating a new control, you need to define the three + To create a new control, you need to define the + following three callbacks: <structfield>info</structfield>, <structfield>get</structfield> and <structfield>put</structfield>. Then, define a @@ -3414,13 +3413,13 @@ struct _snd_pcm_runtime { <para> Most likely the control is created via <function>snd_ctl_new1()</function>, and in such a case, you can - add <parameter>__devinitdata</parameter> prefix to the - definition like above. + add the <parameter>__devinitdata</parameter> prefix to the + definition as above. </para> <para> - The <structfield>iface</structfield> field specifies the type of - the control, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which + The <structfield>iface</structfield> field specifies the control + type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which is usually <constant>MIXER</constant>. Use <constant>CARD</constant> for global controls that are not logically part of the mixer. @@ -3435,12 +3434,11 @@ struct _snd_pcm_runtime { <para> The <structfield>name</structfield> is the name identifier - string. On ALSA 0.9.x, the control name is very important, + string. Since ALSA 0.9.x, the control name is very important, because its role is classified from its name. There are pre-defined standard control names. The details are described in - the subsection - <link linkend="control-interface-control-names"><citetitle> - Control Names</citetitle></link>. + the <link linkend="control-interface-control-names"><citetitle> + Control Names</citetitle></link> subsection. </para> <para> @@ -3456,15 +3454,15 @@ struct _snd_pcm_runtime { The <structfield>access</structfield> field contains the access type of this control. Give the combination of bit masks, <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there. - The detailed will be explained in the subsection - <link linkend="control-interface-access-flags"><citetitle> - Access Flags</citetitle></link>. + The details will be explained in + the <link linkend="control-interface-access-flags"><citetitle> + Access Flags</citetitle></link> subsection. </para> <para> The <structfield>private_value</structfield> field contains an arbitrary long integer value for this record. When using - generic <structfield>info</structfield>, + the generic <structfield>info</structfield>, <structfield>get</structfield> and <structfield>put</structfield> callbacks, you can pass a value through this field. If several small numbers are necessary, you can @@ -3489,7 +3487,7 @@ struct _snd_pcm_runtime { <section id="control-interface-control-names"> <title>Control Names</title> <para> - There are some standards for defining the control names. A + There are some standards to define the control names. A control is usually defined from the three parts as <quote>SOURCE DIRECTION FUNCTION</quote>. </para> @@ -3497,7 +3495,7 @@ struct _snd_pcm_runtime { <para> The first, <constant>SOURCE</constant>, specifies the source of the control, and is a string such as <quote>Master</quote>, - <quote>PCM</quote>, <quote>CD</quote> or + <quote>PCM</quote>, <quote>CD</quote> and <quote>Line</quote>. There are many pre-defined sources. </para> @@ -3575,22 +3573,22 @@ struct _snd_pcm_runtime { <title>Access Flags</title> <para> - The access flag is the bit-flags which specifies the access type + The access flag is the bitmask which specifies the access type of the given control. The default access type is <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, which means both read and write are allowed to this control. When the access flag is omitted (i.e. = 0), it is - regarded as <constant>READWRITE</constant> access as default. + considered as <constant>READWRITE</constant> access as default. </para> <para> When the control is read-only, pass <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead. In this case, you don't have to define - <structfield>put</structfield> callback. + the <structfield>put</structfield> callback. Similarly, when the control is write-only (although it's a rare - case), you can use <constant>WRITE</constant> flag instead, and - you don't need <structfield>get</structfield> callback. + case), you can use the <constant>WRITE</constant> flag instead, and + you don't need the <structfield>get</structfield> callback. </para> <para> @@ -3598,15 +3596,15 @@ struct _snd_pcm_runtime { <constant>VOLATILE</constant> flag should be given. This means that the control may be changed without <link linkend="control-interface-change-notification"><citetitle> - notification</citetitle></link>. Applications should poll such + notification</citetitle></link>. Applications should poll such a control constantly. </para> <para> When the control is inactive, set - <constant>INACTIVE</constant> flag, too. + the <constant>INACTIVE</constant> flag, too. There are <constant>LOCK</constant> and - <constant>OWNER</constant> flags for changing the write + <constant>OWNER</constant> flags to change the write permissions. </para> @@ -3619,10 +3617,10 @@ struct _snd_pcm_runtime { <title>info callback</title> <para> The <structfield>info</structfield> callback is used to get - the detailed information of this control. This must store the + detailed information on this control. This must store the values of the given struct <structname>snd_ctl_elem_info</structname> object. For example, for a boolean control with a single - element will be: + element: <example> <title>Example of info callback</title> @@ -3653,7 +3651,7 @@ struct _snd_pcm_runtime { volume would have count = 2. The <structfield>value</structfield> field is a union, and the values stored are depending on the type. The boolean and - integer are identical. + integer types are identical. </para> <para> @@ -3684,7 +3682,7 @@ struct _snd_pcm_runtime { </para> <para> - Some common info callbacks are prepared for easy use: + Some common info callbacks are available for your convenience: <function>snd_ctl_boolean_mono_info()</function> and <function>snd_ctl_boolean_stereo_info()</function>. Obviously, the former is an info callback for a mono channel @@ -3699,7 +3697,7 @@ struct _snd_pcm_runtime { <para> This callback is used to read the current value of the - control and to return to the user-space. + control and to return to user-space. </para> <para> @@ -3722,11 +3720,11 @@ struct _snd_pcm_runtime { </para> <para> - The <structfield>value</structfield> field is depending on - the type of control as well as on info callback. For example, + The <structfield>value</structfield> field depends on + the type of control as well as on the info callback. For example, the sb driver uses this field to store the register offset, the bit-shift and the bit-mask. The - <structfield>private_value</structfield> is set like + <structfield>private_value</structfield> field is set as follows: <informalexample> <programlisting> <![CDATA[ @@ -3752,7 +3750,8 @@ struct _snd_pcm_runtime { </para> <para> - In <structfield>get</structfield> callback, you have to fill all the elements if the + In the <structfield>get</structfield> callback, + you have to fill all the elements if the control has more than one elements, i.e. <structfield>count</structfield> > 1. In the example above, we filled only one element @@ -3765,7 +3764,7 @@ struct _snd_pcm_runtime { <title>put callback</title> <para> - This callback is used to write a value from the user-space. + This callback is used to write a value from user-space. </para> <para> @@ -3799,7 +3798,7 @@ struct _snd_pcm_runtime { </para> <para> - Like <structfield>get</structfield> callback, + As in the <structfield>get</structfield> callback, when the control has more than one elements, all elements must be evaluated in this callback, too. </para> @@ -3817,7 +3816,7 @@ struct _snd_pcm_runtime { <title>Constructor</title> <para> When everything is ready, finally we can create a new - control. For creating a control, there are two functions to be + control. To create a control, there are two functions to be called, <function>snd_ctl_new1()</function> and <function>snd_ctl_add()</function>. </para> @@ -3839,14 +3838,14 @@ struct _snd_pcm_runtime { struct <structname>snd_kcontrol_new</structname> object defined above, and chip is the object pointer to be passed to kcontrol->private_data - which can be referred in callbacks. + which can be referred to in callbacks. </para> <para> <function>snd_ctl_new1()</function> allocates a new <structname>snd_kcontrol</structname> instance (that's why the definition of <parameter>my_control</parameter> can be with - <parameter>__devinitdata</parameter> + the <parameter>__devinitdata</parameter> prefix), and <function>snd_ctl_add</function> assigns the given control component to the card. </para> @@ -3941,7 +3940,7 @@ struct _snd_pcm_runtime { <title>General</title> <para> The ALSA AC97 codec layer is a well-defined one, and you don't - have to write many codes to control it. Only low-level control + have to write much code to control it. Only low-level control routines are necessary. The AC97 codec API is defined in <filename><sound/ac97_codec.h></filename>. </para> @@ -4004,7 +4003,7 @@ struct _snd_pcm_runtime { <section id="api-ac97-constructor"> <title>Constructor</title> <para> - For creating an ac97 instance, first call <function>snd_ac97_bus</function> + To create an ac97 instance, first call <function>snd_ac97_bus</function> with an <type>ac97_bus_ops_t</type> record with callback functions. <informalexample> @@ -4042,12 +4041,12 @@ struct _snd_pcm_runtime { </programlisting> </informalexample> - where chip->ac97 is the pointer of a newly created + where chip->ac97 is a pointer to a newly created <type>ac97_t</type> instance. In this case, the chip pointer is set as the private data, so that the read/write callback functions can refer to this chip instance. This instance is not necessarily stored in the chip - record. When you need to change the register values from the + record. If you need to change the register values from the driver, or need the suspend/resume of ac97 codecs, keep this pointer to pass to the corresponding functions. </para> @@ -4098,7 +4097,7 @@ struct _snd_pcm_runtime { </para> <para> - These callbacks are non-atomic like the callbacks of control API. + These callbacks are non-atomic like the control API callbacks. </para> <para> @@ -4110,14 +4109,14 @@ struct _snd_pcm_runtime { <para> The <structfield>reset</structfield> callback is used to reset - the codec. If the chip requires a special way of reset, you can + the codec. If the chip requires a special kind of reset, you can define this callback. </para> <para> - The <structfield>wait</structfield> callback is used for a - certain wait at the standard initialization of the codec. If the - chip requires the extra wait-time, define this callback. + The <structfield>wait</structfield> callback is used to + add some waiting time in the standard initialization of the codec. If the + chip requires the extra waiting time, define this callback. </para> <para> @@ -4172,7 +4171,7 @@ struct _snd_pcm_runtime { <para> <function>snd_ac97_update_bits()</function> is used to update - some bits of the given register. + some bits in the given register. <informalexample> <programlisting> @@ -4185,7 +4184,7 @@ struct _snd_pcm_runtime { <para> Also, there is a function to change the sample rate (of a - certain register such as + given register such as <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or DRA is supported by the codec: <function>snd_ac97_set_rate()</function>. @@ -4200,11 +4199,11 @@ struct _snd_pcm_runtime { </para> <para> - The following registers are available for setting the rate: + The following registers are available to set the rate: <constant>AC97_PCM_MIC_ADC_RATE</constant>, <constant>AC97_PCM_FRONT_DAC_RATE</constant>, <constant>AC97_PCM_LR_ADC_RATE</constant>, - <constant>AC97_SPDIF</constant>. When the + <constant>AC97_SPDIF</constant>. When <constant>AC97_SPDIF</constant> is specified, the register is not really changed but the corresponding IEC958 status bits will be updated. @@ -4214,12 +4213,11 @@ struct _snd_pcm_runtime { <section id="api-ac97-clock-adjustment"> <title>Clock Adjustment</title> <para> - On some chip, the clock of the codec isn't 48000 but using a + In some chips, the clock of the codec isn't 48000 but using a PCI clock (to save a quartz!). In this case, change the field bus->clock to the corresponding value. For example, intel8x0 - and es1968 drivers have the auto-measurement function of the - clock. + and es1968 drivers have their own function to read from the clock. </para> </section> @@ -4239,15 +4237,13 @@ struct _snd_pcm_runtime { When there are several codecs on the same card, you need to call <function>snd_ac97_mixer()</function> multiple times with ac97.num=1 or greater. The <structfield>num</structfield> field - specifies the codec - number. + specifies the codec number. </para> <para> - If you have set up multiple codecs, you need to either write + If you set up multiple codecs, you either need to write different callbacks for each codec or check - ac97->num in the - callback routines. + ac97->num in the callback routines. </para> </section> @@ -4271,7 +4267,7 @@ struct _snd_pcm_runtime { </para> <para> - Some soundchips have similar but a little bit different + Some soundchips have a similar but slightly different implementation of mpu401 stuff. For example, emu10k1 has its own mpu401 routines. </para> @@ -4280,7 +4276,7 @@ struct _snd_pcm_runtime { <section id="midi-interface-constructor"> <title>Constructor</title> <para> - For creating a rawmidi object, call + To create a rawmidi object, call <function>snd_mpu401_uart_new()</function>. <informalexample> @@ -4307,25 +4303,24 @@ struct _snd_pcm_runtime { </para> <para> - The 4th argument is the i/o port address. Many - backward-compatible MPU401 has an i/o port such as 0x330. Or, it - might be a part of its own PCI i/o region. It depends on the + The 4th argument is the I/O port address. Many + backward-compatible MPU401 have an I/O port such as 0x330. Or, it + might be a part of its own PCI I/O region. It depends on the chip design. </para> <para> - The 5th argument is bitflags for additional information. - When the i/o port address above is a part of the PCI i/o - region, the MPU401 i/o port might have been already allocated + The 5th argument is a bitflag for additional information. + When the I/O port address above is part of the PCI I/O + region, the MPU401 I/O port might have been already allocated (reserved) by the driver itself. In such a case, pass a bit flag <constant>MPU401_INFO_INTEGRATED</constant>, - and - the mpu401-uart layer will allocate the i/o ports by itself. + and the mpu401-uart layer will allocate the I/O ports by itself. </para> <para> When the controller supports only the input or output MIDI stream, - pass <constant>MPU401_INFO_INPUT</constant> or + pass the <constant>MPU401_INFO_INPUT</constant> or <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. Then the rawmidi instance is created as a single stream. </para> @@ -4333,7 +4328,7 @@ struct _snd_pcm_runtime { <para> <constant>MPU401_INFO_MMIO</constant> bitflag is used to change the access method to MMIO (via readb and writeb) instead of - iob and outb. In this case, you have to pass the iomapped address + iob and outb. In this case, you have to pass the iomapped address to <function>snd_mpu401_uart_new()</function>. </para> @@ -4341,7 +4336,7 @@ struct _snd_pcm_runtime { When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output stream isn't checked in the default interrupt handler. The driver needs to call <function>snd_mpu401_uart_interrupt_tx()</function> - by itself to start processing the output stream in irq handler. + by itself to start processing the output stream in the irq handler. </para> <para> @@ -4381,7 +4376,7 @@ struct _snd_pcm_runtime { (<parameter>irq_flags</parameter>). Otherwise, pass the flags for irq allocation (<constant>SA_XXX</constant> bits) to it, and the irq will be - reserved by the mpu401-uart layer. If the card doesn't generates + reserved by the mpu401-uart layer. If the card doesn't generate UART interrupts, pass -1 as the irq number. Then a timer interrupt will be invoked for polling. </para> @@ -4392,8 +4387,8 @@ struct _snd_pcm_runtime { <para> When the interrupt is allocated in <function>snd_mpu401_uart_new()</function>, the private - interrupt handler is used, hence you don't have to do nothing - else than creating the mpu401 stuff. Otherwise, you have to call + interrupt handler is used, hence you don't have anything else to do + than creating the mpu401 stuff. Otherwise, you have to call <function>snd_mpu401_uart_interrupt()</function> explicitly when a UART interrupt is invoked and checked in your own interrupt handler. @@ -4480,8 +4475,8 @@ struct _snd_pcm_runtime { <para> The fourth and fifth arguments are the number of output and - input substreams, respectively, of this device. (A substream is - the equivalent of a MIDI port.) + input substreams, respectively, of this device (a substream is + the equivalent of a MIDI port). </para> <para> @@ -4498,7 +4493,7 @@ struct _snd_pcm_runtime { <para> After the rawmidi device is created, you need to set the operators (callbacks) for each substream. There are helper - functions to set the operators for all substream of a device: + functions to set the operators for all the substreams of a device: <informalexample> <programlisting> <![CDATA[ @@ -4528,8 +4523,8 @@ struct _snd_pcm_runtime { </para> <para> - If there is more than one substream, you should give each one a - unique name: + If there are more than one substream, you should give a + unique name to each of them: <informalexample> <programlisting> <![CDATA[ @@ -4550,7 +4545,7 @@ struct _snd_pcm_runtime { <title>Callbacks</title> <para> - In all callbacks, the private data that you've set for the + In all the callbacks, the private data that you've set for the rawmidi device can be accessed as substream->rmidi->private_data. <!-- <code> isn't available before DocBook 4.3 --> @@ -4583,8 +4578,8 @@ struct _snd_pcm_runtime { <para> This is called when a substream is opened. - You can initialize the hardware here, but you should not yet - start transmitting/receiving data. + You can initialize the hardware here, but you shouldn't + start transmitting/receiving data yet. </para> </section> @@ -4632,9 +4627,9 @@ struct _snd_pcm_runtime { To read data from the buffer, call <function>snd_rawmidi_transmit_peek</function>. It will return the number of bytes that have been read; this will be - less than the number of bytes requested when there is no more + less than the number of bytes requested when there are no more data in the buffer. - After the data has been transmitted successfully, call + After the data have been transmitted successfully, call <function>snd_rawmidi_transmit_ack</function> to remove the data from the substream buffer: <informalexample> @@ -4655,7 +4650,7 @@ struct _snd_pcm_runtime { <para> If you know beforehand that the hardware will accept data, you can use the <function>snd_rawmidi_transmit</function> function - which reads some data and removes it from the buffer at once: + which reads some data and removes them from the buffer at once: <informalexample> <programlisting> <![CDATA[ @@ -4749,13 +4744,13 @@ struct _snd_pcm_runtime { <para> This is only used with output substreams. This function should wait - until all data read from the substream buffer has been transmitted. + until all data read from the substream buffer have been transmitted. This ensures that the device can be closed and the driver unloaded without losing data. </para> <para> - This callback is optional. If you do not set + This callback is optional. If you do not set <structfield>drain</structfield> in the struct snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds instead. @@ -4775,24 +4770,24 @@ struct _snd_pcm_runtime { <section id="misc-devices-opl3"> <title>FM OPL3</title> <para> - The FM OPL3 is still used on many chips (mainly for backward + The FM OPL3 is still used in many chips (mainly for backward compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API is defined in <filename><sound/opl3.h></filename>. </para> <para> - FM registers can be directly accessed through direct-FM API, + FM registers can be directly accessed through the direct-FM API, defined in <filename><sound/asound_fm.h></filename>. In ALSA native mode, FM registers are accessed through - Hardware-Dependant Device direct-FM extension API, whereas in - OSS compatible mode, FM registers can be accessed with OSS - direct-FM compatible API on <filename>/dev/dmfmX</filename> device. + the Hardware-Dependant Device direct-FM extension API, whereas in + OSS compatible mode, FM registers can be accessed with the OSS + direct-FM compatible API in <filename>/dev/dmfmX</filename> device. </para> <para> - For creating the OPL3 component, you have two functions to - call. The first one is a constructor for <type>opl3_t</type> + To create the OPL3 component, you have two functions to + call. The first one is a constructor for the <type>opl3_t</type> instance. <informalexample> @@ -4819,12 +4814,12 @@ struct _snd_pcm_runtime { <para> When the left and right ports have been already allocated by the card driver, pass non-zero to the fifth argument - (<parameter>integrated</parameter>). Otherwise, opl3 module will + (<parameter>integrated</parameter>). Otherwise, the opl3 module will allocate the specified ports by itself. </para> <para> - When the accessing to the hardware requires special method + When the accessing the hardware requires special method instead of the standard I/O access, you can create opl3 instance separately with <function>snd_opl3_new()</function>. @@ -4845,13 +4840,13 @@ struct _snd_pcm_runtime { access function, the private data and the destructor. The l_port and r_port are not necessarily set. Only the command must be set properly. You can retrieve the data - from opl3->private_data field. + from the opl3->private_data field. </para> <para> After creating the opl3 instance via <function>snd_opl3_new()</function>, call <function>snd_opl3_init()</function> to initialize the chip to the - proper state. Note that <function>snd_opl3_create()</function> always + proper state. Note that <function>snd_opl3_create()</function> always calls it internally. </para> @@ -4884,7 +4879,7 @@ struct _snd_pcm_runtime { <section id="misc-devices-hardware-dependent"> <title>Hardware-Dependent Devices</title> <para> - Some chips need the access from the user-space for special + Some chips need user-space access for special controls or for loading the micro code. In such a case, you can create a hwdep (hardware-dependent) device. The hwdep API is defined in <filename><sound/hwdep.h></filename>. You can @@ -4893,7 +4888,7 @@ struct _snd_pcm_runtime { </para> <para> - Creation of the <type>hwdep</type> instance is done via + The creation of the <type>hwdep</type> instance is done via <function>snd_hwdep_new()</function>. <informalexample> @@ -4912,8 +4907,8 @@ struct _snd_pcm_runtime { You can then pass any pointer value to the <parameter>private_data</parameter>. If you assign a private data, you should define the - destructor, too. The destructor function is set to - <structfield>private_free</structfield> field. + destructor, too. The destructor function is set in + the <structfield>private_free</structfield> field. <informalexample> <programlisting> @@ -4925,7 +4920,7 @@ struct _snd_pcm_runtime { </programlisting> </informalexample> - and the implementation of destructor would be: + and the implementation of the destructor would be: <informalexample> <programlisting> @@ -4943,7 +4938,7 @@ struct _snd_pcm_runtime { <para> The arbitrary file operations can be defined for this instance. The file operators are defined in - <parameter>ops</parameter> table. For example, assume that + the <parameter>ops</parameter> table. For example, assume that this chip needs an ioctl. <informalexample> @@ -4964,7 +4959,7 @@ struct _snd_pcm_runtime { <title>IEC958 (S/PDIF)</title> <para> Usually the controls for IEC958 devices are implemented via - control interface. There is a macro to compose a name string for + the control interface. There is a macro to compose a name string for IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function> defined in <filename><include/asound.h></filename>. </para> @@ -4973,7 +4968,7 @@ struct _snd_pcm_runtime { There are some standard controls for IEC958 status bits. These controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>, and the size of element is fixed as 4 bytes array - (value.iec958.status[x]). For <structfield>info</structfield> + (value.iec958.status[x]). For the <structfield>info</structfield> callback, you don't specify the value field for this type (the count field must be set, though). @@ -5001,7 +4996,7 @@ struct _snd_pcm_runtime { enable/disable or to set the raw bit mode. The implementation will depend on the chip, but the control should be named as <quote>IEC958 xxx</quote>, preferably using - <function>SNDRV_CTL_NAME_IEC958()</function> macro. + the <function>SNDRV_CTL_NAME_IEC958()</function> macro. </para> <para> @@ -5036,12 +5031,12 @@ struct _snd_pcm_runtime { The allocation of pages with fallback is <function>snd_malloc_xxx_pages_fallback()</function>. This function tries to allocate the specified pages but if the pages - are not available, it tries to reduce the page sizes until the + are not available, it tries to reduce the page sizes until enough space is found. </para> <para> - For releasing the space, call + The release the pages, call <function>snd_free_xxx_pages()</function> function. </para> @@ -5050,8 +5045,8 @@ struct _snd_pcm_runtime { a large contiguous physical space at the time the module is loaded for the later use. This is called <quote>pre-allocation</quote>. - As already written, you can call the following function at the - construction of pcm instance (in the case of PCI bus). + As already written, you can call the following function at + pcm instance construction time (in the case of PCI bus). <informalexample> <programlisting> @@ -5063,34 +5058,34 @@ struct _snd_pcm_runtime { </informalexample> where <parameter>size</parameter> is the byte size to be - pre-allocated and the <parameter>max</parameter> is the maximal - size to be changed via <filename>prealloc</filename> proc file. - The allocator will try to get as large area as possible + pre-allocated and the <parameter>max</parameter> is the maximum + size to be changed via the <filename>prealloc</filename> proc file. + The allocator will try to get an area as large as possible within the given size. </para> <para> The second argument (type) and the third argument (device pointer) are dependent on the bus. - In the case of ISA bus, pass <function>snd_dma_isa_data()</function> + In the case of the ISA bus, pass <function>snd_dma_isa_data()</function> as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type. For the continuous buffer unrelated to the bus can be pre-allocated with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, - whereh <constant>GFP_KERNEL</constant> is the kernel allocation flag to + where <constant>GFP_KERNEL</constant> is the kernel allocation flag to use. For the SBUS, <constant>SNDRV_DMA_TYPE_SBUS</constant> and <function>snd_dma_sbus_data(sbus_dev)</function> are used instead. For the PCI scatter-gather buffers, use <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with <function>snd_dma_pci_data(pci)</function> - (see the section + (see the <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers - </citetitle></link>). + </citetitle></link> section). </para> <para> - Once when the buffer is pre-allocated, you can use the - allocator in the <structfield>hw_params</structfield> callback + Once the buffer is pre-allocated, you can use the + allocator in the <structfield>hw_params</structfield> callback: <informalexample> <programlisting> @@ -5116,8 +5111,8 @@ struct _snd_pcm_runtime { </para> <para> - The first case works fine if the external hardware buffer is enough - large. This method doesn't need any extra buffers and thus is + The first case works fine if the external hardware buffer is large + enough. This method doesn't need any extra buffers and thus is more effective. You need to define the <structfield>copy</structfield> and <structfield>silence</structfield> callbacks for @@ -5127,25 +5122,25 @@ struct _snd_pcm_runtime { </para> <para> - The second case allows the mmap of the buffer, although you have - to handle an interrupt or a tasklet for transferring the data + The second case allows for mmap on the buffer, although you have + to handle an interrupt or a tasklet to transfer the data from the intermediate buffer to the hardware buffer. You can find an - example in vxpocket driver. + example in the vxpocket driver. </para> <para> - Another case is that the chip uses a PCI memory-map + Another case is when the chip uses a PCI memory-map region for the buffer instead of the host memory. In this case, - mmap is available only on certain architectures like intel. In - non-mmap mode, the data cannot be transferred as the normal - way. Thus you need to define <structfield>copy</structfield> and - <structfield>silence</structfield> callbacks as well + mmap is available only on certain architectures like the Intel one. + In non-mmap mode, the data cannot be transferred as in the normal + way. Thus you need to define the <structfield>copy</structfield> and + <structfield>silence</structfield> callbacks as well, as in the cases above. The examples are found in <filename>rme32.c</filename> and <filename>rme96.c</filename>. </para> <para> - The implementation of <structfield>copy</structfield> and + The implementation of the <structfield>copy</structfield> and <structfield>silence</structfield> callbacks depends upon whether the hardware supports interleaved or non-interleaved samples. The <structfield>copy</structfield> callback is @@ -5184,8 +5179,8 @@ struct _snd_pcm_runtime { <para> What you have to do in this callback is again different - between playback and capture directions. In the case of - playback, you do: copy the given amount of data + between playback and capture directions. In the + playback case, you copy the given amount of data (<parameter>count</parameter>) at the specified pointer (<parameter>src</parameter>) to the specified offset (<parameter>pos</parameter>) on the hardware buffer. When @@ -5202,7 +5197,7 @@ struct _snd_pcm_runtime { </para> <para> - For the capture direction, you do: copy the given amount of + For the capture direction, you copy the given amount of data (<parameter>count</parameter>) at the specified offset (<parameter>pos</parameter>) on the hardware buffer to the specified pointer (<parameter>dst</parameter>). @@ -5216,7 +5211,7 @@ struct _snd_pcm_runtime { </programlisting> </informalexample> - Note that both of the position and the data amount are given + Note that both the position and the amount of data are given in frames. </para> @@ -5247,7 +5242,7 @@ struct _snd_pcm_runtime { </para> <para> - The meanings of arguments are identical with the + The meanings of arguments are the same as in the <structfield>copy</structfield> callback, although there is no <parameter>src/dst</parameter> argument. In the case of interleaved samples, the channel @@ -5284,8 +5279,8 @@ struct _snd_pcm_runtime { <section id="buffer-and-memory-non-contiguous"> <title>Non-Contiguous Buffers</title> <para> - If your hardware supports the page table like emu10k1 or the - buffer descriptors like via82xx, you can use the scatter-gather + If your hardware supports the page table as in emu10k1 or the + buffer descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA provides an interface for handling SG-buffers. The API is provided in <filename><sound/pcm.h></filename>. </para> @@ -5296,7 +5291,7 @@ struct _snd_pcm_runtime { <function>snd_pcm_lib_preallocate_pages_for_all()</function> with <constant>SNDRV_DMA_TYPE_DEV_SG</constant> in the PCM constructor like other PCI pre-allocator. - You need to pass the <function>snd_dma_pci_data(pci)</function>, + You need to pass <function>snd_dma_pci_data(pci)</function>, where pci is the struct <structname>pci_dev</structname> pointer of the chip as well. The <type>struct snd_sg_buf</type> instance is created as @@ -5314,7 +5309,7 @@ struct _snd_pcm_runtime { <para> Then call <function>snd_pcm_lib_malloc_pages()</function> - in <structfield>hw_params</structfield> callback + in the <structfield>hw_params</structfield> callback as well as in the case of normal PCI buffer. The SG-buffer handler will allocate the non-contiguous kernel pages of the given size and map them onto the virtually contiguous @@ -5335,7 +5330,7 @@ struct _snd_pcm_runtime { </para> <para> - For releasing the data, call + To release the data, call <function>snd_pcm_lib_free_pages()</function> in the <structfield>hw_free</structfield> callback as usual. </para> @@ -5390,7 +5385,7 @@ struct _snd_pcm_runtime { </para> <para> - For creating a proc file, call + To create a proc file, call <function>snd_card_proc_new()</function>. <informalexample> @@ -5402,7 +5397,7 @@ struct _snd_pcm_runtime { </programlisting> </informalexample> - where the second argument specifies the proc-file name to be + where the second argument specifies the name of the proc file to be created. The above example will create a file <filename>my-file</filename> under the card directory, e.g. <filename>/proc/asound/card0/my-file</filename>. @@ -5417,8 +5412,8 @@ struct _snd_pcm_runtime { <para> When the creation is successful, the function stores a new - instance at the pointer given in the third argument. - It is initialized as a text proc file for read only. For using + instance in the pointer given in the third argument. + It is initialized as a text proc file for read only. To use this proc file as a read-only text file as it is, set the read callback with a private data via <function>snd_info_set_text_ops()</function>. @@ -5470,9 +5465,9 @@ struct _snd_pcm_runtime { </para> <para> - The file permission can be changed afterwards. As default, it's - set as read only for all users. If you want to add the write - permission to the user (root as default), set like below: + The file permissions can be changed afterwards. As default, it's + set as read only for all users. If you want to add write + permission for the user (root as default), do as follows: <informalexample> <programlisting> @@ -5503,7 +5498,7 @@ struct _snd_pcm_runtime { </para> <para> - For a raw-data proc-file, set the attributes like the following: + For a raw-data proc-file, set the attributes as follows: <informalexample> <programlisting> @@ -5524,7 +5519,7 @@ struct _snd_pcm_runtime { <para> The callback is much more complicated than the text-file - version. You need to use a low-level i/o functions such as + version. You need to use a low-level I/O functions such as <function>copy_from/to_user()</function> to transfer the data. @@ -5560,28 +5555,28 @@ struct _snd_pcm_runtime { <title>Power Management</title> <para> If the chip is supposed to work with suspend/resume - functions, you need to add the power-management codes to the - driver. The additional codes for the power-management should be + functions, you need to add power-management code to the + driver. The additional code for power-management should be <function>ifdef</function>'ed with <constant>CONFIG_PM</constant>. </para> <para> - If the driver supports the suspend/resume - <emphasis>fully</emphasis>, that is, the device can be - properly resumed to the status at the suspend is called, - you can set <constant>SNDRV_PCM_INFO_RESUME</constant> flag - to pcm info field. Usually, this is possible when the - registers of ths chip can be safely saved and restored to the - RAM. If this is set, the trigger callback is called with - <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after resume - callback is finished. + If the driver <emphasis>fully</emphasis> supports suspend/resume + that is, the device can be + properly resumed to its state when suspend was called, + you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag + in the pcm info field. Usually, this is possible when the + registers of the chip can be safely saved and restored to + RAM. If this is set, the trigger callback is called with + <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume + callback completes. </para> <para> - Even if the driver doesn't support PM fully but only the - partial suspend/resume is possible, it's still worthy to - implement suspend/resume callbacks. In such a case, applications + Even if the driver doesn't support PM fully but + partial suspend/resume is still possible, it's still worthy to + implement suspend/resume callbacks. In such a case, applications would reset the status by calling <function>snd_pcm_prepare()</function> and restart the stream appropriately. Hence, you can define suspend/resume callbacks @@ -5590,22 +5585,22 @@ struct _snd_pcm_runtime { </para> <para> - Note that the trigger with SUSPEND can be always called when + Note that the trigger with SUSPEND can always be called when <function>snd_pcm_suspend_all</function> is called, - regardless of <constant>SNDRV_PCM_INFO_RESUME</constant> flag. + regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag. The <constant>RESUME</constant> flag affects only the behavior of <function>snd_pcm_resume()</function>. (Thus, in theory, <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed to be handled in the trigger callback when no <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, - it's better to keep it for compatibility reason.) + it's better to keep it for compatibility reasons.) </para> <para> In the earlier version of ALSA drivers, a common power-management layer was provided, but it has been removed. The driver needs to define the suspend/resume hooks according to - the bus the device is assigned. In the case of PCI driver, the + the bus the device is connected to. In the case of PCI drivers, the callbacks look like below: <informalexample> @@ -5629,7 +5624,7 @@ struct _snd_pcm_runtime { </para> <para> - The scheme of the real suspend job is as following. + The scheme of the real suspend job is as follows. <orderedlist> <listitem><para>Retrieve the card and the chip data.</para></listitem> @@ -5679,11 +5674,11 @@ struct _snd_pcm_runtime { </para> <para> - The scheme of the real resume job is as following. + The scheme of the real resume job is as follows. <orderedlist> <listitem><para>Retrieve the card and the chip data.</para></listitem> - <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. + <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. Then enable the pci device again by calling <function>pci_enable_device()</function>. Call <function>pci_set_master()</function> if necessary, too.</para></listitem> <listitem><para>Re-initialize the chip.</para></listitem> @@ -5734,7 +5729,7 @@ struct _snd_pcm_runtime { <function>snd_pcm_suspend_all()</function> or <function>snd_pcm_suspend()</function>. It means that the PCM streams are already stoppped when the register snapshot is - taken. But, remind that you don't have to restart the PCM + taken. But, remember that you don't have to restart the PCM stream in the resume callback. It'll be restarted via trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> when necessary. @@ -5795,7 +5790,7 @@ struct _snd_pcm_runtime { </para> <para> - If you need a space for saving the registers, allocate the + If you need a space to save the registers, allocate the buffer for it here, too, since it would be fatal if you cannot allocate a memory in the suspend phase. The allocated buffer should be released in the corresponding @@ -5833,7 +5828,7 @@ struct _snd_pcm_runtime { <title>Module Parameters</title> <para> There are standard module options for ALSA. At least, each - module should have <parameter>index</parameter>, + module should have the <parameter>index</parameter>, <parameter>id</parameter> and <parameter>enable</parameter> options. </para> @@ -5841,8 +5836,8 @@ struct _snd_pcm_runtime { <para> If the module supports multiple cards (usually up to 8 = <constant>SNDRV_CARDS</constant> cards), they should be - arrays. The default initial values are defined already as - constants for ease of programming: + arrays. The default initial values are defined already as + constants for easier programming: <informalexample> <programlisting> @@ -5858,7 +5853,7 @@ struct _snd_pcm_runtime { <para> If the module supports only a single card, they could be single variables, instead. <parameter>enable</parameter> option is not - always necessary in this case, but it wouldn't be so bad to have a + always necessary in this case, but it would be better to have a dummy option for compatibility. </para> @@ -5923,22 +5918,22 @@ struct _snd_pcm_runtime { </para> <para> - Suppose that you'll create a new PCI driver for the card + Suppose that you create a new PCI driver for the card <quote>xyz</quote>. The card module name would be - snd-xyz. The new driver is usually put into alsa-driver + snd-xyz. The new driver is usually put into the alsa-driver tree, <filename>alsa-driver/pci</filename> directory in the case of PCI cards. Then the driver is evaluated, audited and tested by developers and users. After a certain time, the driver - will go to alsa-kernel tree (to the corresponding directory, + will go to the alsa-kernel tree (to the corresponding directory, such as <filename>alsa-kernel/pci</filename>) and eventually - integrated into Linux 2.6 tree (the directory would be + will be integrated into the Linux 2.6 tree (the directory would be <filename>linux/sound/pci</filename>). </para> <para> In the following sections, the driver code is supposed - to be put into alsa-driver tree. The two cases are assumed: + to be put into alsa-driver tree. The two cases are covered: a driver consisting of a single source file and one consisting of several source files. </para> @@ -6033,7 +6028,7 @@ struct _snd_pcm_runtime { <listitem> <para> Add a new directory (<filename>xyz</filename>) in - <filename>alsa-driver/pci/Makefile</filename> like below + <filename>alsa-driver/pci/Makefile</filename> as below <informalexample> <programlisting> @@ -6102,7 +6097,7 @@ struct _snd_pcm_runtime { <section id="useful-functions-snd-printk"> <title><function>snd_printk()</function> and friends</title> <para> - ALSA provides a verbose version of + ALSA provides a verbose version of the <function>printk()</function> function. If a kernel config <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this function prints the given message together with the file name @@ -6170,7 +6165,7 @@ struct _snd_pcm_runtime { <section id="useful-functions-snd-bug"> <title><function>snd_BUG()</function></title> <para> - It shows <computeroutput>BUG?</computeroutput> message and + It shows the <computeroutput>BUG?</computeroutput> message and stack trace as well as <function>snd_assert</function> at the point. It's useful to show that a fatal error happens there. </para> @@ -6199,6 +6194,4 @@ struct _snd_pcm_runtime { in the hardware constraints section. </para> </chapter> - - </book> diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt index 3feeb9e..0ebd7ea 100644 --- a/Documentation/sound/alsa/soc/DAI.txt +++ b/Documentation/sound/alsa/soc/DAI.txt @@ -1,5 +1,5 @@ ASoC currently supports the three main Digital Audio Interfaces (DAI) found on -SoC controllers and portable audio CODECS today, namely AC97, I2S and PCM. +SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM. AC97 @@ -25,7 +25,7 @@ left/right clock (LRC) synchronise the link. I2S is flexible in that either the controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock usually varies depending on the sample rate and the master system clock (SYSCLK). LRCLK is the same as the sample rate. A few devices support separate -ADC and DAC LRCLK's, this allows for simultaneous capture and playback at +ADC and DAC LRCLKs, this allows for simultaneous capture and playback at different sample rates. I2S has several different operating modes:- @@ -35,7 +35,7 @@ I2S has several different operating modes:- o Left Justified - MSB is transmitted on transition of LRC. - o Right Justified - MSB is transmitted sample size BCLK's before LRC + o Right Justified - MSB is transmitted sample size BCLKs before LRC transition. PCM diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt index 1493088..b130016 100644 --- a/Documentation/sound/alsa/soc/clocking.txt +++ b/Documentation/sound/alsa/soc/clocking.txt @@ -13,7 +13,7 @@ or SYSCLK). This audio master clock can be derived from a number of sources (e.g. crystal, PLL, CPU clock) and is responsible for producing the correct audio playback and capture sample rates. -Some master clocks (e.g. PLL's and CPU based clocks) are configurable in that +Some master clocks (e.g. PLLs and CPU based clocks) are configurable in that their speed can be altered by software (depending on the system use and to save power). Other master clocks are fixed at a set frequency (i.e. crystals). @@ -41,11 +41,11 @@ BCLK = LRC * x BCLK = LRC * Channels * Word Size This relationship depends on the codec or SoC CPU in particular. In general -it's best to configure BCLK to the lowest possible speed (depending on your -rate, number of channels and wordsize) to save on power. +it is best to configure BCLK to the lowest possible speed (depending on your +rate, number of channels and word size) to save on power. -It's also desirable to use the codec (if possible) to drive (or master) the -audio clocks as it's usually gives more accurate sample rates than the CPU. +It is also desirable to use the codec (if possible) to drive (or master) the +audio clocks as it usually gives more accurate sample rates than the CPU. diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt index 1e766ad..1e95342 100644 --- a/Documentation/sound/alsa/soc/codec.txt +++ b/Documentation/sound/alsa/soc/codec.txt @@ -9,7 +9,7 @@ code should be added to the platform and machine drivers respectively. Each codec driver *must* provide the following features:- 1) Codec DAI and PCM configuration - 2) Codec control IO - using I2C, 3 Wire(SPI) or both API's + 2) Codec control IO - using I2C, 3 Wire(SPI) or both APIs 3) Mixers and audio controls 4) Codec audio operations @@ -19,7 +19,7 @@ Optionally, codec drivers can also provide:- 6) DAPM event handler. 7) DAC Digital mute control. -It's probably best to use this guide in conjunction with the existing codec +Its probably best to use this guide in conjunction with the existing codec driver code in sound/soc/codecs/ ASoC Codec driver breakdown @@ -27,8 +27,8 @@ ASoC Codec driver breakdown 1 - Codec DAI and PCM configuration ----------------------------------- -Each codec driver must have a struct snd_soc_codec_dai to define it's DAI and -PCM's capabilities and operations. This struct is exported so that it can be +Each codec driver must have a struct snd_soc_codec_dai to define its DAI and +PCM capabilities and operations. This struct is exported so that it can be registered with the core by your machine driver. e.g. @@ -67,18 +67,18 @@ EXPORT_SYMBOL_GPL(wm8731_dai); 2 - Codec control IO -------------------- -The codec can usually be controlled via an I2C or SPI style interface (AC97 -combines control with data in the DAI). The codec drivers will have to provide -functions to read and write the codec registers along with supplying a register -cache:- +The codec can usually be controlled via an I2C or SPI style interface +(AC97 combines control with data in the DAI). The codec drivers provide +functions to read and write the codec registers along with supplying a +register cache:- /* IO control data and register cache */ - void *control_data; /* codec control (i2c/3wire) data */ - void *reg_cache; + void *control_data; /* codec control (i2c/3wire) data */ + void *reg_cache; -Codec read/write should do any data formatting and call the hardware read write -below to perform the IO. These functions are called by the core and alsa when -performing DAPM or changing the mixer:- +Codec read/write should do any data formatting and call the hardware +read write below to perform the IO. These functions are called by the +core and ALSA when performing DAPM or changing the mixer:- unsigned int (*read)(struct snd_soc_codec *, unsigned int); int (*write)(struct snd_soc_codec *, unsigned int, unsigned int); @@ -131,7 +131,7 @@ Defines a stereo enumerated control 4 - Codec Audio Operations -------------------------- -The codec driver also supports the following alsa operations:- +The codec driver also supports the following ALSA operations:- /* SoC audio ops */ struct snd_soc_ops { @@ -142,15 +142,15 @@ struct snd_soc_ops { int (*prepare)(struct snd_pcm_substream *); }; -Please refer to the alsa driver PCM documentation for details. +Please refer to the ALSA driver PCM documentation for details. http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm 5 - DAPM description. --------------------- -The Dynamic Audio Power Management description describes the codec's power -components, their relationships and registers to the ASoC core. Please read -dapm.txt for details of building the description. +The Dynamic Audio Power Management description describes the codec power +components and their relationships and registers to the ASoC core. +Please read dapm.txt for details of building the description. Please also see the examples in other codec drivers. @@ -158,8 +158,8 @@ Please also see the examples in other codec drivers. 6 - DAPM event handler ---------------------- This function is a callback that handles codec domain PM calls and system -domain PM calls (e.g. suspend and resume). It's used to put the codec to sleep -when not in use. +domain PM calls (e.g. suspend and resume). It is used to put the codec +to sleep when not in use. Power states:- @@ -175,13 +175,14 @@ Power states:- SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */ -7 - Codec DAC digital mute control. ------------------------------------- -Most codecs have a digital mute before the DAC's that can be used to minimise -any system noise. The mute stops any digital data from entering the DAC. +7 - Codec DAC digital mute control +---------------------------------- +Most codecs have a digital mute before the DACs that can be used to +minimise any system noise. The mute stops any digital data from +entering the DAC. -A callback can be created that is called by the core for each codec DAI when the -mute is applied or freed. +A callback can be created that is called by the core for each codec DAI +when the mute is applied or freed. i.e. diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt index ab0766f..c784a18 100644 --- a/Documentation/sound/alsa/soc/dapm.txt +++ b/Documentation/sound/alsa/soc/dapm.txt @@ -4,20 +4,20 @@ Dynamic Audio Power Management for Portable Devices 1. Description ============== -Dynamic Audio Power Management (DAPM) is designed to allow portable Linux devices -to use the minimum amount of power within the audio subsystem at all times. It -is independent of other kernel PM and as such, can easily co-exist with the -other PM systems. +Dynamic Audio Power Management (DAPM) is designed to allow portable +Linux devices to use the minimum amount of power within the audio +subsystem at all times. It is independent of other kernel PM and as +such, can easily co-exist with the other PM systems. -DAPM is also completely transparent to all user space applications as all power -switching is done within the ASoC core. No code changes or recompiling are -required for user space applications. DAPM makes power switching decisions based -upon any audio stream (capture/playback) activity and audio mixer settings -within the device. +DAPM is also completely transparent to all user space applications as +all power switching is done within the ASoC core. No code changes or +recompiling are required for user space applications. DAPM makes power +switching decisions based upon any audio stream (capture/playback) +activity and audio mixer settings within the device. -DAPM spans the whole machine. It covers power control within the entire audio -subsystem, this includes internal codec power blocks and machine level power -systems. +DAPM spans the whole machine. It covers power control within the entire +audio subsystem, this includes internal codec power blocks and machine +level power systems. There are 4 power domains within DAPM @@ -34,7 +34,7 @@ There are 4 power domains within DAPM Automatically set when mixer and mux settings are changed by the user. e.g. alsamixer, amixer. - 4. Stream domain - DAC's and ADC's. + 4. Stream domain - DACs and ADCs. Enabled and disabled when stream playback/capture is started and stopped respectively. e.g. aplay, arecord. @@ -51,7 +51,7 @@ widgets hereafter. Audio DAPM widgets fall into a number of types:- o Mixer - Mixes several analog signals into a single analog signal. - o Mux - An analog switch that outputs only 1 of it's inputs. + o Mux - An analog switch that outputs only one of many inputs. o PGA - A programmable gain amplifier or attenuation widget. o ADC - Analog to Digital Converter o DAC - Digital to Analog Converter @@ -78,14 +78,14 @@ parameters for stream name and kcontrols. 2.1 Stream Domain Widgets ------------------------- -Stream Widgets relate to the stream power domain and only consist of ADC's -(analog to digital converters) and DAC's (digital to analog converters). +Stream Widgets relate to the stream power domain and only consist of ADCs +(analog to digital converters) and DACs (digital to analog converters). Stream widgets have the following format:- SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert), -NOTE: the stream name must match the corresponding stream name in your codecs +NOTE: the stream name must match the corresponding stream name in your codec snd_soc_codec_dai. e.g. stream widgets for HiFi playback and capture @@ -97,7 +97,7 @@ SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1), 2.2 Path Domain Widgets ----------------------- -Path domain widgets have a ability to control or effect the audio signal or +Path domain widgets have a ability to control or affect the audio signal or audio paths within the audio subsystem. They have the following form:- SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls) @@ -149,7 +149,7 @@ SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias), 2.4 Codec Domain ---------------- -The Codec power domain has no widgets and is handled by the codecs DAPM event +The codec power domain has no widgets and is handled by the codecs DAPM event handler. This handler is called when the codec powerstate is changed wrt to any stream event or by kernel PM events. @@ -158,8 +158,8 @@ stream event or by kernel PM events. ------------------- Sometimes widgets exist in the codec or machine audio map that don't have any -corresponding register bit for power control. In this case it's necessary to -create a virtual widget - a widget with no control bits e.g. +corresponding soft power control. In this case it is necessary to create +a virtual widget - a widget with no control bits e.g. SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0), @@ -172,13 +172,14 @@ subsystem individually with a call to snd_soc_dapm_new_control(). 3. Codec Widget Interconnections ================================ -Widgets are connected to each other within the codec and machine by audio -paths (called interconnections). Each interconnection must be defined in order -to create a map of all audio paths between widgets. +Widgets are connected to each other within the codec and machine by audio paths +(called interconnections). Each interconnection must be defined in order to +create a map of all audio paths between widgets. + This is easiest with a diagram of the codec (and schematic of the machine audio system), as it requires joining widgets together via their audio signal paths. -i.e. from the WM8731 codec's output mixer (wm8731.c) +e.g., from the WM8731 output mixer (wm8731.c) The WM8731 output mixer has 3 inputs (sources) diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt index 72bd222..f370e7d 100644 --- a/Documentation/sound/alsa/soc/machine.txt +++ b/Documentation/sound/alsa/soc/machine.txt @@ -16,7 +16,7 @@ struct snd_soc_machine { int (*remove)(struct platform_device *pdev); /* the pre and post PM functions are used to do any PM work before and - * after the codec and DAI's do any PM work. */ + * after the codec and DAIs do any PM work. */ int (*suspend_pre)(struct platform_device *pdev, pm_message_t state); int (*suspend_post)(struct platform_device *pdev, pm_message_t state); int (*resume_pre)(struct platform_device *pdev); @@ -38,7 +38,7 @@ probe/remove are optional. Do any machine specific probe here. suspend()/resume() ------------------ The machine driver has pre and post versions of suspend and resume to take care -of any machine audio tasks that have to be done before or after the codec, DAI's +of any machine audio tasks that have to be done before or after the codec, DAIs and DMA is suspended and resumed. Optional. @@ -49,10 +49,10 @@ The machine specific audio operations can be set here. Again this is optional. Machine DAI Configuration ------------------------- -The machine DAI configuration glues all the codec and CPU DAI's together. It can +The machine DAI configuration glues all the codec and CPU DAIs together. It can also be used to set up the DAI system clock and for any machine related DAI initialisation e.g. the machine audio map can be connected to the codec audio -map, unconnnected codec pins can be set as such. Please see corgi.c, spitz.c +map, unconnected codec pins can be set as such. Please see corgi.c, spitz.c for examples. struct snd_soc_dai_link is used to set up each DAI in your machine. e.g. @@ -67,7 +67,7 @@ static struct snd_soc_dai_link corgi_dai = { .ops = &corgi_ops, }; -struct snd_soc_machine then sets up the machine with it's DAI's. e.g. +struct snd_soc_machine then sets up the machine with it's DAIs. e.g. /* corgi audio machine driver */ static struct snd_soc_machine snd_soc_machine_corgi = { @@ -110,4 +110,4 @@ details. Machine Controls ---------------- -Machine specific audio mixer controls can be added in the dai init function.
\ No newline at end of file +Machine specific audio mixer controls can be added in the DAI init function. diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt index c47ce95..1e4c6d3 100644 --- a/Documentation/sound/alsa/soc/overview.txt +++ b/Documentation/sound/alsa/soc/overview.txt @@ -1,25 +1,26 @@ ALSA SoC Layer ============== -The overall project goal of the ALSA System on Chip (ASoC) layer is to provide -better ALSA support for embedded system-on-chip processors (e.g. pxa2xx, au1x00, -iMX, etc) and portable audio codecs. Currently there is some support in the -kernel for SoC audio, however it has some limitations:- +The overall project goal of the ALSA System on Chip (ASoC) layer is to +provide better ALSA support for embedded system-on-chip processors (e.g. +pxa2xx, au1x00, iMX, etc) and portable audio codecs. Prior to the ASoC +subsystem there was some support in the kernel for SoC audio, however it +had some limitations:- - * Currently, codec drivers are often tightly coupled to the underlying SoC - CPU. This is not ideal and leads to code duplication i.e. Linux now has 4 - different wm8731 drivers for 4 different SoC platforms. + * Codec drivers were often tightly coupled to the underlying SoC + CPU. This is not ideal and leads to code duplication - for example, + Linux had different wm8731 drivers for 4 different SoC platforms. - * There is no standard method to signal user initiated audio events (e.g. + * There was no standard method to signal user initiated audio events (e.g. Headphone/Mic insertion, Headphone/Mic detection after an insertion event). These are quite common events on portable devices and often require machine specific code to re-route audio, enable amps, etc., after such an event. - * Current drivers tend to power up the entire codec when playing - (or recording) audio. This is fine for a PC, but tends to waste a lot of - power on portable devices. There is also no support for saving power via - changing codec oversampling rates, bias currents, etc. + * Drivers tended to power up the entire codec when playing (or + recording) audio. This is fine for a PC, but tends to waste a lot of + power on portable devices. There was also no support for saving + power via changing codec oversampling rates, bias currents, etc. ASoC Design @@ -31,12 +32,13 @@ features :- * Codec independence. Allows reuse of codec drivers on other platforms and machines. - * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC interface - and codec registers it's audio interface capabilities with the core and are - subsequently matched and configured when the application hw params are known. + * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC + interface and codec registers it's audio interface capabilities with the + core and are subsequently matched and configured when the application + hardware parameters are known. * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to - it's minimum power state at all times. This includes powering up/down + its minimum power state at all times. This includes powering up/down internal power blocks depending on the internal codec audio routing and any active streams. @@ -45,16 +47,16 @@ features :- signals the codec when to change power states. * Machine specific controls: Allow machines to add controls to the sound card - (e.g. volume control for speaker amp). + (e.g. volume control for speaker amplifier). To achieve all this, ASoC basically splits an embedded audio system into 3 components :- * Codec driver: The codec driver is platform independent and contains audio - controls, audio interface capabilities, codec dapm definition and codec IO + controls, audio interface capabilities, codec DAPM definition and codec IO functions. - * Platform driver: The platform driver contains the audio dma engine and audio + * Platform driver: The platform driver contains the audio DMA engine and audio interface drivers (e.g. I2S, AC97, PCM) for that platform. * Machine driver: The machine driver handles any machine specific controls and @@ -81,4 +83,4 @@ machine.txt: Machine driver internals. pop_clicks.txt: How to minimise audio artifacts. -clocking.txt: ASoC clocking for best power performance.
\ No newline at end of file +clocking.txt: ASoC clocking for best power performance. diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt index d4678b4..b681d17 100644 --- a/Documentation/sound/alsa/soc/platform.txt +++ b/Documentation/sound/alsa/soc/platform.txt @@ -8,7 +8,7 @@ specific code. Audio DMA ========= -The platform DMA driver optionally supports the following alsa operations:- +The platform DMA driver optionally supports the following ALSA operations:- /* SoC audio ops */ struct snd_soc_ops { @@ -38,7 +38,7 @@ struct snd_soc_platform { struct snd_pcm_ops *pcm_ops; }; -Please refer to the alsa driver documentation for details of audio DMA. +Please refer to the ALSA driver documentation for details of audio DMA. http://www.alsa-project.org/~iwai/writing-an-alsa-driver/c436.htm An example DMA driver is soc/pxa/pxa2xx-pcm.c @@ -52,7 +52,7 @@ Each SoC DAI driver must provide the following features:- 1) Digital audio interface (DAI) description 2) Digital audio interface configuration 3) PCM's description - 4) Sysclk configuration + 4) SYSCLK configuration 5) Suspend and resume (optional) Please see codec.txt for a description of items 1 - 4. diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt index 3371bd9..e1e74da 100644 --- a/Documentation/sound/alsa/soc/pops_clicks.txt +++ b/Documentation/sound/alsa/soc/pops_clicks.txt @@ -15,11 +15,11 @@ click every time a component power state is changed. Minimising Playback Pops and Clicks =================================== -Playback pops in portable audio subsystems cannot be completely eliminated atm, -however future audio codec hardware will have better pop and click suppression. -Pops can be reduced within playback by powering the audio components in a -specific order. This order is different for startup and shutdown and follows -some basic rules:- +Playback pops in portable audio subsystems cannot be completely eliminated +currently, however future audio codec hardware will have better pop and click +suppression. Pops can be reduced within playback by powering the audio +components in a specific order. This order is different for startup and +shutdown and follows some basic rules:- Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt index aa986a3..f992543 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/sysctl/fs.txt @@ -23,6 +23,7 @@ Currently, these files are in /proc/sys/fs: - inode-max - inode-nr - inode-state +- nr_open - overflowuid - overflowgid - suid_dumpable @@ -91,6 +92,15 @@ usage of file handles and you don't need to increase the maximum. ============================================================== +nr_open: + +This denotes the maximum number of file-handles a process can +allocate. Default value is 1024*1024 (1048576) which should be +enough for most machines. Actual limit depends on RLIMIT_NOFILE +resource limit. + +============================================================== + inode-max, inode-nr & inode-state: As with file handles, the kernel allocates the inode structures diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 6f31f0a..8a4863c 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -22,6 +22,7 @@ Currently, these files are in /proc/sys/vm: - dirty_background_ratio - dirty_expire_centisecs - dirty_writeback_centisecs +- highmem_is_dirtyable (only if CONFIG_HIGHMEM set) - max_map_count - min_free_kbytes - laptop_mode @@ -31,6 +32,7 @@ Currently, these files are in /proc/sys/vm: - min_unmapped_ratio - min_slab_ratio - panic_on_oom +- oom_dump_tasks - oom_kill_allocating_task - mmap_min_address - numa_zonelist_order @@ -40,9 +42,9 @@ Currently, these files are in /proc/sys/vm: ============================================================== dirty_ratio, dirty_background_ratio, dirty_expire_centisecs, -dirty_writeback_centisecs, vfs_cache_pressure, laptop_mode, -block_dump, swap_token_timeout, drop-caches, -hugepages_treat_as_movable: +dirty_writeback_centisecs, highmem_is_dirtyable, +vfs_cache_pressure, laptop_mode, block_dump, swap_token_timeout, +drop-caches, hugepages_treat_as_movable: See Documentation/filesystems/proc.txt @@ -231,6 +233,27 @@ according to your policy of failover. ============================================================= +oom_dump_tasks + +Enables a system-wide task dump (excluding kernel threads) to be +produced when the kernel performs an OOM-killing and includes such +information as pid, uid, tgid, vm size, rss, cpu, oom_adj score, and +name. This is helpful to determine why the OOM killer was invoked +and to identify the rogue task that caused it. + +If this is set to zero, this information is suppressed. On very +large systems with thousands of tasks it may not be feasible to dump +the memory state information for each one. Such systems should not +be forced to incur a performance penalty in OOM conditions when the +information may not be desired. + +If this is set to non-zero, this information is shown whenever the +OOM killer actually kills a memory-hogging task. + +The default value is 0. + +============================================================= + oom_kill_allocating_task This enables or disables killing the OOM-triggering task in diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt new file mode 100644 index 0000000..ba9c2da --- /dev/null +++ b/Documentation/thermal/sysfs-api.txt @@ -0,0 +1,245 @@ +Generic Thermal Sysfs driver How To +========================= + +Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> + +Updated: 2 January 2008 + +Copyright (c) 2008 Intel Corporation + + +0. Introduction + +The generic thermal sysfs provides a set of interfaces for thermal zone devices (sensors) +and thermal cooling devices (fan, processor...) to register with the thermal management +solution and to be a part of it. + +This how-to focuses on enabling new thermal zone and cooling devices to participate +in thermal management. +This solution is platform independent and any type of thermal zone devices and +cooling devices should be able to make use of the infrastructure. + +The main task of the thermal sysfs driver is to expose thermal zone attributes as well +as cooling device attributes to the user space. +An intelligent thermal management application can make decisions based on inputs +from thermal zone attributes (the current temperature and trip point temperature) +and throttle appropriate devices. + +[0-*] denotes any positive number starting from 0 +[1-*] denotes any positive number starting from 1 + +1. thermal sysfs driver interface functions + +1.1 thermal zone device interface +1.1.1 struct thermal_zone_device *thermal_zone_device_register(char *name, int trips, + void *devdata, struct thermal_zone_device_ops *ops) + + This interface function adds a new thermal zone device (sensor) to + /sys/class/thermal folder as thermal_zone[0-*]. + It tries to bind all the thermal cooling devices registered at the same time. + + name: the thermal zone name. + trips: the total number of trip points this thermal zone supports. + devdata: device private data + ops: thermal zone device call-backs. + .bind: bind the thermal zone device with a thermal cooling device. + .unbind: unbind the thermal zone device with a thermal cooling device. + .get_temp: get the current temperature of the thermal zone. + .get_mode: get the current mode (user/kernel) of the thermal zone. + "kernel" means thermal management is done in kernel. + "user" will prevent kernel thermal driver actions upon trip points + so that user applications can take charge of thermal management. + .set_mode: set the mode (user/kernel) of the thermal zone. + .get_trip_type: get the type of certain trip point. + .get_trip_temp: get the temperature above which the certain trip point + will be fired. + +1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz) + + This interface function removes the thermal zone device. + It deletes the corresponding entry form /sys/class/thermal folder and unbind all + the thermal cooling devices it uses. + +1.2 thermal cooling device interface +1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name, + void *devdata, struct thermal_cooling_device_ops *) + + This interface function adds a new thermal cooling device (fan/processor/...) to + /sys/class/thermal/ folder as cooling_device[0-*]. + It tries to bind itself to all the thermal zone devices register at the same time. + name: the cooling device name. + devdata: device private data. + ops: thermal cooling devices call-backs. + .get_max_state: get the Maximum throttle state of the cooling device. + .get_cur_state: get the Current throttle state of the cooling device. + .set_cur_state: set the Current throttle state of the cooling device. + +1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev) + + This interface function remove the thermal cooling device. + It deletes the corresponding entry form /sys/class/thermal folder and unbind + itself from all the thermal zone devices using it. + +1.3 interface for binding a thermal zone device with a thermal cooling device +1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz, + int trip, struct thermal_cooling_device *cdev); + + This interface function bind a thermal cooling device to the certain trip point + of a thermal zone device. + This function is usually called in the thermal zone device .bind callback. + tz: the thermal zone device + cdev: thermal cooling device + trip: indicates which trip point the cooling devices is associated with + in this thermal zone. + +1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz, + int trip, struct thermal_cooling_device *cdev); + + This interface function unbind a thermal cooling device from the certain trip point + of a thermal zone device. + This function is usually called in the thermal zone device .unbind callback. + tz: the thermal zone device + cdev: thermal cooling device + trip: indicates which trip point the cooling devices is associated with + in this thermal zone. + +2. sysfs attributes structure + +RO read only value +RW read/write value + +All thermal sysfs attributes will be represented under /sys/class/thermal + +Thermal zone device sys I/F, created once it's registered: +|thermal_zone[0-*]: + |-----type: Type of the thermal zone + |-----temp: Current temperature + |-----mode: Working mode of the thermal zone + |-----trip_point_[0-*]_temp: Trip point temperature + |-----trip_point_[0-*]_type: Trip point type + +Thermal cooling device sys I/F, created once it's registered: +|cooling_device[0-*]: + |-----type : Type of the cooling device(processor/fan/...) + |-----max_state: Maximum cooling state of the cooling device + |-----cur_state: Current cooling state of the cooling device + + +These two dynamic attributes are created/removed in pairs. +They represent the relationship between a thermal zone and its associated cooling device. +They are created/removed for each +thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device successful execution. + +|thermal_zone[0-*] + |-----cdev[0-*]: The [0-*]th cooling device in the current thermal zone + |-----cdev[0-*]_trip_point: Trip point that cdev[0-*] is associated with + + +*************************** +* Thermal zone attributes * +*************************** + +type Strings which represent the thermal zone type. + This is given by thermal zone driver as part of registration. + Eg: "ACPI thermal zone" indicates it's a ACPI thermal device + RO + Optional + +temp Current temperature as reported by thermal zone (sensor) + Unit: degree Celsius + RO + Required + +mode One of the predefined values in [kernel, user] + This file gives information about the algorithm + that is currently managing the thermal zone. + It can be either default kernel based algorithm + or user space application. + RW + Optional + kernel = Thermal management in kernel thermal zone driver. + user = Preventing kernel thermal zone driver actions upon + trip points so that user application can take full + charge of the thermal management. + +trip_point_[0-*]_temp The temperature above which trip point will be fired + Unit: degree Celsius + RO + Optional + +trip_point_[0-*]_type Strings which indicate the type of the trip point + E.g. it can be one of critical, hot, passive, + active[0-*] for ACPI thermal zone. + RO + Optional + +cdev[0-*] Sysfs link to the thermal cooling device node where the sys I/F + for cooling device throttling control represents. + RO + Optional + +cdev[0-*]_trip_point The trip point with which cdev[0-*] is associated in this thermal zone + -1 means the cooling device is not associated with any trip point. + RO + Optional + +****************************** +* Cooling device attributes * +****************************** + +type String which represents the type of device + eg: For generic ACPI: this should be "Fan", + "Processor" or "LCD" + eg. For memory controller device on intel_menlow platform: + this should be "Memory controller" + RO + Optional + +max_state The maximum permissible cooling state of this cooling device. + RO + Required + +cur_state The current cooling state of this cooling device. + the value can any integer numbers between 0 and max_state, + cur_state == 0 means no cooling + cur_state == max_state means the maximum cooling. + RW + Required + +3. A simple implementation + +ACPI thermal zone may support multiple trip points like critical/hot/passive/active. +If an ACPI thermal zone supports critical, passive, active[0] and active[1] at the same time, +it may register itself as a thermal_zone_device (thermal_zone1) with 4 trip points in all. +It has one processor and one fan, which are both registered as thermal_cooling_device. +If the processor is listed in _PSL method, and the fan is listed in _AL0 method, +the sys I/F structure will be built like this: + +/sys/class/thermal: + +|thermal_zone1: + |-----type: ACPI thermal zone + |-----temp: 37 + |-----mode: kernel + |-----trip_point_0_temp: 100 + |-----trip_point_0_type: critical + |-----trip_point_1_temp: 80 + |-----trip_point_1_type: passive + |-----trip_point_2_temp: 70 + |-----trip_point_2_type: active[0] + |-----trip_point_3_temp: 60 + |-----trip_point_3_type: active[1] + |-----cdev0: --->/sys/class/thermal/cooling_device0 + |-----cdev0_trip_point: 1 /* cdev0 can be used for passive */ + |-----cdev1: --->/sys/class/thermal/cooling_device3 + |-----cdev1_trip_point: 2 /* cdev1 can be used for active[0]*/ + +|cooling_device0: + |-----type: Processor + |-----max_state: 8 + |-----cur_state: 0 + +|cooling_device3: + |-----type: Fan + |-----max_state: 2 + |-----cur_state: 0 diff --git a/Documentation/thinkpad-acpi.txt b/Documentation/thinkpad-acpi.txt index 10c041c..6c24777 100644 --- a/Documentation/thinkpad-acpi.txt +++ b/Documentation/thinkpad-acpi.txt @@ -1,7 +1,7 @@ ThinkPad ACPI Extras Driver - Version 0.17 - October 04th, 2007 + Version 0.19 + January 06th, 2008 Borislav Deianov <borislav@users.sf.net> Henrique de Moraes Holschuh <hmh@hmh.eng.br> @@ -215,6 +215,11 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file: ... any other 8-hex-digit mask ... echo reset > /proc/acpi/ibm/hotkey -- restore the original mask +The procfs interface does not support NVRAM polling control. So as to +maintain maximum bug-to-bug compatibility, it does not report any masks, +nor does it allow one to manipulate the hot key mask when the firmware +does not support masks at all, even if NVRAM polling is in use. + sysfs notes: hotkey_bios_enabled: @@ -231,17 +236,26 @@ sysfs notes: to this value. hotkey_enable: - Enables/disables the hot keys feature, and reports - current status of the hot keys feature. + Enables/disables the hot keys feature in the ACPI + firmware, and reports current status of the hot keys + feature. Has no effect on the NVRAM hot key polling + functionality. 0: disables the hot keys feature / feature disabled 1: enables the hot keys feature / feature enabled hotkey_mask: - 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. + bit mask to enable driver-handling (and depending on + the firmware, ACPI event generation) for each hot key + (see above). Returns the current status of the hot keys + mask, and allows one to modify it. + + Note: when NVRAM polling is active, the firmware mask + will be different from the value returned by + hotkey_mask. The driver will retain enabled bits for + hotkeys that are under NVRAM polling even if the + firmware refuses them, and will not set these bits on + the firmware hot key mask. hotkey_all_mask: bit mask that should enable event reporting for all @@ -257,12 +271,48 @@ sysfs notes: handled by the firmware anyway. Echo it to hotkey_mask above, to use. + hotkey_source_mask: + bit mask that selects which hot keys will the driver + poll the NVRAM for. This is auto-detected by the driver + based on the capabilities reported by the ACPI firmware, + but it can be overridden at runtime. + + Hot keys whose bits are set in both hotkey_source_mask + and also on hotkey_mask are polled for in NVRAM. Only a + few hot keys are available through CMOS NVRAM polling. + + Warning: when in NVRAM mode, the volume up/down/mute + keys are synthesized according to changes in the mixer, + so you have to use volume up or volume down to unmute, + as per the ThinkPad volume mixer user interface. When + in ACPI event mode, volume up/down/mute are reported as + separate events, but this behaviour may be corrected in + future releases of this driver, in which case the + ThinkPad volume mixer user interface semanthics will be + enforced. + + hotkey_poll_freq: + frequency in Hz for hot key polling. It must be between + 0 and 25 Hz. Polling is only carried out when strictly + needed. + + Setting hotkey_poll_freq to zero disables polling, and + will cause hot key presses that require NVRAM polling + to never be reported. + + Setting hotkey_poll_freq too low will cause repeated + pressings of the same hot key to be misreported as a + single key press, or to not even be detected at all. + The recommended polling frequency is 10Hz. + 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. + This attribute has poll()/select() support. + hotkey_report_mode: Returns the state of the procfs ACPI event report mode filter for hot keys. If it is set to 1 (the default), @@ -277,6 +327,25 @@ sysfs notes: May return -EPERM (write access locked out by module parameter) or -EACCES (read-only). + wakeup_reason: + Set to 1 if the system is waking up because the user + requested a bay ejection. Set to 2 if the system is + waking up because the user requested the system to + undock. Set to zero for normal wake-ups or wake-ups + due to unknown reasons. + + This attribute has poll()/select() support. + + wakeup_hotunplug_complete: + Set to 1 if the system was waken up because of an + undock or bay ejection request, and that request + was sucessfully completed. At this point, it might + be useful to send the system back to sleep, at the + user's choice. Refer to HKEY events 0x4003 and + 0x3003, below. + + This attribute has poll()/select() support. + input layer notes: A Hot key is mapped to a single input layer EV_KEY event, possibly @@ -427,6 +496,23 @@ Non hot-key ACPI HKEY event map: The above events are not propagated by the driver, except for legacy compatibility purposes when hotkey_report_mode is set to 1. +0x2304 System is waking up from suspend to undock +0x2305 System is waking up from suspend to eject bay +0x2404 System is waking up from hibernation to undock +0x2405 System is waking up from hibernation to eject bay + +The above events are never propagated by the driver. + +0x3003 Bay ejection (see 0x2x05) complete, can sleep again +0x4003 Undocked (see 0x2x04), can sleep again +0x5009 Tablet swivel: switched to tablet mode +0x500A Tablet swivel: switched to normal mode +0x500B Tablet pen insterted into its storage bay +0x500C Tablet pen removed from its storage bay +0x5010 Brightness level changed (newer Lenovo BIOSes) + +The above events are propagated by the driver. + Compatibility notes: ibm-acpi and thinkpad-acpi 0.15 (mainline kernels before 2.6.23) never @@ -1263,3 +1349,17 @@ Sysfs interface changelog: and the hwmon class for libsensors4 (lm-sensors 3) compatibility. Moved all hwmon attributes to this new platform device. + +0x020100: Marker for thinkpad-acpi with hot key NVRAM polling + support. If you must, use it to know you should not + start an userspace NVRAM poller (allows to detect when + NVRAM is compiled out by the user because it is + unneeded/undesired in the first place). +0x020101: Marker for thinkpad-acpi with hot key NVRAM polling + and proper hotkey_mask semanthics (version 8 of the + NVRAM polling patch). Some development snapshots of + 0.18 had an earlier version that did strange things + to hotkey_mask. + +0x020200: Add poll()/select() support to the following attributes: + hotkey_radio_sw, wakeup_hotunplug_complete, wakeup_reason diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt new file mode 100644 index 0000000..6223eac --- /dev/null +++ b/Documentation/unaligned-memory-access.txt @@ -0,0 +1,226 @@ +UNALIGNED MEMORY ACCESSES +========================= + +Linux runs on a wide variety of architectures which have varying behaviour +when it comes to memory access. This document presents some details about +unaligned accesses, why you need to write code that doesn't cause them, +and how to write such code! + + +The definition of an unaligned access +===================================== + +Unaligned memory accesses occur when you try to read N bytes of data starting +from an address that is not evenly divisible by N (i.e. addr % N != 0). +For example, reading 4 bytes of data from address 0x10004 is fine, but +reading 4 bytes of data from address 0x10005 would be an unaligned memory +access. + +The above may seem a little vague, as memory access can happen in different +ways. The context here is at the machine code level: certain instructions read +or write a number of bytes to or from memory (e.g. movb, movw, movl in x86 +assembly). As will become clear, it is relatively easy to spot C statements +which will compile to multiple-byte memory access instructions, namely when +dealing with types such as u16, u32 and u64. + + +Natural alignment +================= + +The rule mentioned above forms what we refer to as natural alignment: +When accessing N bytes of memory, the base memory address must be evenly +divisible by N, i.e. addr % N == 0. + +When writing code, assume the target architecture has natural alignment +requirements. + +In reality, only a few architectures require natural alignment on all sizes +of memory access. However, we must consider ALL supported architectures; +writing code that satisfies natural alignment requirements is the easiest way +to achieve full portability. + + +Why unaligned access is bad +=========================== + +The effects of performing an unaligned memory access vary from architecture +to architecture. It would be easy to write a whole document on the differences +here; a summary of the common scenarios is presented below: + + - Some architectures are able to perform unaligned memory accesses + transparently, but there is usually a significant performance cost. + - Some architectures raise processor exceptions when unaligned accesses + happen. The exception handler is able to correct the unaligned access, + at significant cost to performance. + - Some architectures raise processor exceptions when unaligned accesses + happen, but the exceptions do not contain enough information for the + unaligned access to be corrected. + - Some architectures are not capable of unaligned memory access, but will + silently perform a different memory access to the one that was requested, + resulting a a subtle code bug that is hard to detect! + +It should be obvious from the above that if your code causes unaligned +memory accesses to happen, your code will not work correctly on certain +platforms and will cause performance problems on others. + + +Code that does not cause unaligned access +========================================= + +At first, the concepts above may seem a little hard to relate to actual +coding practice. After all, you don't have a great deal of control over +memory addresses of certain variables, etc. + +Fortunately things are not too complex, as in most cases, the compiler +ensures that things will work for you. For example, take the following +structure: + + struct foo { + u16 field1; + u32 field2; + u8 field3; + }; + +Let us assume that an instance of the above structure resides in memory +starting at address 0x10000. With a basic level of understanding, it would +not be unreasonable to expect that accessing field2 would cause an unaligned +access. You'd be expecting field2 to be located at offset 2 bytes into the +structure, i.e. address 0x10002, but that address is not evenly divisible +by 4 (remember, we're reading a 4 byte value here). + +Fortunately, the compiler understands the alignment constraints, so in the +above case it would insert 2 bytes of padding in between field1 and field2. +Therefore, for standard structure types you can always rely on the compiler +to pad structures so that accesses to fields are suitably aligned (assuming +you do not cast the field to a type of different length). + +Similarly, you can also rely on the compiler to align variables and function +parameters to a naturally aligned scheme, based on the size of the type of +the variable. + +At this point, it should be clear that accessing a single byte (u8 or char) +will never cause an unaligned access, because all memory addresses are evenly +divisible by one. + +On a related topic, with the above considerations in mind you may observe +that you could reorder the fields in the structure in order to place fields +where padding would otherwise be inserted, and hence reduce the overall +resident memory size of structure instances. The optimal layout of the +above example is: + + struct foo { + u32 field2; + u16 field1; + u8 field3; + }; + +For a natural alignment scheme, the compiler would only have to add a single +byte of padding at the end of the structure. This padding is added in order +to satisfy alignment constraints for arrays of these structures. + +Another point worth mentioning is the use of __attribute__((packed)) on a +structure type. This GCC-specific attribute tells the compiler never to +insert any padding within structures, useful when you want to use a C struct +to represent some data that comes in a fixed arrangement 'off the wire'. + +You might be inclined to believe that usage of this attribute can easily +lead to unaligned accesses when accessing fields that do not satisfy +architectural alignment requirements. However, again, the compiler is aware +of the alignment constraints and will generate extra instructions to perform +the memory access in a way that does not cause unaligned access. Of course, +the extra instructions obviously cause a loss in performance compared to the +non-packed case, so the packed attribute should only be used when avoiding +structure padding is of importance. + + +Code that causes unaligned access +================================= + +With the above in mind, let's move onto a real life example of a function +that can cause an unaligned memory access. The following function adapted +from include/linux/etherdevice.h is an optimized routine to compare two +ethernet MAC addresses for equality. + +unsigned int compare_ether_addr(const u8 *addr1, const u8 *addr2) +{ + const u16 *a = (const u16 *) addr1; + const u16 *b = (const u16 *) addr2; + return ((a[0] ^ b[0]) | (a[1] ^ b[1]) | (a[2] ^ b[2])) != 0; +} + +In the above function, the reference to a[0] causes 2 bytes (16 bits) to +be read from memory starting at address addr1. Think about what would happen +if addr1 was an odd address such as 0x10003. (Hint: it'd be an unaligned +access.) + +Despite the potential unaligned access problems with the above function, it +is included in the kernel anyway but is understood to only work on +16-bit-aligned addresses. It is up to the caller to ensure this alignment or +not use this function at all. This alignment-unsafe function is still useful +as it is a decent optimization for the cases when you can ensure alignment, +which is true almost all of the time in ethernet networking context. + + +Here is another example of some code that could cause unaligned accesses: + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +This code will cause unaligned accesses every time the data parameter points +to an address that is not evenly divisible by 4. + +In summary, the 2 main scenarios where you may run into unaligned access +problems involve: + 1. Casting variables to types of different lengths + 2. Pointer arithmetic followed by access to at least 2 bytes of data + + +Avoiding unaligned accesses +=========================== + +The easiest way to avoid unaligned access is to use the get_unaligned() and +put_unaligned() macros provided by the <asm/unaligned.h> header file. + +Going back to an earlier example of code that potentially causes unaligned +access: + + void myfunc(u8 *data, u32 value) + { + [...] + *((u32 *) data) = cpu_to_le32(value); + [...] + } + +To avoid the unaligned memory access, you would rewrite it as follows: + + void myfunc(u8 *data, u32 value) + { + [...] + value = cpu_to_le32(value); + put_unaligned(value, (u32 *) data); + [...] + } + +The get_unaligned() macro works similarly. Assuming 'data' is a pointer to +memory and you wish to avoid unaligned access, its usage is as follows: + + u32 value = get_unaligned((u32 *) data); + +These macros work work for memory accesses of any length (not just 32 bits as +in the examples above). Be aware that when compared to standard access of +aligned memory, using these macros to access unaligned memory can be costly in +terms of performance. + +If use of such macros is not convenient, another option is to use memcpy(), +where the source or destination (or both) are of type u8* or unsigned char*. +Due to the byte-wise nature of this operation, unaligned accesses are avoided. + +-- +Author: Daniel Drake <dsd@gentoo.org> +With help from: Alan Cox, Avuton Olrich, Heikki Orsila, Jan Engelhardt, +Johannes Berg, Kyle McMartin, Kyle Moffett, Randy Dunlap, Robert Hancock, +Uli Kunitz, Vadim Lobanov + diff --git a/Documentation/usb/gadget_printer.txt b/Documentation/usb/gadget_printer.txt new file mode 100644 index 0000000..ad995bf --- /dev/null +++ b/Documentation/usb/gadget_printer.txt @@ -0,0 +1,510 @@ + + Linux USB Printer Gadget Driver + 06/04/2007 + + Copyright (C) 2007 Craig W. Nadler <craig@nadler.us> + + + +GENERAL +======= + +This driver may be used if you are writing printer firmware using Linux as +the embedded OS. This driver has nothing to do with using a printer with +your Linux host system. + +You will need a USB device controller and a Linux driver for it that accepts +a gadget / "device class" driver using the Linux USB Gadget API. After the +USB device controller driver is loaded then load the printer gadget driver. +This will present a printer interface to the USB Host that your USB Device +port is connected to. + +This driver is structured for printer firmware that runs in user mode. The +user mode printer firmware will read and write data from the kernel mode +printer gadget driver using a device file. The printer returns a printer status +byte when the USB HOST sends a device request to get the printer status. The +user space firmware can read or write this status byte using a device file +/dev/g_printer . Both blocking and non-blocking read/write calls are supported. + + + + +HOWTO USE THIS DRIVER +===================== + +To load the USB device controller driver and the printer gadget driver. The +following example uses the Netchip 2280 USB device controller driver: + +modprobe net2280 +modprobe g_printer + + +The follow command line parameter can be used when loading the printer gadget +(ex: modprobe g_printer idVendor=0x0525 idProduct=0xa4a8 ): + +idVendor - This is the Vendor ID used in the device descriptor. The default is + the Netchip vendor id 0x0525. YOU MUST CHANGE TO YOUR OWN VENDOR ID + BEFORE RELEASING A PRODUCT. If you plan to release a product and don't + already have a Vendor ID please see www.usb.org for details on how to + get one. + +idProduct - This is the Product ID used in the device descriptor. The default + is 0xa4a8, you should change this to an ID that's not used by any of + your other USB products if you have any. It would be a good idea to + start numbering your products starting with say 0x0001. + +bcdDevice - This is the version number of your product. It would be a good idea + to put your firmware version here. + +iManufacturer - A string containing the name of the Vendor. + +iProduct - A string containing the Product Name. + +iSerialNum - A string containing the Serial Number. This should be changed for + each unit of your product. + +iPNPstring - The PNP ID string used for this printer. You will want to set + either on the command line or hard code the PNP ID string used for + your printer product. + +qlen - The number of 8k buffers to use per endpoint. The default is 10, you + should tune this for your product. You may also want to tune the + size of each buffer for your product. + + + + +USING THE EXAMPLE CODE +====================== + +This example code talks to stdout, instead of a print engine. + +To compile the test code below: + +1) save it to a file called prn_example.c +2) compile the code with the follow command: + gcc prn_example.c -o prn_example + + + +To read printer data from the host to stdout: + + # prn_example -read_data + + +To write printer data from a file (data_file) to the host: + + # cat data_file | prn_example -write_data + + +To get the current printer status for the gadget driver: + + # prn_example -get_status + + Printer status is: + Printer is NOT Selected + Paper is Out + Printer OK + + +To set printer to Selected/On-line: + + # prn_example -selected + + +To set printer to Not Selected/Off-line: + + # prn_example -not_selected + + +To set paper status to paper out: + + # prn_example -paper_out + + +To set paper status to paper loaded: + + # prn_example -paper_loaded + + +To set error status to printer OK: + + # prn_example -no_error + + +To set error status to ERROR: + + # prn_example -error + + + + +EXAMPLE CODE +============ + + +#include <stdio.h> +#include <stdlib.h> +#include <fcntl.h> +#include <linux/poll.h> +#include <sys/ioctl.h> +#include <linux/usb/g_printer.h> + +#define PRINTER_FILE "/dev/g_printer" +#define BUF_SIZE 512 + + +/* + * 'usage()' - Show program usage. + */ + +static void +usage(const char *option) /* I - Option string or NULL */ +{ + if (option) { + fprintf(stderr,"prn_example: Unknown option \"%s\"!\n", + option); + } + + fputs("\n", stderr); + fputs("Usage: prn_example -[options]\n", stderr); + fputs("Options:\n", stderr); + fputs("\n", stderr); + fputs("-get_status Get the current printer status.\n", stderr); + fputs("-selected Set the selected status to selected.\n", stderr); + fputs("-not_selected Set the selected status to NOT selected.\n", + stderr); + fputs("-error Set the error status to error.\n", stderr); + fputs("-no_error Set the error status to NO error.\n", stderr); + fputs("-paper_out Set the paper status to paper out.\n", stderr); + fputs("-paper_loaded Set the paper status to paper loaded.\n", + stderr); + fputs("-read_data Read printer data from driver.\n", stderr); + fputs("-write_data Write printer sata to driver.\n", stderr); + fputs("-NB_read_data (Non-Blocking) Read printer data from driver.\n", + stderr); + fputs("\n\n", stderr); + + exit(1); +} + + +static int +read_printer_data() +{ + struct pollfd fd[1]; + + /* Open device file for printer gadget. */ + fd[0].fd = open(PRINTER_FILE, O_RDWR); + if (fd[0].fd < 0) { + printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } + + fd[0].events = POLLIN | POLLRDNORM; + + while (1) { + static char buf[BUF_SIZE]; + int bytes_read; + int retval; + + /* Wait for up to 1 second for data. */ + retval = poll(fd, 1, 1000); + + if (retval && (fd[0].revents & POLLRDNORM)) { + + /* Read data from printer gadget driver. */ + bytes_read = read(fd[0].fd, buf, BUF_SIZE); + + if (bytes_read < 0) { + printf("Error %d reading from %s\n", + fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } else if (bytes_read > 0) { + /* Write data to standard OUTPUT (stdout). */ + fwrite(buf, 1, bytes_read, stdout); + fflush(stdout); + } + + } + + } + + /* Close the device file. */ + close(fd[0].fd); + + return 0; +} + + +static int +write_printer_data() +{ + struct pollfd fd[1]; + + /* Open device file for printer gadget. */ + fd[0].fd = open (PRINTER_FILE, O_RDWR); + if (fd[0].fd < 0) { + printf("Error %d opening %s\n", fd[0].fd, PRINTER_FILE); + close(fd[0].fd); + return(-1); + } + + fd[0].events = POLLOUT | POLLWRNORM; + + while (1) { + int retval; + static char buf[BUF_SIZE]; + /* Read data from standard INPUT (stdin). */ + int bytes_read = fread(buf, 1, BUF_SIZE, stdin); + + if (!bytes_read) { + break; + } + + while (bytes_read) { + + /* Wait for up to 1 second to sent data. */ + retval = poll(fd, 1, 1000); + + /* Write data to printer gadget driver. */ + if (retval && (fd[0].revents & POLLWRNORM)) { + retval = write(fd[0].fd, buf, bytes_read); + if (retval < 0) { + printf("Error %d writing to %s\n", + fd[0].fd, + PRINTER_FILE); + close(fd[0].fd); + return(-1); + } else { + bytes_read -= retval; + } + + } + + } + + } + + /* Wait until the data has been sent. */ + fsync(fd[0].fd); + + /* Close the device file. */ + close(fd[0].fd); + + return 0; +} + + +static int +read_NB_printer_data() +{ + int fd; + static char buf[BUF_SIZE]; + int bytes_read; + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR|O_NONBLOCK); + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + while (1) { + /* Read data from printer gadget driver. */ + bytes_read = read(fd, buf, BUF_SIZE); + if (bytes_read <= 0) { + break; + } + + /* Write data to standard OUTPUT (stdout). */ + fwrite(buf, 1, bytes_read, stdout); + fflush(stdout); + } + + /* Close the device file. */ + close(fd); + + return 0; +} + + +static int +get_printer_status() +{ + int retval; + int fd; + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR); + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + /* Make the IOCTL call. */ + retval = ioctl(fd, GADGET_GET_PRINTER_STATUS); + if (retval < 0) { + fprintf(stderr, "ERROR: Failed to set printer status\n"); + return(-1); + } + + /* Close the device file. */ + close(fd); + + return(retval); +} + + +static int +set_printer_status(unsigned char buf, int clear_printer_status_bit) +{ + int retval; + int fd; + + retval = get_printer_status(); + if (retval < 0) { + fprintf(stderr, "ERROR: Failed to get printer status\n"); + return(-1); + } + + /* Open device file for printer gadget. */ + fd = open(PRINTER_FILE, O_RDWR); + + if (fd < 0) { + printf("Error %d opening %s\n", fd, PRINTER_FILE); + close(fd); + return(-1); + } + + if (clear_printer_status_bit) { + retval &= ~buf; + } else { + retval |= buf; + } + + /* Make the IOCTL call. */ + if (ioctl(fd, GADGET_SET_PRINTER_STATUS, (unsigned char)retval)) { + fprintf(stderr, "ERROR: Failed to set printer status\n"); + return(-1); + } + + /* Close the device file. */ + close(fd); + + return 0; +} + + +static int +display_printer_status() +{ + char printer_status; + + printer_status = get_printer_status(); + if (printer_status < 0) { + fprintf(stderr, "ERROR: Failed to get printer status\n"); + return(-1); + } + + printf("Printer status is:\n"); + if (printer_status & PRINTER_SELECTED) { + printf(" Printer is Selected\n"); + } else { + printf(" Printer is NOT Selected\n"); + } + if (printer_status & PRINTER_PAPER_EMPTY) { + printf(" Paper is Out\n"); + } else { + printf(" Paper is Loaded\n"); + } + if (printer_status & PRINTER_NOT_ERROR) { + printf(" Printer OK\n"); + } else { + printf(" Printer ERROR\n"); + } + + return(0); +} + + +int +main(int argc, char *argv[]) +{ + int i; /* Looping var */ + int retval = 0; + + /* No Args */ + if (argc == 1) { + usage(0); + exit(0); + } + + for (i = 1; i < argc && !retval; i ++) { + + if (argv[i][0] != '-') { + continue; + } + + if (!strcmp(argv[i], "-get_status")) { + if (display_printer_status()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-paper_loaded")) { + if (set_printer_status(PRINTER_PAPER_EMPTY, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-paper_out")) { + if (set_printer_status(PRINTER_PAPER_EMPTY, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-selected")) { + if (set_printer_status(PRINTER_SELECTED, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-not_selected")) { + if (set_printer_status(PRINTER_SELECTED, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-error")) { + if (set_printer_status(PRINTER_NOT_ERROR, 1)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-no_error")) { + if (set_printer_status(PRINTER_NOT_ERROR, 0)) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-read_data")) { + if (read_printer_data()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-write_data")) { + if (write_printer_data()) { + retval = 1; + } + + } else if (!strcmp(argv[i], "-NB_read_data")) { + if (read_NB_printer_data()) { + retval = 1; + } + + } else { + usage(argv[i]); + retval = 1; + } + } + + exit(retval); +} diff --git a/Documentation/usb/iuu_phoenix.txt b/Documentation/usb/iuu_phoenix.txt new file mode 100644 index 0000000..e5f0480 --- /dev/null +++ b/Documentation/usb/iuu_phoenix.txt @@ -0,0 +1,84 @@ +Infinity Usb Unlimited Readme +----------------------------- + +Hi all, + + +This module provide a serial interface to use your +IUU unit in phoenix mode. Loading this module will +bring a ttyUSB[0-x] interface. This driver must be +used by your favorite application to pilot the IUU + +This driver is still in beta stage, so bugs can +occur and your system may freeze. As far I now, +I never had any problem with it, but I'm not a real +guru, so don't blame me if your system is unstable + +You can plug more than one IUU. Every unit will +have his own device file(/dev/ttyUSB0,/dev/ttyUSB1,...) + + + +How to tune the reader speed ? + + A few parameters can be used at load time + To use parameters, just unload the module if it is + already loaded and use modprobe iuu_phoenix param=value. + In case of prebuilt module, use the command + insmod iuu_phoenix param=value. + + Example: + + modprobe iuu_phoenix clockmode=3 + + The parameters are: + + parm: clockmode:1=3Mhz579,2=3Mhz680,3=6Mhz (int) + parm: boost:overclock boost percent 100 to 500 (int) + parm: cdmode:Card detect mode 0=none, 1=CD, 2=!CD, 3=DSR, 4=!DSR, 5=CTS, 6=!CTS, 7=RING, 8=!RING (int) + parm: xmas:xmas color enabled or not (bool) + parm: debug:Debug enabled or not (bool) + +- clockmode will provide 3 different base settings commonly adopted by + different software: + 1. 3Mhz579 + 2. 3Mhz680 + 3. 6Mhz + +- boost provide a way to overclock the reader ( my favorite :-) ) + For example to have best performance than a simple clockmode=3, try this: + + modprobe boost=195 + + This will put the reader in a base of 3Mhz579 but boosted a 195 % ! + the real clock will be now : 6979050 Hz ( 6Mhz979 ) and will increase + the speed to a score 10 to 20% better than the simple clockmode=3 !!! + + +- cdmode permit to setup the signal used to inform the userland ( ioctl answer ) + if the card is present or not. Eight signals are possible. + +- xmas is completely useless except for your eyes. This is one of my friend who was + so sad to have a nice device like the iuu without seeing all color range available. + So I have added this option to permit him to see a lot of color ( each activity change the color + and the frequency randomly ) + +- debug will produce a lot of debugging messages... + + + Last notes: + + Don't worry about the serial settings, the serial emulation + is an abstraction, so use any speed or parity setting will + work. ( This will not change anything ).Later I will perhaps + use this settings to deduce de boost but is that feature + really necessary ? + The autodetect feature used is the serial CD. If that doesn't + work for your software, disable detection mechanism in it. + + + Have fun ! + + Alain Degreffe + + eczema(at)ecze.com diff --git a/Documentation/vm/slabinfo.c b/Documentation/vm/slabinfo.c index 488c1f3..7123fee 100644 --- a/Documentation/vm/slabinfo.c +++ b/Documentation/vm/slabinfo.c @@ -32,6 +32,13 @@ struct slabinfo { int sanity_checks, slab_size, store_user, trace; int order, poison, reclaim_account, red_zone; unsigned long partial, objects, slabs; + unsigned long alloc_fastpath, alloc_slowpath; + unsigned long free_fastpath, free_slowpath; + unsigned long free_frozen, free_add_partial, free_remove_partial; + unsigned long alloc_from_partial, alloc_slab, free_slab, alloc_refill; + unsigned long cpuslab_flush, deactivate_full, deactivate_empty; + unsigned long deactivate_to_head, deactivate_to_tail; + unsigned long deactivate_remote_frees; int numa[MAX_NODES]; int numa_partial[MAX_NODES]; } slabinfo[MAX_SLABS]; @@ -64,8 +71,10 @@ int show_inverted = 0; int show_single_ref = 0; int show_totals = 0; int sort_size = 0; +int sort_active = 0; int set_debug = 0; int show_ops = 0; +int show_activity = 0; /* Debug options */ int sanity = 0; @@ -93,8 +102,10 @@ void usage(void) printf("slabinfo 5/7/2007. (c) 2007 sgi. clameter@sgi.com\n\n" "slabinfo [-ahnpvtsz] [-d debugopts] [slab-regexp]\n" "-a|--aliases Show aliases\n" + "-A|--activity Most active slabs first\n" "-d<options>|--debug=<options> Set/Clear Debug options\n" - "-e|--empty Show empty slabs\n" + "-D|--display-active Switch line format to activity\n" + "-e|--empty Show empty slabs\n" "-f|--first-alias Show first alias\n" "-h|--help Show usage information\n" "-i|--inverted Inverted list\n" @@ -281,8 +292,11 @@ int line = 0; void first_line(void) { - printf("Name Objects Objsize Space " - "Slabs/Part/Cpu O/S O %%Fr %%Ef Flg\n"); + if (show_activity) + printf("Name Objects Alloc Free %%Fast\n"); + else + printf("Name Objects Objsize Space " + "Slabs/Part/Cpu O/S O %%Fr %%Ef Flg\n"); } /* @@ -309,6 +323,12 @@ unsigned long slab_size(struct slabinfo *s) return s->slabs * (page_size << s->order); } +unsigned long slab_activity(struct slabinfo *s) +{ + return s->alloc_fastpath + s->free_fastpath + + s->alloc_slowpath + s->free_slowpath; +} + void slab_numa(struct slabinfo *s, int mode) { int node; @@ -392,6 +412,71 @@ const char *onoff(int x) return "Off"; } +void slab_stats(struct slabinfo *s) +{ + unsigned long total_alloc; + unsigned long total_free; + unsigned long total; + + if (!s->alloc_slab) + return; + + total_alloc = s->alloc_fastpath + s->alloc_slowpath; + total_free = s->free_fastpath + s->free_slowpath; + + if (!total_alloc) + return; + + printf("\n"); + printf("Slab Perf Counter Alloc Free %%Al %%Fr\n"); + printf("--------------------------------------------------\n"); + printf("Fastpath %8lu %8lu %3lu %3lu\n", + s->alloc_fastpath, s->free_fastpath, + s->alloc_fastpath * 100 / total_alloc, + s->free_fastpath * 100 / total_free); + printf("Slowpath %8lu %8lu %3lu %3lu\n", + total_alloc - s->alloc_fastpath, s->free_slowpath, + (total_alloc - s->alloc_fastpath) * 100 / total_alloc, + s->free_slowpath * 100 / total_free); + printf("Page Alloc %8lu %8lu %3lu %3lu\n", + s->alloc_slab, s->free_slab, + s->alloc_slab * 100 / total_alloc, + s->free_slab * 100 / total_free); + printf("Add partial %8lu %8lu %3lu %3lu\n", + s->deactivate_to_head + s->deactivate_to_tail, + s->free_add_partial, + (s->deactivate_to_head + s->deactivate_to_tail) * 100 / total_alloc, + s->free_add_partial * 100 / total_free); + printf("Remove partial %8lu %8lu %3lu %3lu\n", + s->alloc_from_partial, s->free_remove_partial, + s->alloc_from_partial * 100 / total_alloc, + s->free_remove_partial * 100 / total_free); + + printf("RemoteObj/SlabFrozen %8lu %8lu %3lu %3lu\n", + s->deactivate_remote_frees, s->free_frozen, + s->deactivate_remote_frees * 100 / total_alloc, + s->free_frozen * 100 / total_free); + + printf("Total %8lu %8lu\n\n", total_alloc, total_free); + + if (s->cpuslab_flush) + printf("Flushes %8lu\n", s->cpuslab_flush); + + if (s->alloc_refill) + printf("Refill %8lu\n", s->alloc_refill); + + total = s->deactivate_full + s->deactivate_empty + + s->deactivate_to_head + s->deactivate_to_tail; + + if (total) + printf("Deactivate Full=%lu(%lu%%) Empty=%lu(%lu%%) " + "ToHead=%lu(%lu%%) ToTail=%lu(%lu%%)\n", + s->deactivate_full, (s->deactivate_full * 100) / total, + s->deactivate_empty, (s->deactivate_empty * 100) / total, + s->deactivate_to_head, (s->deactivate_to_head * 100) / total, + s->deactivate_to_tail, (s->deactivate_to_tail * 100) / total); +} + void report(struct slabinfo *s) { if (strcmp(s->name, "*") == 0) @@ -430,6 +515,7 @@ void report(struct slabinfo *s) ops(s); show_tracking(s); slab_numa(s, 1); + slab_stats(s); } void slabcache(struct slabinfo *s) @@ -479,13 +565,27 @@ void slabcache(struct slabinfo *s) *p++ = 'T'; *p = 0; - printf("%-21s %8ld %7d %8s %14s %4d %1d %3ld %3ld %s\n", - s->name, s->objects, s->object_size, size_str, dist_str, - s->objs_per_slab, s->order, - s->slabs ? (s->partial * 100) / s->slabs : 100, - s->slabs ? (s->objects * s->object_size * 100) / - (s->slabs * (page_size << s->order)) : 100, - flags); + if (show_activity) { + unsigned long total_alloc; + unsigned long total_free; + + total_alloc = s->alloc_fastpath + s->alloc_slowpath; + total_free = s->free_fastpath + s->free_slowpath; + + printf("%-21s %8ld %8ld %8ld %3ld %3ld \n", + s->name, s->objects, + total_alloc, total_free, + total_alloc ? (s->alloc_fastpath * 100 / total_alloc) : 0, + total_free ? (s->free_fastpath * 100 / total_free) : 0); + } + else + printf("%-21s %8ld %7d %8s %14s %4d %1d %3ld %3ld %s\n", + s->name, s->objects, s->object_size, size_str, dist_str, + s->objs_per_slab, s->order, + s->slabs ? (s->partial * 100) / s->slabs : 100, + s->slabs ? (s->objects * s->object_size * 100) / + (s->slabs * (page_size << s->order)) : 100, + flags); } /* @@ -892,6 +992,8 @@ void sort_slabs(void) if (sort_size) result = slab_size(s1) < slab_size(s2); + else if (sort_active) + result = slab_activity(s1) < slab_activity(s2); else result = strcasecmp(s1->name, s2->name); @@ -1074,6 +1176,23 @@ void read_slab_dir(void) free(t); slab->store_user = get_obj("store_user"); slab->trace = get_obj("trace"); + slab->alloc_fastpath = get_obj("alloc_fastpath"); + slab->alloc_slowpath = get_obj("alloc_slowpath"); + slab->free_fastpath = get_obj("free_fastpath"); + slab->free_slowpath = get_obj("free_slowpath"); + slab->free_frozen= get_obj("free_frozen"); + slab->free_add_partial = get_obj("free_add_partial"); + slab->free_remove_partial = get_obj("free_remove_partial"); + slab->alloc_from_partial = get_obj("alloc_from_partial"); + slab->alloc_slab = get_obj("alloc_slab"); + slab->alloc_refill = get_obj("alloc_refill"); + slab->free_slab = get_obj("free_slab"); + slab->cpuslab_flush = get_obj("cpuslab_flush"); + slab->deactivate_full = get_obj("deactivate_full"); + slab->deactivate_empty = get_obj("deactivate_empty"); + slab->deactivate_to_head = get_obj("deactivate_to_head"); + slab->deactivate_to_tail = get_obj("deactivate_to_tail"); + slab->deactivate_remote_frees = get_obj("deactivate_remote_frees"); chdir(".."); if (slab->name[0] == ':') alias_targets++; @@ -1124,7 +1243,9 @@ void output_slabs(void) struct option opts[] = { { "aliases", 0, NULL, 'a' }, + { "activity", 0, NULL, 'A' }, { "debug", 2, NULL, 'd' }, + { "display-activity", 0, NULL, 'D' }, { "empty", 0, NULL, 'e' }, { "first-alias", 0, NULL, 'f' }, { "help", 0, NULL, 'h' }, @@ -1149,7 +1270,7 @@ int main(int argc, char *argv[]) page_size = getpagesize(); - while ((c = getopt_long(argc, argv, "ad::efhil1noprstvzTS", + while ((c = getopt_long(argc, argv, "aAd::Defhil1noprstvzTS", opts, NULL)) != -1) switch (c) { case '1': @@ -1158,11 +1279,17 @@ int main(int argc, char *argv[]) case 'a': show_alias = 1; break; + case 'A': + sort_active = 1; + break; case 'd': set_debug = 1; if (!debug_opt_scan(optarg)) fatal("Invalid debug option '%s'\n", optarg); break; + case 'D': + show_activity = 1; + break; case 'e': show_empty = 1; break; diff --git a/Documentation/w1/masters/00-INDEX b/Documentation/w1/masters/00-INDEX index 752613c..7b0ceaa 100644 --- a/Documentation/w1/masters/00-INDEX +++ b/Documentation/w1/masters/00-INDEX @@ -4,3 +4,5 @@ ds2482 - The Maxim/Dallas Semiconductor DS2482 provides 1-wire busses. ds2490 - The Maxim/Dallas Semiconductor DS2490 builds USB <-> W1 bridges. +w1-gpio + - GPIO 1-wire bus master driver. diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio new file mode 100644 index 0000000..af5d3b4 --- /dev/null +++ b/Documentation/w1/masters/w1-gpio @@ -0,0 +1,33 @@ +Kernel driver w1-gpio +===================== + +Author: Ville Syrjala <syrjala@sci.fi> + + +Description +----------- + +GPIO 1-wire bus master driver. The driver uses the GPIO API to control the +wire and the GPIO pin can be specified using platform data. + + +Example (mach-at91) +------------------- + +#include <linux/w1-gpio.h> + +static struct w1_gpio_platform_data foo_w1_gpio_pdata = { + .pin = AT91_PIN_PB20, + .is_open_drain = 1, +}; + +static struct platform_device foo_w1_device = { + .name = "w1-gpio", + .id = -1, + .dev.platform_data = &foo_w1_gpio_pdata, +}; + +... + at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); + at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); + platform_device_register(&foo_w1_device); diff --git a/Documentation/x86_64/00-INDEX b/Documentation/x86_64/00-INDEX new file mode 100644 index 0000000..92fc20a --- /dev/null +++ b/Documentation/x86_64/00-INDEX @@ -0,0 +1,16 @@ +00-INDEX + - This file +boot-options.txt + - AMD64-specific boot options. +cpu-hotplug-spec + - Firmware support for CPU hotplug under Linux/x86-64 +fake-numa-for-cpusets + - Using numa=fake and CPUSets for Resource Management +kernel-stacks + - Context-specific per-processor interrupt stacks. +machinecheck + - Configurable sysfs parameters for the x86-64 machine check code. +mm.txt + - Memory layout of x86-64 (4 level page tables, 46 bits physical). +uefi.txt + - Booting Linux via Unified Extensible Firmware Interface. |
