Merge branch 'doc/4.4' of git.lwn.net:/home/git/linux-2.6

This commit is contained in:
Jonathan Corbet 2015-09-24 15:32:09 -06:00
commit 1c0032c8eb
13 changed files with 163 additions and 84 deletions

View File

@ -11,5 +11,7 @@
*.png
*.gif
*.svg
*.proc
*.db
media-indices.tmpl
media-entities.tmpl

View File

@ -17,13 +17,13 @@ the sysfs directory entries we ensure that we don't have conflicts
in the directories and applications only see a limited set of
the network devices.
Each sysfs directory entry may be tagged with zero or one
namespaces. A sysfs_dirent is augmented with a void *s_ns. If a
directory entry is tagged, then sysfs_dirent->s_flags will have a
flag between KOBJ_NS_TYPE_NONE and KOBJ_NS_TYPES, and s_ns will
point to the namespace to which it belongs.
Each sysfs directory entry may be tagged with a namespace via the
void *ns member of its kernfs_node. If a directory entry is tagged,
then kernfs_node->flags will have a flag between KOBJ_NS_TYPE_NONE
and KOBJ_NS_TYPES, and ns will point to the namespace to which it
belongs.
Each sysfs superblock's sysfs_super_info contains an array void
Each sysfs superblock's kernfs_super_info contains an array void
*ns[KOBJ_NS_TYPES]. When a task in a tagging namespace
kobj_nstype first mounts sysfs, a new superblock is created. It
will be differentiated from other sysfs mounts by having its
@ -31,7 +31,7 @@ s_fs_info->ns[kobj_nstype] set to the new namespace. Note that
through bind mounting and mounts propagation, a task can easily view
the contents of other namespaces' sysfs mounts. Therefore, when a
namespace exits, it will call kobj_ns_exit() to invalidate any
sysfs_dirent->s_ns pointers pointing to it.
kernfs_node->ns pointers pointing to it.
Users of this interface:
- define a type in the kobj_ns_type enumeration.

View File

@ -40,7 +40,7 @@ ancestors of object hierarchies; i.e. the subsystems the objects
belong to.
Sysfs internally stores a pointer to the kobject that implements a
directory in the sysfs_dirent object associated with the directory. In
directory in the kernfs_node 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
@ -191,8 +191,9 @@ implementations:
be called again, rearmed, to fill the buffer.
- On write(2), sysfs expects the entire buffer to be passed during the
first write. Sysfs then passes the entire buffer to the store()
method.
first write. Sysfs then passes the entire buffer to the store() method.
A terminating null is added after the data on stores. This makes
functions like sysfs_streq() safe to use.
When writing sysfs files, userspace processes should first read the
entire file, modify the values it wishes to change, then write the

View File

@ -12,7 +12,7 @@ Because things like lock contention can severely impact performance.
- HOW
Lockdep already has hooks in the lock functions and maps lock instances to
lock classes. We build on that (see Documentation/lokcing/lockdep-design.txt).
lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
The graph below shows the relation between the lock functions and the various
hooks therein.

View File

@ -30,7 +30,7 @@ lead to false interrupt, but that doesn't harm.
ALS contains 4 different gain steps. Driver automatically
selects suitable gain step. After each measurement, reliability of the results
is estimated and new measurement is trigged if necessary.
is estimated and new measurement is triggered if necessary.
Platform data can provide tuned values to the conversion formulas if
values are known. Otherwise plain sensor default values are used.

View File

@ -29,7 +29,7 @@ Detection
The ISL29003 does not have an ID register which could be used to identify
it, so the detection routine will just try to read from the configured I2C
addess and consider the device to be present as soon as it ACKs the
address and consider the device to be present as soon as it ACKs the
transfer.

View File

@ -22,7 +22,7 @@ At reset, the MAX6875 reads the configuration EEPROM into its configuration
registers. The chip then begins to operate according to the values in the
registers.
The Maxim MAX6874 is a similar, mostly compatible device, with more intputs
The Maxim MAX6874 is a similar, mostly compatible device, with more inputs
and outputs:
vin gpi vout
MAX6874 6 4 8

View File

