Skip to content
Snippets Groups Projects
Commit d6a24d06 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6

Pull documentation updates from Jonathan Corbet:
 "Numerous fixes, the overdue removal of the i2o docs, some new Chinese
  translations, and, hopefully, the README fix that will end the flow of
  identical patches to that file"

* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (34 commits)
  Documentation/memcg: update memcg/kmem status
  Documentation: blackfin: Makefile: Typo building issue
  Documentation/vm/pagemap.txt: correct location of page-types tool
  Documentation/memory-barriers.txt: typo fix
  doc: Add guest_nice column to example output of `cat /proc/stat'
  Documentation/kernel-parameters: Move "eagerfpu" to its right place
  Documentation: gpio: Update ACPI part of the document to mention _DSD
  docs/completion.txt: Various tweaks and corrections
  doc: completion: context, scope and language fixes
  Documentation:Update Documentation/zh_CN/arm64/memory.txt
  Documentation:Update Documentation/zh_CN/arm64/booting.txt
  Documentation: Chinese translation of arm64/legacy_instructions.txt
  DocBook media: fix broken EIA hyperlink
  Documentation: tweak the maintainers entry
  README: Change gzip/bzip2 to xz compression format
  README: Update version number reference
  doc:pci: Fix typo in Documentation/PCI
  Documentation: drm: Use '->' when describing access through pointers.
  Documentation: Remove mentioning of block barriers
  Documentation/email-clients.txt: Fix one grammar mistake, add extra info about TB
  ...
parents 1f5014d6 19717542
No related branches found
No related tags found
No related merge requests found
Showing
with 177 additions and 607 deletions
...@@ -13,7 +13,7 @@ and NOT read it. Burn them, it's a great symbolic gesture. ...@@ -13,7 +13,7 @@ and NOT read it. Burn them, it's a great symbolic gesture.
Anyway, here goes: Anyway, here goes:
Chapter 1: Indentation Chapter 1: Indentation
Tabs are 8 characters, and thus indentations are also 8 characters. Tabs are 8 characters, and thus indentations are also 8 characters.
There are heretic movements that try to make indentations 4 (or even 2!) There are heretic movements that try to make indentations 4 (or even 2!)
...@@ -56,7 +56,6 @@ instead of "double-indenting" the "case" labels. E.g.: ...@@ -56,7 +56,6 @@ instead of "double-indenting" the "case" labels. E.g.:
break; break;
} }
Don't put multiple statements on a single line unless you have Don't put multiple statements on a single line unless you have
something to hide: something to hide:
...@@ -156,25 +155,25 @@ comments on. ...@@ -156,25 +155,25 @@ comments on.
Do not unnecessarily use braces where a single statement will do. Do not unnecessarily use braces where a single statement will do.
if (condition) if (condition)
action(); action();
and and
if (condition) if (condition)
do_this(); do_this();
else else
do_that(); do_that();
This does not apply if only one branch of a conditional statement is a single This does not apply if only one branch of a conditional statement is a single
statement; in the latter case use braces in both branches: statement; in the latter case use braces in both branches:
if (condition) { if (condition) {
do_this(); do_this();
do_that(); do_that();
} else { } else {
otherwise(); otherwise();
} }
3.1: Spaces 3.1: Spaces
...@@ -186,8 +185,11 @@ although they are not required in the language, as in: "sizeof info" after ...@@ -186,8 +185,11 @@ although they are not required in the language, as in: "sizeof info" after
"struct fileinfo info;" is declared). "struct fileinfo info;" is declared).
So use a space after these keywords: So use a space after these keywords:
if, switch, case, for, do, while if, switch, case, for, do, while
but not with sizeof, typeof, alignof, or __attribute__. E.g., but not with sizeof, typeof, alignof, or __attribute__. E.g.,
s = sizeof(struct file); s = sizeof(struct file);
Do not add spaces around (inside) parenthesized expressions. This example is Do not add spaces around (inside) parenthesized expressions. This example is
...@@ -209,12 +211,15 @@ such as any of these: ...@@ -209,12 +211,15 @@ such as any of these:
= + - < > * / % | & ^ <= >= == != ? : = + - < > * / % | & ^ <= >= == != ? :
but no space after unary operators: but no space after unary operators:
& * + - ~ ! sizeof typeof alignof __attribute__ defined & * + - ~ ! sizeof typeof alignof __attribute__ defined
no space before the postfix increment & decrement unary operators: no space before the postfix increment & decrement unary operators:
++ -- ++ --
no space after the prefix increment & decrement unary operators: no space after the prefix increment & decrement unary operators:
++ -- ++ --
and no space around the '.' and "->" structure member operators. and no space around the '.' and "->" structure member operators.
...@@ -268,13 +273,11 @@ See chapter 6 (Functions). ...@@ -268,13 +273,11 @@ See chapter 6 (Functions).
Chapter 5: Typedefs Chapter 5: Typedefs
Please don't use things like "vps_t". Please don't use things like "vps_t".
It's a _mistake_ to use typedef for structures and pointers. When you see a It's a _mistake_ to use typedef for structures and pointers. When you see a
vps_t a; vps_t a;
in the source, what does it mean? in the source, what does it mean?
In contrast, if it says In contrast, if it says
struct virtual_container *a; struct virtual_container *a;
...@@ -372,11 +375,11 @@ In source files, separate functions with one blank line. If the function is ...@@ -372,11 +375,11 @@ In source files, separate functions with one blank line. If the function is
exported, the EXPORT* macro for it should follow immediately after the closing exported, the EXPORT* macro for it should follow immediately after the closing
function brace line. E.g.: function brace line. E.g.:
int system_is_up(void) int system_is_up(void)
{ {
return system_state == SYSTEM_RUNNING; return system_state == SYSTEM_RUNNING;
} }
EXPORT_SYMBOL(system_is_up); EXPORT_SYMBOL(system_is_up);
In function prototypes, include parameter names with their data types. In function prototypes, include parameter names with their data types.
Although this is not required by the C language, it is preferred in Linux Although this is not required by the C language, it is preferred in Linux
...@@ -405,34 +408,34 @@ The rationale for using gotos is: ...@@ -405,34 +408,34 @@ The rationale for using gotos is:
modifications are prevented modifications are prevented
- saves the compiler work to optimize redundant code away ;) - saves the compiler work to optimize redundant code away ;)
int fun(int a) int fun(int a)
{ {
int result = 0; int result = 0;
char *buffer; char *buffer;
buffer = kmalloc(SIZE, GFP_KERNEL); buffer = kmalloc(SIZE, GFP_KERNEL);
if (!buffer) if (!buffer)
return -ENOMEM; return -ENOMEM;
if (condition1) { if (condition1) {
while (loop1) { while (loop1) {
... ...
}
result = 1;
goto out_buffer;
} }
result = 1; ...
goto out_buffer; out_buffer:
kfree(buffer);
return result;
} }
...
out_buffer:
kfree(buffer);
return result;
}
A common type of bug to be aware of it "one err bugs" which look like this: A common type of bug to be aware of it "one err bugs" which look like this:
err: err:
kfree(foo->bar); kfree(foo->bar);
kfree(foo); kfree(foo);
return ret; return ret;
The bug in this code is that on some exit paths "foo" is NULL. Normally the The bug in this code is that on some exit paths "foo" is NULL. Normally the
fix for this is to split it up into two error labels "err_bar:" and "err_foo:". fix for this is to split it up into two error labels "err_bar:" and "err_foo:".
...@@ -503,9 +506,9 @@ values. To do the latter, you can stick the following in your .emacs file: ...@@ -503,9 +506,9 @@ values. To do the latter, you can stick the following in your .emacs file:
(defun c-lineup-arglist-tabs-only (ignored) (defun c-lineup-arglist-tabs-only (ignored)
"Line up argument lists by tabs, not spaces" "Line up argument lists by tabs, not spaces"
(let* ((anchor (c-langelem-pos c-syntactic-element)) (let* ((anchor (c-langelem-pos c-syntactic-element))
(column (c-langelem-2nd-pos c-syntactic-element)) (column (c-langelem-2nd-pos c-syntactic-element))
(offset (- (1+ column) anchor)) (offset (- (1+ column) anchor))
(steps (floor offset c-basic-offset))) (steps (floor offset c-basic-offset)))
(* (max steps 1) (* (max steps 1)
c-basic-offset))) c-basic-offset)))
...@@ -612,7 +615,7 @@ have a reference count on it, you almost certainly have a bug. ...@@ -612,7 +615,7 @@ have a reference count on it, you almost certainly have a bug.
Names of macros defining constants and labels in enums are capitalized. Names of macros defining constants and labels in enums are capitalized.
#define CONSTANT 0x12345 #define CONSTANT 0x12345
Enums are preferred when defining several related constants. Enums are preferred when defining several related constants.
...@@ -623,28 +626,28 @@ Generally, inline functions are preferable to macros resembling functions. ...@@ -623,28 +626,28 @@ Generally, inline functions are preferable to macros resembling functions.
Macros with multiple statements should be enclosed in a do - while block: Macros with multiple statements should be enclosed in a do - while block:
#define macrofun(a, b, c) \ #define macrofun(a, b, c) \
do { \ do { \
if (a == 5) \ if (a == 5) \
do_this(b, c); \ do_this(b, c); \
} while (0) } while (0)
Things to avoid when using macros: Things to avoid when using macros:
1) macros that affect control flow: 1) macros that affect control flow:
#define FOO(x) \ #define FOO(x) \
do { \ do { \
if (blah(x) < 0) \ if (blah(x) < 0) \
return -EBUGGERED; \ return -EBUGGERED; \
} while(0) } while(0)
is a _very_ bad idea. It looks like a function call but exits the "calling" is a _very_ bad idea. It looks like a function call but exits the "calling"
function; don't break the internal parsers of those who will read the code. function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name: 2) macros that depend on having a local variable with a magic name:
#define FOO(val) bar(index, val) #define FOO(val) bar(index, val)
might look like a good thing, but it's confusing as hell when one reads the might look like a good thing, but it's confusing as hell when one reads the
code and it's prone to breakage from seemingly innocent changes. code and it's prone to breakage from seemingly innocent changes.
...@@ -656,8 +659,8 @@ bite you if somebody e.g. turns FOO into an inline function. ...@@ -656,8 +659,8 @@ bite you if somebody e.g. turns FOO into an inline function.
must enclose the expression in parentheses. Beware of similar issues with must enclose the expression in parentheses. Beware of similar issues with
macros using parameters. macros using parameters.
#define CONSTANT 0x4000 #define CONSTANT 0x4000
#define CONSTEXP (CONSTANT | 3) #define CONSTEXP (CONSTANT | 3)
5) namespace collisions when defining local variables in macros resembling 5) namespace collisions when defining local variables in macros resembling
functions: functions:
...@@ -809,11 +812,11 @@ you should use, rather than explicitly coding some variant of them yourself. ...@@ -809,11 +812,11 @@ you should use, rather than explicitly coding some variant of them yourself.
For example, if you need to calculate the length of an array, take advantage For example, if you need to calculate the length of an array, take advantage
of the macro of the macro
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
Similarly, if you need to calculate the size of some structure member, use Similarly, if you need to calculate the size of some structure member, use
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
There are also min() and max() macros that do strict type checking if you There are also min() and max() macros that do strict type checking if you
need them. Feel free to peruse that header file to see what else is already need them. Feel free to peruse that header file to see what else is already
...@@ -826,19 +829,19 @@ Some editors can interpret configuration information embedded in source files, ...@@ -826,19 +829,19 @@ Some editors can interpret configuration information embedded in source files,
indicated with special markers. For example, emacs interprets lines marked indicated with special markers. For example, emacs interprets lines marked
like this: like this:
-*- mode: c -*- -*- mode: c -*-
Or like this: Or like this:
/* /*
Local Variables: Local Variables:
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
End: End:
*/ */
Vim interprets markers that look like this: Vim interprets markers that look like this:
/* vim:set sw=8 noet */ /* vim:set sw=8 noet */
Do not include any of these in source files. People have their own personal Do not include any of these in source files. People have their own personal
editor configurations, and your source files should not override them. This editor configurations, and your source files should not override them. This
...@@ -915,9 +918,9 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines), ...@@ -915,9 +918,9 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
place a comment after the #endif on the same line, noting the conditional place a comment after the #endif on the same line, noting the conditional
expression used. For instance: expression used. For instance:
#ifdef CONFIG_SOMETHING #ifdef CONFIG_SOMETHING
... ...
#endif /* CONFIG_SOMETHING */ #endif /* CONFIG_SOMETHING */
Appendix I: References Appendix I: References
......
...@@ -1293,7 +1293,7 @@ int max_width, max_height;</synopsis> ...@@ -1293,7 +1293,7 @@ int max_width, max_height;</synopsis>
</para> </para>
<para> <para>
If a page flip can be successfully scheduled the driver must set the If a page flip can be successfully scheduled the driver must set the
<code>drm_crtc-&lt;fb</code> field to the new framebuffer pointed to <code>drm_crtc-&gt;fb</code> field to the new framebuffer pointed to
by <code>fb</code>. This is important so that the reference counting by <code>fb</code>. This is important so that the reference counting
on framebuffers stays balanced. on framebuffers stays balanced.
</para> </para>
......
<bibliography> <bibliography>
<title>References</title> <title>References</title>
<biblioentry id="eia608"> <biblioentry id="cea608">
<abbrev>EIA&nbsp;608-B</abbrev> <abbrev>CEA&nbsp;608-E</abbrev>
<authorgroup> <authorgroup>
<corpauthor>Electronic Industries Alliance (<ulink <corpauthor>Consumer Electronics Association (<ulink
url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor> url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>
</authorgroup> </authorgroup>
<title>EIA 608-B "Recommended Practice for Line 21 Data <title>CEA-608-E R-2014 "Line 21 Data Services"</title>
Service"</title>
</biblioentry> </biblioentry>
<biblioentry id="en300294"> <biblioentry id="en300294">
......
...@@ -254,7 +254,7 @@ ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry> ...@@ -254,7 +254,7 @@ ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
<row> <row>
<entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
<entry>0x1000</entry> <entry>0x1000</entry>
<entry><xref linkend="eia608" /></entry> <entry><xref linkend="cea608" /></entry>
<entry>NTSC line 21, 284 (second field 21)</entry> <entry>NTSC line 21, 284 (second field 21)</entry>
<entry>Two bytes in transmission order, including parity <entry>Two bytes in transmission order, including parity
bit, lsb first transmitted.</entry> bit, lsb first transmitted.</entry>
......
...@@ -205,7 +205,7 @@ ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry> ...@@ -205,7 +205,7 @@ ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
<row> <row>
<entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
<entry>0x1000</entry> <entry>0x1000</entry>
<entry><xref linkend="eia608" /></entry> <entry><xref linkend="cea608" /></entry>
<entry>NTSC line 21, 284 (second field 21)</entry> <entry>NTSC line 21, 284 (second field 21)</entry>
<entry>Two bytes in transmission order, including parity <entry>Two bytes in transmission order, including parity
bit, lsb first transmitted.</entry> bit, lsb first transmitted.</entry>
......
...@@ -353,7 +353,7 @@ retry: ...@@ -353,7 +353,7 @@ retry:
rc = pci_enable_msix_range(adapter->pdev, adapter->msix_entries, rc = pci_enable_msix_range(adapter->pdev, adapter->msix_entries,
maxvec, maxvec); maxvec, maxvec);
/* /*
* -ENOSPC is the only error code allowed to be analized * -ENOSPC is the only error code allowed to be analyzed
*/ */
if (rc == -ENOSPC) { if (rc == -ENOSPC) {
if (maxvec == 1) if (maxvec == 1)
...@@ -370,7 +370,7 @@ retry: ...@@ -370,7 +370,7 @@ retry:
return rc; return rc;
} }
Note how pci_enable_msix_range() return value is analized for a fallback - Note how pci_enable_msix_range() return value is analyzed for a fallback -
any error code other than -ENOSPC indicates a fatal error and should not any error code other than -ENOSPC indicates a fatal error and should not
be retried. be retried.
...@@ -486,7 +486,7 @@ during development. ...@@ -486,7 +486,7 @@ during development.
If your device supports both MSI-X and MSI capabilities, you should use If your device supports both MSI-X and MSI capabilities, you should use
the MSI-X facilities in preference to the MSI facilities. As mentioned the MSI-X facilities in preference to the MSI facilities. As mentioned
above, MSI-X supports any number of interrupts between 1 and 2048. above, MSI-X supports any number of interrupts between 1 and 2048.
In constrast, MSI is restricted to a maximum of 32 interrupts (and In contrast, MSI is restricted to a maximum of 32 interrupts (and
must be a power of two). In addition, the MSI interrupt vectors must must be a power of two). In addition, the MSI interrupt vectors must
be allocated consecutively, so the system might not be able to allocate be allocated consecutively, so the system might not be able to allocate
as many vectors for MSI as it could for MSI-X. On some platforms, MSI as many vectors for MSI as it could for MSI-X. On some platforms, MSI
...@@ -501,18 +501,9 @@ necessary to disable interrupts (Linux guarantees the same interrupt will ...@@ -501,18 +501,9 @@ necessary to disable interrupts (Linux guarantees the same interrupt will
not be re-entered). If a device uses multiple interrupts, the driver not be re-entered). If a device uses multiple interrupts, the driver
must disable interrupts while the lock is held. If the device sends must disable interrupts while the lock is held. If the device sends
a different interrupt, the driver will deadlock trying to recursively a different interrupt, the driver will deadlock trying to recursively
acquire the spinlock. acquire the spinlock. Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
There are two solutions. The first is to take the lock with and acquire the lock (see Documentation/DocBook/kernel-locking).
spin_lock_irqsave() or spin_lock_irq() (see
Documentation/DocBook/kernel-locking). The second is to specify
IRQF_DISABLED to request_irq() so that the kernel runs the entire
interrupt routine with interrupts disabled.
If your MSI interrupt routine does not hold the lock for the whole time
it is running, the first solution may be best. The second solution is
normally preferred as it avoids making two transitions from interrupt
disabled to enabled and back again.
4.6 How to tell whether MSI/MSI-X is enabled on a device 4.6 How to tell whether MSI/MSI-X is enabled on a device
......
...@@ -256,7 +256,7 @@ STEP 4: Slot Reset ...@@ -256,7 +256,7 @@ STEP 4: Slot Reset
------------------ ------------------
In response to a return value of PCI_ERS_RESULT_NEED_RESET, the In response to a return value of PCI_ERS_RESULT_NEED_RESET, the
the platform will peform a slot reset on the requesting PCI device(s). the platform will perform a slot reset on the requesting PCI device(s).
The actual steps taken by a platform to perform a slot reset The actual steps taken by a platform to perform a slot reset
will be platform-dependent. Upon completion of slot reset, the will be platform-dependent. Upon completion of slot reset, the
platform will call the device slot_reset() callback. platform will call the device slot_reset() callback.
......
...@@ -66,8 +66,8 @@ hardware (mostly chipsets) has root ports that cannot obtain the reporting ...@@ -66,8 +66,8 @@ hardware (mostly chipsets) has root ports that cannot obtain the reporting
source ID. nosourceid=n by default. source ID. nosourceid=n by default.
2.3 AER error output 2.3 AER error output
When a PCI-E AER error is captured, an error message will be outputed to When a PCI-E AER error is captured, an error message will be outputted to
console. If it's a correctable error, it is outputed as a warning. console. If it's a correctable error, it is outputted as a warning.
Otherwise, it is printed as an error. So users could choose different Otherwise, it is printed as an error. So users could choose different
log level to filter out correctable error messages. log level to filter out correctable error messages.
......
...@@ -58,13 +58,18 @@ serial format options as described in ...@@ -58,13 +58,18 @@ serial format options as described in
-------------------------- --------------------------
Existing boot loaders: OPTIONAL Existing boot loaders: OPTIONAL
New boot loaders: MANDATORY New boot loaders: MANDATORY except for DT-only platforms
The boot loader should detect the machine type its running on by some The boot loader should detect the machine type its running on by some
method. Whether this is a hard coded value or some algorithm that method. Whether this is a hard coded value or some algorithm that
looks at the connected hardware is beyond the scope of this document. looks at the connected hardware is beyond the scope of this document.
The boot loader must ultimately be able to provide a MACH_TYPE_xxx The boot loader must ultimately be able to provide a MACH_TYPE_xxx
value to the kernel. (see linux/arch/arm/tools/mach-types). value to the kernel. (see linux/arch/arm/tools/mach-types). This
should be passed to the kernel in register r1.
For DT-only platforms, the machine type will be determined by device
tree. set the machine type to all ones (~0). This is not strictly
necessary, but assures that it will not match any existing types.
4. Setup boot data 4. Setup boot data
------------------ ------------------
......
...@@ -185,13 +185,20 @@ Kernel entry (head.S) ...@@ -185,13 +185,20 @@ Kernel entry (head.S)
board devices are used, or the device is setup, and provides that board devices are used, or the device is setup, and provides that
machine specific "personality." machine specific "personality."
This fine-grained machine specific selection is controlled by the machine For platforms that support device tree (DT), the machine selection is
type ID, which acts both as a run-time and a compile-time code selection controlled at runtime by passing the device tree blob to the kernel. At
method. compile-time, support for the machine type must be selected. This allows for
a single multiplatform kernel build to be used for several machine types.
You can register a new machine via the web site at: For platforms that do not use device tree, this machine selection is
controlled by the machine type ID, which acts both as a run-time and a
compile-time code selection method. You can register a new machine via the
web site at:
<http://www.arm.linux.org.uk/developer/machines/> <http://www.arm.linux.org.uk/developer/machines/>
Note: Please do not register a machine type for DT-only platforms. If your
platform is DT-only, you do not need a registered machine type.
--- ---
Russell King (15/03/2004) Russell King (15/03/2004)
ifneq ($(CONFIG_BLACKFIN),) ifneq ($(CONFIG_BLACKFIN),)
ifneq ($(CONFIG_BFIN_GPTIMERS,) ifneq ($(CONFIG_BFIN_GPTIMERS),)
obj-m := gptimers-example.o obj-m := gptimers-example.o
endif endif
endif endif
...@@ -48,8 +48,7 @@ Description of Contents: ...@@ -48,8 +48,7 @@ Description of Contents:
- Highmem I/O support - Highmem I/O support
- I/O scheduler modularization - I/O scheduler modularization
1.2 Tuning based on high level requirements/capabilities 1.2 Tuning based on high level requirements/capabilities
1.2.1 I/O Barriers 1.2.1 Request Priority/Latency
1.2.2 Request Priority/Latency
1.3 Direct access/bypass to lower layers for diagnostics and special 1.3 Direct access/bypass to lower layers for diagnostics and special
device operations device operations
1.3.1 Pre-built commands 1.3.1 Pre-built commands
...@@ -255,29 +254,12 @@ some control over i/o ordering. ...@@ -255,29 +254,12 @@ some control over i/o ordering.
What kind of support exists at the generic block layer for this ? What kind of support exists at the generic block layer for this ?
The flags and rw fields in the bio structure can be used for some tuning The flags and rw fields in the bio structure can be used for some tuning
from above e.g indicating that an i/o is just a readahead request, or for from above e.g indicating that an i/o is just a readahead request, or priority
marking barrier requests (discussed next), or priority settings (currently settings (currently unused). As far as user applications are concerned they
unused). As far as user applications are concerned they would need an would need an additional mechanism either via open flags or ioctls, or some
additional mechanism either via open flags or ioctls, or some other upper other upper level mechanism to communicate such settings to block.
level mechanism to communicate such settings to block.
1.2.1 Request Priority/Latency
1.2.1 I/O Barriers
There is a way to enforce strict ordering for i/os through barriers.
All requests before a barrier point must be serviced before the barrier
request and any other requests arriving after the barrier will not be
serviced until after the barrier has completed. This is useful for higher
level control on write ordering, e.g flushing a log of committed updates
to disk before the corresponding updates themselves.
A flag in the bio structure, BIO_BARRIER is used to identify a barrier i/o.
The generic i/o scheduler would make sure that it places the barrier request and
all other requests coming after it after all the previous requests in the
queue. Barriers may be implemented in different ways depending on the
driver. For more details regarding I/O barriers, please read barrier.txt
in this directory.
1.2.2 Request Priority/Latency
Todo/Under discussion: Todo/Under discussion:
Arjan's proposed request priority scheme allows higher levels some broad Arjan's proposed request priority scheme allows higher levels some broad
...@@ -906,8 +888,8 @@ queue and specific I/O schedulers. Unless stated otherwise, elevator is used ...@@ -906,8 +888,8 @@ queue and specific I/O schedulers. Unless stated otherwise, elevator is used
to refer to both parts and I/O scheduler to specific I/O schedulers. to refer to both parts and I/O scheduler to specific I/O schedulers.
Block layer implements generic dispatch queue in block/*.c. Block layer implements generic dispatch queue in block/*.c.
The generic dispatch queue is responsible for properly ordering barrier The generic dispatch queue is responsible for requeueing, handling non-fs
requests, requeueing, handling non-fs requests and all other subtleties. requests and all other subtleties.
Specific I/O schedulers are responsible for ordering normal filesystem Specific I/O schedulers are responsible for ordering normal filesystem
requests. They can also choose to delay certain requests to improve requests. They can also choose to delay certain requests to improve
......
...@@ -275,11 +275,6 @@ When oom event notifier is registered, event will be delivered. ...@@ -275,11 +275,6 @@ When oom event notifier is registered, event will be delivered.
2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM) 2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM)
WARNING: Current implementation lacks reclaim support. That means allocation
attempts will fail when close to the limit even if there are plenty of
kmem available for reclaim. That makes this option unusable in real
life so DO NOT SELECT IT unless for development purposes.
With the Kernel memory extension, the Memory Controller is able to limit With the Kernel memory extension, the Memory Controller is able to limit
the amount of kernel memory used by the system. Kernel memory is fundamentally the amount of kernel memory used by the system. Kernel memory is fundamentally
different than user memory, since it can't be swapped out, which makes it different than user memory, since it can't be swapped out, which makes it
...@@ -345,6 +340,9 @@ set: ...@@ -345,6 +340,9 @@ set:
In this case, the admin could set up K so that the sum of all groups is In this case, the admin could set up K so that the sum of all groups is
never greater than the total memory, and freely set U at the cost of his never greater than the total memory, and freely set U at the cost of his
QoS. QoS.
WARNING: In the current implementation, memory reclaim will NOT be
triggered for a cgroup when it hits K while staying below U, which makes
this setup impractical.
U != 0, K >= U: U != 0, K >= U:
Since kmem charges will also be fed to the user counter and reclaim will be Since kmem charges will also be fed to the user counter and reclaim will be
......
...@@ -211,7 +211,7 @@ Thunderbird (GUI) ...@@ -211,7 +211,7 @@ Thunderbird (GUI)
Thunderbird is an Outlook clone that likes to mangle text, but there are ways Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving. to coerce it into behaving.
- Allows use of an external editor: - Allow use of an external editor:
The easiest thing to do with Thunderbird and patches is to use an The easiest thing to do with Thunderbird and patches is to use an
"external editor" extension and then just use your favorite $EDITOR "external editor" extension and then just use your favorite $EDITOR
for reading/merging patches into the body text. To do this, download for reading/merging patches into the body text. To do this, download
...@@ -219,6 +219,15 @@ to coerce it into behaving. ...@@ -219,6 +219,15 @@ to coerce it into behaving.
View->Toolbars->Customize... and finally just click on it when in the View->Toolbars->Customize... and finally just click on it when in the
Compose dialog. Compose dialog.
Please note that "external editor" requires that your editor must not
fork, or in other words, the editor must not return before closing.
You may have to pass additional flags or change the settings of your
editor. Most notably if you are using gvim then you must pass the -f
option to gvim by putting "/usr/bin/gvim -f" (if the binary is in
/usr/bin) to the text editor field in "external editor" settings. If you
are using some other editor then please read its manual to find out how
to do this.
To beat some sense out of the internal editor, do this: To beat some sense out of the internal editor, do this:
- Edit your Thunderbird config settings so that it won't use format=flowed. - Edit your Thunderbird config settings so that it won't use format=flowed.
......
...@@ -1260,9 +1260,9 @@ Various pieces of information about kernel activity are available in the ...@@ -1260,9 +1260,9 @@ Various pieces of information about kernel activity are available in the
since the system first booted. For a quick look, simply cat the file: since the system first booted. For a quick look, simply cat the file:
> cat /proc/stat > cat /proc/stat
cpu 2255 34 2290 22625563 6290 127 456 0 0 cpu 2255 34 2290 22625563 6290 127 456 0 0 0
cpu0 1132 34 1441 11311718 3675 127 438 0 0 cpu0 1132 34 1441 11311718 3675 127 438 0 0 0
cpu1 1123 0 849 11313845 2614 0 18 0 0 cpu1 1123 0 849 11313845 2614 0 18 0 0 0
intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...] intr 114930548 113199788 3 0 5 263 0 4 [... lots more numbers ...]
ctxt 1990473 ctxt 1990473
btime 1062191376 btime 1062191376
......
...@@ -50,10 +50,43 @@ gpiod_is_active_low(power) will be true). ...@@ -50,10 +50,43 @@ gpiod_is_active_low(power) will be true).
ACPI ACPI
---- ----
ACPI does not support function names for GPIOs. Therefore, only the "idx" ACPI also supports function names for GPIOs in a similar fashion to DT.
argument of gpiod_get_index() is useful to discriminate between GPIOs assigned The above DT example can be converted to an equivalent ACPI description
to a device. The "con_id" argument can still be set for debugging purposes (it with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
will appear under error messages as well as debug and sysfs nodes).
Device (FOO) {
Name (_CRS, ResourceTemplate () {
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
"\\_SB.GPI0") {15} // red
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
"\\_SB.GPI0") {16} // green
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
"\\_SB.GPI0") {17} // blue
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
"\\_SB.GPI0") {1} // power
})
Name (_DSD, Package () {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () {
"led-gpios",
Package () {
^FOO, 0, 0, 1,
^FOO, 1, 0, 1,
^FOO, 2, 0, 1,
}
},
Package () {
"power-gpios",
Package () {^FOO, 3, 0, 0},
},
}
})
}
For more information about the ACPI GPIO bindings see
Documentation/acpi/gpio-properties.txt.
Platform Data Platform Data
------------- -------------
......
Linux I2O Support (c) Copyright 1999 Red Hat Software
and others.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version
2 of the License, or (at your option) any later version.
AUTHORS (so far)
Alan Cox, Building Number Three Ltd.
Core code, SCSI and Block OSMs
Steve Ralston, LSI Logic Corp.
Debugging SCSI and Block OSM
Deepak Saxena, Intel Corp.
Various core/block extensions
/proc interface, bug fixes
Ioctl interfaces for control
Debugging LAN OSM
Philip Rumpf
Fixed assorted dumb SMP locking bugs
Juha Sievanen, University of Helsinki Finland
LAN OSM code
/proc interface to LAN class
Bug fixes
Core code extensions
Auvo Häkkinen, University of Helsinki Finland
LAN OSM code
/Proc interface to LAN class
Bug fixes
Core code extensions
Taneli Vähäkangas, University of Helsinki Finland
Fixes to i2o_config
CREDITS
This work was made possible by
Red Hat Software
Funding for the Building #3 part of the project
Symbios Logic (Now LSI)
Host adapters, hints, known to work platforms when I hit
compatibility problems
BoxHill Corporation
Loan of initial FibreChannel disk array used for development work.
European Commission
Funding the work done by the University of Helsinki
SysKonnect
Loan of FDDI and Gigabit Ethernet cards
ASUSTeK
Loan of I2O motherboard
Linux I2O User Space Interface
rev 0.3 - 04/20/99
=============================================================================
Originally written by Deepak Saxena(deepak@plexity.net)
Currently maintained by Deepak Saxena(deepak@plexity.net)
=============================================================================
I. Introduction
The Linux I2O subsystem provides a set of ioctl() commands that can be
utilized by user space applications to communicate with IOPs and devices
on individual IOPs. This document defines the specific ioctl() commands
that are available to the user and provides examples of their uses.
This document assumes the reader is familiar with or has access to the
I2O specification as no I2O message parameters are outlined. For information
on the specification, see http://www.i2osig.org
This document and the I2O user space interface are currently maintained
by Deepak Saxena. Please send all comments, errata, and bug fixes to
deepak@csociety.purdue.edu
II. IOP Access
Access to the I2O subsystem is provided through the device file named
/dev/i2o/ctl. This file is a character file with major number 10 and minor
number 166. It can be created through the following command:
mknod /dev/i2o/ctl c 10 166
III. Determining the IOP Count
SYNOPSIS
ioctl(fd, I2OGETIOPS, int *count);
u8 count[MAX_I2O_CONTROLLERS];
DESCRIPTION
This function returns the system's active IOP table. count should
point to a buffer containing MAX_I2O_CONTROLLERS entries. Upon
returning, each entry will contain a non-zero value if the given
IOP unit is active, and NULL if it is inactive or non-existent.
RETURN VALUE.
Returns 0 if no errors occur, and -1 otherwise. If an error occurs,
errno is set appropriately:
EFAULT Invalid user space pointer was passed
IV. Getting Hardware Resource Table
SYNOPSIS
ioctl(fd, I2OHRTGET, struct i2o_cmd_hrt *hrt);
struct i2o_cmd_hrtlct
{
u32 iop; /* IOP unit number */
void *resbuf; /* Buffer for result */
u32 *reslen; /* Buffer length in bytes */
};
DESCRIPTION
This function returns the Hardware Resource Table of the IOP specified
by hrt->iop in the buffer pointed to by hrt->resbuf. The actual size of
the data is written into *(hrt->reslen).
RETURNS
This function returns 0 if no errors occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ENOBUFS Buffer not large enough. If this occurs, the required
buffer length is written into *(hrt->reslen)
V. Getting Logical Configuration Table
SYNOPSIS
ioctl(fd, I2OLCTGET, struct i2o_cmd_lct *lct);
struct i2o_cmd_hrtlct
{
u32 iop; /* IOP unit number */
void *resbuf; /* Buffer for result */
u32 *reslen; /* Buffer length in bytes */
};
DESCRIPTION
This function returns the Logical Configuration Table of the IOP specified
by lct->iop in the buffer pointed to by lct->resbuf. The actual size of
the data is written into *(lct->reslen).
RETURNS
This function returns 0 if no errors occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ENOBUFS Buffer not large enough. If this occurs, the required
buffer length is written into *(lct->reslen)
VI. Setting Parameters
SYNOPSIS
ioctl(fd, I2OPARMSET, struct i2o_parm_setget *ops);
struct i2o_cmd_psetget
{
u32 iop; /* IOP unit number */
u32 tid; /* Target device TID */
void *opbuf; /* Operation List buffer */
u32 oplen; /* Operation List buffer length in bytes */
void *resbuf; /* Result List buffer */
u32 *reslen; /* Result List buffer length in bytes */
};
DESCRIPTION
This function posts a UtilParamsSet message to the device identified
by ops->iop and ops->tid. The operation list for the message is
sent through the ops->opbuf buffer, and the result list is written
into the buffer pointed to by ops->resbuf. The number of bytes
written is placed into *(ops->reslen).
RETURNS
The return value is the size in bytes of the data written into
ops->resbuf if no errors occur. If an error occurs, -1 is returned
and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ENOBUFS Buffer not large enough. If this occurs, the required
buffer length is written into *(ops->reslen)
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
A return value of 0 does not mean that the value was actually
changed properly on the IOP. The user should check the result
list to determine the specific status of the transaction.
VII. Getting Parameters
SYNOPSIS
ioctl(fd, I2OPARMGET, struct i2o_parm_setget *ops);
struct i2o_parm_setget
{
u32 iop; /* IOP unit number */
u32 tid; /* Target device TID */
void *opbuf; /* Operation List buffer */
u32 oplen; /* Operation List buffer length in bytes */
void *resbuf; /* Result List buffer */
u32 *reslen; /* Result List buffer length in bytes */
};
DESCRIPTION
This function posts a UtilParamsGet message to the device identified
by ops->iop and ops->tid. The operation list for the message is
sent through the ops->opbuf buffer, and the result list is written
into the buffer pointed to by ops->resbuf. The actual size of data
written is placed into *(ops->reslen).
RETURNS
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ENOBUFS Buffer not large enough. If this occurs, the required
buffer length is written into *(ops->reslen)
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
A return value of 0 does not mean that the value was actually
properly retrieved. The user should check the result list
to determine the specific status of the transaction.
VIII. Downloading Software
SYNOPSIS
ioctl(fd, I2OSWDL, struct i2o_sw_xfer *sw);
struct i2o_sw_xfer
{
u32 iop; /* IOP unit number */
u8 flags; /* DownloadFlags field */
u8 sw_type; /* Software type */
u32 sw_id; /* Software ID */
void *buf; /* Pointer to software buffer */
u32 *swlen; /* Length of software buffer */
u32 *maxfrag; /* Number of fragments */
u32 *curfrag; /* Current fragment number */
};
DESCRIPTION
This function downloads a software fragment pointed by sw->buf
to the iop identified by sw->iop. The DownloadFlags, SwID, SwType
and SwSize fields of the ExecSwDownload message are filled in with
the values of sw->flags, sw->sw_id, sw->sw_type and *(sw->swlen).
The fragments _must_ be sent in order and be 8K in size. The last
fragment _may_ be shorter, however. The kernel will compute its
size based on information in the sw->swlen field.
Please note that SW transfers can take a long time.
RETURNS
This function returns 0 no errors occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
IX. Uploading Software
SYNOPSIS
ioctl(fd, I2OSWUL, struct i2o_sw_xfer *sw);
struct i2o_sw_xfer
{
u32 iop; /* IOP unit number */
u8 flags; /* UploadFlags */
u8 sw_type; /* Software type */
u32 sw_id; /* Software ID */
void *buf; /* Pointer to software buffer */
u32 *swlen; /* Length of software buffer */
u32 *maxfrag; /* Number of fragments */
u32 *curfrag; /* Current fragment number */
};
DESCRIPTION
This function uploads a software fragment from the IOP identified
by sw->iop, sw->sw_type, sw->sw_id and optionally sw->swlen fields.
The UploadFlags, SwID, SwType and SwSize fields of the ExecSwUpload
message are filled in with the values of sw->flags, sw->sw_id,
sw->sw_type and *(sw->swlen).
The fragments _must_ be requested in order and be 8K in size. The
user is responsible for allocating memory pointed by sw->buf. The
last fragment _may_ be shorter.
Please note that SW transfers can take a long time.
RETURNS
This function returns 0 if no errors occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
X. Removing Software
SYNOPSIS
ioctl(fd, I2OSWDEL, struct i2o_sw_xfer *sw);
struct i2o_sw_xfer
{
u32 iop; /* IOP unit number */
u8 flags; /* RemoveFlags */
u8 sw_type; /* Software type */
u32 sw_id; /* Software ID */
void *buf; /* Unused */
u32 *swlen; /* Length of the software data */
u32 *maxfrag; /* Unused */
u32 *curfrag; /* Unused */
};
DESCRIPTION
This function removes software from the IOP identified by sw->iop.
The RemoveFlags, SwID, SwType and SwSize fields of the ExecSwRemove message
are filled in with the values of sw->flags, sw->sw_id, sw->sw_type and
*(sw->swlen). Give zero in *(sw->len) if the value is unknown. IOP uses
*(sw->swlen) value to verify correct identication of the module to remove.
The actual size of the module is written into *(sw->swlen).
RETURNS
This function returns 0 if no errors occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
X. Validating Configuration
SYNOPSIS
ioctl(fd, I2OVALIDATE, int *iop);
u32 iop;
DESCRIPTION
This function posts an ExecConfigValidate message to the controller
identified by iop. This message indicates that the current
configuration is accepted. The iop changes the status of suspect drivers
to valid and may delete old drivers from its store.
RETURNS
This function returns 0 if no erro occur. If an error occurs, -1 is
returned and errno is set appropriately:
ETIMEDOUT Timeout waiting for reply message
ENXIO Invalid IOP number
XI. Configuration Dialog
SYNOPSIS
ioctl(fd, I2OHTML, struct i2o_html *htquery);
struct i2o_html
{
u32 iop; /* IOP unit number */
u32 tid; /* Target device ID */
u32 page; /* HTML page */
void *resbuf; /* Buffer for reply HTML page */
u32 *reslen; /* Length in bytes of reply buffer */
void *qbuf; /* Pointer to HTTP query string */
u32 qlen; /* Length in bytes of query string buffer */
};
DESCRIPTION
This function posts an UtilConfigDialog message to the device identified
by htquery->iop and htquery->tid. The requested HTML page number is
provided by the htquery->page field, and the resultant data is stored
in the buffer pointed to by htquery->resbuf. If there is an HTTP query
string that is to be sent to the device, it should be sent in the buffer
pointed to by htquery->qbuf. If there is no query string, this field
should be set to NULL. The actual size of the reply received is written
into *(htquery->reslen).
RETURNS
This function returns 0 if no error occur. If an error occurs, -1
is returned and errno is set appropriately:
EFAULT Invalid user space pointer was passed
ENXIO Invalid IOP number
ENOBUFS Buffer not large enough. If this occurs, the required
buffer length is written into *(ops->reslen)
ETIMEDOUT Timeout waiting for reply message
ENOMEM Kernel memory allocation error
XII. Events
In the process of determining this. Current idea is to have use
the select() interface to allow user apps to periodically poll
the /dev/i2o/ctl device for events. When select() notifies the user
that an event is available, the user would call read() to retrieve
a list of all the events that are pending for the specific device.
=============================================================================
Revision History
=============================================================================
Rev 0.1 - 04/01/99
- Initial revision
Rev 0.2 - 04/06/99
- Changed return values to match UNIX ioctl() standard. Only return values
are 0 and -1. All errors are reported through errno.
- Added summary of proposed possible event interfaces
Rev 0.3 - 04/20/99
- Changed all ioctls() to use pointers to user data instead of actual data
- Updated error values to match the code
...@@ -58,7 +58,7 @@ To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad. ...@@ -58,7 +58,7 @@ To exit command mode, PSMOUSE_CMD_SETSTREAM (EA) is sent to the touchpad.
While in command mode, register addresses can be set by first sending a While in command mode, register addresses can be set by first sending a
specific command, either EC for v3 devices or F5 for v4 devices. Then the specific command, either EC for v3 devices or F5 for v4 devices. Then the
address is sent one nibble at a time, where each nibble is encoded as a address is sent one nibble at a time, where each nibble is encoded as a
command with optional data. This enoding differs slightly between the v3 and command with optional data. This encoding differs slightly between the v3 and
v4 protocols. v4 protocols.
Once an address has been set, the addressed register can be read by sending Once an address has been set, the addressed register can be read by sending
...@@ -139,7 +139,7 @@ ALPS Absolute Mode - Protocol Version 3 ...@@ -139,7 +139,7 @@ ALPS Absolute Mode - Protocol Version 3
--------------------------------------- ---------------------------------------
ALPS protocol version 3 has three different packet formats. The first two are ALPS protocol version 3 has three different packet formats. The first two are
associated with touchpad events, and the third is associatd with trackstick associated with touchpad events, and the third is associated with trackstick
events. events.
The first type is the touchpad position packet. The first type is the touchpad position packet.
......
...@@ -229,7 +229,7 @@ such device to feedback. ...@@ -229,7 +229,7 @@ such device to feedback.
EV_PWR: EV_PWR:
---------- ----------
EV_PWR events are a special type of event used specifically for power EV_PWR events are a special type of event used specifically for power
mangement. Its usage is not well defined. To be addressed later. management. Its usage is not well defined. To be addressed later.
Device properties: Device properties:
================= =================
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment