diff options
Diffstat (limited to 'Documentation')
40 files changed, 1138 insertions, 318 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 8dfc6708a257..f607367e642f 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -328,8 +328,6 @@ sysrq.txt - info on the magic SysRq key. telephony/ - directory with info on telephony (e.g. voice over IP) support. -time_interpolators.txt - - info on time interpolators. uml/ - directory with information about User Mode Linux. unicode.txt @@ -346,8 +344,6 @@ vm/ - directory with info on the Linux vm code. volatile-considered-harmful.txt - Why the "volatile" type class should not be used -voyager.txt - - guide to running Linux on the Voyager architecture. w1/ - directory with documents regarding the 1-wire (w1) subsystem. watchdog/ diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars new file mode 100644 index 000000000000..5def20b9019e --- /dev/null +++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars @@ -0,0 +1,75 @@ +What: /sys/firmware/efi/vars +Date: April 2004 +Contact: Matt Domsch <Matt_Domsch@dell.com> +Description: + This directory exposes interfaces for interactive with + EFI variables. For more information on EFI variables, + see 'Variable Services' in the UEFI specification + (section 7.2 in specification version 2.3 Errata D). + + In summary, EFI variables are named, and are classified + into separate namespaces through the use of a vendor + GUID. They also have an arbitrary binary value + associated with them. + + The efivars module enumerates these variables and + creates a separate directory for each one found. Each + directory has a name of the form "<key>-<vendor guid>" + and contains the following files: + + attributes: A read-only text file enumerating the + EFI variable flags. Potential values + include: + + EFI_VARIABLE_NON_VOLATILE + EFI_VARIABLE_BOOTSERVICE_ACCESS + EFI_VARIABLE_RUNTIME_ACCESS + EFI_VARIABLE_HARDWARE_ERROR_RECORD + EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS + + See the EFI documentation for an + explanation of each of these variables. + + data: A read-only binary file that can be read + to attain the value of the EFI variable + + guid: The vendor GUID of the variable. This + should always match the GUID in the + variable's name. + + raw_var: A binary file that can be read to obtain + a structure that contains everything + there is to know about the variable. + For structure definition see "struct + efi_variable" in the kernel sources. + + This file can also be written to in + order to update the value of a variable. + For this to work however, all fields of + the "struct efi_variable" passed must + match byte for byte with the structure + read out of the file, save for the value + portion. + + **Note** the efi_variable structure + read/written with this file contains a + 'long' type that may change widths + depending on your underlying + architecture. + + size: As ASCII representation of the size of + the variable's value. + + + In addition, two other magic binary files are provided + in the top-level directory and are used for adding and + removing variables: + + new_var: Takes a "struct efi_variable" and + instructs the EFI firmware to create a + new variable. + + del_var: Takes a "struct efi_variable" and + instructs the EFI firmware to remove any + variable that has a matching vendor GUID + and variable key name. diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power index 7628cd1bc36a..8ffbc25376a0 100644 --- a/Documentation/ABI/testing/sysfs-devices-power +++ b/Documentation/ABI/testing/sysfs-devices-power @@ -29,9 +29,8 @@ Description: "disabled" to it. For the devices that are not capable of generating system wakeup - events this file contains "\n". In that cases the user space - cannot modify the contents of this file and the device cannot be - enabled to wake up the system. + events this file is not present. In that case the device cannot + be enabled to wake up the system from sleep states. What: /sys/devices/.../power/control Date: January 2009 @@ -85,7 +84,7 @@ Description: The /sys/devices/.../wakeup_count attribute contains the number of signaled wakeup events associated with the device. This attribute is read-only. If the device is not enabled to wake up - the system from sleep states, this attribute is empty. + the system from sleep states, this attribute is not present. What: /sys/devices/.../power/wakeup_active_count Date: September 2010 @@ -95,7 +94,7 @@ Description: number of times the processing of wakeup events associated with the device was completed (at the kernel level). This attribute is read-only. If the device is not enabled to wake up the - system from sleep states, this attribute is empty. + system from sleep states, this attribute is not present. What: /sys/devices/.../power/wakeup_hit_count Date: September 2010 @@ -105,7 +104,8 @@ Description: number of times the processing of a wakeup event associated with the device might prevent the system from entering a sleep state. This attribute is read-only. If the device is not enabled to - wake up the system from sleep states, this attribute is empty. + wake up the system from sleep states, this attribute is not + present. What: /sys/devices/.../power/wakeup_active Date: September 2010 @@ -115,7 +115,7 @@ Description: or 0, depending on whether or not a wakeup event associated with the device is being processed (1). This attribute is read-only. If the device is not enabled to wake up the system from sleep - states, this attribute is empty. + states, this attribute is not present. What: /sys/devices/.../power/wakeup_total_time_ms Date: September 2010 @@ -125,7 +125,7 @@ Description: the total time of processing wakeup events associated with the device, in milliseconds. This attribute is read-only. If the device is not enabled to wake up the system from sleep states, - this attribute is empty. + this attribute is not present. What: /sys/devices/.../power/wakeup_max_time_ms Date: September 2010 @@ -135,7 +135,7 @@ Description: the maximum time of processing a single wakeup event associated with the device, in milliseconds. This attribute is read-only. If the device is not enabled to wake up the system from sleep - states, this attribute is empty. + states, this attribute is not present. What: /sys/devices/.../power/wakeup_last_time_ms Date: September 2010 @@ -146,7 +146,7 @@ Description: signaling the last wakeup event associated with the device, in milliseconds. This attribute is read-only. If the device is not enabled to wake up the system from sleep states, this - attribute is empty. + attribute is not present. What: /sys/devices/.../power/autosuspend_delay_ms Date: September 2010 diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi b/Documentation/ABI/testing/sysfs-firmware-dmi new file mode 100644 index 000000000000..ba9da9503c23 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-dmi @@ -0,0 +1,110 @@ +What: /sys/firmware/dmi/ +Date: February 2011 +Contact: Mike Waychison <mikew@google.com> +Description: + Many machines' firmware (x86 and ia64) export DMI / + SMBIOS tables to the operating system. Getting at this + information is often valuable to userland, especially in + cases where there are OEM extensions used. + + The kernel itself does not rely on the majority of the + information in these tables being correct. It equally + cannot ensure that the data as exported to userland is + without error either. + + DMI is structured as a large table of entries, where + each entry has a common header indicating the type and + length of the entry, as well as 'handle' that is + supposed to be unique amongst all entries. + + Some entries are required by the specification, but many + others are optional. In general though, users should + never expect to find a specific entry type on their + system unless they know for certain what their firmware + is doing. Machine to machine will vary. + + Multiple entries of the same type are allowed. In order + to handle these duplicate entry types, each entry is + assigned by the operating system an 'instance', which is + derived from an entry type's ordinal position. That is + to say, if there are 'N' multiple entries with the same type + 'T' in the DMI tables (adjacent or spread apart, it + doesn't matter), they will be represented in sysfs as + entries "T-0" through "T-(N-1)": + + Example entry directories: + + /sys/firmware/dmi/entries/17-0 + /sys/firmware/dmi/entries/17-1 + /sys/firmware/dmi/entries/17-2 + /sys/firmware/dmi/entries/17-3 + ... + + Instance numbers are used in lieu of the firmware + assigned entry handles as the kernel itself makes no + guarantees that handles as exported are unique, and + there are likely firmware images that get this wrong in + the wild. + + Each DMI entry in sysfs has the common header values + exported as attributes: + + handle : The 16bit 'handle' that is assigned to this + entry by the firmware. This handle may be + referred to by other entries. + length : The length of the entry, as presented in the + entry itself. Note that this is _not the + total count of bytes associated with the + entry_. This value represents the length of + the "formatted" portion of the entry. This + "formatted" region is sometimes followed by + the "unformatted" region composed of nul + terminated strings, with termination signalled + by a two nul characters in series. + raw : The raw bytes of the entry. This includes the + "formatted" portion of the entry, the + "unformatted" strings portion of the entry, + and the two terminating nul characters. + type : The type of the entry. This value is the same + as found in the directory name. It indicates + how the rest of the entry should be + interpreted. + instance: The instance ordinal of the entry for the + given type. This value is the same as found + in the parent directory name. + position: The position of the entry within the entirety + of the entirety. + + === Entry Specialization === + + Some entry types may have other information available in + sysfs. + + --- Type 15 - System Event Log --- + + This entry allows the firmware to export a log of + events the system has taken. This information is + typically backed by nvram, but the implementation + details are abstracted by this table. This entries data + is exported in the directory: + + /sys/firmware/dmi/entries/15-0/system_event_log + + and has the following attributes (documented in the + SMBIOS / DMI specification under "System Event Log (Type 15)": + + area_length + header_start_offset + data_start_offset + access_method + status + change_token + access_method_address + header_format + per_log_type_descriptor_length + type_descriptors_supported_count + + As well, the kernel exports the binary attribute: + + raw_event_log : The raw binary bits of the event log + as described by the DMI entry. diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim new file mode 100644 index 000000000000..c1653271872a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-kim @@ -0,0 +1,48 @@ +What: /sys/devices/platform/kim/dev_name +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + Name of the UART device at which the WL128x chip + is connected. example: "/dev/ttyS0". + The device name flows down to architecture specific board + initialization file from the SFI/ATAGS bootloader + firmware. The name exposed is read from the user-space + dameon and opens the device when install is requested. + +What: /sys/devices/platform/kim/baud_rate +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The maximum reliable baud-rate the host can support. + Different platforms tend to have different high-speed + UART configurations, so the baud-rate needs to be set + locally and also sent across to the WL128x via a HCI-VS + command. The entry is read and made use by the user-space + daemon when the ldisc install is requested. + +What: /sys/devices/platform/kim/flow_cntrl +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The WL128x makes use of flow control mechanism, and this + entry most often should be 1, the host's UART is required + to have the capability of flow-control, or else this + entry can be made use of for exceptions. + +What: /sys/devices/platform/kim/install +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + When one of the protocols Bluetooth, FM or GPS wants to make + use of the shared UART transport, it registers to the shared + transport driver, which will signal the user-space for opening, + configuring baud and install line discipline via this sysfs + entry. This entry would be polled upon by the user-space + daemon managing the UART, and is notified about the change + by the sysfs_notify. The value would be '1' when UART needs + to be opened/ldisc installed, and would be '0' when UART + is no more required and needs to be closed. diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 8bb37237ebd2..1cd3478e5834 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -659,7 +659,7 @@ There are a number of driver model diagnostic macros in <linux/device.h> which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a -particular device, <linux/kernel.h> defines pr_debug() and pr_info(). +particular device, <linux/printk.h> defines pr_debug() and pr_info(). Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. Such @@ -819,6 +819,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ --- -Last updated on 2007-July-13. - diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index cfaac34c4557..6ef692667e2f 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -849,6 +849,37 @@ All: lockdep-checked RCU-protected pointer access See the comment headers in the source code (or the docbook generated from them) for more information. +However, given that there are no fewer than four families of RCU APIs +in the Linux kernel, how do you choose which one to use? The following +list can be helpful: + +a. Will readers need to block? If so, you need SRCU. + +b. What about the -rt patchset? If readers would need to block + in an non-rt kernel, you need SRCU. If readers would block + in a -rt kernel, but not in a non-rt kernel, SRCU is not + necessary. + +c. Do you need to treat NMI handlers, hardirq handlers, + and code segments with preemption disabled (whether + via preempt_disable(), local_irq_save(), local_bh_disable(), + or some other mechanism) as if they were explicit RCU readers? + If so, you need RCU-sched. + +d. Do you need RCU grace periods to complete even in the face + of softirq monopolization of one or more of the CPUs? For + example, is your code subject to network-based denial-of-service + attacks? If so, you need RCU-bh. + +e. Is your workload too update-intensive for normal use of + RCU, but inappropriate for other synchronization mechanisms? + If so, consider SLAB_DESTROY_BY_RCU. But please be careful! + +f. Otherwise, use RCU. + +Of course, this all assumes that you have determined that RCU is in fact +the right tool for your job. + 8. ANSWERS TO QUICK QUIZZES diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index 44b8b7af8019..cbdfb7d9455b 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -349,6 +349,10 @@ To mount a cgroup hierarchy with all available subsystems, type: The "xxx" is not interpreted by the cgroup code, but will appear in /proc/mounts so may be any useful identifying string that you like. +Note: Some subsystems do not work without some user input first. For instance, +if cpusets are enabled the user will have to populate the cpus and mems files +for each new cgroup created before that group can be used. + To mount a cgroup hierarchy with just the cpuset and memory subsystems, type: # mount -t cgroup -o cpuset,memory hier1 /dev/cgroup @@ -426,6 +430,14 @@ You can attach the current shell task by echoing 0: # echo 0 > tasks +Note: Since every task is always a member of exactly one cgroup in each +mounted hierarchy, to remove a task from its current cgroup you must +move it into a new cgroup (possibly the root cgroup) by writing to the +new cgroup's tasks file. + +Note: If the ns cgroup is active, moving a process to another cgroup can +fail. + 2.3 Mounting hierarchies by name -------------------------------- diff --git a/Documentation/devicetree/00-INDEX b/Documentation/devicetree/00-INDEX new file mode 100644 index 000000000000..b78f691fd847 --- /dev/null +++ b/Documentation/devicetree/00-INDEX @@ -0,0 +1,10 @@ +Documentation for device trees, a data structure by which bootloaders pass +hardware layout to Linux in a device-independent manner, simplifying hardware +probing. This subsystem is maintained by Grant Likely +<grant.likely@secretlab.ca> and has a mailing list at +https://lists.ozlabs.org/listinfo/devicetree-discuss + +00-INDEX + - this file +booting-without-of.txt + - Booting Linux without Open Firmware, describes history and format of device trees. diff --git a/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt b/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt new file mode 100644 index 000000000000..569b16248514 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/ce4100-i2c.txt @@ -0,0 +1,93 @@ +CE4100 I2C +---------- + +CE4100 has one PCI device which is described as the I2C-Controller. This +PCI device has three PCI-bars, each bar contains a complete I2C +controller. So we have a total of three independent I2C-Controllers +which share only an interrupt line. +The driver is probed via the PCI-ID and is gathering the information of +attached devices from the devices tree. +Grant Likely recommended to use the ranges property to map the PCI-Bar +number to its physical address and to use this to find the child nodes +of the specific I2C controller. This were his exact words: + + Here's where the magic happens. Each entry in + ranges describes how the parent pci address space + (middle group of 3) is translated to the local + address space (first group of 2) and the size of + each range (last cell). In this particular case, + the first cell of the local address is chosen to be + 1:1 mapped to the BARs, and the second is the + offset from be base of the BAR (which would be + non-zero if you had 2 or more devices mapped off + the same BAR) + + ranges allows the address mapping to be described + in a way that the OS can interpret without + requiring custom device driver code. + +This is an example which is used on FalconFalls: +------------------------------------------------ + i2c-controller@b,2 { + #address-cells = <2>; + #size-cells = <1>; + compatible = "pci8086,2e68.2", + "pci8086,2e68", + "pciclass,ff0000", + "pciclass,ff00"; + + reg = <0x15a00 0x0 0x0 0x0 0x0>; + interrupts = <16 1>; + + /* as described by Grant, the first number in the group of + * three is the bar number followed by the 64bit bar address + * followed by size of the mapping. The bar address + * requires also a valid translation in parents ranges + * property. + */ + ranges = <0 0 0x02000000 0 0xdffe0500 0x100 + 1 0 0x02000000 0 0xdffe0600 0x100 + 2 0 0x02000000 0 0xdffe0700 0x100>; + + i2c@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + + /* The first number in the reg property is the + * number of the bar + */ + reg = <0 0 0x100>; + + /* This I2C controller has no devices */ + }; + + i2c@1 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + reg = <1 0 0x100>; + + /* This I2C controller has one gpio controller */ + gpio@26 { + #gpio-cells = <2>; + compatible = "ti,pcf8575"; + reg = <0x26>; + gpio-controller; + }; + }; + + i2c@2 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "intel,ce4100-i2c-controller"; + reg = <2 0 0x100>; + + gpio@26 { + #gpio-cells = <2>; + compatible = "ti,pcf8575"; + reg = <0x26>; + gpio-controller; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/rtc/rtc-cmos.txt b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt new file mode 100644 index 000000000000..7382989b3052 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-cmos.txt @@ -0,0 +1,28 @@ + Motorola mc146818 compatible RTC +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Required properties: + - compatible : "motorola,mc146818" + - reg : should contain registers location and length. + +Optional properties: + - interrupts : should contain interrupt. + - interrupt-parent : interrupt source phandle. + - ctrl-reg : Contains the initial value of the control register also + called "Register B". + - freq-reg : Contains the initial value of the frequency register also + called "Regsiter A". + +"Register A" and "B" are usually initialized by the firmware (BIOS for +instance). If this is not done, it can be performed by the driver. + +ISA Example: + + rtc@70 { + compatible = "motorola,mc146818"; + interrupts = <8 3>; + interrupt-parent = <&ioapic1>; + ctrl-reg = <2>; + freq-reg = <0x26>; + reg = <1 0x70 2>; + }; diff --git a/Documentation/devicetree/bindings/x86/ce4100.txt b/Documentation/devicetree/bindings/x86/ce4100.txt new file mode 100644 index 000000000000..b49ae593a60b --- /dev/null +++ b/Documentation/devicetree/bindings/x86/ce4100.txt @@ -0,0 +1,38 @@ +CE4100 Device Tree Bindings +--------------------------- + +The CE4100 SoC uses for in core peripherals the following compatible +format: <vendor>,<chip>-<device>. +Many of the "generic" devices like HPET or IO APIC have the ce4100 +name in their compatible property because they first appeared in this +SoC. + +The CPU node +------------ + cpu@0 { + device_type = "cpu"; + compatible = "intel,ce4100"; + reg = <0>; + lapic = <&lapic0>; + }; + +The reg property describes the CPU number. The lapic property points to +the local APIC timer. + +The SoC node +------------ + +This node describes the in-core peripherals. Required property: + compatible = "intel,ce4100-cp"; + +The PCI node +------------ +This node describes the PCI bus on the SoC. Its property should be + compatible = "intel,ce4100-pci", "pci"; + +If the OS is using the IO-APIC for interrupt routing then the reported +interrupt numbers for devices is no longer true. In order to obtain the +correct interrupt number, the child node which represents the device has +to contain the interrupt property. Besides the interrupt property it has +to contain at least the reg property containing the PCI bus address and +compatible property according to "PCI Bus Binding Revision 2.1". diff --git a/Documentation/devicetree/bindings/x86/interrupt.txt b/Documentation/devicetree/bindings/x86/interrupt.txt new file mode 100644 index 000000000000..7d19f494f19a --- /dev/null +++ b/Documentation/devicetree/bindings/x86/interrupt.txt @@ -0,0 +1,26 @@ +Interrupt chips +--------------- + +* Intel I/O Advanced Programmable Interrupt Controller (IO APIC) + + Required properties: + -------------------- + compatible = "intel,ce4100-ioapic"; + #interrupt-cells = <2>; + + Device's interrupt property: + + interrupts = <P S>; + + The first number (P) represents the interrupt pin which is wired to the + IO APIC. The second number (S) represents the sense of interrupt which + should be configured and can be one of: + 0 - Edge Rising + 1 - Level Low + 2 - Level High + 3 - Edge Falling + +* Local APIC + Required property: + + compatible = "intel,ce4100-lapic"; diff --git a/Documentation/devicetree/bindings/x86/timer.txt b/Documentation/devicetree/bindings/x86/timer.txt new file mode 100644 index 000000000000..c688af58e3bd --- /dev/null +++ b/Documentation/devicetree/bindings/x86/timer.txt @@ -0,0 +1,6 @@ +Timers +------ + +* High Precision Event Timer (HPET) + Required property: + compatible = "intel,ce4100-hpet"; diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt index 28b1c9d3d351..55fd2623445b 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.txt @@ -13,6 +13,7 @@ Table of Contents I - Introduction 1) Entry point for arch/powerpc + 2) Entry point for arch/x86 II - The DT block format 1) Header @@ -225,6 +226,25 @@ it with special cases. cannot support both configurations with Book E and configurations with classic Powerpc architectures. +2) Entry point for arch/x86 +------------------------------- + + There is one single 32bit entry point to the kernel at code32_start, + the decompressor (the real mode entry point goes to the same 32bit + entry point once it switched into protected mode). That entry point + supports one calling convention which is documented in + Documentation/x86/boot.txt + The physical pointer to the device-tree block (defined in chapter II) + is passed via setup_data which requires at least boot protocol 2.09. + The type filed is defined as + + #define SETUP_DTB 2 + + This device-tree is used as an extension to the "boot page". As such it + does not parse / consider data which is already covered by the boot + page. This includes memory size, reserved ranges, command line arguments + or initrd address. It simply holds information which can not be retrieved + otherwise like interrupt routing or a list of devices behind an I2C bus. II - The DT block format ======================== diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt index 58ea64a96165..e6c4b757025b 100644 --- a/Documentation/dynamic-debug-howto.txt +++ b/Documentation/dynamic-debug-howto.txt @@ -205,12 +205,20 @@ of the characters: The flags are: +f + Include the function name in the printed message +l + Include line number in the printed message +m + Include module name in the printed message p Causes a printk() message to be emitted to dmesg +t + Include thread ID in messages not generated from interrupt context -Note the regexp ^[-+=][scp]+$ matches a flags specification. +Note the regexp ^[-+=][flmpt]+$ matches a flags specification. Note also that there is no convenient syntax to remove all -the flags at once, you need to use "-psc". +the flags at once, you need to use "-flmpt". Debug messages during boot process diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 5d1335faec2d..f806e50aaa63 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -39,10 +39,12 @@ userspace. Top-level directories in sysfs represent the common ancestors of object hierarchies; i.e. the subsystems the objects belong to. -Sysfs internally stores the kobject that owns the directory in the -->d_fsdata pointer of the directory's dentry. This allows sysfs to do -reference counting directly on the kobject when the file is opened and -closed. +Sysfs internally stores a pointer to the kobject that implements a +directory in the sysfs_dirent object associated with the directory. In +the past this kobject pointer has been used by sysfs to do reference +counting directly on the kobject whenever the file is opened or closed. +With the current sysfs implementation the kobject reference count is +only modified directly by the function sysfs_schedule_callback(). Attributes @@ -208,9 +210,9 @@ Other notes: is 4096. - show() methods should return the number of bytes printed into the - buffer. This is the return value of snprintf(). + buffer. This is the return value of scnprintf(). -- show() should always use snprintf(). +- show() should always use scnprintf(). - store() should return the number of bytes used from the buffer. If the entire buffer has been used, just return the count argument. @@ -229,7 +231,7 @@ A very simple (and naive) implementation of a device attribute is: static ssize_t show_name(struct device *dev, struct device_attribute *attr, char *buf) { - return snprintf(buf, PAGE_SIZE, "%s\n", dev->name); + return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); } static ssize_t store_name(struct device *dev, struct device_attribute *attr, diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index f4a04c0c7edc..738c6fda3fb0 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2444,6 +2444,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. <deci-seconds>: poll all this frequency 0: no polling (default) + threadirqs [KNL] + Force threading of all interrupt handlers except those + marked explicitely IRQF_NO_THREAD. + topology= [S390] Format: {off | on} Specify if the kernel should make use of the cpu diff --git a/Documentation/keys-request-key.txt b/Documentation/keys-request-key.txt index 09b55e461740..69686ad12c66 100644 --- a/Documentation/keys-request-key.txt +++ b/Documentation/keys-request-key.txt @@ -127,14 +127,15 @@ This is because process A's keyrings can't simply be attached to of them, and (b) it requires the same UID/GID/Groups all the way through. -====================== -NEGATIVE INSTANTIATION -====================== +==================================== +NEGATIVE INSTANTIATION AND REJECTION +==================================== Rather than instantiating a key, it is possible for the possessor of an authorisation key to negatively instantiate a key that's under construction. This is a short duration placeholder that causes any attempt at re-requesting -the key whilst it exists to fail with error ENOKEY. +the key whilst it exists to fail with error ENOKEY if negated or the specified +error if rejected. This is provided to prevent excessive repeated spawning of /sbin/request-key processes for a key that will never be obtainable. diff --git a/Documentation/keys.txt b/Documentation/keys.txt index e4dbbdb1bd96..6523a9e6f293 100644 --- a/Documentation/keys.txt +++ b/Documentation/keys.txt @@ -637,6 +637,9 @@ The keyctl syscall functions are: long keyctl(KEYCTL_INSTANTIATE, key_serial_t key, const void *payload, size_t plen, key_serial_t keyring); + long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key, + const struct iovec *payload_iov, unsigned ioc, + key_serial_t keyring); If the kernel calls back to userspace to complete the instantiation of a key, userspace should use this call to supply data for the key before the @@ -652,11 +655,16 @@ The keyctl syscall functions are: The payload and plen arguments describe the payload data as for add_key(). + The payload_iov and ioc arguments describe the payload data in an iovec + array instead of a single buffer. + (*) Negatively instantiate a partially constructed key. long keyctl(KEYCTL_NEGATE, key_serial_t key, unsigned timeout, key_serial_t keyring); + long keyctl(KEYCTL_REJECT, key_serial_t key, + unsigned timeout, unsigned error, key_serial_t keyring); If the kernel calls back to userspace to complete the instantiation of a key, userspace should use this call mark the key as negative before the @@ -669,6 +677,10 @@ The keyctl syscall functions are: that keyring, however all the constraints applying in KEYCTL_LINK apply in this case too. + If the key is rejected, future searches for it will return the specified + error code until the rejected key expires. Negating the key is the same + as rejecting the key with ENOKEY as the error code. + (*) Set the default request-key destination keyring. @@ -1062,6 +1074,13 @@ The structure has a number of fields, some of which are mandatory: viable. + (*) int (*vet_description)(const char *description); + + This optional method is called to vet a key description. If the key type + doesn't approve of the key description, it may return an error, otherwise + it should return 0. + + (*) int (*instantiate)(struct key *key, const void *data, size_t datalen); This method is called to attach a payload to a key during construction. @@ -1231,10 +1250,11 @@ hand the request off to (perhaps a path held in placed in another key by, for example, the KDE desktop manager). The program (or whatever it calls) should finish construction of the key by -calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of -the keyrings (probably the session ring) before returning. Alternatively, the -key can be marked as negative with KEYCTL_NEGATE; this also permits the key to -be cached in one of the keyrings. +calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to +cache the key in one of the keyrings (probably the session ring) before +returning. Alternatively, the key can be marked as negative with KEYCTL_NEGATE +or KEYCTL_REJECT; this also permits the key to be cached in one of the +keyrings. If it returns with the key remaining in the unconstructed state, the key will be marked as being negative, it will be added to the session keyring, and an diff --git a/Documentation/kref.txt b/Documentation/kref.txt index ae203f91ee9b..48ba715d5a63 100644 --- a/Documentation/kref.txt +++ b/Documentation/kref.txt @@ -156,7 +156,7 @@ static struct my_data *get_entry() struct my_data *entry = NULL; mutex_lock(&mutex); if (!list_empty(&q)) { - entry = container_of(q.next, struct my_q_entry, link); + entry = container_of(q.next, struct my_data, link); kref_get(&entry->refcount); } mutex_unlock(&mutex); diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 631ad2f1b229..f0d3a8026a56 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -21,6 +21,7 @@ Contents: - SMP barrier pairing. - Examples of memory barrier sequences. - Read memory barriers vs load speculation. + - Transitivity (*) Explicit kernel barriers. @@ -959,6 +960,63 @@ the speculation will be cancelled and the value reloaded: retrieved : : +-------+ +TRANSITIVITY +------------ + +Transitivity is a deeply intuitive notion about ordering that is not +always provided by real computer systems. The following example +demonstrates transitivity (also called "cumulativity"): + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <general barrier> <general barrier> + LOAD Y LOAD X + +Suppose that CPU 2's load from X returns 1 and its load from Y returns 0. +This indicates that CPU 2's load from X in some sense follows CPU 1's +store to X and that CPU 2's load from Y in some sense preceded CPU 3's +store to Y. The question is then "Can CPU 3's load from X return 0?" + +Because CPU 2's load from X in some sense came after CPU 1's store, it +is natural to expect that CPU 3's load from X must therefore return 1. +This expectation is an example of transitivity: if a load executing on +CPU A follows a load from the same variable executing on CPU B, then +CPU A's load must either return the same value that CPU B's load did, +or must return some later value. + +In the Linux kernel, use of general memory barriers guarantees +transitivity. Therefore, in the above example, if CPU 2's load from X +returns 1 and its load from Y returns 0, then CPU 3's load from X must +also return 1. + +However, transitivity is -not- guaranteed for read or write barriers. +For example, suppose that CPU 2's general barrier in the above example +is changed to a read barrier as shown below: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <read barrier> <general barrier> + LOAD Y LOAD X + +This substitution destroys transitivity: in this example, it is perfectly +legal for CPU 2's load from X to return 1, its load from Y to return 0, +and CPU 3's load from X to return 0. + +The key point is that although CPU 2's read barrier orders its pair +of loads, it does not guarantee to order CPU 1's store. Therefore, if +this example runs on a system where CPUs 1 and 2 share a store buffer +or a level of cache, CPU 2 might have early access to CPU 1's writes. +General barriers are therefore required to ensure that all CPUs agree +on the combined order of CPU 1's and CPU 2's accesses. + +To reiterate, if your code requires transitivity, use general barriers +throughout. + + ======================== EXPLICIT KERNEL BARRIERS ======================== diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 57e7e9cc1870..8f485d72cf25 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -126,36 +126,51 @@ config options. -------------------------------- 4 sysfs files for memory hotplug -------------------------------- -All sections have their device information under /sys/devices/system/memory as +All sections have their device information in sysfs. Each section is part of +a memory block under /sys/devices/system/memory as /sys/devices/system/memory/memoryXXX -(XXX is section id.) +(XXX is the section id.) -Now, XXX is defined as start_address_of_section / section_size. +Now, XXX is defined as (start_address_of_section / section_size) of the first +section contained in the memory block. The files 'phys_index' and +'end_phys_index' under each directory report the beginning and end section id's +for the memory block covered by the sysfs directory. It is expected that all +memory sections in this range are present and no memory holes exist in the +range. Currently there is no way to determine if there is a memory hole, but +the existence of one should not affect the hotplug capabilities of the memory +block. For example, assume 1GiB section size. A device for a memory starting at 0x100000000 is /sys/device/system/memory/memory4 (0x100000000 / 1Gib = 4) This device covers address range [0x100000000 ... 0x140000000) -Under each section, you can see 4 files. +Under each section, you can see 4 or 5 files, the end_phys_index file being +a recent addition and not present on older kernels. -/sys/devices/system/memory/memoryXXX/phys_index +/sys/devices/system/memory/memoryXXX/start_phys_index +/sys/devices/system/memory/memoryXXX/end_phys_index /sys/devices/system/memory/memoryXXX/phys_device /sys/devices/system/memory/memoryXXX/state /sys/devices/system/memory/memoryXXX/removable -'phys_index' : read-only and contains section id, same as XXX. -'state' : read-write - at read: contains online/offline state of memory. - at write: user can specify "online", "offline" command -'phys_device': read-only: designed to show the name of physical memory device. - This is not well implemented now. -'removable' : read-only: contains an integer value indicating - whether the memory section is removable or not - removable. A value of 1 indicates that the memory - section is removable and a value of 0 indicates that - it is not removable. +'phys_index' : read-only and contains section id of the first section + in the memory block, same as XXX. +'end_phys_index' : read-only and contains section id of the last section + in the memory block. +'state' : read-write + at read: contains online/offline state of memory. + at write: user can specify "online", "offline" command + which will be performed on al sections in the block. +'phys_device' : read-only: designed to show the name of physical memory + device. This is not well implemented now. +'removable' : read-only: contains an integer value indicating + whether the memory block is removable or not + removable. A value of 1 indicates that the memory + block is removable and a value of 0 indicates that + it is not removable. A memory block is removable only if + every section in the block is removable. NOTE: These directories/files appear after physical memory hotplug phase. diff --git a/Documentation/networking/00-INDEX b/Documentation/networking/00-INDEX index fe5c099b8fc8..4edd78dfb362 100644 --- a/Documentation/networking/00-INDEX +++ b/Documentation/networking/00-INDEX @@ -40,8 +40,6 @@ decnet.txt - info on using the DECnet networking layer in Linux. depca.txt - the Digital DEPCA/EtherWORKS DE1?? and DE2?? LANCE Ethernet driver -dgrs.txt - - the Digi International RightSwitch SE-X Ethernet driver dmfe.txt - info on the Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver. e100.txt @@ -50,8 +48,6 @@ e1000.txt - info on Intel's E1000 line of gigabit ethernet boards eql.txt - serial IP load balancing -ethertap.txt - - the Ethertap user space packet reception and transmission driver ewrk3.txt - the Digital EtherWORKS 3 DE203/4/5 Ethernet driver filter.txt @@ -104,8 +100,6 @@ tuntap.txt - TUN/TAP device driver, allowing user space Rx/Tx of packets. vortex.txt - info on using 3Com Vortex (3c590, 3c592, 3c595, 3c597) Ethernet cards. -wavelan.txt - - AT&T GIS (nee NCR) WaveLAN card: An Ethernet-like radio transceiver x25.txt - general info on X.25 development. x25-iface.txt diff --git a/Documentation/networking/dns_resolver.txt b/Documentation/networking/dns_resolver.txt index aefd1e681804..04ca06325b08 100644 --- a/Documentation/networking/dns_resolver.txt +++ b/Documentation/networking/dns_resolver.txt @@ -61,7 +61,6 @@ before the more general line given above as the first match is the one taken. create dns_resolver foo:* * /usr/sbin/dns.foo %k - ===== USAGE ===== @@ -104,6 +103,14 @@ implemented in the module can be called after doing: returned also. +=============================== +READING DNS KEYS FROM USERSPACE +=============================== + +Keys of dns_resolver type can be read from userspace using keyctl_read() or +"keyctl read/print/pipe". + + ========= MECHANISM ========= diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt index 57080cd74575..f023ba6bba62 100644 --- a/Documentation/power/devices.txt +++ b/Documentation/power/devices.txt @@ -1,6 +1,6 @@ Device Power Management -Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> @@ -159,18 +159,18 @@ matter, and the kernel is responsible for keeping track of it. By contrast, whether or not a wakeup-capable device should issue wakeup events is a policy decision, and it is managed by user space through a sysfs attribute: the power/wakeup file. User space can write the strings "enabled" or "disabled" to -set or clear the should_wakeup flag, respectively. Reads from the file will -return the corresponding string if can_wakeup is true, but if can_wakeup is -false then reads will return an empty string, to indicate that the device -doesn't support wakeup events. (But even though the file appears empty, writes -will still affect the should_wakeup flag.) +set or clear the "should_wakeup" flag, respectively. This file is only present +for wakeup-capable devices (i.e. devices whose "can_wakeup" flags are set) +and is created (or removed) by device_set_wakeup_capable(). Reads from the +file will return the corresponding string. The device_may_wakeup() routine returns true only if both flags are set. -Drivers should check this routine when putting devices in a low-power state -during a system sleep transition, to see whether or not to enable the devices' -wakeup mechanisms. However for runtime power management, wakeup events should -be enabled whenever the device and driver both support them, regardless of the -should_wakeup flag. +This information is used by subsystems, like the PCI bus type code, to see +whether or not to enable the devices' wakeup mechanisms. If device wakeup +mechanisms are enabled or disabled directly by drivers, they also should use +device_may_wakeup() to decide what to do during a system sleep transition. +However for runtime power management, wakeup events should be enabled whenever +the device and driver both support them, regardless of the should_wakeup flag. /sys/devices/.../power/control files @@ -249,23 +249,18 @@ various phases always run after tasks have been frozen and before they are unfrozen. Furthermore, the *_noirq phases run at a time when IRQ handlers have been disabled (except for those marked with the IRQ_WAKEUP flag). -Most phases use bus, type, and class callbacks (that is, methods defined in -dev->bus->pm, dev->type->pm, and dev->class->pm). The prepare and complete -phases are exceptions; they use only bus callbacks. When multiple callbacks -are used in a phase, they are invoked in the order: <class, type, bus> during -power-down transitions and in the opposite order during power-up transitions. -For example, during the suspend phase the PM core invokes - - dev->class->pm.suspend(dev); - dev->type->pm.suspend(dev); - dev->bus->pm.suspend(dev); - -before moving on to the next device, whereas during the resume phase the core -invokes - - dev->bus->pm.resume(dev); - dev->type->pm.resume(dev); - dev->class->pm.resume(dev); +All phases use bus, type, or class callbacks (that is, methods defined in +dev->bus->pm, dev->type->pm, or dev->class->pm). These callbacks are mutually +exclusive, so if the device type provides a struct dev_pm_ops object pointed to +by its pm field (i.e. both dev->type and dev->type->pm are defined), the +callbacks included in that object (i.e. dev->type->pm) will be used. Otherwise, +if the class provides a struct dev_pm_ops object pointed to by its pm field +(i.e. both dev->class and dev->class->pm are defined), the PM core will use the +callbacks from that object (i.e. dev->class->pm). Finally, if the pm fields of +both the device type and class objects are NULL (or those objects do not exist), +the callbacks provided by the bus (that is, the callbacks from dev->bus->pm) +will be used (this allows device types to override callbacks provided by bus +types or classes if necessary). These callbacks may in turn invoke device- or driver-specific methods stored in dev->driver->pm, but they don't have to. @@ -507,6 +502,49 @@ routines. Nevertheless, different callback pointers are used in case there is a situation where it actually matters. +Device Power Domains +-------------------- +Sometimes devices share reference clocks or other power resources. In those +cases it generally is not possible to put devices into low-power states +individually. Instead, a set of devices sharing a power resource can be put +into a low-power state together at the same time by turning off the shared +power resource. Of course, they also need to be put into the full-power state +together, by turning the shared power resource on. A set of devices with this +property is often referred to as a power domain. + +Support for power domains is provided through the pwr_domain field of struct +device. This field is a pointer to an object of type struct dev_power_domain, +defined in include/linux/pm.h, providing a set of power management callbacks +analogous to the subsystem-level and device driver callbacks that are executed +for the given device during all power transitions, in addition to the respective +subsystem-level callbacks. Specifically, the power domain "suspend" callbacks +(i.e. ->runtime_suspend(), ->suspend(), ->freeze(), ->poweroff(), etc.) are +executed after the analogous subsystem-level callbacks, while the power domain +"resume" callbacks (i.e. ->runtime_resume(), ->resume(), ->thaw(), ->restore, +etc.) are executed before the analogous subsystem-level callbacks. Error codes +returned by the "suspend" and "resume" power domain callbacks are ignored. + +Power domain ->runtime_idle() callback is executed before the subsystem-level +->runtime_idle() callback and the result returned by it is not ignored. Namely, +if it returns error code, the subsystem-level ->runtime_idle() callback will not +be called and the helper function rpm_idle() executing it will return error +code. This mechanism is intended to help platforms where saving device state +is a time consuming operation and should only be carried out if all devices +in the power domain are idle, before turning off the shared power resource(s). +Namely, the power domain ->runtime_idle() callback may return error code until +the pm_runtime_idle() helper (or its asychronous version) has been called for +all devices in the power domain (it is recommended that the returned error code +be -EBUSY in those cases), preventing the subsystem-level ->runtime_idle() +callback from being run prematurely. + +The support for device power domains is only relevant to platforms needing to +use the same subsystem-level (e.g. platform bus type) and device driver power +management callbacks in many different power domain configurations and wanting +to avoid incorporating the support for power domains into the subsystem-level +callbacks. The other platforms need not implement it or take it into account +in any way. + + System Devices -------------- System devices (sysdevs) follow a slightly different API, which can be found in diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index ffe55ffa540a..654097b130b4 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -1,6 +1,6 @@ Run-time Power Management Framework for I/O Devices -(C) 2009 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. (C) 2010 Alan Stern <stern@rowland.harvard.edu> 1. Introduction @@ -44,11 +44,12 @@ struct dev_pm_ops { }; The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are -executed by the PM core for either the bus type, or device type (if the bus -type's callback is not defined), or device class (if the bus type's and device -type's callbacks are not defined) of given device. The bus type, device type -and device class callbacks are referred to as subsystem-level callbacks in what -follows. +executed by the PM core for either the device type, or the class (if the device +type's struct dev_pm_ops object does not exist), or the bus type (if the +device type's and class' struct dev_pm_ops objects do not exist) of the given +device (this allows device types to override callbacks provided by bus types or +classes if necessary). The bus type, device type and class callbacks are +referred to as subsystem-level callbacks in what follows. By default, the callbacks are always invoked in process context with interrupts enabled. However, subsystems can use the pm_runtime_irq_safe() helper function diff --git a/Documentation/power/states.txt b/Documentation/power/states.txt index 34800cc521bf..4416b28630df 100644 --- a/Documentation/power/states.txt +++ b/Documentation/power/states.txt @@ -62,12 +62,12 @@ setup via another operating system for it to use. Despite the inconvenience, this method requires minimal work by the kernel, since the firmware will also handle restoring memory contents on resume. -For suspend-to-disk, a mechanism called swsusp called 'swsusp' (Swap -Suspend) is used to write memory contents to free swap space. -swsusp has some restrictive requirements, but should work in most -cases. Some, albeit outdated, documentation can be found in -Documentation/power/swsusp.txt. Alternatively, userspace can do most -of the actual suspend to disk work, see userland-swsusp.txt. +For suspend-to-disk, a mechanism called 'swsusp' (Swap Suspend) is used +to write memory contents to free swap space. swsusp has some restrictive +requirements, but should work in most cases. Some, albeit outdated, +documentation can be found in Documentation/power/swsusp.txt. +Alternatively, userspace can do most of the actual suspend to disk work, +see userland-swsusp.txt. Once memory state is written to disk, the system may either enter a low-power state (like ACPI S4), or it may simply power down. Powering diff --git a/Documentation/powerpc/00-INDEX b/Documentation/powerpc/00-INDEX index e3960b8c8689..5620fb5ac425 100644 --- a/Documentation/powerpc/00-INDEX +++ b/Documentation/powerpc/00-INDEX @@ -5,8 +5,6 @@ please mail me. 00-INDEX - this file -booting-without-of.txt - - Booting the Linux/ppc kernel without Open Firmware cpu_features.txt - info on how we support a variety of CPUs with minimal compile-time options. @@ -16,8 +14,6 @@ hvcs.txt - IBM "Hypervisor Virtual Console Server" Installation Guide mpc52xx.txt - Linux 2.6.x on MPC52xx family -mpc52xx-device-tree-bindings.txt - - MPC5200 Device Tree Bindings sound.txt - info on sound support under Linux/PPC zImage_layout.txt diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 9104c1062084..250160469d83 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -178,38 +178,29 @@ RTC class framework, but can't be supported by the older driver. setting the longer alarm time and enabling its IRQ using a single request (using the same model as EFI firmware). - * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, it probably - also offers update IRQs whenever the "seconds" counter changes. - If needed, the RTC framework can emulate this mechanism. + * RTC_UIE_ON, RTC_UIE_OFF ... if the RTC offers IRQs, the RTC framework + will emulate this mechanism. - * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... another - feature often accessible with an IRQ line is a periodic IRQ, issued - at settable frequencies (usually 2^N Hz). + * RTC_PIE_ON, RTC_PIE_OFF, RTC_IRQP_SET, RTC_IRQP_READ ... these icotls + are emulated via a kernel hrtimer. In many cases, the RTC alarm can be a system wake event, used to force Linux out of a low power sleep state (or hibernation) back to a fully operational state. For example, a system could enter a deep power saving state until it's time to execute some scheduled tasks. -Note that many of these ioctls need not actually be implemented by your -driver. The common rtc-dev interface handles many of these nicely if your -driver returns ENOIOCTLCMD. Some common examples: +Note that many of these ioctls are handled by the common rtc-dev interface. +Some common examples: * RTC_RD_TIME, RTC_SET_TIME: the read_time/set_time functions will be called with appropriate values. - * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: the - set_alarm/read_alarm functions will be called. + * RTC_ALM_SET, RTC_ALM_READ, RTC_WKALM_SET, RTC_WKALM_RD: gets or sets + the alarm rtc_timer. May call the set_alarm driver function. - * RTC_IRQP_SET, RTC_IRQP_READ: the irq_set_freq function will be called - to set the frequency while the framework will handle the read for you - 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 it isn't, return -EINVAL. If - you cannot actually change the frequency, do not define irq_set_freq. + * RTC_IRQP_SET, RTC_IRQP_READ: These are emulated by the generic code. - * RTC_PIE_ON, RTC_PIE_OFF: the irq_set_state function will be called. + * RTC_PIE_ON, RTC_PIE_OFF: These are also emulated by the generic code. If all else fails, check out the rtc-test.c driver! diff --git a/Documentation/spinlocks.txt b/Documentation/spinlocks.txt index 178c831b907d..2e3c64b1a6a5 100644 --- a/Documentation/spinlocks.txt +++ b/Documentation/spinlocks.txt @@ -86,7 +86,7 @@ to change the variables it has to get an exclusive write lock. The routines look the same as above: - rwlock_t xxx_lock = RW_LOCK_UNLOCKED; + rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock); unsigned long flags; @@ -196,25 +196,3 @@ appropriate: For static initialization, use DEFINE_SPINLOCK() / DEFINE_RWLOCK() or __SPIN_LOCK_UNLOCKED() / __RW_LOCK_UNLOCKED() as appropriate. - -SPIN_LOCK_UNLOCKED and RW_LOCK_UNLOCKED are deprecated. These interfere -with lockdep state tracking. - -Most of the time, you can simply turn: - static spinlock_t xxx_lock = SPIN_LOCK_UNLOCKED; -into: - static DEFINE_SPINLOCK(xxx_lock); - -Static structure member variables go from: - - struct foo bar { - .lock = SPIN_LOCK_UNLOCKED; - }; - -to: - - struct foo bar { - .lock = __SPIN_LOCK_UNLOCKED(bar.lock); - }; - -Declaration of static rw_locks undergo a similar transformation. diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt index 62682500878a..4af0614147ef 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/sysctl/fs.txt @@ -88,20 +88,19 @@ you might want to raise the limit. file-max & file-nr: -The kernel allocates file handles dynamically, but as yet it -doesn't free them again. - The value in file-max denotes the maximum number of file- handles that the Linux kernel will allocate. When you get lots of error messages about running out of file handles, you might want to increase this limit. -Historically, the three values in file-nr denoted the number of -allocated file handles, the number of allocated but unused file -handles, and the maximum number of file handles. Linux 2.6 always -reports 0 as the number of free file handles -- this is not an -error, it just means that the number of allocated file handles -exactly matches the number of used file handles. +Historically,the kernel was able to allocate file handles +dynamically, but not to free them again. The three values in +file-nr denote the number of allocated file handles, the number +of allocated but unused file handles, and the maximum number of +file handles. Linux 2.6 always reports 0 as the number of free +file handles -- this is not an error, it just means that the +number of allocated file handles exactly matches the number of +used file handles. Attempts to allocate more file descriptors than file-max are reported with printk, look for "VFS: file-max limit <number> diff --git a/Documentation/trace/ftrace-design.txt b/Documentation/trace/ftrace-design.txt index dc52bd442c92..79fcafc7fd64 100644 --- a/Documentation/trace/ftrace-design.txt +++ b/Documentation/trace/ftrace-design.txt @@ -247,6 +247,13 @@ You need very few things to get the syscalls tracing in an arch. - Support the TIF_SYSCALL_TRACEPOINT thread flags. - Put the trace_sys_enter() and trace_sys_exit() tracepoints calls from ptrace in the ptrace syscalls tracing path. +- If the system call table on this arch is more complicated than a simple array + of addresses of the system calls, implement an arch_syscall_addr to return + the address of a given system call. +- If the symbol names of the system calls do not match the function names on + this arch, define ARCH_HAS_SYSCALL_MATCH_SYM_NAME in asm/ftrace.h and + implement arch_syscall_match_sym_name with the appropriate logic to return + true if the function name corresponds with the symbol name. - Tag this arch as HAVE_SYSCALL_TRACEPOINTS. diff --git a/Documentation/trace/ftrace.txt b/Documentation/trace/ftrace.txt index 557c1edeccaf..1ebc24cf9a55 100644 --- a/Documentation/trace/ftrace.txt +++ b/Documentation/trace/ftrace.txt @@ -80,11 +80,11 @@ of ftrace. Here is a list of some of the key files: tracers listed here can be configured by echoing their name into current_tracer. - tracing_enabled: + tracing_on: - This sets or displays whether the current_tracer - is activated and tracing or not. Echo 0 into this - file to disable the tracer or 1 to enable it. + This sets or displays whether writing to the trace + ring buffer is enabled. Echo 0 into this file to disable + the tracer or 1 to enable it. trace: @@ -202,10 +202,6 @@ Here is the list of current tracers that may be configured. to draw a graph of function calls similar to C code source. - "sched_switch" - - Traces the context switches and wakeups between tasks. - "irqsoff" Traces the areas that disable interrupts and saves @@ -273,39 +269,6 @@ format, the function name that was traced "path_put" and the parent function that called this function "path_walk". The timestamp is the time at which the function was entered. -The sched_switch tracer also includes tracing of task wakeups -and context switches. - - ksoftirqd/1-7 [01] 1453.070013: 7:115:R + 2916:115:S - ksoftirqd/1-7 [01] 1453.070013: 7:115:R + 10:115:S - ksoftirqd/1-7 [01] 1453.070013: 7:115:R ==> 10:115:R - events/1-10 [01] 1453.070013: 10:115:S ==> 2916:115:R - kondemand/1-2916 [01] 1453.070013: 2916:115:S ==> 7:115:R - ksoftirqd/1-7 [01] 1453.070013: 7:115:S ==> 0:140:R - -Wake ups are represented by a "+" and the context switches are -shown as "==>". The format is: - - Context switches: - - Previous task Next Task - - <pid>:<prio>:<state> ==> <pid>:<prio>:<state> - - Wake ups: - - Current task Task waking up - - <pid>:<prio>:<state> + <pid>:<prio>:<state> - -The prio is the internal kernel priority, which is the inverse -of the priority that is usually displayed by user-space tools. -Zero represents the highest priority (99). Prio 100 starts the -"nice" priorities with 100 being equal to nice -20 and 139 being -nice 19. The prio "140" is reserved for the idle task which is -the lowest priority thread (pid 0). - - Latency trace format -------------------- @@ -491,78 +454,10 @@ x494] <- /root/a.out[+0x4a8] <- /lib/libc-2.7.so[+0x1e1a6] latencies, as described in "Latency trace format". -sched_switch ------------- - -This tracer simply records schedule switches. Here is an example -of how to use it. - - # echo sched_switch > current_tracer - # echo 1 > tracing_enabled - # sleep 1 - # echo 0 > tracing_enabled - # cat trace - -# tracer: sched_switch -# -# TASK-PID CPU# TIMESTAMP FUNCTION -# | | | | | - bash-3997 [01] 240.132281: 3997:120:R + 4055:120:R - bash-3997 [01] 240.132284: 3997:120:R ==> 4055:120:R - sleep-4055 [01] 240.132371: 4055:120:S ==> 3997:120:R - bash-3997 [01] 240.132454: 3997:120:R + 4055:120:S - bash-3997 [01] 240.132457: 3997:120:R ==> 4055:120:R - sleep-4055 [01] 240.132460: 4055:120:D ==> 3997:120:R - bash-3997 [01] 240.132463: 3997:120:R + 4055:120:D - bash-3997 [01] 240.132465: 3997:120:R ==> 4055:120:R - <idle>-0 [00] 240.132589: 0:140:R + 4:115:S - <idle>-0 [00] 240.132591: 0:140:R ==> 4:115:R - ksoftirqd/0-4 [00] 240.132595: 4:115:S ==> 0:140:R - <idle>-0 [00] 240.132598: 0:140:R + 4:115:S - <idle>-0 [00] 240.132599: 0:140:R ==> 4:115:R - ksoftirqd/0-4 [00] 240.132603: 4:115:S ==> 0:140:R - sleep-4055 [01] 240.133058: 4055:120:S ==> 3997:120:R - [...] - - -As we have discussed previously about this format, the header -shows the name of the trace and points to the options. The -"FUNCTION" is a misnomer since here it represents the wake ups -and context switches. - -The sched_switch file only lists the wake ups (represented with -'+') and context switches ('==>') with the previous task or -current task first followed by the next task or task waking up. -The format for both of these is PID:KERNEL-PRIO:TASK-STATE. -Remember that the KERNEL-PRIO is the inverse of the actual -priority with zero (0) being the highest priority and the nice -values starting at 100 (nice -20). Below is a quick chart to map -the kernel priority to user land priorities. - - Kernel Space User Space - =============================================================== - 0(high) to 98(low) user RT priority 99(high) to 1(low) - with SCHED_RR or SCHED_FIFO - --------------------------------------------------------------- - 99 sched_priority is not used in scheduling - decisions(it must be specified as 0) - --------------------------------------------------------------- - 100(high) to 139(low) user nice -20(high) to 19(low) - --------------------------------------------------------------- - 140 idle task priority - --------------------------------------------------------------- - -The task states are: - - R - running : wants to run, may not actually be running - S - sleep : process is waiting to be woken up (handles signals) - D - disk sleep (uninterruptible sleep) : process must be woken up - (ignores signals) - T - stopped : process suspended - t - traced : process is being traced (with something like gdb) - Z - zombie : process waiting to be cleaned up - X - unknown - + overwrite - This controls what happens when the trace buffer is + full. If "1" (default), the oldest events are + discarded and overwritten. If "0", then the newest + events are discarded. ftrace_enabled -------------- @@ -607,10 +502,10 @@ an example: # echo irqsoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: irqsoff # @@ -715,10 +610,10 @@ is much like the irqsoff tracer. # echo preemptoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: preemptoff # @@ -863,10 +758,10 @@ tracers. # echo preemptirqsoff > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # ls -ltr [...] - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: preemptirqsoff # @@ -1026,9 +921,9 @@ Instead of performing an 'ls', we will run 'sleep 1' under # echo wakeup > current_tracer # echo latency-format > trace_options # echo 0 > tracing_max_latency - # echo 1 > tracing_enabled + # echo 1 > tracing_on # chrt -f 5 sleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: wakeup # @@ -1140,9 +1035,9 @@ ftrace_enabled is set; otherwise this tracer is a nop. # sysctl kernel.ftrace_enabled=1 # echo function > current_tracer - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: function # @@ -1180,7 +1075,7 @@ int trace_fd; [...] int main(int argc, char *argv[]) { [...] - trace_fd = open(tracing_file("tracing_enabled"), O_WRONLY); + trace_fd = open(tracing_file("tracing_on"), O_WRONLY); [...] if (condition_hit()) { write(trace_fd, "0", 1); @@ -1631,9 +1526,9 @@ If I am only interested in sys_nanosleep and hrtimer_interrupt: # echo sys_nanosleep hrtimer_interrupt \ > set_ftrace_filter # echo function > current_tracer - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: ftrace # @@ -1879,9 +1774,9 @@ different. The trace is live. # echo function > current_tracer # cat trace_pipe > /tmp/trace.out & [1] 4153 - # echo 1 > tracing_enabled + # echo 1 > tracing_on # usleep 1 - # echo 0 > tracing_enabled + # echo 0 > tracing_on # cat trace # tracer: function # diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index 5f77d94598dd..6d27ab8d6e9f 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -42,11 +42,25 @@ Synopsis of kprobe_events +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**) NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types - (u8/u16/u32/u64/s8/s16/s32/s64) and string are supported. + (u8/u16/u32/u64/s8/s16/s32/s64), "string" and bitfield + are supported. (*) only for return probe. (**) this is useful for fetching a field of data structures. +Types +----- +Several types are supported for fetch-args. Kprobe tracer will access memory +by given type. Prefix 's' and 'u' means those types are signed and unsigned +respectively. Traced arguments are shown in decimal (signed) or hex (unsigned). +String type is a special type, which fetches a "null-terminated" string from +kernel space. This means it will fail and store NULL if the string container +has been paged out. +Bitfield is another special type, which takes 3 parameters, bit-width, bit- +offset, and container-size (usually 32). The syntax is; + + b<bit-width>@<bit-offset>/<container-size> + Per-Probe Event Filtering ------------------------- diff --git a/Documentation/usb/usbmon.txt b/Documentation/usb/usbmon.txt index 66f92d1194c1..a4efa0462f05 100644 --- a/Documentation/usb/usbmon.txt +++ b/Documentation/usb/usbmon.txt @@ -12,6 +12,10 @@ Controller Drivers (HCD). So, if HCD is buggy, the traces reported by usbmon may not correspond to bus transactions precisely. This is the same situation as with tcpdump. +Two APIs are currently implemented: "text" and "binary". The binary API +is available through a character device in /dev namespace and is an ABI. +The text API is deprecated since 2.6.35, but available for convenience. + * How to use usbmon to collect raw text traces Unlike the packet socket, usbmon has an interface which provides traces @@ -162,39 +166,11 @@ Here is the list of words, from left to right: not machine words, but really just a byte stream split into words to make it easier to read. Thus, the last word may contain from one to four bytes. The length of collected data is limited and can be less than the data length - report in Data Length word. - -Here is an example of code to read the data stream in a well known programming -language: - -class ParsedLine { - int data_len; /* Available length of data */ - byte data[]; - - void parseData(StringTokenizer st) { - int availwords = st.countTokens(); - data = new byte[availwords * 4]; - data_len = 0; - while (st.hasMoreTokens()) { - String data_str = st.nextToken(); - int len = data_str.length() / 2; - int i; - int b; // byte is signed, apparently?! XXX - for (i = 0; i < len; i++) { - // data[data_len] = Byte.parseByte( - // data_str.substring(i*2, i*2 + 2), - // 16); - b = Integer.parseInt( - data_str.substring(i*2, i*2 + 2), - 16); - if (b >= 128) - b *= -1; - data[data_len] = (byte) b; - data_len++; - } - } - } -} + reported in the Data Length word. In the case of an Isochronous input (Zi) + completion where the received data is sparse in the buffer, the length of + the collected data can be greater than the Data Length value (because Data + Length counts only the bytes that were received whereas the Data words + contain the entire transfer buffer). Examples: diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs new file mode 100644 index 000000000000..d21eb07fe943 --- /dev/null +++ b/Documentation/zh_CN/SecurityBugs @@ -0,0 +1,50 @@ +Chinese translated version of Documentation/SecurityBugs + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/SecurityBugs 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Harry Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Harry Wei <harryxiyou@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于 +安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全 +漏洞报告给Linux内核安全团队。 + +1) 联系 + +linux内核安全团队可以通过email<security@kernel.org>来联系。这是 +一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 +全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 +当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 +是有帮助的信息，那就请重温一下REPORTING-BUGS文件中的概述过程。任 +何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 +被公布于众。 + +2) 公开 + +Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直 +到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理 +解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们 +期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开 +日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很 +短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我 +们所期望通知公众的日期是7天的安排。 + +3) 保密协议 + +Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。 diff --git a/Documentation/zh_CN/SubmitChecklist b/Documentation/zh_CN/SubmitChecklist new file mode 100644 index 000000000000..951415bbab0c --- /dev/null +++ b/Documentation/zh_CN/SubmitChecklist @@ -0,0 +1,109 @@ +Chinese translated version of Documentation/SubmitChecklist + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Chinese maintainer: Harry Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/SubmitChecklist ķ + +ۻ±ĵݣֱϵԭĵάߡʹӢ +ѵĻҲİά²ʱ߷ +⣬ϵİάߡ + +İάߣ Harry Wei <harryxiyou@gmail.com> +İ淭ߣ Harry Wei <harryxiyou@gmail.com> +İУߣ Harry Wei <harryxiyou@gmail.com> + + +Ϊ +--------------------------------------------------------------------- +Linuxںύ嵥 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +һЩں˿ӦĻ飬뿴Լں˲ύ +ܵĸ졣 + +ЩdzDocumentation/SubmittingPatchesĵṩԼ +ύLinuxں˲˵ + +1ʹһô#include/ǸܵǸļ + Ҫ붨/Ǹܵͷļ + +2û߸CONFIGѡ =y=m=n + Ҫб뾯/ ҪӾ/ + +2bͨ allnoconfig, allmodconfig + +2cʹ 0=builddir ɹع + +3ͨʹñؽ빤һЩڶCPUϹ + +4ppc64 һܺõļ齻ĿܣΪѡunsigned long + 64λֵʹá + +5Documentation/CodingStyleļϸ㲹 + ʹòΥ(scripts/checkpatch.pl)Աύ + Ӧõ㲹еΥ档 + +6κθ»߸ĶCONFIGѡܴò˵ + +7еKconfigѡ¶Ҫ˵֡ + +8ѾܽصKconfigϡǺͨõ--½ + +9мԡ + +10ʹ'make checkstack''make namespacecheck'飬Ȼҵ⡣ + ע⣺ջ鲻ȷس⣬κεһڶջʹö512ֽ + Ҫġ + +11kernel-docȫںAPIsļҪ̬ĺǰҲν + ʹ'make htmldocs''make mandocs'kernel-docȻκ + ֵ⡣ + +12ѾͨCONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, + CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, + CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_SPINLOCK_SLEEPԣͬʱ + ʹܡ + +13Ѿʹû߲ʹ CONFIG_SMP CONFIG_PREEMPTִʱ䡣 + +14ӰIO/DiskȵȣѾͨʹû߲ʹ CONFIG_LBDAF ԡ + +15еcodepathsѾʹlockdepùܡ + +16е/proc¼¶ҪļDocumentation/Ŀ¼¡ + +17еں¶¼Documentation/kernel-parameters.txtļС + +18еģ¶MODULE_PARM_DESC()¼ + +19еûռӿڸ¶¼Documentation/ABI/鿴Documentation/ABI/README + ԻøϢıûռӿڵIJӦñʼlinux-api@vger.kernel.org + +20DzǶͨ`make headers_check' + +21Ѿͨslabpage-allocationʧܼ顣鿴Documentation/fault-injection/ + +22¼ԴѾͨ`gcc -W'ʹ"make EXTRA_CFLAGS=-W"롣ܶෳգ + ǶѰ©洦:"warning: comparison between signed and unsigned" + +23ϲ-mmٲԣȷǷͲеһԼVMVFS + ϵͳи仯 + +24еڴ{e.g., barrier(), rmb(), wmb()}ҪԴеһעǶǸʲô + Լԭ + +25κƵIJӣҲҪDocumentation/ioctl/ioctl-number.txt + +26ĸĴʹκεںAPIskconfigйϵĹܣҪ + ʹصkconfigŹرգ and/or =mѡṩ[ͬһʱ䲻õĶã + ] + + CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, + CONFIG_BLOCK, CONFIG_PM, CONFIG_HOTPLUG, CONFIG_MAGIC_SYSRQ, + CONFIG_NET, CONFIG_INET=n (һʹ CONFIG_NET=y) diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches index 9a1a6e1ed09e..0f4385a62a49 100644 --- a/Documentation/zh_CN/SubmittingPatches +++ b/Documentation/zh_CN/SubmittingPatches @@ -100,7 +100,7 @@ http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz 将改动拆分，逻辑类似的放到同一个补丁文件里。 -例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动才分到两个或 +例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或 者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适 应这些新的API，那么把这些修改分成两个补丁。 @@ -230,7 +230,7 @@ pref("mailnews.display.disable_format_flowed_support", true); 些原因，修正错误，重新提交更新后的改动，是你自己的工作。 Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很 -平常。如果他没有接受你的补丁，也许是由于以下原本： +平常。如果他没有接受你的补丁，也许是由于以下原因： * 你的补丁不能在最新版本的内核上干净的打上。 * 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。 * 风格问题（参照第2小节） diff --git a/Documentation/zh_CN/magic-number.txt b/Documentation/zh_CN/magic-number.txt new file mode 100644 index 000000000000..4c4ce853577b --- /dev/null +++ b/Documentation/zh_CN/magic-number.txt @@ -0,0 +1,167 @@ +Chinese translated version of Documentation/magic-number.txt + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Jia Wei Wei <harryxiyou@gmail.com> +--------------------------------------------------------------------- +Documentation/magic-number.txt的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版翻译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> +中文版校译者： 贾威威 Jia Wei Wei <harryxiyou@gmail.com> + +以下为正文 +--------------------------------------------------------------------- +这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。 + +使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。 + +使用魔术值的方法是在结构的开始处声明的，如下： + +struct tty_ldisc { + int magic; + ... +}; + +当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，这些情况可以被快速地，安全地避免。 + + Theodore Ts'o + 31 Mar 94 + +给当前的Linux 2.1.55添加魔术表。 + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + +现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。 + + Krzysztof G.Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + +更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。 + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + +更新魔术表到Linux 2.5.74。 + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + +魔术名 地址 结构 所在文件 +=========================================================================== +PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h +CMAGIC 0x0111 user include/linux/a.out.h +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h +RISCOM8_MAGIC 0x0907 riscom_port drivers/char/riscom8.h +SPECIALIX_MAGIC 0x0907 specialix_port drivers/char/specialix_io8.h +HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c +APM_BIOS_MAGIC 0x4101 apm_user arch/i386/kernel/apm.c +CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h +DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c +DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c +FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h +FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c +ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h +PTY_MAGIC 0x5001 drivers/char/pty.c +PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h +SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h +SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h +SLIP_MAGIC 0x5302 slip drivers/net/slip.h +STRIP_MAGIC 0x5303 strip drivers/net/strip.c +X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h +SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h +AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h +ESP_MAGIC 0x53ee esp_struct drivers/char/esp.h +TTY_MAGIC 0x5401 tty_struct include/linux/tty.h +MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c +TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h +MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c +TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h +USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h +FULL_DUPLEX_MAGIC 0x6969 drivers/net/tulip/de2104x.c +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c +RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h +CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h +A2232_MAGIC 0x000a2232 gs_port drivers/char/ser_a2232.h +RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h +LSEMAGIC 0x05091998 lse drivers/fc4/fc.c +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h +RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c +RIO_MAGIC 0x12345678 gs_port drivers/char/rio/rio_linux.c +SX_MAGIC 0x12345678 gs_port drivers/char/sx.h +NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h +RED_MAGIC2 0x170fc2a5 (any) mm/slab.c +BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data + drivers/isdn/isdn_x25iface.h +ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h +LSOMAGIC 0x27091997 lso drivers/fc4/fc.c +LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h +CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c +LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h +ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c +STLI_BOARDMAGIC 0x4bc6c825 stlibrd include/linux/istallion.h +CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c +SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c +COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c +I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c +TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c +ROUTER_MAGIC 0x524d4157 wan_device include/linux/wanrouter.h +SCC_MAGIC 0x52696368 gs_port drivers/char/scc.h +SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c +GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h +RED_MAGIC1 0x5a2cf071 (any) mm/slab.c +STL_PORTMAGIC 0x5a7182c9 stlport include/linux/stallion.h +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h +EPCA_MAGIC 0x5c6df104 channel include/linux/epca.h +PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h +KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h +I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c +TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c +M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c +FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h +SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h +SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h +LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h +OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h +M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c +STL_PANELMAGIC 0x7ef621a1 stlpanel include/linux/stallion.h +VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c +KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c +PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h +NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h +STL_BOARDMAGIC 0xa2267f52 stlbrd include/linux/stallion.h +ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h +SCI_MAGIC 0xbabeface gs_port drivers/char/sh-sci.h +CODA_MAGIC 0xC0DAC0DA coda_file_info include/linux/coda_fs_i.h +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h +STLI_PORTMAGIC 0xe671c7a1 stliport include/linux/istallion.h +YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c +CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c +HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c +NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h + +请注意，在声音记忆管理中仍然有每一些被定义的驱动魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。 + +IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。 + +HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。 |