@ -1018,25 +1018,34 @@ solution for a couple of reasons:
$ ip link set can0 type can help
Usage: ip link set DEVICE type can
[ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
[ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
[ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
[ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
[ loopback { on | off } ]
[ listen-only { on | off } ]
[ triple-sampling { on | off } ]
[ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
[ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
[ restart-ms TIME-MS ]
[ restart ]
[ loopback { on | off } ]
[ listen-only { on | off } ]
[ triple-sampling { on | off } ]
[ one-shot { on | off } ]
[ berr-reporting { on | off } ]
[ fd { on | off } ]
[ fd-non-iso { on | off } ]
[ presume-ack { on | off } ]
Where: BITRATE := { 1..1000000 }
SAMPLE-POINT := { 0.000..0.999 }
TQ := { NUMBER }
PROP-SEG := { 1..8 }
PHASE-SEG1 := { 1..8 }
PHASE-SEG2 := { 1..8 }
SJW := { 1..4 }
RESTART-MS := { 0 | NUMBER }
[ restart-ms TIME-MS ]
[ restart ]
Where: BITRATE := { 1..1000000 }
SAMPLE-POINT := { 0.000..0.999 }
TQ := { NUMBER }
PROP-SEG := { 1..8 }
PHASE-SEG1 := { 1..8 }
PHASE-SEG2 := { 1..8 }
SJW := { 1..4 }
RESTART-MS := { 0 | NUMBER }
- Display CAN device details and statistics:
@ -1178,7 +1187,55 @@ solution for a couple of reasons:
The CAN device MTU can be retrieved e.g. with a SIOCGIFMTU ioctl() syscall.
N.B. CAN FD capable devices can also handle and send legacy CAN frames.
FIXME: Add details about the CAN FD controller configuration when available.
When configuring CAN FD capable CAN controllers an additional 'data' bitrate
has to be set. This bitrate for the data phase of the CAN FD frame has to be
at least the bitrate which was configured for the arbitration phase. This
second bitrate is specified analogue to the first bitrate but the bitrate
setting keywords for the 'data' bitrate start with 'd' e.g. dbitrate,
dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
within the configuration process the controller option "fd on" can be
specified to enable the CAN FD mode in the CAN controller. This controller
option also switches the device MTU to 72 (CANFD_MTU).
The first CAN FD specification presented as whitepaper at the International
CAN Conference 2012 needed to be improved for data integrity reasons.
Therefore two CAN FD implementations have to be distinguished today:
- ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
- non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
Finally there are three types of CAN FD controllers:
1. ISO compliant (fixed)
2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
The current ISO/non-ISO mode is announced by the CAN controller driver via
netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
switchable CAN FD controllers only.
Example configuring 500 kbit/s arbitration bitrate and 4 Mbit/s data bitrate:
$ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
dbitrate 4000000 dsample-point 0.8 fd on
$ ip -details link show can0
5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \
mode DEFAULT group default qlen 10
link/can promiscuity 0
can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
bitrate 500000 sample-point 0.750
tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
pcan_usb_pro_fd: tseg1 1..64 tseg2 1..16 sjw 1..16 brp 1..1024 \
brp-inc 1
dbitrate 4000000 dsample-point 0.800
dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
pcan_usb_pro_fd: dtseg1 1..16 dtseg2 1..8 dsjw 1..4 dbrp 1..1024 \
dbrp-inc 1
clock 80000000
Example when 'fd-non-iso on' is added on this switchable CAN FD adapter:
can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
6.7 Supported CAN hardware

View File

@ -203,7 +203,7 @@ functions with the user provided augmentation callback when inserting
and erasing nodes.
C files implementing augmented rbtree manipulation must include
<linux/rbtree_augmented.h> instead of <linus/rbtree.h>. Note that
<linux/rbtree_augmented.h> instead of <linux/rbtree.h>. Note that
linux/rbtree_augmented.h exposes some rbtree implementations details
you are not expected to rely on; please stick to the documented APIs
there and do not include <linux/rbtree_augmented.h> from header files

View File

@ -61,7 +61,7 @@ Documentation/kobject.txt 文档以获得更多关于 kobject 接口的
内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的
共同祖先;例如:某些对象属于某个子系统。
Sysfs 在与其目录关联的 sysfs_dirent 对象中内部保存一个指向实现
Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现
目录的 kobject 的指针。以前,这个 kobject 指针被 sysfs 直接用于
kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中kobject
引用计数只能通过 sysfs_schedule_callback() 函数直接修改。

View File

@ -3496,6 +3496,8 @@ M: Jonathan Corbet <corbet@lwn.net>
L: linux-doc@vger.kernel.org
S: Maintained
F: Documentation/
F: scripts/docproc.c
F: scripts/kernel-doc*
X: Documentation/ABI/
X: Documentation/devicetree/
X: Documentation/acpi

2
README
View File

@ -24,7 +24,7 @@ ON WHAT HARDWARE DOES IT RUN?
today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and
UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell,
IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS,
Xtensa, Tilera TILE, AVR32 and Renesas M32R architectures.
Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures.
Linux is easily portable to most general-purpose 32- or 64-bit architectures
as long as they have a paged memory management unit (PMMU) and a port of the

View File

@ -206,59 +206,73 @@ my $type_env = '(\$\w+)';
# One for each output format
# these work fairly well
my %highlights_html = ( $type_constant, "<i>\$1</i>",
$type_func, "<b>\$1</b>",
$type_struct_xml, "<i>\$1</i>",
$type_env, "<b><i>\$1</i></b>",
$type_param, "<tt><b>\$1</b></tt>" );
my @highlights_html = (
[$type_constant, "<i>\$1</i>"],
[$type_func, "<b>\$1</b>"],
[$type_struct_xml, "<i>\$1</i>"],
[$type_env, "<b><i>\$1</i></b>"],
[$type_param, "<tt><b>\$1</b></tt>"]
);
my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:";
my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
# html version 5
my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
$type_func, "<span class=\"func\">\$1</span>",
$type_struct_xml, "<span class=\"struct\">\$1</span>",
$type_env, "<span class=\"env\">\$1</span>",
$type_param, "<span class=\"param\">\$1</span>" );
my @highlights_html5 = (
[$type_constant, "<span class=\"const\">\$1</span>"],
[$type_func, "<span class=\"func\">\$1</span>"],
[$type_struct_xml, "<span class=\"struct\">\$1</span>"],
[$type_env, "<span class=\"env\">\$1</span>"],
[$type_param, "<span class=\"param\">\$1</span>]"]
);
my $blankline_html5 = $local_lt . "br /" . $local_gt;
# XML, docbook format
my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
$type_constant, "<constant>\$1</constant>",
$type_func, "<function>\$1</function>",
$type_struct_xml, "<structname>\$1</structname>",
$type_env, "<envar>\$1</envar>",
$type_param, "<parameter>\$1</parameter>" );
my @highlights_xml = (
["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
[$type_constant, "<constant>\$1</constant>"],
[$type_struct_xml, "<structname>\$1</structname>"],
[$type_param, "<parameter>\$1</parameter>"],
[$type_func, "<function>\$1</function>"],
[$type_env, "<envar>\$1</envar>"]
);
my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
# gnome, docbook format
my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
$type_func, "<function>\$1</function>",
$type_struct, "<structname>\$1</structname>",
$type_env, "<envar>\$1</envar>",
$type_param, "<parameter>\$1</parameter>" );
my @highlights_gnome = (
[$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
[$type_func, "<function>\$1</function>"],
[$type_struct, "<structname>\$1</structname>"],
[$type_env, "<envar>\$1</envar>"],
[$type_param, "<parameter>\$1</parameter>" ]
);
my $blankline_gnome = "</para><para>\n";
# these are pretty rough
my %highlights_man = ( $type_constant, "\$1",
$type_func, "\\\\fB\$1\\\\fP",
$type_struct, "\\\\fI\$1\\\\fP",
$type_param, "\\\\fI\$1\\\\fP" );
my @highlights_man = (
[$type_constant, "\$1"],
[$type_func, "\\\\fB\$1\\\\fP"],
[$type_struct, "\\\\fI\$1\\\\fP"],
[$type_param, "\\\\fI\$1\\\\fP"]
);
my $blankline_man = "";
# text-mode
my %highlights_text = ( $type_constant, "\$1",
$type_func, "\$1",
$type_struct, "\$1",
$type_param, "\$1" );
my @highlights_text = (
[$type_constant, "\$1"],
[$type_func, "\$1"],
[$type_struct, "\$1"],
[$type_param, "\$1"]
);
my $blankline_text = "";
# list mode
my %highlights_list = ( $type_constant, "\$1",
$type_func, "\$1",
$type_struct, "\$1",
$type_param, "\$1" );
my @highlights_list = (
[$type_constant, "\$1"],
[$type_func, "\$1"],
[$type_struct, "\$1"],
[$type_param, "\$1"]
);
my $blankline_list = "";
# read arguments
@ -273,7 +287,7 @@ my $verbose = 0;
my $output_mode = "man";
my $output_preformatted = 0;
my $no_doc_sections = 0;
my %highlights = %highlights_man;
my @highlights = @highlights_man;
my $blankline = $blankline_man;
my $modulename = "Kernel API";
my $function_only = 0;
@ -374,31 +388,31 @@ while ($ARGV[0] =~ m/^-(.*)/) {
my $cmd = shift @ARGV;
if ($cmd eq "-html") {
$output_mode = "html";
%highlights = %highlights_html;
@highlights = @highlights_html;
$blankline = $blankline_html;
} elsif ($cmd eq "-html5") {
$output_mode = "html5";
%highlights = %highlights_html5;
@highlights = @highlights_html5;
$blankline = $blankline_html5;
} elsif ($cmd eq "-man") {
$output_mode = "man";
%highlights = %highlights_man;
@highlights = @highlights_man;
$blankline = $blankline_man;
} elsif ($cmd eq "-text") {
$output_mode = "text";
%highlights = %highlights_text;
@highlights = @highlights_text;
$blankline = $blankline_text;
} elsif ($cmd eq "-docbook") {
$output_mode = "xml";
%highlights = %highlights_xml;
@highlights = @highlights_xml;
$blankline = $blankline_xml;
} elsif ($cmd eq "-list") {
$output_mode = "list";
%highlights = %highlights_list;
@highlights = @highlights_list;
$blankline = $blankline_list;
} elsif ($cmd eq "-gnome") {
$output_mode = "gnome";
%highlights = %highlights_gnome;
@highlights = @highlights_gnome;
$blankline = $blankline_gnome;
} elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
$modulename = shift @ARGV;
@ -1746,7 +1760,7 @@ sub output_declaration {
my $func = "output_${functype}_$output_mode";
if (($function_only==0) ||
( $function_only == 1 && defined($function_table{$name})) ||
( $function_only == 2 && !defined($function_table{$name})))
( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
{
&$func(@_);
$section_counter++;
@ -2391,12 +2405,13 @@ sub process_file($) {
my $descr;
my $in_purpose = 0;
my $initial_section_counter = $section_counter;
my ($orig_file) = @_;
if (defined($ENV{'SRCTREE'})) {
$file = "$ENV{'SRCTREE'}" . "/" . "@_";
$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
}
else {
$file = "@_";
$file = $orig_file;
}
if (defined($source_map{$file})) {
$file = $source_map{$file};
@ -2640,7 +2655,7 @@ sub process_file($) {
print "<refentry>\n";
print " <refnamediv>\n";
print " <refname>\n";
print " ${file}\n";
print " ${orig_file}\n";
print " </refname>\n";
print " <refpurpose>\n";
print " Document generation inconsistency\n";
@ -2654,7 +2669,7 @@ sub process_file($) {
print " <para>\n";
print " The template for this document tried to insert\n";
print " the structured comment from the file\n";
print " <filename>${file}</filename> at this point,\n";
print " <filename>${orig_file}</filename> at this point,\n";
print " but none was found.\n";
print " This dummy section is inserted to allow\n";
print " generation to continue.\n";
@ -2671,9 +2686,11 @@ $kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information
# using the s// operator.
foreach my $pattern (sort keys %highlights) {
# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
$dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
foreach my $k (keys @highlights) {
my $pattern = $highlights[$k][0];
my $result = $highlights[$k][1];
# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
$dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
}
# Read the file that maps relative names to absolute names for