add idl4k kernel firmware version 1.13.0.105
This commit is contained in:
parent
5194d2792e
commit
e9070cdc77
|
@ -0,0 +1,78 @@
|
||||||
|
#
|
||||||
|
# NOTE! Don't add files that are generated in specific
|
||||||
|
# subdirectories here. Add them in the ".gitignore" file
|
||||||
|
# in that subdirectory instead.
|
||||||
|
#
|
||||||
|
# NOTE! Please use 'git ls-files -i --exclude-standard'
|
||||||
|
# command after changing this file, to see if there are
|
||||||
|
# any tracked files which get ignored after the change.
|
||||||
|
#
|
||||||
|
# Normal rules
|
||||||
|
#
|
||||||
|
.*
|
||||||
|
*.o
|
||||||
|
*.o.*
|
||||||
|
*.a
|
||||||
|
*.s
|
||||||
|
*.ko
|
||||||
|
*.so
|
||||||
|
*.so.dbg
|
||||||
|
*.mod.c
|
||||||
|
*.i
|
||||||
|
*.lst
|
||||||
|
*.symtypes
|
||||||
|
*.order
|
||||||
|
*.elf
|
||||||
|
*.bin
|
||||||
|
*.gz
|
||||||
|
*.bz2
|
||||||
|
*.lzma
|
||||||
|
*.patch
|
||||||
|
*.gcno
|
||||||
|
|
||||||
|
#
|
||||||
|
# Top-level generic files
|
||||||
|
#
|
||||||
|
tags
|
||||||
|
TAGS
|
||||||
|
vmlinux
|
||||||
|
System.map
|
||||||
|
Module.markers
|
||||||
|
Module.symvers
|
||||||
|
!.gitignore
|
||||||
|
!.mailmap
|
||||||
|
|
||||||
|
#
|
||||||
|
# Generated include files
|
||||||
|
#
|
||||||
|
include/asm
|
||||||
|
include/asm-*/asm-offsets.h
|
||||||
|
include/asm-sh/machtypes.h
|
||||||
|
include/config
|
||||||
|
include/linux/autoconf.h
|
||||||
|
include/linux/compile.h
|
||||||
|
include/linux/version.h
|
||||||
|
include/linux/utsrelease.h
|
||||||
|
include/linux/bounds.h
|
||||||
|
include/generated
|
||||||
|
|
||||||
|
# stgit generated dirs
|
||||||
|
patches-*
|
||||||
|
|
||||||
|
# quilt's files
|
||||||
|
patches
|
||||||
|
series
|
||||||
|
|
||||||
|
# cscope files
|
||||||
|
cscope.*
|
||||||
|
ncscope.*
|
||||||
|
|
||||||
|
# gnu global files
|
||||||
|
GPATH
|
||||||
|
GRTAGS
|
||||||
|
GSYMS
|
||||||
|
GTAGS
|
||||||
|
|
||||||
|
*.orig
|
||||||
|
*~
|
||||||
|
\#*#
|
|
@ -0,0 +1,107 @@
|
||||||
|
#
|
||||||
|
# This list is used by git-shortlog to fix a few botched name translations
|
||||||
|
# in the git archive, either because the author's full name was messed up
|
||||||
|
# and/or not always written the same way, making contributions from the
|
||||||
|
# same person appearing not to be so or badly displayed.
|
||||||
|
#
|
||||||
|
# repo-abbrev: /pub/scm/linux/kernel/git/
|
||||||
|
#
|
||||||
|
|
||||||
|
Aaron Durbin <adurbin@google.com>
|
||||||
|
Adam Oldham <oldhamca@gmail.com>
|
||||||
|
Adam Radford <aradford@gmail.com>
|
||||||
|
Adrian Bunk <bunk@stusta.de>
|
||||||
|
Alan Cox <alan@lxorguk.ukuu.org.uk>
|
||||||
|
Alan Cox <root@hraefn.swansea.linux.org.uk>
|
||||||
|
Aleksey Gorelov <aleksey_gorelov@phoenix.com>
|
||||||
|
Al Viro <viro@ftp.linux.org.uk>
|
||||||
|
Al Viro <viro@zenIV.linux.org.uk>
|
||||||
|
Andreas Herrmann <aherrman@de.ibm.com>
|
||||||
|
Andrew Morton <akpm@osdl.org>
|
||||||
|
Andrew Vasquez <andrew.vasquez@qlogic.com>
|
||||||
|
Andy Adamson <andros@citi.umich.edu>
|
||||||
|
Arnaud Patard <arnaud.patard@rtp-net.org>
|
||||||
|
Arnd Bergmann <arnd@arndb.de>
|
||||||
|
Axel Dyks <xl@xlsigned.net>
|
||||||
|
Ben Gardner <bgardner@wabtec.com>
|
||||||
|
Ben M Cahill <ben.m.cahill@intel.com>
|
||||||
|
Björn Steinbrink <B.Steinbrink@gmx.de>
|
||||||
|
Brian Avery <b.avery@hp.com>
|
||||||
|
Brian King <brking@us.ibm.com>
|
||||||
|
Christoph Hellwig <hch@lst.de>
|
||||||
|
Corey Minyard <minyard@acm.org>
|
||||||
|
David Brownell <david-b@pacbell.net>
|
||||||
|
David Woodhouse <dwmw2@shinybook.infradead.org>
|
||||||
|
Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
|
||||||
|
Domen Puncer <domen@coderock.org>
|
||||||
|
Douglas Gilbert <dougg@torque.net>
|
||||||
|
Ed L. Cashin <ecashin@coraid.com>
|
||||||
|
Evgeniy Polyakov <johnpol@2ka.mipt.ru>
|
||||||
|
Felipe W Damasio <felipewd@terra.com.br>
|
||||||
|
Felix Kuhling <fxkuehl@gmx.de>
|
||||||
|
Felix Moeller <felix@derklecks.de>
|
||||||
|
Filipe Lautert <filipe@icewall.org>
|
||||||
|
Franck Bui-Huu <vagabon.xyz@gmail.com>
|
||||||
|
Frank Zago <fzago@systemfabricworks.com>
|
||||||
|
Greg Kroah-Hartman <greg@echidna.(none)>
|
||||||
|
Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Greg Kroah-Hartman <greg@kroah.com>
|
||||||
|
Henk Vergonet <Henk.Vergonet@gmail.com>
|
||||||
|
Henrik Kretzschmar <henne@nachtwindheim.de>
|
||||||
|
Herbert Xu <herbert@gondor.apana.org.au>
|
||||||
|
Jacob Shin <Jacob.Shin@amd.com>
|
||||||
|
James Bottomley <jejb@mulgrave.(none)>
|
||||||
|
James Bottomley <jejb@titanic.il.steeleye.com>
|
||||||
|
James E Wilson <wilson@specifix.com>
|
||||||
|
James Ketrenos <jketreno@io.(none)>
|
||||||
|
Jean Tourrilhes <jt@hpl.hp.com>
|
||||||
|
Jeff Garzik <jgarzik@pretzel.yyz.us>
|
||||||
|
Jens Axboe <axboe@suse.de>
|
||||||
|
Jens Osterkamp <Jens.Osterkamp@de.ibm.com>
|
||||||
|
John Stultz <johnstul@us.ibm.com>
|
||||||
|
Juha Yrjola <at solidboot.com>
|
||||||
|
Juha Yrjola <juha.yrjola@nokia.com>
|
||||||
|
Juha Yrjola <juha.yrjola@solidboot.com>
|
||||||
|
Kay Sievers <kay.sievers@vrfy.org>
|
||||||
|
Kenneth W Chen <kenneth.w.chen@intel.com>
|
||||||
|
Koushik <raghavendra.koushik@neterion.com>
|
||||||
|
Leonid I Ananiev <leonid.i.ananiev@intel.com>
|
||||||
|
Linas Vepstas <linas@austin.ibm.com>
|
||||||
|
Mark Brown <broonie@sirena.org.uk>
|
||||||
|
Matthieu CASTET <castet.matthieu@free.fr>
|
||||||
|
Michael Buesch <mb@bu3sch.de>
|
||||||
|
Michael Buesch <mbuesch@freenet.de>
|
||||||
|
Michel Dänzer <michel@tungstengraphics.com>
|
||||||
|
Mitesh shah <mshah@teja.com>
|
||||||
|
Morten Welinder <terra@gnome.org>
|
||||||
|
Morten Welinder <welinder@anemone.rentec.com>
|
||||||
|
Morten Welinder <welinder@darter.rentec.com>
|
||||||
|
Morten Welinder <welinder@troll.com>
|
||||||
|
Nguyen Anh Quynh <aquynh@gmail.com>
|
||||||
|
Paolo 'Blaisorblade' Giarrusso <blaisorblade@yahoo.it>
|
||||||
|
Patrick Mochel <mochel@digitalimplant.org>
|
||||||
|
Peter A Jonsson <pj@ludd.ltu.se>
|
||||||
|
Peter Oruba <peter@oruba.de>
|
||||||
|
Peter Oruba <peter.oruba@amd.com>
|
||||||
|
Praveen BP <praveenbp@ti.com>
|
||||||
|
Rajesh Shah <rajesh.shah@intel.com>
|
||||||
|
Ralf Baechle <ralf@linux-mips.org>
|
||||||
|
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
|
||||||
|
Rémi Denis-Courmont <rdenis@simphalempin.com>
|
||||||
|
Rudolf Marek <R.Marek@sh.cvut.cz>
|
||||||
|
Rui Saraiva <rmps@joel.ist.utl.pt>
|
||||||
|
Sachin P Sant <ssant@in.ibm.com>
|
||||||
|
Sam Ravnborg <sam@mars.ravnborg.org>
|
||||||
|
Sascha Hauer <s.hauer@pengutronix.de>
|
||||||
|
S.Çağlar Onur <caglar@pardus.org.tr>
|
||||||
|
Simon Kelley <simon@thekelleys.org.uk>
|
||||||
|
Stéphane Witzmann <stephane.witzmann@ubpmes.univ-bpclermont.fr>
|
||||||
|
Stephen Hemminger <shemminger@osdl.org>
|
||||||
|
Tejun Heo <htejun@gmail.com>
|
||||||
|
Thomas Graf <tgraf@suug.ch>
|
||||||
|
Tony Luck <tony.luck@intel.com>
|
||||||
|
Tsuneo Yoshioka <Tsuneo.Yoshioka@f-secure.com>
|
||||||
|
Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de>
|
||||||
|
Uwe Kleine-König <ukl@pengutronix.de>
|
||||||
|
Uwe Kleine-König <Uwe.Kleine-Koenig@digi.com>
|
||||||
|
Valdis Kletnieks <Valdis.Kletnieks@vt.edu>
|
|
@ -0,0 +1,356 @@
|
||||||
|
|
||||||
|
NOTE! This copyright does *not* cover user programs that use kernel
|
||||||
|
services by normal system calls - this is merely considered normal use
|
||||||
|
of the kernel, and does *not* fall under the heading of "derived work".
|
||||||
|
Also note that the GPL below is copyrighted by the Free Software
|
||||||
|
Foundation, but the instance of code that it refers to (the Linux
|
||||||
|
kernel) is copyrighted by me and others who actually wrote it.
|
||||||
|
|
||||||
|
Also note that the only valid version of the GPL as far as the kernel
|
||||||
|
is concerned is _this_ particular version of the license (ie v2, not
|
||||||
|
v2.2 or v3.x or whatever), unless explicitly otherwise stated.
|
||||||
|
|
||||||
|
Linus Torvalds
|
||||||
|
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
GNU GENERAL PUBLIC LICENSE
|
||||||
|
Version 2, June 1991
|
||||||
|
|
||||||
|
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
|
||||||
|
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
||||||
|
Everyone is permitted to copy and distribute verbatim copies
|
||||||
|
of this license document, but changing it is not allowed.
|
||||||
|
|
||||||
|
Preamble
|
||||||
|
|
||||||
|
The licenses for most software are designed to take away your
|
||||||
|
freedom to share and change it. By contrast, the GNU General Public
|
||||||
|
License is intended to guarantee your freedom to share and change free
|
||||||
|
software--to make sure the software is free for all its users. This
|
||||||
|
General Public License applies to most of the Free Software
|
||||||
|
Foundation's software and to any other program whose authors commit to
|
||||||
|
using it. (Some other Free Software Foundation software is covered by
|
||||||
|
the GNU Library General Public License instead.) You can apply it to
|
||||||
|
your programs, too.
|
||||||
|
|
||||||
|
When we speak of free software, we are referring to freedom, not
|
||||||
|
price. Our General Public Licenses are designed to make sure that you
|
||||||
|
have the freedom to distribute copies of free software (and charge for
|
||||||
|
this service if you wish), that you receive source code or can get it
|
||||||
|
if you want it, that you can change the software or use pieces of it
|
||||||
|
in new free programs; and that you know you can do these things.
|
||||||
|
|
||||||
|
To protect your rights, we need to make restrictions that forbid
|
||||||
|
anyone to deny you these rights or to ask you to surrender the rights.
|
||||||
|
These restrictions translate to certain responsibilities for you if you
|
||||||
|
distribute copies of the software, or if you modify it.
|
||||||
|
|
||||||
|
For example, if you distribute copies of such a program, whether
|
||||||
|
gratis or for a fee, you must give the recipients all the rights that
|
||||||
|
you have. You must make sure that they, too, receive or can get the
|
||||||
|
source code. And you must show them these terms so they know their
|
||||||
|
rights.
|
||||||
|
|
||||||
|
We protect your rights with two steps: (1) copyright the software, and
|
||||||
|
(2) offer you this license which gives you legal permission to copy,
|
||||||
|
distribute and/or modify the software.
|
||||||
|
|
||||||
|
Also, for each author's protection and ours, we want to make certain
|
||||||
|
that everyone understands that there is no warranty for this free
|
||||||
|
software. If the software is modified by someone else and passed on, we
|
||||||
|
want its recipients to know that what they have is not the original, so
|
||||||
|
that any problems introduced by others will not reflect on the original
|
||||||
|
authors' reputations.
|
||||||
|
|
||||||
|
Finally, any free program is threatened constantly by software
|
||||||
|
patents. We wish to avoid the danger that redistributors of a free
|
||||||
|
program will individually obtain patent licenses, in effect making the
|
||||||
|
program proprietary. To prevent this, we have made it clear that any
|
||||||
|
patent must be licensed for everyone's free use or not licensed at all.
|
||||||
|
|
||||||
|
The precise terms and conditions for copying, distribution and
|
||||||
|
modification follow.
|
||||||
|
|
||||||
|
GNU GENERAL PUBLIC LICENSE
|
||||||
|
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
||||||
|
|
||||||
|
0. This License applies to any program or other work which contains
|
||||||
|
a notice placed by the copyright holder saying it may be distributed
|
||||||
|
under the terms of this General Public License. The "Program", below,
|
||||||
|
refers to any such program or work, and a "work based on the Program"
|
||||||
|
means either the Program or any derivative work under copyright law:
|
||||||
|
that is to say, a work containing the Program or a portion of it,
|
||||||
|
either verbatim or with modifications and/or translated into another
|
||||||
|
language. (Hereinafter, translation is included without limitation in
|
||||||
|
the term "modification".) Each licensee is addressed as "you".
|
||||||
|
|
||||||
|
Activities other than copying, distribution and modification are not
|
||||||
|
covered by this License; they are outside its scope. The act of
|
||||||
|
running the Program is not restricted, and the output from the Program
|
||||||
|
is covered only if its contents constitute a work based on the
|
||||||
|
Program (independent of having been made by running the Program).
|
||||||
|
Whether that is true depends on what the Program does.
|
||||||
|
|
||||||
|
1. You may copy and distribute verbatim copies of the Program's
|
||||||
|
source code as you receive it, in any medium, provided that you
|
||||||
|
conspicuously and appropriately publish on each copy an appropriate
|
||||||
|
copyright notice and disclaimer of warranty; keep intact all the
|
||||||
|
notices that refer to this License and to the absence of any warranty;
|
||||||
|
and give any other recipients of the Program a copy of this License
|
||||||
|
along with the Program.
|
||||||
|
|
||||||
|
You may charge a fee for the physical act of transferring a copy, and
|
||||||
|
you may at your option offer warranty protection in exchange for a fee.
|
||||||
|
|
||||||
|
2. You may modify your copy or copies of the Program or any portion
|
||||||
|
of it, thus forming a work based on the Program, and copy and
|
||||||
|
distribute such modifications or work under the terms of Section 1
|
||||||
|
above, provided that you also meet all of these conditions:
|
||||||
|
|
||||||
|
a) You must cause the modified files to carry prominent notices
|
||||||
|
stating that you changed the files and the date of any change.
|
||||||
|
|
||||||
|
b) You must cause any work that you distribute or publish, that in
|
||||||
|
whole or in part contains or is derived from the Program or any
|
||||||
|
part thereof, to be licensed as a whole at no charge to all third
|
||||||
|
parties under the terms of this License.
|
||||||
|
|
||||||
|
c) If the modified program normally reads commands interactively
|
||||||
|
when run, you must cause it, when started running for such
|
||||||
|
interactive use in the most ordinary way, to print or display an
|
||||||
|
announcement including an appropriate copyright notice and a
|
||||||
|
notice that there is no warranty (or else, saying that you provide
|
||||||
|
a warranty) and that users may redistribute the program under
|
||||||
|
these conditions, and telling the user how to view a copy of this
|
||||||
|
License. (Exception: if the Program itself is interactive but
|
||||||
|
does not normally print such an announcement, your work based on
|
||||||
|
the Program is not required to print an announcement.)
|
||||||
|
|
||||||
|
These requirements apply to the modified work as a whole. If
|
||||||
|
identifiable sections of that work are not derived from the Program,
|
||||||
|
and can be reasonably considered independent and separate works in
|
||||||
|
themselves, then this License, and its terms, do not apply to those
|
||||||
|
sections when you distribute them as separate works. But when you
|
||||||
|
distribute the same sections as part of a whole which is a work based
|
||||||
|
on the Program, the distribution of the whole must be on the terms of
|
||||||
|
this License, whose permissions for other licensees extend to the
|
||||||
|
entire whole, and thus to each and every part regardless of who wrote it.
|
||||||
|
|
||||||
|
Thus, it is not the intent of this section to claim rights or contest
|
||||||
|
your rights to work written entirely by you; rather, the intent is to
|
||||||
|
exercise the right to control the distribution of derivative or
|
||||||
|
collective works based on the Program.
|
||||||
|
|
||||||
|
In addition, mere aggregation of another work not based on the Program
|
||||||
|
with the Program (or with a work based on the Program) on a volume of
|
||||||
|
a storage or distribution medium does not bring the other work under
|
||||||
|
the scope of this License.
|
||||||
|
|
||||||
|
3. You may copy and distribute the Program (or a work based on it,
|
||||||
|
under Section 2) in object code or executable form under the terms of
|
||||||
|
Sections 1 and 2 above provided that you also do one of the following:
|
||||||
|
|
||||||
|
a) Accompany it with the complete corresponding machine-readable
|
||||||
|
source code, which must be distributed under the terms of Sections
|
||||||
|
1 and 2 above on a medium customarily used for software interchange; or,
|
||||||
|
|
||||||
|
b) Accompany it with a written offer, valid for at least three
|
||||||
|
years, to give any third party, for a charge no more than your
|
||||||
|
cost of physically performing source distribution, a complete
|
||||||
|
machine-readable copy of the corresponding source code, to be
|
||||||
|
distributed under the terms of Sections 1 and 2 above on a medium
|
||||||
|
customarily used for software interchange; or,
|
||||||
|
|
||||||
|
c) Accompany it with the information you received as to the offer
|
||||||
|
to distribute corresponding source code. (This alternative is
|
||||||
|
allowed only for noncommercial distribution and only if you
|
||||||
|
received the program in object code or executable form with such
|
||||||
|
an offer, in accord with Subsection b above.)
|
||||||
|
|
||||||
|
The source code for a work means the preferred form of the work for
|
||||||
|
making modifications to it. For an executable work, complete source
|
||||||
|
code means all the source code for all modules it contains, plus any
|
||||||
|
associated interface definition files, plus the scripts used to
|
||||||
|
control compilation and installation of the executable. However, as a
|
||||||
|
special exception, the source code distributed need not include
|
||||||
|
anything that is normally distributed (in either source or binary
|
||||||
|
form) with the major components (compiler, kernel, and so on) of the
|
||||||
|
operating system on which the executable runs, unless that component
|
||||||
|
itself accompanies the executable.
|
||||||
|
|
||||||
|
If distribution of executable or object code is made by offering
|
||||||
|
access to copy from a designated place, then offering equivalent
|
||||||
|
access to copy the source code from the same place counts as
|
||||||
|
distribution of the source code, even though third parties are not
|
||||||
|
compelled to copy the source along with the object code.
|
||||||
|
|
||||||
|
4. You may not copy, modify, sublicense, or distribute the Program
|
||||||
|
except as expressly provided under this License. Any attempt
|
||||||
|
otherwise to copy, modify, sublicense or distribute the Program is
|
||||||
|
void, and will automatically terminate your rights under this License.
|
||||||
|
However, parties who have received copies, or rights, from you under
|
||||||
|
this License will not have their licenses terminated so long as such
|
||||||
|
parties remain in full compliance.
|
||||||
|
|
||||||
|
5. You are not required to accept this License, since you have not
|
||||||
|
signed it. However, nothing else grants you permission to modify or
|
||||||
|
distribute the Program or its derivative works. These actions are
|
||||||
|
prohibited by law if you do not accept this License. Therefore, by
|
||||||
|
modifying or distributing the Program (or any work based on the
|
||||||
|
Program), you indicate your acceptance of this License to do so, and
|
||||||
|
all its terms and conditions for copying, distributing or modifying
|
||||||
|
the Program or works based on it.
|
||||||
|
|
||||||
|
6. Each time you redistribute the Program (or any work based on the
|
||||||
|
Program), the recipient automatically receives a license from the
|
||||||
|
original licensor to copy, distribute or modify the Program subject to
|
||||||
|
these terms and conditions. You may not impose any further
|
||||||
|
restrictions on the recipients' exercise of the rights granted herein.
|
||||||
|
You are not responsible for enforcing compliance by third parties to
|
||||||
|
this License.
|
||||||
|
|
||||||
|
7. If, as a consequence of a court judgment or allegation of patent
|
||||||
|
infringement or for any other reason (not limited to patent issues),
|
||||||
|
conditions are imposed on you (whether by court order, agreement or
|
||||||
|
otherwise) that contradict the conditions of this License, they do not
|
||||||
|
excuse you from the conditions of this License. If you cannot
|
||||||
|
distribute so as to satisfy simultaneously your obligations under this
|
||||||
|
License and any other pertinent obligations, then as a consequence you
|
||||||
|
may not distribute the Program at all. For example, if a patent
|
||||||
|
license would not permit royalty-free redistribution of the Program by
|
||||||
|
all those who receive copies directly or indirectly through you, then
|
||||||
|
the only way you could satisfy both it and this License would be to
|
||||||
|
refrain entirely from distribution of the Program.
|
||||||
|
|
||||||
|
If any portion of this section is held invalid or unenforceable under
|
||||||
|
any particular circumstance, the balance of the section is intended to
|
||||||
|
apply and the section as a whole is intended to apply in other
|
||||||
|
circumstances.
|
||||||
|
|
||||||
|
It is not the purpose of this section to induce you to infringe any
|
||||||
|
patents or other property right claims or to contest validity of any
|
||||||
|
such claims; this section has the sole purpose of protecting the
|
||||||
|
integrity of the free software distribution system, which is
|
||||||
|
implemented by public license practices. Many people have made
|
||||||
|
generous contributions to the wide range of software distributed
|
||||||
|
through that system in reliance on consistent application of that
|
||||||
|
system; it is up to the author/donor to decide if he or she is willing
|
||||||
|
to distribute software through any other system and a licensee cannot
|
||||||
|
impose that choice.
|
||||||
|
|
||||||
|
This section is intended to make thoroughly clear what is believed to
|
||||||
|
be a consequence of the rest of this License.
|
||||||
|
|
||||||
|
8. If the distribution and/or use of the Program is restricted in
|
||||||
|
certain countries either by patents or by copyrighted interfaces, the
|
||||||
|
original copyright holder who places the Program under this License
|
||||||
|
may add an explicit geographical distribution limitation excluding
|
||||||
|
those countries, so that distribution is permitted only in or among
|
||||||
|
countries not thus excluded. In such case, this License incorporates
|
||||||
|
the limitation as if written in the body of this License.
|
||||||
|
|
||||||
|
9. The Free Software Foundation may publish revised and/or new versions
|
||||||
|
of the General Public License from time to time. Such new versions will
|
||||||
|
be similar in spirit to the present version, but may differ in detail to
|
||||||
|
address new problems or concerns.
|
||||||
|
|
||||||
|
Each version is given a distinguishing version number. If the Program
|
||||||
|
specifies a version number of this License which applies to it and "any
|
||||||
|
later version", you have the option of following the terms and conditions
|
||||||
|
either of that version or of any later version published by the Free
|
||||||
|
Software Foundation. If the Program does not specify a version number of
|
||||||
|
this License, you may choose any version ever published by the Free Software
|
||||||
|
Foundation.
|
||||||
|
|
||||||
|
10. If you wish to incorporate parts of the Program into other free
|
||||||
|
programs whose distribution conditions are different, write to the author
|
||||||
|
to ask for permission. For software which is copyrighted by the Free
|
||||||
|
Software Foundation, write to the Free Software Foundation; we sometimes
|
||||||
|
make exceptions for this. Our decision will be guided by the two goals
|
||||||
|
of preserving the free status of all derivatives of our free software and
|
||||||
|
of promoting the sharing and reuse of software generally.
|
||||||
|
|
||||||
|
NO WARRANTY
|
||||||
|
|
||||||
|
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
||||||
|
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
||||||
|
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
||||||
|
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
||||||
|
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||||||
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||||||
|
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
||||||
|
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
||||||
|
REPAIR OR CORRECTION.
|
||||||
|
|
||||||
|
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||||
|
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
||||||
|
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
||||||
|
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
||||||
|
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
||||||
|
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
||||||
|
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
||||||
|
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
||||||
|
POSSIBILITY OF SUCH DAMAGES.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
|
How to Apply These Terms to Your New Programs
|
||||||
|
|
||||||
|
If you develop a new program, and you want it to be of the greatest
|
||||||
|
possible use to the public, the best way to achieve this is to make it
|
||||||
|
free software which everyone can redistribute and change under these terms.
|
||||||
|
|
||||||
|
To do so, attach the following notices to the program. It is safest
|
||||||
|
to attach them to the start of each source file to most effectively
|
||||||
|
convey the exclusion of warranty; and each file should have at least
|
||||||
|
the "copyright" line and a pointer to where the full notice is found.
|
||||||
|
|
||||||
|
<one line to give the program's name and a brief idea of what it does.>
|
||||||
|
Copyright (C) <year> <name of author>
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
This program is distributed in the hope that it will be useful,
|
||||||
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
GNU General Public License for more details.
|
||||||
|
|
||||||
|
You should have received a copy of the GNU General Public License
|
||||||
|
along with this program; if not, write to the Free Software
|
||||||
|
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
||||||
|
|
||||||
|
|
||||||
|
Also add information on how to contact you by electronic and paper mail.
|
||||||
|
|
||||||
|
If the program is interactive, make it output a short notice like this
|
||||||
|
when it starts in an interactive mode:
|
||||||
|
|
||||||
|
Gnomovision version 69, Copyright (C) year name of author
|
||||||
|
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
||||||
|
This is free software, and you are welcome to redistribute it
|
||||||
|
under certain conditions; type `show c' for details.
|
||||||
|
|
||||||
|
The hypothetical commands `show w' and `show c' should show the appropriate
|
||||||
|
parts of the General Public License. Of course, the commands you use may
|
||||||
|
be called something other than `show w' and `show c'; they could even be
|
||||||
|
mouse-clicks or menu items--whatever suits your program.
|
||||||
|
|
||||||
|
You should also get your employer (if you work as a programmer) or your
|
||||||
|
school, if any, to sign a "copyright disclaimer" for the program, if
|
||||||
|
necessary. Here is a sample; alter the names:
|
||||||
|
|
||||||
|
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
||||||
|
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
||||||
|
|
||||||
|
<signature of Ty Coon>, 1 April 1989
|
||||||
|
Ty Coon, President of Vice
|
||||||
|
|
||||||
|
This General Public License does not permit incorporating your program into
|
||||||
|
proprietary programs. If your program is a subroutine library, you may
|
||||||
|
consider it more useful to permit linking proprietary applications with the
|
||||||
|
library. If this is what you want to do, use the GNU Library General
|
||||||
|
Public License instead of this License.
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,354 @@
|
||||||
|
|
||||||
|
This is a brief list of all the files in ./linux/Documentation and what
|
||||||
|
they contain. If you add a documentation file, please list it here in
|
||||||
|
alphabetical order as well, or risk being hunted down like a rabid dog.
|
||||||
|
Please try and keep the descriptions small enough to fit on one line.
|
||||||
|
Thanks -- Paul G.
|
||||||
|
|
||||||
|
Following translations are available on the WWW:
|
||||||
|
|
||||||
|
- Japanese, maintained by the JF Project (JF@linux.or.jp), at
|
||||||
|
http://www.linux.or.jp/JF/
|
||||||
|
|
||||||
|
00-INDEX
|
||||||
|
- this file.
|
||||||
|
ABI/
|
||||||
|
- info on kernel <-> userspace ABI and relative interface stability.
|
||||||
|
|
||||||
|
BUG-HUNTING
|
||||||
|
- brute force method of doing binary search of patches to find bug.
|
||||||
|
Changes
|
||||||
|
- list of changes that break older software packages.
|
||||||
|
CodingStyle
|
||||||
|
- how the boss likes the C code in the kernel to look.
|
||||||
|
development-process/
|
||||||
|
- An extended tutorial on how to work with the kernel development
|
||||||
|
process.
|
||||||
|
DMA-API.txt
|
||||||
|
- DMA API, pci_ API & extensions for non-consistent memory machines.
|
||||||
|
DMA-ISA-LPC.txt
|
||||||
|
- How to do DMA with ISA (and LPC) devices.
|
||||||
|
DocBook/
|
||||||
|
- directory with DocBook templates etc. for kernel documentation.
|
||||||
|
HOWTO
|
||||||
|
- the process and procedures of how to do Linux kernel development.
|
||||||
|
IO-mapping.txt
|
||||||
|
- how to access I/O mapped memory from within device drivers.
|
||||||
|
IPMI.txt
|
||||||
|
- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
|
||||||
|
IRQ-affinity.txt
|
||||||
|
- how to select which CPU(s) handle which interrupt events on SMP.
|
||||||
|
IRQ.txt
|
||||||
|
- description of what an IRQ is.
|
||||||
|
ManagementStyle
|
||||||
|
- how to (attempt to) manage kernel hackers.
|
||||||
|
RCU/
|
||||||
|
- directory with info on RCU (read-copy update).
|
||||||
|
SAK.txt
|
||||||
|
- info on Secure Attention Keys.
|
||||||
|
SM501.txt
|
||||||
|
- Silicon Motion SM501 multimedia companion chip
|
||||||
|
SecurityBugs
|
||||||
|
- procedure for reporting security bugs found in the kernel.
|
||||||
|
SubmitChecklist
|
||||||
|
- Linux kernel patch submission checklist.
|
||||||
|
SubmittingDrivers
|
||||||
|
- procedure to get a new driver source included into the kernel tree.
|
||||||
|
SubmittingPatches
|
||||||
|
- procedure to get a source patch included into the kernel tree.
|
||||||
|
VGA-softcursor.txt
|
||||||
|
- how to change your VGA cursor from a blinking underscore.
|
||||||
|
accounting/
|
||||||
|
- documentation on accounting and taskstats.
|
||||||
|
acpi/
|
||||||
|
- info on ACPI-specific hooks in the kernel.
|
||||||
|
aoe/
|
||||||
|
- description of AoE (ATA over Ethernet) along with config examples.
|
||||||
|
applying-patches.txt
|
||||||
|
- description of various trees and how to apply their patches.
|
||||||
|
arm/
|
||||||
|
- directory with info about Linux on the ARM architecture.
|
||||||
|
atomic_ops.txt
|
||||||
|
- semantics and behavior of atomic and bitmask operations.
|
||||||
|
auxdisplay/
|
||||||
|
- misc. LCD driver documentation (cfag12864b, ks0108).
|
||||||
|
basic_profiling.txt
|
||||||
|
- basic instructions for those who wants to profile Linux kernel.
|
||||||
|
binfmt_misc.txt
|
||||||
|
- info on the kernel support for extra binary formats.
|
||||||
|
blackfin/
|
||||||
|
- directory with documentation for the Blackfin arch.
|
||||||
|
block/
|
||||||
|
- info on the Block I/O (BIO) layer.
|
||||||
|
blockdev/
|
||||||
|
- info on block devices & drivers
|
||||||
|
btmrvl.txt
|
||||||
|
- info on Marvell Bluetooth driver usage.
|
||||||
|
cachetlb.txt
|
||||||
|
- describes the cache/TLB flushing interfaces Linux uses.
|
||||||
|
cdrom/
|
||||||
|
- directory with information on the CD-ROM drivers that Linux has.
|
||||||
|
cgroups/
|
||||||
|
- cgroups features, including cpusets and memory controller.
|
||||||
|
connector/
|
||||||
|
- docs on the netlink based userspace<->kernel space communication mod.
|
||||||
|
console/
|
||||||
|
- documentation on Linux console drivers.
|
||||||
|
cpu-freq/
|
||||||
|
- info on CPU frequency and voltage scaling.
|
||||||
|
cpu-hotplug.txt
|
||||||
|
- document describing CPU hotplug support in the Linux kernel.
|
||||||
|
cpu-load.txt
|
||||||
|
- document describing how CPU load statistics are collected.
|
||||||
|
cpuidle/
|
||||||
|
- info on CPU_IDLE, CPU idle state management subsystem.
|
||||||
|
cputopology.txt
|
||||||
|
- documentation on how CPU topology info is exported via sysfs.
|
||||||
|
cris/
|
||||||
|
- directory with info about Linux on CRIS architecture.
|
||||||
|
crypto/
|
||||||
|
- directory with info on the Crypto API.
|
||||||
|
dcdbas.txt
|
||||||
|
- information on the Dell Systems Management Base Driver.
|
||||||
|
debugging-modules.txt
|
||||||
|
- some notes on debugging modules after Linux 2.6.3.
|
||||||
|
dell_rbu.txt
|
||||||
|
- document demonstrating the use of the Dell Remote BIOS Update driver.
|
||||||
|
device-mapper/
|
||||||
|
- directory with info on Device Mapper.
|
||||||
|
devices.txt
|
||||||
|
- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
|
||||||
|
dontdiff
|
||||||
|
- file containing a list of files that should never be diff'ed.
|
||||||
|
driver-model/
|
||||||
|
- directory with info about Linux driver model.
|
||||||
|
dvb/
|
||||||
|
- info on Linux Digital Video Broadcast (DVB) subsystem.
|
||||||
|
early-userspace/
|
||||||
|
- info about initramfs, klibc, and userspace early during boot.
|
||||||
|
edac.txt
|
||||||
|
- information on EDAC - Error Detection And Correction
|
||||||
|
eisa.txt
|
||||||
|
- info on EISA bus support.
|
||||||
|
exception.txt
|
||||||
|
- how Linux v2.2 handles exceptions without verify_area etc.
|
||||||
|
fault-injection/
|
||||||
|
- dir with docs about the fault injection capabilities infrastructure.
|
||||||
|
fb/
|
||||||
|
- directory with info on the frame buffer graphics abstraction layer.
|
||||||
|
feature-removal-schedule.txt
|
||||||
|
- list of files and features that are going to be removed.
|
||||||
|
filesystems/
|
||||||
|
- info on the vfs and the various filesystems that Linux supports.
|
||||||
|
firmware_class/
|
||||||
|
- request_firmware() hotplug interface info.
|
||||||
|
frv/
|
||||||
|
- Fujitsu FR-V Linux documentation.
|
||||||
|
gpio.txt
|
||||||
|
- overview of GPIO (General Purpose Input/Output) access conventions.
|
||||||
|
highuid.txt
|
||||||
|
- notes on the change from 16 bit to 32 bit user/group IDs.
|
||||||
|
timers/
|
||||||
|
- info on the timer related topics
|
||||||
|
hw_random.txt
|
||||||
|
- info on Linux support for random number generator in i8xx chipsets.
|
||||||
|
hwmon/
|
||||||
|
- directory with docs on various hardware monitoring drivers.
|
||||||
|
i2c/
|
||||||
|
- directory with info about the I2C bus/protocol (2 wire, kHz speed).
|
||||||
|
i2o/
|
||||||
|
- directory with info about the Linux I2O subsystem.
|
||||||
|
x86/i386/
|
||||||
|
- directory with info about Linux on Intel 32 bit architecture.
|
||||||
|
ia64/
|
||||||
|
- directory with info about Linux on Intel 64 bit architecture.
|
||||||
|
infiniband/
|
||||||
|
- directory with documents concerning Linux InfiniBand support.
|
||||||
|
initrd.txt
|
||||||
|
- how to use the RAM disk as an initial/temporary root filesystem.
|
||||||
|
input/
|
||||||
|
- info on Linux input device support.
|
||||||
|
io_ordering.txt
|
||||||
|
- info on ordering I/O writes to memory-mapped addresses.
|
||||||
|
ioctl/
|
||||||
|
- directory with documents describing various IOCTL calls.
|
||||||
|
iostats.txt
|
||||||
|
- info on I/O statistics Linux kernel provides.
|
||||||
|
irqflags-tracing.txt
|
||||||
|
- how to use the irq-flags tracing feature.
|
||||||
|
isapnp.txt
|
||||||
|
- info on Linux ISA Plug & Play support.
|
||||||
|
isdn/
|
||||||
|
- directory with info on the Linux ISDN support, and supported cards.
|
||||||
|
java.txt
|
||||||
|
- info on the in-kernel binary support for Java(tm).
|
||||||
|
kbuild/
|
||||||
|
- directory with info about the kernel build process.
|
||||||
|
kdump/
|
||||||
|
- directory with mini HowTo on getting the crash dump code to work.
|
||||||
|
kernel-doc-nano-HOWTO.txt
|
||||||
|
- mini HowTo on generation and location of kernel documentation files.
|
||||||
|
kernel-docs.txt
|
||||||
|
- listing of various WWW + books that document kernel internals.
|
||||||
|
kernel-parameters.txt
|
||||||
|
- summary listing of command line / boot prompt args for the kernel.
|
||||||
|
keys-request-key.txt
|
||||||
|
- description of the kernel key request service.
|
||||||
|
keys.txt
|
||||||
|
- description of the kernel key retention service.
|
||||||
|
kobject.txt
|
||||||
|
- info of the kobject infrastructure of the Linux kernel.
|
||||||
|
kprobes.txt
|
||||||
|
- documents the kernel probes debugging feature.
|
||||||
|
kref.txt
|
||||||
|
- docs on adding reference counters (krefs) to kernel objects.
|
||||||
|
laptops/
|
||||||
|
- directory with laptop related info and laptop driver documentation.
|
||||||
|
ldm.txt
|
||||||
|
- a brief description of LDM (Windows Dynamic Disks).
|
||||||
|
leds-class.txt
|
||||||
|
- documents LED handling under Linux.
|
||||||
|
local_ops.txt
|
||||||
|
- semantics and behavior of local atomic operations.
|
||||||
|
lockdep-design.txt
|
||||||
|
- documentation on the runtime locking correctness validator.
|
||||||
|
logo.gif
|
||||||
|
- full colour GIF image of Linux logo (penguin - Tux).
|
||||||
|
logo.txt
|
||||||
|
- info on creator of above logo & site to get additional images from.
|
||||||
|
m68k/
|
||||||
|
- directory with info about Linux on Motorola 68k architecture.
|
||||||
|
magic-number.txt
|
||||||
|
- list of magic numbers used to mark/protect kernel data structures.
|
||||||
|
mca.txt
|
||||||
|
- info on supporting Micro Channel Architecture (e.g. PS/2) systems.
|
||||||
|
md.txt
|
||||||
|
- info on boot arguments for the multiple devices driver.
|
||||||
|
memory-barriers.txt
|
||||||
|
- info on Linux kernel memory barriers.
|
||||||
|
memory-hotplug.txt
|
||||||
|
- Hotpluggable memory support, how to use and current status.
|
||||||
|
memory.txt
|
||||||
|
- info on typical Linux memory problems.
|
||||||
|
mips/
|
||||||
|
- directory with info about Linux on MIPS architecture.
|
||||||
|
mono.txt
|
||||||
|
- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
|
||||||
|
mutex-design.txt
|
||||||
|
- info on the generic mutex subsystem.
|
||||||
|
namespaces/
|
||||||
|
- directory with various information about namespaces
|
||||||
|
netlabel/
|
||||||
|
- directory with information on the NetLabel subsystem.
|
||||||
|
networking/
|
||||||
|
- directory with info on various aspects of networking with Linux.
|
||||||
|
nmi_watchdog.txt
|
||||||
|
- info on NMI watchdog for SMP systems.
|
||||||
|
nommu-mmap.txt
|
||||||
|
- documentation about no-mmu memory mapping support.
|
||||||
|
numastat.txt
|
||||||
|
- info on how to read Numa policy hit/miss statistics in sysfs.
|
||||||
|
oops-tracing.txt
|
||||||
|
- how to decode those nasty internal kernel error dump messages.
|
||||||
|
parisc/
|
||||||
|
- directory with info on using Linux on PA-RISC architecture.
|
||||||
|
parport.txt
|
||||||
|
- how to use the parallel-port driver.
|
||||||
|
parport-lowlevel.txt
|
||||||
|
- description and usage of the low level parallel port functions.
|
||||||
|
pcmcia/
|
||||||
|
- info on the Linux PCMCIA driver.
|
||||||
|
pi-futex.txt
|
||||||
|
- documentation on lightweight PI-futexes.
|
||||||
|
pnp.txt
|
||||||
|
- Linux Plug and Play documentation.
|
||||||
|
power/
|
||||||
|
- directory with info on Linux PCI power management.
|
||||||
|
powerpc/
|
||||||
|
- directory with info on using Linux with the PowerPC.
|
||||||
|
preempt-locking.txt
|
||||||
|
- info on locking under a preemptive kernel.
|
||||||
|
printk-formats.txt
|
||||||
|
- how to get printk format specifiers right
|
||||||
|
prio_tree.txt
|
||||||
|
- info on radix-priority-search-tree use for indexing vmas.
|
||||||
|
rbtree.txt
|
||||||
|
- info on what red-black trees are and what they are for.
|
||||||
|
robust-futex-ABI.txt
|
||||||
|
- documentation of the robust futex ABI.
|
||||||
|
robust-futexes.txt
|
||||||
|
- a description of what robust futexes are.
|
||||||
|
rt-mutex-design.txt
|
||||||
|
- description of the RealTime mutex implementation design.
|
||||||
|
rt-mutex.txt
|
||||||
|
- desc. of RT-mutex subsystem with PI (Priority Inheritance) support.
|
||||||
|
rtc.txt
|
||||||
|
- notes on how to use the Real Time Clock (aka CMOS clock) driver.
|
||||||
|
s390/
|
||||||
|
- directory with info on using Linux on the IBM S390.
|
||||||
|
scheduler/
|
||||||
|
- directory with info on the scheduler.
|
||||||
|
scsi/
|
||||||
|
- directory with info on Linux scsi support.
|
||||||
|
serial/
|
||||||
|
- directory with info on the low level serial API.
|
||||||
|
serial-console.txt
|
||||||
|
- how to set up Linux with a serial line console as the default.
|
||||||
|
sgi-ioc4.txt
|
||||||
|
- description of the SGI IOC4 PCI (multi function) device.
|
||||||
|
sgi-visws.txt
|
||||||
|
- short blurb on the SGI Visual Workstations.
|
||||||
|
sh/
|
||||||
|
- directory with info on porting Linux to a new architecture.
|
||||||
|
sound/
|
||||||
|
- directory with info on sound card support.
|
||||||
|
sparc/
|
||||||
|
- directory with info on using Linux on Sparc architecture.
|
||||||
|
sparse.txt
|
||||||
|
- info on how to obtain and use the sparse tool for typechecking.
|
||||||
|
spi/
|
||||||
|
- overview of Linux kernel Serial Peripheral Interface (SPI) support.
|
||||||
|
spinlocks.txt
|
||||||
|
- info on using spinlocks to provide exclusive access in kernel.
|
||||||
|
stable_api_nonsense.txt
|
||||||
|
- info on why the kernel does not have a stable in-kernel api or abi.
|
||||||
|
stable_kernel_rules.txt
|
||||||
|
- rules and procedures for the -stable kernel releases.
|
||||||
|
svga.txt
|
||||||
|
- short guide on selecting video modes at boot via VGA BIOS.
|
||||||
|
sysfs-rules.txt
|
||||||
|
- How not to use sysfs.
|
||||||
|
sysctl/
|
||||||
|
- directory with info on the /proc/sys/* files.
|
||||||
|
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
|
||||||
|
- info on the Unicode character/font mapping used in Linux.
|
||||||
|
unshare.txt
|
||||||
|
- description of the Linux unshare system call.
|
||||||
|
usb/
|
||||||
|
- directory with info regarding the Universal Serial Bus.
|
||||||
|
video-output.txt
|
||||||
|
- sysfs class driver interface to enable/disable a video output device.
|
||||||
|
video4linux/
|
||||||
|
- directory with info regarding video/TV/radio cards and linux.
|
||||||
|
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/
|
||||||
|
- how to auto-reboot Linux if it has "fallen and can't get up". ;-)
|
||||||
|
x86/x86_64/
|
||||||
|
- directory with info on Linux support for AMD x86-64 (Hammer) machines.
|
||||||
|
zorro.txt
|
||||||
|
- info on writing drivers for Zorro bus devices found on Amigas.
|
|
@ -0,0 +1,77 @@
|
||||||
|
This directory attempts to document the ABI between the Linux kernel and
|
||||||
|
userspace, and the relative stability of these interfaces. Due to the
|
||||||
|
everchanging nature of Linux, and the differing maturity levels, these
|
||||||
|
interfaces should be used by userspace programs in different ways.
|
||||||
|
|
||||||
|
We have four different levels of ABI stability, as shown by the four
|
||||||
|
different subdirectories in this location. Interfaces may change levels
|
||||||
|
of stability according to the rules described below.
|
||||||
|
|
||||||
|
The different levels of stability are:
|
||||||
|
|
||||||
|
stable/
|
||||||
|
This directory documents the interfaces that the developer has
|
||||||
|
defined to be stable. Userspace programs are free to use these
|
||||||
|
interfaces with no restrictions, and backward compatibility for
|
||||||
|
them will be guaranteed for at least 2 years. Most interfaces
|
||||||
|
(like syscalls) are expected to never change and always be
|
||||||
|
available.
|
||||||
|
|
||||||
|
testing/
|
||||||
|
This directory documents interfaces that are felt to be stable,
|
||||||
|
as the main development of this interface has been completed.
|
||||||
|
The interface can be changed to add new features, but the
|
||||||
|
current interface will not break by doing this, unless grave
|
||||||
|
errors or security problems are found in them. Userspace
|
||||||
|
programs can start to rely on these interfaces, but they must be
|
||||||
|
aware of changes that can occur before these interfaces move to
|
||||||
|
be marked stable. Programs that use these interfaces are
|
||||||
|
strongly encouraged to add their name to the description of
|
||||||
|
these interfaces, so that the kernel developers can easily
|
||||||
|
notify them if any changes occur (see the description of the
|
||||||
|
layout of the files below for details on how to do this.)
|
||||||
|
|
||||||
|
obsolete/
|
||||||
|
This directory documents interfaces that are still remaining in
|
||||||
|
the kernel, but are marked to be removed at some later point in
|
||||||
|
time. The description of the interface will document the reason
|
||||||
|
why it is obsolete and when it can be expected to be removed.
|
||||||
|
The file Documentation/feature-removal-schedule.txt may describe
|
||||||
|
some of these interfaces, giving a schedule for when they will
|
||||||
|
be removed.
|
||||||
|
|
||||||
|
removed/
|
||||||
|
This directory contains a list of the old interfaces that have
|
||||||
|
been removed from the kernel.
|
||||||
|
|
||||||
|
Every file in these directories will contain the following information:
|
||||||
|
|
||||||
|
What: Short description of the interface
|
||||||
|
Date: Date created
|
||||||
|
KernelVersion: Kernel version this feature first showed up in.
|
||||||
|
Contact: Primary contact for this interface (may be a mailing list)
|
||||||
|
Description: Long description of the interface and how to use it.
|
||||||
|
Users: All users of this interface who wish to be notified when
|
||||||
|
it changes. This is very important for interfaces in
|
||||||
|
the "testing" stage, so that kernel developers can work
|
||||||
|
with userspace developers to ensure that things do not
|
||||||
|
break in ways that are unacceptable. It is also
|
||||||
|
important to get feedback for these interfaces to make
|
||||||
|
sure they are working in a proper way and do not need to
|
||||||
|
be changed further.
|
||||||
|
|
||||||
|
|
||||||
|
How things move between levels:
|
||||||
|
|
||||||
|
Interfaces in stable may move to obsolete, as long as the proper
|
||||||
|
notification is given.
|
||||||
|
|
||||||
|
Interfaces may be removed from obsolete and the kernel as long as the
|
||||||
|
documented amount of time has gone by.
|
||||||
|
|
||||||
|
Interfaces in the testing state can move to the stable state when the
|
||||||
|
developers feel they are finished. They cannot be removed from the
|
||||||
|
kernel tree without going through the obsolete state first.
|
||||||
|
|
||||||
|
It's up to the developer to place their interfaces in the category they
|
||||||
|
wish for it to start out in.
|
|
@ -0,0 +1,9 @@
|
||||||
|
What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire)
|
||||||
|
Contact: linux1394-devel@lists.sourceforge.net
|
||||||
|
Description:
|
||||||
|
New application development should use raw1394 + userspace libraries
|
||||||
|
instead, notably libiec61883 which is functionally equivalent.
|
||||||
|
|
||||||
|
Users:
|
||||||
|
ffmpeg/libavformat (used by a variety of media players)
|
||||||
|
dvgrab v1.x (replaced by dvgrab2 on top of raw1394 and resp. libraries)
|
|
@ -0,0 +1,11 @@
|
||||||
|
What: /sys/o2cb symlink
|
||||||
|
Date: Dec 2005
|
||||||
|
KernelVersion: 2.6.16
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description: This is a symlink: /sys/o2cb to /sys/fs/o2cb. The symlink will
|
||||||
|
be removed when new versions of ocfs2-tools which know to look
|
||||||
|
in /sys/fs/o2cb are sufficiently prevalent. Don't code new
|
||||||
|
software to look here, it should try /sys/fs/o2cb instead.
|
||||||
|
See Documentation/ABI/stable/o2cb for more information on usage.
|
||||||
|
Users: ocfs2-tools. It's sufficient to mail proposed changes to
|
||||||
|
ocfs2-devel@oss.oracle.com.
|
|
@ -0,0 +1,12 @@
|
||||||
|
What: devfs
|
||||||
|
Date: July 2005 (scheduled), finally removed in kernel v2.6.18
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
devfs has been unmaintained for a number of years, has unfixable
|
||||||
|
races, contains a naming policy within the kernel that is
|
||||||
|
against the LSB, and can be replaced by using udev.
|
||||||
|
The files fs/devfs/*, include/linux/devfs_fs*.h were removed,
|
||||||
|
along with the assorted devfs function calls throughout the
|
||||||
|
kernel tree.
|
||||||
|
|
||||||
|
Users:
|
|
@ -0,0 +1,16 @@
|
||||||
|
What: legacy isochronous ABI of raw1394 (1st generation iso ABI)
|
||||||
|
Date: June 2007 (scheduled), removed in kernel v2.6.23
|
||||||
|
Contact: linux1394-devel@lists.sourceforge.net
|
||||||
|
Description:
|
||||||
|
The two request types RAW1394_REQ_ISO_SEND, RAW1394_REQ_ISO_LISTEN have
|
||||||
|
been deprecated for quite some time. They are very inefficient as they
|
||||||
|
come with high interrupt load and several layers of callbacks for each
|
||||||
|
packet. Because of these deficiencies, the video1394 and dv1394 drivers
|
||||||
|
and the 3rd-generation isochronous ABI in raw1394 (rawiso) were created.
|
||||||
|
|
||||||
|
Users:
|
||||||
|
libraw1394 users via the long deprecated API raw1394_iso_write,
|
||||||
|
raw1394_start_iso_write, raw1394_start_iso_rcv, raw1394_stop_iso_rcv
|
||||||
|
|
||||||
|
libdc1394, which optionally uses these old libraw1394 calls
|
||||||
|
alternatively to the more efficient video1394 ABI
|
|
@ -0,0 +1,10 @@
|
||||||
|
What: /sys/fs/o2cb/ (was /sys/o2cb)
|
||||||
|
Date: Dec 2005
|
||||||
|
KernelVersion: 2.6.16
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description: Ocfs2-tools looks at 'interface-revision' for versioning
|
||||||
|
information. Each logmask/ file controls a set of debug prints
|
||||||
|
and can be written into with the strings "allow", "deny", or
|
||||||
|
"off". Reading the file returns the current state.
|
||||||
|
Users: ocfs2-tools. It's sufficient to mail proposed changes to
|
||||||
|
ocfs2-devel@oss.oracle.com.
|
|
@ -0,0 +1,10 @@
|
||||||
|
What: The kernel syscall interface
|
||||||
|
Description:
|
||||||
|
This interface matches much of the POSIX interface and is based
|
||||||
|
on it and other Unix based interfaces. It will only be added to
|
||||||
|
over time, and not have things removed from it.
|
||||||
|
|
||||||
|
Note that this interface is different for every architecture
|
||||||
|
that Linux supports. Please see the architecture-specific
|
||||||
|
documentation for details on the syscall numbers that are to be
|
||||||
|
mapped to each syscall.
|
|
@ -0,0 +1,36 @@
|
||||||
|
What: /sys/class/backlight/<backlight>/bl_power
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Control BACKLIGHT power, values are FB_BLANK_* from fb.h
|
||||||
|
- FB_BLANK_UNBLANK (0) : power on.
|
||||||
|
- FB_BLANK_POWERDOWN (4) : power off
|
||||||
|
Users: HAL
|
||||||
|
|
||||||
|
What: /sys/class/backlight/<backlight>/brightness
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Control the brightness for this <backlight>. Values
|
||||||
|
are between 0 and max_brightness. This file will also
|
||||||
|
show the brightness level stored in the driver, which
|
||||||
|
may not be the actual brightness (see actual_brightness).
|
||||||
|
Users: HAL
|
||||||
|
|
||||||
|
What: /sys/class/backlight/<backlight>/actual_brightness
|
||||||
|
Date: March 2006
|
||||||
|
KernelVersion: 2.6.17
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Show the actual brightness by querying the hardware.
|
||||||
|
Users: HAL
|
||||||
|
|
||||||
|
What: /sys/class/backlight/<backlight>/max_brightness
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Maximum brightness for <backlight>.
|
||||||
|
Users: HAL
|
|
@ -0,0 +1,212 @@
|
||||||
|
What: /sys/class/ubi/
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
The ubi/ class sub-directory belongs to the UBI subsystem and
|
||||||
|
provides general UBI information, per-UBI device information
|
||||||
|
and per-UBI volume information.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/version
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
This file contains version of the latest supported UBI on-media
|
||||||
|
format. Currently it is 1, and there is no plan to change this.
|
||||||
|
However, if in the future UBI needs on-flash format changes
|
||||||
|
which cannot be done in a compatible manner, a new format
|
||||||
|
version will be added. So this is a mechanism for possible
|
||||||
|
future backward-compatible (but forward-incompatible)
|
||||||
|
improvements.
|
||||||
|
|
||||||
|
What: /sys/class/ubiX/
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
The /sys/class/ubi0, /sys/class/ubi1, etc directories describe
|
||||||
|
UBI devices (UBI device 0, 1, etc). They contain general UBI
|
||||||
|
device information and per UBI volume information (each UBI
|
||||||
|
device may have many UBI volumes)
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/avail_eraseblocks
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Amount of available logical eraseblock. For example, one may
|
||||||
|
create a new UBI volume which has this amount of logical
|
||||||
|
eraseblocks.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/bad_peb_count
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Count of bad physical eraseblocks on the underlying MTD device.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/bgt_enabled
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Contains ASCII "0\n" if the UBI background thread is disabled,
|
||||||
|
and ASCII "1\n" if it is enabled.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/dev
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Major and minor numbers of the character device corresponding
|
||||||
|
to this UBI device (in <major>:<minor> format).
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/eraseblock_size
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Maximum logical eraseblock size this UBI device may provide. UBI
|
||||||
|
volumes may have smaller logical eraseblock size because of their
|
||||||
|
alignment.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/max_ec
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Maximum physical eraseblock erase counter value.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/max_vol_count
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Maximum number of volumes which this UBI device may have.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/min_io_size
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Minimum input/output unit size. All the I/O may only be done
|
||||||
|
in fractions of the contained number.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/mtd_num
|
||||||
|
Date: January 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Number of the underlying MTD device.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/reserved_for_bad
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Number of physical eraseblocks reserved for bad block handling.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/total_eraseblocks
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Total number of good (not marked as bad) physical eraseblocks on
|
||||||
|
the underlying MTD device.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/volumes_count
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Count of volumes on this UBI device.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
The /sys/class/ubi/ubiX/ubiX_0/, /sys/class/ubi/ubiX/ubiX_1/,
|
||||||
|
etc directories describe UBI volumes on UBI device X (volumes
|
||||||
|
0, 1, etc).
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/alignment
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Volume alignment - the value the logical eraseblock size of
|
||||||
|
this volume has to be aligned on. For example, 2048 means that
|
||||||
|
logical eraseblock size is multiple of 2048. In other words,
|
||||||
|
volume logical eraseblock size is UBI device logical eraseblock
|
||||||
|
size aligned to the alignment value.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/corrupted
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Contains ASCII "0\n" if the UBI volume is OK, and ASCII "1\n"
|
||||||
|
if it is corrupted (e.g., due to an interrupted volume update).
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/data_bytes
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
The amount of data this volume contains. This value makes sense
|
||||||
|
only for static volumes, and for dynamic volume it equivalent
|
||||||
|
to the total volume size in bytes.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/dev
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Major and minor numbers of the character device corresponding
|
||||||
|
to this UBI volume (in <major>:<minor> format).
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/name
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Volume name.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/reserved_ebs
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Count of physical eraseblock reserved for this volume.
|
||||||
|
Equivalent to the volume size in logical eraseblocks.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/type
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Volume type. Contains ASCII "dynamic\n" for dynamic volumes and
|
||||||
|
"static\n" for static volumes.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/upd_marker
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Contains ASCII "0\n" if the update marker is not set for this
|
||||||
|
volume, and "1\n" if it is set. The update marker is set when
|
||||||
|
volume update starts, and cleaned when it ends. So the presence
|
||||||
|
of the update marker indicates that the volume is being updated
|
||||||
|
at the moment of the update was interrupted. The later may be
|
||||||
|
checked using the "corrupted" sysfs file.
|
||||||
|
|
||||||
|
What: /sys/class/ubi/ubiX/ubiX_Y/usable_eb_size
|
||||||
|
Date: July 2006
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Artem Bityutskiy <dedekind@infradead.org>
|
||||||
|
Description:
|
||||||
|
Logical eraseblock size of this volume. Equivalent to logical
|
||||||
|
eraseblock size of the device aligned on the volume alignment
|
||||||
|
value.
|
|
@ -0,0 +1,62 @@
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/interface_capabilities
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/device_capabilities
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
These files show the various USB TMC capabilities as described
|
||||||
|
by the device itself. The full description of the bitfields
|
||||||
|
can be found in the USB TMC documents from the USB-IF entitled
|
||||||
|
"Universal Serial Bus Test and Measurement Class Specification
|
||||||
|
(USBTMC) Revision 1.0" section 4.2.1.8.
|
||||||
|
|
||||||
|
The files are read only.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_interface_capabilities
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_device_capabilities
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
These files show the various USB TMC capabilities as described
|
||||||
|
by the device itself. The full description of the bitfields
|
||||||
|
can be found in the USB TMC documents from the USB-IF entitled
|
||||||
|
"Universal Serial Bus Test and Measurement Class, Subclass
|
||||||
|
USB488 Specification (USBTMC-USB488) Revision 1.0" section
|
||||||
|
4.2.2.
|
||||||
|
|
||||||
|
The files are read only.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/TermChar
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
This file is the TermChar value to be sent to the USB TMC
|
||||||
|
device as described by the document, "Universal Serial Bus Test
|
||||||
|
and Measurement Class Specification
|
||||||
|
(USBTMC) Revision 1.0" as published by the USB-IF.
|
||||||
|
|
||||||
|
Note that the TermCharEnabled file determines if this value is
|
||||||
|
sent to the device or not.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/TermCharEnabled
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
This file determines if the TermChar is to be sent to the
|
||||||
|
device on every transaction or not. For more details about
|
||||||
|
this, please see the document, "Universal Serial Bus Test and
|
||||||
|
Measurement Class Specification (USBTMC) Revision 1.0" as
|
||||||
|
published by the USB-IF.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/usbtmc/devices/*/auto_abort
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
This file determines if the the transaction of the USB TMC
|
||||||
|
device is to be automatically aborted if there is any error.
|
||||||
|
For more details about this, please see the document,
|
||||||
|
"Universal Serial Bus Test and Measurement Class Specification
|
||||||
|
(USBTMC) Revision 1.0" as published by the USB-IF.
|
|
@ -0,0 +1,30 @@
|
||||||
|
What: /sys/module
|
||||||
|
Description:
|
||||||
|
The /sys/module tree consists of the following structure:
|
||||||
|
|
||||||
|
/sys/module/MODULENAME
|
||||||
|
The name of the module that is in the kernel. This
|
||||||
|
module name will show up either if the module is built
|
||||||
|
directly into the kernel, or if it is loaded as a
|
||||||
|
dyanmic module.
|
||||||
|
|
||||||
|
/sys/module/MODULENAME/parameters
|
||||||
|
This directory contains individual files that are each
|
||||||
|
individual parameters of the module that are able to be
|
||||||
|
changed at runtime. See the individual module
|
||||||
|
documentation as to the contents of these parameters and
|
||||||
|
what they accomplish.
|
||||||
|
|
||||||
|
Note: The individual parameter names and values are not
|
||||||
|
considered stable, only the fact that they will be
|
||||||
|
placed in this location within sysfs. See the
|
||||||
|
individual driver documentation for details as to the
|
||||||
|
stability of the different parameters.
|
||||||
|
|
||||||
|
/sys/module/MODULENAME/refcnt
|
||||||
|
If the module is able to be unloaded from the kernel, this file
|
||||||
|
will contain the current reference count of the module.
|
||||||
|
|
||||||
|
Note: If the module is built into the kernel, or if the
|
||||||
|
CONFIG_MODULE_UNLOAD kernel configuration value is not enabled,
|
||||||
|
this file will not be present.
|
|
@ -0,0 +1,71 @@
|
||||||
|
What: /sys/kernel/debug/kmemtrace/
|
||||||
|
Date: July 2008
|
||||||
|
Contact: Eduard - Gabriel Munteanu <eduard.munteanu@linux360.ro>
|
||||||
|
Description:
|
||||||
|
|
||||||
|
In kmemtrace-enabled kernels, the following files are created:
|
||||||
|
|
||||||
|
/sys/kernel/debug/kmemtrace/
|
||||||
|
cpu<n> (0400) Per-CPU tracing data, see below. (binary)
|
||||||
|
total_overruns (0400) Total number of bytes which were dropped from
|
||||||
|
cpu<n> files because of full buffer condition,
|
||||||
|
non-binary. (text)
|
||||||
|
abi_version (0400) Kernel's kmemtrace ABI version. (text)
|
||||||
|
|
||||||
|
Each per-CPU file should be read according to the relay interface. That is,
|
||||||
|
the reader should set affinity to that specific CPU and, as currently done by
|
||||||
|
the userspace application (though there are other methods), use poll() with
|
||||||
|
an infinite timeout before every read(). Otherwise, erroneous data may be
|
||||||
|
read. The binary data has the following _core_ format:
|
||||||
|
|
||||||
|
Event ID (1 byte) Unsigned integer, one of:
|
||||||
|
0 - represents an allocation (KMEMTRACE_EVENT_ALLOC)
|
||||||
|
1 - represents a freeing of previously allocated memory
|
||||||
|
(KMEMTRACE_EVENT_FREE)
|
||||||
|
Type ID (1 byte) Unsigned integer, one of:
|
||||||
|
0 - this is a kmalloc() / kfree()
|
||||||
|
1 - this is a kmem_cache_alloc() / kmem_cache_free()
|
||||||
|
2 - this is a __get_free_pages() et al.
|
||||||
|
Event size (2 bytes) Unsigned integer representing the
|
||||||
|
size of this event. Used to extend
|
||||||
|
kmemtrace. Discard the bytes you
|
||||||
|
don't know about.
|
||||||
|
Sequence number (4 bytes) Signed integer used to reorder data
|
||||||
|
logged on SMP machines. Wraparound
|
||||||
|
must be taken into account, although
|
||||||
|
it is unlikely.
|
||||||
|
Caller address (8 bytes) Return address to the caller.
|
||||||
|
Pointer to mem (8 bytes) Pointer to target memory area. Can be
|
||||||
|
NULL, but not all such calls might be
|
||||||
|
recorded.
|
||||||
|
|
||||||
|
In case of KMEMTRACE_EVENT_ALLOC events, the next fields follow:
|
||||||
|
|
||||||
|
Requested bytes (8 bytes) Total number of requested bytes,
|
||||||
|
unsigned, must not be zero.
|
||||||
|
Allocated bytes (8 bytes) Total number of actually allocated
|
||||||
|
bytes, unsigned, must not be lower
|
||||||
|
than requested bytes.
|
||||||
|
Requested flags (4 bytes) GFP flags supplied by the caller.
|
||||||
|
Target CPU (4 bytes) Signed integer, valid for event id 1.
|
||||||
|
If equal to -1, target CPU is the same
|
||||||
|
as origin CPU, but the reverse might
|
||||||
|
not be true.
|
||||||
|
|
||||||
|
The data is made available in the same endianness the machine has.
|
||||||
|
|
||||||
|
Other event ids and type ids may be defined and added. Other fields may be
|
||||||
|
added by increasing event size, but see below for details.
|
||||||
|
Every modification to the ABI, including new id definitions, are followed
|
||||||
|
by bumping the ABI version by one.
|
||||||
|
|
||||||
|
Adding new data to the packet (features) is done at the end of the mandatory
|
||||||
|
data:
|
||||||
|
Feature size (2 byte)
|
||||||
|
Feature ID (1 byte)
|
||||||
|
Feature data (Feature size - 3 bytes)
|
||||||
|
|
||||||
|
|
||||||
|
Users:
|
||||||
|
kmemtrace-user - git://repo.or.cz/kmemtrace-user.git
|
||||||
|
|
|
@ -0,0 +1,19 @@
|
||||||
|
What: /sys/kernel/debug/pktcdvd/pktcdvd[0-7]
|
||||||
|
Date: Oct. 2006
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: Thomas Maier <balagi@justmail.de>
|
||||||
|
Description:
|
||||||
|
|
||||||
|
debugfs interface
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
The pktcdvd module (packet writing driver) creates
|
||||||
|
these files in debugfs:
|
||||||
|
|
||||||
|
/sys/kernel/debug/pktcdvd/pktcdvd[0-7]/
|
||||||
|
info (0444) Lots of driver statistics and infos.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
-------
|
||||||
|
|
||||||
|
cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
|
|
@ -0,0 +1,61 @@
|
||||||
|
What: security/ima/policy
|
||||||
|
Date: May 2008
|
||||||
|
Contact: Mimi Zohar <zohar@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The Trusted Computing Group(TCG) runtime Integrity
|
||||||
|
Measurement Architecture(IMA) maintains a list of hash
|
||||||
|
values of executables and other sensitive system files
|
||||||
|
loaded into the run-time of this system. At runtime,
|
||||||
|
the policy can be constrained based on LSM specific data.
|
||||||
|
Policies are loaded into the securityfs file ima/policy
|
||||||
|
by opening the file, writing the rules one at a time and
|
||||||
|
then closing the file. The new policy takes effect after
|
||||||
|
the file ima/policy is closed.
|
||||||
|
|
||||||
|
rule format: action [condition ...]
|
||||||
|
|
||||||
|
action: measure | dont_measure
|
||||||
|
condition:= base | lsm
|
||||||
|
base: [[func=] [mask=] [fsmagic=] [uid=]]
|
||||||
|
lsm: [[subj_user=] [subj_role=] [subj_type=]
|
||||||
|
[obj_user=] [obj_role=] [obj_type=]]
|
||||||
|
|
||||||
|
base: func:= [BPRM_CHECK][FILE_MMAP][INODE_PERMISSION]
|
||||||
|
mask:= [MAY_READ] [MAY_WRITE] [MAY_APPEND] [MAY_EXEC]
|
||||||
|
fsmagic:= hex value
|
||||||
|
uid:= decimal value
|
||||||
|
lsm: are LSM specific
|
||||||
|
|
||||||
|
default policy:
|
||||||
|
# PROC_SUPER_MAGIC
|
||||||
|
dont_measure fsmagic=0x9fa0
|
||||||
|
# SYSFS_MAGIC
|
||||||
|
dont_measure fsmagic=0x62656572
|
||||||
|
# DEBUGFS_MAGIC
|
||||||
|
dont_measure fsmagic=0x64626720
|
||||||
|
# TMPFS_MAGIC
|
||||||
|
dont_measure fsmagic=0x01021994
|
||||||
|
# SECURITYFS_MAGIC
|
||||||
|
dont_measure fsmagic=0x73636673
|
||||||
|
|
||||||
|
measure func=BPRM_CHECK
|
||||||
|
measure func=FILE_MMAP mask=MAY_EXEC
|
||||||
|
measure func=INODE_PERM mask=MAY_READ uid=0
|
||||||
|
|
||||||
|
The default policy measures all executables in bprm_check,
|
||||||
|
all files mmapped executable in file_mmap, and all files
|
||||||
|
open for read by root in inode_permission.
|
||||||
|
|
||||||
|
Examples of LSM specific definitions:
|
||||||
|
|
||||||
|
SELinux:
|
||||||
|
# SELINUX_MAGIC
|
||||||
|
dont_measure fsmagic=0xF97CFF8C
|
||||||
|
|
||||||
|
dont_measure obj_type=var_log_t
|
||||||
|
dont_measure obj_type=auditd_log_t
|
||||||
|
measure subj_user=system_u func=INODE_PERM mask=MAY_READ
|
||||||
|
measure subj_role=system_r func=INODE_PERM mask=MAY_READ
|
||||||
|
|
||||||
|
Smack:
|
||||||
|
measure subj_user=_ func=INODE_PERM mask=MAY_READ
|
|
@ -0,0 +1,22 @@
|
||||||
|
What: /proc/diskstats
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Jerome Marchand <jmarchan@redhat.com>
|
||||||
|
Description:
|
||||||
|
The /proc/diskstats file displays the I/O statistics
|
||||||
|
of block devices. Each line contains the following 14
|
||||||
|
fields:
|
||||||
|
1 - major number
|
||||||
|
2 - minor mumber
|
||||||
|
3 - device name
|
||||||
|
4 - reads completed succesfully
|
||||||
|
5 - reads merged
|
||||||
|
6 - sectors read
|
||||||
|
7 - time spent reading (ms)
|
||||||
|
8 - writes completed
|
||||||
|
9 - writes merged
|
||||||
|
10 - sectors written
|
||||||
|
11 - time spent writing (ms)
|
||||||
|
12 - I/Os currently in progress
|
||||||
|
13 - time spent doing I/Os (ms)
|
||||||
|
14 - weighted time spent doing I/Os (ms)
|
||||||
|
For more details refer to Documentation/iostats.txt
|
|
@ -0,0 +1,130 @@
|
||||||
|
What: /sys/block/<disk>/stat
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Jerome Marchand <jmarchan@redhat.com>
|
||||||
|
Description:
|
||||||
|
The /sys/block/<disk>/stat files displays the I/O
|
||||||
|
statistics of disk <disk>. They contain 11 fields:
|
||||||
|
1 - reads completed succesfully
|
||||||
|
2 - reads merged
|
||||||
|
3 - sectors read
|
||||||
|
4 - time spent reading (ms)
|
||||||
|
5 - writes completed
|
||||||
|
6 - writes merged
|
||||||
|
7 - sectors written
|
||||||
|
8 - time spent writing (ms)
|
||||||
|
9 - I/Os currently in progress
|
||||||
|
10 - time spent doing I/Os (ms)
|
||||||
|
11 - weighted time spent doing I/Os (ms)
|
||||||
|
For more details refer Documentation/iostats.txt
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/<part>/stat
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Jerome Marchand <jmarchan@redhat.com>
|
||||||
|
Description:
|
||||||
|
The /sys/block/<disk>/<part>/stat files display the
|
||||||
|
I/O statistics of partition <part>. The format is the
|
||||||
|
same as the above-written /sys/block/<disk>/stat
|
||||||
|
format.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/integrity/format
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Metadata format for integrity capable block device.
|
||||||
|
E.g. T10-DIF-TYPE1-CRC.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/integrity/read_verify
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Indicates whether the block layer should verify the
|
||||||
|
integrity of read requests serviced by devices that
|
||||||
|
support sending integrity metadata.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/integrity/tag_size
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Number of bytes of integrity tag space available per
|
||||||
|
512 bytes of data.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/integrity/write_generate
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Indicates whether the block layer should automatically
|
||||||
|
generate checksums for write requests bound for
|
||||||
|
devices that support receiving integrity metadata.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/alignment_offset
|
||||||
|
Date: April 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Storage devices may report a physical block size that is
|
||||||
|
bigger than the logical block size (for instance a drive
|
||||||
|
with 4KB physical sectors exposing 512-byte logical
|
||||||
|
blocks to the operating system). This parameter
|
||||||
|
indicates how many bytes the beginning of the device is
|
||||||
|
offset from the disk's natural alignment.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/<partition>/alignment_offset
|
||||||
|
Date: April 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Storage devices may report a physical block size that is
|
||||||
|
bigger than the logical block size (for instance a drive
|
||||||
|
with 4KB physical sectors exposing 512-byte logical
|
||||||
|
blocks to the operating system). This parameter
|
||||||
|
indicates how many bytes the beginning of the partition
|
||||||
|
is offset from the disk's natural alignment.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/queue/logical_block_size
|
||||||
|
Date: May 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
This is the smallest unit the storage device can
|
||||||
|
address. It is typically 512 bytes.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/queue/physical_block_size
|
||||||
|
Date: May 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
This is the smallest unit a physical storage device can
|
||||||
|
write atomically. It is usually the same as the logical
|
||||||
|
block size but may be bigger. One example is SATA
|
||||||
|
drives with 4KB sectors that expose a 512-byte logical
|
||||||
|
block size to the operating system. For stacked block
|
||||||
|
devices the physical_block_size variable contains the
|
||||||
|
maximum physical_block_size of the component devices.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/queue/minimum_io_size
|
||||||
|
Date: April 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Storage devices may report a granularity or preferred
|
||||||
|
minimum I/O size which is the smallest request the
|
||||||
|
device can perform without incurring a performance
|
||||||
|
penalty. For disk drives this is often the physical
|
||||||
|
block size. For RAID arrays it is often the stripe
|
||||||
|
chunk size. A properly aligned multiple of
|
||||||
|
minimum_io_size is the preferred request size for
|
||||||
|
workloads where a high number of I/O operations is
|
||||||
|
desired.
|
||||||
|
|
||||||
|
What: /sys/block/<disk>/queue/optimal_io_size
|
||||||
|
Date: April 2009
|
||||||
|
Contact: Martin K. Petersen <martin.petersen@oracle.com>
|
||||||
|
Description:
|
||||||
|
Storage devices may report an optimal I/O size, which is
|
||||||
|
the device's preferred unit for sustained I/O. This is
|
||||||
|
rarely reported for disk drives. For RAID arrays it is
|
||||||
|
usually the stripe width or the internal track size. A
|
||||||
|
properly aligned multiple of optimal_io_size is the
|
||||||
|
preferred request size for workloads where sustained
|
||||||
|
throughput is desired. If no optimal I/O size is
|
||||||
|
reported this file contains 0.
|
|
@ -0,0 +1,35 @@
|
||||||
|
What: /sys/bus/css/devices/.../type
|
||||||
|
Date: March 2008
|
||||||
|
Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
|
||||||
|
linux-s390@vger.kernel.org
|
||||||
|
Description: Contains the subchannel type, as reported by the hardware.
|
||||||
|
This attribute is present for all subchannel types.
|
||||||
|
|
||||||
|
What: /sys/bus/css/devices/.../modalias
|
||||||
|
Date: March 2008
|
||||||
|
Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
|
||||||
|
linux-s390@vger.kernel.org
|
||||||
|
Description: Contains the module alias as reported with uevents.
|
||||||
|
It is of the format css:t<type> and present for all
|
||||||
|
subchannel types.
|
||||||
|
|
||||||
|
What: /sys/bus/css/drivers/io_subchannel/.../chpids
|
||||||
|
Date: December 2002
|
||||||
|
Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
|
||||||
|
linux-s390@vger.kernel.org
|
||||||
|
Description: Contains the ids of the channel paths used by this
|
||||||
|
subchannel, as reported by the channel subsystem
|
||||||
|
during subchannel recognition.
|
||||||
|
Note: This is an I/O-subchannel specific attribute.
|
||||||
|
Users: s390-tools, HAL
|
||||||
|
|
||||||
|
What: /sys/bus/css/drivers/io_subchannel/.../pimpampom
|
||||||
|
Date: December 2002
|
||||||
|
Contact: Cornelia Huck <cornelia.huck@de.ibm.com>
|
||||||
|
linux-s390@vger.kernel.org
|
||||||
|
Description: Contains the PIM/PAM/POM values, as reported by the
|
||||||
|
channel subsystem when last queried by the common I/O
|
||||||
|
layer (this implies that this attribute is not neccessarily
|
||||||
|
in sync with the values current in the channel subsystem).
|
||||||
|
Note: This is an I/O-subchannel specific attribute.
|
||||||
|
Users: s390-tools, HAL
|
|
@ -0,0 +1,141 @@
|
||||||
|
What: /sys/bus/pci/drivers/.../bind
|
||||||
|
Date: December 2003
|
||||||
|
Contact: linux-pci@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Writing a device location to this file will cause
|
||||||
|
the driver to attempt to bind to the device found at
|
||||||
|
this location. This is useful for overriding default
|
||||||
|
bindings. The format for the location is: DDDD:BB:DD.F.
|
||||||
|
That is Domain:Bus:Device.Function and is the same as
|
||||||
|
found in /sys/bus/pci/devices/. For example:
|
||||||
|
# echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
|
||||||
|
(Note: kernels before 2.6.28 may require echo -n).
|
||||||
|
|
||||||
|
What: /sys/bus/pci/drivers/.../unbind
|
||||||
|
Date: December 2003
|
||||||
|
Contact: linux-pci@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Writing a device location to this file will cause the
|
||||||
|
driver to attempt to unbind from the device found at
|
||||||
|
this location. This may be useful when overriding default
|
||||||
|
bindings. The format for the location is: DDDD:BB:DD.F.
|
||||||
|
That is Domain:Bus:Device.Function and is the same as
|
||||||
|
found in /sys/bus/pci/devices/. For example:
|
||||||
|
# echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
|
||||||
|
(Note: kernels before 2.6.28 may require echo -n).
|
||||||
|
|
||||||
|
What: /sys/bus/pci/drivers/.../new_id
|
||||||
|
Date: December 2003
|
||||||
|
Contact: linux-pci@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Writing a device ID to this file will attempt to
|
||||||
|
dynamically add a new device ID to a PCI device driver.
|
||||||
|
This may allow the driver to support more hardware than
|
||||||
|
was included in the driver's static device ID support
|
||||||
|
table at compile time. The format for the device ID is:
|
||||||
|
VVVV DDDD SVVV SDDD CCCC MMMM PPPP. That is Vendor ID,
|
||||||
|
Device ID, Subsystem Vendor ID, Subsystem Device ID,
|
||||||
|
Class, Class Mask, and Private Driver Data. The Vendor ID
|
||||||
|
and Device ID fields are required, the rest are optional.
|
||||||
|
Upon successfully adding an ID, the driver will probe
|
||||||
|
for the device and attempt to bind to it. For example:
|
||||||
|
# echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
|
||||||
|
|
||||||
|
What: /sys/bus/pci/drivers/.../remove_id
|
||||||
|
Date: February 2009
|
||||||
|
Contact: Chris Wright <chrisw@sous-sol.org>
|
||||||
|
Description:
|
||||||
|
Writing a device ID to this file will remove an ID
|
||||||
|
that was dynamically added via the new_id sysfs entry.
|
||||||
|
The format for the device ID is:
|
||||||
|
VVVV DDDD SVVV SDDD CCCC MMMM. That is Vendor ID, Device
|
||||||
|
ID, Subsystem Vendor ID, Subsystem Device ID, Class,
|
||||||
|
and Class Mask. The Vendor ID and Device ID fields are
|
||||||
|
required, the rest are optional. After successfully
|
||||||
|
removing an ID, the driver will no longer support the
|
||||||
|
device. This is useful to ensure auto probing won't
|
||||||
|
match the driver to the device. For example:
|
||||||
|
# echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
|
||||||
|
|
||||||
|
What: /sys/bus/pci/rescan
|
||||||
|
Date: January 2009
|
||||||
|
Contact: Linux PCI developers <linux-pci@vger.kernel.org>
|
||||||
|
Description:
|
||||||
|
Writing a non-zero value to this attribute will
|
||||||
|
force a rescan of all PCI buses in the system, and
|
||||||
|
re-discover previously removed devices.
|
||||||
|
Depends on CONFIG_HOTPLUG.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../remove
|
||||||
|
Date: January 2009
|
||||||
|
Contact: Linux PCI developers <linux-pci@vger.kernel.org>
|
||||||
|
Description:
|
||||||
|
Writing a non-zero value to this attribute will
|
||||||
|
hot-remove the PCI device and any of its children.
|
||||||
|
Depends on CONFIG_HOTPLUG.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../rescan
|
||||||
|
Date: January 2009
|
||||||
|
Contact: Linux PCI developers <linux-pci@vger.kernel.org>
|
||||||
|
Description:
|
||||||
|
Writing a non-zero value to this attribute will
|
||||||
|
force a rescan of the device's parent bus and all
|
||||||
|
child buses, and re-discover devices removed earlier
|
||||||
|
from this part of the device tree.
|
||||||
|
Depends on CONFIG_HOTPLUG.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../reset
|
||||||
|
Date: July 2009
|
||||||
|
Contact: Michael S. Tsirkin <mst@redhat.com>
|
||||||
|
Description:
|
||||||
|
Some devices allow an individual function to be reset
|
||||||
|
without affecting other functions in the same device.
|
||||||
|
For devices that have this support, a file named reset
|
||||||
|
will be present in sysfs. Writing 1 to this file
|
||||||
|
will perform reset.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../vpd
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Ben Hutchings <bhutchings@solarflare.com>
|
||||||
|
Description:
|
||||||
|
A file named vpd in a device directory will be a
|
||||||
|
binary file containing the Vital Product Data for the
|
||||||
|
device. It should follow the VPD format defined in
|
||||||
|
PCI Specification 2.1 or 2.2, but users should consider
|
||||||
|
that some devices may have malformatted data. If the
|
||||||
|
underlying VPD has a writable section then the
|
||||||
|
corresponding section of this file will be writable.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../virtfnN
|
||||||
|
Date: March 2009
|
||||||
|
Contact: Yu Zhao <yu.zhao@intel.com>
|
||||||
|
Description:
|
||||||
|
This symbolic link appears when hardware supports the SR-IOV
|
||||||
|
capability and the Physical Function driver has enabled it.
|
||||||
|
The symbolic link points to the PCI device sysfs entry of the
|
||||||
|
Virtual Function whose index is N (0...MaxVFs-1).
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../dep_link
|
||||||
|
Date: March 2009
|
||||||
|
Contact: Yu Zhao <yu.zhao@intel.com>
|
||||||
|
Description:
|
||||||
|
This symbolic link appears when hardware supports the SR-IOV
|
||||||
|
capability and the Physical Function driver has enabled it,
|
||||||
|
and this device has vendor specific dependencies with others.
|
||||||
|
The symbolic link points to the PCI device sysfs entry of
|
||||||
|
Physical Function this device depends on.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/devices/.../physfn
|
||||||
|
Date: March 2009
|
||||||
|
Contact: Yu Zhao <yu.zhao@intel.com>
|
||||||
|
Description:
|
||||||
|
This symbolic link appears when a device is a Virtual Function.
|
||||||
|
The symbolic link points to the PCI device sysfs entry of the
|
||||||
|
Physical Function this device associates with.
|
||||||
|
|
||||||
|
What: /sys/bus/pci/slots/.../module
|
||||||
|
Date: June 2009
|
||||||
|
Contact: linux-pci@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
This symbolic link points to the PCI hotplug controller driver
|
||||||
|
module that manages the hotplug slot.
|
|
@ -0,0 +1,61 @@
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
|
||||||
|
Date: March 2009
|
||||||
|
Kernel Version: 2.6.30
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the SCSI INQUIRY page 0 model for logical drive
|
||||||
|
Y of controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
|
||||||
|
Date: March 2009
|
||||||
|
Kernel Version: 2.6.30
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the SCSI INQUIRY page 0 revision for logical
|
||||||
|
drive Y of controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
|
||||||
|
Date: March 2009
|
||||||
|
Kernel Version: 2.6.30
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the SCSI INQUIRY page 83 serial number for logical
|
||||||
|
drive Y of controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
|
||||||
|
Date: March 2009
|
||||||
|
Kernel Version: 2.6.30
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the SCSI INQUIRY page 0 vendor for logical drive
|
||||||
|
Y of controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
|
||||||
|
Date: March 2009
|
||||||
|
Kernel Version: 2.6.30
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: A symbolic link to /sys/block/cciss!cXdY
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/rescan
|
||||||
|
Date: August 2009
|
||||||
|
Kernel Version: 2.6.31
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Kicks of a rescan of the controller to discover logical
|
||||||
|
drive topology changes.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
|
||||||
|
Date: August 2009
|
||||||
|
Kernel Version: 2.6.31
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the 8-byte LUN ID used to address logical
|
||||||
|
drive Y of controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
|
||||||
|
Date: August 2009
|
||||||
|
Kernel Version: 2.6.31
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the RAID level of logical drive Y of
|
||||||
|
controller X.
|
||||||
|
|
||||||
|
Where: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
|
||||||
|
Date: August 2009
|
||||||
|
Kernel Version: 2.6.31
|
||||||
|
Contact: iss_storagedev@hp.com
|
||||||
|
Description: Displays the usage count (number of opens) of logical drive Y
|
||||||
|
of controller X.
|
|
@ -0,0 +1,28 @@
|
||||||
|
What: /sys/bus/umc/
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The Wireless Host Controller Interface (WHCI)
|
||||||
|
specification describes a PCI-based device with
|
||||||
|
multiple capabilities; the UWB Multi-interface
|
||||||
|
Controller (UMC).
|
||||||
|
|
||||||
|
The umc bus presents each of the individual
|
||||||
|
capabilties as a device.
|
||||||
|
|
||||||
|
What: /sys/bus/umc/devices/.../capability_id
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The ID of this capability, with 0 being the radio
|
||||||
|
controller capability.
|
||||||
|
|
||||||
|
What: /sys/bus/umc/devices/.../version
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The specification version this capability's hardware
|
||||||
|
interface complies with.
|
|
@ -0,0 +1,146 @@
|
||||||
|
What: /sys/bus/usb/devices/.../power/autosuspend
|
||||||
|
Date: March 2007
|
||||||
|
KernelVersion: 2.6.21
|
||||||
|
Contact: Alan Stern <stern@rowland.harvard.edu>
|
||||||
|
Description:
|
||||||
|
Each USB device directory will contain a file named
|
||||||
|
power/autosuspend. This file holds the time (in seconds)
|
||||||
|
the device must be idle before it will be autosuspended.
|
||||||
|
0 means the device will be autosuspended as soon as
|
||||||
|
possible. Negative values will prevent the device from
|
||||||
|
being autosuspended at all, and writing a negative value
|
||||||
|
will resume the device if it is already suspended.
|
||||||
|
|
||||||
|
The autosuspend delay for newly-created devices is set to
|
||||||
|
the value of the usbcore.autosuspend module parameter.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/devices/.../power/level
|
||||||
|
Date: March 2007
|
||||||
|
KernelVersion: 2.6.21
|
||||||
|
Contact: Alan Stern <stern@rowland.harvard.edu>
|
||||||
|
Description:
|
||||||
|
Each USB device directory will contain a file named
|
||||||
|
power/level. This file holds a power-level setting for
|
||||||
|
the device, one of "on", "auto", or "suspend".
|
||||||
|
|
||||||
|
"on" means that the device is not allowed to autosuspend,
|
||||||
|
although normal suspends for system sleep will still
|
||||||
|
be honored. "auto" means the device will autosuspend
|
||||||
|
and autoresume in the usual manner, according to the
|
||||||
|
capabilities of its driver. "suspend" means the device
|
||||||
|
is forced into a suspended state and it will not autoresume
|
||||||
|
in response to I/O requests. However remote-wakeup requests
|
||||||
|
from the device may still be enabled (the remote-wakeup
|
||||||
|
setting is controlled separately by the power/wakeup
|
||||||
|
attribute).
|
||||||
|
|
||||||
|
During normal use, devices should be left in the "auto"
|
||||||
|
level. The other levels are meant for administrative uses.
|
||||||
|
If you want to suspend a device immediately but leave it
|
||||||
|
free to wake up in response to I/O requests, you should
|
||||||
|
write "0" to power/autosuspend.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/devices/.../power/persist
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.23
|
||||||
|
Contact: Alan Stern <stern@rowland.harvard.edu>
|
||||||
|
Description:
|
||||||
|
If CONFIG_USB_PERSIST is set, then each USB device directory
|
||||||
|
will contain a file named power/persist. The file holds a
|
||||||
|
boolean value (0 or 1) indicating whether or not the
|
||||||
|
"USB-Persist" facility is enabled for the device. Since the
|
||||||
|
facility is inherently dangerous, it is disabled by default
|
||||||
|
for all devices except hubs. For more information, see
|
||||||
|
Documentation/usb/persist.txt.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../power/connected_duration
|
||||||
|
Date: January 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Sarah Sharp <sarah.a.sharp@intel.com>
|
||||||
|
Description:
|
||||||
|
If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
|
||||||
|
is present. When read, it returns the total time (in msec)
|
||||||
|
that the USB device has been connected to the machine. This
|
||||||
|
file is read-only.
|
||||||
|
Users:
|
||||||
|
PowerTOP <power@bughost.org>
|
||||||
|
http://www.lesswatts.org/projects/powertop/
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../power/active_duration
|
||||||
|
Date: January 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Sarah Sharp <sarah.a.sharp@intel.com>
|
||||||
|
Description:
|
||||||
|
If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
|
||||||
|
is present. When read, it returns the total time (in msec)
|
||||||
|
that the USB device has been active, i.e. not in a suspended
|
||||||
|
state. This file is read-only.
|
||||||
|
|
||||||
|
Tools can use this file and the connected_duration file to
|
||||||
|
compute the percentage of time that a device has been active.
|
||||||
|
For example,
|
||||||
|
echo $((100 * `cat active_duration` / `cat connected_duration`))
|
||||||
|
will give an integer percentage. Note that this does not
|
||||||
|
account for counter wrap.
|
||||||
|
Users:
|
||||||
|
PowerTOP <power@bughost.org>
|
||||||
|
http://www.lesswatts.org/projects/powertop/
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend
|
||||||
|
Date: January 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: Sarah Sharp <sarah.a.sharp@intel.com>
|
||||||
|
Description:
|
||||||
|
When read, this file returns 1 if the interface driver
|
||||||
|
for this interface supports autosuspend. It also
|
||||||
|
returns 1 if no driver has claimed this interface, as an
|
||||||
|
unclaimed interface will not stop the device from being
|
||||||
|
autosuspended if all other interface drivers are idle.
|
||||||
|
The file returns 0 if autosuspend support has not been
|
||||||
|
added to the driver.
|
||||||
|
Users:
|
||||||
|
USB PM tool
|
||||||
|
git://git.moblin.org/users/sarah/usb-pm-tool/
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../authorized
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
Authorized devices are available for use by device
|
||||||
|
drivers, non-authorized one are not. By default, wired
|
||||||
|
USB devices are authorized.
|
||||||
|
|
||||||
|
Certified Wireless USB devices are not authorized
|
||||||
|
initially and should be (by writing 1) after the
|
||||||
|
device has been authenticated.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../wusb_cdid
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
For Certified Wireless USB devices only.
|
||||||
|
|
||||||
|
A devices's CDID, as 16 space-separated hex octets.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../wusb_ck
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
For Certified Wireless USB devices only.
|
||||||
|
|
||||||
|
Write the device's connection key (CK) to start the
|
||||||
|
authentication of the device. The CK is 16
|
||||||
|
space-separated hex octets.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/device/.../wusb_disconnect
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
For Certified Wireless USB devices only.
|
||||||
|
|
||||||
|
Write a 1 to force the device to disconnect
|
||||||
|
(equivalent to unplugging a wired USB device).
|
|
@ -0,0 +1,43 @@
|
||||||
|
Where: /sys/bus/usb/.../powered
|
||||||
|
Date: August 2008
|
||||||
|
Kernel Version: 2.6.26
|
||||||
|
Contact: Harrison Metzger <harrisonmetz@gmail.com>
|
||||||
|
Description: Controls whether the device's display will powered.
|
||||||
|
A value of 0 is off and a non-zero value is on.
|
||||||
|
|
||||||
|
Where: /sys/bus/usb/.../mode_msb
|
||||||
|
Where: /sys/bus/usb/.../mode_lsb
|
||||||
|
Date: August 2008
|
||||||
|
Kernel Version: 2.6.26
|
||||||
|
Contact: Harrison Metzger <harrisonmetz@gmail.com>
|
||||||
|
Description: Controls the devices display mode.
|
||||||
|
For a 6 character display the values are
|
||||||
|
MSB 0x06; LSB 0x3F, and
|
||||||
|
for an 8 character display the values are
|
||||||
|
MSB 0x08; LSB 0xFF.
|
||||||
|
|
||||||
|
Where: /sys/bus/usb/.../textmode
|
||||||
|
Date: August 2008
|
||||||
|
Kernel Version: 2.6.26
|
||||||
|
Contact: Harrison Metzger <harrisonmetz@gmail.com>
|
||||||
|
Description: Controls the way the device interprets its text buffer.
|
||||||
|
raw: each character controls its segment manually
|
||||||
|
hex: each character is between 0-15
|
||||||
|
ascii: each character is between '0'-'9' and 'A'-'F'.
|
||||||
|
|
||||||
|
Where: /sys/bus/usb/.../text
|
||||||
|
Date: August 2008
|
||||||
|
Kernel Version: 2.6.26
|
||||||
|
Contact: Harrison Metzger <harrisonmetz@gmail.com>
|
||||||
|
Description: The text (or data) for the device to display
|
||||||
|
|
||||||
|
Where: /sys/bus/usb/.../decimals
|
||||||
|
Date: August 2008
|
||||||
|
Kernel Version: 2.6.26
|
||||||
|
Contact: Harrison Metzger <harrisonmetz@gmail.com>
|
||||||
|
Description: Controls the decimal places on the device.
|
||||||
|
To set the nth decimal place, give this field
|
||||||
|
the value of 10 ** n. Assume this field has
|
||||||
|
the value k and has 1 or more decimal places set,
|
||||||
|
to set the mth place (where m is not already set),
|
||||||
|
change this fields value to k + 10 ** m.
|
|
@ -0,0 +1,88 @@
|
||||||
|
What: /sys/class/c2port/
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/ directory will contain files and
|
||||||
|
directories that will provide a unified interface to
|
||||||
|
the C2 port interface.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/ directory is related to X-th
|
||||||
|
C2 port into the system. Each directory will contain files to
|
||||||
|
manage and control its C2 port.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/access
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/access file enable the access
|
||||||
|
to the C2 port from the system. No commands can be sent
|
||||||
|
till this entry is set to 0.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/dev_id
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/dev_id file show the device ID
|
||||||
|
of the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_access
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_access file enable the
|
||||||
|
access to the on-board flash of the connected micro.
|
||||||
|
No commands can be sent till this entry is set to 0.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_block_size
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_block_size file show
|
||||||
|
the on-board flash block size of the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_blocks_num
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_blocks_num file show
|
||||||
|
the on-board flash blocks number of the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_data
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_data file export
|
||||||
|
the content of the on-board flash of the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_erase
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_erase file execute
|
||||||
|
the "erase" command on the on-board flash of the connected
|
||||||
|
micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/flash_erase
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/flash_erase file show the
|
||||||
|
on-board flash size of the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/reset
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/reset file execute a "reset"
|
||||||
|
command on the connected micro.
|
||||||
|
|
||||||
|
What: /sys/class/c2port/c2portX/rev_id
|
||||||
|
Date: October 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/c2port/c2portX/rev_id file show the revision ID
|
||||||
|
of the connected micro.
|
|
@ -0,0 +1,16 @@
|
||||||
|
What: /sys/class/
|
||||||
|
Date: Febuary 2006
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
The /sys/class directory will consist of a group of
|
||||||
|
subdirectories describing individual classes of devices
|
||||||
|
in the kernel. The individual directories will consist
|
||||||
|
of either subdirectories, or symlinks to other
|
||||||
|
directories.
|
||||||
|
|
||||||
|
All programs that use this directory tree must be able
|
||||||
|
to handle both subdirectories or symlinks in order to
|
||||||
|
work properly.
|
||||||
|
|
||||||
|
Users:
|
||||||
|
udev <linux-hotplug-devel@lists.sourceforge.net>
|
|
@ -0,0 +1,50 @@
|
||||||
|
What: /sys/class/bdi/<bdi>/
|
||||||
|
Date: January 2008
|
||||||
|
Contact: Peter Zijlstra <a.p.zijlstra@chello.nl>
|
||||||
|
Description:
|
||||||
|
|
||||||
|
Provide a place in sysfs for the backing_dev_info object. This allows
|
||||||
|
setting and retrieving various BDI specific variables.
|
||||||
|
|
||||||
|
The <bdi> identifier can be either of the following:
|
||||||
|
|
||||||
|
MAJOR:MINOR
|
||||||
|
|
||||||
|
Device number for block devices, or value of st_dev on
|
||||||
|
non-block filesystems which provide their own BDI, such as NFS
|
||||||
|
and FUSE.
|
||||||
|
|
||||||
|
MAJOR:MINOR-fuseblk
|
||||||
|
|
||||||
|
Value of st_dev on fuseblk filesystems.
|
||||||
|
|
||||||
|
default
|
||||||
|
|
||||||
|
The default backing dev, used for non-block device backed
|
||||||
|
filesystems which do not provide their own BDI.
|
||||||
|
|
||||||
|
Files under /sys/class/bdi/<bdi>/
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
read_ahead_kb (read-write)
|
||||||
|
|
||||||
|
Size of the read-ahead window in kilobytes
|
||||||
|
|
||||||
|
min_ratio (read-write)
|
||||||
|
|
||||||
|
Under normal circumstances each device is given a part of the
|
||||||
|
total write-back cache that relates to its current average
|
||||||
|
writeout speed in relation to the other devices.
|
||||||
|
|
||||||
|
The 'min_ratio' parameter allows assigning a minimum
|
||||||
|
percentage of the write-back cache to a particular device.
|
||||||
|
For example, this is useful for providing a minimum QoS.
|
||||||
|
|
||||||
|
max_ratio (read-write)
|
||||||
|
|
||||||
|
Allows limiting a particular device to use not more than the
|
||||||
|
given percentage of the write-back cache. This is useful in
|
||||||
|
situations where we want to avoid one device taking all or
|
||||||
|
most of the write-back cache. For example in case of an NFS
|
||||||
|
mount that is prone to get stuck, or a FUSE mount which cannot
|
||||||
|
be trusted to play fair.
|
|
@ -0,0 +1,23 @@
|
||||||
|
What: /sys/class/lcd/<lcd>/lcd_power
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Control LCD power, values are FB_BLANK_* from fb.h
|
||||||
|
- FB_BLANK_UNBLANK (0) : power on.
|
||||||
|
- FB_BLANK_POWERDOWN (4) : power off
|
||||||
|
|
||||||
|
What: /sys/class/lcd/<lcd>/contrast
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Current contrast of this LCD device. Value is between 0 and
|
||||||
|
/sys/class/lcd/<lcd>/max_contrast.
|
||||||
|
|
||||||
|
What: /sys/class/lcd/<lcd>/max_contrast
|
||||||
|
Date: April 2005
|
||||||
|
KernelVersion: 2.6.12
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Maximum contrast for this LCD device.
|
|
@ -0,0 +1,28 @@
|
||||||
|
What: /sys/class/leds/<led>/brightness
|
||||||
|
Date: March 2006
|
||||||
|
KernelVersion: 2.6.17
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Set the brightness of the LED. Most LEDs don't
|
||||||
|
have hardware brightness support so will just be turned on for
|
||||||
|
non-zero brightness settings. The value is between 0 and
|
||||||
|
/sys/class/leds/<led>/max_brightness.
|
||||||
|
|
||||||
|
What: /sys/class/leds/<led>/max_brightness
|
||||||
|
Date: March 2006
|
||||||
|
KernelVersion: 2.6.17
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Maximum brightness level for this led, default is 255 (LED_FULL).
|
||||||
|
|
||||||
|
What: /sys/class/leds/<led>/trigger
|
||||||
|
Date: March 2006
|
||||||
|
KernelVersion: 2.6.17
|
||||||
|
Contact: Richard Purdie <rpurdie@rpsys.net>
|
||||||
|
Description:
|
||||||
|
Set the trigger for this LED. A trigger is a kernel based source
|
||||||
|
of led events.
|
||||||
|
You can change triggers in a similar manner to the way an IO
|
||||||
|
scheduler is chosen. Trigger specific parameters can appear in
|
||||||
|
/sys/class/leds/<led> once a given trigger is selected.
|
||||||
|
|
|
@ -0,0 +1,125 @@
|
||||||
|
What: /sys/class/mtd/
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
The mtd/ class subdirectory belongs to the MTD subsystem
|
||||||
|
(MTD core).
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
The /sys/class/mtd/mtd{0,1,2,3,...} directories correspond
|
||||||
|
to each /dev/mtdX character device. These may represent
|
||||||
|
physical/simulated flash devices, partitions on a flash
|
||||||
|
device, or concatenated flash devices. They exist regardless
|
||||||
|
of whether CONFIG_MTD_CHAR is actually enabled.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdXro/
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
These directories provide the corresponding read-only device
|
||||||
|
nodes for /sys/class/mtd/mtdX/ . They are only created
|
||||||
|
(for the benefit of udev) if CONFIG_MTD_CHAR is enabled.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/dev
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
Major and minor numbers of the character device corresponding
|
||||||
|
to this MTD device (in <major>:<minor> format). This is the
|
||||||
|
read-write device so <minor> will be even.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdXro/dev
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
Major and minor numbers of the character device corresponding
|
||||||
|
to the read-only variant of thie MTD device (in
|
||||||
|
<major>:<minor> format). In this case <minor> will be odd.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/erasesize
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
"Major" erase size for the device. If numeraseregions is
|
||||||
|
zero, this is the eraseblock size for the entire device.
|
||||||
|
Otherwise, the MEMGETREGIONCOUNT/MEMGETREGIONINFO ioctls
|
||||||
|
can be used to determine the actual eraseblock layout.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/flags
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
A hexadecimal value representing the device flags, ORed
|
||||||
|
together:
|
||||||
|
|
||||||
|
0x0400: MTD_WRITEABLE - device is writable
|
||||||
|
0x0800: MTD_BIT_WRITEABLE - single bits can be flipped
|
||||||
|
0x1000: MTD_NO_ERASE - no erase necessary
|
||||||
|
0x2000: MTD_POWERUP_LOCK - always locked after reset
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/name
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
A human-readable ASCII name for the device or partition.
|
||||||
|
This will match the name in /proc/mtd .
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/numeraseregions
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
For devices that have variable eraseblock sizes, this
|
||||||
|
provides the total number of erase regions. Otherwise,
|
||||||
|
it will read back as zero.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/oobsize
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
Number of OOB bytes per page.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/size
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
Total size of the device/partition, in bytes.
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/type
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
One of the following ASCII strings, representing the device
|
||||||
|
type:
|
||||||
|
|
||||||
|
absent, ram, rom, nor, nand, dataflash, ubi, unknown
|
||||||
|
|
||||||
|
What: /sys/class/mtd/mtdX/writesize
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.29
|
||||||
|
Contact: linux-mtd@lists.infradead.org
|
||||||
|
Description:
|
||||||
|
Minimal writable flash unit size. This will always be
|
||||||
|
a positive integer.
|
||||||
|
|
||||||
|
In the case of NOR flash it is 1 (even though individual
|
||||||
|
bits can be cleared).
|
||||||
|
|
||||||
|
In the case of NAND flash it is one NAND page (or a
|
||||||
|
half page, or a quarter page).
|
||||||
|
|
||||||
|
In the case of ECC NOR, it is the ECC block size.
|
|
@ -0,0 +1,72 @@
|
||||||
|
What: /sys/class/pktcdvd/
|
||||||
|
Date: Oct. 2006
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: Thomas Maier <balagi@justmail.de>
|
||||||
|
Description:
|
||||||
|
|
||||||
|
sysfs interface
|
||||||
|
---------------
|
||||||
|
|
||||||
|
The pktcdvd module (packet writing driver) creates
|
||||||
|
these files in the sysfs:
|
||||||
|
(<devid> is in format major:minor )
|
||||||
|
|
||||||
|
/sys/class/pktcdvd/
|
||||||
|
add (0200) Write a block device id (major:minor)
|
||||||
|
to create a new pktcdvd device and map
|
||||||
|
it to the block device.
|
||||||
|
|
||||||
|
remove (0200) Write the pktcdvd device id (major:minor)
|
||||||
|
to it to remove the pktcdvd device.
|
||||||
|
|
||||||
|
device_map (0444) Shows the device mapping in format:
|
||||||
|
pktcdvd[0-7] <pktdevid> <blkdevid>
|
||||||
|
|
||||||
|
/sys/class/pktcdvd/pktcdvd[0-7]/
|
||||||
|
dev (0444) Device id
|
||||||
|
uevent (0200) To send an uevent.
|
||||||
|
|
||||||
|
/sys/class/pktcdvd/pktcdvd[0-7]/stat/
|
||||||
|
packets_started (0444) Number of started packets.
|
||||||
|
packets_finished (0444) Number of finished packets.
|
||||||
|
|
||||||
|
kb_written (0444) kBytes written.
|
||||||
|
kb_read (0444) kBytes read.
|
||||||
|
kb_read_gather (0444) kBytes read to fill write packets.
|
||||||
|
|
||||||
|
reset (0200) Write any value to it to reset
|
||||||
|
pktcdvd device statistic values, like
|
||||||
|
bytes read/written.
|
||||||
|
|
||||||
|
/sys/class/pktcdvd/pktcdvd[0-7]/write_queue/
|
||||||
|
size (0444) Contains the size of the bio write
|
||||||
|
queue.
|
||||||
|
|
||||||
|
congestion_off (0644) If bio write queue size is below
|
||||||
|
this mark, accept new bio requests
|
||||||
|
from the block layer.
|
||||||
|
|
||||||
|
congestion_on (0644) If bio write queue size is higher
|
||||||
|
as this mark, do no longer accept
|
||||||
|
bio write requests from the block
|
||||||
|
layer and wait till the pktcdvd
|
||||||
|
device has processed enough bio's
|
||||||
|
so that bio write queue size is
|
||||||
|
below congestion off mark.
|
||||||
|
A value of <= 0 disables congestion
|
||||||
|
control.
|
||||||
|
|
||||||
|
|
||||||
|
Example:
|
||||||
|
--------
|
||||||
|
To use the pktcdvd sysfs interface directly, you can do:
|
||||||
|
|
||||||
|
# create a new pktcdvd device mapped to /dev/hdc
|
||||||
|
echo "22:0" >/sys/class/pktcdvd/add
|
||||||
|
cat /sys/class/pktcdvd/device_map
|
||||||
|
# assuming device pktcdvd0 was created, look at stat's
|
||||||
|
cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written
|
||||||
|
# print the device id of the mapped block device
|
||||||
|
fgrep pktcdvd0 /sys/class/pktcdvd/device_map
|
||||||
|
# remove device, using pktcdvd0 device id 253:0
|
||||||
|
echo "253:0" >/sys/class/pktcdvd/remove
|
|
@ -0,0 +1,351 @@
|
||||||
|
What: /sys/class/regulator/.../state
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
state. This reports the regulator enable control, for
|
||||||
|
regulators which can report that input value.
|
||||||
|
|
||||||
|
This will be one of the following strings:
|
||||||
|
|
||||||
|
'enabled'
|
||||||
|
'disabled'
|
||||||
|
'unknown'
|
||||||
|
|
||||||
|
'enabled' means the regulator output is ON and is supplying
|
||||||
|
power to the system (assuming no error prevents it).
|
||||||
|
|
||||||
|
'disabled' means the regulator output is OFF and is not
|
||||||
|
supplying power to the system (unless some non-Linux
|
||||||
|
control has enabled it).
|
||||||
|
|
||||||
|
'unknown' means software cannot determine the state, or
|
||||||
|
the reported state is invalid.
|
||||||
|
|
||||||
|
NOTE: this field can be used in conjunction with microvolts
|
||||||
|
or microamps to determine configured regulator output levels.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../status
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
"status". This reports the current regulator status, for
|
||||||
|
regulators which can report that output value.
|
||||||
|
|
||||||
|
This will be one of the following strings:
|
||||||
|
|
||||||
|
off
|
||||||
|
on
|
||||||
|
error
|
||||||
|
fast
|
||||||
|
normal
|
||||||
|
idle
|
||||||
|
standby
|
||||||
|
|
||||||
|
"off" means the regulator is not supplying power to the
|
||||||
|
system.
|
||||||
|
|
||||||
|
"on" means the regulator is supplying power to the system,
|
||||||
|
and the regulator can't report a detailed operation mode.
|
||||||
|
|
||||||
|
"error" indicates an out-of-regulation status such as being
|
||||||
|
disabled due to thermal shutdown, or voltage being unstable
|
||||||
|
because of problems with the input power supply.
|
||||||
|
|
||||||
|
"fast", "normal", "idle", and "standby" are all detailed
|
||||||
|
regulator operation modes (described elsewhere). They
|
||||||
|
imply "on", but provide more detail.
|
||||||
|
|
||||||
|
Note that regulator status is a function of many inputs,
|
||||||
|
not limited to control inputs from Linux. For example,
|
||||||
|
the actual load presented may trigger "error" status; or
|
||||||
|
a regulator may be enabled by another user, even though
|
||||||
|
Linux did not enable it.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../type
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Each regulator directory will contain a field called
|
||||||
|
type. This holds the regulator type.
|
||||||
|
|
||||||
|
This will be one of the following strings:
|
||||||
|
|
||||||
|
'voltage'
|
||||||
|
'current'
|
||||||
|
'unknown'
|
||||||
|
|
||||||
|
'voltage' means the regulator output voltage can be controlled
|
||||||
|
by software.
|
||||||
|
|
||||||
|
'current' means the regulator output current limit can be
|
||||||
|
controlled by software.
|
||||||
|
|
||||||
|
'unknown' means software cannot control either voltage or
|
||||||
|
current limit.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../microvolts
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
microvolts. This holds the regulator output voltage setting
|
||||||
|
measured in microvolts (i.e. E-6 Volts), for regulators
|
||||||
|
which can report the control input for voltage.
|
||||||
|
|
||||||
|
NOTE: This value should not be used to determine the regulator
|
||||||
|
output voltage level as this value is the same regardless of
|
||||||
|
whether the regulator is enabled or disabled.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../microamps
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
microamps. This holds the regulator output current limit
|
||||||
|
setting measured in microamps (i.e. E-6 Amps), for regulators
|
||||||
|
which can report the control input for a current limit.
|
||||||
|
|
||||||
|
NOTE: This value should not be used to determine the regulator
|
||||||
|
output current level as this value is the same regardless of
|
||||||
|
whether the regulator is enabled or disabled.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../opmode
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
opmode. This holds the current regulator operating mode,
|
||||||
|
for regulators which can report that control input value.
|
||||||
|
|
||||||
|
The opmode value can be one of the following strings:
|
||||||
|
|
||||||
|
'fast'
|
||||||
|
'normal'
|
||||||
|
'idle'
|
||||||
|
'standby'
|
||||||
|
'unknown'
|
||||||
|
|
||||||
|
The modes are described in include/linux/regulator/consumer.h
|
||||||
|
|
||||||
|
NOTE: This value should not be used to determine the regulator
|
||||||
|
output operating mode as this value is the same regardless of
|
||||||
|
whether the regulator is enabled or disabled. A "status"
|
||||||
|
attribute may be available to determine the actual mode.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../min_microvolts
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
min_microvolts. This holds the minimum safe working regulator
|
||||||
|
output voltage setting for this domain measured in microvolts,
|
||||||
|
for regulators which support voltage constraints.
|
||||||
|
|
||||||
|
NOTE: this will return the string 'constraint not defined' if
|
||||||
|
the power domain has no min microvolts constraint defined by
|
||||||
|
platform code.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../max_microvolts
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
max_microvolts. This holds the maximum safe working regulator
|
||||||
|
output voltage setting for this domain measured in microvolts,
|
||||||
|
for regulators which support voltage constraints.
|
||||||
|
|
||||||
|
NOTE: this will return the string 'constraint not defined' if
|
||||||
|
the power domain has no max microvolts constraint defined by
|
||||||
|
platform code.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../min_microamps
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
min_microamps. This holds the minimum safe working regulator
|
||||||
|
output current limit setting for this domain measured in
|
||||||
|
microamps, for regulators which support current constraints.
|
||||||
|
|
||||||
|
NOTE: this will return the string 'constraint not defined' if
|
||||||
|
the power domain has no min microamps constraint defined by
|
||||||
|
platform code.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../max_microamps
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
max_microamps. This holds the maximum safe working regulator
|
||||||
|
output current limit setting for this domain measured in
|
||||||
|
microamps, for regulators which support current constraints.
|
||||||
|
|
||||||
|
NOTE: this will return the string 'constraint not defined' if
|
||||||
|
the power domain has no max microamps constraint defined by
|
||||||
|
platform code.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../name
|
||||||
|
Date: October 2008
|
||||||
|
KernelVersion: 2.6.28
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Each regulator directory will contain a field called
|
||||||
|
name. This holds a string identifying the regulator for
|
||||||
|
display purposes.
|
||||||
|
|
||||||
|
NOTE: this will be empty if no suitable name is provided
|
||||||
|
by platform or regulator drivers.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../num_users
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Each regulator directory will contain a field called
|
||||||
|
num_users. This holds the number of consumer devices that
|
||||||
|
have called regulator_enable() on this regulator.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../requested_microamps
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
requested_microamps. This holds the total requested load
|
||||||
|
current in microamps for this regulator from all its consumer
|
||||||
|
devices.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../parent
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a link called parent.
|
||||||
|
This points to the parent or supply regulator if one exists.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_mem_microvolts
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_mem_microvolts. This holds the regulator output
|
||||||
|
voltage setting for this domain measured in microvolts when
|
||||||
|
the system is suspended to memory, for voltage regulators
|
||||||
|
implementing suspend voltage configuration constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_disk_microvolts
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_disk_microvolts. This holds the regulator output
|
||||||
|
voltage setting for this domain measured in microvolts when
|
||||||
|
the system is suspended to disk, for voltage regulators
|
||||||
|
implementing suspend voltage configuration constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_standby_microvolts
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_standby_microvolts. This holds the regulator output
|
||||||
|
voltage setting for this domain measured in microvolts when
|
||||||
|
the system is suspended to standby, for voltage regulators
|
||||||
|
implementing suspend voltage configuration constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_mem_mode
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_mem_mode. This holds the regulator operating mode
|
||||||
|
setting for this domain when the system is suspended to
|
||||||
|
memory, for regulators implementing suspend mode
|
||||||
|
configuration constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_disk_mode
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_disk_mode. This holds the regulator operating mode
|
||||||
|
setting for this domain when the system is suspended to disk,
|
||||||
|
for regulators implementing suspend mode configuration
|
||||||
|
constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_standby_mode
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_standby_mode. This holds the regulator operating mode
|
||||||
|
setting for this domain when the system is suspended to
|
||||||
|
standby, for regulators implementing suspend mode
|
||||||
|
configuration constraints.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_mem_state
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_mem_state. This holds the regulator operating state
|
||||||
|
when suspended to memory, for regulators implementing suspend
|
||||||
|
configuration constraints.
|
||||||
|
|
||||||
|
This will be one of the same strings reported by
|
||||||
|
the "state" attribute.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_disk_state
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_disk_state. This holds the regulator operating state
|
||||||
|
when suspended to disk, for regulators implementing
|
||||||
|
suspend configuration constraints.
|
||||||
|
|
||||||
|
This will be one of the same strings reported by
|
||||||
|
the "state" attribute.
|
||||||
|
|
||||||
|
What: /sys/class/regulator/.../suspend_standby_state
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Liam Girdwood <lrg@slimlogic.co.uk>
|
||||||
|
Description:
|
||||||
|
Some regulator directories will contain a field called
|
||||||
|
suspend_standby_state. This holds the regulator operating
|
||||||
|
state when suspended to standby, for regulators implementing
|
||||||
|
suspend configuration constraints.
|
||||||
|
|
||||||
|
This will be one of the same strings reported by
|
||||||
|
the "state" attribute.
|
|
@ -0,0 +1,146 @@
|
||||||
|
What: /sys/class/uwb_rc
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Interfaces for WiMedia Ultra Wideband Common Radio
|
||||||
|
Platform (UWB) radio controllers.
|
||||||
|
|
||||||
|
Familiarity with the ECMA-368 'High Rate Ultra
|
||||||
|
Wideband MAC and PHY Specification' is assumed.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/beacon_timeout_ms
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Description:
|
||||||
|
If no beacons are received from a device for at least
|
||||||
|
this time, the device will be considered to have gone
|
||||||
|
and it will be removed. The default is 3 superframes
|
||||||
|
(~197 ms) as required by the specification.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
An individual UWB radio controller.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/beacon
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Write:
|
||||||
|
|
||||||
|
<channel>
|
||||||
|
|
||||||
|
to force a specific channel to be used when beaconing,
|
||||||
|
or, if <channel> is -1, to prohibit beaconing. If
|
||||||
|
<channel> is 0, then the default channel selection
|
||||||
|
algorithm will be used. Valid channels depends on the
|
||||||
|
radio controller's supported band groups.
|
||||||
|
|
||||||
|
Reading returns the currently active channel, or -1 if
|
||||||
|
the radio controller is not beaconing.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/scan
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Write:
|
||||||
|
|
||||||
|
<channel> <type> [<bpst offset>]
|
||||||
|
|
||||||
|
to start (or stop) scanning on a channel. <type> is one of:
|
||||||
|
0 - scan
|
||||||
|
1 - scan outside BP
|
||||||
|
2 - scan while inactive
|
||||||
|
3 - scanning disabled
|
||||||
|
4 - scan (with start time of <bpst offset>)
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/mac_address
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
The EUI-48, in colon-separated hex octets, for this
|
||||||
|
radio controller. A write will change the radio
|
||||||
|
controller's EUI-48 but only do so while the device is
|
||||||
|
not beaconing or scanning.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/wusbhc
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
A symlink to the device (if any) of the WUSB Host
|
||||||
|
Controller PAL using this radio controller.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
A neighbour UWB device that has either been detected
|
||||||
|
as part of a scan or is a member of the radio
|
||||||
|
controllers beacon group.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
The time (using the radio controllers internal 1 ms
|
||||||
|
interval superframe timer) of the last beacon from
|
||||||
|
this device was received.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/DevAddr
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
The current DevAddr of this device in colon separated
|
||||||
|
hex octets.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/EUI_48
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
|
||||||
|
The EUI-48 of this device in colon separated hex
|
||||||
|
octets.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/BPST
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/IEs
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
The latest IEs included in this device's beacon, in
|
||||||
|
space separated hex octets with one IE per line.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/LQE
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Link Quality Estimate - the Signal to Noise Ratio
|
||||||
|
(SNR) of all packets received from this device in dB.
|
||||||
|
This gives an estimate on a suitable PHY rate. Refer
|
||||||
|
to [ECMA-368] section 13.3 for more details.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/<EUI-48>/RSSI
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: linux-usb@vger.kernel.org
|
||||||
|
Description:
|
||||||
|
Received Signal Strength Indication - the strength of
|
||||||
|
the received signal in dB. LQE is a more useful
|
||||||
|
measure of the radio link quality.
|
|
@ -0,0 +1,25 @@
|
||||||
|
What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_chid
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
Write the CHID (16 space-separated hex octets) for this host controller.
|
||||||
|
This starts the host controller, allowing it to accept connection from
|
||||||
|
WUSB devices.
|
||||||
|
|
||||||
|
Set an all zero CHID to stop the host controller.
|
||||||
|
|
||||||
|
What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_trust_timeout
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
Devices that haven't sent a WUSB packet to the host
|
||||||
|
within 'wusb_trust_timeout' ms are considered to have
|
||||||
|
disconnected and are removed. The default value of
|
||||||
|
4000 ms is the value required by the WUSB
|
||||||
|
specification.
|
||||||
|
|
||||||
|
Since this relates to security (specifically, the
|
||||||
|
lifetime of PTKs and GTKs) it should not be changed
|
||||||
|
from the default.
|
|
@ -0,0 +1,20 @@
|
||||||
|
What: /sys/dev
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Dan Williams <dan.j.williams@intel.com>
|
||||||
|
Description: The /sys/dev tree provides a method to look up the sysfs
|
||||||
|
path for a device using the information returned from
|
||||||
|
stat(2). There are two directories, 'block' and 'char',
|
||||||
|
beneath /sys/dev containing symbolic links with names of
|
||||||
|
the form "<major>:<minor>". These links point to the
|
||||||
|
corresponding sysfs path for the given device.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
$ readlink /sys/dev/block/8:32
|
||||||
|
../../block/sdc
|
||||||
|
|
||||||
|
Entries in /sys/dev/char and /sys/dev/block will be
|
||||||
|
dynamically created and destroyed as devices enter and
|
||||||
|
leave the system.
|
||||||
|
|
||||||
|
Users: mdadm <linux-raid@vger.kernel.org>
|
|
@ -0,0 +1,25 @@
|
||||||
|
What: /sys/devices
|
||||||
|
Date: February 2006
|
||||||
|
Contact: Greg Kroah-Hartman <gregkh@suse.de>
|
||||||
|
Description:
|
||||||
|
The /sys/devices tree contains a snapshot of the
|
||||||
|
internal state of the kernel device tree. Devices will
|
||||||
|
be added and removed dynamically as the machine runs,
|
||||||
|
and between different kernel versions, the layout of the
|
||||||
|
devices within this tree will change.
|
||||||
|
|
||||||
|
Please do not rely on the format of this tree because of
|
||||||
|
this. If a program wishes to find different things in
|
||||||
|
the tree, please use the /sys/class structure and rely
|
||||||
|
on the symlinks there to point to the proper location
|
||||||
|
within the /sys/devices tree of the individual devices.
|
||||||
|
Or rely on the uevent messages to notify programs of
|
||||||
|
devices being added and removed from this tree to find
|
||||||
|
the location of those devices.
|
||||||
|
|
||||||
|
Note that sometimes not all devices along the directory
|
||||||
|
chain will have emitted uevent messages, so userspace
|
||||||
|
programs must be able to handle such occurrences.
|
||||||
|
|
||||||
|
Users:
|
||||||
|
udev <linux-hotplug-devel@lists.sourceforge.net>
|
|
@ -0,0 +1,73 @@
|
||||||
|
What: /sys/devices/system/memory
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Badari Pulavarty <pbadari@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The /sys/devices/system/memory contains a snapshot of the
|
||||||
|
internal state of the kernel memory blocks. Files could be
|
||||||
|
added or removed dynamically to represent hot-add/remove
|
||||||
|
operations.
|
||||||
|
Users: hotplug memory add/remove tools
|
||||||
|
https://w3.opensource.ibm.com/projects/powerpc-utils/
|
||||||
|
|
||||||
|
What: /sys/devices/system/memory/memoryX/removable
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Badari Pulavarty <pbadari@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The file /sys/devices/system/memory/memoryX/removable
|
||||||
|
indicates whether this memory block is removable or not.
|
||||||
|
This is useful for a user-level agent to determine
|
||||||
|
identify removable sections of the memory before attempting
|
||||||
|
potentially expensive hot-remove memory operation
|
||||||
|
Users: hotplug memory remove tools
|
||||||
|
https://w3.opensource.ibm.com/projects/powerpc-utils/
|
||||||
|
|
||||||
|
What: /sys/devices/system/memory/memoryX/phys_device
|
||||||
|
Date: September 2008
|
||||||
|
Contact: Badari Pulavarty <pbadari@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The file /sys/devices/system/memory/memoryX/phys_device
|
||||||
|
is read-only and is designed to show the name of physical
|
||||||
|
memory device. Implementation is currently incomplete.
|
||||||
|
|
||||||
|
What: /sys/devices/system/memory/memoryX/phys_index
|
||||||
|
Date: September 2008
|
||||||
|
Contact: Badari Pulavarty <pbadari@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The file /sys/devices/system/memory/memoryX/phys_index
|
||||||
|
is read-only and contains the section ID in hexadecimal
|
||||||
|
which is equivalent to decimal X contained in the
|
||||||
|
memory section directory name.
|
||||||
|
|
||||||
|
What: /sys/devices/system/memory/memoryX/state
|
||||||
|
Date: September 2008
|
||||||
|
Contact: Badari Pulavarty <pbadari@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
The file /sys/devices/system/memory/memoryX/state
|
||||||
|
is read-write. When read, it's contents show the
|
||||||
|
online/offline state of the memory section. When written,
|
||||||
|
root can toggle the the online/offline state of a removable
|
||||||
|
memory section (see removable file description above)
|
||||||
|
using the following commands.
|
||||||
|
# echo online > /sys/devices/system/memory/memoryX/state
|
||||||
|
# echo offline > /sys/devices/system/memory/memoryX/state
|
||||||
|
|
||||||
|
For example, if /sys/devices/system/memory/memory22/removable
|
||||||
|
contains a value of 1 and
|
||||||
|
/sys/devices/system/memory/memory22/state contains the
|
||||||
|
string "online" the following command can be executed by
|
||||||
|
by root to offline that section.
|
||||||
|
# echo offline > /sys/devices/system/memory/memory22/state
|
||||||
|
Users: hotplug memory remove tools
|
||||||
|
https://w3.opensource.ibm.com/projects/powerpc-utils/
|
||||||
|
|
||||||
|
What: /sys/devices/system/node/nodeX/memoryY
|
||||||
|
Date: September 2008
|
||||||
|
Contact: Gary Hade <garyhade@us.ibm.com>
|
||||||
|
Description:
|
||||||
|
When CONFIG_NUMA is enabled
|
||||||
|
/sys/devices/system/node/nodeX/memoryY is a symbolic link that
|
||||||
|
points to the corresponding /sys/devices/system/memory/memoryY
|
||||||
|
memory section directory. For example, the following symbolic
|
||||||
|
link is created for memory section 9 on node0.
|
||||||
|
/sys/devices/system/node/node0/memory9 -> ../../memory/memory9
|
||||||
|
|
|
@ -0,0 +1,156 @@
|
||||||
|
What: /sys/devices/system/cpu/
|
||||||
|
Date: pre-git history
|
||||||
|
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||||
|
Description:
|
||||||
|
A collection of both global and individual CPU attributes
|
||||||
|
|
||||||
|
Individual CPU attributes are contained in subdirectories
|
||||||
|
named by the kernel's logical CPU number, e.g.:
|
||||||
|
|
||||||
|
/sys/devices/system/cpu/cpu#/
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/sched_mc_power_savings
|
||||||
|
/sys/devices/system/cpu/sched_smt_power_savings
|
||||||
|
Date: June 2006
|
||||||
|
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||||
|
Description: Discover and adjust the kernel's multi-core scheduler support.
|
||||||
|
|
||||||
|
Possible values are:
|
||||||
|
|
||||||
|
0 - No power saving load balance (default value)
|
||||||
|
1 - Fill one thread/core/package first for long running threads
|
||||||
|
2 - Also bias task wakeups to semi-idle cpu package for power
|
||||||
|
savings
|
||||||
|
|
||||||
|
sched_mc_power_savings is dependent upon SCHED_MC, which is
|
||||||
|
itself architecture dependent.
|
||||||
|
|
||||||
|
sched_smt_power_savings is dependent upon SCHED_SMT, which
|
||||||
|
is itself architecture dependent.
|
||||||
|
|
||||||
|
The two files are independent of each other. It is possible
|
||||||
|
that one file may be present without the other.
|
||||||
|
|
||||||
|
Introduced by git commit 5c45bf27.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/kernel_max
|
||||||
|
/sys/devices/system/cpu/offline
|
||||||
|
/sys/devices/system/cpu/online
|
||||||
|
/sys/devices/system/cpu/possible
|
||||||
|
/sys/devices/system/cpu/present
|
||||||
|
Date: December 2008
|
||||||
|
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||||
|
Description: CPU topology files that describe kernel limits related to
|
||||||
|
hotplug. Briefly:
|
||||||
|
|
||||||
|
kernel_max: the maximum cpu index allowed by the kernel
|
||||||
|
configuration.
|
||||||
|
|
||||||
|
offline: cpus that are not online because they have been
|
||||||
|
HOTPLUGGED off or exceed the limit of cpus allowed by the
|
||||||
|
kernel configuration (kernel_max above).
|
||||||
|
|
||||||
|
online: cpus that are online and being scheduled.
|
||||||
|
|
||||||
|
possible: cpus that have been allocated resources and can be
|
||||||
|
brought online if they are present.
|
||||||
|
|
||||||
|
present: cpus that have been identified as being present in
|
||||||
|
the system.
|
||||||
|
|
||||||
|
See Documentation/cputopology.txt for more information.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/cpu#/node
|
||||||
|
Date: October 2009
|
||||||
|
Contact: Linux memory management mailing list <linux-mm@kvack.org>
|
||||||
|
Description: Discover NUMA node a CPU belongs to
|
||||||
|
|
||||||
|
When CONFIG_NUMA is enabled, a symbolic link that points
|
||||||
|
to the corresponding NUMA node directory.
|
||||||
|
|
||||||
|
For example, the following symlink is created for cpu42
|
||||||
|
in NUMA node 2:
|
||||||
|
|
||||||
|
/sys/devices/system/cpu/cpu42/node2 -> ../../node/node2
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/cpu#/topology/core_id
|
||||||
|
/sys/devices/system/cpu/cpu#/topology/core_siblings
|
||||||
|
/sys/devices/system/cpu/cpu#/topology/core_siblings_list
|
||||||
|
/sys/devices/system/cpu/cpu#/topology/physical_package_id
|
||||||
|
/sys/devices/system/cpu/cpu#/topology/thread_siblings
|
||||||
|
/sys/devices/system/cpu/cpu#/topology/thread_siblings_list
|
||||||
|
Date: December 2008
|
||||||
|
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||||
|
Description: CPU topology files that describe a logical CPU's relationship
|
||||||
|
to other cores and threads in the same physical package.
|
||||||
|
|
||||||
|
One cpu# directory is created per logical CPU in the system,
|
||||||
|
e.g. /sys/devices/system/cpu/cpu42/.
|
||||||
|
|
||||||
|
Briefly, the files above are:
|
||||||
|
|
||||||
|
core_id: the CPU core ID of cpu#. Typically it is the
|
||||||
|
hardware platform's identifier (rather than the kernel's).
|
||||||
|
The actual value is architecture and platform dependent.
|
||||||
|
|
||||||
|
core_siblings: internal kernel map of cpu#'s hardware threads
|
||||||
|
within the same physical_package_id.
|
||||||
|
|
||||||
|
core_siblings_list: human-readable list of the logical CPU
|
||||||
|
numbers within the same physical_package_id as cpu#.
|
||||||
|
|
||||||
|
physical_package_id: physical package id of cpu#. Typically
|
||||||
|
corresponds to a physical socket number, but the actual value
|
||||||
|
is architecture and platform dependent.
|
||||||
|
|
||||||
|
thread_siblings: internel kernel map of cpu#'s hardware
|
||||||
|
threads within the same core as cpu#
|
||||||
|
|
||||||
|
thread_siblings_list: human-readable list of cpu#'s hardware
|
||||||
|
threads within the same core as cpu#
|
||||||
|
|
||||||
|
See Documentation/cputopology.txt for more information.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/cpuidle/current_driver
|
||||||
|
/sys/devices/system/cpu/cpuidle/current_governer_ro
|
||||||
|
Date: September 2007
|
||||||
|
Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org>
|
||||||
|
Description: Discover cpuidle policy and mechanism
|
||||||
|
|
||||||
|
Various CPUs today support multiple idle levels that are
|
||||||
|
differentiated by varying exit latencies and power
|
||||||
|
consumption during idle.
|
||||||
|
|
||||||
|
Idle policy (governor) is differentiated from idle mechanism
|
||||||
|
(driver)
|
||||||
|
|
||||||
|
current_driver: displays current idle mechanism
|
||||||
|
|
||||||
|
current_governor_ro: displays current idle policy
|
||||||
|
|
||||||
|
See files in Documentation/cpuidle/ for more information.
|
||||||
|
|
||||||
|
|
||||||
|
What: /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: mark.langsdorf@amd.com
|
||||||
|
Description: These files exist in every cpu's cache index directories.
|
||||||
|
There are currently 2 cache_disable_# files in each
|
||||||
|
directory. Reading from these files on a supported
|
||||||
|
processor will return that cache disable index value
|
||||||
|
for that processor and node. Writing to one of these
|
||||||
|
files will cause the specificed cache index to be disabled.
|
||||||
|
|
||||||
|
Currently, only AMD Family 10h Processors support cache index
|
||||||
|
disable, and only for their L3 caches. See the BIOS and
|
||||||
|
Kernel Developer's Guide at
|
||||||
|
http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf
|
||||||
|
for formatting information and other details on the
|
||||||
|
cache index disable.
|
||||||
|
Users: joachim.deguara@amd.com
|
|
@ -0,0 +1,150 @@
|
||||||
|
What: /sys/firmware/acpi/interrupts/
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Len Brown <lenb@kernel.org>
|
||||||
|
Description:
|
||||||
|
All ACPI interrupts are handled via a single IRQ,
|
||||||
|
the System Control Interrupt (SCI), which appears
|
||||||
|
as "acpi" in /proc/interrupts.
|
||||||
|
|
||||||
|
However, one of the main functions of ACPI is to make
|
||||||
|
the platform understand random hardware without
|
||||||
|
special driver support. So while the SCI handles a few
|
||||||
|
well known (fixed feature) interrupts sources, such
|
||||||
|
as the power button, it can also handle a variable
|
||||||
|
number of a "General Purpose Events" (GPE).
|
||||||
|
|
||||||
|
A GPE vectors to a specified handler in AML, which
|
||||||
|
can do a anything the BIOS writer wants from
|
||||||
|
OS context. GPE 0x12, for example, would vector
|
||||||
|
to a level or edge handler called _L12 or _E12.
|
||||||
|
The handler may do its business and return.
|
||||||
|
Or the handler may send send a Notify event
|
||||||
|
to a Linux device driver registered on an ACPI device,
|
||||||
|
such as a battery, or a processor.
|
||||||
|
|
||||||
|
To figure out where all the SCI's are coming from,
|
||||||
|
/sys/firmware/acpi/interrupts contains a file listing
|
||||||
|
every possible source, and the count of how many
|
||||||
|
times it has triggered.
|
||||||
|
|
||||||
|
$ cd /sys/firmware/acpi/interrupts
|
||||||
|
$ grep . *
|
||||||
|
error: 0
|
||||||
|
ff_gbl_lock: 0 enable
|
||||||
|
ff_pmtimer: 0 invalid
|
||||||
|
ff_pwr_btn: 0 enable
|
||||||
|
ff_rt_clk: 2 disable
|
||||||
|
ff_slp_btn: 0 invalid
|
||||||
|
gpe00: 0 invalid
|
||||||
|
gpe01: 0 enable
|
||||||
|
gpe02: 108 enable
|
||||||
|
gpe03: 0 invalid
|
||||||
|
gpe04: 0 invalid
|
||||||
|
gpe05: 0 invalid
|
||||||
|
gpe06: 0 enable
|
||||||
|
gpe07: 0 enable
|
||||||
|
gpe08: 0 invalid
|
||||||
|
gpe09: 0 invalid
|
||||||
|
gpe0A: 0 invalid
|
||||||
|
gpe0B: 0 invalid
|
||||||
|
gpe0C: 0 invalid
|
||||||
|
gpe0D: 0 invalid
|
||||||
|
gpe0E: 0 invalid
|
||||||
|
gpe0F: 0 invalid
|
||||||
|
gpe10: 0 invalid
|
||||||
|
gpe11: 0 invalid
|
||||||
|
gpe12: 0 invalid
|
||||||
|
gpe13: 0 invalid
|
||||||
|
gpe14: 0 invalid
|
||||||
|
gpe15: 0 invalid
|
||||||
|
gpe16: 0 invalid
|
||||||
|
gpe17: 1084 enable
|
||||||
|
gpe18: 0 enable
|
||||||
|
gpe19: 0 invalid
|
||||||
|
gpe1A: 0 invalid
|
||||||
|
gpe1B: 0 invalid
|
||||||
|
gpe1C: 0 invalid
|
||||||
|
gpe1D: 0 invalid
|
||||||
|
gpe1E: 0 invalid
|
||||||
|
gpe1F: 0 invalid
|
||||||
|
gpe_all: 1192
|
||||||
|
sci: 1194
|
||||||
|
sci_not: 0
|
||||||
|
|
||||||
|
sci - The number of times the ACPI SCI
|
||||||
|
has been called and claimed an interrupt.
|
||||||
|
|
||||||
|
sci_not - The number of times the ACPI SCI
|
||||||
|
has been called and NOT claimed an interrupt.
|
||||||
|
|
||||||
|
gpe_all - count of SCI caused by GPEs.
|
||||||
|
|
||||||
|
gpeXX - count for individual GPE source
|
||||||
|
|
||||||
|
ff_gbl_lock - Global Lock
|
||||||
|
|
||||||
|
ff_pmtimer - PM Timer
|
||||||
|
|
||||||
|
ff_pwr_btn - Power Button
|
||||||
|
|
||||||
|
ff_rt_clk - Real Time Clock
|
||||||
|
|
||||||
|
ff_slp_btn - Sleep Button
|
||||||
|
|
||||||
|
error - an interrupt that can't be accounted for above.
|
||||||
|
|
||||||
|
invalid: it's either a GPE or a Fixed Event that
|
||||||
|
doesn't have an event handler.
|
||||||
|
|
||||||
|
disable: the GPE/Fixed Event is valid but disabled.
|
||||||
|
|
||||||
|
enable: the GPE/Fixed Event is valid and enabled.
|
||||||
|
|
||||||
|
Root has permission to clear any of these counters. Eg.
|
||||||
|
# echo 0 > gpe11
|
||||||
|
|
||||||
|
All counters can be cleared by clearing the total "sci":
|
||||||
|
# echo 0 > sci
|
||||||
|
|
||||||
|
None of these counters has an effect on the function
|
||||||
|
of the system, they are simply statistics.
|
||||||
|
|
||||||
|
Besides this, user can also write specific strings to these files
|
||||||
|
to enable/disable/clear ACPI interrupts in user space, which can be
|
||||||
|
used to debug some ACPI interrupt storm issues.
|
||||||
|
|
||||||
|
Note that only writting to VALID GPE/Fixed Event is allowed,
|
||||||
|
i.e. user can only change the status of runtime GPE and
|
||||||
|
Fixed Event with event handler installed.
|
||||||
|
|
||||||
|
Let's take power button fixed event for example, please kill acpid
|
||||||
|
and other user space applications so that the machine won't shutdown
|
||||||
|
when pressing the power button.
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
0 enabled
|
||||||
|
# press the power button for 3 times;
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
3 enabled
|
||||||
|
# echo disable > ff_pwr_btn
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
3 disabled
|
||||||
|
# press the power button for 3 times;
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
3 disabled
|
||||||
|
# echo enable > ff_pwr_btn
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
4 enabled
|
||||||
|
/*
|
||||||
|
* this is because the status bit is set even if the enable bit is cleared,
|
||||||
|
* and it triggers an ACPI fixed event when the enable bit is set again
|
||||||
|
*/
|
||||||
|
# press the power button for 3 times;
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
7 enabled
|
||||||
|
# echo disable > ff_pwr_btn
|
||||||
|
# press the power button for 3 times;
|
||||||
|
# echo clear > ff_pwr_btn /* clear the status bit */
|
||||||
|
# echo disable > ff_pwr_btn
|
||||||
|
# cat ff_pwr_btn
|
||||||
|
7 enabled
|
||||||
|
|
|
@ -0,0 +1,71 @@
|
||||||
|
What: /sys/firmware/memmap/
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Bernhard Walle <bernhard.walle@gmx.de>
|
||||||
|
Description:
|
||||||
|
On all platforms, the firmware provides a memory map which the
|
||||||
|
kernel reads. The resources from that memory map are registered
|
||||||
|
in the kernel resource tree and exposed to userspace via
|
||||||
|
/proc/iomem (together with other resources).
|
||||||
|
|
||||||
|
However, on most architectures that firmware-provided memory
|
||||||
|
map is modified afterwards by the kernel itself, either because
|
||||||
|
the kernel merges that memory map with other information or
|
||||||
|
just because the user overwrites that memory map via command
|
||||||
|
line.
|
||||||
|
|
||||||
|
kexec needs the raw firmware-provided memory map to setup the
|
||||||
|
parameter segment of the kernel that should be booted with
|
||||||
|
kexec. Also, the raw memory map is useful for debugging. For
|
||||||
|
that reason, /sys/firmware/memmap is an interface that provides
|
||||||
|
the raw memory map to userspace.
|
||||||
|
|
||||||
|
The structure is as follows: Under /sys/firmware/memmap there
|
||||||
|
are subdirectories with the number of the entry as their name:
|
||||||
|
|
||||||
|
/sys/firmware/memmap/0
|
||||||
|
/sys/firmware/memmap/1
|
||||||
|
/sys/firmware/memmap/2
|
||||||
|
/sys/firmware/memmap/3
|
||||||
|
...
|
||||||
|
|
||||||
|
The maximum depends on the number of memory map entries provided
|
||||||
|
by the firmware. The order is just the order that the firmware
|
||||||
|
provides.
|
||||||
|
|
||||||
|
Each directory contains three files:
|
||||||
|
|
||||||
|
start : The start address (as hexadecimal number with the
|
||||||
|
'0x' prefix).
|
||||||
|
end : The end address, inclusive (regardless whether the
|
||||||
|
firmware provides inclusive or exclusive ranges).
|
||||||
|
type : Type of the entry as string. See below for a list of
|
||||||
|
valid types.
|
||||||
|
|
||||||
|
So, for example:
|
||||||
|
|
||||||
|
/sys/firmware/memmap/0/start
|
||||||
|
/sys/firmware/memmap/0/end
|
||||||
|
/sys/firmware/memmap/0/type
|
||||||
|
/sys/firmware/memmap/1/start
|
||||||
|
...
|
||||||
|
|
||||||
|
Currently following types exist:
|
||||||
|
|
||||||
|
- System RAM
|
||||||
|
- ACPI Tables
|
||||||
|
- ACPI Non-volatile Storage
|
||||||
|
- reserved
|
||||||
|
|
||||||
|
Following shell snippet can be used to display that memory
|
||||||
|
map in a human-readable format:
|
||||||
|
|
||||||
|
-------------------- 8< ----------------------------------------
|
||||||
|
#!/bin/bash
|
||||||
|
cd /sys/firmware/memmap
|
||||||
|
for dir in * ; do
|
||||||
|
start=$(cat $dir/start)
|
||||||
|
end=$(cat $dir/end)
|
||||||
|
type=$(cat $dir/type)
|
||||||
|
printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type"
|
||||||
|
done
|
||||||
|
-------------------- >8 ----------------------------------------
|
|
@ -0,0 +1,27 @@
|
||||||
|
What: /sys/firmware/sgi_uv/
|
||||||
|
Date: August 2008
|
||||||
|
Contact: Russ Anderson <rja@sgi.com>
|
||||||
|
Description:
|
||||||
|
The /sys/firmware/sgi_uv directory contains information
|
||||||
|
about the SGI UV platform.
|
||||||
|
|
||||||
|
Under that directory are a number of files:
|
||||||
|
|
||||||
|
partition_id
|
||||||
|
coherence_id
|
||||||
|
|
||||||
|
The partition_id entry contains the partition id.
|
||||||
|
SGI UV systems can be partitioned into multiple physical
|
||||||
|
machines, which each partition running a unique copy
|
||||||
|
of the operating system. Each partition will have a unique
|
||||||
|
partition id. To display the partition id, use the command:
|
||||||
|
|
||||||
|
cat /sys/firmware/sgi_uv/partition_id
|
||||||
|
|
||||||
|
The coherence_id entry contains the coherence id.
|
||||||
|
A partitioned SGI UV system can have one or more coherence
|
||||||
|
domain. The coherence id indicates which coherence domain
|
||||||
|
this partition is in. To display the coherence id, use the
|
||||||
|
command:
|
||||||
|
|
||||||
|
cat /sys/firmware/sgi_uv/coherence_id
|
|
@ -0,0 +1,91 @@
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_stats
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
Controls whether the multiblock allocator should
|
||||||
|
collect statistics, which are shown during the unmount.
|
||||||
|
1 means to collect statistics, 0 means not to collect
|
||||||
|
statistics
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_group_prealloc
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
The multiblock allocator will round up allocation
|
||||||
|
requests to a multiple of this tuning parameter if the
|
||||||
|
stripe size is not set in the ext4 superblock
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_max_to_scan
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
The maximum number of extents the multiblock allocator
|
||||||
|
will search to find the best extent
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_min_to_scan
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
The minimum number of extents the multiblock allocator
|
||||||
|
will search to find the best extent
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_order2_req
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
Tuning parameter which controls the minimum size for
|
||||||
|
requests (as a power of 2) where the buddy cache is
|
||||||
|
used
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/mb_stream_req
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
Files which have fewer blocks than this tunable
|
||||||
|
parameter will have their blocks allocated out of a
|
||||||
|
block group specific preallocation pool, so that small
|
||||||
|
files are packed closely together. Each large file
|
||||||
|
will have its blocks allocated out of its own unique
|
||||||
|
preallocation pool.
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/inode_readahead
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
Tuning parameter which controls the maximum number of
|
||||||
|
inode table blocks that ext4's inode table readahead
|
||||||
|
algorithm will pre-read into the buffer cache
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/delayed_allocation_blocks
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
This file is read-only and shows the number of blocks
|
||||||
|
that are dirty in the page cache, but which do not
|
||||||
|
have their location in the filesystem allocated yet.
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/lifetime_write_kbytes
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
This file is read-only and shows the number of kilobytes
|
||||||
|
of data that have been written to this filesystem since it was
|
||||||
|
created.
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/session_write_kbytes
|
||||||
|
Date: March 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
This file is read-only and shows the number of
|
||||||
|
kilobytes of data that have been written to this
|
||||||
|
filesystem since it was mounted.
|
||||||
|
|
||||||
|
What: /sys/fs/ext4/<disk>/inode_goal
|
||||||
|
Date: June 2008
|
||||||
|
Contact: "Theodore Ts'o" <tytso@mit.edu>
|
||||||
|
Description:
|
||||||
|
Tuning parameter which (if non-zero) controls the goal
|
||||||
|
inode used by the inode allocator in p0reference to
|
||||||
|
all other allocation hueristics. This is intended for
|
||||||
|
debugging use only, and should be 0 on production
|
||||||
|
systems.
|
|
@ -0,0 +1,27 @@
|
||||||
|
What: /sys/class/gpio/
|
||||||
|
Date: July 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Brownell <dbrownell@users.sourceforge.net>
|
||||||
|
Description:
|
||||||
|
|
||||||
|
As a Kconfig option, individual GPIO signals may be accessed from
|
||||||
|
userspace. GPIOs are only made available to userspace by an explicit
|
||||||
|
"export" operation. If a given GPIO is not claimed for use by
|
||||||
|
kernel code, it may be exported by userspace (and unexported later).
|
||||||
|
Kernel code may export it for complete or partial access.
|
||||||
|
|
||||||
|
GPIOs are identified as they are inside the kernel, using integers in
|
||||||
|
the range 0..INT_MAX. See Documentation/gpio.txt for more information.
|
||||||
|
|
||||||
|
/sys/class/gpio
|
||||||
|
/export ... asks the kernel to export a GPIO to userspace
|
||||||
|
/unexport ... to return a GPIO to the kernel
|
||||||
|
/gpioN ... for each exported GPIO #N
|
||||||
|
/value ... always readable, writes fail for input GPIOs
|
||||||
|
/direction ... r/w as: in, out (default low); write: high, low
|
||||||
|
/edge ... r/w as: none, falling, rising, both
|
||||||
|
/gpiochipN ... for each gpiochip; #N is its first GPIO
|
||||||
|
/base ... (r/o) same as N
|
||||||
|
/label ... (r/o) descriptive, not necessarily unique
|
||||||
|
/ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1)
|
||||||
|
|
|
@ -0,0 +1,23 @@
|
||||||
|
What: /sys/firmware/ibft/initiator
|
||||||
|
Date: November 2007
|
||||||
|
Contact: Konrad Rzeszutek <ketuzsezr@darnok.org>
|
||||||
|
Description: The /sys/firmware/ibft/initiator directory will contain
|
||||||
|
files that expose the iSCSI Boot Firmware Table initiator data.
|
||||||
|
Usually this contains the Initiator name.
|
||||||
|
|
||||||
|
What: /sys/firmware/ibft/targetX
|
||||||
|
Date: November 2007
|
||||||
|
Contact: Konrad Rzeszutek <ketuzsezr@darnok.org>
|
||||||
|
Description: The /sys/firmware/ibft/targetX directory will contain
|
||||||
|
files that expose the iSCSI Boot Firmware Table target data.
|
||||||
|
Usually this contains the target's IP address, boot LUN,
|
||||||
|
target name, and what NIC it is associated with. It can also
|
||||||
|
contain the CHAP name (and password), the reverse CHAP
|
||||||
|
name (and password)
|
||||||
|
|
||||||
|
What: /sys/firmware/ibft/ethernetX
|
||||||
|
Date: November 2007
|
||||||
|
Contact: Konrad Rzeszutek <ketuzsezr@darnok.org>
|
||||||
|
Description: The /sys/firmware/ibft/ethernetX directory will contain
|
||||||
|
files that expose the iSCSI Boot Firmware Table NIC data.
|
||||||
|
This can this can the IP address, MAC, and gateway of the NIC.
|
|
@ -0,0 +1,6 @@
|
||||||
|
What: /sys/kernel/mm
|
||||||
|
Date: July 2008
|
||||||
|
Contact: Nishanth Aravamudan <nacc@us.ibm.com>, VM maintainers
|
||||||
|
Description:
|
||||||
|
/sys/kernel/mm/ should contain any and all VM
|
||||||
|
related information in /sys/kernel/.
|
|
@ -0,0 +1,15 @@
|
||||||
|
What: /sys/kernel/mm/hugepages/
|
||||||
|
Date: June 2008
|
||||||
|
Contact: Nishanth Aravamudan <nacc@us.ibm.com>, hugetlb maintainers
|
||||||
|
Description:
|
||||||
|
/sys/kernel/mm/hugepages/ contains a number of subdirectories
|
||||||
|
of the form hugepages-<size>kB, where <size> is the page size
|
||||||
|
of the hugepages supported by the kernel/CPU combination.
|
||||||
|
|
||||||
|
Under these directories are a number of files:
|
||||||
|
nr_hugepages
|
||||||
|
nr_overcommit_hugepages
|
||||||
|
free_hugepages
|
||||||
|
surplus_hugepages
|
||||||
|
resv_hugepages
|
||||||
|
See Documentation/vm/hugetlbpage.txt for details.
|
|
@ -0,0 +1,479 @@
|
||||||
|
What: /sys/kernel/slab
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The /sys/kernel/slab directory contains a snapshot of the
|
||||||
|
internal state of the SLUB allocator for each cache. Certain
|
||||||
|
files may be modified to change the behavior of the cache (and
|
||||||
|
any cache it aliases, if any).
|
||||||
|
Users: kernel memory tuning tools
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/aliases
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The aliases file is read-only and specifies how many caches
|
||||||
|
have merged into this cache.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/align
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The align file is read-only and specifies the cache's object
|
||||||
|
alignment in bytes.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_calls
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_calls file is read-only and lists the kernel code
|
||||||
|
locations from which allocations for this cache were performed.
|
||||||
|
The alloc_calls file only contains information if debugging is
|
||||||
|
enabled for that cache (see Documentation/vm/slub.txt).
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_fastpath
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_fastpath file is read-only and specifies how many
|
||||||
|
objects have been allocated using the fast path.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_from_partial
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_from_partial file is read-only and specifies how
|
||||||
|
many times a cpu slab has been full and it has been refilled
|
||||||
|
by using a slab from the list of partially used slabs.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_refill
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_refill file is read-only and specifies how many
|
||||||
|
times the per-cpu freelist was empty but there were objects
|
||||||
|
available as the result of remote cpu frees.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_slab
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_slab file is read-only and specifies how many times
|
||||||
|
a new slab had to be allocated from the page allocator.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/alloc_slowpath
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The alloc_slowpath file is read-only and specifies how many
|
||||||
|
objects have been allocated using the slow path because of a
|
||||||
|
refill or allocation from a partial or new slab.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/cache_dma
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The cache_dma file is read-only and specifies whether objects
|
||||||
|
are from ZONE_DMA.
|
||||||
|
Available when CONFIG_ZONE_DMA is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/cpu_slabs
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The cpu_slabs file is read-only and displays how many cpu slabs
|
||||||
|
are active and their NUMA locality.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/cpuslab_flush
|
||||||
|
Date: April 2009
|
||||||
|
KernelVersion: 2.6.31
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file cpuslab_flush is read-only and specifies how many
|
||||||
|
times a cache's cpu slabs have been flushed as the result of
|
||||||
|
destroying or shrinking a cache, a cpu going offline, or as
|
||||||
|
the result of forcing an allocation from a certain node.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/ctor
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The ctor file is read-only and specifies the cache's object
|
||||||
|
constructor function, which is invoked for each object when a
|
||||||
|
new slab is allocated.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/deactivate_empty
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file deactivate_empty is read-only and specifies how many
|
||||||
|
times an empty cpu slab was deactivated.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/deactivate_full
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file deactivate_full is read-only and specifies how many
|
||||||
|
times a full cpu slab was deactivated.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/deactivate_remote_frees
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file deactivate_remote_frees is read-only and specifies how
|
||||||
|
many times a cpu slab has been deactivated and contained free
|
||||||
|
objects that were freed remotely.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/deactivate_to_head
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file deactivate_to_head is read-only and specifies how
|
||||||
|
many times a partial cpu slab was deactivated and added to the
|
||||||
|
head of its node's partial list.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/deactivate_to_tail
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file deactivate_to_tail is read-only and specifies how
|
||||||
|
many times a partial cpu slab was deactivated and added to the
|
||||||
|
tail of its node's partial list.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/destroy_by_rcu
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The destroy_by_rcu file is read-only and specifies whether
|
||||||
|
slabs (not objects) are freed by rcu.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_add_partial
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file free_add_partial is read-only and specifies how many
|
||||||
|
times an object has been freed in a full slab so that it had to
|
||||||
|
added to its node's partial list.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_calls
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The free_calls file is read-only and lists the locations of
|
||||||
|
object frees if slab debugging is enabled (see
|
||||||
|
Documentation/vm/slub.txt).
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_fastpath
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The free_fastpath file is read-only and specifies how many
|
||||||
|
objects have been freed using the fast path because it was an
|
||||||
|
object from the cpu slab.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_frozen
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The free_frozen file is read-only and specifies how many
|
||||||
|
objects have been freed to a frozen slab (i.e. a remote cpu
|
||||||
|
slab).
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_remove_partial
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file free_remove_partial is read-only and specifies how
|
||||||
|
many times an object has been freed to a now-empty slab so
|
||||||
|
that it had to be removed from its node's partial list.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_slab
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The free_slab file is read-only and specifies how many times an
|
||||||
|
empty slab has been freed back to the page allocator.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/free_slowpath
|
||||||
|
Date: February 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The free_slowpath file is read-only and specifies how many
|
||||||
|
objects have been freed using the slow path (i.e. to a full or
|
||||||
|
partial slab).
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/hwcache_align
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The hwcache_align file is read-only and specifies whether
|
||||||
|
objects are aligned on cachelines.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/min_partial
|
||||||
|
Date: February 2009
|
||||||
|
KernelVersion: 2.6.30
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
David Rientjes <rientjes@google.com>
|
||||||
|
Description:
|
||||||
|
The min_partial file specifies how many empty slabs shall
|
||||||
|
remain on a node's partial list to avoid the overhead of
|
||||||
|
allocating new slabs. Such slabs may be reclaimed by utilizing
|
||||||
|
the shrink file.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/object_size
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The object_size file is read-only and specifies the cache's
|
||||||
|
object size.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/objects
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The objects file is read-only and displays how many objects are
|
||||||
|
active and from which nodes they are from.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/objects_partial
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The objects_partial file is read-only and displays how many
|
||||||
|
objects are on partial slabs and from which nodes they are
|
||||||
|
from.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/objs_per_slab
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file objs_per_slab is read-only and specifies how many
|
||||||
|
objects may be allocated from a single slab of the order
|
||||||
|
specified in /sys/kernel/slab/cache/order.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/order
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The order file specifies the page order at which new slabs are
|
||||||
|
allocated. It is writable and can be changed to increase the
|
||||||
|
number of objects per slab. If a slab cannot be allocated
|
||||||
|
because of fragmentation, SLUB will retry with the minimum order
|
||||||
|
possible depending on its characteristics.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/order_fallback
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file order_fallback is read-only and specifies how many
|
||||||
|
times an allocation of a new slab has not been possible at the
|
||||||
|
cache's order and instead fallen back to its minimum possible
|
||||||
|
order.
|
||||||
|
Available when CONFIG_SLUB_STATS is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/partial
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The partial file is read-only and displays how long many
|
||||||
|
partial slabs there are and how long each node's list is.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/poison
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The poison file specifies whether objects should be poisoned
|
||||||
|
when a new slab is allocated.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/reclaim_account
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The reclaim_account file specifies whether the cache's objects
|
||||||
|
are reclaimable (and grouped by their mobility).
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/red_zone
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The red_zone file specifies whether the cache's objects are red
|
||||||
|
zoned.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/remote_node_defrag_ratio
|
||||||
|
Date: January 2008
|
||||||
|
KernelVersion: 2.6.25
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The file remote_node_defrag_ratio specifies the percentage of
|
||||||
|
times SLUB will attempt to refill the cpu slab with a partial
|
||||||
|
slab from a remote node as opposed to allocating a new slab on
|
||||||
|
the local node. This reduces the amount of wasted memory over
|
||||||
|
the entire system but can be expensive.
|
||||||
|
Available when CONFIG_NUMA is enabled.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/sanity_checks
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The sanity_checks file specifies whether expensive checks
|
||||||
|
should be performed on free and, at minimum, enables double free
|
||||||
|
checks. Caches that enable sanity_checks cannot be merged with
|
||||||
|
caches that do not.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/shrink
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The shrink file is written when memory should be reclaimed from
|
||||||
|
a cache. Empty partial slabs are freed and the partial list is
|
||||||
|
sorted so the slabs with the fewest available objects are used
|
||||||
|
first.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/slab_size
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The slab_size file is read-only and specifies the object size
|
||||||
|
with metadata (debugging information and alignment) in bytes.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/slabs
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The slabs file is read-only and displays how long many slabs
|
||||||
|
there are (both cpu and partial) and from which nodes they are
|
||||||
|
from.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/store_user
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The store_user file specifies whether the location of
|
||||||
|
allocation or free should be tracked for a cache.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/total_objects
|
||||||
|
Date: April 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The total_objects file is read-only and displays how many total
|
||||||
|
objects a cache has and from which nodes they are from.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/trace
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
The trace file specifies whether object allocations and frees
|
||||||
|
should be traced.
|
||||||
|
|
||||||
|
What: /sys/kernel/slab/cache/validate
|
||||||
|
Date: May 2007
|
||||||
|
KernelVersion: 2.6.22
|
||||||
|
Contact: Pekka Enberg <penberg@cs.helsinki.fi>,
|
||||||
|
Christoph Lameter <cl@linux-foundation.org>
|
||||||
|
Description:
|
||||||
|
Writing to the validate file causes SLUB to traverse all of its
|
||||||
|
cache's objects and check the validity of metadata.
|
|
@ -0,0 +1,14 @@
|
||||||
|
What: /sys/kernel/uids/<uid>/cpu_shares
|
||||||
|
Date: December 2007
|
||||||
|
Contact: Dhaval Giani <dhaval@linux.vnet.ibm.com>
|
||||||
|
Srivatsa Vaddagiri <vatsa@linux.vnet.ibm.com>
|
||||||
|
Description:
|
||||||
|
The /sys/kernel/uids/<uid>/cpu_shares tunable is used
|
||||||
|
to set the cpu bandwidth a user is allowed. This is a
|
||||||
|
propotional value. What that means is that if there
|
||||||
|
are two users logged in, each with an equal number of
|
||||||
|
shares, then they will get equal CPU bandwidth. Another
|
||||||
|
example would be, if User A has shares = 1024 and user
|
||||||
|
B has shares = 2048, User B will get twice the CPU
|
||||||
|
bandwidth user A will. For more details refer
|
||||||
|
Documentation/scheduler/sched-design-CFS.txt
|
|
@ -0,0 +1,89 @@
|
||||||
|
What: /sys/fs/ocfs2/
|
||||||
|
Date: April 2008
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description:
|
||||||
|
The /sys/fs/ocfs2 directory contains knobs used by the
|
||||||
|
ocfs2-tools to interact with the filesystem.
|
||||||
|
|
||||||
|
What: /sys/fs/ocfs2/max_locking_protocol
|
||||||
|
Date: April 2008
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description:
|
||||||
|
The /sys/fs/ocfs2/max_locking_protocol file displays version
|
||||||
|
of ocfs2 locking supported by the filesystem. This version
|
||||||
|
covers how ocfs2 uses distributed locking between cluster
|
||||||
|
nodes.
|
||||||
|
|
||||||
|
The protocol version has a major and minor number. Two
|
||||||
|
cluster nodes can interoperate if they have an identical
|
||||||
|
major number and an overlapping minor number - thus,
|
||||||
|
a node with version 1.10 can interoperate with a node
|
||||||
|
sporting version 1.8, as long as both use the 1.8 protocol.
|
||||||
|
|
||||||
|
Reading from this file returns a single line, the major
|
||||||
|
number and minor number joined by a period, eg "1.10".
|
||||||
|
|
||||||
|
This file is read-only. The value is compiled into the
|
||||||
|
driver.
|
||||||
|
|
||||||
|
What: /sys/fs/ocfs2/loaded_cluster_plugins
|
||||||
|
Date: April 2008
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description:
|
||||||
|
The /sys/fs/ocfs2/loaded_cluster_plugins file describes
|
||||||
|
the available plugins to support ocfs2 cluster operation.
|
||||||
|
A cluster plugin is required to use ocfs2 in a cluster.
|
||||||
|
There are currently two available plugins:
|
||||||
|
|
||||||
|
* 'o2cb' - The classic o2cb cluster stack that ocfs2 has
|
||||||
|
used since its inception.
|
||||||
|
* 'user' - A plugin supporting userspace cluster software
|
||||||
|
in conjunction with fs/dlm.
|
||||||
|
|
||||||
|
Reading from this file returns the names of all loaded
|
||||||
|
plugins, one per line.
|
||||||
|
|
||||||
|
This file is read-only. Its contents may change as
|
||||||
|
plugins are loaded or removed.
|
||||||
|
|
||||||
|
What: /sys/fs/ocfs2/active_cluster_plugin
|
||||||
|
Date: April 2008
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description:
|
||||||
|
The /sys/fs/ocfs2/active_cluster_plugin displays which
|
||||||
|
cluster plugin is currently in use by the filesystem.
|
||||||
|
The active plugin will appear in the loaded_cluster_plugins
|
||||||
|
file as well. Only one plugin can be used at a time.
|
||||||
|
|
||||||
|
Reading from this file returns the name of the active plugin
|
||||||
|
on a single line.
|
||||||
|
|
||||||
|
This file is read-only. Which plugin is active depends on
|
||||||
|
the cluster stack in use. The contents may change
|
||||||
|
when all filesystems are unmounted and the cluster stack
|
||||||
|
is changed.
|
||||||
|
|
||||||
|
What: /sys/fs/ocfs2/cluster_stack
|
||||||
|
Date: April 2008
|
||||||
|
Contact: ocfs2-devel@oss.oracle.com
|
||||||
|
Description:
|
||||||
|
The /sys/fs/ocfs2/cluster_stack file contains the name
|
||||||
|
of current ocfs2 cluster stack. This value is set by
|
||||||
|
userspace tools when bringing the cluster stack online.
|
||||||
|
|
||||||
|
Cluster stack names are 4 characters in length.
|
||||||
|
|
||||||
|
When the 'o2cb' cluster stack is used, the 'o2cb' cluster
|
||||||
|
plugin is active. All other cluster stacks use the 'user'
|
||||||
|
cluster plugin.
|
||||||
|
|
||||||
|
Reading from this file returns the name of the current
|
||||||
|
cluster stack on a single line.
|
||||||
|
|
||||||
|
Writing a new stack name to this file changes the current
|
||||||
|
cluster stack unless there are mounted ocfs2 filesystems.
|
||||||
|
If there are mounted filesystems, attempts to change the
|
||||||
|
stack return an error.
|
||||||
|
|
||||||
|
Users:
|
||||||
|
ocfs2-tools <ocfs2-tools-devel@oss.oracle.com>
|
|
@ -0,0 +1,52 @@
|
||||||
|
What: /sys/devices/platform/asus-laptop/display
|
||||||
|
Date: January 2007
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
This file allows display switching. The value
|
||||||
|
is composed by 4 bits and defined as follow:
|
||||||
|
4321
|
||||||
|
|||`- LCD
|
||||||
|
||`-- CRT
|
||||||
|
|`--- TV
|
||||||
|
`---- DVI
|
||||||
|
Ex: - 0 (0000b) means no display
|
||||||
|
- 3 (0011b) CRT+LCD.
|
||||||
|
|
||||||
|
What: /sys/devices/platform/asus-laptop/gps
|
||||||
|
Date: January 2007
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Control the gps device. 1 means on, 0 means off.
|
||||||
|
Users: Lapsus
|
||||||
|
|
||||||
|
What: /sys/devices/platform/asus-laptop/ledd
|
||||||
|
Date: January 2007
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Some models like the W1N have a LED display that can be
|
||||||
|
used to display several informations.
|
||||||
|
To control the LED display, use the following :
|
||||||
|
echo 0x0T000DDD > /sys/devices/platform/asus-laptop/
|
||||||
|
where T control the 3 letters display, and DDD the 3 digits display.
|
||||||
|
The DDD table can be found in Documentation/laptops/asus-laptop.txt
|
||||||
|
|
||||||
|
What: /sys/devices/platform/asus-laptop/bluetooth
|
||||||
|
Date: January 2007
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Control the bluetooth device. 1 means on, 0 means off.
|
||||||
|
This may control the led, the device or both.
|
||||||
|
Users: Lapsus
|
||||||
|
|
||||||
|
What: /sys/devices/platform/asus-laptop/wlan
|
||||||
|
Date: January 2007
|
||||||
|
KernelVersion: 2.6.20
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Control the bluetooth device. 1 means on, 0 means off.
|
||||||
|
This may control the led, the device or both.
|
||||||
|
Users: Lapsus
|
|
@ -0,0 +1,50 @@
|
||||||
|
What: /sys/devices/platform/eeepc-laptop/disp
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
This file allows display switching.
|
||||||
|
- 1 = LCD
|
||||||
|
- 2 = CRT
|
||||||
|
- 3 = LCD+CRT
|
||||||
|
If you run X11, you should use xrandr instead.
|
||||||
|
|
||||||
|
What: /sys/devices/platform/eeepc-laptop/camera
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Control the camera. 1 means on, 0 means off.
|
||||||
|
|
||||||
|
What: /sys/devices/platform/eeepc-laptop/cardr
|
||||||
|
Date: May 2008
|
||||||
|
KernelVersion: 2.6.26
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Control the card reader. 1 means on, 0 means off.
|
||||||
|
|
||||||
|
What: /sys/devices/platform/eeepc-laptop/cpufv
|
||||||
|
Date: Jun 2009
|
||||||
|
KernelVersion: 2.6.31
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
Change CPU clock configuration.
|
||||||
|
On the Eee PC 1000H there are three available clock configuration:
|
||||||
|
* 0 -> Super Performance Mode
|
||||||
|
* 1 -> High Performance Mode
|
||||||
|
* 2 -> Power Saving Mode
|
||||||
|
On Eee PC 701 there is only 2 available clock configurations.
|
||||||
|
Available configuration are listed in available_cpufv file.
|
||||||
|
Reading this file will show the raw hexadecimal value which
|
||||||
|
is defined as follow:
|
||||||
|
| 8 bit | 8 bit |
|
||||||
|
| `---- Current mode
|
||||||
|
`------------ Availables modes
|
||||||
|
For example, 0x301 means: mode 1 selected, 3 available modes.
|
||||||
|
|
||||||
|
What: /sys/devices/platform/eeepc-laptop/available_cpufv
|
||||||
|
Date: Jun 2009
|
||||||
|
KernelVersion: 2.6.31
|
||||||
|
Contact: "Corentin Chary" <corentincj@iksaif.net>
|
||||||
|
Description:
|
||||||
|
List available cpufv modes.
|
|
@ -0,0 +1,103 @@
|
||||||
|
What: /sys/power/
|
||||||
|
Date: August 2006
|
||||||
|
Contact: Rafael J. Wysocki <rjw@sisk.pl>
|
||||||
|
Description:
|
||||||
|
The /sys/power directory will contain files that will
|
||||||
|
provide a unified interface to the power management
|
||||||
|
subsystem.
|
||||||
|
|
||||||
|
What: /sys/power/state
|
||||||
|
Date: August 2006
|
||||||
|
Contact: Rafael J. Wysocki <rjw@sisk.pl>
|
||||||
|
Description:
|
||||||
|
The /sys/power/state file controls the system power state.
|
||||||
|
Reading from this file returns what states are supported,
|
||||||
|
which is hard-coded to 'standby' (Power-On Suspend), 'mem'
|
||||||
|
(Suspend-to-RAM), and 'disk' (Suspend-to-Disk).
|
||||||
|
|
||||||
|
Writing to this file one of these strings causes the system to
|
||||||
|
transition into that state. Please see the file
|
||||||
|
Documentation/power/states.txt for a description of each of
|
||||||
|
these states.
|
||||||
|
|
||||||
|
What: /sys/power/disk
|
||||||
|
Date: September 2006
|
||||||
|
Contact: Rafael J. Wysocki <rjw@sisk.pl>
|
||||||
|
Description:
|
||||||
|
The /sys/power/disk file controls the operating mode of the
|
||||||
|
suspend-to-disk mechanism. Reading from this file returns
|
||||||
|
the name of the method by which the system will be put to
|
||||||
|
sleep on the next suspend. There are four methods supported:
|
||||||
|
'firmware' - means that the memory image will be saved to disk
|
||||||
|
by some firmware, in which case we also assume that the
|
||||||
|
firmware will handle the system suspend.
|
||||||
|
'platform' - the memory image will be saved by the kernel and
|
||||||
|
the system will be put to sleep by the platform driver (e.g.
|
||||||
|
ACPI or other PM registers).
|
||||||
|
'shutdown' - the memory image will be saved by the kernel and
|
||||||
|
the system will be powered off.
|
||||||
|
'reboot' - the memory image will be saved by the kernel and
|
||||||
|
the system will be rebooted.
|
||||||
|
|
||||||
|
Additionally, /sys/power/disk can be used to turn on one of the
|
||||||
|
two testing modes of the suspend-to-disk mechanism: 'testproc'
|
||||||
|
or 'test'. If the suspend-to-disk mechanism is in the
|
||||||
|
'testproc' mode, writing 'disk' to /sys/power/state will cause
|
||||||
|
the kernel to disable nonboot CPUs and freeze tasks, wait for 5
|
||||||
|
seconds, unfreeze tasks and enable nonboot CPUs. If it is in
|
||||||
|
the 'test' mode, writing 'disk' to /sys/power/state will cause
|
||||||
|
the kernel to disable nonboot CPUs and freeze tasks, shrink
|
||||||
|
memory, suspend devices, wait for 5 seconds, resume devices,
|
||||||
|
unfreeze tasks and enable nonboot CPUs. Then, we are able to
|
||||||
|
look in the log messages and work out, for example, which code
|
||||||
|
is being slow and which device drivers are misbehaving.
|
||||||
|
|
||||||
|
The suspend-to-disk method may be chosen by writing to this
|
||||||
|
file one of the accepted strings:
|
||||||
|
|
||||||
|
'firmware'
|
||||||
|
'platform'
|
||||||
|
'shutdown'
|
||||||
|
'reboot'
|
||||||
|
'testproc'
|
||||||
|
'test'
|
||||||
|
|
||||||
|
It will only change to 'firmware' or 'platform' if the system
|
||||||
|
supports that.
|
||||||
|
|
||||||
|
What: /sys/power/image_size
|
||||||
|
Date: August 2006
|
||||||
|
Contact: Rafael J. Wysocki <rjw@sisk.pl>
|
||||||
|
Description:
|
||||||
|
The /sys/power/image_size file controls the size of the image
|
||||||
|
created by the suspend-to-disk mechanism. It can be written a
|
||||||
|
string representing a non-negative integer that will be used
|
||||||
|
as an upper limit of the image size, in bytes. The kernel's
|
||||||
|
suspend-to-disk code will do its best to ensure the image size
|
||||||
|
will not exceed this number. However, if it turns out to be
|
||||||
|
impossible, the kernel will try to suspend anyway using the
|
||||||
|
smallest image possible. In particular, if "0" is written to
|
||||||
|
this file, the suspend image will be as small as possible.
|
||||||
|
|
||||||
|
Reading from this file will display the current image size
|
||||||
|
limit, which is set to 500 MB by default.
|
||||||
|
|
||||||
|
What: /sys/power/pm_trace
|
||||||
|
Date: August 2006
|
||||||
|
Contact: Rafael J. Wysocki <rjw@sisk.pl>
|
||||||
|
Description:
|
||||||
|
The /sys/power/pm_trace file controls the code which saves the
|
||||||
|
last PM event point in the RTC across reboots, so that you can
|
||||||
|
debug a machine that just hangs during suspend (or more
|
||||||
|
commonly, during resume). Namely, the RTC is only used to save
|
||||||
|
the last PM event point if this file contains '1'. Initially
|
||||||
|
it contains '0' which may be changed to '1' by writing a
|
||||||
|
string representing a nonzero integer into it.
|
||||||
|
|
||||||
|
To use this debugging feature you should attempt to suspend
|
||||||
|
the machine, then reboot it and run
|
||||||
|
|
||||||
|
dmesg -s 1000000 | grep 'hash matches'
|
||||||
|
|
||||||
|
CAUTION: Using it will cause your machine's real-time (CMOS)
|
||||||
|
clock to be set to a random invalid time after a resume.
|
|
@ -0,0 +1,73 @@
|
||||||
|
What: /sys/class/pps/
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ directory will contain files and
|
||||||
|
directories that will provide a unified interface to
|
||||||
|
the PPS sources.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/ directory is related to X-th
|
||||||
|
PPS source into the system. Each directory will
|
||||||
|
contain files to manage and control its PPS source.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/assert
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/assert file reports the assert events
|
||||||
|
and the assert sequence number of the X-th source in the form:
|
||||||
|
|
||||||
|
<secs>.<nsec>#<sequence>
|
||||||
|
|
||||||
|
If the source has no assert events the content of this file
|
||||||
|
is empty.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/clear
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/clear file reports the clear events
|
||||||
|
and the clear sequence number of the X-th source in the form:
|
||||||
|
|
||||||
|
<secs>.<nsec>#<sequence>
|
||||||
|
|
||||||
|
If the source has no clear events the content of this file
|
||||||
|
is empty.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/mode
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/mode file reports the functioning
|
||||||
|
mode of the X-th source in hexadecimal encoding.
|
||||||
|
|
||||||
|
Please, refer to linux/include/linux/pps.h for further
|
||||||
|
info.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/echo
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/echo file reports if the X-th does
|
||||||
|
or does not support an "echo" function.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/name
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/name file reports the name of the
|
||||||
|
X-th source.
|
||||||
|
|
||||||
|
What: /sys/class/pps/ppsX/path
|
||||||
|
Date: February 2008
|
||||||
|
Contact: Rodolfo Giometti <giometti@linux.it>
|
||||||
|
Description:
|
||||||
|
The /sys/class/pps/ppsX/path file reports the path name of
|
||||||
|
the device connected with the X-th source.
|
||||||
|
|
||||||
|
If the source is not connected with any device the content
|
||||||
|
of this file is empty.
|
|
@ -0,0 +1,13 @@
|
||||||
|
What: /sys/kernel/profile
|
||||||
|
Date: September 2008
|
||||||
|
Contact: Dave Hansen <dave@linux.vnet.ibm.com>
|
||||||
|
Description:
|
||||||
|
/sys/kernel/profile is the runtime equivalent
|
||||||
|
of the boot-time profile= option.
|
||||||
|
|
||||||
|
You can get the same effect running:
|
||||||
|
|
||||||
|
echo 2 > /sys/kernel/profile
|
||||||
|
|
||||||
|
as you would by issuing profile=2 on the boot
|
||||||
|
command line.
|
|
@ -0,0 +1,100 @@
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_*
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
Various files for managing Cable Based Association of
|
||||||
|
(wireless) USB devices.
|
||||||
|
|
||||||
|
The sequence of operations should be:
|
||||||
|
|
||||||
|
1. Device is plugged in.
|
||||||
|
|
||||||
|
2. The connection manager (CM) sees a device with CBA capability.
|
||||||
|
(the wusb_chid etc. files in /sys/devices/blah/OURDEVICE).
|
||||||
|
|
||||||
|
3. The CM writes the host name, supported band groups,
|
||||||
|
and the CHID (host ID) into the wusb_host_name,
|
||||||
|
wusb_host_band_groups and wusb_chid files. These
|
||||||
|
get sent to the device and the CDID (if any) for
|
||||||
|
this host is requested.
|
||||||
|
|
||||||
|
4. The CM can verify that the device's supported band
|
||||||
|
groups (wusb_device_band_groups) are compatible
|
||||||
|
with the host.
|
||||||
|
|
||||||
|
5. The CM reads the wusb_cdid file.
|
||||||
|
|
||||||
|
6. The CM looks it up its database.
|
||||||
|
|
||||||
|
- If it has a matching CHID,CDID entry, the device
|
||||||
|
has been authorized before and nothing further
|
||||||
|
needs to be done.
|
||||||
|
|
||||||
|
- If the CDID is zero (or the CM doesn't find a
|
||||||
|
matching CDID in its database), the device is
|
||||||
|
assumed to be not known. The CM may associate
|
||||||
|
the host with device by: writing a randomly
|
||||||
|
generated CDID to wusb_cdid and then a random CK
|
||||||
|
to wusb_ck (this uploads the new CC to the
|
||||||
|
device).
|
||||||
|
|
||||||
|
CMD may choose to prompt the user before
|
||||||
|
associating with a new device.
|
||||||
|
|
||||||
|
7. Device is unplugged.
|
||||||
|
|
||||||
|
References:
|
||||||
|
[WUSB-AM] Association Models Supplement to the
|
||||||
|
Certified Wireless Universal Serial Bus
|
||||||
|
Specification, version 1.0.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_chid
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The CHID of the host formatted as 16 space-separated
|
||||||
|
hex octets.
|
||||||
|
|
||||||
|
Writes fetches device's supported band groups and the
|
||||||
|
the CDID for any existing association with this host.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_name
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
A friendly name for the host as a UTF-8 encoded string.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_host_band_groups
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The band groups supported by the host, in the format
|
||||||
|
defined in [WUSB-AM].
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_device_band_groups
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The band groups supported by the device, in the format
|
||||||
|
defined in [WUSB-AM].
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_cdid
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
The device's CDID formatted as 16 space-separated hex
|
||||||
|
octets.
|
||||||
|
|
||||||
|
What: /sys/bus/usb/drivers/wusb_cbaf/.../wusb_ck
|
||||||
|
Date: August 2008
|
||||||
|
KernelVersion: 2.6.27
|
||||||
|
Contact: David Vrabel <david.vrabel@csr.com>
|
||||||
|
Description:
|
||||||
|
Write 16 space-separated random, hex octets to
|
||||||
|
associate with the device.
|
|
@ -0,0 +1,246 @@
|
||||||
|
Table of contents
|
||||||
|
=================
|
||||||
|
|
||||||
|
Last updated: 20 December 2005
|
||||||
|
|
||||||
|
Contents
|
||||||
|
========
|
||||||
|
|
||||||
|
- Introduction
|
||||||
|
- Devices not appearing
|
||||||
|
- Finding patch that caused a bug
|
||||||
|
-- Finding using git-bisect
|
||||||
|
-- Finding it the old way
|
||||||
|
- Fixing the bug
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
Always try the latest kernel from kernel.org and build from source. If you are
|
||||||
|
not confident in doing that please report the bug to your distribution vendor
|
||||||
|
instead of to a kernel developer.
|
||||||
|
|
||||||
|
Finding bugs is not always easy. Have a go though. If you can't find it don't
|
||||||
|
give up. Report as much as you have found to the relevant maintainer. See
|
||||||
|
MAINTAINERS for who that is for the subsystem you have worked on.
|
||||||
|
|
||||||
|
Before you submit a bug report read REPORTING-BUGS.
|
||||||
|
|
||||||
|
Devices not appearing
|
||||||
|
=====================
|
||||||
|
|
||||||
|
Often this is caused by udev. Check that first before blaming it on the
|
||||||
|
kernel.
|
||||||
|
|
||||||
|
Finding patch that caused a bug
|
||||||
|
===============================
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Finding using git-bisect
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Using the provided tools with git makes finding bugs easy provided the bug is
|
||||||
|
reproducible.
|
||||||
|
|
||||||
|
Steps to do it:
|
||||||
|
- start using git for the kernel source
|
||||||
|
- read the man page for git-bisect
|
||||||
|
- have fun
|
||||||
|
|
||||||
|
Finding it the old way
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)]
|
||||||
|
|
||||||
|
This is how to track down a bug if you know nothing about kernel hacking.
|
||||||
|
It's a brute force approach but it works pretty well.
|
||||||
|
|
||||||
|
You need:
|
||||||
|
|
||||||
|
. A reproducible bug - it has to happen predictably (sorry)
|
||||||
|
. All the kernel tar files from a revision that worked to the
|
||||||
|
revision that doesn't
|
||||||
|
|
||||||
|
You will then do:
|
||||||
|
|
||||||
|
. Rebuild a revision that you believe works, install, and verify that.
|
||||||
|
. Do a binary search over the kernels to figure out which one
|
||||||
|
introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but
|
||||||
|
you know that 1.3.69 does. Pick a kernel in the middle and build
|
||||||
|
that, like 1.3.50. Build & test; if it works, pick the mid point
|
||||||
|
between .50 and .69, else the mid point between .28 and .50.
|
||||||
|
. You'll narrow it down to the kernel that introduced the bug. You
|
||||||
|
can probably do better than this but it gets tricky.
|
||||||
|
|
||||||
|
. Narrow it down to a subdirectory
|
||||||
|
|
||||||
|
- Copy kernel that works into "test". Let's say that 3.62 works,
|
||||||
|
but 3.63 doesn't. So you diff -r those two kernels and come
|
||||||
|
up with a list of directories that changed. For each of those
|
||||||
|
directories:
|
||||||
|
|
||||||
|
Copy the non-working directory next to the working directory
|
||||||
|
as "dir.63".
|
||||||
|
One directory at time, try moving the working directory to
|
||||||
|
"dir.62" and mv dir.63 dir"time, try
|
||||||
|
|
||||||
|
mv dir dir.62
|
||||||
|
mv dir.63 dir
|
||||||
|
find dir -name '*.[oa]' -print | xargs rm -f
|
||||||
|
|
||||||
|
And then rebuild and retest. Assuming that all related
|
||||||
|
changes were contained in the sub directory, this should
|
||||||
|
isolate the change to a directory.
|
||||||
|
|
||||||
|
Problems: changes in header files may have occurred; I've
|
||||||
|
found in my case that they were self explanatory - you may
|
||||||
|
or may not want to give up when that happens.
|
||||||
|
|
||||||
|
. Narrow it down to a file
|
||||||
|
|
||||||
|
- You can apply the same technique to each file in the directory,
|
||||||
|
hoping that the changes in that file are self contained.
|
||||||
|
|
||||||
|
. Narrow it down to a routine
|
||||||
|
|
||||||
|
- You can take the old file and the new file and manually create
|
||||||
|
a merged file that has
|
||||||
|
|
||||||
|
#ifdef VER62
|
||||||
|
routine()
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
#else
|
||||||
|
routine()
|
||||||
|
{
|
||||||
|
...
|
||||||
|
}
|
||||||
|
#endif
|
||||||
|
|
||||||
|
And then walk through that file, one routine at a time and
|
||||||
|
prefix it with
|
||||||
|
|
||||||
|
#define VER62
|
||||||
|
/* both routines here */
|
||||||
|
#undef VER62
|
||||||
|
|
||||||
|
Then recompile, retest, move the ifdefs until you find the one
|
||||||
|
that makes the difference.
|
||||||
|
|
||||||
|
Finally, you take all the info that you have, kernel revisions, bug
|
||||||
|
description, the extent to which you have narrowed it down, and pass
|
||||||
|
that off to whomever you believe is the maintainer of that section.
|
||||||
|
A post to linux.dev.kernel isn't such a bad idea if you've done some
|
||||||
|
work to narrow it down.
|
||||||
|
|
||||||
|
If you get it down to a routine, you'll probably get a fix in 24 hours.
|
||||||
|
|
||||||
|
My apologies to Linus and the other kernel hackers for describing this
|
||||||
|
brute force approach, it's hardly what a kernel hacker would do. However,
|
||||||
|
it does work and it lets non-hackers help fix bugs. And it is cool
|
||||||
|
because Linux snapshots will let you do this - something that you can't
|
||||||
|
do with vendor supplied releases.
|
||||||
|
|
||||||
|
Fixing the bug
|
||||||
|
==============
|
||||||
|
|
||||||
|
Nobody is going to tell you how to fix bugs. Seriously. You need to work it
|
||||||
|
out. But below are some hints on how to use the tools.
|
||||||
|
|
||||||
|
To debug a kernel, use objdump and look for the hex offset from the crash
|
||||||
|
output to find the valid line of code/assembler. Without debug symbols, you
|
||||||
|
will see the assembler code for the routine shown, but if your kernel has
|
||||||
|
debug symbols the C code will also be available. (Debug symbols can be enabled
|
||||||
|
in the kernel hacking menu of the menu configuration.) For example:
|
||||||
|
|
||||||
|
objdump -r -S -l --disassemble net/dccp/ipv4.o
|
||||||
|
|
||||||
|
NB.: you need to be at the top level of the kernel tree for this to pick up
|
||||||
|
your C files.
|
||||||
|
|
||||||
|
If you don't have access to the code you can also debug on some crash dumps
|
||||||
|
e.g. crash dump output as shown by Dave Miller.
|
||||||
|
|
||||||
|
> EIP is at ip_queue_xmit+0x14/0x4c0
|
||||||
|
> ...
|
||||||
|
> Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00
|
||||||
|
> 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08
|
||||||
|
> <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85
|
||||||
|
>
|
||||||
|
> Put the bytes into a "foo.s" file like this:
|
||||||
|
>
|
||||||
|
> .text
|
||||||
|
> .globl foo
|
||||||
|
> foo:
|
||||||
|
> .byte .... /* bytes from Code: part of OOPS dump */
|
||||||
|
>
|
||||||
|
> Compile it with "gcc -c -o foo.o foo.s" then look at the output of
|
||||||
|
> "objdump --disassemble foo.o".
|
||||||
|
>
|
||||||
|
> Output:
|
||||||
|
>
|
||||||
|
> ip_queue_xmit:
|
||||||
|
> push %ebp
|
||||||
|
> push %edi
|
||||||
|
> push %esi
|
||||||
|
> push %ebx
|
||||||
|
> sub $0xbc, %esp
|
||||||
|
> mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb)
|
||||||
|
> mov 0x8(%ebp), %ebx ! %ebx = skb->sk
|
||||||
|
> mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt
|
||||||
|
|
||||||
|
In addition, you can use GDB to figure out the exact file and line
|
||||||
|
number of the OOPS from the vmlinux file. If you have
|
||||||
|
CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the
|
||||||
|
OOPS:
|
||||||
|
|
||||||
|
EIP: 0060:[<c021e50e>] Not tainted VLI
|
||||||
|
|
||||||
|
And use GDB to translate that to human-readable form:
|
||||||
|
|
||||||
|
gdb vmlinux
|
||||||
|
(gdb) l *0xc021e50e
|
||||||
|
|
||||||
|
If you don't have CONFIG_DEBUG_INFO enabled, you use the function
|
||||||
|
offset from the OOPS:
|
||||||
|
|
||||||
|
EIP is at vt_ioctl+0xda8/0x1482
|
||||||
|
|
||||||
|
And recompile the kernel with CONFIG_DEBUG_INFO enabled:
|
||||||
|
|
||||||
|
make vmlinux
|
||||||
|
gdb vmlinux
|
||||||
|
(gdb) p vt_ioctl
|
||||||
|
(gdb) l *(0x<address of vt_ioctl> + 0xda8)
|
||||||
|
or, as one command
|
||||||
|
(gdb) l *(vt_ioctl + 0xda8)
|
||||||
|
|
||||||
|
If you have a call trace, such as :-
|
||||||
|
>Call Trace:
|
||||||
|
> [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5
|
||||||
|
> [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e
|
||||||
|
> [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee
|
||||||
|
> ...
|
||||||
|
this shows the problem in the :jbd: module. You can load that module in gdb
|
||||||
|
and list the relevant code.
|
||||||
|
gdb fs/jbd/jbd.ko
|
||||||
|
(gdb) p log_wait_commit
|
||||||
|
(gdb) l *(0x<address> + 0xa3)
|
||||||
|
or
|
||||||
|
(gdb) l *(log_wait_commit + 0xa3)
|
||||||
|
|
||||||
|
|
||||||
|
Another very useful option of the Kernel Hacking section in menuconfig is
|
||||||
|
Debug memory allocations. This will help you see whether data has been
|
||||||
|
initialised and not set before use etc. To see the values that get assigned
|
||||||
|
with this look at mm/slab.c and search for POISON_INUSE. When using this an
|
||||||
|
Oops will often show the poisoned data instead of zero which is the default.
|
||||||
|
|
||||||
|
Once you have worked out a fix please submit it upstream. After all open
|
||||||
|
source is about sharing what you do and don't you want to be recognised for
|
||||||
|
your genius?
|
||||||
|
|
||||||
|
Please do read Documentation/SubmittingPatches though to help your code get
|
||||||
|
accepted.
|
|
@ -0,0 +1,422 @@
|
||||||
|
Intro
|
||||||
|
=====
|
||||||
|
|
||||||
|
This document is designed to provide a list of the minimum levels of
|
||||||
|
software necessary to run the 2.6 kernels, as well as provide brief
|
||||||
|
instructions regarding any other "Gotchas" users may encounter when
|
||||||
|
trying life on the Bleeding Edge. If upgrading from a pre-2.4.x
|
||||||
|
kernel, please consult the Changes file included with 2.4.x kernels for
|
||||||
|
additional information; most of that information will not be repeated
|
||||||
|
here. Basically, this document assumes that your system is already
|
||||||
|
functional and running at least 2.4.x kernels.
|
||||||
|
|
||||||
|
This document is originally based on my "Changes" file for 2.0.x kernels
|
||||||
|
and therefore owes credit to the same people as that file (Jared Mauch,
|
||||||
|
Axel Boldt, Alessandro Sigala, and countless other users all over the
|
||||||
|
'net).
|
||||||
|
|
||||||
|
Current Minimal Requirements
|
||||||
|
============================
|
||||||
|
|
||||||
|
Upgrade to at *least* these software revisions before thinking you've
|
||||||
|
encountered a bug! If you're unsure what version you're currently
|
||||||
|
running, the suggested command should tell you.
|
||||||
|
|
||||||
|
Again, keep in mind that this list assumes you are already
|
||||||
|
functionally running a Linux 2.4 kernel. Also, not all tools are
|
||||||
|
necessary on all systems; obviously, if you don't have any ISDN
|
||||||
|
hardware, for example, you probably needn't concern yourself with
|
||||||
|
isdn4k-utils.
|
||||||
|
|
||||||
|
o Gnu C 3.2 # gcc --version
|
||||||
|
o Gnu make 3.80 # make --version
|
||||||
|
o binutils 2.12 # ld -v
|
||||||
|
o util-linux 2.10o # fdformat --version
|
||||||
|
o module-init-tools 0.9.10 # depmod -V
|
||||||
|
o e2fsprogs 1.41.4 # e2fsck -V
|
||||||
|
o jfsutils 1.1.3 # fsck.jfs -V
|
||||||
|
o reiserfsprogs 3.6.3 # reiserfsck -V 2>&1|grep reiserfsprogs
|
||||||
|
o xfsprogs 2.6.0 # xfs_db -V
|
||||||
|
o squashfs-tools 4.0 # mksquashfs -version
|
||||||
|
o btrfs-progs 0.18 # btrfsck
|
||||||
|
o pcmciautils 004 # pccardctl -V
|
||||||
|
o quota-tools 3.09 # quota -V
|
||||||
|
o PPP 2.4.0 # pppd --version
|
||||||
|
o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version
|
||||||
|
o nfs-utils 1.0.5 # showmount --version
|
||||||
|
o procps 3.2.0 # ps --version
|
||||||
|
o oprofile 0.9 # oprofiled --version
|
||||||
|
o udev 081 # udevinfo -V
|
||||||
|
o grub 0.93 # grub --version
|
||||||
|
o mcelog 0.6
|
||||||
|
o iptables 1.4.1 # iptables -V
|
||||||
|
|
||||||
|
|
||||||
|
Kernel compilation
|
||||||
|
==================
|
||||||
|
|
||||||
|
GCC
|
||||||
|
---
|
||||||
|
|
||||||
|
The gcc version requirements may vary depending on the type of CPU in your
|
||||||
|
computer.
|
||||||
|
|
||||||
|
Make
|
||||||
|
----
|
||||||
|
|
||||||
|
You will need Gnu make 3.80 or later to build the kernel.
|
||||||
|
|
||||||
|
Binutils
|
||||||
|
--------
|
||||||
|
|
||||||
|
Linux on IA-32 has recently switched from using as86 to using gas for
|
||||||
|
assembling the 16-bit boot code, removing the need for as86 to compile
|
||||||
|
your kernel. This change does, however, mean that you need a recent
|
||||||
|
release of binutils.
|
||||||
|
|
||||||
|
Perl
|
||||||
|
----
|
||||||
|
|
||||||
|
You will need perl 5 and the following modules: Getopt::Long, Getopt::Std,
|
||||||
|
File::Basename, and File::Find to build the kernel.
|
||||||
|
|
||||||
|
|
||||||
|
System utilities
|
||||||
|
================
|
||||||
|
|
||||||
|
Architectural changes
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
DevFS has been obsoleted in favour of udev
|
||||||
|
(http://www.kernel.org/pub/linux/utils/kernel/hotplug/)
|
||||||
|
|
||||||
|
32-bit UID support is now in place. Have fun!
|
||||||
|
|
||||||
|
Linux documentation for functions is transitioning to inline
|
||||||
|
documentation via specially-formatted comments near their
|
||||||
|
definitions in the source. These comments can be combined with the
|
||||||
|
SGML templates in the Documentation/DocBook directory to make DocBook
|
||||||
|
files, which can then be converted by DocBook stylesheets to PostScript,
|
||||||
|
HTML, PDF files, and several other formats. In order to convert from
|
||||||
|
DocBook format to a format of your choice, you'll need to install Jade as
|
||||||
|
well as the desired DocBook stylesheets.
|
||||||
|
|
||||||
|
Util-linux
|
||||||
|
----------
|
||||||
|
|
||||||
|
New versions of util-linux provide *fdisk support for larger disks,
|
||||||
|
support new options to mount, recognize more supported partition
|
||||||
|
types, have a fdformat which works with 2.4 kernels, and similar goodies.
|
||||||
|
You'll probably want to upgrade.
|
||||||
|
|
||||||
|
Ksymoops
|
||||||
|
--------
|
||||||
|
|
||||||
|
If the unthinkable happens and your kernel oopses, you may need the
|
||||||
|
ksymoops tool to decode it, but in most cases you don't.
|
||||||
|
In the 2.6 kernel it is generally preferred to build the kernel with
|
||||||
|
CONFIG_KALLSYMS so that it produces readable dumps that can be used as-is
|
||||||
|
(this also produces better output than ksymoops).
|
||||||
|
If for some reason your kernel is not build with CONFIG_KALLSYMS and
|
||||||
|
you have no way to rebuild and reproduce the Oops with that option, then
|
||||||
|
you can still decode that Oops with ksymoops.
|
||||||
|
|
||||||
|
Module-Init-Tools
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
A new module loader is now in the kernel that requires module-init-tools
|
||||||
|
to use. It is backward compatible with the 2.4.x series kernels.
|
||||||
|
|
||||||
|
Mkinitrd
|
||||||
|
--------
|
||||||
|
|
||||||
|
These changes to the /lib/modules file tree layout also require that
|
||||||
|
mkinitrd be upgraded.
|
||||||
|
|
||||||
|
E2fsprogs
|
||||||
|
---------
|
||||||
|
|
||||||
|
The latest version of e2fsprogs fixes several bugs in fsck and
|
||||||
|
debugfs. Obviously, it's a good idea to upgrade.
|
||||||
|
|
||||||
|
JFSutils
|
||||||
|
--------
|
||||||
|
|
||||||
|
The jfsutils package contains the utilities for the file system.
|
||||||
|
The following utilities are available:
|
||||||
|
o fsck.jfs - initiate replay of the transaction log, and check
|
||||||
|
and repair a JFS formatted partition.
|
||||||
|
o mkfs.jfs - create a JFS formatted partition.
|
||||||
|
o other file system utilities are also available in this package.
|
||||||
|
|
||||||
|
Reiserfsprogs
|
||||||
|
-------------
|
||||||
|
|
||||||
|
The reiserfsprogs package should be used for reiserfs-3.6.x
|
||||||
|
(Linux kernels 2.4.x). It is a combined package and contains working
|
||||||
|
versions of mkreiserfs, resize_reiserfs, debugreiserfs and
|
||||||
|
reiserfsck. These utils work on both i386 and alpha platforms.
|
||||||
|
|
||||||
|
Xfsprogs
|
||||||
|
--------
|
||||||
|
|
||||||
|
The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the
|
||||||
|
xfs_repair utilities, among others, for the XFS filesystem. It is
|
||||||
|
architecture independent and any version from 2.0.0 onward should
|
||||||
|
work correctly with this version of the XFS kernel code (2.6.0 or
|
||||||
|
later is recommended, due to some significant improvements).
|
||||||
|
|
||||||
|
PCMCIAutils
|
||||||
|
-----------
|
||||||
|
|
||||||
|
PCMCIAutils replaces pcmcia-cs (see below). It properly sets up
|
||||||
|
PCMCIA sockets at system startup and loads the appropriate modules
|
||||||
|
for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
|
||||||
|
subsystem is used.
|
||||||
|
|
||||||
|
Pcmcia-cs
|
||||||
|
---------
|
||||||
|
|
||||||
|
PCMCIA (PC Card) support is now partially implemented in the main
|
||||||
|
kernel source. The "pcmciautils" package (see above) replaces pcmcia-cs
|
||||||
|
for newest kernels.
|
||||||
|
|
||||||
|
Quota-tools
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Support for 32 bit uid's and gid's is required if you want to use
|
||||||
|
the newer version 2 quota format. Quota-tools version 3.07 and
|
||||||
|
newer has this support. Use the recommended version or newer
|
||||||
|
from the table above.
|
||||||
|
|
||||||
|
Intel IA32 microcode
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
A driver has been added to allow updating of Intel IA32 microcode,
|
||||||
|
accessible as a normal (misc) character device. If you are not using
|
||||||
|
udev you may need to:
|
||||||
|
|
||||||
|
mkdir /dev/cpu
|
||||||
|
mknod /dev/cpu/microcode c 10 184
|
||||||
|
chmod 0644 /dev/cpu/microcode
|
||||||
|
|
||||||
|
as root before you can use this. You'll probably also want to
|
||||||
|
get the user-space microcode_ctl utility to use with this.
|
||||||
|
|
||||||
|
Powertweak
|
||||||
|
----------
|
||||||
|
|
||||||
|
If you are running v0.1.17 or earlier, you should upgrade to
|
||||||
|
version v0.99.0 or higher. Running old versions may cause problems
|
||||||
|
with programs using shared memory.
|
||||||
|
|
||||||
|
udev
|
||||||
|
----
|
||||||
|
udev is a userspace application for populating /dev dynamically with
|
||||||
|
only entries for devices actually present. udev replaces the basic
|
||||||
|
functionality of devfs, while allowing persistent device naming for
|
||||||
|
devices.
|
||||||
|
|
||||||
|
FUSE
|
||||||
|
----
|
||||||
|
|
||||||
|
Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount
|
||||||
|
options 'direct_io' and 'kernel_cache' won't work.
|
||||||
|
|
||||||
|
Networking
|
||||||
|
==========
|
||||||
|
|
||||||
|
General changes
|
||||||
|
---------------
|
||||||
|
|
||||||
|
If you have advanced network configuration needs, you should probably
|
||||||
|
consider using the network tools from ip-route2.
|
||||||
|
|
||||||
|
Packet Filter / NAT
|
||||||
|
-------------------
|
||||||
|
The packet filtering and NAT code uses the same tools like the previous 2.4.x
|
||||||
|
kernel series (iptables). It still includes backwards-compatibility modules
|
||||||
|
for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
|
||||||
|
|
||||||
|
PPP
|
||||||
|
---
|
||||||
|
|
||||||
|
The PPP driver has been restructured to support multilink and to
|
||||||
|
enable it to operate over diverse media layers. If you use PPP,
|
||||||
|
upgrade pppd to at least 2.4.0.
|
||||||
|
|
||||||
|
If you are not using udev, you must have the device file /dev/ppp
|
||||||
|
which can be made by:
|
||||||
|
|
||||||
|
mknod /dev/ppp c 108 0
|
||||||
|
|
||||||
|
as root.
|
||||||
|
|
||||||
|
Isdn4k-utils
|
||||||
|
------------
|
||||||
|
|
||||||
|
Due to changes in the length of the phone number field, isdn4k-utils
|
||||||
|
needs to be recompiled or (preferably) upgraded.
|
||||||
|
|
||||||
|
NFS-utils
|
||||||
|
---------
|
||||||
|
|
||||||
|
In 2.4 and earlier kernels, the nfs server needed to know about any
|
||||||
|
client that expected to be able to access files via NFS. This
|
||||||
|
information would be given to the kernel by "mountd" when the client
|
||||||
|
mounted the filesystem, or by "exportfs" at system startup. exportfs
|
||||||
|
would take information about active clients from /var/lib/nfs/rmtab.
|
||||||
|
|
||||||
|
This approach is quite fragile as it depends on rmtab being correct
|
||||||
|
which is not always easy, particularly when trying to implement
|
||||||
|
fail-over. Even when the system is working well, rmtab suffers from
|
||||||
|
getting lots of old entries that never get removed.
|
||||||
|
|
||||||
|
With 2.6 we have the option of having the kernel tell mountd when it
|
||||||
|
gets a request from an unknown host, and mountd can give appropriate
|
||||||
|
export information to the kernel. This removes the dependency on
|
||||||
|
rmtab and means that the kernel only needs to know about currently
|
||||||
|
active clients.
|
||||||
|
|
||||||
|
To enable this new functionality, you need to:
|
||||||
|
|
||||||
|
mount -t nfsd nfsd /proc/fs/nfsd
|
||||||
|
|
||||||
|
before running exportfs or mountd. It is recommended that all NFS
|
||||||
|
services be protected from the internet-at-large by a firewall where
|
||||||
|
that is possible.
|
||||||
|
|
||||||
|
mcelog
|
||||||
|
------
|
||||||
|
|
||||||
|
In Linux 2.6.31+ the i386 kernel needs to run the mcelog utility
|
||||||
|
as a regular cronjob similar to the x86-64 kernel to process and log
|
||||||
|
machine check events when CONFIG_X86_NEW_MCE is enabled. Machine check
|
||||||
|
events are errors reported by the CPU. Processing them is strongly encouraged.
|
||||||
|
All x86-64 kernels since 2.6.4 require the mcelog utility to
|
||||||
|
process machine checks.
|
||||||
|
|
||||||
|
Getting updated software
|
||||||
|
========================
|
||||||
|
|
||||||
|
Kernel compilation
|
||||||
|
******************
|
||||||
|
|
||||||
|
gcc
|
||||||
|
---
|
||||||
|
o <ftp://ftp.gnu.org/gnu/gcc/>
|
||||||
|
|
||||||
|
Make
|
||||||
|
----
|
||||||
|
o <ftp://ftp.gnu.org/gnu/make/>
|
||||||
|
|
||||||
|
Binutils
|
||||||
|
--------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/devel/binutils/>
|
||||||
|
|
||||||
|
System utilities
|
||||||
|
****************
|
||||||
|
|
||||||
|
Util-linux
|
||||||
|
----------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/>
|
||||||
|
|
||||||
|
Ksymoops
|
||||||
|
--------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
|
||||||
|
|
||||||
|
Module-Init-Tools
|
||||||
|
-----------------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/>
|
||||||
|
|
||||||
|
Mkinitrd
|
||||||
|
--------
|
||||||
|
o <ftp://rawhide.redhat.com/pub/rawhide/SRPMS/SRPMS/>
|
||||||
|
|
||||||
|
E2fsprogs
|
||||||
|
---------
|
||||||
|
o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
|
||||||
|
|
||||||
|
JFSutils
|
||||||
|
--------
|
||||||
|
o <http://jfs.sourceforge.net/>
|
||||||
|
|
||||||
|
Reiserfsprogs
|
||||||
|
-------------
|
||||||
|
o <http://www.namesys.com/pub/reiserfsprogs/reiserfsprogs-3.6.3.tar.gz>
|
||||||
|
|
||||||
|
Xfsprogs
|
||||||
|
--------
|
||||||
|
o <ftp://oss.sgi.com/projects/xfs/download/>
|
||||||
|
|
||||||
|
Pcmciautils
|
||||||
|
-----------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/>
|
||||||
|
|
||||||
|
Pcmcia-cs
|
||||||
|
---------
|
||||||
|
o <http://pcmcia-cs.sourceforge.net/>
|
||||||
|
|
||||||
|
Quota-tools
|
||||||
|
----------
|
||||||
|
o <http://sourceforge.net/projects/linuxquota/>
|
||||||
|
|
||||||
|
DocBook Stylesheets
|
||||||
|
-------------------
|
||||||
|
o <http://nwalsh.com/docbook/dsssl/>
|
||||||
|
|
||||||
|
XMLTO XSLT Frontend
|
||||||
|
-------------------
|
||||||
|
o <http://cyberelk.net/tim/xmlto/>
|
||||||
|
|
||||||
|
Intel P6 microcode
|
||||||
|
------------------
|
||||||
|
o <http://www.urbanmyth.org/microcode/>
|
||||||
|
|
||||||
|
Powertweak
|
||||||
|
----------
|
||||||
|
o <http://powertweak.sourceforge.net/>
|
||||||
|
|
||||||
|
udev
|
||||||
|
----
|
||||||
|
o <http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html>
|
||||||
|
|
||||||
|
FUSE
|
||||||
|
----
|
||||||
|
o <http://sourceforge.net/projects/fuse>
|
||||||
|
|
||||||
|
mcelog
|
||||||
|
------
|
||||||
|
o <ftp://ftp.kernel.org/pub/linux/utils/cpu/mce/mcelog/>
|
||||||
|
|
||||||
|
Networking
|
||||||
|
**********
|
||||||
|
|
||||||
|
PPP
|
||||||
|
---
|
||||||
|
o <ftp://ftp.samba.org/pub/ppp/ppp-2.4.0.tar.gz>
|
||||||
|
|
||||||
|
Isdn4k-utils
|
||||||
|
------------
|
||||||
|
o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/isdn4k-utils.v3.1pre1.tar.gz>
|
||||||
|
|
||||||
|
NFS-utils
|
||||||
|
---------
|
||||||
|
o <http://sourceforge.net/project/showfiles.php?group_id=14>
|
||||||
|
|
||||||
|
Iptables
|
||||||
|
--------
|
||||||
|
o <http://www.iptables.org/downloads.html>
|
||||||
|
|
||||||
|
Ip-route2
|
||||||
|
---------
|
||||||
|
o <ftp://ftp.tux.org/pub/net/ip-routing/iproute2-2.2.4-now-ss991023.tar.gz>
|
||||||
|
|
||||||
|
OProfile
|
||||||
|
--------
|
||||||
|
o <http://oprofile.sf.net/download/>
|
||||||
|
|
||||||
|
NFS-Utils
|
||||||
|
---------
|
||||||
|
o <http://nfs.sourceforge.net/>
|
||||||
|
|
|
@ -0,0 +1,824 @@
|
||||||
|
|
||||||
|
Linux kernel coding style
|
||||||
|
|
||||||
|
This is a short document describing the preferred coding style for the
|
||||||
|
linux kernel. Coding style is very personal, and I won't _force_ my
|
||||||
|
views on anybody, but this is what goes for anything that I have to be
|
||||||
|
able to maintain, and I'd prefer it for most other things too. Please
|
||||||
|
at least consider the points made here.
|
||||||
|
|
||||||
|
First off, I'd suggest printing out a copy of the GNU coding standards,
|
||||||
|
and NOT read it. Burn them, it's a great symbolic gesture.
|
||||||
|
|
||||||
|
Anyway, here goes:
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 1: Indentation
|
||||||
|
|
||||||
|
Tabs are 8 characters, and thus indentations are also 8 characters.
|
||||||
|
There are heretic movements that try to make indentations 4 (or even 2!)
|
||||||
|
characters deep, and that is akin to trying to define the value of PI to
|
||||||
|
be 3.
|
||||||
|
|
||||||
|
Rationale: The whole idea behind indentation is to clearly define where
|
||||||
|
a block of control starts and ends. Especially when you've been looking
|
||||||
|
at your screen for 20 straight hours, you'll find it a lot easier to see
|
||||||
|
how the indentation works if you have large indentations.
|
||||||
|
|
||||||
|
Now, some people will claim that having 8-character indentations makes
|
||||||
|
the code move too far to the right, and makes it hard to read on a
|
||||||
|
80-character terminal screen. The answer to that is that if you need
|
||||||
|
more than 3 levels of indentation, you're screwed anyway, and should fix
|
||||||
|
your program.
|
||||||
|
|
||||||
|
In short, 8-char indents make things easier to read, and have the added
|
||||||
|
benefit of warning you when you're nesting your functions too deep.
|
||||||
|
Heed that warning.
|
||||||
|
|
||||||
|
The preferred way to ease multiple indentation levels in a switch statement is
|
||||||
|
to align the "switch" and its subordinate "case" labels in the same column
|
||||||
|
instead of "double-indenting" the "case" labels. E.g.:
|
||||||
|
|
||||||
|
switch (suffix) {
|
||||||
|
case 'G':
|
||||||
|
case 'g':
|
||||||
|
mem <<= 30;
|
||||||
|
break;
|
||||||
|
case 'M':
|
||||||
|
case 'm':
|
||||||
|
mem <<= 20;
|
||||||
|
break;
|
||||||
|
case 'K':
|
||||||
|
case 'k':
|
||||||
|
mem <<= 10;
|
||||||
|
/* fall through */
|
||||||
|
default:
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
Don't put multiple statements on a single line unless you have
|
||||||
|
something to hide:
|
||||||
|
|
||||||
|
if (condition) do_this;
|
||||||
|
do_something_everytime;
|
||||||
|
|
||||||
|
Don't put multiple assignments on a single line either. Kernel coding style
|
||||||
|
is super simple. Avoid tricky expressions.
|
||||||
|
|
||||||
|
Outside of comments, documentation and except in Kconfig, spaces are never
|
||||||
|
used for indentation, and the above example is deliberately broken.
|
||||||
|
|
||||||
|
Get a decent editor and don't leave whitespace at the end of lines.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 2: Breaking long lines and strings
|
||||||
|
|
||||||
|
Coding style is all about readability and maintainability using commonly
|
||||||
|
available tools.
|
||||||
|
|
||||||
|
The limit on the length of lines is 80 columns and this is a strongly
|
||||||
|
preferred limit.
|
||||||
|
|
||||||
|
Statements longer than 80 columns will be broken into sensible chunks.
|
||||||
|
Descendants are always substantially shorter than the parent and are placed
|
||||||
|
substantially to the right. The same applies to function headers with a long
|
||||||
|
argument list. Long strings are as well broken into shorter strings. The
|
||||||
|
only exception to this is where exceeding 80 columns significantly increases
|
||||||
|
readability and does not hide information.
|
||||||
|
|
||||||
|
void fun(int a, int b, int c)
|
||||||
|
{
|
||||||
|
if (condition)
|
||||||
|
printk(KERN_WARNING "Warning this is a long printk with "
|
||||||
|
"3 parameters a: %u b: %u "
|
||||||
|
"c: %u \n", a, b, c);
|
||||||
|
else
|
||||||
|
next_statement;
|
||||||
|
}
|
||||||
|
|
||||||
|
Chapter 3: Placing Braces and Spaces
|
||||||
|
|
||||||
|
The other issue that always comes up in C styling is the placement of
|
||||||
|
braces. Unlike the indent size, there are few technical reasons to
|
||||||
|
choose one placement strategy over the other, but the preferred way, as
|
||||||
|
shown to us by the prophets Kernighan and Ritchie, is to put the opening
|
||||||
|
brace last on the line, and put the closing brace first, thusly:
|
||||||
|
|
||||||
|
if (x is true) {
|
||||||
|
we do y
|
||||||
|
}
|
||||||
|
|
||||||
|
This applies to all non-function statement blocks (if, switch, for,
|
||||||
|
while, do). E.g.:
|
||||||
|
|
||||||
|
switch (action) {
|
||||||
|
case KOBJ_ADD:
|
||||||
|
return "add";
|
||||||
|
case KOBJ_REMOVE:
|
||||||
|
return "remove";
|
||||||
|
case KOBJ_CHANGE:
|
||||||
|
return "change";
|
||||||
|
default:
|
||||||
|
return NULL;
|
||||||
|
}
|
||||||
|
|
||||||
|
However, there is one special case, namely functions: they have the
|
||||||
|
opening brace at the beginning of the next line, thus:
|
||||||
|
|
||||||
|
int function(int x)
|
||||||
|
{
|
||||||
|
body of function
|
||||||
|
}
|
||||||
|
|
||||||
|
Heretic people all over the world have claimed that this inconsistency
|
||||||
|
is ... well ... inconsistent, but all right-thinking people know that
|
||||||
|
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
|
||||||
|
special anyway (you can't nest them in C).
|
||||||
|
|
||||||
|
Note that the closing brace is empty on a line of its own, _except_ in
|
||||||
|
the cases where it is followed by a continuation of the same statement,
|
||||||
|
ie a "while" in a do-statement or an "else" in an if-statement, like
|
||||||
|
this:
|
||||||
|
|
||||||
|
do {
|
||||||
|
body of do-loop
|
||||||
|
} while (condition);
|
||||||
|
|
||||||
|
and
|
||||||
|
|
||||||
|
if (x == y) {
|
||||||
|
..
|
||||||
|
} else if (x > y) {
|
||||||
|
...
|
||||||
|
} else {
|
||||||
|
....
|
||||||
|
}
|
||||||
|
|
||||||
|
Rationale: K&R.
|
||||||
|
|
||||||
|
Also, note that this brace-placement also minimizes the number of empty
|
||||||
|
(or almost empty) lines, without any loss of readability. Thus, as the
|
||||||
|
supply of new-lines on your screen is not a renewable resource (think
|
||||||
|
25-line terminal screens here), you have more empty lines to put
|
||||||
|
comments on.
|
||||||
|
|
||||||
|
Do not unnecessarily use braces where a single statement will do.
|
||||||
|
|
||||||
|
if (condition)
|
||||||
|
action();
|
||||||
|
|
||||||
|
This does not apply if one branch of a conditional statement is a single
|
||||||
|
statement. Use braces in both branches.
|
||||||
|
|
||||||
|
if (condition) {
|
||||||
|
do_this();
|
||||||
|
do_that();
|
||||||
|
} else {
|
||||||
|
otherwise();
|
||||||
|
}
|
||||||
|
|
||||||
|
3.1: Spaces
|
||||||
|
|
||||||
|
Linux kernel style for use of spaces depends (mostly) on
|
||||||
|
function-versus-keyword usage. Use a space after (most) keywords. The
|
||||||
|
notable exceptions are sizeof, typeof, alignof, and __attribute__, which look
|
||||||
|
somewhat like functions (and are usually used with parentheses in Linux,
|
||||||
|
although they are not required in the language, as in: "sizeof info" after
|
||||||
|
"struct fileinfo info;" is declared).
|
||||||
|
|
||||||
|
So use a space after these keywords:
|
||||||
|
if, switch, case, for, do, while
|
||||||
|
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||||
|
s = sizeof(struct file);
|
||||||
|
|
||||||
|
Do not add spaces around (inside) parenthesized expressions. This example is
|
||||||
|
*bad*:
|
||||||
|
|
||||||
|
s = sizeof( struct file );
|
||||||
|
|
||||||
|
When declaring pointer data or a function that returns a pointer type, the
|
||||||
|
preferred use of '*' is adjacent to the data name or function name and not
|
||||||
|
adjacent to the type name. Examples:
|
||||||
|
|
||||||
|
char *linux_banner;
|
||||||
|
unsigned long long memparse(char *ptr, char **retptr);
|
||||||
|
char *match_strdup(substring_t *s);
|
||||||
|
|
||||||
|
Use one space around (on each side of) most binary and ternary operators,
|
||||||
|
such as any of these:
|
||||||
|
|
||||||
|
= + - < > * / % | & ^ <= >= == != ? :
|
||||||
|
|
||||||
|
but no space after unary operators:
|
||||||
|
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||||
|
|
||||||
|
no space before the postfix increment & decrement unary operators:
|
||||||
|
++ --
|
||||||
|
|
||||||
|
no space after the prefix increment & decrement unary operators:
|
||||||
|
++ --
|
||||||
|
|
||||||
|
and no space around the '.' and "->" structure member operators.
|
||||||
|
|
||||||
|
Do not leave trailing whitespace at the ends of lines. Some editors with
|
||||||
|
"smart" indentation will insert whitespace at the beginning of new lines as
|
||||||
|
appropriate, so you can start typing the next line of code right away.
|
||||||
|
However, some such editors do not remove the whitespace if you end up not
|
||||||
|
putting a line of code there, such as if you leave a blank line. As a result,
|
||||||
|
you end up with lines containing trailing whitespace.
|
||||||
|
|
||||||
|
Git will warn you about patches that introduce trailing whitespace, and can
|
||||||
|
optionally strip the trailing whitespace for you; however, if applying a series
|
||||||
|
of patches, this may make later patches in the series fail by changing their
|
||||||
|
context lines.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 4: Naming
|
||||||
|
|
||||||
|
C is a Spartan language, and so should your naming be. Unlike Modula-2
|
||||||
|
and Pascal programmers, C programmers do not use cute names like
|
||||||
|
ThisVariableIsATemporaryCounter. A C programmer would call that
|
||||||
|
variable "tmp", which is much easier to write, and not the least more
|
||||||
|
difficult to understand.
|
||||||
|
|
||||||
|
HOWEVER, while mixed-case names are frowned upon, descriptive names for
|
||||||
|
global variables are a must. To call a global function "foo" is a
|
||||||
|
shooting offense.
|
||||||
|
|
||||||
|
GLOBAL variables (to be used only if you _really_ need them) need to
|
||||||
|
have descriptive names, as do global functions. If you have a function
|
||||||
|
that counts the number of active users, you should call that
|
||||||
|
"count_active_users()" or similar, you should _not_ call it "cntusr()".
|
||||||
|
|
||||||
|
Encoding the type of a function into the name (so-called Hungarian
|
||||||
|
notation) is brain damaged - the compiler knows the types anyway and can
|
||||||
|
check those, and it only confuses the programmer. No wonder MicroSoft
|
||||||
|
makes buggy programs.
|
||||||
|
|
||||||
|
LOCAL variable names should be short, and to the point. If you have
|
||||||
|
some random integer loop counter, it should probably be called "i".
|
||||||
|
Calling it "loop_counter" is non-productive, if there is no chance of it
|
||||||
|
being mis-understood. Similarly, "tmp" can be just about any type of
|
||||||
|
variable that is used to hold a temporary value.
|
||||||
|
|
||||||
|
If you are afraid to mix up your local variable names, you have another
|
||||||
|
problem, which is called the function-growth-hormone-imbalance syndrome.
|
||||||
|
See chapter 6 (Functions).
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 5: Typedefs
|
||||||
|
|
||||||
|
Please don't use things like "vps_t".
|
||||||
|
|
||||||
|
It's a _mistake_ to use typedef for structures and pointers. When you see a
|
||||||
|
|
||||||
|
vps_t a;
|
||||||
|
|
||||||
|
in the source, what does it mean?
|
||||||
|
|
||||||
|
In contrast, if it says
|
||||||
|
|
||||||
|
struct virtual_container *a;
|
||||||
|
|
||||||
|
you can actually tell what "a" is.
|
||||||
|
|
||||||
|
Lots of people think that typedefs "help readability". Not so. They are
|
||||||
|
useful only for:
|
||||||
|
|
||||||
|
(a) totally opaque objects (where the typedef is actively used to _hide_
|
||||||
|
what the object is).
|
||||||
|
|
||||||
|
Example: "pte_t" etc. opaque objects that you can only access using
|
||||||
|
the proper accessor functions.
|
||||||
|
|
||||||
|
NOTE! Opaqueness and "accessor functions" are not good in themselves.
|
||||||
|
The reason we have them for things like pte_t etc. is that there
|
||||||
|
really is absolutely _zero_ portably accessible information there.
|
||||||
|
|
||||||
|
(b) Clear integer types, where the abstraction _helps_ avoid confusion
|
||||||
|
whether it is "int" or "long".
|
||||||
|
|
||||||
|
u8/u16/u32 are perfectly fine typedefs, although they fit into
|
||||||
|
category (d) better than here.
|
||||||
|
|
||||||
|
NOTE! Again - there needs to be a _reason_ for this. If something is
|
||||||
|
"unsigned long", then there's no reason to do
|
||||||
|
|
||||||
|
typedef unsigned long myflags_t;
|
||||||
|
|
||||||
|
but if there is a clear reason for why it under certain circumstances
|
||||||
|
might be an "unsigned int" and under other configurations might be
|
||||||
|
"unsigned long", then by all means go ahead and use a typedef.
|
||||||
|
|
||||||
|
(c) when you use sparse to literally create a _new_ type for
|
||||||
|
type-checking.
|
||||||
|
|
||||||
|
(d) New types which are identical to standard C99 types, in certain
|
||||||
|
exceptional circumstances.
|
||||||
|
|
||||||
|
Although it would only take a short amount of time for the eyes and
|
||||||
|
brain to become accustomed to the standard types like 'uint32_t',
|
||||||
|
some people object to their use anyway.
|
||||||
|
|
||||||
|
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
|
||||||
|
signed equivalents which are identical to standard types are
|
||||||
|
permitted -- although they are not mandatory in new code of your
|
||||||
|
own.
|
||||||
|
|
||||||
|
When editing existing code which already uses one or the other set
|
||||||
|
of types, you should conform to the existing choices in that code.
|
||||||
|
|
||||||
|
(e) Types safe for use in userspace.
|
||||||
|
|
||||||
|
In certain structures which are visible to userspace, we cannot
|
||||||
|
require C99 types and cannot use the 'u32' form above. Thus, we
|
||||||
|
use __u32 and similar types in all structures which are shared
|
||||||
|
with userspace.
|
||||||
|
|
||||||
|
Maybe there are other cases too, but the rule should basically be to NEVER
|
||||||
|
EVER use a typedef unless you can clearly match one of those rules.
|
||||||
|
|
||||||
|
In general, a pointer, or a struct that has elements that can reasonably
|
||||||
|
be directly accessed should _never_ be a typedef.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 6: Functions
|
||||||
|
|
||||||
|
Functions should be short and sweet, and do just one thing. They should
|
||||||
|
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
|
||||||
|
as we all know), and do one thing and do that well.
|
||||||
|
|
||||||
|
The maximum length of a function is inversely proportional to the
|
||||||
|
complexity and indentation level of that function. So, if you have a
|
||||||
|
conceptually simple function that is just one long (but simple)
|
||||||
|
case-statement, where you have to do lots of small things for a lot of
|
||||||
|
different cases, it's OK to have a longer function.
|
||||||
|
|
||||||
|
However, if you have a complex function, and you suspect that a
|
||||||
|
less-than-gifted first-year high-school student might not even
|
||||||
|
understand what the function is all about, you should adhere to the
|
||||||
|
maximum limits all the more closely. Use helper functions with
|
||||||
|
descriptive names (you can ask the compiler to in-line them if you think
|
||||||
|
it's performance-critical, and it will probably do a better job of it
|
||||||
|
than you would have done).
|
||||||
|
|
||||||
|
Another measure of the function is the number of local variables. They
|
||||||
|
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
|
||||||
|
function, and split it into smaller pieces. A human brain can
|
||||||
|
generally easily keep track of about 7 different things, anything more
|
||||||
|
and it gets confused. You know you're brilliant, but maybe you'd like
|
||||||
|
to understand what you did 2 weeks from now.
|
||||||
|
|
||||||
|
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
|
||||||
|
function brace line. E.g.:
|
||||||
|
|
||||||
|
int system_is_up(void)
|
||||||
|
{
|
||||||
|
return system_state == SYSTEM_RUNNING;
|
||||||
|
}
|
||||||
|
EXPORT_SYMBOL(system_is_up);
|
||||||
|
|
||||||
|
In function prototypes, include parameter names with their data types.
|
||||||
|
Although this is not required by the C language, it is preferred in Linux
|
||||||
|
because it is a simple way to add valuable information for the reader.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 7: Centralized exiting of functions
|
||||||
|
|
||||||
|
Albeit deprecated by some people, the equivalent of the goto statement is
|
||||||
|
used frequently by compilers in form of the unconditional jump instruction.
|
||||||
|
|
||||||
|
The goto statement comes in handy when a function exits from multiple
|
||||||
|
locations and some common work such as cleanup has to be done.
|
||||||
|
|
||||||
|
The rationale is:
|
||||||
|
|
||||||
|
- unconditional statements are easier to understand and follow
|
||||||
|
- nesting is reduced
|
||||||
|
- errors by not updating individual exit points when making
|
||||||
|
modifications are prevented
|
||||||
|
- saves the compiler work to optimize redundant code away ;)
|
||||||
|
|
||||||
|
int fun(int a)
|
||||||
|
{
|
||||||
|
int result = 0;
|
||||||
|
char *buffer = kmalloc(SIZE);
|
||||||
|
|
||||||
|
if (buffer == NULL)
|
||||||
|
return -ENOMEM;
|
||||||
|
|
||||||
|
if (condition1) {
|
||||||
|
while (loop1) {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
result = 1;
|
||||||
|
goto out;
|
||||||
|
}
|
||||||
|
...
|
||||||
|
out:
|
||||||
|
kfree(buffer);
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
Chapter 8: Commenting
|
||||||
|
|
||||||
|
Comments are good, but there is also a danger of over-commenting. NEVER
|
||||||
|
try to explain HOW your code works in a comment: it's much better to
|
||||||
|
write the code so that the _working_ is obvious, and it's a waste of
|
||||||
|
time to explain badly written code.
|
||||||
|
|
||||||
|
Generally, you want your comments to tell WHAT your code does, not HOW.
|
||||||
|
Also, try to avoid putting comments inside a function body: if the
|
||||||
|
function is so complex that you need to separately comment parts of it,
|
||||||
|
you should probably go back to chapter 6 for a while. You can make
|
||||||
|
small comments to note or warn about something particularly clever (or
|
||||||
|
ugly), but try to avoid excess. Instead, put the comments at the head
|
||||||
|
of the function, telling people what it does, and possibly WHY it does
|
||||||
|
it.
|
||||||
|
|
||||||
|
When commenting the kernel API functions, please use the kernel-doc format.
|
||||||
|
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
|
||||||
|
for details.
|
||||||
|
|
||||||
|
Linux style for comments is the C89 "/* ... */" style.
|
||||||
|
Don't use C99-style "// ..." comments.
|
||||||
|
|
||||||
|
The preferred style for long (multi-line) comments is:
|
||||||
|
|
||||||
|
/*
|
||||||
|
* This is the preferred style for multi-line
|
||||||
|
* comments in the Linux kernel source code.
|
||||||
|
* Please use it consistently.
|
||||||
|
*
|
||||||
|
* Description: A column of asterisks on the left side,
|
||||||
|
* with beginning and ending almost-blank lines.
|
||||||
|
*/
|
||||||
|
|
||||||
|
It's also important to comment data, whether they are basic types or derived
|
||||||
|
types. To this end, use just one data declaration per line (no commas for
|
||||||
|
multiple data declarations). This leaves you room for a small comment on each
|
||||||
|
item, explaining its use.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 9: You've made a mess of it
|
||||||
|
|
||||||
|
That's OK, we all do. You've probably been told by your long-time Unix
|
||||||
|
user helper that "GNU emacs" automatically formats the C sources for
|
||||||
|
you, and you've noticed that yes, it does do that, but the defaults it
|
||||||
|
uses are less than desirable (in fact, they are worse than random
|
||||||
|
typing - an infinite number of monkeys typing into GNU emacs would never
|
||||||
|
make a good program).
|
||||||
|
|
||||||
|
So, you can either get rid of GNU emacs, or change it to use saner
|
||||||
|
values. To do the latter, you can stick the following in your .emacs file:
|
||||||
|
|
||||||
|
(defun c-lineup-arglist-tabs-only (ignored)
|
||||||
|
"Line up argument lists by tabs, not spaces"
|
||||||
|
(let* ((anchor (c-langelem-pos c-syntactic-element))
|
||||||
|
(column (c-langelem-2nd-pos c-syntactic-element))
|
||||||
|
(offset (- (1+ column) anchor))
|
||||||
|
(steps (floor offset c-basic-offset)))
|
||||||
|
(* (max steps 1)
|
||||||
|
c-basic-offset)))
|
||||||
|
|
||||||
|
(add-hook 'c-mode-common-hook
|
||||||
|
(lambda ()
|
||||||
|
;; Add kernel style
|
||||||
|
(c-add-style
|
||||||
|
"linux-tabs-only"
|
||||||
|
'("linux" (c-offsets-alist
|
||||||
|
(arglist-cont-nonempty
|
||||||
|
c-lineup-gcc-asm-reg
|
||||||
|
c-lineup-arglist-tabs-only))))))
|
||||||
|
|
||||||
|
(add-hook 'c-mode-hook
|
||||||
|
(lambda ()
|
||||||
|
(let ((filename (buffer-file-name)))
|
||||||
|
;; Enable kernel mode for the appropriate files
|
||||||
|
(when (and filename
|
||||||
|
(string-match (expand-file-name "~/src/linux-trees")
|
||||||
|
filename))
|
||||||
|
(setq indent-tabs-mode t)
|
||||||
|
(c-set-style "linux-tabs-only")))))
|
||||||
|
|
||||||
|
This will make emacs go better with the kernel coding style for C
|
||||||
|
files below ~/src/linux-trees.
|
||||||
|
|
||||||
|
But even if you fail in getting emacs to do sane formatting, not
|
||||||
|
everything is lost: use "indent".
|
||||||
|
|
||||||
|
Now, again, GNU indent has the same brain-dead settings that GNU emacs
|
||||||
|
has, which is why you need to give it a few command line options.
|
||||||
|
However, that's not too bad, because even the makers of GNU indent
|
||||||
|
recognize the authority of K&R (the GNU people aren't evil, they are
|
||||||
|
just severely misguided in this matter), so you just give indent the
|
||||||
|
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
|
||||||
|
"scripts/Lindent", which indents in the latest style.
|
||||||
|
|
||||||
|
"indent" has a lot of options, and especially when it comes to comment
|
||||||
|
re-formatting you may want to take a look at the man page. But
|
||||||
|
remember: "indent" is not a fix for bad programming.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 10: Kconfig configuration files
|
||||||
|
|
||||||
|
For all of the Kconfig* configuration files throughout the source tree,
|
||||||
|
the indentation is somewhat different. Lines under a "config" definition
|
||||||
|
are indented with one tab, while help text is indented an additional two
|
||||||
|
spaces. Example:
|
||||||
|
|
||||||
|
config AUDIT
|
||||||
|
bool "Auditing support"
|
||||||
|
depends on NET
|
||||||
|
help
|
||||||
|
Enable auditing infrastructure that can be used with another
|
||||||
|
kernel subsystem, such as SELinux (which requires this for
|
||||||
|
logging of avc messages output). Does not do system-call
|
||||||
|
auditing without CONFIG_AUDITSYSCALL.
|
||||||
|
|
||||||
|
Features that might still be considered unstable should be defined as
|
||||||
|
dependent on "EXPERIMENTAL":
|
||||||
|
|
||||||
|
config SLUB
|
||||||
|
depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT
|
||||||
|
bool "SLUB (Unqueued Allocator)"
|
||||||
|
...
|
||||||
|
|
||||||
|
while seriously dangerous features (such as write support for certain
|
||||||
|
filesystems) should advertise this prominently in their prompt string:
|
||||||
|
|
||||||
|
config ADFS_FS_RW
|
||||||
|
bool "ADFS write support (DANGEROUS)"
|
||||||
|
depends on ADFS_FS
|
||||||
|
...
|
||||||
|
|
||||||
|
For full documentation on the configuration files, see the file
|
||||||
|
Documentation/kbuild/kconfig-language.txt.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 11: Data structures
|
||||||
|
|
||||||
|
Data structures that have visibility outside the single-threaded
|
||||||
|
environment they are created and destroyed in should always have
|
||||||
|
reference counts. In the kernel, garbage collection doesn't exist (and
|
||||||
|
outside the kernel garbage collection is slow and inefficient), which
|
||||||
|
means that you absolutely _have_ to reference count all your uses.
|
||||||
|
|
||||||
|
Reference counting means that you can avoid locking, and allows multiple
|
||||||
|
users to have access to the data structure in parallel - and not having
|
||||||
|
to worry about the structure suddenly going away from under them just
|
||||||
|
because they slept or did something else for a while.
|
||||||
|
|
||||||
|
Note that locking is _not_ a replacement for reference counting.
|
||||||
|
Locking is used to keep data structures coherent, while reference
|
||||||
|
counting is a memory management technique. Usually both are needed, and
|
||||||
|
they are not to be confused with each other.
|
||||||
|
|
||||||
|
Many data structures can indeed have two levels of reference counting,
|
||||||
|
when there are users of different "classes". The subclass count counts
|
||||||
|
the number of subclass users, and decrements the global count just once
|
||||||
|
when the subclass count goes to zero.
|
||||||
|
|
||||||
|
Examples of this kind of "multi-level-reference-counting" can be found in
|
||||||
|
memory management ("struct mm_struct": mm_users and mm_count), and in
|
||||||
|
filesystem code ("struct super_block": s_count and s_active).
|
||||||
|
|
||||||
|
Remember: if another thread can find your data structure, and you don't
|
||||||
|
have a reference count on it, you almost certainly have a bug.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 12: Macros, Enums and RTL
|
||||||
|
|
||||||
|
Names of macros defining constants and labels in enums are capitalized.
|
||||||
|
|
||||||
|
#define CONSTANT 0x12345
|
||||||
|
|
||||||
|
Enums are preferred when defining several related constants.
|
||||||
|
|
||||||
|
CAPITALIZED macro names are appreciated but macros resembling functions
|
||||||
|
may be named in lower case.
|
||||||
|
|
||||||
|
Generally, inline functions are preferable to macros resembling functions.
|
||||||
|
|
||||||
|
Macros with multiple statements should be enclosed in a do - while block:
|
||||||
|
|
||||||
|
#define macrofun(a, b, c) \
|
||||||
|
do { \
|
||||||
|
if (a == 5) \
|
||||||
|
do_this(b, c); \
|
||||||
|
} while (0)
|
||||||
|
|
||||||
|
Things to avoid when using macros:
|
||||||
|
|
||||||
|
1) macros that affect control flow:
|
||||||
|
|
||||||
|
#define FOO(x) \
|
||||||
|
do { \
|
||||||
|
if (blah(x) < 0) \
|
||||||
|
return -EBUGGERED; \
|
||||||
|
} while(0)
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
2) macros that depend on having a local variable with a magic name:
|
||||||
|
|
||||||
|
#define FOO(val) bar(index, val)
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
3) macros with arguments that are used as l-values: FOO(x) = y; will
|
||||||
|
bite you if somebody e.g. turns FOO into an inline function.
|
||||||
|
|
||||||
|
4) forgetting about precedence: macros defining constants using expressions
|
||||||
|
must enclose the expression in parentheses. Beware of similar issues with
|
||||||
|
macros using parameters.
|
||||||
|
|
||||||
|
#define CONSTANT 0x4000
|
||||||
|
#define CONSTEXP (CONSTANT | 3)
|
||||||
|
|
||||||
|
The cpp manual deals with macros exhaustively. The gcc internals manual also
|
||||||
|
covers RTL which is used frequently with assembly language in the kernel.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 13: Printing kernel messages
|
||||||
|
|
||||||
|
Kernel developers like to be seen as literate. Do mind the spelling
|
||||||
|
of kernel messages to make a good impression. Do not use crippled
|
||||||
|
words like "dont"; use "do not" or "don't" instead. Make the messages
|
||||||
|
concise, clear, and unambiguous.
|
||||||
|
|
||||||
|
Kernel messages do not have to be terminated with a period.
|
||||||
|
|
||||||
|
Printing numbers in parentheses (%d) adds no value and should be avoided.
|
||||||
|
|
||||||
|
There are a number of driver model diagnostic macros in <linux/device.h>
|
||||||
|
which you should use to make sure messages are matched to the right device
|
||||||
|
and driver, and are tagged with the right level: dev_err(), dev_warn(),
|
||||||
|
dev_info(), and so forth. For messages that aren't associated with a
|
||||||
|
particular device, <linux/kernel.h> defines pr_debug() and pr_info().
|
||||||
|
|
||||||
|
Coming up with good debugging messages can be quite a challenge; and once
|
||||||
|
you have them, they can be a huge help for remote troubleshooting. Such
|
||||||
|
messages should be compiled out when the DEBUG symbol is not defined (that
|
||||||
|
is, by default they are not included). When you use dev_dbg() or pr_debug(),
|
||||||
|
that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
|
||||||
|
A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
|
||||||
|
ones already enabled by DEBUG.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 14: Allocating memory
|
||||||
|
|
||||||
|
The kernel provides the following general purpose memory allocators:
|
||||||
|
kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
|
||||||
|
documentation for further information about them.
|
||||||
|
|
||||||
|
The preferred form for passing a size of a struct is the following:
|
||||||
|
|
||||||
|
p = kmalloc(sizeof(*p), ...);
|
||||||
|
|
||||||
|
The alternative form where struct name is spelled out hurts readability and
|
||||||
|
introduces an opportunity for a bug when the pointer variable type is changed
|
||||||
|
but the corresponding sizeof that is passed to a memory allocator is not.
|
||||||
|
|
||||||
|
Casting the return value which is a void pointer is redundant. The conversion
|
||||||
|
from void pointer to any other pointer type is guaranteed by the C programming
|
||||||
|
language.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 15: The inline disease
|
||||||
|
|
||||||
|
There appears to be a common misperception that gcc has a magic "make me
|
||||||
|
faster" speedup option called "inline". While the use of inlines can be
|
||||||
|
appropriate (for example as a means of replacing macros, see Chapter 12), it
|
||||||
|
very often is not. Abundant use of the inline keyword leads to a much bigger
|
||||||
|
kernel, which in turn slows the system as a whole down, due to a bigger
|
||||||
|
icache footprint for the CPU and simply because there is less memory
|
||||||
|
available for the pagecache. Just think about it; a pagecache miss causes a
|
||||||
|
disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles
|
||||||
|
that can go into these 5 milliseconds.
|
||||||
|
|
||||||
|
A reasonable rule of thumb is to not put inline at functions that have more
|
||||||
|
than 3 lines of code in them. An exception to this rule are the cases where
|
||||||
|
a parameter is known to be a compiletime constant, and as a result of this
|
||||||
|
constantness you *know* the compiler will be able to optimize most of your
|
||||||
|
function away at compile time. For a good example of this later case, see
|
||||||
|
the kmalloc() inline function.
|
||||||
|
|
||||||
|
Often people argue that adding inline to functions that are static and used
|
||||||
|
only once is always a win since there is no space tradeoff. While this is
|
||||||
|
technically correct, gcc is capable of inlining these automatically without
|
||||||
|
help, and the maintenance issue of removing the inline when a second user
|
||||||
|
appears outweighs the potential value of the hint that tells gcc to do
|
||||||
|
something it would have done anyway.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 16: Function return values and names
|
||||||
|
|
||||||
|
Functions can return values of many different kinds, and one of the
|
||||||
|
most common is a value indicating whether the function succeeded or
|
||||||
|
failed. Such a value can be represented as an error-code integer
|
||||||
|
(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
|
||||||
|
non-zero = success).
|
||||||
|
|
||||||
|
Mixing up these two sorts of representations is a fertile source of
|
||||||
|
difficult-to-find bugs. If the C language included a strong distinction
|
||||||
|
between integers and booleans then the compiler would find these mistakes
|
||||||
|
for us... but it doesn't. To help prevent such bugs, always follow this
|
||||||
|
convention:
|
||||||
|
|
||||||
|
If the name of a function is an action or an imperative command,
|
||||||
|
the function should return an error-code integer. If the name
|
||||||
|
is a predicate, the function should return a "succeeded" boolean.
|
||||||
|
|
||||||
|
For example, "add work" is a command, and the add_work() function returns 0
|
||||||
|
for success or -EBUSY for failure. In the same way, "PCI device present" is
|
||||||
|
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
|
||||||
|
finding a matching device or 0 if it doesn't.
|
||||||
|
|
||||||
|
All EXPORTed functions must respect this convention, and so should all
|
||||||
|
public functions. Private (static) functions need not, but it is
|
||||||
|
recommended that they do.
|
||||||
|
|
||||||
|
Functions whose return value is the actual result of a computation, rather
|
||||||
|
than an indication of whether the computation succeeded, are not subject to
|
||||||
|
this rule. Generally they indicate failure by returning some out-of-range
|
||||||
|
result. Typical examples would be functions that return pointers; they use
|
||||||
|
NULL or the ERR_PTR mechanism to report failure.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 17: Don't re-invent the kernel macros
|
||||||
|
|
||||||
|
The header file include/linux/kernel.h contains a number of macros that
|
||||||
|
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
|
||||||
|
of the macro
|
||||||
|
|
||||||
|
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
|
||||||
|
|
||||||
|
Similarly, if you need to calculate the size of some structure member, use
|
||||||
|
|
||||||
|
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
|
||||||
|
|
||||||
|
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
|
||||||
|
defined that you shouldn't reproduce in your code.
|
||||||
|
|
||||||
|
|
||||||
|
Chapter 18: Editor modelines and other cruft
|
||||||
|
|
||||||
|
Some editors can interpret configuration information embedded in source files,
|
||||||
|
indicated with special markers. For example, emacs interprets lines marked
|
||||||
|
like this:
|
||||||
|
|
||||||
|
-*- mode: c -*-
|
||||||
|
|
||||||
|
Or like this:
|
||||||
|
|
||||||
|
/*
|
||||||
|
Local Variables:
|
||||||
|
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||||
|
End:
|
||||||
|
*/
|
||||||
|
|
||||||
|
Vim interprets markers that look like this:
|
||||||
|
|
||||||
|
/* vim:set sw=8 noet */
|
||||||
|
|
||||||
|
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
|
||||||
|
includes markers for indentation and mode configuration. People may use their
|
||||||
|
own custom mode, or may have some other magic method for making indentation
|
||||||
|
work correctly.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Appendix I: References
|
||||||
|
|
||||||
|
The C Programming Language, Second Edition
|
||||||
|
by Brian W. Kernighan and Dennis M. Ritchie.
|
||||||
|
Prentice Hall, Inc., 1988.
|
||||||
|
ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
|
||||||
|
URL: http://cm.bell-labs.com/cm/cs/cbook/
|
||||||
|
|
||||||
|
The Practice of Programming
|
||||||
|
by Brian W. Kernighan and Rob Pike.
|
||||||
|
Addison-Wesley, Inc., 1999.
|
||||||
|
ISBN 0-201-61586-X.
|
||||||
|
URL: http://cm.bell-labs.com/cm/cs/tpop/
|
||||||
|
|
||||||
|
GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
|
||||||
|
gcc internals and indent, all available from http://www.gnu.org/manual/
|
||||||
|
|
||||||
|
WG14 is the international standardization working group for the programming
|
||||||
|
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.
|
||||||
|
|
|
@ -0,0 +1,729 @@
|
||||||
|
Dynamic DMA mapping using the generic device
|
||||||
|
============================================
|
||||||
|
|
||||||
|
James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
|
||||||
|
|
||||||
|
This document describes the DMA API. For a more gentle introduction
|
||||||
|
phrased in terms of the pci_ equivalents (and actual examples) see
|
||||||
|
Documentation/PCI/PCI-DMA-mapping.txt.
|
||||||
|
|
||||||
|
This API is split into two pieces. Part I describes the API and the
|
||||||
|
corresponding pci_ API. Part II describes the extensions to the API
|
||||||
|
for supporting non-consistent memory machines. Unless you know that
|
||||||
|
your driver absolutely has to support non-consistent platforms (this
|
||||||
|
is usually only legacy platforms) you should only use the API
|
||||||
|
described in part I.
|
||||||
|
|
||||||
|
Part I - pci_ and dma_ Equivalent API
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
To get the pci_ API, you must #include <linux/pci.h>
|
||||||
|
To get the dma_ API, you must #include <linux/dma-mapping.h>
|
||||||
|
|
||||||
|
|
||||||
|
Part Ia - Using large dma-coherent buffers
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
void *
|
||||||
|
dma_alloc_coherent(struct device *dev, size_t size,
|
||||||
|
dma_addr_t *dma_handle, gfp_t flag)
|
||||||
|
void *
|
||||||
|
pci_alloc_consistent(struct pci_dev *dev, size_t size,
|
||||||
|
dma_addr_t *dma_handle)
|
||||||
|
|
||||||
|
Consistent memory is memory for which a write by either the device or
|
||||||
|
the processor can immediately be read by the processor or device
|
||||||
|
without having to worry about caching effects. (You may however need
|
||||||
|
to make sure to flush the processor's write buffers before telling
|
||||||
|
devices to read that memory.)
|
||||||
|
|
||||||
|
This routine allocates a region of <size> bytes of consistent memory.
|
||||||
|
It also returns a <dma_handle> which may be cast to an unsigned
|
||||||
|
integer the same width as the bus and used as the physical address
|
||||||
|
base of the region.
|
||||||
|
|
||||||
|
Returns: a pointer to the allocated region (in the processor's virtual
|
||||||
|
address space) or NULL if the allocation failed.
|
||||||
|
|
||||||
|
Note: consistent memory can be expensive on some platforms, and the
|
||||||
|
minimum allocation length may be as big as a page, so you should
|
||||||
|
consolidate your requests for consistent memory as much as possible.
|
||||||
|
The simplest way to do that is to use the dma_pool calls (see below).
|
||||||
|
|
||||||
|
The flag parameter (dma_alloc_coherent only) allows the caller to
|
||||||
|
specify the GFP_ flags (see kmalloc) for the allocation (the
|
||||||
|
implementation may choose to ignore flags that affect the location of
|
||||||
|
the returned memory, like GFP_DMA). For pci_alloc_consistent, you
|
||||||
|
must assume GFP_ATOMIC behaviour.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
|
||||||
|
dma_addr_t dma_handle)
|
||||||
|
void
|
||||||
|
pci_free_consistent(struct pci_dev *dev, size_t size, void *cpu_addr,
|
||||||
|
dma_addr_t dma_handle)
|
||||||
|
|
||||||
|
Free the region of consistent memory you previously allocated. dev,
|
||||||
|
size and dma_handle must all be the same as those passed into the
|
||||||
|
consistent allocate. cpu_addr must be the virtual address returned by
|
||||||
|
the consistent allocate.
|
||||||
|
|
||||||
|
Note that unlike their sibling allocation calls, these routines
|
||||||
|
may only be called with IRQs enabled.
|
||||||
|
|
||||||
|
|
||||||
|
Part Ib - Using small dma-coherent buffers
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
To get this part of the dma_ API, you must #include <linux/dmapool.h>
|
||||||
|
|
||||||
|
Many drivers need lots of small dma-coherent memory regions for DMA
|
||||||
|
descriptors or I/O buffers. Rather than allocating in units of a page
|
||||||
|
or more using dma_alloc_coherent(), you can use DMA pools. These work
|
||||||
|
much like a struct kmem_cache, except that they use the dma-coherent allocator,
|
||||||
|
not __get_free_pages(). Also, they understand common hardware constraints
|
||||||
|
for alignment, like queue heads needing to be aligned on N-byte boundaries.
|
||||||
|
|
||||||
|
|
||||||
|
struct dma_pool *
|
||||||
|
dma_pool_create(const char *name, struct device *dev,
|
||||||
|
size_t size, size_t align, size_t alloc);
|
||||||
|
|
||||||
|
struct pci_pool *
|
||||||
|
pci_pool_create(const char *name, struct pci_device *dev,
|
||||||
|
size_t size, size_t align, size_t alloc);
|
||||||
|
|
||||||
|
The pool create() routines initialize a pool of dma-coherent buffers
|
||||||
|
for use with a given device. It must be called in a context which
|
||||||
|
can sleep.
|
||||||
|
|
||||||
|
The "name" is for diagnostics (like a struct kmem_cache name); dev and size
|
||||||
|
are like what you'd pass to dma_alloc_coherent(). The device's hardware
|
||||||
|
alignment requirement for this type of data is "align" (which is expressed
|
||||||
|
in bytes, and must be a power of two). If your device has no boundary
|
||||||
|
crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
|
||||||
|
from this pool must not cross 4KByte boundaries.
|
||||||
|
|
||||||
|
|
||||||
|
void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
|
||||||
|
dma_addr_t *dma_handle);
|
||||||
|
|
||||||
|
void *pci_pool_alloc(struct pci_pool *pool, gfp_t gfp_flags,
|
||||||
|
dma_addr_t *dma_handle);
|
||||||
|
|
||||||
|
This allocates memory from the pool; the returned memory will meet the size
|
||||||
|
and alignment requirements specified at creation time. Pass GFP_ATOMIC to
|
||||||
|
prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks),
|
||||||
|
pass GFP_KERNEL to allow blocking. Like dma_alloc_coherent(), this returns
|
||||||
|
two values: an address usable by the cpu, and the dma address usable by the
|
||||||
|
pool's device.
|
||||||
|
|
||||||
|
|
||||||
|
void dma_pool_free(struct dma_pool *pool, void *vaddr,
|
||||||
|
dma_addr_t addr);
|
||||||
|
|
||||||
|
void pci_pool_free(struct pci_pool *pool, void *vaddr,
|
||||||
|
dma_addr_t addr);
|
||||||
|
|
||||||
|
This puts memory back into the pool. The pool is what was passed to
|
||||||
|
the pool allocation routine; the cpu (vaddr) and dma addresses are what
|
||||||
|
were returned when that routine allocated the memory being freed.
|
||||||
|
|
||||||
|
|
||||||
|
void dma_pool_destroy(struct dma_pool *pool);
|
||||||
|
|
||||||
|
void pci_pool_destroy(struct pci_pool *pool);
|
||||||
|
|
||||||
|
The pool destroy() routines free the resources of the pool. They must be
|
||||||
|
called in a context which can sleep. Make sure you've freed all allocated
|
||||||
|
memory back to the pool before you destroy it.
|
||||||
|
|
||||||
|
|
||||||
|
Part Ic - DMA addressing limitations
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_supported(struct device *dev, u64 mask)
|
||||||
|
int
|
||||||
|
pci_dma_supported(struct pci_dev *hwdev, u64 mask)
|
||||||
|
|
||||||
|
Checks to see if the device can support DMA to the memory described by
|
||||||
|
mask.
|
||||||
|
|
||||||
|
Returns: 1 if it can and 0 if it can't.
|
||||||
|
|
||||||
|
Notes: This routine merely tests to see if the mask is possible. It
|
||||||
|
won't change the current mask settings. It is more intended as an
|
||||||
|
internal API for use by the platform than an external API for use by
|
||||||
|
driver writers.
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_set_mask(struct device *dev, u64 mask)
|
||||||
|
int
|
||||||
|
pci_set_dma_mask(struct pci_device *dev, u64 mask)
|
||||||
|
|
||||||
|
Checks to see if the mask is possible and updates the device
|
||||||
|
parameters if it is.
|
||||||
|
|
||||||
|
Returns: 0 if successful and a negative error if not.
|
||||||
|
|
||||||
|
u64
|
||||||
|
dma_get_required_mask(struct device *dev)
|
||||||
|
|
||||||
|
This API returns the mask that the platform requires to
|
||||||
|
operate efficiently. Usually this means the returned mask
|
||||||
|
is the minimum required to cover all of memory. Examining the
|
||||||
|
required mask gives drivers with variable descriptor sizes the
|
||||||
|
opportunity to use smaller descriptors as necessary.
|
||||||
|
|
||||||
|
Requesting the required mask does not alter the current mask. If you
|
||||||
|
wish to take advantage of it, you should issue a dma_set_mask()
|
||||||
|
call to set the mask to the value returned.
|
||||||
|
|
||||||
|
|
||||||
|
Part Id - Streaming DMA mappings
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
dma_addr_t
|
||||||
|
dma_map_single(struct device *dev, void *cpu_addr, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
dma_addr_t
|
||||||
|
pci_map_single(struct pci_dev *hwdev, void *cpu_addr, size_t size,
|
||||||
|
int direction)
|
||||||
|
|
||||||
|
Maps a piece of processor virtual memory so it can be accessed by the
|
||||||
|
device and returns the physical handle of the memory.
|
||||||
|
|
||||||
|
The direction for both api's may be converted freely by casting.
|
||||||
|
However the dma_ API uses a strongly typed enumerator for its
|
||||||
|
direction:
|
||||||
|
|
||||||
|
DMA_NONE = PCI_DMA_NONE no direction (used for
|
||||||
|
debugging)
|
||||||
|
DMA_TO_DEVICE = PCI_DMA_TODEVICE data is going from the
|
||||||
|
memory to the device
|
||||||
|
DMA_FROM_DEVICE = PCI_DMA_FROMDEVICE data is coming from
|
||||||
|
the device to the
|
||||||
|
memory
|
||||||
|
DMA_BIDIRECTIONAL = PCI_DMA_BIDIRECTIONAL direction isn't known
|
||||||
|
|
||||||
|
Notes: Not all memory regions in a machine can be mapped by this
|
||||||
|
API. Further, regions that appear to be physically contiguous in
|
||||||
|
kernel virtual space may not be contiguous as physical memory. Since
|
||||||
|
this API does not provide any scatter/gather capability, it will fail
|
||||||
|
if the user tries to map a non-physically contiguous piece of memory.
|
||||||
|
For this reason, it is recommended that memory mapped by this API be
|
||||||
|
obtained only from sources which guarantee it to be physically contiguous
|
||||||
|
(like kmalloc).
|
||||||
|
|
||||||
|
Further, the physical address of the memory must be within the
|
||||||
|
dma_mask of the device (the dma_mask represents a bit mask of the
|
||||||
|
addressable region for the device. I.e., if the physical address of
|
||||||
|
the memory anded with the dma_mask is still equal to the physical
|
||||||
|
address, then the device can perform DMA to the memory). In order to
|
||||||
|
ensure that the memory allocated by kmalloc is within the dma_mask,
|
||||||
|
the driver may specify various platform-dependent flags to restrict
|
||||||
|
the physical memory range of the allocation (e.g. on x86, GFP_DMA
|
||||||
|
guarantees to be within the first 16Mb of available physical memory,
|
||||||
|
as required by ISA devices).
|
||||||
|
|
||||||
|
Note also that the above constraints on physical contiguity and
|
||||||
|
dma_mask may not apply if the platform has an IOMMU (a device which
|
||||||
|
supplies a physical to virtual mapping between the I/O memory bus and
|
||||||
|
the device). However, to be portable, device driver writers may *not*
|
||||||
|
assume that such an IOMMU exists.
|
||||||
|
|
||||||
|
Warnings: Memory coherency operates at a granularity called the cache
|
||||||
|
line width. In order for memory mapped by this API to operate
|
||||||
|
correctly, the mapped region must begin exactly on a cache line
|
||||||
|
boundary and end exactly on one (to prevent two separately mapped
|
||||||
|
regions from sharing a single cache line). Since the cache line size
|
||||||
|
may not be known at compile time, the API will not enforce this
|
||||||
|
requirement. Therefore, it is recommended that driver writers who
|
||||||
|
don't take special care to determine the cache line size at run time
|
||||||
|
only map virtual regions that begin and end on page boundaries (which
|
||||||
|
are guaranteed also to be cache line boundaries).
|
||||||
|
|
||||||
|
DMA_TO_DEVICE synchronisation must be done after the last modification
|
||||||
|
of the memory region by the software and before it is handed off to
|
||||||
|
the driver. Once this primitive is used, memory covered by this
|
||||||
|
primitive should be treated as read-only by the device. If the device
|
||||||
|
may write to it at any point, it should be DMA_BIDIRECTIONAL (see
|
||||||
|
below).
|
||||||
|
|
||||||
|
DMA_FROM_DEVICE synchronisation must be done before the driver
|
||||||
|
accesses data that may be changed by the device. This memory should
|
||||||
|
be treated as read-only by the driver. If the driver needs to write
|
||||||
|
to it at any point, it should be DMA_BIDIRECTIONAL (see below).
|
||||||
|
|
||||||
|
DMA_BIDIRECTIONAL requires special handling: it means that the driver
|
||||||
|
isn't sure if the memory was modified before being handed off to the
|
||||||
|
device and also isn't sure if the device will also modify it. Thus,
|
||||||
|
you must always sync bidirectional memory twice: once before the
|
||||||
|
memory is handed off to the device (to make sure all memory changes
|
||||||
|
are flushed from the processor) and once before the data may be
|
||||||
|
accessed after being used by the device (to make sure any processor
|
||||||
|
cache lines are updated with data that the device may have changed).
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
void
|
||||||
|
pci_unmap_single(struct pci_dev *hwdev, dma_addr_t dma_addr,
|
||||||
|
size_t size, int direction)
|
||||||
|
|
||||||
|
Unmaps the region previously mapped. All the parameters passed in
|
||||||
|
must be identical to those passed in (and returned) by the mapping
|
||||||
|
API.
|
||||||
|
|
||||||
|
dma_addr_t
|
||||||
|
dma_map_page(struct device *dev, struct page *page,
|
||||||
|
unsigned long offset, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
dma_addr_t
|
||||||
|
pci_map_page(struct pci_dev *hwdev, struct page *page,
|
||||||
|
unsigned long offset, size_t size, int direction)
|
||||||
|
void
|
||||||
|
dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
void
|
||||||
|
pci_unmap_page(struct pci_dev *hwdev, dma_addr_t dma_address,
|
||||||
|
size_t size, int direction)
|
||||||
|
|
||||||
|
API for mapping and unmapping for pages. All the notes and warnings
|
||||||
|
for the other mapping APIs apply here. Also, although the <offset>
|
||||||
|
and <size> parameters are provided to do partial page mapping, it is
|
||||||
|
recommended that you never use these unless you really know what the
|
||||||
|
cache width is.
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
|
||||||
|
|
||||||
|
int
|
||||||
|
pci_dma_mapping_error(struct pci_dev *hwdev, dma_addr_t dma_addr)
|
||||||
|
|
||||||
|
In some circumstances dma_map_single and dma_map_page will fail to create
|
||||||
|
a mapping. A driver can check for these errors by testing the returned
|
||||||
|
dma address with dma_mapping_error(). A non-zero return value means the mapping
|
||||||
|
could not be created and the driver should take appropriate action (e.g.
|
||||||
|
reduce current DMA mapping usage or delay and try again later).
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_map_sg(struct device *dev, struct scatterlist *sg,
|
||||||
|
int nents, enum dma_data_direction direction)
|
||||||
|
int
|
||||||
|
pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg,
|
||||||
|
int nents, int direction)
|
||||||
|
|
||||||
|
Returns: the number of physical segments mapped (this may be shorter
|
||||||
|
than <nents> passed in if some elements of the scatter/gather list are
|
||||||
|
physically or virtually adjacent and an IOMMU maps them with a single
|
||||||
|
entry).
|
||||||
|
|
||||||
|
Please note that the sg cannot be mapped again if it has been mapped once.
|
||||||
|
The mapping process is allowed to destroy information in the sg.
|
||||||
|
|
||||||
|
As with the other mapping interfaces, dma_map_sg can fail. When it
|
||||||
|
does, 0 is returned and a driver must take appropriate action. It is
|
||||||
|
critical that the driver do something, in the case of a block driver
|
||||||
|
aborting the request or even oopsing is better than doing nothing and
|
||||||
|
corrupting the filesystem.
|
||||||
|
|
||||||
|
With scatterlists, you use the resulting mapping like this:
|
||||||
|
|
||||||
|
int i, count = dma_map_sg(dev, sglist, nents, direction);
|
||||||
|
struct scatterlist *sg;
|
||||||
|
|
||||||
|
for_each_sg(sglist, sg, count, i) {
|
||||||
|
hw_address[i] = sg_dma_address(sg);
|
||||||
|
hw_len[i] = sg_dma_len(sg);
|
||||||
|
}
|
||||||
|
|
||||||
|
where nents is the number of entries in the sglist.
|
||||||
|
|
||||||
|
The implementation is free to merge several consecutive sglist entries
|
||||||
|
into one (e.g. with an IOMMU, or if several pages just happen to be
|
||||||
|
physically contiguous) and returns the actual number of sg entries it
|
||||||
|
mapped them to. On failure 0, is returned.
|
||||||
|
|
||||||
|
Then you should loop count times (note: this can be less than nents times)
|
||||||
|
and use sg_dma_address() and sg_dma_len() macros where you previously
|
||||||
|
accessed sg->address and sg->length as shown above.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_unmap_sg(struct device *dev, struct scatterlist *sg,
|
||||||
|
int nhwentries, enum dma_data_direction direction)
|
||||||
|
void
|
||||||
|
pci_unmap_sg(struct pci_dev *hwdev, struct scatterlist *sg,
|
||||||
|
int nents, int direction)
|
||||||
|
|
||||||
|
Unmap the previously mapped scatter/gather list. All the parameters
|
||||||
|
must be the same as those and passed in to the scatter/gather mapping
|
||||||
|
API.
|
||||||
|
|
||||||
|
Note: <nents> must be the number you passed in, *not* the number of
|
||||||
|
physical entries returned.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_sync_single(struct device *dev, dma_addr_t dma_handle, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
void
|
||||||
|
pci_dma_sync_single(struct pci_dev *hwdev, dma_addr_t dma_handle,
|
||||||
|
size_t size, int direction)
|
||||||
|
void
|
||||||
|
dma_sync_sg(struct device *dev, struct scatterlist *sg, int nelems,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
void
|
||||||
|
pci_dma_sync_sg(struct pci_dev *hwdev, struct scatterlist *sg,
|
||||||
|
int nelems, int direction)
|
||||||
|
|
||||||
|
Synchronise a single contiguous or scatter/gather mapping. All the
|
||||||
|
parameters must be the same as those passed into the single mapping
|
||||||
|
API.
|
||||||
|
|
||||||
|
Notes: You must do this:
|
||||||
|
|
||||||
|
- Before reading values that have been written by DMA from the device
|
||||||
|
(use the DMA_FROM_DEVICE direction)
|
||||||
|
- After writing values that will be written to the device using DMA
|
||||||
|
(use the DMA_TO_DEVICE) direction
|
||||||
|
- before *and* after handing memory to the device if the memory is
|
||||||
|
DMA_BIDIRECTIONAL
|
||||||
|
|
||||||
|
See also dma_map_single().
|
||||||
|
|
||||||
|
dma_addr_t
|
||||||
|
dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
|
||||||
|
enum dma_data_direction dir,
|
||||||
|
struct dma_attrs *attrs)
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
|
||||||
|
size_t size, enum dma_data_direction dir,
|
||||||
|
struct dma_attrs *attrs)
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
|
||||||
|
int nents, enum dma_data_direction dir,
|
||||||
|
struct dma_attrs *attrs)
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
|
||||||
|
int nents, enum dma_data_direction dir,
|
||||||
|
struct dma_attrs *attrs)
|
||||||
|
|
||||||
|
The four functions above are just like the counterpart functions
|
||||||
|
without the _attrs suffixes, except that they pass an optional
|
||||||
|
struct dma_attrs*.
|
||||||
|
|
||||||
|
struct dma_attrs encapsulates a set of "dma attributes". For the
|
||||||
|
definition of struct dma_attrs see linux/dma-attrs.h.
|
||||||
|
|
||||||
|
The interpretation of dma attributes is architecture-specific, and
|
||||||
|
each attribute should be documented in Documentation/DMA-attributes.txt.
|
||||||
|
|
||||||
|
If struct dma_attrs* is NULL, the semantics of each of these
|
||||||
|
functions is identical to those of the corresponding function
|
||||||
|
without the _attrs suffix. As a result dma_map_single_attrs()
|
||||||
|
can generally replace dma_map_single(), etc.
|
||||||
|
|
||||||
|
As an example of the use of the *_attrs functions, here's how
|
||||||
|
you could pass an attribute DMA_ATTR_FOO when mapping memory
|
||||||
|
for DMA:
|
||||||
|
|
||||||
|
#include <linux/dma-attrs.h>
|
||||||
|
/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
|
||||||
|
* documented in Documentation/DMA-attributes.txt */
|
||||||
|
...
|
||||||
|
|
||||||
|
DEFINE_DMA_ATTRS(attrs);
|
||||||
|
dma_set_attr(DMA_ATTR_FOO, &attrs);
|
||||||
|
....
|
||||||
|
n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
|
||||||
|
....
|
||||||
|
|
||||||
|
Architectures that care about DMA_ATTR_FOO would check for its
|
||||||
|
presence in their implementations of the mapping and unmapping
|
||||||
|
routines, e.g.:
|
||||||
|
|
||||||
|
void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
|
||||||
|
size_t size, enum dma_data_direction dir,
|
||||||
|
struct dma_attrs *attrs)
|
||||||
|
{
|
||||||
|
....
|
||||||
|
int foo = dma_get_attr(DMA_ATTR_FOO, attrs);
|
||||||
|
....
|
||||||
|
if (foo)
|
||||||
|
/* twizzle the frobnozzle */
|
||||||
|
....
|
||||||
|
|
||||||
|
|
||||||
|
Part II - Advanced dma_ usage
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Warning: These pieces of the DMA API have no PCI equivalent. They
|
||||||
|
should also not be used in the majority of cases, since they cater for
|
||||||
|
unlikely corner cases that don't belong in usual drivers.
|
||||||
|
|
||||||
|
If you don't understand how cache line coherency works between a
|
||||||
|
processor and an I/O device, you should not be using this part of the
|
||||||
|
API at all.
|
||||||
|
|
||||||
|
void *
|
||||||
|
dma_alloc_noncoherent(struct device *dev, size_t size,
|
||||||
|
dma_addr_t *dma_handle, gfp_t flag)
|
||||||
|
|
||||||
|
Identical to dma_alloc_coherent() except that the platform will
|
||||||
|
choose to return either consistent or non-consistent memory as it sees
|
||||||
|
fit. By using this API, you are guaranteeing to the platform that you
|
||||||
|
have all the correct and necessary sync points for this memory in the
|
||||||
|
driver should it choose to return non-consistent memory.
|
||||||
|
|
||||||
|
Note: where the platform can return consistent memory, it will
|
||||||
|
guarantee that the sync points become nops.
|
||||||
|
|
||||||
|
Warning: Handling non-consistent memory is a real pain. You should
|
||||||
|
only ever use this API if you positively know your driver will be
|
||||||
|
required to work on one of the rare (usually non-PCI) architectures
|
||||||
|
that simply cannot make consistent memory.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
|
||||||
|
dma_addr_t dma_handle)
|
||||||
|
|
||||||
|
Free memory allocated by the nonconsistent API. All parameters must
|
||||||
|
be identical to those passed in (and returned by
|
||||||
|
dma_alloc_noncoherent()).
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_is_consistent(struct device *dev, dma_addr_t dma_handle)
|
||||||
|
|
||||||
|
Returns true if the device dev is performing consistent DMA on the memory
|
||||||
|
area pointed to by the dma_handle.
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_get_cache_alignment(void)
|
||||||
|
|
||||||
|
Returns the processor cache alignment. This is the absolute minimum
|
||||||
|
alignment *and* width that you must observe when either mapping
|
||||||
|
memory or doing partial flushes.
|
||||||
|
|
||||||
|
Notes: This API may return a number *larger* than the actual cache
|
||||||
|
line, but it will guarantee that one or more cache lines fit exactly
|
||||||
|
into the width returned by this call. It will also always be a power
|
||||||
|
of two for easy alignment.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,
|
||||||
|
unsigned long offset, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
|
||||||
|
Does a partial sync, starting at offset and continuing for size. You
|
||||||
|
must be careful to observe the cache alignment and width when doing
|
||||||
|
anything like this. You must also be extra careful about accessing
|
||||||
|
memory you intend to sync partially.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_cache_sync(struct device *dev, void *vaddr, size_t size,
|
||||||
|
enum dma_data_direction direction)
|
||||||
|
|
||||||
|
Do a partial sync of memory that was allocated by
|
||||||
|
dma_alloc_noncoherent(), starting at virtual address vaddr and
|
||||||
|
continuing on for size. Again, you *must* observe the cache line
|
||||||
|
boundaries when doing this.
|
||||||
|
|
||||||
|
int
|
||||||
|
dma_declare_coherent_memory(struct device *dev, dma_addr_t bus_addr,
|
||||||
|
dma_addr_t device_addr, size_t size, int
|
||||||
|
flags)
|
||||||
|
|
||||||
|
Declare region of memory to be handed out by dma_alloc_coherent when
|
||||||
|
it's asked for coherent memory for this device.
|
||||||
|
|
||||||
|
bus_addr is the physical address to which the memory is currently
|
||||||
|
assigned in the bus responding region (this will be used by the
|
||||||
|
platform to perform the mapping).
|
||||||
|
|
||||||
|
device_addr is the physical address the device needs to be programmed
|
||||||
|
with actually to address this memory (this will be handed out as the
|
||||||
|
dma_addr_t in dma_alloc_coherent()).
|
||||||
|
|
||||||
|
size is the size of the area (must be multiples of PAGE_SIZE).
|
||||||
|
|
||||||
|
flags can be or'd together and are:
|
||||||
|
|
||||||
|
DMA_MEMORY_MAP - request that the memory returned from
|
||||||
|
dma_alloc_coherent() be directly writable.
|
||||||
|
|
||||||
|
DMA_MEMORY_IO - request that the memory returned from
|
||||||
|
dma_alloc_coherent() be addressable using read/write/memcpy_toio etc.
|
||||||
|
|
||||||
|
One or both of these flags must be present.
|
||||||
|
|
||||||
|
DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
|
||||||
|
dma_alloc_coherent of any child devices of this one (for memory residing
|
||||||
|
on a bridge).
|
||||||
|
|
||||||
|
DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
|
||||||
|
Do not allow dma_alloc_coherent() to fall back to system memory when
|
||||||
|
it's out of memory in the declared region.
|
||||||
|
|
||||||
|
The return value will be either DMA_MEMORY_MAP or DMA_MEMORY_IO and
|
||||||
|
must correspond to a passed in flag (i.e. no returning DMA_MEMORY_IO
|
||||||
|
if only DMA_MEMORY_MAP were passed in) for success or zero for
|
||||||
|
failure.
|
||||||
|
|
||||||
|
Note, for DMA_MEMORY_IO returns, all subsequent memory returned by
|
||||||
|
dma_alloc_coherent() may no longer be accessed directly, but instead
|
||||||
|
must be accessed using the correct bus functions. If your driver
|
||||||
|
isn't prepared to handle this contingency, it should not specify
|
||||||
|
DMA_MEMORY_IO in the input flags.
|
||||||
|
|
||||||
|
As a simplification for the platforms, only *one* such region of
|
||||||
|
memory may be declared per device.
|
||||||
|
|
||||||
|
For reasons of efficiency, most platforms choose to track the declared
|
||||||
|
region only at the granularity of a page. For smaller allocations,
|
||||||
|
you should use the dma_pool() API.
|
||||||
|
|
||||||
|
void
|
||||||
|
dma_release_declared_memory(struct device *dev)
|
||||||
|
|
||||||
|
Remove the memory region previously declared from the system. This
|
||||||
|
API performs *no* in-use checking for this region and will return
|
||||||
|
unconditionally having removed all the required structures. It is the
|
||||||
|
driver's job to ensure that no parts of this memory region are
|
||||||
|
currently in use.
|
||||||
|
|
||||||
|
void *
|
||||||
|
dma_mark_declared_memory_occupied(struct device *dev,
|
||||||
|
dma_addr_t device_addr, size_t size)
|
||||||
|
|
||||||
|
This is used to occupy specific regions of the declared space
|
||||||
|
(dma_alloc_coherent() will hand out the first free region it finds).
|
||||||
|
|
||||||
|
device_addr is the *device* address of the region requested.
|
||||||
|
|
||||||
|
size is the size (and should be a page-sized multiple).
|
||||||
|
|
||||||
|
The return value will be either a pointer to the processor virtual
|
||||||
|
address of the memory, or an error (via PTR_ERR()) if any part of the
|
||||||
|
region is occupied.
|
||||||
|
|
||||||
|
Part III - Debug drivers use of the DMA-API
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
The DMA-API as described above as some constraints. DMA addresses must be
|
||||||
|
released with the corresponding function with the same size for example. With
|
||||||
|
the advent of hardware IOMMUs it becomes more and more important that drivers
|
||||||
|
do not violate those constraints. In the worst case such a violation can
|
||||||
|
result in data corruption up to destroyed filesystems.
|
||||||
|
|
||||||
|
To debug drivers and find bugs in the usage of the DMA-API checking code can
|
||||||
|
be compiled into the kernel which will tell the developer about those
|
||||||
|
violations. If your architecture supports it you can select the "Enable
|
||||||
|
debugging of DMA-API usage" option in your kernel configuration. Enabling this
|
||||||
|
option has a performance impact. Do not enable it in production kernels.
|
||||||
|
|
||||||
|
If you boot the resulting kernel will contain code which does some bookkeeping
|
||||||
|
about what DMA memory was allocated for which device. If this code detects an
|
||||||
|
error it prints a warning message with some details into your kernel log. An
|
||||||
|
example warning message may look like this:
|
||||||
|
|
||||||
|
------------[ cut here ]------------
|
||||||
|
WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
|
||||||
|
check_unmap+0x203/0x490()
|
||||||
|
Hardware name:
|
||||||
|
forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
|
||||||
|
function [device address=0x00000000640444be] [size=66 bytes] [mapped as
|
||||||
|
single] [unmapped as page]
|
||||||
|
Modules linked in: nfsd exportfs bridge stp llc r8169
|
||||||
|
Pid: 0, comm: swapper Tainted: G W 2.6.28-dmatest-09289-g8bb99c0 #1
|
||||||
|
Call Trace:
|
||||||
|
<IRQ> [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
|
||||||
|
[<ffffffff80647b70>] _spin_unlock+0x10/0x30
|
||||||
|
[<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
|
||||||
|
[<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
|
||||||
|
[<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
|
||||||
|
[<ffffffff80252f96>] queue_work+0x56/0x60
|
||||||
|
[<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
|
||||||
|
[<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
|
||||||
|
[<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
|
||||||
|
[<ffffffff80235177>] find_busiest_group+0x207/0x8a0
|
||||||
|
[<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
|
||||||
|
[<ffffffff803c7ea3>] check_unmap+0x203/0x490
|
||||||
|
[<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
|
||||||
|
[<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
|
||||||
|
[<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
|
||||||
|
[<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
|
||||||
|
[<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
|
||||||
|
[<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
|
||||||
|
[<ffffffff8020c093>] ret_from_intr+0x0/0xa
|
||||||
|
<EOI> <4>---[ end trace f6435a98e2a38c0e ]---
|
||||||
|
|
||||||
|
The driver developer can find the driver and the device including a stacktrace
|
||||||
|
of the DMA-API call which caused this warning.
|
||||||
|
|
||||||
|
Per default only the first error will result in a warning message. All other
|
||||||
|
errors will only silently counted. This limitation exist to prevent the code
|
||||||
|
from flooding your kernel log. To support debugging a device driver this can
|
||||||
|
be disabled via debugfs. See the debugfs interface documentation below for
|
||||||
|
details.
|
||||||
|
|
||||||
|
The debugfs directory for the DMA-API debugging code is called dma-api/. In
|
||||||
|
this directory the following files can currently be found:
|
||||||
|
|
||||||
|
dma-api/all_errors This file contains a numeric value. If this
|
||||||
|
value is not equal to zero the debugging code
|
||||||
|
will print a warning for every error it finds
|
||||||
|
into the kernel log. Be careful with this
|
||||||
|
option, as it can easily flood your logs.
|
||||||
|
|
||||||
|
dma-api/disabled This read-only file contains the character 'Y'
|
||||||
|
if the debugging code is disabled. This can
|
||||||
|
happen when it runs out of memory or if it was
|
||||||
|
disabled at boot time
|
||||||
|
|
||||||
|
dma-api/error_count This file is read-only and shows the total
|
||||||
|
numbers of errors found.
|
||||||
|
|
||||||
|
dma-api/num_errors The number in this file shows how many
|
||||||
|
warnings will be printed to the kernel log
|
||||||
|
before it stops. This number is initialized to
|
||||||
|
one at system boot and be set by writing into
|
||||||
|
this file
|
||||||
|
|
||||||
|
dma-api/min_free_entries
|
||||||
|
This read-only file can be read to get the
|
||||||
|
minimum number of free dma_debug_entries the
|
||||||
|
allocator has ever seen. If this value goes
|
||||||
|
down to zero the code will disable itself
|
||||||
|
because it is not longer reliable.
|
||||||
|
|
||||||
|
dma-api/num_free_entries
|
||||||
|
The current number of free dma_debug_entries
|
||||||
|
in the allocator.
|
||||||
|
|
||||||
|
dma-api/driver-filter
|
||||||
|
You can write a name of a driver into this file
|
||||||
|
to limit the debug output to requests from that
|
||||||
|
particular driver. Write an empty string to
|
||||||
|
that file to disable the filter and see
|
||||||
|
all errors again.
|
||||||
|
|
||||||
|
If you have this code compiled into your kernel it will be enabled by default.
|
||||||
|
If you want to boot without the bookkeeping anyway you can provide
|
||||||
|
'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
|
||||||
|
Notice that you can not enable it again at runtime. You have to reboot to do
|
||||||
|
so.
|
||||||
|
|
||||||
|
If you want to see debug messages only for a special device driver you can
|
||||||
|
specify the dma_debug_driver=<drivername> parameter. This will enable the
|
||||||
|
driver filter at boot time. The debug code will only print errors for that
|
||||||
|
driver afterwards. This filter can be disabled or changed later using debugfs.
|
||||||
|
|
||||||
|
When the code disables itself at runtime this is most likely because it ran
|
||||||
|
out of dma_debug_entries. These entries are preallocated at boot. The number
|
||||||
|
of preallocated entries is defined per architecture. If it is too low for you
|
||||||
|
boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
|
||||||
|
architectural default.
|
|
@ -0,0 +1,151 @@
|
||||||
|
DMA with ISA and LPC devices
|
||||||
|
============================
|
||||||
|
|
||||||
|
Pierre Ossman <drzeus@drzeus.cx>
|
||||||
|
|
||||||
|
This document describes how to do DMA transfers using the old ISA DMA
|
||||||
|
controller. Even though ISA is more or less dead today the LPC bus
|
||||||
|
uses the same DMA system so it will be around for quite some time.
|
||||||
|
|
||||||
|
Part I - Headers and dependencies
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
To do ISA style DMA you need to include two headers:
|
||||||
|
|
||||||
|
#include <linux/dma-mapping.h>
|
||||||
|
#include <asm/dma.h>
|
||||||
|
|
||||||
|
The first is the generic DMA API used to convert virtual addresses to
|
||||||
|
physical addresses (see Documentation/DMA-API.txt for details).
|
||||||
|
|
||||||
|
The second contains the routines specific to ISA DMA transfers. Since
|
||||||
|
this is not present on all platforms make sure you construct your
|
||||||
|
Kconfig to be dependent on ISA_DMA_API (not ISA) so that nobody tries
|
||||||
|
to build your driver on unsupported platforms.
|
||||||
|
|
||||||
|
Part II - Buffer allocation
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The ISA DMA controller has some very strict requirements on which
|
||||||
|
memory it can access so extra care must be taken when allocating
|
||||||
|
buffers.
|
||||||
|
|
||||||
|
(You usually need a special buffer for DMA transfers instead of
|
||||||
|
transferring directly to and from your normal data structures.)
|
||||||
|
|
||||||
|
The DMA-able address space is the lowest 16 MB of _physical_ memory.
|
||||||
|
Also the transfer block may not cross page boundaries (which are 64
|
||||||
|
or 128 KiB depending on which channel you use).
|
||||||
|
|
||||||
|
In order to allocate a piece of memory that satisfies all these
|
||||||
|
requirements you pass the flag GFP_DMA to kmalloc.
|
||||||
|
|
||||||
|
Unfortunately the memory available for ISA DMA is scarce so unless you
|
||||||
|
allocate the memory during boot-up it's a good idea to also pass
|
||||||
|
__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.
|
||||||
|
|
||||||
|
(This scarcity also means that you should allocate the buffer as
|
||||||
|
early as possible and not release it until the driver is unloaded.)
|
||||||
|
|
||||||
|
Part III - Address translation
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
To translate the virtual address to a physical use the normal DMA
|
||||||
|
API. Do _not_ use isa_virt_to_phys() even though it does the same
|
||||||
|
thing. The reason for this is that the function isa_virt_to_phys()
|
||||||
|
will require a Kconfig dependency to ISA, not just ISA_DMA_API which
|
||||||
|
is really all you need. Remember that even though the DMA controller
|
||||||
|
has its origins in ISA it is used elsewhere.
|
||||||
|
|
||||||
|
Note: x86_64 had a broken DMA API when it came to ISA but has since
|
||||||
|
been fixed. If your arch has problems then fix the DMA API instead of
|
||||||
|
reverting to the ISA functions.
|
||||||
|
|
||||||
|
Part IV - Channels
|
||||||
|
------------------
|
||||||
|
|
||||||
|
A normal ISA DMA controller has 8 channels. The lower four are for
|
||||||
|
8-bit transfers and the upper four are for 16-bit transfers.
|
||||||
|
|
||||||
|
(Actually the DMA controller is really two separate controllers where
|
||||||
|
channel 4 is used to give DMA access for the second controller (0-3).
|
||||||
|
This means that of the four 16-bits channels only three are usable.)
|
||||||
|
|
||||||
|
You allocate these in a similar fashion as all basic resources:
|
||||||
|
|
||||||
|
extern int request_dma(unsigned int dmanr, const char * device_id);
|
||||||
|
extern void free_dma(unsigned int dmanr);
|
||||||
|
|
||||||
|
The ability to use 16-bit or 8-bit transfers is _not_ up to you as a
|
||||||
|
driver author but depends on what the hardware supports. Check your
|
||||||
|
specs or test different channels.
|
||||||
|
|
||||||
|
Part V - Transfer data
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Now for the good stuff, the actual DMA transfer. :)
|
||||||
|
|
||||||
|
Before you use any ISA DMA routines you need to claim the DMA lock
|
||||||
|
using claim_dma_lock(). The reason is that some DMA operations are
|
||||||
|
not atomic so only one driver may fiddle with the registers at a
|
||||||
|
time.
|
||||||
|
|
||||||
|
The first time you use the DMA controller you should call
|
||||||
|
clear_dma_ff(). This clears an internal register in the DMA
|
||||||
|
controller that is used for the non-atomic operations. As long as you
|
||||||
|
(and everyone else) uses the locking functions then you only need to
|
||||||
|
reset this once.
|
||||||
|
|
||||||
|
Next, you tell the controller in which direction you intend to do the
|
||||||
|
transfer using set_dma_mode(). Currently you have the options
|
||||||
|
DMA_MODE_READ and DMA_MODE_WRITE.
|
||||||
|
|
||||||
|
Set the address from where the transfer should start (this needs to
|
||||||
|
be 16-bit aligned for 16-bit transfers) and how many bytes to
|
||||||
|
transfer. Note that it's _bytes_. The DMA routines will do all the
|
||||||
|
required translation to values that the DMA controller understands.
|
||||||
|
|
||||||
|
The final step is enabling the DMA channel and releasing the DMA
|
||||||
|
lock.
|
||||||
|
|
||||||
|
Once the DMA transfer is finished (or timed out) you should disable
|
||||||
|
the channel again. You should also check get_dma_residue() to make
|
||||||
|
sure that all data has been transferred.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
int flags, residue;
|
||||||
|
|
||||||
|
flags = claim_dma_lock();
|
||||||
|
|
||||||
|
clear_dma_ff();
|
||||||
|
|
||||||
|
set_dma_mode(channel, DMA_MODE_WRITE);
|
||||||
|
set_dma_addr(channel, phys_addr);
|
||||||
|
set_dma_count(channel, num_bytes);
|
||||||
|
|
||||||
|
dma_enable(channel);
|
||||||
|
|
||||||
|
release_dma_lock(flags);
|
||||||
|
|
||||||
|
while (!device_done());
|
||||||
|
|
||||||
|
flags = claim_dma_lock();
|
||||||
|
|
||||||
|
dma_disable(channel);
|
||||||
|
|
||||||
|
residue = dma_get_residue(channel);
|
||||||
|
if (residue != 0)
|
||||||
|
printk(KERN_ERR "driver: Incomplete DMA transfer!"
|
||||||
|
" %d bytes left!\n", residue);
|
||||||
|
|
||||||
|
release_dma_lock(flags);
|
||||||
|
|
||||||
|
Part VI - Suspend/resume
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
It is the driver's responsibility to make sure that the machine isn't
|
||||||
|
suspended while a DMA transfer is in progress. Also, all DMA settings
|
||||||
|
are lost when the system suspends so if your driver relies on the DMA
|
||||||
|
controller being in a certain state then you have to restore these
|
||||||
|
registers upon resume.
|
|
@ -0,0 +1,33 @@
|
||||||
|
DMA attributes
|
||||||
|
==============
|
||||||
|
|
||||||
|
This document describes the semantics of the DMA attributes that are
|
||||||
|
defined in linux/dma-attrs.h.
|
||||||
|
|
||||||
|
DMA_ATTR_WRITE_BARRIER
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA. DMA
|
||||||
|
to a memory region with the DMA_ATTR_WRITE_BARRIER attribute forces
|
||||||
|
all pending DMA writes to complete, and thus provides a mechanism to
|
||||||
|
strictly order DMA from a device across all intervening busses and
|
||||||
|
bridges. This barrier is not specific to a particular type of
|
||||||
|
interconnect, it applies to the system as a whole, and so its
|
||||||
|
implementation must account for the idiosyncracies of the system all
|
||||||
|
the way from the DMA device to memory.
|
||||||
|
|
||||||
|
As an example of a situation where DMA_ATTR_WRITE_BARRIER would be
|
||||||
|
useful, suppose that a device does a DMA write to indicate that data is
|
||||||
|
ready and available in memory. The DMA of the "completion indication"
|
||||||
|
could race with data DMA. Mapping the memory used for completion
|
||||||
|
indications with DMA_ATTR_WRITE_BARRIER would prevent the race.
|
||||||
|
|
||||||
|
DMA_ATTR_WEAK_ORDERING
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mapping
|
||||||
|
may be weakly ordered, that is that reads and writes may pass each other.
|
||||||
|
|
||||||
|
Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING,
|
||||||
|
those that do not will simply ignore the attribute and exhibit default
|
||||||
|
behavior.
|
|
@ -0,0 +1,766 @@
|
||||||
|
Dynamic DMA mapping
|
||||||
|
===================
|
||||||
|
|
||||||
|
David S. Miller <davem@redhat.com>
|
||||||
|
Richard Henderson <rth@cygnus.com>
|
||||||
|
Jakub Jelinek <jakub@redhat.com>
|
||||||
|
|
||||||
|
This document describes the DMA mapping system in terms of the pci_
|
||||||
|
API. For a similar API that works for generic devices, see
|
||||||
|
DMA-API.txt.
|
||||||
|
|
||||||
|
Most of the 64bit platforms have special hardware that translates bus
|
||||||
|
addresses (DMA addresses) into physical addresses. This is similar to
|
||||||
|
how page tables and/or a TLB translates virtual addresses to physical
|
||||||
|
addresses on a CPU. This is needed so that e.g. PCI devices can
|
||||||
|
access with a Single Address Cycle (32bit DMA address) any page in the
|
||||||
|
64bit physical address space. Previously in Linux those 64bit
|
||||||
|
platforms had to set artificial limits on the maximum RAM size in the
|
||||||
|
system, so that the virt_to_bus() static scheme works (the DMA address
|
||||||
|
translation tables were simply filled on bootup to map each bus
|
||||||
|
address to the physical page __pa(bus_to_virt())).
|
||||||
|
|
||||||
|
So that Linux can use the dynamic DMA mapping, it needs some help from the
|
||||||
|
drivers, namely it has to take into account that DMA addresses should be
|
||||||
|
mapped only for the time they are actually used and unmapped after the DMA
|
||||||
|
transfer.
|
||||||
|
|
||||||
|
The following API will work of course even on platforms where no such
|
||||||
|
hardware exists, see e.g. arch/x86/include/asm/pci.h for how it is implemented on
|
||||||
|
top of the virt_to_bus interface.
|
||||||
|
|
||||||
|
First of all, you should make sure
|
||||||
|
|
||||||
|
#include <linux/pci.h>
|
||||||
|
|
||||||
|
is in your driver. This file will obtain for you the definition of the
|
||||||
|
dma_addr_t (which can hold any valid DMA address for the platform)
|
||||||
|
type which should be used everywhere you hold a DMA (bus) address
|
||||||
|
returned from the DMA mapping functions.
|
||||||
|
|
||||||
|
What memory is DMA'able?
|
||||||
|
|
||||||
|
The first piece of information you must know is what kernel memory can
|
||||||
|
be used with the DMA mapping facilities. There has been an unwritten
|
||||||
|
set of rules regarding this, and this text is an attempt to finally
|
||||||
|
write them down.
|
||||||
|
|
||||||
|
If you acquired your memory via the page allocator
|
||||||
|
(i.e. __get_free_page*()) or the generic memory allocators
|
||||||
|
(i.e. kmalloc() or kmem_cache_alloc()) then you may DMA to/from
|
||||||
|
that memory using the addresses returned from those routines.
|
||||||
|
|
||||||
|
This means specifically that you may _not_ use the memory/addresses
|
||||||
|
returned from vmalloc() for DMA. It is possible to DMA to the
|
||||||
|
_underlying_ memory mapped into a vmalloc() area, but this requires
|
||||||
|
walking page tables to get the physical addresses, and then
|
||||||
|
translating each of those pages back to a kernel address using
|
||||||
|
something like __va(). [ EDIT: Update this when we integrate
|
||||||
|
Gerd Knorr's generic code which does this. ]
|
||||||
|
|
||||||
|
This rule also means that you may use neither kernel image addresses
|
||||||
|
(items in data/text/bss segments), nor module image addresses, nor
|
||||||
|
stack addresses for DMA. These could all be mapped somewhere entirely
|
||||||
|
different than the rest of physical memory. Even if those classes of
|
||||||
|
memory could physically work with DMA, you'd need to ensure the I/O
|
||||||
|
buffers were cacheline-aligned. Without that, you'd see cacheline
|
||||||
|
sharing problems (data corruption) on CPUs with DMA-incoherent caches.
|
||||||
|
(The CPU could write to one word, DMA would write to a different one
|
||||||
|
in the same cache line, and one of them could be overwritten.)
|
||||||
|
|
||||||
|
Also, this means that you cannot take the return of a kmap()
|
||||||
|
call and DMA to/from that. This is similar to vmalloc().
|
||||||
|
|
||||||
|
What about block I/O and networking buffers? The block I/O and
|
||||||
|
networking subsystems make sure that the buffers they use are valid
|
||||||
|
for you to DMA from/to.
|
||||||
|
|
||||||
|
DMA addressing limitations
|
||||||
|
|
||||||
|
Does your device have any DMA addressing limitations? For example, is
|
||||||
|
your device only capable of driving the low order 24-bits of address
|
||||||
|
on the PCI bus for SAC DMA transfers? If so, you need to inform the
|
||||||
|
PCI layer of this fact.
|
||||||
|
|
||||||
|
By default, the kernel assumes that your device can address the full
|
||||||
|
32-bits in a SAC cycle. For a 64-bit DAC capable device, this needs
|
||||||
|
to be increased. And for a device with limitations, as discussed in
|
||||||
|
the previous paragraph, it needs to be decreased.
|
||||||
|
|
||||||
|
pci_alloc_consistent() by default will return 32-bit DMA addresses.
|
||||||
|
PCI-X specification requires PCI-X devices to support 64-bit
|
||||||
|
addressing (DAC) for all transactions. And at least one platform (SGI
|
||||||
|
SN2) requires 64-bit consistent allocations to operate correctly when
|
||||||
|
the IO bus is in PCI-X mode. Therefore, like with pci_set_dma_mask(),
|
||||||
|
it's good practice to call pci_set_consistent_dma_mask() to set the
|
||||||
|
appropriate mask even if your device only supports 32-bit DMA
|
||||||
|
(default) and especially if it's a PCI-X device.
|
||||||
|
|
||||||
|
For correct operation, you must interrogate the PCI layer in your
|
||||||
|
device probe routine to see if the PCI controller on the machine can
|
||||||
|
properly support the DMA addressing limitation your device has. It is
|
||||||
|
good style to do this even if your device holds the default setting,
|
||||||
|
because this shows that you did think about these issues wrt. your
|
||||||
|
device.
|
||||||
|
|
||||||
|
The query is performed via a call to pci_set_dma_mask():
|
||||||
|
|
||||||
|
int pci_set_dma_mask(struct pci_dev *pdev, u64 device_mask);
|
||||||
|
|
||||||
|
The query for consistent allocations is performed via a call to
|
||||||
|
pci_set_consistent_dma_mask():
|
||||||
|
|
||||||
|
int pci_set_consistent_dma_mask(struct pci_dev *pdev, u64 device_mask);
|
||||||
|
|
||||||
|
Here, pdev is a pointer to the PCI device struct of your device, and
|
||||||
|
device_mask is a bit mask describing which bits of a PCI address your
|
||||||
|
device supports. It returns zero if your card can perform DMA
|
||||||
|
properly on the machine given the address mask you provided.
|
||||||
|
|
||||||
|
If it returns non-zero, your device cannot perform DMA properly on
|
||||||
|
this platform, and attempting to do so will result in undefined
|
||||||
|
behavior. You must either use a different mask, or not use DMA.
|
||||||
|
|
||||||
|
This means that in the failure case, you have three options:
|
||||||
|
|
||||||
|
1) Use another DMA mask, if possible (see below).
|
||||||
|
2) Use some non-DMA mode for data transfer, if possible.
|
||||||
|
3) Ignore this device and do not initialize it.
|
||||||
|
|
||||||
|
It is recommended that your driver print a kernel KERN_WARNING message
|
||||||
|
when you end up performing either #2 or #3. In this manner, if a user
|
||||||
|
of your driver reports that performance is bad or that the device is not
|
||||||
|
even detected, you can ask them for the kernel messages to find out
|
||||||
|
exactly why.
|
||||||
|
|
||||||
|
The standard 32-bit addressing PCI device would do something like
|
||||||
|
this:
|
||||||
|
|
||||||
|
if (pci_set_dma_mask(pdev, DMA_BIT_MASK(32))) {
|
||||||
|
printk(KERN_WARNING
|
||||||
|
"mydev: No suitable DMA available.\n");
|
||||||
|
goto ignore_this_device;
|
||||||
|
}
|
||||||
|
|
||||||
|
Another common scenario is a 64-bit capable device. The approach
|
||||||
|
here is to try for 64-bit DAC addressing, but back down to a
|
||||||
|
32-bit mask should that fail. The PCI platform code may fail the
|
||||||
|
64-bit mask not because the platform is not capable of 64-bit
|
||||||
|
addressing. Rather, it may fail in this case simply because
|
||||||
|
32-bit SAC addressing is done more efficiently than DAC addressing.
|
||||||
|
Sparc64 is one platform which behaves in this way.
|
||||||
|
|
||||||
|
Here is how you would handle a 64-bit capable device which can drive
|
||||||
|
all 64-bits when accessing streaming DMA:
|
||||||
|
|
||||||
|
int using_dac;
|
||||||
|
|
||||||
|
if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(64))) {
|
||||||
|
using_dac = 1;
|
||||||
|
} else if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(32))) {
|
||||||
|
using_dac = 0;
|
||||||
|
} else {
|
||||||
|
printk(KERN_WARNING
|
||||||
|
"mydev: No suitable DMA available.\n");
|
||||||
|
goto ignore_this_device;
|
||||||
|
}
|
||||||
|
|
||||||
|
If a card is capable of using 64-bit consistent allocations as well,
|
||||||
|
the case would look like this:
|
||||||
|
|
||||||
|
int using_dac, consistent_using_dac;
|
||||||
|
|
||||||
|
if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(64))) {
|
||||||
|
using_dac = 1;
|
||||||
|
consistent_using_dac = 1;
|
||||||
|
pci_set_consistent_dma_mask(pdev, DMA_BIT_MASK(64));
|
||||||
|
} else if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(32))) {
|
||||||
|
using_dac = 0;
|
||||||
|
consistent_using_dac = 0;
|
||||||
|
pci_set_consistent_dma_mask(pdev, DMA_BIT_MASK(32));
|
||||||
|
} else {
|
||||||
|
printk(KERN_WARNING
|
||||||
|
"mydev: No suitable DMA available.\n");
|
||||||
|
goto ignore_this_device;
|
||||||
|
}
|
||||||
|
|
||||||
|
pci_set_consistent_dma_mask() will always be able to set the same or a
|
||||||
|
smaller mask as pci_set_dma_mask(). However for the rare case that a
|
||||||
|
device driver only uses consistent allocations, one would have to
|
||||||
|
check the return value from pci_set_consistent_dma_mask().
|
||||||
|
|
||||||
|
Finally, if your device can only drive the low 24-bits of
|
||||||
|
address during PCI bus mastering you might do something like:
|
||||||
|
|
||||||
|
if (pci_set_dma_mask(pdev, DMA_BIT_MASK(24))) {
|
||||||
|
printk(KERN_WARNING
|
||||||
|
"mydev: 24-bit DMA addressing not available.\n");
|
||||||
|
goto ignore_this_device;
|
||||||
|
}
|
||||||
|
|
||||||
|
When pci_set_dma_mask() is successful, and returns zero, the PCI layer
|
||||||
|
saves away this mask you have provided. The PCI layer will use this
|
||||||
|
information later when you make DMA mappings.
|
||||||
|
|
||||||
|
There is a case which we are aware of at this time, which is worth
|
||||||
|
mentioning in this documentation. If your device supports multiple
|
||||||
|
functions (for example a sound card provides playback and record
|
||||||
|
functions) and the various different functions have _different_
|
||||||
|
DMA addressing limitations, you may wish to probe each mask and
|
||||||
|
only provide the functionality which the machine can handle. It
|
||||||
|
is important that the last call to pci_set_dma_mask() be for the
|
||||||
|
most specific mask.
|
||||||
|
|
||||||
|
Here is pseudo-code showing how this might be done:
|
||||||
|
|
||||||
|
#define PLAYBACK_ADDRESS_BITS DMA_BIT_MASK(32)
|
||||||
|
#define RECORD_ADDRESS_BITS 0x00ffffff
|
||||||
|
|
||||||
|
struct my_sound_card *card;
|
||||||
|
struct pci_dev *pdev;
|
||||||
|
|
||||||
|
...
|
||||||
|
if (!pci_set_dma_mask(pdev, PLAYBACK_ADDRESS_BITS)) {
|
||||||
|
card->playback_enabled = 1;
|
||||||
|
} else {
|
||||||
|
card->playback_enabled = 0;
|
||||||
|
printk(KERN_WARN "%s: Playback disabled due to DMA limitations.\n",
|
||||||
|
card->name);
|
||||||
|
}
|
||||||
|
if (!pci_set_dma_mask(pdev, RECORD_ADDRESS_BITS)) {
|
||||||
|
card->record_enabled = 1;
|
||||||
|
} else {
|
||||||
|
card->record_enabled = 0;
|
||||||
|
printk(KERN_WARN "%s: Record disabled due to DMA limitations.\n",
|
||||||
|
card->name);
|
||||||
|
}
|
||||||
|
|
||||||
|
A sound card was used as an example here because this genre of PCI
|
||||||
|
devices seems to be littered with ISA chips given a PCI front end,
|
||||||
|
and thus retaining the 16MB DMA addressing limitations of ISA.
|
||||||
|
|
||||||
|
Types of DMA mappings
|
||||||
|
|
||||||
|
There are two types of DMA mappings:
|
||||||
|
|
||||||
|
- Consistent DMA mappings which are usually mapped at driver
|
||||||
|
initialization, unmapped at the end and for which the hardware should
|
||||||
|
guarantee that the device and the CPU can access the data
|
||||||
|
in parallel and will see updates made by each other without any
|
||||||
|
explicit software flushing.
|
||||||
|
|
||||||
|
Think of "consistent" as "synchronous" or "coherent".
|
||||||
|
|
||||||
|
The current default is to return consistent memory in the low 32
|
||||||
|
bits of the PCI bus space. However, for future compatibility you
|
||||||
|
should set the consistent mask even if this default is fine for your
|
||||||
|
driver.
|
||||||
|
|
||||||
|
Good examples of what to use consistent mappings for are:
|
||||||
|
|
||||||
|
- Network card DMA ring descriptors.
|
||||||
|
- SCSI adapter mailbox command data structures.
|
||||||
|
- Device firmware microcode executed out of
|
||||||
|
main memory.
|
||||||
|
|
||||||
|
The invariant these examples all require is that any CPU store
|
||||||
|
to memory is immediately visible to the device, and vice
|
||||||
|
versa. Consistent mappings guarantee this.
|
||||||
|
|
||||||
|
IMPORTANT: Consistent DMA memory does not preclude the usage of
|
||||||
|
proper memory barriers. The CPU may reorder stores to
|
||||||
|
consistent memory just as it may normal memory. Example:
|
||||||
|
if it is important for the device to see the first word
|
||||||
|
of a descriptor updated before the second, you must do
|
||||||
|
something like:
|
||||||
|
|
||||||
|
desc->word0 = address;
|
||||||
|
wmb();
|
||||||
|
desc->word1 = DESC_VALID;
|
||||||
|
|
||||||
|
in order to get correct behavior on all platforms.
|
||||||
|
|
||||||
|
Also, on some platforms your driver may need to flush CPU write
|
||||||
|
buffers in much the same way as it needs to flush write buffers
|
||||||
|
found in PCI bridges (such as by reading a register's value
|
||||||
|
after writing it).
|
||||||
|
|
||||||
|
- Streaming DMA mappings which are usually mapped for one DMA transfer,
|
||||||
|
unmapped right after it (unless you use pci_dma_sync_* below) and for which
|
||||||
|
hardware can optimize for sequential accesses.
|
||||||
|
|
||||||
|
This of "streaming" as "asynchronous" or "outside the coherency
|
||||||
|
domain".
|
||||||
|
|
||||||
|
Good examples of what to use streaming mappings for are:
|
||||||
|
|
||||||
|
- Networking buffers transmitted/received by a device.
|
||||||
|
- Filesystem buffers written/read by a SCSI device.
|
||||||
|
|
||||||
|
The interfaces for using this type of mapping were designed in
|
||||||
|
such a way that an implementation can make whatever performance
|
||||||
|
optimizations the hardware allows. To this end, when using
|
||||||
|
such mappings you must be explicit about what you want to happen.
|
||||||
|
|
||||||
|
Neither type of DMA mapping has alignment restrictions that come
|
||||||
|
from PCI, although some devices may have such restrictions.
|
||||||
|
Also, systems with caches that aren't DMA-coherent will work better
|
||||||
|
when the underlying buffers don't share cache lines with other data.
|
||||||
|
|
||||||
|
|
||||||
|
Using Consistent DMA mappings.
|
||||||
|
|
||||||
|
To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
|
||||||
|
you should do:
|
||||||
|
|
||||||
|
dma_addr_t dma_handle;
|
||||||
|
|
||||||
|
cpu_addr = pci_alloc_consistent(pdev, size, &dma_handle);
|
||||||
|
|
||||||
|
where pdev is a struct pci_dev *. This may be called in interrupt context.
|
||||||
|
You should use dma_alloc_coherent (see DMA-API.txt) for buses
|
||||||
|
where devices don't have struct pci_dev (like ISA, EISA).
|
||||||
|
|
||||||
|
This argument is needed because the DMA translations may be bus
|
||||||
|
specific (and often is private to the bus which the device is attached
|
||||||
|
to).
|
||||||
|
|
||||||
|
Size is the length of the region you want to allocate, in bytes.
|
||||||
|
|
||||||
|
This routine will allocate RAM for that region, so it acts similarly to
|
||||||
|
__get_free_pages (but takes size instead of a page order). If your
|
||||||
|
driver needs regions sized smaller than a page, you may prefer using
|
||||||
|
the pci_pool interface, described below.
|
||||||
|
|
||||||
|
The consistent DMA mapping interfaces, for non-NULL pdev, will by
|
||||||
|
default return a DMA address which is SAC (Single Address Cycle)
|
||||||
|
addressable. Even if the device indicates (via PCI dma mask) that it
|
||||||
|
may address the upper 32-bits and thus perform DAC cycles, consistent
|
||||||
|
allocation will only return > 32-bit PCI addresses for DMA if the
|
||||||
|
consistent dma mask has been explicitly changed via
|
||||||
|
pci_set_consistent_dma_mask(). This is true of the pci_pool interface
|
||||||
|
as well.
|
||||||
|
|
||||||
|
pci_alloc_consistent returns two values: the virtual address which you
|
||||||
|
can use to access it from the CPU and dma_handle which you pass to the
|
||||||
|
card.
|
||||||
|
|
||||||
|
The cpu return address and the DMA bus master address are both
|
||||||
|
guaranteed to be aligned to the smallest PAGE_SIZE order which
|
||||||
|
is greater than or equal to the requested size. This invariant
|
||||||
|
exists (for example) to guarantee that if you allocate a chunk
|
||||||
|
which is smaller than or equal to 64 kilobytes, the extent of the
|
||||||
|
buffer you receive will not cross a 64K boundary.
|
||||||
|
|
||||||
|
To unmap and free such a DMA region, you call:
|
||||||
|
|
||||||
|
pci_free_consistent(pdev, size, cpu_addr, dma_handle);
|
||||||
|
|
||||||
|
where pdev, size are the same as in the above call and cpu_addr and
|
||||||
|
dma_handle are the values pci_alloc_consistent returned to you.
|
||||||
|
This function may not be called in interrupt context.
|
||||||
|
|
||||||
|
If your driver needs lots of smaller memory regions, you can write
|
||||||
|
custom code to subdivide pages returned by pci_alloc_consistent,
|
||||||
|
or you can use the pci_pool API to do that. A pci_pool is like
|
||||||
|
a kmem_cache, but it uses pci_alloc_consistent not __get_free_pages.
|
||||||
|
Also, it understands common hardware constraints for alignment,
|
||||||
|
like queue heads needing to be aligned on N byte boundaries.
|
||||||
|
|
||||||
|
Create a pci_pool like this:
|
||||||
|
|
||||||
|
struct pci_pool *pool;
|
||||||
|
|
||||||
|
pool = pci_pool_create(name, pdev, size, align, alloc);
|
||||||
|
|
||||||
|
The "name" is for diagnostics (like a kmem_cache name); pdev and size
|
||||||
|
are as above. The device's hardware alignment requirement for this
|
||||||
|
type of data is "align" (which is expressed in bytes, and must be a
|
||||||
|
power of two). If your device has no boundary crossing restrictions,
|
||||||
|
pass 0 for alloc; passing 4096 says memory allocated from this pool
|
||||||
|
must not cross 4KByte boundaries (but at that time it may be better to
|
||||||
|
go for pci_alloc_consistent directly instead).
|
||||||
|
|
||||||
|
Allocate memory from a pci pool like this:
|
||||||
|
|
||||||
|
cpu_addr = pci_pool_alloc(pool, flags, &dma_handle);
|
||||||
|
|
||||||
|
flags are SLAB_KERNEL if blocking is permitted (not in_interrupt nor
|
||||||
|
holding SMP locks), SLAB_ATOMIC otherwise. Like pci_alloc_consistent,
|
||||||
|
this returns two values, cpu_addr and dma_handle.
|
||||||
|
|
||||||
|
Free memory that was allocated from a pci_pool like this:
|
||||||
|
|
||||||
|
pci_pool_free(pool, cpu_addr, dma_handle);
|
||||||
|
|
||||||
|
where pool is what you passed to pci_pool_alloc, and cpu_addr and
|
||||||
|
dma_handle are the values pci_pool_alloc returned. This function
|
||||||
|
may be called in interrupt context.
|
||||||
|
|
||||||
|
Destroy a pci_pool by calling:
|
||||||
|
|
||||||
|
pci_pool_destroy(pool);
|
||||||
|
|
||||||
|
Make sure you've called pci_pool_free for all memory allocated
|
||||||
|
from a pool before you destroy the pool. This function may not
|
||||||
|
be called in interrupt context.
|
||||||
|
|
||||||
|
DMA Direction
|
||||||
|
|
||||||
|
The interfaces described in subsequent portions of this document
|
||||||
|
take a DMA direction argument, which is an integer and takes on
|
||||||
|
one of the following values:
|
||||||
|
|
||||||
|
PCI_DMA_BIDIRECTIONAL
|
||||||
|
PCI_DMA_TODEVICE
|
||||||
|
PCI_DMA_FROMDEVICE
|
||||||
|
PCI_DMA_NONE
|
||||||
|
|
||||||
|
One should provide the exact DMA direction if you know it.
|
||||||
|
|
||||||
|
PCI_DMA_TODEVICE means "from main memory to the PCI device"
|
||||||
|
PCI_DMA_FROMDEVICE means "from the PCI device to main memory"
|
||||||
|
It is the direction in which the data moves during the DMA
|
||||||
|
transfer.
|
||||||
|
|
||||||
|
You are _strongly_ encouraged to specify this as precisely
|
||||||
|
as you possibly can.
|
||||||
|
|
||||||
|
If you absolutely cannot know the direction of the DMA transfer,
|
||||||
|
specify PCI_DMA_BIDIRECTIONAL. It means that the DMA can go in
|
||||||
|
either direction. The platform guarantees that you may legally
|
||||||
|
specify this, and that it will work, but this may be at the
|
||||||
|
cost of performance for example.
|
||||||
|
|
||||||
|
The value PCI_DMA_NONE is to be used for debugging. One can
|
||||||
|
hold this in a data structure before you come to know the
|
||||||
|
precise direction, and this will help catch cases where your
|
||||||
|
direction tracking logic has failed to set things up properly.
|
||||||
|
|
||||||
|
Another advantage of specifying this value precisely (outside of
|
||||||
|
potential platform-specific optimizations of such) is for debugging.
|
||||||
|
Some platforms actually have a write permission boolean which DMA
|
||||||
|
mappings can be marked with, much like page protections in the user
|
||||||
|
program address space. Such platforms can and do report errors in the
|
||||||
|
kernel logs when the PCI controller hardware detects violation of the
|
||||||
|
permission setting.
|
||||||
|
|
||||||
|
Only streaming mappings specify a direction, consistent mappings
|
||||||
|
implicitly have a direction attribute setting of
|
||||||
|
PCI_DMA_BIDIRECTIONAL.
|
||||||
|
|
||||||
|
The SCSI subsystem tells you the direction to use in the
|
||||||
|
'sc_data_direction' member of the SCSI command your driver is
|
||||||
|
working on.
|
||||||
|
|
||||||
|
For Networking drivers, it's a rather simple affair. For transmit
|
||||||
|
packets, map/unmap them with the PCI_DMA_TODEVICE direction
|
||||||
|
specifier. For receive packets, just the opposite, map/unmap them
|
||||||
|
with the PCI_DMA_FROMDEVICE direction specifier.
|
||||||
|
|
||||||
|
Using Streaming DMA mappings
|
||||||
|
|
||||||
|
The streaming DMA mapping routines can be called from interrupt
|
||||||
|
context. There are two versions of each map/unmap, one which will
|
||||||
|
map/unmap a single memory region, and one which will map/unmap a
|
||||||
|
scatterlist.
|
||||||
|
|
||||||
|
To map a single region, you do:
|
||||||
|
|
||||||
|
struct pci_dev *pdev = mydev->pdev;
|
||||||
|
dma_addr_t dma_handle;
|
||||||
|
void *addr = buffer->ptr;
|
||||||
|
size_t size = buffer->len;
|
||||||
|
|
||||||
|
dma_handle = pci_map_single(pdev, addr, size, direction);
|
||||||
|
|
||||||
|
and to unmap it:
|
||||||
|
|
||||||
|
pci_unmap_single(pdev, dma_handle, size, direction);
|
||||||
|
|
||||||
|
You should call pci_unmap_single when the DMA activity is finished, e.g.
|
||||||
|
from the interrupt which told you that the DMA transfer is done.
|
||||||
|
|
||||||
|
Using cpu pointers like this for single mappings has a disadvantage,
|
||||||
|
you cannot reference HIGHMEM memory in this way. Thus, there is a
|
||||||
|
map/unmap interface pair akin to pci_{map,unmap}_single. These
|
||||||
|
interfaces deal with page/offset pairs instead of cpu pointers.
|
||||||
|
Specifically:
|
||||||
|
|
||||||
|
struct pci_dev *pdev = mydev->pdev;
|
||||||
|
dma_addr_t dma_handle;
|
||||||
|
struct page *page = buffer->page;
|
||||||
|
unsigned long offset = buffer->offset;
|
||||||
|
size_t size = buffer->len;
|
||||||
|
|
||||||
|
dma_handle = pci_map_page(pdev, page, offset, size, direction);
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
pci_unmap_page(pdev, dma_handle, size, direction);
|
||||||
|
|
||||||
|
Here, "offset" means byte offset within the given page.
|
||||||
|
|
||||||
|
With scatterlists, you map a region gathered from several regions by:
|
||||||
|
|
||||||
|
int i, count = pci_map_sg(pdev, sglist, nents, direction);
|
||||||
|
struct scatterlist *sg;
|
||||||
|
|
||||||
|
for_each_sg(sglist, sg, count, i) {
|
||||||
|
hw_address[i] = sg_dma_address(sg);
|
||||||
|
hw_len[i] = sg_dma_len(sg);
|
||||||
|
}
|
||||||
|
|
||||||
|
where nents is the number of entries in the sglist.
|
||||||
|
|
||||||
|
The implementation is free to merge several consecutive sglist entries
|
||||||
|
into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
|
||||||
|
consecutive sglist entries can be merged into one provided the first one
|
||||||
|
ends and the second one starts on a page boundary - in fact this is a huge
|
||||||
|
advantage for cards which either cannot do scatter-gather or have very
|
||||||
|
limited number of scatter-gather entries) and returns the actual number
|
||||||
|
of sg entries it mapped them to. On failure 0 is returned.
|
||||||
|
|
||||||
|
Then you should loop count times (note: this can be less than nents times)
|
||||||
|
and use sg_dma_address() and sg_dma_len() macros where you previously
|
||||||
|
accessed sg->address and sg->length as shown above.
|
||||||
|
|
||||||
|
To unmap a scatterlist, just call:
|
||||||
|
|
||||||
|
pci_unmap_sg(pdev, sglist, nents, direction);
|
||||||
|
|
||||||
|
Again, make sure DMA activity has already finished.
|
||||||
|
|
||||||
|
PLEASE NOTE: The 'nents' argument to the pci_unmap_sg call must be
|
||||||
|
the _same_ one you passed into the pci_map_sg call,
|
||||||
|
it should _NOT_ be the 'count' value _returned_ from the
|
||||||
|
pci_map_sg call.
|
||||||
|
|
||||||
|
Every pci_map_{single,sg} call should have its pci_unmap_{single,sg}
|
||||||
|
counterpart, because the bus address space is a shared resource (although
|
||||||
|
in some ports the mapping is per each BUS so less devices contend for the
|
||||||
|
same bus address space) and you could render the machine unusable by eating
|
||||||
|
all bus addresses.
|
||||||
|
|
||||||
|
If you need to use the same streaming DMA region multiple times and touch
|
||||||
|
the data in between the DMA transfers, the buffer needs to be synced
|
||||||
|
properly in order for the cpu and device to see the most uptodate and
|
||||||
|
correct copy of the DMA buffer.
|
||||||
|
|
||||||
|
So, firstly, just map it with pci_map_{single,sg}, and after each DMA
|
||||||
|
transfer call either:
|
||||||
|
|
||||||
|
pci_dma_sync_single_for_cpu(pdev, dma_handle, size, direction);
|
||||||
|
|
||||||
|
or:
|
||||||
|
|
||||||
|
pci_dma_sync_sg_for_cpu(pdev, sglist, nents, direction);
|
||||||
|
|
||||||
|
as appropriate.
|
||||||
|
|
||||||
|
Then, if you wish to let the device get at the DMA area again,
|
||||||
|
finish accessing the data with the cpu, and then before actually
|
||||||
|
giving the buffer to the hardware call either:
|
||||||
|
|
||||||
|
pci_dma_sync_single_for_device(pdev, dma_handle, size, direction);
|
||||||
|
|
||||||
|
or:
|
||||||
|
|
||||||
|
pci_dma_sync_sg_for_device(dev, sglist, nents, direction);
|
||||||
|
|
||||||
|
as appropriate.
|
||||||
|
|
||||||
|
After the last DMA transfer call one of the DMA unmap routines
|
||||||
|
pci_unmap_{single,sg}. If you don't touch the data from the first pci_map_*
|
||||||
|
call till pci_unmap_*, then you don't have to call the pci_dma_sync_*
|
||||||
|
routines at all.
|
||||||
|
|
||||||
|
Here is pseudo code which shows a situation in which you would need
|
||||||
|
to use the pci_dma_sync_*() interfaces.
|
||||||
|
|
||||||
|
my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len)
|
||||||
|
{
|
||||||
|
dma_addr_t mapping;
|
||||||
|
|
||||||
|
mapping = pci_map_single(cp->pdev, buffer, len, PCI_DMA_FROMDEVICE);
|
||||||
|
|
||||||
|
cp->rx_buf = buffer;
|
||||||
|
cp->rx_len = len;
|
||||||
|
cp->rx_dma = mapping;
|
||||||
|
|
||||||
|
give_rx_buf_to_card(cp);
|
||||||
|
}
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
my_card_interrupt_handler(int irq, void *devid, struct pt_regs *regs)
|
||||||
|
{
|
||||||
|
struct my_card *cp = devid;
|
||||||
|
|
||||||
|
...
|
||||||
|
if (read_card_status(cp) == RX_BUF_TRANSFERRED) {
|
||||||
|
struct my_card_header *hp;
|
||||||
|
|
||||||
|
/* Examine the header to see if we wish
|
||||||
|
* to accept the data. But synchronize
|
||||||
|
* the DMA transfer with the CPU first
|
||||||
|
* so that we see updated contents.
|
||||||
|
*/
|
||||||
|
pci_dma_sync_single_for_cpu(cp->pdev, cp->rx_dma,
|
||||||
|
cp->rx_len,
|
||||||
|
PCI_DMA_FROMDEVICE);
|
||||||
|
|
||||||
|
/* Now it is safe to examine the buffer. */
|
||||||
|
hp = (struct my_card_header *) cp->rx_buf;
|
||||||
|
if (header_is_ok(hp)) {
|
||||||
|
pci_unmap_single(cp->pdev, cp->rx_dma, cp->rx_len,
|
||||||
|
PCI_DMA_FROMDEVICE);
|
||||||
|
pass_to_upper_layers(cp->rx_buf);
|
||||||
|
make_and_setup_new_rx_buf(cp);
|
||||||
|
} else {
|
||||||
|
/* Just sync the buffer and give it back
|
||||||
|
* to the card.
|
||||||
|
*/
|
||||||
|
pci_dma_sync_single_for_device(cp->pdev,
|
||||||
|
cp->rx_dma,
|
||||||
|
cp->rx_len,
|
||||||
|
PCI_DMA_FROMDEVICE);
|
||||||
|
give_rx_buf_to_card(cp);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Drivers converted fully to this interface should not use virt_to_bus any
|
||||||
|
longer, nor should they use bus_to_virt. Some drivers have to be changed a
|
||||||
|
little bit, because there is no longer an equivalent to bus_to_virt in the
|
||||||
|
dynamic DMA mapping scheme - you have to always store the DMA addresses
|
||||||
|
returned by the pci_alloc_consistent, pci_pool_alloc, and pci_map_single
|
||||||
|
calls (pci_map_sg stores them in the scatterlist itself if the platform
|
||||||
|
supports dynamic DMA mapping in hardware) in your driver structures and/or
|
||||||
|
in the card registers.
|
||||||
|
|
||||||
|
All PCI drivers should be using these interfaces with no exceptions.
|
||||||
|
It is planned to completely remove virt_to_bus() and bus_to_virt() as
|
||||||
|
they are entirely deprecated. Some ports already do not provide these
|
||||||
|
as it is impossible to correctly support them.
|
||||||
|
|
||||||
|
Optimizing Unmap State Space Consumption
|
||||||
|
|
||||||
|
On many platforms, pci_unmap_{single,page}() is simply a nop.
|
||||||
|
Therefore, keeping track of the mapping address and length is a waste
|
||||||
|
of space. Instead of filling your drivers up with ifdefs and the like
|
||||||
|
to "work around" this (which would defeat the whole purpose of a
|
||||||
|
portable API) the following facilities are provided.
|
||||||
|
|
||||||
|
Actually, instead of describing the macros one by one, we'll
|
||||||
|
transform some example code.
|
||||||
|
|
||||||
|
1) Use DECLARE_PCI_UNMAP_{ADDR,LEN} in state saving structures.
|
||||||
|
Example, before:
|
||||||
|
|
||||||
|
struct ring_state {
|
||||||
|
struct sk_buff *skb;
|
||||||
|
dma_addr_t mapping;
|
||||||
|
__u32 len;
|
||||||
|
};
|
||||||
|
|
||||||
|
after:
|
||||||
|
|
||||||
|
struct ring_state {
|
||||||
|
struct sk_buff *skb;
|
||||||
|
DECLARE_PCI_UNMAP_ADDR(mapping)
|
||||||
|
DECLARE_PCI_UNMAP_LEN(len)
|
||||||
|
};
|
||||||
|
|
||||||
|
NOTE: DO NOT put a semicolon at the end of the DECLARE_*()
|
||||||
|
macro.
|
||||||
|
|
||||||
|
2) Use pci_unmap_{addr,len}_set to set these values.
|
||||||
|
Example, before:
|
||||||
|
|
||||||
|
ringp->mapping = FOO;
|
||||||
|
ringp->len = BAR;
|
||||||
|
|
||||||
|
after:
|
||||||
|
|
||||||
|
pci_unmap_addr_set(ringp, mapping, FOO);
|
||||||
|
pci_unmap_len_set(ringp, len, BAR);
|
||||||
|
|
||||||
|
3) Use pci_unmap_{addr,len} to access these values.
|
||||||
|
Example, before:
|
||||||
|
|
||||||
|
pci_unmap_single(pdev, ringp->mapping, ringp->len,
|
||||||
|
PCI_DMA_FROMDEVICE);
|
||||||
|
|
||||||
|
after:
|
||||||
|
|
||||||
|
pci_unmap_single(pdev,
|
||||||
|
pci_unmap_addr(ringp, mapping),
|
||||||
|
pci_unmap_len(ringp, len),
|
||||||
|
PCI_DMA_FROMDEVICE);
|
||||||
|
|
||||||
|
It really should be self-explanatory. We treat the ADDR and LEN
|
||||||
|
separately, because it is possible for an implementation to only
|
||||||
|
need the address in order to perform the unmap operation.
|
||||||
|
|
||||||
|
Platform Issues
|
||||||
|
|
||||||
|
If you are just writing drivers for Linux and do not maintain
|
||||||
|
an architecture port for the kernel, you can safely skip down
|
||||||
|
to "Closing".
|
||||||
|
|
||||||
|
1) Struct scatterlist requirements.
|
||||||
|
|
||||||
|
Struct scatterlist must contain, at a minimum, the following
|
||||||
|
members:
|
||||||
|
|
||||||
|
struct page *page;
|
||||||
|
unsigned int offset;
|
||||||
|
unsigned int length;
|
||||||
|
|
||||||
|
The base address is specified by a "page+offset" pair.
|
||||||
|
|
||||||
|
Previous versions of struct scatterlist contained a "void *address"
|
||||||
|
field that was sometimes used instead of page+offset. As of Linux
|
||||||
|
2.5., page+offset is always used, and the "address" field has been
|
||||||
|
deleted.
|
||||||
|
|
||||||
|
2) More to come...
|
||||||
|
|
||||||
|
Handling Errors
|
||||||
|
|
||||||
|
DMA address space is limited on some architectures and an allocation
|
||||||
|
failure can be determined by:
|
||||||
|
|
||||||
|
- checking if pci_alloc_consistent returns NULL or pci_map_sg returns 0
|
||||||
|
|
||||||
|
- checking the returned dma_addr_t of pci_map_single and pci_map_page
|
||||||
|
by using pci_dma_mapping_error():
|
||||||
|
|
||||||
|
dma_addr_t dma_handle;
|
||||||
|
|
||||||
|
dma_handle = pci_map_single(pdev, addr, size, direction);
|
||||||
|
if (pci_dma_mapping_error(pdev, dma_handle)) {
|
||||||
|
/*
|
||||||
|
* reduce current DMA mapping usage,
|
||||||
|
* delay and try again later or
|
||||||
|
* reset driver.
|
||||||
|
*/
|
||||||
|
}
|
||||||
|
|
||||||
|
Closing
|
||||||
|
|
||||||
|
This document, and the API itself, would not be in it's current
|
||||||
|
form without the feedback and suggestions from numerous individuals.
|
||||||
|
We would like to specifically mention, in no particular order, the
|
||||||
|
following people:
|
||||||
|
|
||||||
|
Russell King <rmk@arm.linux.org.uk>
|
||||||
|
Leo Dagum <dagum@barrel.engr.sgi.com>
|
||||||
|
Ralf Baechle <ralf@oss.sgi.com>
|
||||||
|
Grant Grundler <grundler@cup.hp.com>
|
||||||
|
Jay Estabrook <Jay.Estabrook@compaq.com>
|
||||||
|
Thomas Sailer <sailer@ife.ee.ethz.ch>
|
||||||
|
Andrea Arcangeli <andrea@suse.de>
|
||||||
|
Jens Axboe <jens.axboe@oracle.com>
|
||||||
|
David Mosberger-Tang <davidm@hpl.hp.com>
|
|
@ -0,0 +1,10 @@
|
||||||
|
*.xml
|
||||||
|
*.ps
|
||||||
|
*.pdf
|
||||||
|
*.html
|
||||||
|
*.9.gz
|
||||||
|
*.9
|
||||||
|
*.aux
|
||||||
|
*.dvi
|
||||||
|
*.log
|
||||||
|
*.out
|
|
@ -0,0 +1,261 @@
|
||||||
|
###
|
||||||
|
# This makefile is used to generate the kernel documentation,
|
||||||
|
# primarily based on in-line comments in various source files.
|
||||||
|
# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
|
||||||
|
# to document the SRC - and how to read it.
|
||||||
|
# To add a new book the only step required is to add the book to the
|
||||||
|
# list of DOCBOOKS.
|
||||||
|
|
||||||
|
DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
|
||||||
|
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
|
||||||
|
procfs-guide.xml writing_usb_driver.xml networking.xml \
|
||||||
|
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
|
||||||
|
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
|
||||||
|
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
|
||||||
|
mac80211.xml debugobjects.xml sh.xml regulator.xml \
|
||||||
|
alsa-driver-api.xml writing-an-alsa-driver.xml \
|
||||||
|
tracepoint.xml media.xml
|
||||||
|
|
||||||
|
###
|
||||||
|
# The build process is as follows (targets):
|
||||||
|
# (xmldocs) [by docproc]
|
||||||
|
# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
|
||||||
|
# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
|
||||||
|
# +--> DIR=file (htmldocs) [by xmlto]
|
||||||
|
# +--> man/ (mandocs) [by xmlto]
|
||||||
|
|
||||||
|
|
||||||
|
# for PDF and PS output you can choose between xmlto and docbook-utils tools
|
||||||
|
PDF_METHOD = $(prefer-db2x)
|
||||||
|
PS_METHOD = $(prefer-db2x)
|
||||||
|
|
||||||
|
|
||||||
|
###
|
||||||
|
# The targets that may be used.
|
||||||
|
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs xmldoclinks
|
||||||
|
|
||||||
|
BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
|
||||||
|
xmldocs: $(BOOKS) xmldoclinks
|
||||||
|
sgmldocs: xmldocs
|
||||||
|
|
||||||
|
PS := $(patsubst %.xml, %.ps, $(BOOKS))
|
||||||
|
psdocs: $(PS)
|
||||||
|
|
||||||
|
PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
|
||||||
|
pdfdocs: $(PDF)
|
||||||
|
|
||||||
|
HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
|
||||||
|
htmldocs: $(HTML)
|
||||||
|
$(call build_main_index)
|
||||||
|
$(call build_images)
|
||||||
|
|
||||||
|
MAN := $(patsubst %.xml, %.9, $(BOOKS))
|
||||||
|
mandocs: $(MAN)
|
||||||
|
|
||||||
|
build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \
|
||||||
|
cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(objtree)/Documentation/DocBook/media/
|
||||||
|
|
||||||
|
xmldoclinks:
|
||||||
|
ifneq ($(objtree),$(srctree))
|
||||||
|
for dep in dvb media-entities.tmpl media-indices.tmpl v4l; do \
|
||||||
|
rm -f $(objtree)/Documentation/DocBook/$$dep \
|
||||||
|
&& ln -s $(srctree)/Documentation/DocBook/$$dep $(objtree)/Documentation/DocBook/ \
|
||||||
|
|| exit; \
|
||||||
|
done
|
||||||
|
endif
|
||||||
|
|
||||||
|
installmandocs: mandocs
|
||||||
|
mkdir -p /usr/local/man/man9/
|
||||||
|
install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
|
||||||
|
|
||||||
|
###
|
||||||
|
#External programs used
|
||||||
|
KERNELDOC = $(srctree)/scripts/kernel-doc
|
||||||
|
DOCPROC = $(objtree)/scripts/basic/docproc
|
||||||
|
|
||||||
|
XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
|
||||||
|
#XMLTOFLAGS += --skip-validation
|
||||||
|
|
||||||
|
###
|
||||||
|
# DOCPROC is used for two purposes:
|
||||||
|
# 1) To generate a dependency list for a .tmpl file
|
||||||
|
# 2) To preprocess a .tmpl file and call kernel-doc with
|
||||||
|
# appropriate parameters.
|
||||||
|
# The following rules are used to generate the .xml documentation
|
||||||
|
# required to generate the final targets. (ps, pdf, html).
|
||||||
|
quiet_cmd_docproc = DOCPROC $@
|
||||||
|
cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
|
||||||
|
define rule_docproc
|
||||||
|
set -e; \
|
||||||
|
$(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
|
||||||
|
$(cmd_$(1)); \
|
||||||
|
( \
|
||||||
|
echo 'cmd_$@ := $(cmd_$(1))'; \
|
||||||
|
echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
|
||||||
|
) > $(dir $@).$(notdir $@).cmd
|
||||||
|
endef
|
||||||
|
|
||||||
|
%.xml: %.tmpl FORCE
|
||||||
|
$(call if_changed_rule,docproc)
|
||||||
|
|
||||||
|
###
|
||||||
|
#Read in all saved dependency files
|
||||||
|
cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
|
||||||
|
|
||||||
|
ifneq ($(cmd_files),)
|
||||||
|
include $(cmd_files)
|
||||||
|
endif
|
||||||
|
|
||||||
|
###
|
||||||
|
# Changes in kernel-doc force a rebuild of all documentation
|
||||||
|
$(BOOKS): $(KERNELDOC)
|
||||||
|
|
||||||
|
###
|
||||||
|
# procfs guide uses a .c file as example code.
|
||||||
|
# This requires an explicit dependency
|
||||||
|
C-procfs-example = procfs_example.xml
|
||||||
|
C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
|
||||||
|
$(obj)/procfs-guide.xml: $(C-procfs-example2)
|
||||||
|
|
||||||
|
# List of programs to build
|
||||||
|
##oops, this is a kernel module::hostprogs-y := procfs_example
|
||||||
|
obj-m += procfs_example.o
|
||||||
|
|
||||||
|
# Tell kbuild to always build the programs
|
||||||
|
always := $(hostprogs-y)
|
||||||
|
|
||||||
|
notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
|
||||||
|
exit 1
|
||||||
|
db2xtemplate = db2TYPE -o $(dir $@) $<
|
||||||
|
xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
|
||||||
|
|
||||||
|
# determine which methods are available
|
||||||
|
ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
|
||||||
|
use-db2x = db2x
|
||||||
|
prefer-db2x = db2x
|
||||||
|
else
|
||||||
|
use-db2x = notfound
|
||||||
|
prefer-db2x = $(use-xmlto)
|
||||||
|
endif
|
||||||
|
ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
|
||||||
|
use-xmlto = xmlto
|
||||||
|
prefer-xmlto = xmlto
|
||||||
|
else
|
||||||
|
use-xmlto = notfound
|
||||||
|
prefer-xmlto = $(use-db2x)
|
||||||
|
endif
|
||||||
|
|
||||||
|
# the commands, generated from the chosen template
|
||||||
|
quiet_cmd_db2ps = PS $@
|
||||||
|
cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
|
||||||
|
%.ps : %.xml
|
||||||
|
$(call cmd,db2ps)
|
||||||
|
|
||||||
|
quiet_cmd_db2pdf = PDF $@
|
||||||
|
cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
|
||||||
|
%.pdf : %.xml
|
||||||
|
$(call cmd,db2pdf)
|
||||||
|
|
||||||
|
|
||||||
|
index = index.html
|
||||||
|
main_idx = Documentation/DocBook/$(index)
|
||||||
|
build_main_index = rm -rf $(main_idx) && \
|
||||||
|
echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
|
||||||
|
echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
|
||||||
|
cat $(HTML) >> $(main_idx)
|
||||||
|
|
||||||
|
quiet_cmd_db2html = HTML $@
|
||||||
|
cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
|
||||||
|
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
|
||||||
|
$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
|
||||||
|
|
||||||
|
%.html: %.xml
|
||||||
|
@(which xmlto > /dev/null 2>&1) || \
|
||||||
|
(echo "*** You need to install xmlto ***"; \
|
||||||
|
exit 1)
|
||||||
|
@rm -rf $@ $(patsubst %.html,%,$@)
|
||||||
|
$(call cmd,db2html)
|
||||||
|
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
|
||||||
|
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
|
||||||
|
|
||||||
|
quiet_cmd_db2man = MAN $@
|
||||||
|
cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
|
||||||
|
%.9 : %.xml
|
||||||
|
@(which xmlto > /dev/null 2>&1) || \
|
||||||
|
(echo "*** You need to install xmlto ***"; \
|
||||||
|
exit 1)
|
||||||
|
$(Q)mkdir -p $(obj)/man
|
||||||
|
$(call cmd,db2man)
|
||||||
|
@touch $@
|
||||||
|
|
||||||
|
###
|
||||||
|
# Rules to generate postscripts and PNG images from .fig format files
|
||||||
|
quiet_cmd_fig2eps = FIG2EPS $@
|
||||||
|
cmd_fig2eps = fig2dev -Leps $< $@
|
||||||
|
|
||||||
|
%.eps: %.fig
|
||||||
|
@(which fig2dev > /dev/null 2>&1) || \
|
||||||
|
(echo "*** You need to install transfig ***"; \
|
||||||
|
exit 1)
|
||||||
|
$(call cmd,fig2eps)
|
||||||
|
|
||||||
|
quiet_cmd_fig2png = FIG2PNG $@
|
||||||
|
cmd_fig2png = fig2dev -Lpng $< $@
|
||||||
|
|
||||||
|
%.png: %.fig
|
||||||
|
@(which fig2dev > /dev/null 2>&1) || \
|
||||||
|
(echo "*** You need to install transfig ***"; \
|
||||||
|
exit 1)
|
||||||
|
$(call cmd,fig2png)
|
||||||
|
|
||||||
|
###
|
||||||
|
# Rule to convert a .c file to inline XML documentation
|
||||||
|
gen_xml = :
|
||||||
|
quiet_gen_xml = echo ' GEN $@'
|
||||||
|
silent_gen_xml = :
|
||||||
|
%.xml: %.c
|
||||||
|
@$($(quiet)gen_xml)
|
||||||
|
@( \
|
||||||
|
echo "<programlisting>"; \
|
||||||
|
expand --tabs=8 < $< | \
|
||||||
|
sed -e "s/&/\\&/g" \
|
||||||
|
-e "s/</\\</g" \
|
||||||
|
-e "s/>/\\>/g"; \
|
||||||
|
echo "</programlisting>") > $@
|
||||||
|
|
||||||
|
###
|
||||||
|
# Help targets as used by the top-level makefile
|
||||||
|
dochelp:
|
||||||
|
@echo ' Linux kernel internal documentation in different formats:'
|
||||||
|
@echo ' htmldocs - HTML'
|
||||||
|
@echo ' pdfdocs - PDF'
|
||||||
|
@echo ' psdocs - Postscript'
|
||||||
|
@echo ' xmldocs - XML DocBook'
|
||||||
|
@echo ' mandocs - man pages'
|
||||||
|
@echo ' installmandocs - install man pages generated by mandocs'
|
||||||
|
@echo ' cleandocs - clean all generated DocBook files'
|
||||||
|
|
||||||
|
###
|
||||||
|
# Temporary files left by various tools
|
||||||
|
clean-files := $(DOCBOOKS) \
|
||||||
|
$(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.aux, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.tex, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.log, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.out, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.ps, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.html, $(DOCBOOKS)) \
|
||||||
|
$(patsubst %.xml, %.9, $(DOCBOOKS)) \
|
||||||
|
$(C-procfs-example) $(index)
|
||||||
|
|
||||||
|
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
|
||||||
|
|
||||||
|
cleandocs:
|
||||||
|
$(Q)rm -f $(call objectify, $(clean-files))
|
||||||
|
$(Q)rm -rf $(call objectify, $(clean-dirs))
|
||||||
|
|
||||||
|
# Declare the contents of the .PHONY variable as phony. We keep that
|
||||||
|
# information in a variable se we can use it in if_changed and friends.
|
||||||
|
|
||||||
|
.PHONY: $(PHONY)
|
|
@ -0,0 +1,109 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<!-- ****************************************************** -->
|
||||||
|
<!-- Header -->
|
||||||
|
<!-- ****************************************************** -->
|
||||||
|
<book id="ALSA-Driver-API">
|
||||||
|
<bookinfo>
|
||||||
|
<title>The ALSA Driver API</title>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This document is free; 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This document is distributed in the hope that it will be useful,
|
||||||
|
but <emphasis>WITHOUT ANY WARRANTY</emphasis>; without even the
|
||||||
|
implied warranty of <emphasis>MERCHANTABILITY or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE</emphasis>. See the GNU General Public License
|
||||||
|
for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter><title>Management of Cards and Devices</title>
|
||||||
|
<sect1><title>Card Management</title>
|
||||||
|
!Esound/core/init.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Device Components</title>
|
||||||
|
!Esound/core/device.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Module requests and Device File Entries</title>
|
||||||
|
!Esound/core/sound.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Memory Management Helpers</title>
|
||||||
|
!Esound/core/memory.c
|
||||||
|
!Esound/core/memalloc.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter><title>PCM API</title>
|
||||||
|
<sect1><title>PCM Core</title>
|
||||||
|
!Esound/core/pcm.c
|
||||||
|
!Esound/core/pcm_lib.c
|
||||||
|
!Esound/core/pcm_native.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>PCM Format Helpers</title>
|
||||||
|
!Esound/core/pcm_misc.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>PCM Memory Management</title>
|
||||||
|
!Esound/core/pcm_memory.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter><title>Control/Mixer API</title>
|
||||||
|
<sect1><title>General Control Interface</title>
|
||||||
|
!Esound/core/control.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>AC97 Codec API</title>
|
||||||
|
!Esound/pci/ac97/ac97_codec.c
|
||||||
|
!Esound/pci/ac97/ac97_pcm.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Virtual Master Control API</title>
|
||||||
|
!Esound/core/vmaster.c
|
||||||
|
!Iinclude/sound/control.h
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter><title>MIDI API</title>
|
||||||
|
<sect1><title>Raw MIDI API</title>
|
||||||
|
!Esound/core/rawmidi.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>MPU401-UART API</title>
|
||||||
|
!Esound/drivers/mpu401/mpu401_uart.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter><title>Proc Info API</title>
|
||||||
|
<sect1><title>Proc Info Interface</title>
|
||||||
|
!Esound/core/info.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter><title>Miscellaneous Functions</title>
|
||||||
|
<sect1><title>Hardware-Dependent Devices API</title>
|
||||||
|
!Esound/core/hwdep.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Jack Abstraction Layer API</title>
|
||||||
|
!Esound/core/jack.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>ISA DMA Helpers</title>
|
||||||
|
!Esound/core/isadma.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Other Helper Macros</title>
|
||||||
|
!Iinclude/sound/core.h
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
|
@ -0,0 +1,391 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="debug-objects-guide">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Debug objects life time</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Thomas</firstname>
|
||||||
|
<surname>Gleixner</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>tglx@linutronix.de</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2008</year>
|
||||||
|
<holder>Thomas Gleixner</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation is free software; you can redistribute
|
||||||
|
it and/or modify it under the terms of the GNU General Public
|
||||||
|
License version 2 as published by the Free Software Foundation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
debugobjects is a generic infrastructure to track the life time
|
||||||
|
of kernel objects and validate the operations on those.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
debugobjects is useful to check for the following error patterns:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Activation of uninitialized objects</para></listitem>
|
||||||
|
<listitem><para>Initialization of active objects</para></listitem>
|
||||||
|
<listitem><para>Usage of freed/destroyed objects</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
debugobjects is not changing the data structure of the real
|
||||||
|
object so it can be compiled in with a minimal runtime impact
|
||||||
|
and enabled on demand with a kernel command line option.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="howto">
|
||||||
|
<title>Howto use debugobjects</title>
|
||||||
|
<para>
|
||||||
|
A kernel subsystem needs to provide a data structure which
|
||||||
|
describes the object type and add calls into the debug code at
|
||||||
|
appropriate places. The data structure to describe the object
|
||||||
|
type needs at minimum the name of the object type. Optional
|
||||||
|
functions can and should be provided to fixup detected problems
|
||||||
|
so the kernel can continue to work and the debug information can
|
||||||
|
be retrieved from a live system instead of hard core debugging
|
||||||
|
with serial consoles and stack trace transcripts from the
|
||||||
|
monitor.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The debug calls provided by debugobjects are:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>debug_object_init</para></listitem>
|
||||||
|
<listitem><para>debug_object_init_on_stack</para></listitem>
|
||||||
|
<listitem><para>debug_object_activate</para></listitem>
|
||||||
|
<listitem><para>debug_object_deactivate</para></listitem>
|
||||||
|
<listitem><para>debug_object_destroy</para></listitem>
|
||||||
|
<listitem><para>debug_object_free</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
Each of these functions takes the address of the real object and
|
||||||
|
a pointer to the object type specific debug description
|
||||||
|
structure.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Each detected error is reported in the statistics and a limited
|
||||||
|
number of errors are printk'ed including a full stack trace.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The statistics are available via /sys/kernel/debug/debug_objects/stats.
|
||||||
|
They provide information about the number of warnings and the
|
||||||
|
number of successful fixups along with information about the
|
||||||
|
usage of the internal tracking objects and the state of the
|
||||||
|
internal tracking objects pool.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="debugfunctions">
|
||||||
|
<title>Debug functions</title>
|
||||||
|
<sect1 id="prototypes">
|
||||||
|
<title>Debug object function reference</title>
|
||||||
|
!Elib/debugobjects.c
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="debug_object_init">
|
||||||
|
<title>debug_object_init</title>
|
||||||
|
<para>
|
||||||
|
This function is called whenever the initialization function
|
||||||
|
of a real object is called.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is already tracked by debugobjects it is
|
||||||
|
checked, whether the object can be initialized. Initializing
|
||||||
|
is not allowed for active and destroyed objects. When
|
||||||
|
debugobjects detects an error, then it calls the fixup_init
|
||||||
|
function of the object type description structure if provided
|
||||||
|
by the caller. The fixup function can correct the problem
|
||||||
|
before the real initialization of the object happens. E.g. it
|
||||||
|
can deactivate an active object in order to prevent damage to
|
||||||
|
the subsystem.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is not yet tracked by debugobjects,
|
||||||
|
debugobjects allocates a tracker object for the real object
|
||||||
|
and sets the tracker object state to ODEBUG_STATE_INIT. It
|
||||||
|
verifies that the object is not on the callers stack. If it is
|
||||||
|
on the callers stack then a limited number of warnings
|
||||||
|
including a full stack trace is printk'ed. The calling code
|
||||||
|
must use debug_object_init_on_stack() and remove the object
|
||||||
|
before leaving the function which allocated it. See next
|
||||||
|
section.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="debug_object_init_on_stack">
|
||||||
|
<title>debug_object_init_on_stack</title>
|
||||||
|
<para>
|
||||||
|
This function is called whenever the initialization function
|
||||||
|
of a real object which resides on the stack is called.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is already tracked by debugobjects it is
|
||||||
|
checked, whether the object can be initialized. Initializing
|
||||||
|
is not allowed for active and destroyed objects. When
|
||||||
|
debugobjects detects an error, then it calls the fixup_init
|
||||||
|
function of the object type description structure if provided
|
||||||
|
by the caller. The fixup function can correct the problem
|
||||||
|
before the real initialization of the object happens. E.g. it
|
||||||
|
can deactivate an active object in order to prevent damage to
|
||||||
|
the subsystem.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is not yet tracked by debugobjects
|
||||||
|
debugobjects allocates a tracker object for the real object
|
||||||
|
and sets the tracker object state to ODEBUG_STATE_INIT. It
|
||||||
|
verifies that the object is on the callers stack.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
An object which is on the stack must be removed from the
|
||||||
|
tracker by calling debug_object_free() before the function
|
||||||
|
which allocates the object returns. Otherwise we keep track of
|
||||||
|
stale objects.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="debug_object_activate">
|
||||||
|
<title>debug_object_activate</title>
|
||||||
|
<para>
|
||||||
|
This function is called whenever the activation function of a
|
||||||
|
real object is called.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is already tracked by debugobjects it is
|
||||||
|
checked, whether the object can be activated. Activating is
|
||||||
|
not allowed for active and destroyed objects. When
|
||||||
|
debugobjects detects an error, then it calls the
|
||||||
|
fixup_activate function of the object type description
|
||||||
|
structure if provided by the caller. The fixup function can
|
||||||
|
correct the problem before the real activation of the object
|
||||||
|
happens. E.g. it can deactivate an active object in order to
|
||||||
|
prevent damage to the subsystem.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is not yet tracked by debugobjects then
|
||||||
|
the fixup_activate function is called if available. This is
|
||||||
|
necessary to allow the legitimate activation of statically
|
||||||
|
allocated and initialized objects. The fixup function checks
|
||||||
|
whether the object is valid and calls the debug_objects_init()
|
||||||
|
function to initialize the tracking of this object.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the activation is legitimate, then the state of the
|
||||||
|
associated tracker object is set to ODEBUG_STATE_ACTIVE.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="debug_object_deactivate">
|
||||||
|
<title>debug_object_deactivate</title>
|
||||||
|
<para>
|
||||||
|
This function is called whenever the deactivation function of
|
||||||
|
a real object is called.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is tracked by debugobjects it is checked,
|
||||||
|
whether the object can be deactivated. Deactivating is not
|
||||||
|
allowed for untracked or destroyed objects.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the deactivation is legitimate, then the state of the
|
||||||
|
associated tracker object is set to ODEBUG_STATE_INACTIVE.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="debug_object_destroy">
|
||||||
|
<title>debug_object_destroy</title>
|
||||||
|
<para>
|
||||||
|
This function is called to mark an object destroyed. This is
|
||||||
|
useful to prevent the usage of invalid objects, which are
|
||||||
|
still available in memory: either statically allocated objects
|
||||||
|
or objects which are freed later.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is tracked by debugobjects it is checked,
|
||||||
|
whether the object can be destroyed. Destruction is not
|
||||||
|
allowed for active and destroyed objects. When debugobjects
|
||||||
|
detects an error, then it calls the fixup_destroy function of
|
||||||
|
the object type description structure if provided by the
|
||||||
|
caller. The fixup function can correct the problem before the
|
||||||
|
real destruction of the object happens. E.g. it can deactivate
|
||||||
|
an active object in order to prevent damage to the subsystem.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the destruction is legitimate, then the state of the
|
||||||
|
associated tracker object is set to ODEBUG_STATE_DESTROYED.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="debug_object_free">
|
||||||
|
<title>debug_object_free</title>
|
||||||
|
<para>
|
||||||
|
This function is called before an object is freed.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When the real object is tracked by debugobjects it is checked,
|
||||||
|
whether the object can be freed. Free is not allowed for
|
||||||
|
active objects. When debugobjects detects an error, then it
|
||||||
|
calls the fixup_free function of the object type description
|
||||||
|
structure if provided by the caller. The fixup function can
|
||||||
|
correct the problem before the real free of the object
|
||||||
|
happens. E.g. it can deactivate an active object in order to
|
||||||
|
prevent damage to the subsystem.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note that debug_object_free removes the object from the
|
||||||
|
tracker. Later usage of the object is detected by the other
|
||||||
|
debug checks.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="fixupfunctions">
|
||||||
|
<title>Fixup functions</title>
|
||||||
|
<sect1 id="debug_obj_descr">
|
||||||
|
<title>Debug object type description structure</title>
|
||||||
|
!Iinclude/linux/debugobjects.h
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="fixup_init">
|
||||||
|
<title>fixup_init</title>
|
||||||
|
<para>
|
||||||
|
This function is called from the debug code whenever a problem
|
||||||
|
in debug_object_init is detected. The function takes the
|
||||||
|
address of the object and the state which is currently
|
||||||
|
recorded in the tracker.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Called from debug_object_init when the object state is:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The function returns 1 when the fixup was successful,
|
||||||
|
otherwise 0. The return value is used to update the
|
||||||
|
statistics.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note, that the function needs to call the debug_object_init()
|
||||||
|
function again, after the damage has been repaired in order to
|
||||||
|
keep the state consistent.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="fixup_activate">
|
||||||
|
<title>fixup_activate</title>
|
||||||
|
<para>
|
||||||
|
This function is called from the debug code whenever a problem
|
||||||
|
in debug_object_activate is detected.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Called from debug_object_activate when the object state is:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem>
|
||||||
|
<listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The function returns 1 when the fixup was successful,
|
||||||
|
otherwise 0. The return value is used to update the
|
||||||
|
statistics.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note that the function needs to call the debug_object_activate()
|
||||||
|
function again after the damage has been repaired in order to
|
||||||
|
keep the state consistent.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The activation of statically initialized objects is a special
|
||||||
|
case. When debug_object_activate() has no tracked object for
|
||||||
|
this object address then fixup_activate() is called with
|
||||||
|
object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
|
||||||
|
needs to check whether this is a legitimate case of a
|
||||||
|
statically initialized object or not. In case it is it calls
|
||||||
|
debug_object_init() and debug_object_activate() to make the
|
||||||
|
object known to the tracker and marked active. In this case
|
||||||
|
the function should return 0 because this is not a real fixup.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="fixup_destroy">
|
||||||
|
<title>fixup_destroy</title>
|
||||||
|
<para>
|
||||||
|
This function is called from the debug code whenever a problem
|
||||||
|
in debug_object_destroy is detected.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Called from debug_object_destroy when the object state is:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The function returns 1 when the fixup was successful,
|
||||||
|
otherwise 0. The return value is used to update the
|
||||||
|
statistics.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="fixup_free">
|
||||||
|
<title>fixup_free</title>
|
||||||
|
<para>
|
||||||
|
This function is called from the debug code whenever a problem
|
||||||
|
in debug_object_free is detected. Further it can be called
|
||||||
|
from the debug checks in kfree/vfree, when an active object is
|
||||||
|
detected from the debug_check_no_obj_freed() sanity checks.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Called from debug_object_free() or debug_check_no_obj_freed()
|
||||||
|
when the object state is:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The function returns 1 when the fixup was successful,
|
||||||
|
otherwise 0. The return value is used to update the
|
||||||
|
statistics.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="bugs">
|
||||||
|
<title>Known Bugs And Assumptions</title>
|
||||||
|
<para>
|
||||||
|
None (knock on wood).
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
</book>
|
|
@ -0,0 +1,418 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="LinuxDriversAPI">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Linux Device Drivers</title>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="Basics">
|
||||||
|
<title>Driver Basics</title>
|
||||||
|
<sect1><title>Driver Entry and Exit points</title>
|
||||||
|
!Iinclude/linux/init.h
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Atomic and pointer manipulation</title>
|
||||||
|
!Iarch/x86/include/asm/atomic_32.h
|
||||||
|
!Iarch/x86/include/asm/unaligned.h
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Delaying, scheduling, and timer routines</title>
|
||||||
|
!Iinclude/linux/sched.h
|
||||||
|
!Ekernel/sched.c
|
||||||
|
!Ekernel/timer.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>High-resolution timers</title>
|
||||||
|
!Iinclude/linux/ktime.h
|
||||||
|
!Iinclude/linux/hrtimer.h
|
||||||
|
!Ekernel/hrtimer.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Workqueues and Kevents</title>
|
||||||
|
!Ekernel/workqueue.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Internal Functions</title>
|
||||||
|
!Ikernel/exit.c
|
||||||
|
!Ikernel/signal.c
|
||||||
|
!Iinclude/linux/kthread.h
|
||||||
|
!Ekernel/kthread.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Kernel objects manipulation</title>
|
||||||
|
<!--
|
||||||
|
X!Iinclude/linux/kobject.h
|
||||||
|
-->
|
||||||
|
!Elib/kobject.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Kernel utility functions</title>
|
||||||
|
!Iinclude/linux/kernel.h
|
||||||
|
!Ekernel/printk.c
|
||||||
|
!Ekernel/panic.c
|
||||||
|
!Ekernel/sys.c
|
||||||
|
!Ekernel/rcupdate.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Device Resource Management</title>
|
||||||
|
!Edrivers/base/devres.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="devdrivers">
|
||||||
|
<title>Device drivers infrastructure</title>
|
||||||
|
<sect1><title>Device Drivers Base</title>
|
||||||
|
<!--
|
||||||
|
X!Iinclude/linux/device.h
|
||||||
|
-->
|
||||||
|
!Edrivers/base/driver.c
|
||||||
|
!Edrivers/base/core.c
|
||||||
|
!Edrivers/base/class.c
|
||||||
|
!Edrivers/base/firmware_class.c
|
||||||
|
!Edrivers/base/transport_class.c
|
||||||
|
<!-- Cannot be included, because
|
||||||
|
attribute_container_add_class_device_adapter
|
||||||
|
and attribute_container_classdev_to_container
|
||||||
|
exceed allowed 44 characters maximum
|
||||||
|
X!Edrivers/base/attribute_container.c
|
||||||
|
-->
|
||||||
|
!Edrivers/base/sys.c
|
||||||
|
<!--
|
||||||
|
X!Edrivers/base/interface.c
|
||||||
|
-->
|
||||||
|
!Edrivers/base/platform.c
|
||||||
|
!Edrivers/base/bus.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Device Drivers Power Management</title>
|
||||||
|
!Edrivers/base/power/main.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Device Drivers ACPI Support</title>
|
||||||
|
<!-- Internal functions only
|
||||||
|
X!Edrivers/acpi/sleep/main.c
|
||||||
|
X!Edrivers/acpi/sleep/wakeup.c
|
||||||
|
X!Edrivers/acpi/motherboard.c
|
||||||
|
X!Edrivers/acpi/bus.c
|
||||||
|
-->
|
||||||
|
!Edrivers/acpi/scan.c
|
||||||
|
!Idrivers/acpi/scan.c
|
||||||
|
<!-- No correct structured comments
|
||||||
|
X!Edrivers/acpi/pci_bind.c
|
||||||
|
-->
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Device drivers PnP support</title>
|
||||||
|
!Idrivers/pnp/core.c
|
||||||
|
<!-- No correct structured comments
|
||||||
|
X!Edrivers/pnp/system.c
|
||||||
|
-->
|
||||||
|
!Edrivers/pnp/card.c
|
||||||
|
!Idrivers/pnp/driver.c
|
||||||
|
!Edrivers/pnp/manager.c
|
||||||
|
!Edrivers/pnp/support.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Userspace IO devices</title>
|
||||||
|
!Edrivers/uio/uio.c
|
||||||
|
!Iinclude/linux/uio_driver.h
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="parportdev">
|
||||||
|
<title>Parallel Port Devices</title>
|
||||||
|
!Iinclude/linux/parport.h
|
||||||
|
!Edrivers/parport/ieee1284.c
|
||||||
|
!Edrivers/parport/share.c
|
||||||
|
!Idrivers/parport/daisy.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="message_devices">
|
||||||
|
<title>Message-based devices</title>
|
||||||
|
<sect1><title>Fusion message devices</title>
|
||||||
|
!Edrivers/message/fusion/mptbase.c
|
||||||
|
!Idrivers/message/fusion/mptbase.c
|
||||||
|
!Edrivers/message/fusion/mptscsih.c
|
||||||
|
!Idrivers/message/fusion/mptscsih.c
|
||||||
|
!Idrivers/message/fusion/mptctl.c
|
||||||
|
!Idrivers/message/fusion/mptspi.c
|
||||||
|
!Idrivers/message/fusion/mptfc.c
|
||||||
|
!Idrivers/message/fusion/mptlan.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>I2O message devices</title>
|
||||||
|
!Iinclude/linux/i2o.h
|
||||||
|
!Idrivers/message/i2o/core.h
|
||||||
|
!Edrivers/message/i2o/iop.c
|
||||||
|
!Idrivers/message/i2o/iop.c
|
||||||
|
!Idrivers/message/i2o/config-osm.c
|
||||||
|
!Edrivers/message/i2o/exec-osm.c
|
||||||
|
!Idrivers/message/i2o/exec-osm.c
|
||||||
|
!Idrivers/message/i2o/bus-osm.c
|
||||||
|
!Edrivers/message/i2o/device.c
|
||||||
|
!Idrivers/message/i2o/device.c
|
||||||
|
!Idrivers/message/i2o/driver.c
|
||||||
|
!Idrivers/message/i2o/pci.c
|
||||||
|
!Idrivers/message/i2o/i2o_block.c
|
||||||
|
!Idrivers/message/i2o/i2o_scsi.c
|
||||||
|
!Idrivers/message/i2o/i2o_proc.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="snddev">
|
||||||
|
<title>Sound Devices</title>
|
||||||
|
!Iinclude/sound/core.h
|
||||||
|
!Esound/sound_core.c
|
||||||
|
!Iinclude/sound/pcm.h
|
||||||
|
!Esound/core/pcm.c
|
||||||
|
!Esound/core/device.c
|
||||||
|
!Esound/core/info.c
|
||||||
|
!Esound/core/rawmidi.c
|
||||||
|
!Esound/core/sound.c
|
||||||
|
!Esound/core/memory.c
|
||||||
|
!Esound/core/pcm_memory.c
|
||||||
|
!Esound/core/init.c
|
||||||
|
!Esound/core/isadma.c
|
||||||
|
!Esound/core/control.c
|
||||||
|
!Esound/core/pcm_lib.c
|
||||||
|
!Esound/core/hwdep.c
|
||||||
|
!Esound/core/pcm_native.c
|
||||||
|
!Esound/core/memalloc.c
|
||||||
|
<!-- FIXME: Removed for now since no structured comments in source
|
||||||
|
X!Isound/sound_firmware.c
|
||||||
|
-->
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="uart16x50">
|
||||||
|
<title>16x50 UART Driver</title>
|
||||||
|
!Iinclude/linux/serial_core.h
|
||||||
|
!Edrivers/serial/serial_core.c
|
||||||
|
!Edrivers/serial/8250.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="fbdev">
|
||||||
|
<title>Frame Buffer Library</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The frame buffer drivers depend heavily on four data structures.
|
||||||
|
These structures are declared in include/linux/fb.h. They are
|
||||||
|
fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs.
|
||||||
|
The last three can be made available to and from userland.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
fb_info defines the current state of a particular video card.
|
||||||
|
Inside fb_info, there exists a fb_ops structure which is a
|
||||||
|
collection of needed functions to make fbdev and fbcon work.
|
||||||
|
fb_info is only visible to the kernel.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
fb_var_screeninfo is used to describe the features of a video card
|
||||||
|
that are user defined. With fb_var_screeninfo, things such as
|
||||||
|
depth and the resolution may be defined.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The next structure is fb_fix_screeninfo. This defines the
|
||||||
|
properties of a card that are created when a mode is set and can't
|
||||||
|
be changed otherwise. A good example of this is the start of the
|
||||||
|
frame buffer memory. This "locks" the address of the frame buffer
|
||||||
|
memory, so that it cannot be changed or moved.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The last structure is fb_monospecs. In the old API, there was
|
||||||
|
little importance for fb_monospecs. This allowed for forbidden things
|
||||||
|
such as setting a mode of 800x600 on a fix frequency monitor. With
|
||||||
|
the new API, fb_monospecs prevents such things, and if used
|
||||||
|
correctly, can prevent a monitor from being cooked. fb_monospecs
|
||||||
|
will not be useful until kernels 2.5.x.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1><title>Frame Buffer Memory</title>
|
||||||
|
!Edrivers/video/fbmem.c
|
||||||
|
</sect1>
|
||||||
|
<!--
|
||||||
|
<sect1><title>Frame Buffer Console</title>
|
||||||
|
X!Edrivers/video/console/fbcon.c
|
||||||
|
</sect1>
|
||||||
|
-->
|
||||||
|
<sect1><title>Frame Buffer Colormap</title>
|
||||||
|
!Edrivers/video/fbcmap.c
|
||||||
|
</sect1>
|
||||||
|
<!-- FIXME:
|
||||||
|
drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment
|
||||||
|
out until somebody adds docs. KAO
|
||||||
|
<sect1><title>Frame Buffer Generic Functions</title>
|
||||||
|
X!Idrivers/video/fbgen.c
|
||||||
|
</sect1>
|
||||||
|
KAO -->
|
||||||
|
<sect1><title>Frame Buffer Video Mode Database</title>
|
||||||
|
!Idrivers/video/modedb.c
|
||||||
|
!Edrivers/video/modedb.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Frame Buffer Macintosh Video Mode Database</title>
|
||||||
|
!Edrivers/video/macmodes.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Frame Buffer Fonts</title>
|
||||||
|
<para>
|
||||||
|
Refer to the file drivers/video/console/fonts.c for more information.
|
||||||
|
</para>
|
||||||
|
<!-- FIXME: Removed for now since no structured comments in source
|
||||||
|
X!Idrivers/video/console/fonts.c
|
||||||
|
-->
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="input_subsystem">
|
||||||
|
<title>Input Subsystem</title>
|
||||||
|
!Iinclude/linux/input.h
|
||||||
|
!Edrivers/input/input.c
|
||||||
|
!Edrivers/input/ff-core.c
|
||||||
|
!Edrivers/input/ff-memless.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="spi">
|
||||||
|
<title>Serial Peripheral Interface (SPI)</title>
|
||||||
|
<para>
|
||||||
|
SPI is the "Serial Peripheral Interface", widely used with
|
||||||
|
embedded systems because it is a simple and efficient
|
||||||
|
interface: basically a multiplexed shift register.
|
||||||
|
Its three signal wires hold a clock (SCK, often in the range
|
||||||
|
of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and
|
||||||
|
a "Master In, Slave Out" (MISO) data line.
|
||||||
|
SPI is a full duplex protocol; for each bit shifted out the
|
||||||
|
MOSI line (one per clock) another is shifted in on the MISO line.
|
||||||
|
Those bits are assembled into words of various sizes on the
|
||||||
|
way to and from system memory.
|
||||||
|
An additional chipselect line is usually active-low (nCS);
|
||||||
|
four signals are normally used for each peripheral, plus
|
||||||
|
sometimes an interrupt.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The SPI bus facilities listed here provide a generalized
|
||||||
|
interface to declare SPI busses and devices, manage them
|
||||||
|
according to the standard Linux driver model, and perform
|
||||||
|
input/output operations.
|
||||||
|
At this time, only "master" side interfaces are supported,
|
||||||
|
where Linux talks to SPI peripherals and does not implement
|
||||||
|
such a peripheral itself.
|
||||||
|
(Interfaces to support implementing SPI slaves would
|
||||||
|
necessarily look different.)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The programming interface is structured around two kinds of driver,
|
||||||
|
and two kinds of device.
|
||||||
|
A "Controller Driver" abstracts the controller hardware, which may
|
||||||
|
be as simple as a set of GPIO pins or as complex as a pair of FIFOs
|
||||||
|
connected to dual DMA engines on the other side of the SPI shift
|
||||||
|
register (maximizing throughput). Such drivers bridge between
|
||||||
|
whatever bus they sit on (often the platform bus) and SPI, and
|
||||||
|
expose the SPI side of their device as a
|
||||||
|
<structname>struct spi_master</structname>.
|
||||||
|
SPI devices are children of that master, represented as a
|
||||||
|
<structname>struct spi_device</structname> and manufactured from
|
||||||
|
<structname>struct spi_board_info</structname> descriptors which
|
||||||
|
are usually provided by board-specific initialization code.
|
||||||
|
A <structname>struct spi_driver</structname> is called a
|
||||||
|
"Protocol Driver", and is bound to a spi_device using normal
|
||||||
|
driver model calls.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The I/O model is a set of queued messages. Protocol drivers
|
||||||
|
submit one or more <structname>struct spi_message</structname>
|
||||||
|
objects, which are processed and completed asynchronously.
|
||||||
|
(There are synchronous wrappers, however.) Messages are
|
||||||
|
built from one or more <structname>struct spi_transfer</structname>
|
||||||
|
objects, each of which wraps a full duplex SPI transfer.
|
||||||
|
A variety of protocol tweaking options are needed, because
|
||||||
|
different chips adopt very different policies for how they
|
||||||
|
use the bits transferred with SPI.
|
||||||
|
</para>
|
||||||
|
!Iinclude/linux/spi/spi.h
|
||||||
|
!Fdrivers/spi/spi.c spi_register_board_info
|
||||||
|
!Edrivers/spi/spi.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="i2c">
|
||||||
|
<title>I<superscript>2</superscript>C and SMBus Subsystem</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
I<superscript>2</superscript>C (or without fancy typography, "I2C")
|
||||||
|
is an acronym for the "Inter-IC" bus, a simple bus protocol which is
|
||||||
|
widely used where low data rate communications suffice.
|
||||||
|
Since it's also a licensed trademark, some vendors use another
|
||||||
|
name (such as "Two-Wire Interface", TWI) for the same bus.
|
||||||
|
I2C only needs two signals (SCL for clock, SDA for data), conserving
|
||||||
|
board real estate and minimizing signal quality issues.
|
||||||
|
Most I2C devices use seven bit addresses, and bus speeds of up
|
||||||
|
to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet
|
||||||
|
found wide use.
|
||||||
|
I2C is a multi-master bus; open drain signaling is used to
|
||||||
|
arbitrate between masters, as well as to handshake and to
|
||||||
|
synchronize clocks from slower clients.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The Linux I2C programming interfaces support only the master
|
||||||
|
side of bus interactions, not the slave side.
|
||||||
|
The programming interface is structured around two kinds of driver,
|
||||||
|
and two kinds of device.
|
||||||
|
An I2C "Adapter Driver" abstracts the controller hardware; it binds
|
||||||
|
to a physical device (perhaps a PCI device or platform_device) and
|
||||||
|
exposes a <structname>struct i2c_adapter</structname> representing
|
||||||
|
each I2C bus segment it manages.
|
||||||
|
On each I2C bus segment will be I2C devices represented by a
|
||||||
|
<structname>struct i2c_client</structname>. Those devices will
|
||||||
|
be bound to a <structname>struct i2c_driver</structname>,
|
||||||
|
which should follow the standard Linux driver model.
|
||||||
|
(At this writing, a legacy model is more widely used.)
|
||||||
|
There are functions to perform various I2C protocol operations; at
|
||||||
|
this writing all such functions are usable only from task context.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
|
||||||
|
systems are also I2C conformant. The electrical constraints are
|
||||||
|
tighter for SMBus, and it standardizes particular protocol messages
|
||||||
|
and idioms. Controllers that support I2C can also support most
|
||||||
|
SMBus operations, but SMBus controllers don't support all the protocol
|
||||||
|
options that an I2C controller will.
|
||||||
|
There are functions to perform various SMBus protocol operations,
|
||||||
|
either using I2C primitives or by issuing SMBus commands to
|
||||||
|
i2c_adapter devices which don't support those I2C operations.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Iinclude/linux/i2c.h
|
||||||
|
!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
|
||||||
|
!Edrivers/i2c/i2c-core.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
|
@ -0,0 +1,323 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="DoingIO">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Bus-Independent Device Accesses</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Matthew</firstname>
|
||||||
|
<surname>Wilcox</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>matthew@wil.cx</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Alan</firstname>
|
||||||
|
<surname>Cox</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>alan@lxorguk.ukuu.org.uk</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2001</year>
|
||||||
|
<holder>Matthew Wilcox</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
Linux provides an API which abstracts performing IO across all busses
|
||||||
|
and devices, allowing device drivers to be written independently of
|
||||||
|
bus type.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="bugs">
|
||||||
|
<title>Known Bugs And Assumptions</title>
|
||||||
|
<para>
|
||||||
|
None.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="mmio">
|
||||||
|
<title>Memory Mapped IO</title>
|
||||||
|
<sect1 id="getting_access_to_the_device">
|
||||||
|
<title>Getting Access to the Device</title>
|
||||||
|
<para>
|
||||||
|
The most widely supported form of IO is memory mapped IO.
|
||||||
|
That is, a part of the CPU's address space is interpreted
|
||||||
|
not as accesses to memory, but as accesses to a device. Some
|
||||||
|
architectures define devices to be at a fixed address, but most
|
||||||
|
have some method of discovering devices. The PCI bus walk is a
|
||||||
|
good example of such a scheme. This document does not cover how
|
||||||
|
to receive such an address, but assumes you are starting with one.
|
||||||
|
Physical addresses are of type unsigned long.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This address should not be used directly. Instead, to get an
|
||||||
|
address suitable for passing to the accessor functions described
|
||||||
|
below, you should call <function>ioremap</function>.
|
||||||
|
An address suitable for accessing the device will be returned to you.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
After you've finished using the device (say, in your module's
|
||||||
|
exit routine), call <function>iounmap</function> in order to return
|
||||||
|
the address space to the kernel. Most architectures allocate new
|
||||||
|
address space each time you call <function>ioremap</function>, and
|
||||||
|
they can run out unless you call <function>iounmap</function>.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="accessing_the_device">
|
||||||
|
<title>Accessing the device</title>
|
||||||
|
<para>
|
||||||
|
The part of the interface most used by drivers is reading and
|
||||||
|
writing memory-mapped registers on the device. Linux provides
|
||||||
|
interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit
|
||||||
|
quantities. Due to a historical accident, these are named byte,
|
||||||
|
word, long and quad accesses. Both read and write accesses are
|
||||||
|
supported; there is no prefetch support at this time.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The functions are named <function>readb</function>,
|
||||||
|
<function>readw</function>, <function>readl</function>,
|
||||||
|
<function>readq</function>, <function>readb_relaxed</function>,
|
||||||
|
<function>readw_relaxed</function>, <function>readl_relaxed</function>,
|
||||||
|
<function>readq_relaxed</function>, <function>writeb</function>,
|
||||||
|
<function>writew</function>, <function>writel</function> and
|
||||||
|
<function>writeq</function>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Some devices (such as framebuffers) would like to use larger
|
||||||
|
transfers than 8 bytes at a time. For these devices, the
|
||||||
|
<function>memcpy_toio</function>, <function>memcpy_fromio</function>
|
||||||
|
and <function>memset_io</function> functions are provided.
|
||||||
|
Do not use memset or memcpy on IO addresses; they
|
||||||
|
are not guaranteed to copy data in order.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The read and write functions are defined to be ordered. That is the
|
||||||
|
compiler is not permitted to reorder the I/O sequence. When the
|
||||||
|
ordering can be compiler optimised, you can use <function>
|
||||||
|
__readb</function> and friends to indicate the relaxed ordering. Use
|
||||||
|
this with care.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
While the basic functions are defined to be synchronous with respect
|
||||||
|
to each other and ordered with respect to each other the busses the
|
||||||
|
devices sit on may themselves have asynchronicity. In particular many
|
||||||
|
authors are burned by the fact that PCI bus writes are posted
|
||||||
|
asynchronously. A driver author must issue a read from the same
|
||||||
|
device to ensure that writes have occurred in the specific cases the
|
||||||
|
author cares. This kind of property cannot be hidden from driver
|
||||||
|
writers in the API. In some cases, the read used to flush the device
|
||||||
|
may be expected to fail (if the card is resetting, for example). In
|
||||||
|
that case, the read should be done from config space, which is
|
||||||
|
guaranteed to soft-fail if the card doesn't respond.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The following is an example of flushing a write to a device when
|
||||||
|
the driver would like to ensure the write's effects are visible prior
|
||||||
|
to continuing execution.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
static inline void
|
||||||
|
qla1280_disable_intrs(struct scsi_qla_host *ha)
|
||||||
|
{
|
||||||
|
struct device_reg *reg;
|
||||||
|
|
||||||
|
reg = ha->iobase;
|
||||||
|
/* disable risc and host interrupts */
|
||||||
|
WRT_REG_WORD(&reg->ictrl, 0);
|
||||||
|
/*
|
||||||
|
* The following read will ensure that the above write
|
||||||
|
* has been received by the device before we return from this
|
||||||
|
* function.
|
||||||
|
*/
|
||||||
|
RD_REG_WORD(&reg->ictrl);
|
||||||
|
ha->flags.ints_enabled = 0;
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In addition to write posting, on some large multiprocessing systems
|
||||||
|
(e.g. SGI Challenge, Origin and Altix machines) posted writes won't
|
||||||
|
be strongly ordered coming from different CPUs. Thus it's important
|
||||||
|
to properly protect parts of your driver that do memory-mapped writes
|
||||||
|
with locks and use the <function>mmiowb</function> to make sure they
|
||||||
|
arrive in the order intended. Issuing a regular <function>readX
|
||||||
|
</function> will also ensure write ordering, but should only be used
|
||||||
|
when the driver has to be sure that the write has actually arrived
|
||||||
|
at the device (not that it's simply ordered with respect to other
|
||||||
|
writes), since a full <function>readX</function> is a relatively
|
||||||
|
expensive operation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Generally, one should use <function>mmiowb</function> prior to
|
||||||
|
releasing a spinlock that protects regions using <function>writeb
|
||||||
|
</function> or similar functions that aren't surrounded by <function>
|
||||||
|
readb</function> calls, which will ensure ordering and flushing. The
|
||||||
|
following pseudocode illustrates what might occur if write ordering
|
||||||
|
isn't guaranteed via <function>mmiowb</function> or one of the
|
||||||
|
<function>readX</function> functions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
CPU A: spin_lock_irqsave(&dev_lock, flags)
|
||||||
|
CPU A: ...
|
||||||
|
CPU A: writel(newval, ring_ptr);
|
||||||
|
CPU A: spin_unlock_irqrestore(&dev_lock, flags)
|
||||||
|
...
|
||||||
|
CPU B: spin_lock_irqsave(&dev_lock, flags)
|
||||||
|
CPU B: writel(newval2, ring_ptr);
|
||||||
|
CPU B: ...
|
||||||
|
CPU B: spin_unlock_irqrestore(&dev_lock, flags)
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In the case above, newval2 could be written to ring_ptr before
|
||||||
|
newval. Fixing it is easy though:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
CPU A: spin_lock_irqsave(&dev_lock, flags)
|
||||||
|
CPU A: ...
|
||||||
|
CPU A: writel(newval, ring_ptr);
|
||||||
|
CPU A: mmiowb(); /* ensure no other writes beat us to the device */
|
||||||
|
CPU A: spin_unlock_irqrestore(&dev_lock, flags)
|
||||||
|
...
|
||||||
|
CPU B: spin_lock_irqsave(&dev_lock, flags)
|
||||||
|
CPU B: writel(newval2, ring_ptr);
|
||||||
|
CPU B: ...
|
||||||
|
CPU B: mmiowb();
|
||||||
|
CPU B: spin_unlock_irqrestore(&dev_lock, flags)
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
See tg3.c for a real world example of how to use <function>mmiowb
|
||||||
|
</function>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
PCI ordering rules also guarantee that PIO read responses arrive
|
||||||
|
after any outstanding DMA writes from that bus, since for some devices
|
||||||
|
the result of a <function>readb</function> call may signal to the
|
||||||
|
driver that a DMA transaction is complete. In many cases, however,
|
||||||
|
the driver may want to indicate that the next
|
||||||
|
<function>readb</function> call has no relation to any previous DMA
|
||||||
|
writes performed by the device. The driver can use
|
||||||
|
<function>readb_relaxed</function> for these cases, although only
|
||||||
|
some platforms will honor the relaxed semantics. Using the relaxed
|
||||||
|
read functions will provide significant performance benefits on
|
||||||
|
platforms that support it. The qla2xxx driver provides examples
|
||||||
|
of how to use <function>readX_relaxed</function>. In many cases,
|
||||||
|
a majority of the driver's <function>readX</function> calls can
|
||||||
|
safely be converted to <function>readX_relaxed</function> calls, since
|
||||||
|
only a few will indicate or depend on DMA completion.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="port_space_accesses">
|
||||||
|
<title>Port Space Accesses</title>
|
||||||
|
<sect1 id="port_space_explained">
|
||||||
|
<title>Port Space Explained</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Another form of IO commonly supported is Port Space. This is a
|
||||||
|
range of addresses separate to the normal memory address space.
|
||||||
|
Access to these addresses is generally not as fast as accesses
|
||||||
|
to the memory mapped addresses, and it also has a potentially
|
||||||
|
smaller address space.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Unlike memory mapped IO, no preparation is required
|
||||||
|
to access port space.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="accessing_port_space">
|
||||||
|
<title>Accessing Port Space</title>
|
||||||
|
<para>
|
||||||
|
Accesses to this space are provided through a set of functions
|
||||||
|
which allow 8-bit, 16-bit and 32-bit accesses; also
|
||||||
|
known as byte, word and long. These functions are
|
||||||
|
<function>inb</function>, <function>inw</function>,
|
||||||
|
<function>inl</function>, <function>outb</function>,
|
||||||
|
<function>outw</function> and <function>outl</function>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Some variants are provided for these functions. Some devices
|
||||||
|
require that accesses to their ports are slowed down. This
|
||||||
|
functionality is provided by appending a <function>_p</function>
|
||||||
|
to the end of the function. There are also equivalents to memcpy.
|
||||||
|
The <function>ins</function> and <function>outs</function>
|
||||||
|
functions copy bytes, words or longs to the given port.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="pubfunctions">
|
||||||
|
<title>Public Functions Provided</title>
|
||||||
|
!Iarch/x86/include/asm/io_32.h
|
||||||
|
!Elib/iomap.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
|
@ -0,0 +1 @@
|
||||||
|
!*.xml
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,221 @@
|
||||||
|
<title>DVB CA Device</title>
|
||||||
|
<para>The DVB CA device controls the conditional access hardware. It can be accessed through
|
||||||
|
<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
|
||||||
|
including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="ca_data_types">
|
||||||
|
<title>CA Data Types</title>
|
||||||
|
|
||||||
|
|
||||||
|
<section id="ca_slot_info_t">
|
||||||
|
<title>ca_slot_info_t</title>
|
||||||
|
<programlisting>
|
||||||
|
/⋆ slot interface types and info ⋆/
|
||||||
|
|
||||||
|
typedef struct ca_slot_info_s {
|
||||||
|
int num; /⋆ slot number ⋆/
|
||||||
|
|
||||||
|
int type; /⋆ CA interface this slot supports ⋆/
|
||||||
|
#define CA_CI 1 /⋆ CI high level interface ⋆/
|
||||||
|
#define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/
|
||||||
|
#define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/
|
||||||
|
#define CA_SC 128 /⋆ simple smart card interface ⋆/
|
||||||
|
|
||||||
|
unsigned int flags;
|
||||||
|
#define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/
|
||||||
|
#define CA_CI_MODULE_READY 2
|
||||||
|
} ca_slot_info_t;
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
<section id="ca_descr_info_t">
|
||||||
|
<title>ca_descr_info_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef struct ca_descr_info_s {
|
||||||
|
unsigned int num; /⋆ number of available descramblers (keys) ⋆/
|
||||||
|
unsigned int type; /⋆ type of supported scrambling system ⋆/
|
||||||
|
#define CA_ECD 1
|
||||||
|
#define CA_NDS 2
|
||||||
|
#define CA_DSS 4
|
||||||
|
} ca_descr_info_t;
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
<section id="ca_cap_t">
|
||||||
|
<title>ca_cap_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef struct ca_cap_s {
|
||||||
|
unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/
|
||||||
|
unsigned int slot_type; /⋆ OR of all supported types ⋆/
|
||||||
|
unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/
|
||||||
|
unsigned int descr_type;/⋆ OR of all supported types ⋆/
|
||||||
|
} ca_cap_t;
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
<section id="ca_msg_t">
|
||||||
|
<title>ca_msg_t</title>
|
||||||
|
<programlisting>
|
||||||
|
/⋆ a message to/from a CI-CAM ⋆/
|
||||||
|
typedef struct ca_msg_s {
|
||||||
|
unsigned int index;
|
||||||
|
unsigned int type;
|
||||||
|
unsigned int length;
|
||||||
|
unsigned char msg[256];
|
||||||
|
} ca_msg_t;
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
<section id="ca_descr_t">
|
||||||
|
<title>ca_descr_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef struct ca_descr_s {
|
||||||
|
unsigned int index;
|
||||||
|
unsigned int parity;
|
||||||
|
unsigned char cw[8];
|
||||||
|
} ca_descr_t;
|
||||||
|
</programlisting>
|
||||||
|
</section></section>
|
||||||
|
<section id="ca_function_calls">
|
||||||
|
<title>CA Function Calls</title>
|
||||||
|
|
||||||
|
|
||||||
|
<section id="ca_fopen">
|
||||||
|
<title>open()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
|
||||||
|
<para>When an open() call has succeeded, the device will be ready for use.
|
||||||
|
The significance of blocking or non-blocking mode is described in the
|
||||||
|
documentation for functions where there is a difference. It does not affect the
|
||||||
|
semantics of the open() call itself. A device opened in blocking mode can later
|
||||||
|
be put into non-blocking mode (and vice versa) using the F_SETFL command
|
||||||
|
of the fcntl system call. This is a standard system call, documented in the Linux
|
||||||
|
manual page for fcntl. Only one user can open the CA Device in O_RDWR
|
||||||
|
mode. All other attempts to open the device in this mode will fail, and an error
|
||||||
|
code will be returned.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int open(const char ⋆deviceName, int flags);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>const char
|
||||||
|
*deviceName</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Name of specific video device.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int flags</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>A bit-wise OR of the following flags:</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>O_RDONLY read-only access</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>O_RDWR read/write access</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>O_NONBLOCK open in non-blocking mode</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>(blocking mode is the default)</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ENODEV</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Device driver not loaded/available.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINTERNAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Internal error.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBUSY</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Device or resource busy.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid argument.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
<section id="ca_fclose">
|
||||||
|
<title>close()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call closes a previously opened audio device.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int close(int fd);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid open file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
</section>
|
|
@ -0,0 +1,973 @@
|
||||||
|
<title>DVB Demux Device</title>
|
||||||
|
|
||||||
|
<para>The DVB demux device controls the filters of the DVB hardware/software. It can be
|
||||||
|
accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
|
||||||
|
accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
|
||||||
|
</para>
|
||||||
|
<section id="dmx_types">
|
||||||
|
<title>Demux Data Types</title>
|
||||||
|
|
||||||
|
<section id="dmx_output_t">
|
||||||
|
<title>dmx_output_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef enum
|
||||||
|
{
|
||||||
|
DMX_OUT_DECODER,
|
||||||
|
DMX_OUT_TAP,
|
||||||
|
DMX_OUT_TS_TAP
|
||||||
|
} dmx_output_t;
|
||||||
|
</programlisting>
|
||||||
|
<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
|
||||||
|
called.
|
||||||
|
</para>
|
||||||
|
<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
|
||||||
|
which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
|
||||||
|
specified.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_input_t">
|
||||||
|
<title>dmx_input_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef enum
|
||||||
|
{
|
||||||
|
DMX_IN_FRONTEND,
|
||||||
|
DMX_IN_DVR
|
||||||
|
} dmx_input_t;
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_pes_type_t">
|
||||||
|
<title>dmx_pes_type_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef enum
|
||||||
|
{
|
||||||
|
DMX_PES_AUDIO,
|
||||||
|
DMX_PES_VIDEO,
|
||||||
|
DMX_PES_TELETEXT,
|
||||||
|
DMX_PES_SUBTITLE,
|
||||||
|
DMX_PES_PCR,
|
||||||
|
DMX_PES_OTHER
|
||||||
|
} dmx_pes_type_t;
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_event_t">
|
||||||
|
<title>dmx_event_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef enum
|
||||||
|
{
|
||||||
|
DMX_SCRAMBLING_EV,
|
||||||
|
DMX_FRONTEND_EV
|
||||||
|
} dmx_event_t;
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_scrambling_status_t">
|
||||||
|
<title>dmx_scrambling_status_t</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef enum
|
||||||
|
{
|
||||||
|
DMX_SCRAMBLING_OFF,
|
||||||
|
DMX_SCRAMBLING_ON
|
||||||
|
} dmx_scrambling_status_t;
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_filter">
|
||||||
|
<title>struct dmx_filter</title>
|
||||||
|
<programlisting>
|
||||||
|
typedef struct dmx_filter
|
||||||
|
{
|
||||||
|
uint8_t filter[DMX_FILTER_SIZE];
|
||||||
|
uint8_t mask[DMX_FILTER_SIZE];
|
||||||
|
} dmx_filter_t;
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_sct_filter_params">
|
||||||
|
<title>struct dmx_sct_filter_params</title>
|
||||||
|
<programlisting>
|
||||||
|
struct dmx_sct_filter_params
|
||||||
|
{
|
||||||
|
uint16_t pid;
|
||||||
|
dmx_filter_t filter;
|
||||||
|
uint32_t timeout;
|
||||||
|
uint32_t flags;
|
||||||
|
#define DMX_CHECK_CRC 1
|
||||||
|
#define DMX_ONESHOT 2
|
||||||
|
#define DMX_IMMEDIATE_START 4
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_pes_filter_params">
|
||||||
|
<title>struct dmx_pes_filter_params</title>
|
||||||
|
<programlisting>
|
||||||
|
struct dmx_pes_filter_params
|
||||||
|
{
|
||||||
|
uint16_t pid;
|
||||||
|
dmx_input_t input;
|
||||||
|
dmx_output_t output;
|
||||||
|
dmx_pes_type_t pes_type;
|
||||||
|
uint32_t flags;
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_event">
|
||||||
|
<title>struct dmx_event</title>
|
||||||
|
<programlisting>
|
||||||
|
struct dmx_event
|
||||||
|
{
|
||||||
|
dmx_event_t event;
|
||||||
|
time_t timeStamp;
|
||||||
|
union
|
||||||
|
{
|
||||||
|
dmx_scrambling_status_t scrambling;
|
||||||
|
} u;
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_stc">
|
||||||
|
<title>struct dmx_stc</title>
|
||||||
|
<programlisting>
|
||||||
|
struct dmx_stc {
|
||||||
|
unsigned int num; /⋆ input : which STC? 0..N ⋆/
|
||||||
|
unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/
|
||||||
|
uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_fcalls">
|
||||||
|
<title>Demux Function Calls</title>
|
||||||
|
|
||||||
|
<section id="dmx_fopen">
|
||||||
|
<title>open()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
|
||||||
|
allocates a new filter and returns a handle which can be used for subsequent
|
||||||
|
control of that filter. This call has to be made for each filter to be used, i.e. every
|
||||||
|
returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
|
||||||
|
is a logical device to be used for retrieving Transport Streams for digital
|
||||||
|
video recording. When reading from this device a transport stream containing
|
||||||
|
the packets from all PES filters set in the corresponding demux device
|
||||||
|
(/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
|
||||||
|
recorded Transport Stream is replayed by writing to this device. </para>
|
||||||
|
<para>The significance of blocking or non-blocking mode is described in the
|
||||||
|
documentation for functions where there is a difference. It does not affect the
|
||||||
|
semantics of the open() call itself. A device opened in blocking mode can later
|
||||||
|
be put into non-blocking mode (and vice versa) using the F_SETFL command
|
||||||
|
of the fcntl system call.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int open(const char ⋆deviceName, int flags);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>const char
|
||||||
|
*deviceName</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Name of demux device.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int flags</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>A bit-wise OR of the following flags:</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>O_RDWR read/write access</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>O_NONBLOCK open in non-blocking mode</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>(blocking mode is the default)</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ENODEV</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Device driver not loaded/available.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid argument.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EMFILE</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>“Too many open files”, i.e. no more filters available.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ENOMEM</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>The driver failed to allocate enough memory.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_fclose">
|
||||||
|
<title>close()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call deactivates and deallocates a filter that was previously
|
||||||
|
allocated via the open() call.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int close(int fd);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid open file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_fread">
|
||||||
|
<title>read()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call returns filtered data, which might be section or PES data. The
|
||||||
|
filtered data is transferred from the driver’s internal circular buffer to buf. The
|
||||||
|
maximum amount of data to be transferred is implied by count.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>When returning section data the driver always tries to return a complete single
|
||||||
|
section (even though buf would provide buffer space for more data). If the size
|
||||||
|
of the buffer is smaller than the section as much as possible will be returned,
|
||||||
|
and the remaining data will be provided in subsequent calls.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
|
||||||
|
sized sections) by default. The size of this buffer may be changed by using the
|
||||||
|
DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
|
||||||
|
the read operations are not performed fast enough, this may result in a buffer
|
||||||
|
overflow error. In this case EOVERFLOW will be returned, and the circular
|
||||||
|
buffer will be emptied. This call is blocking if there is no data to return, i.e. the
|
||||||
|
process will be put to sleep waiting for data, unless the O_NONBLOCK flag
|
||||||
|
is specified.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>Note that in order to be able to read, the filtering process has to be started
|
||||||
|
by defining either a section or a PES filter by means of the ioctl functions,
|
||||||
|
and then starting the filtering process via the DMX_START ioctl function
|
||||||
|
or by setting the DMX_IMMEDIATE_START flag. If the reading is done
|
||||||
|
from a logical DVR demux device, the data will constitute a Transport Stream
|
||||||
|
including the packets from all PES filters in the corresponding demux device
|
||||||
|
/dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>size_t read(int fd, void ⋆buf, size_t count);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>void *buf</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to the buffer to be used for returned filtered data.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>size_t count</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Size of buf.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EWOULDBLOCK</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>No data to return and O_NONBLOCK was specified.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid open file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ECRC</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Last section had a CRC error - no data returned. The
|
||||||
|
buffer is flushed.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EOVERFLOW</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>The filtered data was not read from the buffer in due
|
||||||
|
time, resulting in non-read data being lost. The buffer is
|
||||||
|
flushed.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ETIMEDOUT</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>The section was not loaded within the stated timeout
|
||||||
|
period. See ioctl DMX_SET_FILTER for how to set a
|
||||||
|
timeout.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EFAULT</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>The driver failed to write to the callers buffer due to an
|
||||||
|
invalid *buf pointer.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_fwrite">
|
||||||
|
<title>write()</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
|
||||||
|
associated with the physical demux device that provides the actual DVR
|
||||||
|
functionality. It is used for replay of a digitally recorded Transport Stream.
|
||||||
|
Matching filters have to be defined in the corresponding physical demux
|
||||||
|
device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
|
||||||
|
implied by count.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ssize_t write(int fd, const void ⋆buf, size_t
|
||||||
|
count);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>void *buf</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to the buffer containing the Transport Stream.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>size_t count</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Size of buf.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EWOULDBLOCK</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>No data was written. This
|
||||||
|
might happen if O_NONBLOCK was specified and there
|
||||||
|
is no more buffer space available (if O_NONBLOCK is
|
||||||
|
not specified the function will block until buffer space is
|
||||||
|
available).</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBUSY</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>This error code indicates that there are conflicting
|
||||||
|
requests. The corresponding demux device is setup to
|
||||||
|
receive data from the front- end. Make sure that these
|
||||||
|
filters are stopped and that the filters with input set to
|
||||||
|
DMX_IN_DVR are started.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid open file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_start">
|
||||||
|
<title>DMX_START</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call is used to start the actual filtering operation defined via the ioctl
|
||||||
|
calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_START);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_START for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid argument, i.e. no filtering parameters provided via
|
||||||
|
the DMX_SET_FILTER or DMX_SET_PES_FILTER
|
||||||
|
functions.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBUSY</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>This error code indicates that there are conflicting
|
||||||
|
requests. There are active filters filtering data from
|
||||||
|
another input source. Make sure that these filters are
|
||||||
|
stopped before starting this filter.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_stop">
|
||||||
|
<title>DMX_STOP</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call is used to stop the actual filtering operation defined via the
|
||||||
|
ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
|
||||||
|
the DMX_START command.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_STOP);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_STOP for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_set_filter">
|
||||||
|
<title>DMX_SET_FILTER</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call sets up a filter according to the filter and mask parameters
|
||||||
|
provided. A timeout may be defined stating number of seconds to wait for a
|
||||||
|
section to be loaded. A value of 0 means that no timeout should be applied.
|
||||||
|
Finally there is a flag field where it is possible to state whether a section should
|
||||||
|
be CRC-checked, whether the filter should be a ”one-shot” filter, i.e. if the
|
||||||
|
filtering operation should be stopped after the first section is received, and
|
||||||
|
whether the filtering operation should be started immediately (without waiting
|
||||||
|
for a DMX_START ioctl call). If a filter was previously set-up, this filter will
|
||||||
|
be canceled, and the receive buffer will be flushed.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_SET_FILTER,
|
||||||
|
struct dmx_sct_filter_params ⋆params);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_SET_FILTER for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>struct
|
||||||
|
dmx_sct_filter_params
|
||||||
|
*params</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to structure containing filter parameters.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid argument.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_set_pes_filter">
|
||||||
|
<title>DMX_SET_PES_FILTER</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call sets up a PES filter according to the parameters provided. By a
|
||||||
|
PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
|
||||||
|
no PES header or payload filtering capability is supported.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>The transport stream destination for the filtered output may be set. Also the
|
||||||
|
PES type may be stated in order to be able to e.g. direct a video stream directly
|
||||||
|
to the video decoder. Finally there is a flag field where it is possible to state
|
||||||
|
whether the filtering operation should be started immediately (without waiting
|
||||||
|
for a DMX_START ioctl call). If a filter was previously set-up, this filter will
|
||||||
|
be cancelled, and the receive buffer will be flushed.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
|
||||||
|
struct dmx_pes_filter_params ⋆params);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_SET_PES_FILTER for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>struct
|
||||||
|
dmx_pes_filter_params
|
||||||
|
*params</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to structure containing filter parameters.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid argument.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBUSY</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>This error code indicates that there are conflicting
|
||||||
|
requests. There are active filters filtering data from
|
||||||
|
another input source. Make sure that these filters are
|
||||||
|
stopped before starting this filter.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dms_set_buffer_size">
|
||||||
|
<title>DMX_SET_BUFFER_SIZE</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call is used to set the size of the circular buffer used for filtered data.
|
||||||
|
The default size is two maximum sized sections, i.e. if this function is not called
|
||||||
|
a buffer size of 2 * 4096 bytes will be used.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request =
|
||||||
|
DMX_SET_BUFFER_SIZE, unsigned long size);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>unsigned long size</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Size of circular buffer.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>ENOMEM</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>The driver was not able to allocate a buffer of the
|
||||||
|
requested size.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_get_event">
|
||||||
|
<title>DMX_GET_EVENT</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call returns an event if available. If an event is not available,
|
||||||
|
the behavior depends on whether the device is in blocking or non-blocking
|
||||||
|
mode. In the latter case, the call fails immediately with errno set to
|
||||||
|
EWOULDBLOCK. In the former case, the call blocks until an event becomes
|
||||||
|
available.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>The standard Linux poll() and/or select() system calls can be used with the
|
||||||
|
device file descriptor to watch for new events. For select(), the file descriptor
|
||||||
|
should be included in the exceptfds argument, and for poll(), POLLPRI should
|
||||||
|
be specified as the wake-up condition. Only the latest event for each filter is
|
||||||
|
saved.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_GET_EVENT,
|
||||||
|
struct dmx_event ⋆ev);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_GET_EVENT for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>struct dmx_event *ev</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to the location where the event is to be stored.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EFAULT</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>ev points to an invalid address.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EWOULDBLOCK</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>There is no event pending, and the device is in
|
||||||
|
non-blocking mode.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dmx_get_stc">
|
||||||
|
<title>DMX_GET_STC</title>
|
||||||
|
<para>DESCRIPTION
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>This ioctl call returns the current value of the system time counter (which is driven
|
||||||
|
by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
|
||||||
|
STC, so you must specify which one by setting the num field of stc before the ioctl
|
||||||
|
(range 0...n). The result is returned in form of a ratio with a 64 bit numerator
|
||||||
|
and a 32 bit denominator, so the real 90kHz STC value is stc->stc /
|
||||||
|
stc->base
|
||||||
|
.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>SYNOPSIS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int ioctl( int fd, int request = DMX_GET_STC, struct
|
||||||
|
dmx_stc ⋆stc);</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>PARAMETERS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int fd</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>File descriptor returned by a previous call to open().</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>int request</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Equals DMX_GET_STC for this command.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>struct dmx_stc *stc</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Pointer to the location where the stc is to be stored.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
<para>ERRORS
|
||||||
|
</para>
|
||||||
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EBADF</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>fd is not a valid file descriptor.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EFAULT</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>stc points to an invalid address.</para>
|
||||||
|
</entry>
|
||||||
|
</row><row><entry
|
||||||
|
align="char">
|
||||||
|
<para>EINVAL</para>
|
||||||
|
</entry><entry
|
||||||
|
align="char">
|
||||||
|
<para>Invalid stc number.</para>
|
||||||
|
</entry>
|
||||||
|
</row></tbody></tgroup></informaltable>
|
||||||
|
</section></section>
|
|
@ -0,0 +1,87 @@
|
||||||
|
<partinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Ralph</firstname>
|
||||||
|
<surname>Metzler</surname>
|
||||||
|
<othername role="mi">J. K.</othername>
|
||||||
|
<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Marcus</firstname>
|
||||||
|
<surname>Metzler</surname>
|
||||||
|
<othername role="mi">O. C.</othername>
|
||||||
|
<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Mauro</firstname>
|
||||||
|
<surname>Chehab</surname>
|
||||||
|
<othername role="mi">Carvalho</othername>
|
||||||
|
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
|
||||||
|
<contrib>Ported document to Docbook XML.</contrib>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
<copyright>
|
||||||
|
<year>2002</year>
|
||||||
|
<year>2003</year>
|
||||||
|
<year>2009</year>
|
||||||
|
<holder>Convergence GmbH</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<revhistory>
|
||||||
|
<!-- Put document revisions here, newest first. -->
|
||||||
|
<revision>
|
||||||
|
<revnumber>2.0.1</revnumber>
|
||||||
|
<date>2009-09-16</date>
|
||||||
|
<authorinitials>mcc</authorinitials>
|
||||||
|
<revremark>
|
||||||
|
Added ISDB-T test originally written by Patrick Boettcher
|
||||||
|
</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>2.0.0</revnumber>
|
||||||
|
<date>2009-09-06</date>
|
||||||
|
<authorinitials>mcc</authorinitials>
|
||||||
|
<revremark>Conversion from LaTex to DocBook XML. The
|
||||||
|
contents is the same as the original LaTex version.</revremark>
|
||||||
|
</revision>
|
||||||
|
<revision>
|
||||||
|
<revnumber>1.0.0</revnumber>
|
||||||
|
<date>2003-07-24</date>
|
||||||
|
<authorinitials>rjkm</authorinitials>
|
||||||
|
<revremark>Initial revision on LaTEX.</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</partinfo>
|
||||||
|
|
||||||
|
|
||||||
|
<title>LINUX DVB API</title>
|
||||||
|
<subtitle>Version 3</subtitle>
|
||||||
|
<!-- ADD THE CHAPTERS HERE -->
|
||||||
|
<chapter id="dvb_introdution">
|
||||||
|
&sub-intro;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_frontend">
|
||||||
|
&sub-frontend;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_demux">
|
||||||
|
&sub-demux;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_video">
|
||||||
|
&sub-video;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_audio">
|
||||||
|
&sub-audio;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_ca">
|
||||||
|
&sub-ca;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_net">
|
||||||
|
&sub-net;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_kdapi">
|
||||||
|
&sub-kdapi;
|
||||||
|
</chapter>
|
||||||
|
<chapter id="dvb_examples">
|
||||||
|
&sub-examples;
|
||||||
|
</chapter>
|
||||||
|
<!-- END OF CHAPTERS -->
|
Binary file not shown.
After Width: | Height: | Size: 22 KiB |
|
@ -0,0 +1,365 @@
|
||||||
|
<title>Examples</title>
|
||||||
|
<para>In this section we would like to present some examples for using the DVB API.
|
||||||
|
</para>
|
||||||
|
<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged
|
||||||
|
with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section id="tuning">
|
||||||
|
<title>Tuning</title>
|
||||||
|
<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as
|
||||||
|
the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
|
||||||
|
QAM.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
#include <sys/ioctl.h>
|
||||||
|
#include <stdio.h>
|
||||||
|
#include <stdint.h>
|
||||||
|
#include <sys/types.h>
|
||||||
|
#include <sys/stat.h>
|
||||||
|
#include <fcntl.h>
|
||||||
|
#include <time.h>
|
||||||
|
#include <unistd.h>
|
||||||
|
|
||||||
|
#include <linux/dvb/dmx.h>
|
||||||
|
#include <linux/dvb/frontend.h>
|
||||||
|
#include <linux/dvb/sec.h>
|
||||||
|
#include <sys/poll.h>
|
||||||
|
|
||||||
|
#define DMX "/dev/dvb/adapter0/demux1"
|
||||||
|
#define FRONT "/dev/dvb/adapter0/frontend1"
|
||||||
|
#define SEC "/dev/dvb/adapter0/sec1"
|
||||||
|
|
||||||
|
/⋆ routine for checking if we have a signal and other status information⋆/
|
||||||
|
int FEReadStatus(int fd, fe_status_t ⋆stat)
|
||||||
|
{
|
||||||
|
int ans;
|
||||||
|
|
||||||
|
if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
|
||||||
|
perror("FE READ STATUS: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (⋆stat & FE_HAS_POWER)
|
||||||
|
printf("FE HAS POWER\n");
|
||||||
|
|
||||||
|
if (⋆stat & FE_HAS_SIGNAL)
|
||||||
|
printf("FE HAS SIGNAL\n");
|
||||||
|
|
||||||
|
if (⋆stat & FE_SPECTRUM_INV)
|
||||||
|
printf("SPEKTRUM INV\n");
|
||||||
|
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
/⋆ tune qpsk ⋆/
|
||||||
|
/⋆ freq: frequency of transponder ⋆/
|
||||||
|
/⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/
|
||||||
|
/⋆ diseqc: DiSEqC address of the used LNB ⋆/
|
||||||
|
/⋆ pol: Polarisation ⋆/
|
||||||
|
/⋆ srate: Symbol Rate ⋆/
|
||||||
|
/⋆ fec. FEC ⋆/
|
||||||
|
/⋆ lnb_lof1: local frequency of lower LNB band ⋆/
|
||||||
|
/⋆ lnb_lof2: local frequency of upper LNB band ⋆/
|
||||||
|
/⋆ lnb_slof: switch frequency of LNB ⋆/
|
||||||
|
|
||||||
|
int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
|
||||||
|
int diseqc, int pol, int srate, int fec, int lnb_lof1,
|
||||||
|
int lnb_lof2, int lnb_slof)
|
||||||
|
{
|
||||||
|
struct secCommand scmd;
|
||||||
|
struct secCmdSequence scmds;
|
||||||
|
struct dmx_pes_filter_params pesFilterParams;
|
||||||
|
FrontendParameters frp;
|
||||||
|
struct pollfd pfd[1];
|
||||||
|
FrontendEvent event;
|
||||||
|
int demux1, demux2, demux3, front;
|
||||||
|
|
||||||
|
frequency = (uint32_t) freq;
|
||||||
|
symbolrate = (uint32_t) srate;
|
||||||
|
|
||||||
|
if((front = open(FRONT,O_RDWR)) < 0){
|
||||||
|
perror("FRONTEND DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
if((sec = open(SEC,O_RDWR)) < 0){
|
||||||
|
perror("SEC DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (demux1 < 0){
|
||||||
|
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
|
||||||
|
< 0){
|
||||||
|
perror("DEMUX DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (demux2 < 0){
|
||||||
|
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
|
||||||
|
< 0){
|
||||||
|
perror("DEMUX DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (demux3 < 0){
|
||||||
|
if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
|
||||||
|
< 0){
|
||||||
|
perror("DEMUX DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (freq < lnb_slof) {
|
||||||
|
frp.Frequency = (freq - lnb_lof1);
|
||||||
|
scmds.continuousTone = SEC_TONE_OFF;
|
||||||
|
} else {
|
||||||
|
frp.Frequency = (freq - lnb_lof2);
|
||||||
|
scmds.continuousTone = SEC_TONE_ON;
|
||||||
|
}
|
||||||
|
frp.Inversion = INVERSION_AUTO;
|
||||||
|
if (pol) scmds.voltage = SEC_VOLTAGE_18;
|
||||||
|
else scmds.voltage = SEC_VOLTAGE_13;
|
||||||
|
|
||||||
|
scmd.type=0;
|
||||||
|
scmd.u.diseqc.addr=0x10;
|
||||||
|
scmd.u.diseqc.cmd=0x38;
|
||||||
|
scmd.u.diseqc.numParams=1;
|
||||||
|
scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) |
|
||||||
|
(scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
|
||||||
|
(scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
|
||||||
|
|
||||||
|
scmds.miniCommand=SEC_MINI_NONE;
|
||||||
|
scmds.numCommands=1;
|
||||||
|
scmds.commands=&scmd;
|
||||||
|
if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
|
||||||
|
perror("SEC SEND: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
|
||||||
|
perror("SEC SEND: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
frp.u.qpsk.SymbolRate = srate;
|
||||||
|
frp.u.qpsk.FEC_inner = fec;
|
||||||
|
|
||||||
|
if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){
|
||||||
|
perror("QPSK TUNE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
pfd[0].fd = front;
|
||||||
|
pfd[0].events = POLLIN;
|
||||||
|
|
||||||
|
if (poll(pfd,1,3000)){
|
||||||
|
if (pfd[0].revents & POLLIN){
|
||||||
|
printf("Getting QPSK event\n");
|
||||||
|
if ( ioctl(front, FE_GET_EVENT, &event)
|
||||||
|
|
||||||
|
== -EOVERFLOW){
|
||||||
|
perror("qpsk get event");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
printf("Received ");
|
||||||
|
switch(event.type){
|
||||||
|
case FE_UNEXPECTED_EV:
|
||||||
|
printf("unexpected event\n");
|
||||||
|
return -1;
|
||||||
|
case FE_FAILURE_EV:
|
||||||
|
printf("failure event\n");
|
||||||
|
return -1;
|
||||||
|
|
||||||
|
case FE_COMPLETION_EV:
|
||||||
|
printf("completion event\n");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
pesFilterParams.pid = vpid;
|
||||||
|
pesFilterParams.input = DMX_IN_FRONTEND;
|
||||||
|
pesFilterParams.output = DMX_OUT_DECODER;
|
||||||
|
pesFilterParams.pes_type = DMX_PES_VIDEO;
|
||||||
|
pesFilterParams.flags = DMX_IMMEDIATE_START;
|
||||||
|
if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
|
||||||
|
perror("set_vpid");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
pesFilterParams.pid = apid;
|
||||||
|
pesFilterParams.input = DMX_IN_FRONTEND;
|
||||||
|
pesFilterParams.output = DMX_OUT_DECODER;
|
||||||
|
pesFilterParams.pes_type = DMX_PES_AUDIO;
|
||||||
|
pesFilterParams.flags = DMX_IMMEDIATE_START;
|
||||||
|
if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
|
||||||
|
perror("set_apid");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
pesFilterParams.pid = tpid;
|
||||||
|
pesFilterParams.input = DMX_IN_FRONTEND;
|
||||||
|
pesFilterParams.output = DMX_OUT_DECODER;
|
||||||
|
pesFilterParams.pes_type = DMX_PES_TELETEXT;
|
||||||
|
pesFilterParams.flags = DMX_IMMEDIATE_START;
|
||||||
|
if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
|
||||||
|
perror("set_tpid");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
return has_signal(fds);
|
||||||
|
}
|
||||||
|
|
||||||
|
</programlisting>
|
||||||
|
<para>The program assumes that you are using a universal LNB and a standard DiSEqC
|
||||||
|
switch with up to 4 addresses. Of course, you could build in some more checking if
|
||||||
|
tuning was successful and maybe try to repeat the tuning process. Depending on the
|
||||||
|
external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
|
||||||
|
necessary.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="the_dvr_device">
|
||||||
|
<title>The DVR device</title>
|
||||||
|
<para>The following program code shows how to use the DVR device for recording.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
#include <sys/ioctl.h>
|
||||||
|
#include <stdio.h>
|
||||||
|
#include <stdint.h>
|
||||||
|
#include <sys/types.h>
|
||||||
|
#include <sys/stat.h>
|
||||||
|
#include <fcntl.h>
|
||||||
|
#include <time.h>
|
||||||
|
#include <unistd.h>
|
||||||
|
|
||||||
|
#include <linux/dvb/dmx.h>
|
||||||
|
#include <linux/dvb/video.h>
|
||||||
|
#include <sys/poll.h>
|
||||||
|
#define DVR "/dev/dvb/adapter0/dvr1"
|
||||||
|
#define AUDIO "/dev/dvb/adapter0/audio1"
|
||||||
|
#define VIDEO "/dev/dvb/adapter0/video1"
|
||||||
|
|
||||||
|
#define BUFFY (188⋆20)
|
||||||
|
#define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/
|
||||||
|
|
||||||
|
|
||||||
|
/⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/
|
||||||
|
|
||||||
|
/⋆ demux1, demux2: file descriptor of video and audio filters ⋆/
|
||||||
|
/⋆ vpid, apid: PIDs of video and audio channels ⋆/
|
||||||
|
|
||||||
|
int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
|
||||||
|
{
|
||||||
|
struct dmx_pes_filter_params pesFilterParams;
|
||||||
|
|
||||||
|
if (demux1 < 0){
|
||||||
|
if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
|
||||||
|
< 0){
|
||||||
|
perror("DEMUX DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (demux2 < 0){
|
||||||
|
if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
|
||||||
|
< 0){
|
||||||
|
perror("DEMUX DEVICE: ");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
pesFilterParams.pid = vpid;
|
||||||
|
pesFilterParams.input = DMX_IN_FRONTEND;
|
||||||
|
pesFilterParams.output = DMX_OUT_TS_TAP;
|
||||||
|
pesFilterParams.pes_type = DMX_PES_VIDEO;
|
||||||
|
pesFilterParams.flags = DMX_IMMEDIATE_START;
|
||||||
|
if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
|
||||||
|
perror("DEMUX DEVICE");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
pesFilterParams.pid = apid;
|
||||||
|
pesFilterParams.input = DMX_IN_FRONTEND;
|
||||||
|
pesFilterParams.output = DMX_OUT_TS_TAP;
|
||||||
|
pesFilterParams.pes_type = DMX_PES_AUDIO;
|
||||||
|
pesFilterParams.flags = DMX_IMMEDIATE_START;
|
||||||
|
if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
|
||||||
|
perror("DEMUX DEVICE");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/
|
||||||
|
|
||||||
|
/⋆ demux1, demux2: file descriptor of video and audio filters ⋆/
|
||||||
|
/⋆ vpid, apid: PIDs of video and audio channels ⋆/
|
||||||
|
int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
|
||||||
|
{
|
||||||
|
int i;
|
||||||
|
int len;
|
||||||
|
int written;
|
||||||
|
uint8_t buf[BUFFY];
|
||||||
|
uint64_t length;
|
||||||
|
struct pollfd pfd[1];
|
||||||
|
int dvr, dvr_out;
|
||||||
|
|
||||||
|
/⋆ open dvr device ⋆/
|
||||||
|
if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){
|
||||||
|
perror("DVR DEVICE");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
/⋆ switch video and audio demuxes to dvr ⋆/
|
||||||
|
printf ("Switching dvr on\n");
|
||||||
|
i = switch_to_record(demux1, demux2, vpid, apid);
|
||||||
|
printf("finished: ");
|
||||||
|
|
||||||
|
printf("Recording %2.0f MB of test file in TS format\n",
|
||||||
|
MAX_LENGTH/(1024.0⋆1024.0));
|
||||||
|
length = 0;
|
||||||
|
|
||||||
|
/⋆ open output file ⋆/
|
||||||
|
if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
|
||||||
|
|O_TRUNC, S_IRUSR|S_IWUSR
|
||||||
|
|S_IRGRP|S_IWGRP|S_IROTH|
|
||||||
|
S_IWOTH)) < 0){
|
||||||
|
perror("Can't open file for dvr test");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
pfd[0].fd = dvr;
|
||||||
|
pfd[0].events = POLLIN;
|
||||||
|
|
||||||
|
/⋆ poll for dvr data and write to file ⋆/
|
||||||
|
while (length < MAX_LENGTH ) {
|
||||||
|
if (poll(pfd,1,1)){
|
||||||
|
if (pfd[0].revents & POLLIN){
|
||||||
|
len = read(dvr, buf, BUFFY);
|
||||||
|
if (len < 0){
|
||||||
|
perror("recording");
|
||||||
|
return -1;
|
||||||
|
}
|
||||||
|
if (len > 0){
|
||||||
|
written = 0;
|
||||||
|
while (written < len)
|
||||||
|
written +=
|
||||||
|
write (dvr_out,
|
||||||
|
buf, len);
|
||||||
|
length += len;
|
||||||
|
printf("written %2.0f MB\r",
|
||||||
|
length/1024./1024.);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
</section>
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,191 @@
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<section id="requisites">
|
||||||
|
<title>What you need to know</title>
|
||||||
|
|
||||||
|
<para>The reader of this document is required to have some knowledge in
|
||||||
|
the area of digital video broadcasting (DVB) and should be familiar with
|
||||||
|
part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
|
||||||
|
you should know what a program/transport stream (PS/TS) is and what is
|
||||||
|
meant by a packetized elementary stream (PES) or an I-frame.</para>
|
||||||
|
|
||||||
|
<para>Various DVB standards documents are available from
|
||||||
|
<ulink url="http://www.dvb.org" /> and/or
|
||||||
|
<ulink url="http://www.etsi.org" />.</para>
|
||||||
|
|
||||||
|
<para>It is also necessary to know how to access unix/linux devices and
|
||||||
|
how to use ioctl calls. This also includes the knowledge of C or C++.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="history">
|
||||||
|
<title>History</title>
|
||||||
|
|
||||||
|
<para>The first API for DVB cards we used at Convergence in late 1999
|
||||||
|
was an extension of the Video4Linux API which was primarily developed
|
||||||
|
for frame grabber cards. As such it was not really well suited to be
|
||||||
|
used for DVB cards and their new features like recording MPEG streams
|
||||||
|
and filtering several section and PES data streams at the same time.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>In early 2000, we were approached by Nokia with a proposal for a
|
||||||
|
new standard Linux DVB API. As a commitment to the development of
|
||||||
|
terminals based on open standards, Nokia and Convergence made it
|
||||||
|
available to all Linux developers and published it on
|
||||||
|
<ulink url="http://www.linuxtv.org/" /> in September 2000.
|
||||||
|
Convergence is the maintainer of the Linux DVB API. Together with the
|
||||||
|
LinuxTV community (i.e. you, the reader of this document), the Linux DVB
|
||||||
|
API will be constantly reviewed and improved. With the Linux driver for
|
||||||
|
the Siemens/Hauppauge DVB PCI card Convergence provides a first
|
||||||
|
implementation of the Linux DVB API.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="overview">
|
||||||
|
<title>Overview</title>
|
||||||
|
|
||||||
|
<figure id="stb_components">
|
||||||
|
<title>Components of a DVB card/STB</title>
|
||||||
|
<mediaobject>
|
||||||
|
<imageobject>
|
||||||
|
<imagedata fileref="dvbstb.pdf" format="PS" />
|
||||||
|
</imageobject>
|
||||||
|
<imageobject>
|
||||||
|
<imagedata fileref="dvbstb.png" format="PNG" />
|
||||||
|
</imageobject>
|
||||||
|
</mediaobject>
|
||||||
|
</figure>
|
||||||
|
|
||||||
|
<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
|
||||||
|
following main hardware components: </para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para>Frontend consisting of tuner and DVB demodulator</para>
|
||||||
|
|
||||||
|
<para>Here the raw signal reaches the DVB hardware from a satellite dish
|
||||||
|
or antenna or directly from cable. The frontend down-converts and
|
||||||
|
demodulates this signal into an MPEG transport stream (TS). In case of a
|
||||||
|
satellite frontend, this includes a facility for satellite equipment
|
||||||
|
control (SEC), which allows control of LNB polarization, multi feed
|
||||||
|
switches or dish rotors.</para>
|
||||||
|
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para>Conditional Access (CA) hardware like CI adapters and smartcard slots
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The complete TS is passed through the CA hardware. Programs to
|
||||||
|
which the user has access (controlled by the smart card) are decoded in
|
||||||
|
real time and re-inserted into the TS.</para>
|
||||||
|
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>Demultiplexer which filters the incoming DVB stream</para>
|
||||||
|
|
||||||
|
<para>The demultiplexer splits the TS into its components like audio and
|
||||||
|
video streams. Besides usually several of such audio and video streams
|
||||||
|
it also contains data streams with information about the programs
|
||||||
|
offered in this or other streams of the same provider.</para>
|
||||||
|
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para>MPEG2 audio and video decoder</para>
|
||||||
|
|
||||||
|
<para>The main targets of the demultiplexer are the MPEG2 audio and
|
||||||
|
video decoders. After decoding they pass on the uncompressed audio and
|
||||||
|
video to the computer screen or (through a PAL/NTSC encoder) to a TV
|
||||||
|
set.</para>
|
||||||
|
|
||||||
|
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
|
||||||
|
between those components.</para>
|
||||||
|
|
||||||
|
<para>On a DVB PCI card not all of these have to be present since some
|
||||||
|
functionality can be provided by the main CPU of the PC (e.g. MPEG
|
||||||
|
picture and sound decoding) or is not needed (e.g. for data-only uses
|
||||||
|
like “internet over satellite”). Also not every card or STB
|
||||||
|
provides conditional access hardware.</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="dvb_devices">
|
||||||
|
<title>Linux DVB Devices</title>
|
||||||
|
|
||||||
|
<para>The Linux DVB API lets you control these hardware components
|
||||||
|
through currently six Unix-style character devices for video, audio,
|
||||||
|
frontend, demux, CA and IP-over-DVB networking. The video and audio
|
||||||
|
devices control the MPEG2 decoder hardware, the frontend device the
|
||||||
|
tuner and the DVB demodulator. The demux device gives you control over
|
||||||
|
the PES and section filters of the hardware. If the hardware does not
|
||||||
|
support filtering these filters can be implemented in software. Finally,
|
||||||
|
the CA device controls all the conditional access capabilities of the
|
||||||
|
hardware. It can depend on the individual security requirements of the
|
||||||
|
platform, if and how many of the CA functions are made available to the
|
||||||
|
application through this device.</para>
|
||||||
|
|
||||||
|
<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
|
||||||
|
tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
|
||||||
|
are called:</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
|
||||||
|
<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist>
|
||||||
|
|
||||||
|
<para>where N enumerates the DVB PCI cards in a system starting
|
||||||
|
from 0, and M enumerates the devices of each type within each
|
||||||
|
adapter, starting from 0, too. We will omit the “<emphasis
|
||||||
|
role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion
|
||||||
|
of these devices. The naming scheme for the devices is the same wheter
|
||||||
|
devfs is used or not.</para>
|
||||||
|
|
||||||
|
<para>More details about the data structures and function calls of all
|
||||||
|
the devices are described in the following chapters.</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="include_files">
|
||||||
|
<title>API include files</title>
|
||||||
|
|
||||||
|
<para>For each of the DVB devices a corresponding include file exists.
|
||||||
|
The DVB API include files should be included in application sources with
|
||||||
|
a partial path like:</para>
|
||||||
|
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
#include <linux/dvb/frontend.h>
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>To enable applications to support different API version, an
|
||||||
|
additional include file <emphasis
|
||||||
|
role="tt">linux/dvb/version.h</emphasis> exists, which defines the
|
||||||
|
constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
|
||||||
|
describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
|
@ -0,0 +1,314 @@
|
||||||
|
<section id="isdbt">
|
||||||
|
<title>ISDB-T frontend</title>
|
||||||
|
<para>This section describes shortly what are the possible parameters in the Linux
|
||||||
|
DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb
|
||||||
|
demodulator:</para>
|
||||||
|
|
||||||
|
<para>This ISDB-T/ISDB-Tsb API extension should reflect all information
|
||||||
|
needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
|
||||||
|
that some very sophisticated devices won't need certain parameters to
|
||||||
|
tune.</para>
|
||||||
|
|
||||||
|
<para>The information given here should help application writers to know how
|
||||||
|
to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
|
||||||
|
|
||||||
|
<para>The details given here about ISDB-T and ISDB-Tsb are just enough to
|
||||||
|
basically show the dependencies between the needed parameter values,
|
||||||
|
but surely some information is left out. For more detailed information
|
||||||
|
see the following documents:</para>
|
||||||
|
|
||||||
|
<para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
|
||||||
|
Television Broadcasting" and</para>
|
||||||
|
<para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
|
||||||
|
Television Broadcasting".</para>
|
||||||
|
|
||||||
|
<para>In order to read this document one has to have some knowledge the
|
||||||
|
channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to
|
||||||
|
the reader that an ISDB-T channel consists of 13 segments, that it can
|
||||||
|
have up to 3 layer sharing those segments, and things like that.</para>
|
||||||
|
|
||||||
|
<para>Parameters used by ISDB-T and ISDB-Tsb.</para>
|
||||||
|
|
||||||
|
<section id="isdbt-parms">
|
||||||
|
<title>Parameters that are common with DVB-T and ATSC</title>
|
||||||
|
|
||||||
|
<section id="isdbt-freq">
|
||||||
|
<title><constant>DTV_FREQUENCY</constant></title>
|
||||||
|
|
||||||
|
<para>Central frequency of the channel.</para>
|
||||||
|
|
||||||
|
<para>For ISDB-T the channels are usally transmitted with an offset of 143kHz. E.g. a
|
||||||
|
valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
|
||||||
|
the channel which is 6MHz.</para>
|
||||||
|
|
||||||
|
<para>As in ISDB-Tsb the channel consists of only one or three segments the
|
||||||
|
frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
|
||||||
|
central frequency of the channel is expected.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-bw">
|
||||||
|
<title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title>
|
||||||
|
|
||||||
|
<para>Possible values:</para>
|
||||||
|
|
||||||
|
<para>For ISDB-T it should be always 6000000Hz (6MHz)</para>
|
||||||
|
<para>For ISDB-Tsb it can vary depending on the number of connected segments</para>
|
||||||
|
|
||||||
|
<para>Note: Hardware specific values might be given here, but standard
|
||||||
|
applications should not bother to set a value to this field as
|
||||||
|
standard demods are ignoring it anyway.</para>
|
||||||
|
|
||||||
|
<para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
|
||||||
|
other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
|
||||||
|
DTV_ISDBT_SB_SEGMENT_COUNT).</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-delivery-sys">
|
||||||
|
<title><constant>DTV_DELIVERY_SYSTEM</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: <constant>SYS_ISDBT</constant></para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-tx-mode">
|
||||||
|
<title><constant>DTV_TRANSMISSION_MODE</constant></title>
|
||||||
|
|
||||||
|
<para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
|
||||||
|
'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
|
||||||
|
|
||||||
|
<para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>,
|
||||||
|
<constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para>
|
||||||
|
|
||||||
|
<para>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
|
||||||
|
hardware will try to find the correct FFT-size (if capable) and will
|
||||||
|
use TMCC to fill in the missing parameters.</para>
|
||||||
|
|
||||||
|
<para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-guard-interval">
|
||||||
|
<title><constant>DTV_GUARD_INTERVAL</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>,
|
||||||
|
<constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para>
|
||||||
|
|
||||||
|
<para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
|
||||||
|
try to find the correct guard interval (if capable) and will use TMCC to fill
|
||||||
|
in the missing parameters.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
<section id="isdbt-new-parms">
|
||||||
|
<title>ISDB-T only parameters</title>
|
||||||
|
|
||||||
|
<section id="isdbt-part-rec">
|
||||||
|
<title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
|
||||||
|
|
||||||
|
<para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
|
||||||
|
the channel is in partial reception mode or not.</para>
|
||||||
|
|
||||||
|
<para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
|
||||||
|
<constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
|
||||||
|
|
||||||
|
<para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
|
||||||
|
<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
|
||||||
|
is consisting of one segment and layer or three segments and two layers.</para>
|
||||||
|
|
||||||
|
<para>Possible values: 0, 1, -1 (AUTO)</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-sound-bcast">
|
||||||
|
<title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
|
||||||
|
|
||||||
|
<para>This field represents whether the other DTV_ISDBT_*-parameters are
|
||||||
|
referring to an ISDB-T and an ISDB-Tsb channel. (See also
|
||||||
|
<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
|
||||||
|
|
||||||
|
<para>Possible values: 0, 1, -1 (AUTO)</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-sb-ch-id">
|
||||||
|
<title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
|
||||||
|
|
||||||
|
<para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
|
||||||
|
|
||||||
|
<para>(Note of the author: This might not be the correct description of the
|
||||||
|
<constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
|
||||||
|
background needed to program a device)</para>
|
||||||
|
|
||||||
|
<para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
|
||||||
|
set of connected ISDB-Tsb channels. In this set of channels every
|
||||||
|
channel can be received independently. The number of connected
|
||||||
|
ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
|
||||||
|
bandwidth available.</para>
|
||||||
|
|
||||||
|
<para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
|
||||||
|
broadcaster has several possibilities to put those channels in the
|
||||||
|
air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
|
||||||
|
segments from position 1-8 to 5-13 or anything in between.</para>
|
||||||
|
|
||||||
|
<para>The underlying layer of segments are subchannels: each segment is
|
||||||
|
consisting of several subchannels with a predefined IDs. A sub-channel
|
||||||
|
is used to help the demodulator to synchronize on the channel.</para>
|
||||||
|
|
||||||
|
<para>An ISDB-T channel is always centered over all sub-channels. As for
|
||||||
|
the example above, in ISDB-Tsb it is no longer as simple as that.</para>
|
||||||
|
|
||||||
|
<para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
|
||||||
|
sub-channel ID of the segment to be demodulated.</para>
|
||||||
|
|
||||||
|
<para>Possible values: 0 .. 41, -1 (AUTO)</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-sb-seg-idx">
|
||||||
|
|
||||||
|
<title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
|
||||||
|
|
||||||
|
<para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
|
||||||
|
|
||||||
|
<para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
|
||||||
|
demodulated for an ISDB-Tsb channel where several of them are
|
||||||
|
transmitted in the connected manner.</para>
|
||||||
|
|
||||||
|
<para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
|
||||||
|
|
||||||
|
<para>Note: This value cannot be determined by an automatic channel search.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-sb-seg-cnt">
|
||||||
|
<title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
|
||||||
|
|
||||||
|
<para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
|
||||||
|
|
||||||
|
<para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
|
||||||
|
channels.</para>
|
||||||
|
|
||||||
|
<para>Possible values: 1 .. 13</para>
|
||||||
|
|
||||||
|
<para>Note: This value cannot be determined by an automatic channel search.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdb-hierq-layers">
|
||||||
|
<title>Hierarchical layers</title>
|
||||||
|
|
||||||
|
<para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
|
||||||
|
ISDB-T hierarchical layers can be decoded simultaneously. For that
|
||||||
|
reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para>
|
||||||
|
|
||||||
|
<para>ISDB-T has 3 hierarchical layers which each can use a part of the
|
||||||
|
available segments. The total number of segments over all layers has
|
||||||
|
to 13 in ISDB-T.</para>
|
||||||
|
|
||||||
|
<section id="isdbt-layer-ena">
|
||||||
|
<title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
|
||||||
|
|
||||||
|
<para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
|
||||||
|
layers in the decoding process. Setting all bits of
|
||||||
|
<constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
|
||||||
|
demodulated. This is the default.</para>
|
||||||
|
|
||||||
|
<para>If the channel is in the partial reception mode
|
||||||
|
(<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
|
||||||
|
independently of the other 12 segments. In that mode layer A has to
|
||||||
|
have a <constant>SEGMENT_COUNT</constant> of 1.</para>
|
||||||
|
|
||||||
|
<para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
|
||||||
|
according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
|
||||||
|
accordingly.</para>
|
||||||
|
|
||||||
|
<para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
|
||||||
|
|
||||||
|
<para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
|
||||||
|
<para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
|
||||||
|
<para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
|
||||||
|
<para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-layer-fec">
|
||||||
|
<title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-layer-mod">
|
||||||
|
<title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
|
||||||
|
|
||||||
|
<para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
|
||||||
|
and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt-layer-seg-cnt">
|
||||||
|
<title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
|
||||||
|
|
||||||
|
<para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
|
||||||
|
<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
|
||||||
|
|
||||||
|
<informaltable id="isdbt-layer_seg-cnt-table">
|
||||||
|
<tgroup cols="6">
|
||||||
|
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry>PR</entry>
|
||||||
|
<entry>SB</entry>
|
||||||
|
<entry>Layer A width</entry>
|
||||||
|
<entry>Layer B width</entry>
|
||||||
|
<entry>Layer C width</entry>
|
||||||
|
<entry>total width</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>1 .. 13</entry>
|
||||||
|
<entry>1 .. 13</entry>
|
||||||
|
<entry>1 .. 13</entry>
|
||||||
|
<entry>13</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>1 .. 13</entry>
|
||||||
|
<entry>1 .. 13</entry>
|
||||||
|
<entry>13</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>1</entry>
|
||||||
|
<entry>2</entry>
|
||||||
|
<entry>0</entry>
|
||||||
|
<entry>13</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
|
||||||
|
</tgroup>
|
||||||
|
</informaltable>
|
||||||
|
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="isdbt_layer_t_interl">
|
||||||
|
<title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
|
||||||
|
|
||||||
|
<para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
|
||||||
|
|
||||||
|
<para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
|
||||||
|
here are referring to what can be found in the TMCC-structure -
|
||||||
|
independent of the mode.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
</section>
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,12 @@
|
||||||
|
<title>DVB Network API</title>
|
||||||
|
<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
|
||||||
|
received via DVB into the Linux network protocol stack, e.g. for internet via satellite
|
||||||
|
applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
|
||||||
|
and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
|
||||||
|
application.
|
||||||
|
</para>
|
||||||
|
<section id="dvb_net_types">
|
||||||
|
<title>DVB Net Data Types</title>
|
||||||
|
<para>To be written…
|
||||||
|
</para>
|
||||||
|
</section>
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,421 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="Linux-filesystems-API">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Linux Filesystems API</title>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="vfs">
|
||||||
|
<title>The Linux VFS</title>
|
||||||
|
<sect1 id="the_filesystem_types"><title>The Filesystem types</title>
|
||||||
|
!Iinclude/linux/fs.h
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="the_directory_cache"><title>The Directory Cache</title>
|
||||||
|
!Efs/dcache.c
|
||||||
|
!Iinclude/linux/dcache.h
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="inode_handling"><title>Inode Handling</title>
|
||||||
|
!Efs/inode.c
|
||||||
|
!Efs/bad_inode.c
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="registration_and_superblocks"><title>Registration and Superblocks</title>
|
||||||
|
!Efs/super.c
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="file_locks"><title>File Locks</title>
|
||||||
|
!Efs/locks.c
|
||||||
|
!Ifs/locks.c
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="other_functions"><title>Other Functions</title>
|
||||||
|
!Efs/mpage.c
|
||||||
|
!Efs/namei.c
|
||||||
|
!Efs/buffer.c
|
||||||
|
!Efs/bio.c
|
||||||
|
!Efs/seq_file.c
|
||||||
|
!Efs/filesystems.c
|
||||||
|
!Efs/fs-writeback.c
|
||||||
|
!Efs/block_dev.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="proc">
|
||||||
|
<title>The proc filesystem</title>
|
||||||
|
|
||||||
|
<sect1 id="sysctl_interface"><title>sysctl interface</title>
|
||||||
|
!Ekernel/sysctl.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="proc_filesystem_interface"><title>proc filesystem interface</title>
|
||||||
|
!Ifs/proc/base.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="sysfs">
|
||||||
|
<title>The Filesystem for Exporting Kernel Objects</title>
|
||||||
|
!Efs/sysfs/file.c
|
||||||
|
!Efs/sysfs/symlink.c
|
||||||
|
!Efs/sysfs/bin.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="debugfs">
|
||||||
|
<title>The debugfs filesystem</title>
|
||||||
|
|
||||||
|
<sect1 id="debugfs_interface"><title>debugfs interface</title>
|
||||||
|
!Efs/debugfs/inode.c
|
||||||
|
!Efs/debugfs/file.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="LinuxJDBAPI">
|
||||||
|
<chapterinfo>
|
||||||
|
<title>The Linux Journalling API</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Roger</firstname>
|
||||||
|
<surname>Gammans</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>rgammans@computer-surgery.co.uk</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Stephen</firstname>
|
||||||
|
<surname>Tweedie</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>sct@redhat.com</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2002</year>
|
||||||
|
<holder>Roger Gammans</holder>
|
||||||
|
</copyright>
|
||||||
|
</chapterinfo>
|
||||||
|
|
||||||
|
<title>The Linux Journalling API</title>
|
||||||
|
|
||||||
|
<sect1 id="journaling_overview">
|
||||||
|
<title>Overview</title>
|
||||||
|
<sect2 id="journaling_details">
|
||||||
|
<title>Details</title>
|
||||||
|
<para>
|
||||||
|
The journalling layer is easy to use. You need to
|
||||||
|
first of all create a journal_t data structure. There are
|
||||||
|
two calls to do this dependent on how you decide to allocate the physical
|
||||||
|
media on which the journal resides. The journal_init_inode() call
|
||||||
|
is for journals stored in filesystem inodes, or the journal_init_dev()
|
||||||
|
call can be use for journal stored on a raw device (in a continuous range
|
||||||
|
of blocks). A journal_t is a typedef for a struct pointer, so when
|
||||||
|
you are finally finished make sure you call journal_destroy() on it
|
||||||
|
to free up any used kernel memory.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once you have got your journal_t object you need to 'mount' or load the journal
|
||||||
|
file, unless of course you haven't initialised it yet - in which case you
|
||||||
|
need to call journal_create().
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Most of the time however your journal file will already have been created, but
|
||||||
|
before you load it you must call journal_wipe() to empty the journal file.
|
||||||
|
Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the
|
||||||
|
job of the client file system to detect this and skip the call to journal_wipe().
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In either case the next call should be to journal_load() which prepares the
|
||||||
|
journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery()
|
||||||
|
for you if it detects any outstanding transactions in the journal and similarly
|
||||||
|
journal_load() will call journal_recover() if necessary.
|
||||||
|
I would advise reading fs/ext3/super.c for examples on this stage.
|
||||||
|
[RGG: Why is the journal_wipe() call necessary - doesn't this needlessly
|
||||||
|
complicate the API. Or isn't a good idea for the journal layer to hide
|
||||||
|
dirty mounts from the client fs]
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Now you can go ahead and start modifying the underlying
|
||||||
|
filesystem. Almost.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
|
||||||
|
You still need to actually journal your filesystem changes, this
|
||||||
|
is done by wrapping them into transactions. Additionally you
|
||||||
|
also need to wrap the modification of each of the buffers
|
||||||
|
with calls to the journal layer, so it knows what the modifications
|
||||||
|
you are actually making are. To do this use journal_start() which
|
||||||
|
returns a transaction handle.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
journal_start()
|
||||||
|
and its counterpart journal_stop(), which indicates the end of a transaction
|
||||||
|
are nestable calls, so you can reenter a transaction if necessary,
|
||||||
|
but remember you must call journal_stop() the same number of times as
|
||||||
|
journal_start() before the transaction is completed (or more accurately
|
||||||
|
leaves the update phase). Ext3/VFS makes use of this feature to simplify
|
||||||
|
quota support.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Inside each transaction you need to wrap the modifications to the
|
||||||
|
individual buffers (blocks). Before you start to modify a buffer you
|
||||||
|
need to call journal_get_{create,write,undo}_access() as appropriate,
|
||||||
|
this allows the journalling layer to copy the unmodified data if it
|
||||||
|
needs to. After all the buffer may be part of a previously uncommitted
|
||||||
|
transaction.
|
||||||
|
At this point you are at last ready to modify a buffer, and once
|
||||||
|
you are have done so you need to call journal_dirty_{meta,}data().
|
||||||
|
Or if you've asked for access to a buffer you now know is now longer
|
||||||
|
required to be pushed back on the device you can call journal_forget()
|
||||||
|
in much the same way as you might have used bforget() in the past.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A journal_flush() may be called at any time to commit and checkpoint
|
||||||
|
all your transactions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Then at umount time , in your put_super() (2.4) or write_super() (2.5)
|
||||||
|
you can then call journal_destroy() to clean up your in-core journal object.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Unfortunately there a couple of ways the journal layer can cause a deadlock.
|
||||||
|
The first thing to note is that each task can only have
|
||||||
|
a single outstanding transaction at any one time, remember nothing
|
||||||
|
commits until the outermost journal_stop(). This means
|
||||||
|
you must complete the transaction at the end of each file/inode/address
|
||||||
|
etc. operation you perform, so that the journalling system isn't re-entered
|
||||||
|
on another journal. Since transactions can't be nested/batched
|
||||||
|
across differing journals, and another filesystem other than
|
||||||
|
yours (say ext3) may be modified in a later syscall.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The second case to bear in mind is that journal_start() can
|
||||||
|
block if there isn't enough space in the journal for your transaction
|
||||||
|
(based on the passed nblocks param) - when it blocks it merely(!) needs to
|
||||||
|
wait for transactions to complete and be committed from other tasks,
|
||||||
|
so essentially we are waiting for journal_stop(). So to avoid
|
||||||
|
deadlocks you must treat journal_start/stop() as if they
|
||||||
|
were semaphores and include them in your semaphore ordering rules to prevent
|
||||||
|
deadlocks. Note that journal_extend() has similar blocking behaviour to
|
||||||
|
journal_start() so you can deadlock here just as easily as on journal_start().
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Try to reserve the right number of blocks the first time. ;-). This will
|
||||||
|
be the maximum number of blocks you are going to touch in this transaction.
|
||||||
|
I advise having a look at at least ext3_jbd.h to see the basis on which
|
||||||
|
ext3 uses to make these decisions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Another wriggle to watch out for is your on-disk block allocation strategy.
|
||||||
|
why? Because, if you undo a delete, you need to ensure you haven't reused any
|
||||||
|
of the freed blocks in a later transaction. One simple way of doing this
|
||||||
|
is make sure any blocks you allocate only have checkpointed transactions
|
||||||
|
listed against them. Ext3 does this in ext3_test_allocatable().
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Lock is also providing through journal_{un,}lock_updates(),
|
||||||
|
ext3 uses this when it wants a window with a clean and stable fs for a moment.
|
||||||
|
eg.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
|
||||||
|
journal_lock_updates() //stop new stuff happening..
|
||||||
|
journal_flush() // checkpoint everything.
|
||||||
|
..do stuff on stable fs
|
||||||
|
journal_unlock_updates() // carry on with filesystem use.
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The opportunities for abuse and DOS attacks with this should be obvious,
|
||||||
|
if you allow unprivileged userspace to trigger codepaths containing these
|
||||||
|
calls.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A new feature of jbd since 2.5.25 is commit callbacks with the new
|
||||||
|
journal_callback_set() function you can now ask the journalling layer
|
||||||
|
to call you back when the transaction is finally committed to disk, so that
|
||||||
|
you can do some of your own management. The key to this is the journal_callback
|
||||||
|
struct, this maintains the internal callback information but you can
|
||||||
|
extend it like this:-
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
struct myfs_callback_s {
|
||||||
|
//Data structure element required by jbd..
|
||||||
|
struct journal_callback for_jbd;
|
||||||
|
// Stuff for myfs allocated together.
|
||||||
|
myfs_inode* i_commited;
|
||||||
|
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
this would be useful if you needed to know when data was committed to a
|
||||||
|
particular inode.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 id="jbd_summary">
|
||||||
|
<title>Summary</title>
|
||||||
|
<para>
|
||||||
|
Using the journal is a matter of wrapping the different context changes,
|
||||||
|
being each mount, each modification (transaction) and each changed buffer
|
||||||
|
to tell the journalling layer about them.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Here is a some pseudo code to give you an idea of how it works, as
|
||||||
|
an example.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
journal_t* my_jnrl = journal_create();
|
||||||
|
journal_init_{dev,inode}(jnrl,...)
|
||||||
|
if (clean) journal_wipe();
|
||||||
|
journal_load();
|
||||||
|
|
||||||
|
foreach(transaction) { /*transactions must be
|
||||||
|
completed before
|
||||||
|
a syscall returns to
|
||||||
|
userspace*/
|
||||||
|
|
||||||
|
handle_t * xct=journal_start(my_jnrl);
|
||||||
|
foreach(bh) {
|
||||||
|
journal_get_{create,write,undo}_access(xact,bh);
|
||||||
|
if ( myfs_modify(bh) ) { /* returns true
|
||||||
|
if makes changes */
|
||||||
|
journal_dirty_{meta,}data(xact,bh);
|
||||||
|
} else {
|
||||||
|
journal_forget(bh);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
journal_stop(xct);
|
||||||
|
}
|
||||||
|
journal_destroy(my_jrnl);
|
||||||
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="data_types">
|
||||||
|
<title>Data Types</title>
|
||||||
|
<para>
|
||||||
|
The journalling layer uses typedefs to 'hide' the concrete definitions
|
||||||
|
of the structures used. As a client of the JBD layer you can
|
||||||
|
just rely on the using the pointer as a magic cookie of some sort.
|
||||||
|
|
||||||
|
Obviously the hiding is not enforced as this is 'C'.
|
||||||
|
</para>
|
||||||
|
<sect2 id="structures"><title>Structures</title>
|
||||||
|
!Iinclude/linux/jbd.h
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="functions">
|
||||||
|
<title>Functions</title>
|
||||||
|
<para>
|
||||||
|
The functions here are split into two groups those that
|
||||||
|
affect a journal as a whole, and those which are used to
|
||||||
|
manage transactions
|
||||||
|
</para>
|
||||||
|
<sect2 id="journal_level"><title>Journal Level</title>
|
||||||
|
!Efs/jbd/journal.c
|
||||||
|
!Ifs/jbd/recovery.c
|
||||||
|
</sect2>
|
||||||
|
<sect2 id="transaction_level"><title>Transasction Level</title>
|
||||||
|
!Efs/jbd/transaction.c
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="see_also">
|
||||||
|
<title>See also</title>
|
||||||
|
<para>
|
||||||
|
<citation>
|
||||||
|
<ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz">
|
||||||
|
Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie
|
||||||
|
</ulink>
|
||||||
|
</citation>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
<citation>
|
||||||
|
<ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html">
|
||||||
|
Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie
|
||||||
|
</ulink>
|
||||||
|
</citation>
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="splice">
|
||||||
|
<title>splice API</title>
|
||||||
|
<para>
|
||||||
|
splice is a method for moving blocks of data around inside the
|
||||||
|
kernel, without continually transferring them between the kernel
|
||||||
|
and user space.
|
||||||
|
</para>
|
||||||
|
!Ffs/splice.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="pipes">
|
||||||
|
<title>pipes API</title>
|
||||||
|
<para>
|
||||||
|
Pipe interfaces are all for in-kernel (builtin image) use.
|
||||||
|
They are not exported for use by modules.
|
||||||
|
</para>
|
||||||
|
!Iinclude/linux/pipe_fs_i.h
|
||||||
|
!Ffs/pipe.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
|
@ -0,0 +1,793 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="USB-Gadget-API">
|
||||||
|
<bookinfo>
|
||||||
|
<title>USB Gadget API for Linux</title>
|
||||||
|
<date>20 August 2004</date>
|
||||||
|
<edition>20 August 2004</edition>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
<copyright>
|
||||||
|
<year>2003-2004</year>
|
||||||
|
<holder>David Brownell</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<author>
|
||||||
|
<firstname>David</firstname>
|
||||||
|
<surname>Brownell</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address><email>dbrownell@users.sourceforge.net</email></address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro"><title>Introduction</title>
|
||||||
|
|
||||||
|
<para>This document presents a Linux-USB "Gadget"
|
||||||
|
kernel mode
|
||||||
|
API, for use within peripherals and other USB devices
|
||||||
|
that embed Linux.
|
||||||
|
It provides an overview of the API structure,
|
||||||
|
and shows how that fits into a system development project.
|
||||||
|
This is the first such API released on Linux to address
|
||||||
|
a number of important problems, including: </para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Supports USB 2.0, for high speed devices which
|
||||||
|
can stream data at several dozen megabytes per second.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Handles devices with dozens of endpoints just as
|
||||||
|
well as ones with just two fixed-function ones. Gadget drivers
|
||||||
|
can be written so they're easy to port to new hardware.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Flexible enough to expose more complex USB device
|
||||||
|
capabilities such as multiple configurations, multiple interfaces,
|
||||||
|
composite devices,
|
||||||
|
and alternate interface settings.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>USB "On-The-Go" (OTG) support, in conjunction
|
||||||
|
with updates to the Linux-USB host side.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Sharing data structures and API models with the
|
||||||
|
Linux-USB host side API. This helps the OTG support, and
|
||||||
|
looks forward to more-symmetric frameworks (where the same
|
||||||
|
I/O model is used by both host and device side drivers).
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Minimalist, so it's easier to support new device
|
||||||
|
controller hardware. I/O processing doesn't imply large
|
||||||
|
demands for memory or CPU resources.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
|
||||||
|
<para>Most Linux developers will not be able to use this API, since they
|
||||||
|
have USB "host" hardware in a PC, workstation, or server.
|
||||||
|
Linux users with embedded systems are more likely to
|
||||||
|
have USB peripheral hardware.
|
||||||
|
To distinguish drivers running inside such hardware from the
|
||||||
|
more familiar Linux "USB device drivers",
|
||||||
|
which are host side proxies for the real USB devices,
|
||||||
|
a different term is used:
|
||||||
|
the drivers inside the peripherals are "USB gadget drivers".
|
||||||
|
In USB protocol interactions, the device driver is the master
|
||||||
|
(or "client driver")
|
||||||
|
and the gadget driver is the slave (or "function driver").
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The gadget API resembles the host side Linux-USB API in that both
|
||||||
|
use queues of request objects to package I/O buffers, and those requests
|
||||||
|
may be submitted or canceled.
|
||||||
|
They share common definitions for the standard USB
|
||||||
|
<emphasis>Chapter 9</emphasis> messages, structures, and constants.
|
||||||
|
Also, both APIs bind and unbind drivers to devices.
|
||||||
|
The APIs differ in detail, since the host side's current
|
||||||
|
URB framework exposes a number of implementation details
|
||||||
|
and assumptions that are inappropriate for a gadget API.
|
||||||
|
While the model for control transfers and configuration
|
||||||
|
management is necessarily different (one side is a hardware-neutral master,
|
||||||
|
the other is a hardware-aware slave), the endpoint I/0 API used here
|
||||||
|
should also be usable for an overhead-reduced host side API.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="structure"><title>Structure of Gadget Drivers</title>
|
||||||
|
|
||||||
|
<para>A system running inside a USB peripheral
|
||||||
|
normally has at least three layers inside the kernel to handle
|
||||||
|
USB protocol processing, and may have additional layers in
|
||||||
|
user space code.
|
||||||
|
The "gadget" API is used by the middle layer to interact
|
||||||
|
with the lowest level (which directly handles hardware).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>In Linux, from the bottom up, these layers are:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis>USB Controller Driver</emphasis></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>This is the lowest software level.
|
||||||
|
It is the only layer that talks to hardware,
|
||||||
|
through registers, fifos, dma, irqs, and the like.
|
||||||
|
The <filename><linux/usb/gadget.h></filename> API abstracts
|
||||||
|
the peripheral controller endpoint hardware.
|
||||||
|
That hardware is exposed through endpoint objects, which accept
|
||||||
|
streams of IN/OUT buffers, and through callbacks that interact
|
||||||
|
with gadget drivers.
|
||||||
|
Since normal USB devices only have one upstream
|
||||||
|
port, they only have one of these drivers.
|
||||||
|
The controller driver can support any number of different
|
||||||
|
gadget drivers, but only one of them can be used at a time.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Examples of such controller hardware include
|
||||||
|
the PCI-based NetChip 2280 USB 2.0 high speed controller,
|
||||||
|
the SA-11x0 or PXA-25x UDC (found within many PDAs),
|
||||||
|
and a variety of other products.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</listitem></varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis>Gadget Driver</emphasis></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>The lower boundary of this driver implements hardware-neutral
|
||||||
|
USB functions, using calls to the controller driver.
|
||||||
|
Because such hardware varies widely in capabilities and restrictions,
|
||||||
|
and is used in embedded environments where space is at a premium,
|
||||||
|
the gadget driver is often configured at compile time
|
||||||
|
to work with endpoints supported by one particular controller.
|
||||||
|
Gadget drivers may be portable to several different controllers,
|
||||||
|
using conditional compilation.
|
||||||
|
(Recent kernels substantially simplify the work involved in
|
||||||
|
supporting new hardware, by <emphasis>autoconfiguring</emphasis>
|
||||||
|
endpoints automatically for many bulk-oriented drivers.)
|
||||||
|
Gadget driver responsibilities include:
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>handling setup requests (ep0 protocol responses)
|
||||||
|
possibly including class-specific functionality
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>returning configuration and string descriptors
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>(re)setting configurations and interface
|
||||||
|
altsettings, including enabling and configuring endpoints
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>handling life cycle events, such as managing
|
||||||
|
bindings to hardware,
|
||||||
|
USB suspend/resume, remote wakeup,
|
||||||
|
and disconnection from the USB host.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>managing IN and OUT transfers on all currently
|
||||||
|
enabled endpoints
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Such drivers may be modules of proprietary code, although
|
||||||
|
that approach is discouraged in the Linux community.
|
||||||
|
</para>
|
||||||
|
</listitem></varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis>Upper Level</emphasis></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Most gadget drivers have an upper boundary that connects
|
||||||
|
to some Linux driver or framework in Linux.
|
||||||
|
Through that boundary flows the data which the gadget driver
|
||||||
|
produces and/or consumes through protocol transfers over USB.
|
||||||
|
Examples include:
|
||||||
|
</para>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>user mode code, using generic (gadgetfs)
|
||||||
|
or application specific files in
|
||||||
|
<filename>/dev</filename>
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>networking subsystem (for network gadgets,
|
||||||
|
like the CDC Ethernet Model gadget driver)
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>data capture drivers, perhaps video4Linux or
|
||||||
|
a scanner driver; or test and measurement hardware.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>input subsystem (for HID gadgets)
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>sound subsystem (for audio gadgets)
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>file system (for PTP gadgets)
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>block i/o subsystem (for usb-storage gadgets)
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>... and more </para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</listitem></varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><emphasis>Additional Layers</emphasis></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Other layers may exist.
|
||||||
|
These could include kernel layers, such as network protocol stacks,
|
||||||
|
as well as user mode applications building on standard POSIX
|
||||||
|
system call APIs such as
|
||||||
|
<emphasis>open()</emphasis>, <emphasis>close()</emphasis>,
|
||||||
|
<emphasis>read()</emphasis> and <emphasis>write()</emphasis>.
|
||||||
|
On newer systems, POSIX Async I/O calls may be an option.
|
||||||
|
Such user mode code will not necessarily be subject to
|
||||||
|
the GNU General Public License (GPL).
|
||||||
|
</para>
|
||||||
|
</listitem></varlistentry>
|
||||||
|
|
||||||
|
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
|
<para>OTG-capable systems will also need to include a standard Linux-USB
|
||||||
|
host side stack,
|
||||||
|
with <emphasis>usbcore</emphasis>,
|
||||||
|
one or more <emphasis>Host Controller Drivers</emphasis> (HCDs),
|
||||||
|
<emphasis>USB Device Drivers</emphasis> to support
|
||||||
|
the OTG "Targeted Peripheral List",
|
||||||
|
and so forth.
|
||||||
|
There will also be an <emphasis>OTG Controller Driver</emphasis>,
|
||||||
|
which is visible to gadget and device driver developers only indirectly.
|
||||||
|
That helps the host and device side USB controllers implement the
|
||||||
|
two new OTG protocols (HNP and SRP).
|
||||||
|
Roles switch (host to peripheral, or vice versa) using HNP
|
||||||
|
during USB suspend processing, and SRP can be viewed as a
|
||||||
|
more battery-friendly kind of device wakeup protocol.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Over time, reusable utilities are evolving to help make some
|
||||||
|
gadget driver tasks simpler.
|
||||||
|
For example, building configuration descriptors from vectors of
|
||||||
|
descriptors for the configurations interfaces and endpoints is
|
||||||
|
now automated, and many drivers now use autoconfiguration to
|
||||||
|
choose hardware endpoints and initialize their descriptors.
|
||||||
|
|
||||||
|
A potential example of particular interest
|
||||||
|
is code implementing standard USB-IF protocols for
|
||||||
|
HID, networking, storage, or audio classes.
|
||||||
|
Some developers are interested in KDB or KGDB hooks, to let
|
||||||
|
target hardware be remotely debugged.
|
||||||
|
Most such USB protocol code doesn't need to be hardware-specific,
|
||||||
|
any more than network protocols like X11, HTTP, or NFS are.
|
||||||
|
Such gadget-side interface drivers should eventually be combined,
|
||||||
|
to implement composite devices.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
|
||||||
|
<chapter id="api"><title>Kernel Mode Gadget API</title>
|
||||||
|
|
||||||
|
<para>Gadget drivers declare themselves through a
|
||||||
|
<emphasis>struct usb_gadget_driver</emphasis>, which is responsible for
|
||||||
|
most parts of enumeration for a <emphasis>struct usb_gadget</emphasis>.
|
||||||
|
The response to a set_configuration usually involves
|
||||||
|
enabling one or more of the <emphasis>struct usb_ep</emphasis> objects
|
||||||
|
exposed by the gadget, and submitting one or more
|
||||||
|
<emphasis>struct usb_request</emphasis> buffers to transfer data.
|
||||||
|
Understand those four data types, and their operations, and
|
||||||
|
you will understand how this API works.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<note><title>Incomplete Data Type Descriptions</title>
|
||||||
|
|
||||||
|
<para>This documentation was prepared using the standard Linux
|
||||||
|
kernel <filename>docproc</filename> tool, which turns text
|
||||||
|
and in-code comments into SGML DocBook and then into usable
|
||||||
|
formats such as HTML or PDF.
|
||||||
|
Other than the "Chapter 9" data types, most of the significant
|
||||||
|
data types and functions are described here.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>However, docproc does not understand all the C constructs
|
||||||
|
that are used, so some relevant information is likely omitted from
|
||||||
|
what you are reading.
|
||||||
|
One example of such information is endpoint autoconfiguration.
|
||||||
|
You'll have to read the header file, and use example source
|
||||||
|
code (such as that for "Gadget Zero"), to fully understand the API.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>The part of the API implementing some basic
|
||||||
|
driver capabilities is specific to the version of the
|
||||||
|
Linux kernel that's in use.
|
||||||
|
The 2.6 kernel includes a <emphasis>driver model</emphasis>
|
||||||
|
framework that has no analogue on earlier kernels;
|
||||||
|
so those parts of the gadget API are not fully portable.
|
||||||
|
(They are implemented on 2.4 kernels, but in a different way.)
|
||||||
|
The driver model state is another part of this API that is
|
||||||
|
ignored by the kerneldoc tools.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
|
||||||
|
<para>The core API does not expose
|
||||||
|
every possible hardware feature, only the most widely available ones.
|
||||||
|
There are significant hardware features, such as device-to-device DMA
|
||||||
|
(without temporary storage in a memory buffer)
|
||||||
|
that would be added using hardware-specific APIs.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>This API allows drivers to use conditional compilation to handle
|
||||||
|
endpoint capabilities of different hardware, but doesn't require that.
|
||||||
|
Hardware tends to have arbitrary restrictions, relating to
|
||||||
|
transfer types, addressing, packet sizes, buffering, and availability.
|
||||||
|
As a rule, such differences only matter for "endpoint zero" logic
|
||||||
|
that handles device configuration and management.
|
||||||
|
The API supports limited run-time
|
||||||
|
detection of capabilities, through naming conventions for endpoints.
|
||||||
|
Many drivers will be able to at least partially autoconfigure
|
||||||
|
themselves.
|
||||||
|
In particular, driver init sections will often have endpoint
|
||||||
|
autoconfiguration logic that scans the hardware's list of endpoints
|
||||||
|
to find ones matching the driver requirements
|
||||||
|
(relying on those conventions), to eliminate some of the most
|
||||||
|
common reasons for conditional compilation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Like the Linux-USB host side API, this API exposes
|
||||||
|
the "chunky" nature of USB messages: I/O requests are in terms
|
||||||
|
of one or more "packets", and packet boundaries are visible to drivers.
|
||||||
|
Compared to RS-232 serial protocols, USB resembles
|
||||||
|
synchronous protocols like HDLC
|
||||||
|
(N bytes per frame, multipoint addressing, host as the primary
|
||||||
|
station and devices as secondary stations)
|
||||||
|
more than asynchronous ones
|
||||||
|
(tty style: 8 data bits per frame, no parity, one stop bit).
|
||||||
|
So for example the controller drivers won't buffer
|
||||||
|
two single byte writes into a single two-byte USB IN packet,
|
||||||
|
although gadget drivers may do so when they implement
|
||||||
|
protocols where packet boundaries (and "short packets")
|
||||||
|
are not significant.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1 id="lifecycle"><title>Driver Life Cycle</title>
|
||||||
|
|
||||||
|
<para>Gadget drivers make endpoint I/O requests to hardware without
|
||||||
|
needing to know many details of the hardware, but driver
|
||||||
|
setup/configuration code needs to handle some differences.
|
||||||
|
Use the API like this:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<orderedlist numeration='arabic'>
|
||||||
|
|
||||||
|
<listitem><para>Register a driver for the particular device side
|
||||||
|
usb controller hardware,
|
||||||
|
such as the net2280 on PCI (USB 2.0),
|
||||||
|
sa11x0 or pxa25x as found in Linux PDAs,
|
||||||
|
and so on.
|
||||||
|
At this point the device is logically in the USB ch9 initial state
|
||||||
|
("attached"), drawing no power and not usable
|
||||||
|
(since it does not yet support enumeration).
|
||||||
|
Any host should not see the device, since it's not
|
||||||
|
activated the data line pullup used by the host to
|
||||||
|
detect a device, even if VBUS power is available.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>Register a gadget driver that implements some higher level
|
||||||
|
device function. That will then bind() to a usb_gadget, which
|
||||||
|
activates the data line pullup sometime after detecting VBUS.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>The hardware driver can now start enumerating.
|
||||||
|
The steps it handles are to accept USB power and set_address requests.
|
||||||
|
Other steps are handled by the gadget driver.
|
||||||
|
If the gadget driver module is unloaded before the host starts to
|
||||||
|
enumerate, steps before step 7 are skipped.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>The gadget driver's setup() call returns usb descriptors,
|
||||||
|
based both on what the bus interface hardware provides and on the
|
||||||
|
functionality being implemented.
|
||||||
|
That can involve alternate settings or configurations,
|
||||||
|
unless the hardware prevents such operation.
|
||||||
|
For OTG devices, each configuration descriptor includes
|
||||||
|
an OTG descriptor.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>The gadget driver handles the last step of enumeration,
|
||||||
|
when the USB host issues a set_configuration call.
|
||||||
|
It enables all endpoints used in that configuration,
|
||||||
|
with all interfaces in their default settings.
|
||||||
|
That involves using a list of the hardware's endpoints, enabling each
|
||||||
|
endpoint according to its descriptor.
|
||||||
|
It may also involve using <function>usb_gadget_vbus_draw</function>
|
||||||
|
to let more power be drawn from VBUS, as allowed by that configuration.
|
||||||
|
For OTG devices, setting a configuration may also involve reporting
|
||||||
|
HNP capabilities through a user interface.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>Do real work and perform data transfers, possibly involving
|
||||||
|
changes to interface settings or switching to new configurations, until the
|
||||||
|
device is disconnect()ed from the host.
|
||||||
|
Queue any number of transfer requests to each endpoint.
|
||||||
|
It may be suspended and resumed several times before being disconnected.
|
||||||
|
On disconnect, the drivers go back to step 3 (above).
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>When the gadget driver module is being unloaded,
|
||||||
|
the driver unbind() callback is issued. That lets the controller
|
||||||
|
driver be unloaded.
|
||||||
|
</para></listitem>
|
||||||
|
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para>Drivers will normally be arranged so that just loading the
|
||||||
|
gadget driver module (or statically linking it into a Linux kernel)
|
||||||
|
allows the peripheral device to be enumerated, but some drivers
|
||||||
|
will defer enumeration until some higher level component (like
|
||||||
|
a user mode daemon) enables it.
|
||||||
|
Note that at this lowest level there are no policies about how
|
||||||
|
ep0 configuration logic is implemented,
|
||||||
|
except that it should obey USB specifications.
|
||||||
|
Such issues are in the domain of gadget drivers,
|
||||||
|
including knowing about implementation constraints
|
||||||
|
imposed by some USB controllers
|
||||||
|
or understanding that composite devices might happen to
|
||||||
|
be built by integrating reusable components.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Note that the lifecycle above can be slightly different
|
||||||
|
for OTG devices.
|
||||||
|
Other than providing an additional OTG descriptor in each
|
||||||
|
configuration, only the HNP-related differences are particularly
|
||||||
|
visible to driver code.
|
||||||
|
They involve reporting requirements during the SET_CONFIGURATION
|
||||||
|
request, and the option to invoke HNP during some suspend callbacks.
|
||||||
|
Also, SRP changes the semantics of
|
||||||
|
<function>usb_gadget_wakeup</function>
|
||||||
|
slightly.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="ch9"><title>USB 2.0 Chapter 9 Types and Constants</title>
|
||||||
|
|
||||||
|
<para>Gadget drivers
|
||||||
|
rely on common USB structures and constants
|
||||||
|
defined in the
|
||||||
|
<filename><linux/usb/ch9.h></filename>
|
||||||
|
header file, which is standard in Linux 2.6 kernels.
|
||||||
|
These are the same types and constants used by host
|
||||||
|
side drivers (and usbcore).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Iinclude/linux/usb/ch9.h
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="core"><title>Core Objects and Methods</title>
|
||||||
|
|
||||||
|
<para>These are declared in
|
||||||
|
<filename><linux/usb/gadget.h></filename>,
|
||||||
|
and are used by gadget drivers to interact with
|
||||||
|
USB peripheral controller drivers.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!-- yeech, this is ugly in nsgmls PDF output.
|
||||||
|
|
||||||
|
the PDF bookmark and refentry output nesting is wrong,
|
||||||
|
and the member/argument documentation indents ugly.
|
||||||
|
|
||||||
|
plus something (docproc?) adds whitespace before the
|
||||||
|
descriptive paragraph text, so it can't line up right
|
||||||
|
unless the explanations are trivial.
|
||||||
|
-->
|
||||||
|
|
||||||
|
!Iinclude/linux/usb/gadget.h
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="utils"><title>Optional Utilities</title>
|
||||||
|
|
||||||
|
<para>The core API is sufficient for writing a USB Gadget Driver,
|
||||||
|
but some optional utilities are provided to simplify common tasks.
|
||||||
|
These utilities include endpoint autoconfiguration.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Edrivers/usb/gadget/usbstring.c
|
||||||
|
!Edrivers/usb/gadget/config.c
|
||||||
|
<!-- !Edrivers/usb/gadget/epautoconf.c -->
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="composite"><title>Composite Device Framework</title>
|
||||||
|
|
||||||
|
<para>The core API is sufficient for writing drivers for composite
|
||||||
|
USB devices (with more than one function in a given configuration),
|
||||||
|
and also multi-configuration devices (also more than one function,
|
||||||
|
but not necessarily sharing a given configuration).
|
||||||
|
There is however an optional framework which makes it easier to
|
||||||
|
reuse and combine functions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Devices using this framework provide a <emphasis>struct
|
||||||
|
usb_composite_driver</emphasis>, which in turn provides one or
|
||||||
|
more <emphasis>struct usb_configuration</emphasis> instances.
|
||||||
|
Each such configuration includes at least one
|
||||||
|
<emphasis>struct usb_function</emphasis>, which packages a user
|
||||||
|
visible role such as "network link" or "mass storage device".
|
||||||
|
Management functions may also exist, such as "Device Firmware
|
||||||
|
Upgrade".
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Iinclude/linux/usb/composite.h
|
||||||
|
!Edrivers/usb/gadget/composite.c
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="functions"><title>Composite Device Functions</title>
|
||||||
|
|
||||||
|
<para>At this writing, a few of the current gadget drivers have
|
||||||
|
been converted to this framework.
|
||||||
|
Near-term plans include converting all of them, except for "gadgetfs".
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Edrivers/usb/gadget/f_acm.c
|
||||||
|
!Edrivers/usb/gadget/f_ecm.c
|
||||||
|
!Edrivers/usb/gadget/f_subset.c
|
||||||
|
!Edrivers/usb/gadget/f_obex.c
|
||||||
|
!Edrivers/usb/gadget/f_serial.c
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="controllers"><title>Peripheral Controller Drivers</title>
|
||||||
|
|
||||||
|
<para>The first hardware supporting this API was the NetChip 2280
|
||||||
|
controller, which supports USB 2.0 high speed and is based on PCI.
|
||||||
|
This is the <filename>net2280</filename> driver module.
|
||||||
|
The driver supports Linux kernel versions 2.4 and 2.6;
|
||||||
|
contact NetChip Technologies for development boards and product
|
||||||
|
information.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Other hardware working in the "gadget" framework includes:
|
||||||
|
Intel's PXA 25x and IXP42x series processors
|
||||||
|
(<filename>pxa2xx_udc</filename>),
|
||||||
|
Toshiba TC86c001 "Goku-S" (<filename>goku_udc</filename>),
|
||||||
|
Renesas SH7705/7727 (<filename>sh_udc</filename>),
|
||||||
|
MediaQ 11xx (<filename>mq11xx_udc</filename>),
|
||||||
|
Hynix HMS30C7202 (<filename>h7202_udc</filename>),
|
||||||
|
National 9303/4 (<filename>n9604_udc</filename>),
|
||||||
|
Texas Instruments OMAP (<filename>omap_udc</filename>),
|
||||||
|
Sharp LH7A40x (<filename>lh7a40x_udc</filename>),
|
||||||
|
and more.
|
||||||
|
Most of those are full speed controllers.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>At this writing, there are people at work on drivers in
|
||||||
|
this framework for several other USB device controllers,
|
||||||
|
with plans to make many of them be widely available.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<!-- !Edrivers/usb/gadget/net2280.c -->
|
||||||
|
|
||||||
|
<para>A partial USB simulator,
|
||||||
|
the <filename>dummy_hcd</filename> driver, is available.
|
||||||
|
It can act like a net2280, a pxa25x, or an sa11x0 in terms
|
||||||
|
of available endpoints and device speeds; and it simulates
|
||||||
|
control, bulk, and to some extent interrupt transfers.
|
||||||
|
That lets you develop some parts of a gadget driver on a normal PC,
|
||||||
|
without any special hardware, and perhaps with the assistance
|
||||||
|
of tools such as GDB running with User Mode Linux.
|
||||||
|
At least one person has expressed interest in adapting that
|
||||||
|
approach, hooking it up to a simulator for a microcontroller.
|
||||||
|
Such simulators can help debug subsystems where the runtime hardware
|
||||||
|
is unfriendly to software development, or is not yet available.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Support for other controllers is expected to be developed
|
||||||
|
and contributed
|
||||||
|
over time, as this driver framework evolves.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="gadget"><title>Gadget Drivers</title>
|
||||||
|
|
||||||
|
<para>In addition to <emphasis>Gadget Zero</emphasis>
|
||||||
|
(used primarily for testing and development with drivers
|
||||||
|
for usb controller hardware), other gadget drivers exist.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>There's an <emphasis>ethernet</emphasis> gadget
|
||||||
|
driver, which implements one of the most useful
|
||||||
|
<emphasis>Communications Device Class</emphasis> (CDC) models.
|
||||||
|
One of the standards for cable modem interoperability even
|
||||||
|
specifies the use of this ethernet model as one of two
|
||||||
|
mandatory options.
|
||||||
|
Gadgets using this code look to a USB host as if they're
|
||||||
|
an Ethernet adapter.
|
||||||
|
It provides access to a network where the gadget's CPU is one host,
|
||||||
|
which could easily be bridging, routing, or firewalling
|
||||||
|
access to other networks.
|
||||||
|
Since some hardware can't fully implement the CDC Ethernet
|
||||||
|
requirements, this driver also implements a "good parts only"
|
||||||
|
subset of CDC Ethernet.
|
||||||
|
(That subset doesn't advertise itself as CDC Ethernet,
|
||||||
|
to avoid creating problems.)
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Support for Microsoft's <emphasis>RNDIS</emphasis>
|
||||||
|
protocol has been contributed by Pengutronix and Auerswald GmbH.
|
||||||
|
This is like CDC Ethernet, but it runs on more slightly USB hardware
|
||||||
|
(but less than the CDC subset).
|
||||||
|
However, its main claim to fame is being able to connect directly to
|
||||||
|
recent versions of Windows, using drivers that Microsoft bundles
|
||||||
|
and supports, making it much simpler to network with Windows.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>There is also support for user mode gadget drivers,
|
||||||
|
using <emphasis>gadgetfs</emphasis>.
|
||||||
|
This provides a <emphasis>User Mode API</emphasis> that presents
|
||||||
|
each endpoint as a single file descriptor. I/O is done using
|
||||||
|
normal <emphasis>read()</emphasis> and <emphasis>read()</emphasis> calls.
|
||||||
|
Familiar tools like GDB and pthreads can be used to
|
||||||
|
develop and debug user mode drivers, so that once a robust
|
||||||
|
controller driver is available many applications for it
|
||||||
|
won't require new kernel mode software.
|
||||||
|
Linux 2.6 <emphasis>Async I/O (AIO)</emphasis>
|
||||||
|
support is available, so that user mode software
|
||||||
|
can stream data with only slightly more overhead
|
||||||
|
than a kernel driver.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>There's a USB Mass Storage class driver, which provides
|
||||||
|
a different solution for interoperability with systems such
|
||||||
|
as MS-Windows and MacOS.
|
||||||
|
That <emphasis>File-backed Storage</emphasis> driver uses a
|
||||||
|
file or block device as backing store for a drive,
|
||||||
|
like the <filename>loop</filename> driver.
|
||||||
|
The USB host uses the BBB, CB, or CBI versions of the mass
|
||||||
|
storage class specification, using transparent SCSI commands
|
||||||
|
to access the data from the backing store.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>There's a "serial line" driver, useful for TTY style
|
||||||
|
operation over USB.
|
||||||
|
The latest version of that driver supports CDC ACM style
|
||||||
|
operation, like a USB modem, and so on most hardware it can
|
||||||
|
interoperate easily with MS-Windows.
|
||||||
|
One interesting use of that driver is in boot firmware (like a BIOS),
|
||||||
|
which can sometimes use that model with very small systems without
|
||||||
|
real serial lines.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Support for other kinds of gadget is expected to
|
||||||
|
be developed and contributed
|
||||||
|
over time, as this driver framework evolves.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="otg"><title>USB On-The-GO (OTG)</title>
|
||||||
|
|
||||||
|
<para>USB OTG support on Linux 2.6 was initially developed
|
||||||
|
by Texas Instruments for
|
||||||
|
<ulink url="http://www.omap.com">OMAP</ulink> 16xx and 17xx
|
||||||
|
series processors.
|
||||||
|
Other OTG systems should work in similar ways, but the
|
||||||
|
hardware level details could be very different.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>Systems need specialized hardware support to implement OTG,
|
||||||
|
notably including a special <emphasis>Mini-AB</emphasis> jack
|
||||||
|
and associated transciever to support <emphasis>Dual-Role</emphasis>
|
||||||
|
operation:
|
||||||
|
they can act either as a host, using the standard
|
||||||
|
Linux-USB host side driver stack,
|
||||||
|
or as a peripheral, using this "gadget" framework.
|
||||||
|
To do that, the system software relies on small additions
|
||||||
|
to those programming interfaces,
|
||||||
|
and on a new internal component (here called an "OTG Controller")
|
||||||
|
affecting which driver stack connects to the OTG port.
|
||||||
|
In each role, the system can re-use the existing pool of
|
||||||
|
hardware-neutral drivers, layered on top of the controller
|
||||||
|
driver interfaces (<emphasis>usb_bus</emphasis> or
|
||||||
|
<emphasis>usb_gadget</emphasis>).
|
||||||
|
Such drivers need at most minor changes, and most of the calls
|
||||||
|
added to support OTG can also benefit non-OTG products.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Gadget drivers test the <emphasis>is_otg</emphasis>
|
||||||
|
flag, and use it to determine whether or not to include
|
||||||
|
an OTG descriptor in each of their configurations.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Gadget drivers may need changes to support the
|
||||||
|
two new OTG protocols, exposed in new gadget attributes
|
||||||
|
such as <emphasis>b_hnp_enable</emphasis> flag.
|
||||||
|
HNP support should be reported through a user interface
|
||||||
|
(two LEDs could suffice), and is triggered in some cases
|
||||||
|
when the host suspends the peripheral.
|
||||||
|
SRP support can be user-initiated just like remote wakeup,
|
||||||
|
probably by pressing the same button.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>On the host side, USB device drivers need
|
||||||
|
to be taught to trigger HNP at appropriate moments, using
|
||||||
|
<function>usb_suspend_device()</function>.
|
||||||
|
That also conserves battery power, which is useful even
|
||||||
|
for non-OTG configurations.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>Also on the host side, a driver must support the
|
||||||
|
OTG "Targeted Peripheral List". That's just a whitelist,
|
||||||
|
used to reject peripherals not supported with a given
|
||||||
|
Linux OTG host.
|
||||||
|
<emphasis>This whitelist is product-specific;
|
||||||
|
each product must modify <filename>otg_whitelist.h</filename>
|
||||||
|
to match its interoperability specification.
|
||||||
|
</emphasis>
|
||||||
|
</para>
|
||||||
|
<para>Non-OTG Linux hosts, like PCs and workstations,
|
||||||
|
normally have some solution for adding drivers, so that
|
||||||
|
peripherals that aren't recognized can eventually be supported.
|
||||||
|
That approach is unreasonable for consumer products that may
|
||||||
|
never have their firmware upgraded, and where it's usually
|
||||||
|
unrealistic to expect traditional PC/workstation/server kinds
|
||||||
|
of support model to work.
|
||||||
|
For example, it's often impractical to change device firmware
|
||||||
|
once the product has been distributed, so driver bugs can't
|
||||||
|
normally be fixed if they're found after shipment.
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Additional changes are needed below those hardware-neutral
|
||||||
|
<emphasis>usb_bus</emphasis> and <emphasis>usb_gadget</emphasis>
|
||||||
|
driver interfaces; those aren't discussed here in any detail.
|
||||||
|
Those affect the hardware-specific code for each USB Host or Peripheral
|
||||||
|
controller, and how the HCD initializes (since OTG can be active only
|
||||||
|
on a single port).
|
||||||
|
They also involve what may be called an <emphasis>OTG Controller
|
||||||
|
Driver</emphasis>, managing the OTG transceiver and the OTG state
|
||||||
|
machine logic as well as much of the root hub behavior for the
|
||||||
|
OTG port.
|
||||||
|
The OTG controller driver needs to activate and deactivate USB
|
||||||
|
controllers depending on the relevant device role.
|
||||||
|
Some related changes were needed inside usbcore, so that it
|
||||||
|
can identify OTG-capable devices and respond appropriately
|
||||||
|
to HNP or SRP protocols.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
||||||
|
<!--
|
||||||
|
vim:syntax=sgml:sw=4
|
||||||
|
-->
|
|
@ -0,0 +1,475 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="Generic-IRQ-Guide">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Linux generic IRQ handling</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Thomas</firstname>
|
||||||
|
<surname>Gleixner</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>tglx@linutronix.de</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Ingo</firstname>
|
||||||
|
<surname>Molnar</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>mingo@elte.hu</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2005-2006</year>
|
||||||
|
<holder>Thomas Gleixner</holder>
|
||||||
|
</copyright>
|
||||||
|
<copyright>
|
||||||
|
<year>2005-2006</year>
|
||||||
|
<holder>Ingo Molnar</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation is free software; you can redistribute
|
||||||
|
it and/or modify it under the terms of the GNU General Public
|
||||||
|
License version 2 as published by the Free Software Foundation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
The generic interrupt handling layer is designed to provide a
|
||||||
|
complete abstraction of interrupt handling for device drivers.
|
||||||
|
It is able to handle all the different types of interrupt controller
|
||||||
|
hardware. Device drivers use generic API functions to request, enable,
|
||||||
|
disable and free interrupts. The drivers do not have to know anything
|
||||||
|
about interrupt hardware details, so they can be used on different
|
||||||
|
platforms without code changes.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This documentation is provided to developers who want to implement
|
||||||
|
an interrupt subsystem based for their architecture, with the help
|
||||||
|
of the generic IRQ handling layer.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="rationale">
|
||||||
|
<title>Rationale</title>
|
||||||
|
<para>
|
||||||
|
The original implementation of interrupt handling in Linux is using
|
||||||
|
the __do_IRQ() super-handler, which is able to deal with every
|
||||||
|
type of interrupt logic.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Originally, Russell King identified different types of handlers to
|
||||||
|
build a quite universal set for the ARM interrupt handler
|
||||||
|
implementation in Linux 2.5/2.6. He distinguished between:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Level type</para></listitem>
|
||||||
|
<listitem><para>Edge type</para></listitem>
|
||||||
|
<listitem><para>Simple type</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
In the SMP world of the __do_IRQ() super-handler another type
|
||||||
|
was identified:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Per CPU type</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This split implementation of highlevel IRQ handlers allows us to
|
||||||
|
optimize the flow of the interrupt handling for each specific
|
||||||
|
interrupt type. This reduces complexity in that particular codepath
|
||||||
|
and allows the optimized handling of a given type.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The original general IRQ implementation used hw_interrupt_type
|
||||||
|
structures and their ->ack(), ->end() [etc.] callbacks to
|
||||||
|
differentiate the flow control in the super-handler. This leads to
|
||||||
|
a mix of flow logic and lowlevel hardware logic, and it also leads
|
||||||
|
to unnecessary code duplication: for example in i386, there is a
|
||||||
|
ioapic_level_irq and a ioapic_edge_irq irq-type which share many
|
||||||
|
of the lowlevel details but have different flow handling.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
A more natural abstraction is the clean separation of the
|
||||||
|
'irq flow' and the 'chip details'.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Analysing a couple of architecture's IRQ subsystem implementations
|
||||||
|
reveals that most of them can use a generic set of 'irq flow'
|
||||||
|
methods and only need to add the chip level specific code.
|
||||||
|
The separation is also valuable for (sub)architectures
|
||||||
|
which need specific quirks in the irq flow itself but not in the
|
||||||
|
chip-details - and thus provides a more transparent IRQ subsystem
|
||||||
|
design.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Each interrupt descriptor is assigned its own highlevel flow
|
||||||
|
handler, which is normally one of the generic
|
||||||
|
implementations. (This highlevel flow handler implementation also
|
||||||
|
makes it simple to provide demultiplexing handlers which can be
|
||||||
|
found in embedded platforms on various architectures.)
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The separation makes the generic interrupt handling layer more
|
||||||
|
flexible and extensible. For example, an (sub)architecture can
|
||||||
|
use a generic irq-flow implementation for 'level type' interrupts
|
||||||
|
and add a (sub)architecture specific 'edge type' implementation.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
To make the transition to the new model easier and prevent the
|
||||||
|
breakage of existing implementations, the __do_IRQ() super-handler
|
||||||
|
is still available. This leads to a kind of duality for the time
|
||||||
|
being. Over time the new model should be used in more and more
|
||||||
|
architectures, as it enables smaller and cleaner IRQ subsystems.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="bugs">
|
||||||
|
<title>Known Bugs And Assumptions</title>
|
||||||
|
<para>
|
||||||
|
None (knock on wood).
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="Abstraction">
|
||||||
|
<title>Abstraction layers</title>
|
||||||
|
<para>
|
||||||
|
There are three main levels of abstraction in the interrupt code:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>Highlevel driver API</para></listitem>
|
||||||
|
<listitem><para>Highlevel IRQ flow handlers</para></listitem>
|
||||||
|
<listitem><para>Chiplevel hardware encapsulation</para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
<sect1 id="Interrupt_control_flow">
|
||||||
|
<title>Interrupt control flow</title>
|
||||||
|
<para>
|
||||||
|
Each interrupt is described by an interrupt descriptor structure
|
||||||
|
irq_desc. The interrupt is referenced by an 'unsigned int' numeric
|
||||||
|
value which selects the corresponding interrupt decription structure
|
||||||
|
in the descriptor structures array.
|
||||||
|
The descriptor structure contains status information and pointers
|
||||||
|
to the interrupt flow method and the interrupt chip structure
|
||||||
|
which are assigned to this interrupt.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Whenever an interrupt triggers, the lowlevel arch code calls into
|
||||||
|
the generic interrupt code by calling desc->handle_irq().
|
||||||
|
This highlevel IRQ handling function only uses desc->chip primitives
|
||||||
|
referenced by the assigned chip descriptor structure.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="Highlevel_Driver_API">
|
||||||
|
<title>Highlevel Driver API</title>
|
||||||
|
<para>
|
||||||
|
The highlevel Driver API consists of following functions:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>request_irq()</para></listitem>
|
||||||
|
<listitem><para>free_irq()</para></listitem>
|
||||||
|
<listitem><para>disable_irq()</para></listitem>
|
||||||
|
<listitem><para>enable_irq()</para></listitem>
|
||||||
|
<listitem><para>disable_irq_nosync() (SMP only)</para></listitem>
|
||||||
|
<listitem><para>synchronize_irq() (SMP only)</para></listitem>
|
||||||
|
<listitem><para>set_irq_type()</para></listitem>
|
||||||
|
<listitem><para>set_irq_wake()</para></listitem>
|
||||||
|
<listitem><para>set_irq_data()</para></listitem>
|
||||||
|
<listitem><para>set_irq_chip()</para></listitem>
|
||||||
|
<listitem><para>set_irq_chip_data()</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
See the autogenerated function documentation for details.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="Highlevel_IRQ_flow_handlers">
|
||||||
|
<title>Highlevel IRQ flow handlers</title>
|
||||||
|
<para>
|
||||||
|
The generic layer provides a set of pre-defined irq-flow methods:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>handle_level_irq</para></listitem>
|
||||||
|
<listitem><para>handle_edge_irq</para></listitem>
|
||||||
|
<listitem><para>handle_simple_irq</para></listitem>
|
||||||
|
<listitem><para>handle_percpu_irq</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
The interrupt flow handlers (either predefined or architecture
|
||||||
|
specific) are assigned to specific interrupts by the architecture
|
||||||
|
either during bootup or during device initialization.
|
||||||
|
</para>
|
||||||
|
<sect2 id="Default_flow_implementations">
|
||||||
|
<title>Default flow implementations</title>
|
||||||
|
<sect3 id="Helper_functions">
|
||||||
|
<title>Helper functions</title>
|
||||||
|
<para>
|
||||||
|
The helper functions call the chip primitives and
|
||||||
|
are used by the default flow implementations.
|
||||||
|
The following helper functions are implemented (simplified excerpt):
|
||||||
|
<programlisting>
|
||||||
|
default_enable(irq)
|
||||||
|
{
|
||||||
|
desc->chip->unmask(irq);
|
||||||
|
}
|
||||||
|
|
||||||
|
default_disable(irq)
|
||||||
|
{
|
||||||
|
if (!delay_disable(irq))
|
||||||
|
desc->chip->mask(irq);
|
||||||
|
}
|
||||||
|
|
||||||
|
default_ack(irq)
|
||||||
|
{
|
||||||
|
chip->ack(irq);
|
||||||
|
}
|
||||||
|
|
||||||
|
default_mask_ack(irq)
|
||||||
|
{
|
||||||
|
if (chip->mask_ack) {
|
||||||
|
chip->mask_ack(irq);
|
||||||
|
} else {
|
||||||
|
chip->mask(irq);
|
||||||
|
chip->ack(irq);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
noop(irq)
|
||||||
|
{
|
||||||
|
}
|
||||||
|
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
<sect2 id="Default_flow_handler_implementations">
|
||||||
|
<title>Default flow handler implementations</title>
|
||||||
|
<sect3 id="Default_Level_IRQ_flow_handler">
|
||||||
|
<title>Default Level IRQ flow handler</title>
|
||||||
|
<para>
|
||||||
|
handle_level_irq provides a generic implementation
|
||||||
|
for level-triggered interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The following control flow is implemented (simplified excerpt):
|
||||||
|
<programlisting>
|
||||||
|
desc->chip->start();
|
||||||
|
handle_IRQ_event(desc->action);
|
||||||
|
desc->chip->end();
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
<sect3 id="Default_Edge_IRQ_flow_handler">
|
||||||
|
<title>Default Edge IRQ flow handler</title>
|
||||||
|
<para>
|
||||||
|
handle_edge_irq provides a generic implementation
|
||||||
|
for edge-triggered interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The following control flow is implemented (simplified excerpt):
|
||||||
|
<programlisting>
|
||||||
|
if (desc->status & running) {
|
||||||
|
desc->chip->hold();
|
||||||
|
desc->status |= pending | masked;
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
desc->chip->start();
|
||||||
|
desc->status |= running;
|
||||||
|
do {
|
||||||
|
if (desc->status & masked)
|
||||||
|
desc->chip->enable();
|
||||||
|
desc->status &= ~pending;
|
||||||
|
handle_IRQ_event(desc->action);
|
||||||
|
} while (status & pending);
|
||||||
|
desc->status &= ~running;
|
||||||
|
desc->chip->end();
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
<sect3 id="Default_simple_IRQ_flow_handler">
|
||||||
|
<title>Default simple IRQ flow handler</title>
|
||||||
|
<para>
|
||||||
|
handle_simple_irq provides a generic implementation
|
||||||
|
for simple interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note: The simple flow handler does not call any
|
||||||
|
handler/chip primitives.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The following control flow is implemented (simplified excerpt):
|
||||||
|
<programlisting>
|
||||||
|
handle_IRQ_event(desc->action);
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
<sect3 id="Default_per_CPU_flow_handler">
|
||||||
|
<title>Default per CPU flow handler</title>
|
||||||
|
<para>
|
||||||
|
handle_percpu_irq provides a generic implementation
|
||||||
|
for per CPU interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Per CPU interrupts are only available on SMP and
|
||||||
|
the handler provides a simplified version without
|
||||||
|
locking.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The following control flow is implemented (simplified excerpt):
|
||||||
|
<programlisting>
|
||||||
|
desc->chip->start();
|
||||||
|
handle_IRQ_event(desc->action);
|
||||||
|
desc->chip->end();
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</sect3>
|
||||||
|
</sect2>
|
||||||
|
<sect2 id="Quirks_and_optimizations">
|
||||||
|
<title>Quirks and optimizations</title>
|
||||||
|
<para>
|
||||||
|
The generic functions are intended for 'clean' architectures and chips,
|
||||||
|
which have no platform-specific IRQ handling quirks. If an architecture
|
||||||
|
needs to implement quirks on the 'flow' level then it can do so by
|
||||||
|
overriding the highlevel irq-flow handler.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
<sect2 id="Delayed_interrupt_disable">
|
||||||
|
<title>Delayed interrupt disable</title>
|
||||||
|
<para>
|
||||||
|
This per interrupt selectable feature, which was introduced by Russell
|
||||||
|
King in the ARM interrupt implementation, does not mask an interrupt
|
||||||
|
at the hardware level when disable_irq() is called. The interrupt is
|
||||||
|
kept enabled and is masked in the flow handler when an interrupt event
|
||||||
|
happens. This prevents losing edge interrupts on hardware which does
|
||||||
|
not store an edge interrupt event while the interrupt is disabled at
|
||||||
|
the hardware level. When an interrupt arrives while the IRQ_DISABLED
|
||||||
|
flag is set, then the interrupt is masked at the hardware level and
|
||||||
|
the IRQ_PENDING bit is set. When the interrupt is re-enabled by
|
||||||
|
enable_irq() the pending bit is checked and if it is set, the
|
||||||
|
interrupt is resent either via hardware or by a software resend
|
||||||
|
mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when
|
||||||
|
you want to use the delayed interrupt disable feature and your
|
||||||
|
hardware is not capable of retriggering an interrupt.)
|
||||||
|
The delayed interrupt disable can be runtime enabled, per interrupt,
|
||||||
|
by setting the IRQ_DELAYED_DISABLE flag in the irq_desc status field.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="Chiplevel_hardware_encapsulation">
|
||||||
|
<title>Chiplevel hardware encapsulation</title>
|
||||||
|
<para>
|
||||||
|
The chip level hardware descriptor structure irq_chip
|
||||||
|
contains all the direct chip relevant functions, which
|
||||||
|
can be utilized by the irq flow implementations.
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>ack()</para></listitem>
|
||||||
|
<listitem><para>mask_ack() - Optional, recommended for performance</para></listitem>
|
||||||
|
<listitem><para>mask()</para></listitem>
|
||||||
|
<listitem><para>unmask()</para></listitem>
|
||||||
|
<listitem><para>retrigger() - Optional</para></listitem>
|
||||||
|
<listitem><para>set_type() - Optional</para></listitem>
|
||||||
|
<listitem><para>set_wake() - Optional</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
These primitives are strictly intended to mean what they say: ack means
|
||||||
|
ACK, masking means masking of an IRQ line, etc. It is up to the flow
|
||||||
|
handler(s) to use these basic units of lowlevel functionality.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="doirq">
|
||||||
|
<title>__do_IRQ entry point</title>
|
||||||
|
<para>
|
||||||
|
The original implementation __do_IRQ() is an alternative entry
|
||||||
|
point for all types of interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This handler turned out to be not suitable for all
|
||||||
|
interrupt hardware and was therefore reimplemented with split
|
||||||
|
functionality for egde/level/simple/percpu interrupts. This is not
|
||||||
|
only a functional optimization. It also shortens code paths for
|
||||||
|
interrupts.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
To make use of the split implementation, replace the call to
|
||||||
|
__do_IRQ by a call to desc->chip->handle_irq() and associate
|
||||||
|
the appropriate handler function to desc->chip->handle_irq().
|
||||||
|
In most cases the generic handler implementations should
|
||||||
|
be sufficient.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="locking">
|
||||||
|
<title>Locking on SMP</title>
|
||||||
|
<para>
|
||||||
|
The locking of chip registers is up to the architecture that
|
||||||
|
defines the chip primitives. There is a chip->lock field that can be used
|
||||||
|
for serialization, but the generic layer does not touch it. The per-irq
|
||||||
|
structure is protected via desc->lock, by the generic layer.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="structs">
|
||||||
|
<title>Structures</title>
|
||||||
|
<para>
|
||||||
|
This chapter contains the autogenerated documentation of the structures which are
|
||||||
|
used in the generic IRQ layer.
|
||||||
|
</para>
|
||||||
|
!Iinclude/linux/irq.h
|
||||||
|
!Iinclude/linux/interrupt.h
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="pubfunctions">
|
||||||
|
<title>Public Functions Provided</title>
|
||||||
|
<para>
|
||||||
|
This chapter contains the autogenerated documentation of the kernel API functions
|
||||||
|
which are exported.
|
||||||
|
</para>
|
||||||
|
!Ekernel/irq/manage.c
|
||||||
|
!Ekernel/irq/chip.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="intfunctions">
|
||||||
|
<title>Internal Functions Provided</title>
|
||||||
|
<para>
|
||||||
|
This chapter contains the autogenerated documentation of the internal functions.
|
||||||
|
</para>
|
||||||
|
!Ikernel/irq/handle.c
|
||||||
|
!Ikernel/irq/chip.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="credits">
|
||||||
|
<title>Credits</title>
|
||||||
|
<para>
|
||||||
|
The following people have contributed to this document:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem>
|
||||||
|
<listitem><para>Ingo Molnar<email>mingo@elte.hu</email></para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
</book>
|
|
@ -0,0 +1,335 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="LinuxKernelAPI">
|
||||||
|
<bookinfo>
|
||||||
|
<title>The Linux Kernel API</title>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="adt">
|
||||||
|
<title>Data Types</title>
|
||||||
|
<sect1><title>Doubly Linked Lists</title>
|
||||||
|
!Iinclude/linux/list.h
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="libc">
|
||||||
|
<title>Basic C Library Functions</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When writing drivers, you cannot in general use routines which are
|
||||||
|
from the C Library. Some of the functions have been found generally
|
||||||
|
useful and they are listed below. The behaviour of these functions
|
||||||
|
may vary slightly from those defined by ANSI, and these deviations
|
||||||
|
are noted in the text.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1><title>String Conversions</title>
|
||||||
|
!Ilib/vsprintf.c
|
||||||
|
!Elib/vsprintf.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>String Manipulation</title>
|
||||||
|
<!-- All functions are exported at now
|
||||||
|
X!Ilib/string.c
|
||||||
|
-->
|
||||||
|
!Elib/string.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Bit Operations</title>
|
||||||
|
!Iarch/x86/include/asm/bitops.h
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="kernel-lib">
|
||||||
|
<title>Basic Kernel Library Functions</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The Linux kernel provides more basic utility functions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1><title>Bitmap Operations</title>
|
||||||
|
!Elib/bitmap.c
|
||||||
|
!Ilib/bitmap.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Command-line Parsing</title>
|
||||||
|
!Elib/cmdline.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="crc"><title>CRC Functions</title>
|
||||||
|
!Elib/crc7.c
|
||||||
|
!Elib/crc16.c
|
||||||
|
!Elib/crc-itu-t.c
|
||||||
|
!Elib/crc32.c
|
||||||
|
!Elib/crc-ccitt.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="mm">
|
||||||
|
<title>Memory Management in Linux</title>
|
||||||
|
<sect1><title>The Slab Cache</title>
|
||||||
|
!Iinclude/linux/slab.h
|
||||||
|
!Emm/slab.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>User Space Memory Access</title>
|
||||||
|
!Iarch/x86/include/asm/uaccess_32.h
|
||||||
|
!Earch/x86/lib/usercopy_32.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>More Memory Management Functions</title>
|
||||||
|
!Emm/readahead.c
|
||||||
|
!Emm/filemap.c
|
||||||
|
!Emm/memory.c
|
||||||
|
!Emm/vmalloc.c
|
||||||
|
!Imm/page_alloc.c
|
||||||
|
!Emm/mempool.c
|
||||||
|
!Emm/dmapool.c
|
||||||
|
!Emm/page-writeback.c
|
||||||
|
!Emm/truncate.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
|
||||||
|
<chapter id="ipc">
|
||||||
|
<title>Kernel IPC facilities</title>
|
||||||
|
|
||||||
|
<sect1><title>IPC utilities</title>
|
||||||
|
!Iipc/util.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="kfifo">
|
||||||
|
<title>FIFO Buffer</title>
|
||||||
|
<sect1><title>kfifo interface</title>
|
||||||
|
!Iinclude/linux/kfifo.h
|
||||||
|
!Ekernel/kfifo.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="relayfs">
|
||||||
|
<title>relay interface support</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Relay interface support
|
||||||
|
is designed to provide an efficient mechanism for tools and
|
||||||
|
facilities to relay large amounts of data from kernel space to
|
||||||
|
user space.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect1><title>relay interface</title>
|
||||||
|
!Ekernel/relay.c
|
||||||
|
!Ikernel/relay.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="modload">
|
||||||
|
<title>Module Support</title>
|
||||||
|
<sect1><title>Module Loading</title>
|
||||||
|
!Ekernel/kmod.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>Inter Module support</title>
|
||||||
|
<para>
|
||||||
|
Refer to the file kernel/module.c for more information.
|
||||||
|
</para>
|
||||||
|
<!-- FIXME: Removed for now since no structured comments in source
|
||||||
|
X!Ekernel/module.c
|
||||||
|
-->
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="hardware">
|
||||||
|
<title>Hardware Interfaces</title>
|
||||||
|
<sect1><title>Interrupt Handling</title>
|
||||||
|
!Ekernel/irq/manage.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>DMA Channels</title>
|
||||||
|
!Ekernel/dma.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>Resources Management</title>
|
||||||
|
!Ikernel/resource.c
|
||||||
|
!Ekernel/resource.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>MTRR Handling</title>
|
||||||
|
!Earch/x86/kernel/cpu/mtrr/main.c
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1><title>PCI Support Library</title>
|
||||||
|
!Edrivers/pci/pci.c
|
||||||
|
!Edrivers/pci/pci-driver.c
|
||||||
|
!Edrivers/pci/remove.c
|
||||||
|
!Edrivers/pci/search.c
|
||||||
|
!Edrivers/pci/msi.c
|
||||||
|
!Edrivers/pci/bus.c
|
||||||
|
!Edrivers/pci/access.c
|
||||||
|
!Edrivers/pci/irq.c
|
||||||
|
!Edrivers/pci/htirq.c
|
||||||
|
<!-- FIXME: Removed for now since no structured comments in source
|
||||||
|
X!Edrivers/pci/hotplug.c
|
||||||
|
-->
|
||||||
|
!Edrivers/pci/probe.c
|
||||||
|
!Edrivers/pci/slot.c
|
||||||
|
!Edrivers/pci/rom.c
|
||||||
|
!Edrivers/pci/iov.c
|
||||||
|
!Idrivers/pci/pci-sysfs.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>PCI Hotplug Support Library</title>
|
||||||
|
!Edrivers/pci/hotplug/pci_hotplug_core.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>MCA Architecture</title>
|
||||||
|
<sect2><title>MCA Device Functions</title>
|
||||||
|
<para>
|
||||||
|
Refer to the file arch/x86/kernel/mca_32.c for more information.
|
||||||
|
</para>
|
||||||
|
<!-- FIXME: Removed for now since no structured comments in source
|
||||||
|
X!Earch/x86/kernel/mca_32.c
|
||||||
|
-->
|
||||||
|
</sect2>
|
||||||
|
<sect2><title>MCA Bus DMA</title>
|
||||||
|
!Iarch/x86/include/asm/mca_dma.h
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="firmware">
|
||||||
|
<title>Firmware Interfaces</title>
|
||||||
|
<sect1><title>DMI Interfaces</title>
|
||||||
|
!Edrivers/firmware/dmi_scan.c
|
||||||
|
</sect1>
|
||||||
|
<sect1><title>EDD Interfaces</title>
|
||||||
|
!Idrivers/firmware/edd.c
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="security">
|
||||||
|
<title>Security Framework</title>
|
||||||
|
!Isecurity/security.c
|
||||||
|
!Esecurity/inode.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="audit">
|
||||||
|
<title>Audit Interfaces</title>
|
||||||
|
!Ekernel/audit.c
|
||||||
|
!Ikernel/auditsc.c
|
||||||
|
!Ikernel/auditfilter.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="accounting">
|
||||||
|
<title>Accounting Framework</title>
|
||||||
|
!Ikernel/acct.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="blkdev">
|
||||||
|
<title>Block Devices</title>
|
||||||
|
!Eblock/blk-core.c
|
||||||
|
!Iblock/blk-core.c
|
||||||
|
!Eblock/blk-map.c
|
||||||
|
!Iblock/blk-sysfs.c
|
||||||
|
!Eblock/blk-settings.c
|
||||||
|
!Eblock/blk-exec.c
|
||||||
|
!Eblock/blk-barrier.c
|
||||||
|
!Eblock/blk-tag.c
|
||||||
|
!Iblock/blk-tag.c
|
||||||
|
!Eblock/blk-integrity.c
|
||||||
|
!Ikernel/trace/blktrace.c
|
||||||
|
!Iblock/genhd.c
|
||||||
|
!Eblock/genhd.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="chrdev">
|
||||||
|
<title>Char devices</title>
|
||||||
|
!Efs/char_dev.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="miscdev">
|
||||||
|
<title>Miscellaneous Devices</title>
|
||||||
|
!Edrivers/char/misc.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="clk">
|
||||||
|
<title>Clock Framework</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The clock framework defines programming interfaces to support
|
||||||
|
software management of the system clock tree.
|
||||||
|
This framework is widely used with System-On-Chip (SOC) platforms
|
||||||
|
to support power management and various devices which may need
|
||||||
|
custom clock rates.
|
||||||
|
Note that these "clocks" don't relate to timekeeping or real
|
||||||
|
time clocks (RTCs), each of which have separate frameworks.
|
||||||
|
These <structname>struct clk</structname> instances may be used
|
||||||
|
to manage for example a 96 MHz signal that is used to shift bits
|
||||||
|
into and out of peripherals or busses, or otherwise trigger
|
||||||
|
synchronous state machine transitions in system hardware.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Power management is supported by explicit software clock gating:
|
||||||
|
unused clocks are disabled, so the system doesn't waste power
|
||||||
|
changing the state of transistors that aren't in active use.
|
||||||
|
On some systems this may be backed by hardware clock gating,
|
||||||
|
where clocks are gated without being disabled in software.
|
||||||
|
Sections of chips that are powered but not clocked may be able
|
||||||
|
to retain their last state.
|
||||||
|
This low power state is often called a <emphasis>retention
|
||||||
|
mode</emphasis>.
|
||||||
|
This mode still incurs leakage currents, especially with finer
|
||||||
|
circuit geometries, but for CMOS circuits power is mostly used
|
||||||
|
by clocked state changes.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Power-aware drivers only enable their clocks when the device
|
||||||
|
they manage is in active use. Also, system sleep states often
|
||||||
|
differ according to which clock domains are active: while a
|
||||||
|
"standby" state may allow wakeup from several active domains, a
|
||||||
|
"mem" (suspend-to-RAM) state may require a more wholesale shutdown
|
||||||
|
of clocks derived from higher speed PLLs and oscillators, limiting
|
||||||
|
the number of possible wakeup event sources. A driver's suspend
|
||||||
|
method may need to be aware of system-specific clock constraints
|
||||||
|
on the target sleep state.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Some platforms support programmable clock generators. These
|
||||||
|
can be used by external chips of various kinds, such as other
|
||||||
|
CPUs, multimedia codecs, and devices with strict requirements
|
||||||
|
for interface clocking.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
!Iinclude/linux/clk.h
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,459 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="kgdbOnLinux">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Using kgdb and the kgdb Internals</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Jason</firstname>
|
||||||
|
<surname>Wessel</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>jason.wessel@windriver.com</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Tom</firstname>
|
||||||
|
<surname>Rini</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>trini@kernel.crashing.org</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Amit S.</firstname>
|
||||||
|
<surname>Kale</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>amitkale@linsyssoft.com</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2008</year>
|
||||||
|
<holder>Wind River Systems, Inc.</holder>
|
||||||
|
</copyright>
|
||||||
|
<copyright>
|
||||||
|
<year>2004-2005</year>
|
||||||
|
<holder>MontaVista Software, Inc.</holder>
|
||||||
|
</copyright>
|
||||||
|
<copyright>
|
||||||
|
<year>2004</year>
|
||||||
|
<holder>Amit S. Kale</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This file is licensed under the terms of the GNU General Public License
|
||||||
|
version 2. This program is licensed "as is" without any warranty of any
|
||||||
|
kind, whether express or implied.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
<chapter id="Introduction">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
kgdb is a source level debugger for linux kernel. It is used along
|
||||||
|
with gdb to debug a linux kernel. The expectation is that gdb can
|
||||||
|
be used to "break in" to the kernel to inspect memory, variables
|
||||||
|
and look through call stack information similar to what an
|
||||||
|
application developer would use gdb for. It is possible to place
|
||||||
|
breakpoints in kernel code and perform some limited execution
|
||||||
|
stepping.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Two machines are required for using kgdb. One of these machines is a
|
||||||
|
development machine and the other is a test machine. The kernel
|
||||||
|
to be debugged runs on the test machine. The development machine
|
||||||
|
runs an instance of gdb against the vmlinux file which contains
|
||||||
|
the symbols (not boot image such as bzImage, zImage, uImage...).
|
||||||
|
In gdb the developer specifies the connection parameters and
|
||||||
|
connects to kgdb. The type of connection a developer makes with
|
||||||
|
gdb depends on the availability of kgdb I/O modules compiled as
|
||||||
|
builtin's or kernel modules in the test machine's kernel.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="CompilingAKernel">
|
||||||
|
<title>Compiling a kernel</title>
|
||||||
|
<para>
|
||||||
|
To enable <symbol>CONFIG_KGDB</symbol> you should first turn on
|
||||||
|
"Prompt for development and/or incomplete code/drivers"
|
||||||
|
(CONFIG_EXPERIMENTAL) in "General setup", then under the
|
||||||
|
"Kernel debugging" select "KGDB: kernel debugging with remote gdb".
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
It is advised, but not required that you turn on the
|
||||||
|
CONFIG_FRAME_POINTER kernel option. This option inserts code to
|
||||||
|
into the compiled executable which saves the frame information in
|
||||||
|
registers or on the stack at different points which will allow a
|
||||||
|
debugger such as gdb to more accurately construct stack back traces
|
||||||
|
while debugging the kernel.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If the architecture that you are using supports the kernel option
|
||||||
|
CONFIG_DEBUG_RODATA, you should consider turning it off. This
|
||||||
|
option will prevent the use of software breakpoints because it
|
||||||
|
marks certain regions of the kernel's memory space as read-only.
|
||||||
|
If kgdb supports it for the architecture you are using, you can
|
||||||
|
use hardware breakpoints if you desire to run with the
|
||||||
|
CONFIG_DEBUG_RODATA option turned on, else you need to turn off
|
||||||
|
this option.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Next you should choose one of more I/O drivers to interconnect debugging
|
||||||
|
host and debugged target. Early boot debugging requires a KGDB
|
||||||
|
I/O driver that supports early debugging and the driver must be
|
||||||
|
built into the kernel directly. Kgdb I/O driver configuration
|
||||||
|
takes place via kernel or module parameters, see following
|
||||||
|
chapter.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The kgdb test compile options are described in the kgdb test suite chapter.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
<chapter id="EnableKGDB">
|
||||||
|
<title>Enable kgdb for debugging</title>
|
||||||
|
<para>
|
||||||
|
In order to use kgdb you must activate it by passing configuration
|
||||||
|
information to one of the kgdb I/O drivers. If you do not pass any
|
||||||
|
configuration information kgdb will not do anything at all. Kgdb
|
||||||
|
will only actively hook up to the kernel trap hooks if a kgdb I/O
|
||||||
|
driver is loaded and configured. If you unconfigure a kgdb I/O
|
||||||
|
driver, kgdb will unregister all the kernel hook points.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
All drivers can be reconfigured at run time, if
|
||||||
|
<symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol>
|
||||||
|
are enabled, by echo'ing a new config string to
|
||||||
|
<constant>/sys/module/<driver>/parameter/<option></constant>.
|
||||||
|
The driver can be unconfigured by passing an empty string. You cannot
|
||||||
|
change the configuration while the debugger is attached. Make sure
|
||||||
|
to detach the debugger with the <constant>detach</constant> command
|
||||||
|
prior to trying unconfigure a kgdb I/O driver.
|
||||||
|
</para>
|
||||||
|
<sect1 id="kgdbwait">
|
||||||
|
<title>Kernel parameter: kgdbwait</title>
|
||||||
|
<para>
|
||||||
|
The Kernel command line option <constant>kgdbwait</constant> makes
|
||||||
|
kgdb wait for a debugger connection during booting of a kernel. You
|
||||||
|
can only use this option you compiled a kgdb I/O driver into the
|
||||||
|
kernel and you specified the I/O driver configuration as a kernel
|
||||||
|
command line option. The kgdbwait parameter should always follow the
|
||||||
|
configuration parameter for the kgdb I/O driver in the kernel
|
||||||
|
command line else the I/O driver will not be configured prior to
|
||||||
|
asking the kernel to use it to wait.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The kernel will stop and wait as early as the I/O driver and
|
||||||
|
architecture will allow when you use this option. If you build the
|
||||||
|
kgdb I/O driver as a kernel module kgdbwait will not do anything.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="kgdboc">
|
||||||
|
<title>Kernel parameter: kgdboc</title>
|
||||||
|
<para>
|
||||||
|
The kgdboc driver was originally an abbreviation meant to stand for
|
||||||
|
"kgdb over console". Kgdboc is designed to work with a single
|
||||||
|
serial port. It was meant to cover the circumstance
|
||||||
|
where you wanted to use a serial console as your primary console as
|
||||||
|
well as using it to perform kernel debugging. Of course you can
|
||||||
|
also use kgdboc without assigning a console to the same port.
|
||||||
|
</para>
|
||||||
|
<sect2 id="UsingKgdboc">
|
||||||
|
<title>Using kgdboc</title>
|
||||||
|
<para>
|
||||||
|
You can configure kgdboc via sysfs or a module or kernel boot line
|
||||||
|
parameter depending on if you build with CONFIG_KGDBOC as a module
|
||||||
|
or built-in.
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>From the module load or build-in</para>
|
||||||
|
<para><constant>kgdboc=<tty-device>,[baud]</constant></para>
|
||||||
|
<para>
|
||||||
|
The example here would be if your console port was typically ttyS0, you would use something like <constant>kgdboc=ttyS0,115200</constant> or on the ARM Versatile AB you would likely use <constant>kgdboc=ttyAMA0,115200</constant>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para>From sysfs</para>
|
||||||
|
<para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
NOTE: Kgdboc does not support interrupting the target via the
|
||||||
|
gdb remote protocol. You must manually send a sysrq-g unless you
|
||||||
|
have a proxy that splits console output to a terminal problem and
|
||||||
|
has a separate port for the debugger to connect to that sends the
|
||||||
|
sysrq-g for you.
|
||||||
|
</para>
|
||||||
|
<para>When using kgdboc with no debugger proxy, you can end up
|
||||||
|
connecting the debugger for one of two entry points. If an
|
||||||
|
exception occurs after you have loaded kgdboc a message should print
|
||||||
|
on the console stating it is waiting for the debugger. In case you
|
||||||
|
disconnect your terminal program and then connect the debugger in
|
||||||
|
its place. If you want to interrupt the target system and forcibly
|
||||||
|
enter a debug session you have to issue a Sysrq sequence and then
|
||||||
|
type the letter <constant>g</constant>. Then you disconnect the
|
||||||
|
terminal session and connect gdb. Your options if you don't like
|
||||||
|
this are to hack gdb to send the sysrq-g for you as well as on the
|
||||||
|
initial connect, or to use a debugger proxy that allows an
|
||||||
|
unmodified gdb to do the debugging.
|
||||||
|
</para>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="kgdbcon">
|
||||||
|
<title>Kernel parameter: kgdbcon</title>
|
||||||
|
<para>
|
||||||
|
Kgdb supports using the gdb serial protocol to send console messages
|
||||||
|
to the debugger when the debugger is connected and running. There
|
||||||
|
are two ways to activate this feature.
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>Activate with the kernel command line option:</para>
|
||||||
|
<para><constant>kgdbcon</constant></para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para>Use sysfs before configuring an io driver</para>
|
||||||
|
<para>
|
||||||
|
<constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
NOTE: If you do this after you configure the kgdb I/O driver, the
|
||||||
|
setting will not take effect until the next point the I/O is
|
||||||
|
reconfigured.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
IMPORTANT NOTE: Using this option with kgdb over the console
|
||||||
|
(kgdboc) is not supported.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="ConnectingGDB">
|
||||||
|
<title>Connecting gdb</title>
|
||||||
|
<para>
|
||||||
|
If you are using kgdboc, you need to have used kgdbwait as a boot
|
||||||
|
argument, issued a sysrq-g, or the system you are going to debug
|
||||||
|
has already taken an exception and is waiting for the debugger to
|
||||||
|
attach before you can connect gdb.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If you are not using different kgdb I/O driver other than kgdboc,
|
||||||
|
you should be able to connect and the target will automatically
|
||||||
|
respond.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Example (using a serial port):
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
% gdb ./vmlinux
|
||||||
|
(gdb) set remotebaud 115200
|
||||||
|
(gdb) target remote /dev/ttyS0
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Example (kgdb to a terminal server on tcp port 2012):
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
% gdb ./vmlinux
|
||||||
|
(gdb) target remote 192.168.2.2:2012
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Once connected, you can debug a kernel the way you would debug an
|
||||||
|
application program.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If you are having problems connecting or something is going
|
||||||
|
seriously wrong while debugging, it will most often be the case
|
||||||
|
that you want to enable gdb to be verbose about its target
|
||||||
|
communications. You do this prior to issuing the <constant>target
|
||||||
|
remote</constant> command by typing in: <constant>set debug remote 1</constant>
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="KGDBTestSuite">
|
||||||
|
<title>kgdb Test Suite</title>
|
||||||
|
<para>
|
||||||
|
When kgdb is enabled in the kernel config you can also elect to
|
||||||
|
enable the config parameter KGDB_TESTS. Turning this on will
|
||||||
|
enable a special kgdb I/O module which is designed to test the
|
||||||
|
kgdb internal functions.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The kgdb tests are mainly intended for developers to test the kgdb
|
||||||
|
internals as well as a tool for developing a new kgdb architecture
|
||||||
|
specific implementation. These tests are not really for end users
|
||||||
|
of the Linux kernel. The primary source of documentation would be
|
||||||
|
to look in the drivers/misc/kgdbts.c file.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The kgdb test suite can also be configured at compile time to run
|
||||||
|
the core set of tests by setting the kernel config parameter
|
||||||
|
KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
|
||||||
|
regression testing and does not require modifying the kernel boot
|
||||||
|
config arguments. If this is turned on, the kgdb test suite can
|
||||||
|
be disabled by specifying "kgdbts=" as a kernel boot argument.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="CommonBackEndReq">
|
||||||
|
<title>KGDB Internals</title>
|
||||||
|
<sect1 id="kgdbArchitecture">
|
||||||
|
<title>Architecture Specifics</title>
|
||||||
|
<para>
|
||||||
|
Kgdb is organized into three basic components:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>kgdb core</para>
|
||||||
|
<para>
|
||||||
|
The kgdb core is found in kernel/kgdb.c. It contains:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>All the logic to implement the gdb serial protocol</para></listitem>
|
||||||
|
<listitem><para>A generic OS exception handler which includes sync'ing the processors into a stopped state on an multi cpu system.</para></listitem>
|
||||||
|
<listitem><para>The API to talk to the kgdb I/O drivers</para></listitem>
|
||||||
|
<listitem><para>The API to make calls to the arch specific kgdb implementation</para></listitem>
|
||||||
|
<listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
|
||||||
|
<listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para>kgdb arch specific implementation</para>
|
||||||
|
<para>
|
||||||
|
This implementation is generally found in arch/*/kernel/kgdb.c.
|
||||||
|
As an example, arch/x86/kernel/kgdb.c contains the specifics to
|
||||||
|
implement HW breakpoint as well as the initialization to
|
||||||
|
dynamically register and unregister for the trap handlers on
|
||||||
|
this architecture. The arch specific portion implements:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>contains an arch specific trap catcher which
|
||||||
|
invokes kgdb_handle_exception() to start kgdb about doing its
|
||||||
|
work</para></listitem>
|
||||||
|
<listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem>
|
||||||
|
<listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem>
|
||||||
|
<listitem><para>Any special exception handling and cleanup</para></listitem>
|
||||||
|
<listitem><para>NMI exception handling and cleanup</para></listitem>
|
||||||
|
<listitem><para>(optional)HW breakpoints</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem><para>kgdb I/O driver</para>
|
||||||
|
<para>
|
||||||
|
Each kgdb I/O driver has to provide an implemenation for the following:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>configuration via builtin or module</para></listitem>
|
||||||
|
<listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
|
||||||
|
<listitem><para>read and write character interface</para></listitem>
|
||||||
|
<listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
|
||||||
|
<listitem><para>(optional) Early debug methodology</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
Any given kgdb I/O driver has to operate very closely with the
|
||||||
|
hardware and must do it in such a way that does not enable
|
||||||
|
interrupts or change other parts of the system context without
|
||||||
|
completely restoring them. The kgdb core will repeatedly "poll"
|
||||||
|
a kgdb I/O driver for characters when it needs input. The I/O
|
||||||
|
driver is expected to return immediately if there is no data
|
||||||
|
available. Doing so allows for the future possibility to touch
|
||||||
|
watch dog hardware in such a way as to have a target system not
|
||||||
|
reset when these are enabled.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If you are intent on adding kgdb architecture specific support
|
||||||
|
for a new architecture, the architecture should define
|
||||||
|
<constant>HAVE_ARCH_KGDB</constant> in the architecture specific
|
||||||
|
Kconfig file. This will enable kgdb for the architecture, and
|
||||||
|
at that point you must create an architecture specific kgdb
|
||||||
|
implementation.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
There are a few flags which must be set on every architecture in
|
||||||
|
their <asm/kgdb.h> file. These are:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
NUMREGBYTES: The size in bytes of all of the registers, so
|
||||||
|
that we can ensure they will all fit into a packet.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
BUFMAX: The size in bytes of the buffer GDB will read into.
|
||||||
|
This must be larger than NUMREGBYTES.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
|
||||||
|
flush_cache_range or flush_icache_range. On some architectures,
|
||||||
|
these functions may not be safe to call on SMP since we keep other
|
||||||
|
CPUs in a holding pattern.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
There are also the following functions for the common backend,
|
||||||
|
found in kernel/kgdb.c, that must be supplied by the
|
||||||
|
architecture-specific backend unless marked as (optional), in
|
||||||
|
which case a default function maybe used if the architecture
|
||||||
|
does not need to provide a specific implementation.
|
||||||
|
</para>
|
||||||
|
!Iinclude/linux/kgdb.h
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="kgdbocDesign">
|
||||||
|
<title>kgdboc internals</title>
|
||||||
|
<para>
|
||||||
|
The kgdboc driver is actually a very thin driver that relies on the
|
||||||
|
underlying low level to the hardware driver having "polling hooks"
|
||||||
|
which the to which the tty driver is attached. In the initial
|
||||||
|
implementation of kgdboc it the serial_core was changed to expose a
|
||||||
|
low level uart hook for doing polled mode reading and writing of a
|
||||||
|
single character while in an atomic context. When kgdb makes an I/O
|
||||||
|
request to the debugger, kgdboc invokes a call back in the serial
|
||||||
|
core which in turn uses the call back in the uart driver. It is
|
||||||
|
certainly possible to extend kgdboc to work with non-uart based
|
||||||
|
consoles in the future.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>
|
||||||
|
#ifdef CONFIG_CONSOLE_POLL
|
||||||
|
.poll_get_char = serial8250_get_poll_char,
|
||||||
|
.poll_put_char = serial8250_put_poll_char,
|
||||||
|
#endif
|
||||||
|
</programlisting>
|
||||||
|
Any implementation specifics around creating a polling driver use the
|
||||||
|
<constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
|
||||||
|
Keep in mind that polling hooks have to be implemented in such a way
|
||||||
|
that they can be called from an atomic context and have to restore
|
||||||
|
the state of the uart chip on return such that the system can return
|
||||||
|
to normal when the debugger detaches. You need to be very careful
|
||||||
|
with any kind of lock you consider, because failing here is most
|
||||||
|
going to mean pressing the reset button.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="credits">
|
||||||
|
<title>Credits</title>
|
||||||
|
<para>
|
||||||
|
The following people have contributed to this document:
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>
|
||||||
|
<listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
In March 2008 this document was completely rewritten by:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
</book>
|
||||||
|
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,289 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="Reed-Solomon-Library-Guide">
|
||||||
|
<bookinfo>
|
||||||
|
<title>Reed-Solomon Library Programming Interface</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Thomas</firstname>
|
||||||
|
<surname>Gleixner</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>tglx@linutronix.de</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2004</year>
|
||||||
|
<holder>Thomas Gleixner</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation is free software; you can redistribute
|
||||||
|
it and/or modify it under the terms of the GNU General Public
|
||||||
|
License version 2 as published by the Free Software Foundation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
The generic Reed-Solomon Library provides encoding, decoding
|
||||||
|
and error correction functions.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Reed-Solomon codes are used in communication and storage
|
||||||
|
applications to ensure data integrity.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This documentation is provided for developers who want to utilize
|
||||||
|
the functions provided by the library.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="bugs">
|
||||||
|
<title>Known Bugs And Assumptions</title>
|
||||||
|
<para>
|
||||||
|
None.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="usage">
|
||||||
|
<title>Usage</title>
|
||||||
|
<para>
|
||||||
|
This chapter provides examples of how to use the library.
|
||||||
|
</para>
|
||||||
|
<sect1>
|
||||||
|
<title>Initializing</title>
|
||||||
|
<para>
|
||||||
|
The init function init_rs returns a pointer to an
|
||||||
|
rs decoder structure, which holds the necessary
|
||||||
|
information for encoding, decoding and error correction
|
||||||
|
with the given polynomial. It either uses an existing
|
||||||
|
matching decoder or creates a new one. On creation all
|
||||||
|
the lookup tables for fast en/decoding are created.
|
||||||
|
The function may take a while, so make sure not to
|
||||||
|
call it in critical code paths.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
/* the Reed Solomon control structure */
|
||||||
|
static struct rs_control *rs_decoder;
|
||||||
|
|
||||||
|
/* Symbolsize is 10 (bits)
|
||||||
|
* Primitive polynomial is x^10+x^3+1
|
||||||
|
* first consecutive root is 0
|
||||||
|
* primitive element to generate roots = 1
|
||||||
|
* generator polynomial degree (number of roots) = 6
|
||||||
|
*/
|
||||||
|
rs_decoder = init_rs (10, 0x409, 0, 1, 6);
|
||||||
|
</programlisting>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Encoding</title>
|
||||||
|
<para>
|
||||||
|
The encoder calculates the Reed-Solomon code over
|
||||||
|
the given data length and stores the result in
|
||||||
|
the parity buffer. Note that the parity buffer must
|
||||||
|
be initialized before calling the encoder.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The expanded data can be inverted on the fly by
|
||||||
|
providing a non-zero inversion mask. The expanded data is
|
||||||
|
XOR'ed with the mask. This is used e.g. for FLASH
|
||||||
|
ECC, where the all 0xFF is inverted to an all 0x00.
|
||||||
|
The Reed-Solomon code for all 0x00 is all 0x00. The
|
||||||
|
code is inverted before storing to FLASH so it is 0xFF
|
||||||
|
too. This prevents that reading from an erased FLASH
|
||||||
|
results in ECC errors.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The databytes are expanded to the given symbol size
|
||||||
|
on the fly. There is no support for encoding continuous
|
||||||
|
bitstreams with a symbol size != 8 at the moment. If
|
||||||
|
it is necessary it should be not a big deal to implement
|
||||||
|
such functionality.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6];
|
||||||
|
/* Initialize the parity buffer */
|
||||||
|
memset(par, 0, sizeof(par));
|
||||||
|
/* Encode 512 byte in data8. Store parity in buffer par */
|
||||||
|
encode_rs8 (rs_decoder, data8, 512, par, 0);
|
||||||
|
</programlisting>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Decoding</title>
|
||||||
|
<para>
|
||||||
|
The decoder calculates the syndrome over
|
||||||
|
the given data length and the received parity symbols
|
||||||
|
and corrects errors in the data.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If a syndrome is available from a hardware decoder
|
||||||
|
then the syndrome calculation is skipped.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The correction of the data buffer can be suppressed
|
||||||
|
by providing a correction pattern buffer and an error
|
||||||
|
location buffer to the decoder. The decoder stores the
|
||||||
|
calculated error location and the correction bitmask
|
||||||
|
in the given buffers. This is useful for hardware
|
||||||
|
decoders which use a weird bit ordering scheme.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The databytes are expanded to the given symbol size
|
||||||
|
on the fly. There is no support for decoding continuous
|
||||||
|
bitstreams with a symbolsize != 8 at the moment. If
|
||||||
|
it is necessary it should be not a big deal to implement
|
||||||
|
such functionality.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>
|
||||||
|
Decoding with syndrome calculation, direct data correction
|
||||||
|
</title>
|
||||||
|
<programlisting>
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr;
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
|
||||||
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>
|
||||||
|
Decoding with syndrome given by hardware decoder, direct data correction
|
||||||
|
</title>
|
||||||
|
<programlisting>
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6], syn[6];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr;
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Get syndrome from hardware decoder */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
|
||||||
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
|
|
||||||
|
<sect2>
|
||||||
|
<title>
|
||||||
|
Decoding with syndrome given by hardware decoder, no direct data correction.
|
||||||
|
</title>
|
||||||
|
<para>
|
||||||
|
Note: It's not necessary to give data and received parity to the decoder.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6], syn[6], corr[8];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr, errpos[8];
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Get syndrome from hardware decoder */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
|
||||||
|
for (i = 0; i < numerr; i++) {
|
||||||
|
do_error_correction_in_your_buffer(errpos[i], corr[i]);
|
||||||
|
}
|
||||||
|
</programlisting>
|
||||||
|
</sect2>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Cleanup</title>
|
||||||
|
<para>
|
||||||
|
The function free_rs frees the allocated resources,
|
||||||
|
if the caller is the last user of the decoder.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
/* Release resources */
|
||||||
|
free_rs(rs_decoder);
|
||||||
|
</programlisting>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="structs">
|
||||||
|
<title>Structures</title>
|
||||||
|
<para>
|
||||||
|
This chapter contains the autogenerated documentation of the structures which are
|
||||||
|
used in the Reed-Solomon Library and are relevant for a developer.
|
||||||
|
</para>
|
||||||
|
!Iinclude/linux/rslib.h
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="pubfunctions">
|
||||||
|
<title>Public Functions Provided</title>
|
||||||
|
<para>
|
||||||
|
This chapter contains the autogenerated documentation of the Reed-Solomon functions
|
||||||
|
which are exported.
|
||||||
|
</para>
|
||||||
|
!Elib/reed_solomon/reed_solomon.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="credits">
|
||||||
|
<title>Credits</title>
|
||||||
|
<para>
|
||||||
|
The library code for encoding and decoding was written by Phil Karn.
|
||||||
|
</para>
|
||||||
|
<programlisting>
|
||||||
|
Copyright 2002, Phil Karn, KA9Q
|
||||||
|
May be used under the terms of the GNU General Public License (GPL)
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
The wrapper functions and interfaces are written by Thomas Gleixner.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Many users have provided bugfixes, improvements and helping hands for testing.
|
||||||
|
Thanks a lot.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The following people have contributed to this document:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Thomas Gleixner<email>tglx@linutronix.de</email>
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
</book>
|
|
@ -0,0 +1,265 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<article class="whitepaper" id="LinuxSecurityModule" lang="en">
|
||||||
|
<articleinfo>
|
||||||
|
<title>Linux Security Modules: General Security Hooks for Linux</title>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Stephen</firstname>
|
||||||
|
<surname>Smalley</surname>
|
||||||
|
<affiliation>
|
||||||
|
<orgname>NAI Labs</orgname>
|
||||||
|
<address><email>ssmalley@nai.com</email></address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Timothy</firstname>
|
||||||
|
<surname>Fraser</surname>
|
||||||
|
<affiliation>
|
||||||
|
<orgname>NAI Labs</orgname>
|
||||||
|
<address><email>tfraser@nai.com</email></address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Chris</firstname>
|
||||||
|
<surname>Vance</surname>
|
||||||
|
<affiliation>
|
||||||
|
<orgname>NAI Labs</orgname>
|
||||||
|
<address><email>cvance@nai.com</email></address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
</articleinfo>
|
||||||
|
|
||||||
|
<sect1 id="Introduction"><title>Introduction</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In March 2001, the National Security Agency (NSA) gave a presentation
|
||||||
|
about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel
|
||||||
|
Summit. SELinux is an implementation of flexible and fine-grained
|
||||||
|
nondiscretionary access controls in the Linux kernel, originally
|
||||||
|
implemented as its own particular kernel patch. Several other
|
||||||
|
security projects (e.g. RSBAC, Medusa) have also developed flexible
|
||||||
|
access control architectures for the Linux kernel, and various
|
||||||
|
projects have developed particular access control models for Linux
|
||||||
|
(e.g. LIDS, DTE, SubDomain). Each project has developed and
|
||||||
|
maintained its own kernel patch to support its security needs.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In response to the NSA presentation, Linus Torvalds made a set of
|
||||||
|
remarks that described a security framework he would be willing to
|
||||||
|
consider for inclusion in the mainstream Linux kernel. He described a
|
||||||
|
general framework that would provide a set of security hooks to
|
||||||
|
control operations on kernel objects and a set of opaque security
|
||||||
|
fields in kernel data structures for maintaining security attributes.
|
||||||
|
This framework could then be used by loadable kernel modules to
|
||||||
|
implement any desired model of security. Linus also suggested the
|
||||||
|
possibility of migrating the Linux capabilities code into such a
|
||||||
|
module.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The Linux Security Modules (LSM) project was started by WireX to
|
||||||
|
develop such a framework. LSM is a joint development effort by
|
||||||
|
several security projects, including Immunix, SELinux, SGI and Janus,
|
||||||
|
and several individuals, including Greg Kroah-Hartman and James
|
||||||
|
Morris, to develop a Linux kernel patch that implements this
|
||||||
|
framework. The patch is currently tracking the 2.4 series and is
|
||||||
|
targeted for integration into the 2.5 development series. This
|
||||||
|
technical report provides an overview of the framework and the example
|
||||||
|
capabilities security module provided by the LSM kernel patch.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="framework"><title>LSM Framework</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The LSM kernel patch provides a general kernel framework to support
|
||||||
|
security modules. In particular, the LSM framework is primarily
|
||||||
|
focused on supporting access control modules, although future
|
||||||
|
development is likely to address other security needs such as
|
||||||
|
auditing. By itself, the framework does not provide any additional
|
||||||
|
security; it merely provides the infrastructure to support security
|
||||||
|
modules. The LSM kernel patch also moves most of the capabilities
|
||||||
|
logic into an optional security module, with the system defaulting
|
||||||
|
to the traditional superuser logic. This capabilities module
|
||||||
|
is discussed further in <xref linkend="cap"/>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The LSM kernel patch adds security fields to kernel data structures
|
||||||
|
and inserts calls to hook functions at critical points in the kernel
|
||||||
|
code to manage the security fields and to perform access control. It
|
||||||
|
also adds functions for registering and unregistering security
|
||||||
|
modules, and adds a general <function>security</function> system call
|
||||||
|
to support new system calls for security-aware applications.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The LSM security fields are simply <type>void*</type> pointers. For
|
||||||
|
process and program execution security information, security fields
|
||||||
|
were added to <structname>struct task_struct</structname> and
|
||||||
|
<structname>struct linux_binprm</structname>. For filesystem security
|
||||||
|
information, a security field was added to
|
||||||
|
<structname>struct super_block</structname>. For pipe, file, and socket
|
||||||
|
security information, security fields were added to
|
||||||
|
<structname>struct inode</structname> and
|
||||||
|
<structname>struct file</structname>. For packet and network device security
|
||||||
|
information, security fields were added to
|
||||||
|
<structname>struct sk_buff</structname> and
|
||||||
|
<structname>struct net_device</structname>. For System V IPC security
|
||||||
|
information, security fields were added to
|
||||||
|
<structname>struct kern_ipc_perm</structname> and
|
||||||
|
<structname>struct msg_msg</structname>; additionally, the definitions
|
||||||
|
for <structname>struct msg_msg</structname>, <structname>struct
|
||||||
|
msg_queue</structname>, and <structname>struct
|
||||||
|
shmid_kernel</structname> were moved to header files
|
||||||
|
(<filename>include/linux/msg.h</filename> and
|
||||||
|
<filename>include/linux/shm.h</filename> as appropriate) to allow
|
||||||
|
the security modules to use these definitions.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Each LSM hook is a function pointer in a global table,
|
||||||
|
security_ops. This table is a
|
||||||
|
<structname>security_operations</structname> structure as defined by
|
||||||
|
<filename>include/linux/security.h</filename>. Detailed documentation
|
||||||
|
for each hook is included in this header file. At present, this
|
||||||
|
structure consists of a collection of substructures that group related
|
||||||
|
hooks based on the kernel object (e.g. task, inode, file, sk_buff,
|
||||||
|
etc) as well as some top-level hook function pointers for system
|
||||||
|
operations. This structure is likely to be flattened in the future
|
||||||
|
for performance. The placement of the hook calls in the kernel code
|
||||||
|
is described by the "called:" lines in the per-hook documentation in
|
||||||
|
the header file. The hook calls can also be easily found in the
|
||||||
|
kernel code by looking for the string "security_ops->".
|
||||||
|
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Linus mentioned per-process security hooks in his original remarks as a
|
||||||
|
possible alternative to global security hooks. However, if LSM were
|
||||||
|
to start from the perspective of per-process hooks, then the base
|
||||||
|
framework would have to deal with how to handle operations that
|
||||||
|
involve multiple processes (e.g. kill), since each process might have
|
||||||
|
its own hook for controlling the operation. This would require a
|
||||||
|
general mechanism for composing hooks in the base framework.
|
||||||
|
Additionally, LSM would still need global hooks for operations that
|
||||||
|
have no process context (e.g. network input operations).
|
||||||
|
Consequently, LSM provides global security hooks, but a security
|
||||||
|
module is free to implement per-process hooks (where that makes sense)
|
||||||
|
by storing a security_ops table in each process' security field and
|
||||||
|
then invoking these per-process hooks from the global hooks.
|
||||||
|
The problem of composition is thus deferred to the module.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The global security_ops table is initialized to a set of hook
|
||||||
|
functions provided by a dummy security module that provides
|
||||||
|
traditional superuser logic. A <function>register_security</function>
|
||||||
|
function (in <filename>security/security.c</filename>) is provided to
|
||||||
|
allow a security module to set security_ops to refer to its own hook
|
||||||
|
functions, and an <function>unregister_security</function> function is
|
||||||
|
provided to revert security_ops to the dummy module hooks. This
|
||||||
|
mechanism is used to set the primary security module, which is
|
||||||
|
responsible for making the final decision for each hook.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
LSM also provides a simple mechanism for stacking additional security
|
||||||
|
modules with the primary security module. It defines
|
||||||
|
<function>register_security</function> and
|
||||||
|
<function>unregister_security</function> hooks in the
|
||||||
|
<structname>security_operations</structname> structure and provides
|
||||||
|
<function>mod_reg_security</function> and
|
||||||
|
<function>mod_unreg_security</function> functions that invoke these
|
||||||
|
hooks after performing some sanity checking. A security module can
|
||||||
|
call these functions in order to stack with other modules. However,
|
||||||
|
the actual details of how this stacking is handled are deferred to the
|
||||||
|
module, which can implement these hooks in any way it wishes
|
||||||
|
(including always returning an error if it does not wish to support
|
||||||
|
stacking). In this manner, LSM again defers the problem of
|
||||||
|
composition to the module.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Although the LSM hooks are organized into substructures based on
|
||||||
|
kernel object, all of the hooks can be viewed as falling into two
|
||||||
|
major categories: hooks that are used to manage the security fields
|
||||||
|
and hooks that are used to perform access control. Examples of the
|
||||||
|
first category of hooks include the
|
||||||
|
<function>alloc_security</function> and
|
||||||
|
<function>free_security</function> hooks defined for each kernel data
|
||||||
|
structure that has a security field. These hooks are used to allocate
|
||||||
|
and free security structures for kernel objects. The first category
|
||||||
|
of hooks also includes hooks that set information in the security
|
||||||
|
field after allocation, such as the <function>post_lookup</function>
|
||||||
|
hook in <structname>struct inode_security_ops</structname>. This hook
|
||||||
|
is used to set security information for inodes after successful lookup
|
||||||
|
operations. An example of the second category of hooks is the
|
||||||
|
<function>permission</function> hook in
|
||||||
|
<structname>struct inode_security_ops</structname>. This hook checks
|
||||||
|
permission when accessing an inode.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 id="cap"><title>LSM Capabilities Module</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The LSM kernel patch moves most of the existing POSIX.1e capabilities
|
||||||
|
logic into an optional security module stored in the file
|
||||||
|
<filename>security/capability.c</filename>. This change allows
|
||||||
|
users who do not want to use capabilities to omit this code entirely
|
||||||
|
from their kernel, instead using the dummy module for traditional
|
||||||
|
superuser logic or any other module that they desire. This change
|
||||||
|
also allows the developers of the capabilities logic to maintain and
|
||||||
|
enhance their code more freely, without needing to integrate patches
|
||||||
|
back into the base kernel.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In addition to moving the capabilities logic, the LSM kernel patch
|
||||||
|
could move the capability-related fields from the kernel data
|
||||||
|
structures into the new security fields managed by the security
|
||||||
|
modules. However, at present, the LSM kernel patch leaves the
|
||||||
|
capability fields in the kernel data structures. In his original
|
||||||
|
remarks, Linus suggested that this might be preferable so that other
|
||||||
|
security modules can be easily stacked with the capabilities module
|
||||||
|
without needing to chain multiple security structures on the security field.
|
||||||
|
It also avoids imposing extra overhead on the capabilities module
|
||||||
|
to manage the security fields. However, the LSM framework could
|
||||||
|
certainly support such a move if it is determined to be desirable,
|
||||||
|
with only a few additional changes described below.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
At present, the capabilities logic for computing process capabilities
|
||||||
|
on <function>execve</function> and <function>set*uid</function>,
|
||||||
|
checking capabilities for a particular process, saving and checking
|
||||||
|
capabilities for netlink messages, and handling the
|
||||||
|
<function>capget</function> and <function>capset</function> system
|
||||||
|
calls have been moved into the capabilities module. There are still a
|
||||||
|
few locations in the base kernel where capability-related fields are
|
||||||
|
directly examined or modified, but the current version of the LSM
|
||||||
|
patch does allow a security module to completely replace the
|
||||||
|
assignment and testing of capabilities. These few locations would
|
||||||
|
need to be changed if the capability-related fields were moved into
|
||||||
|
the security field. The following is a list of known locations that
|
||||||
|
still perform such direct examination or modification of
|
||||||
|
capability-related fields:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para><filename>fs/open.c</filename>:<function>sys_access</function></para></listitem>
|
||||||
|
<listitem><para><filename>fs/lockd/host.c</filename>:<function>nlm_bind_host</function></para></listitem>
|
||||||
|
<listitem><para><filename>fs/nfsd/auth.c</filename>:<function>nfsd_setuser</function></para></listitem>
|
||||||
|
<listitem><para><filename>fs/proc/array.c</filename>:<function>task_cap</function></para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
</sect1>
|
||||||
|
|
||||||
|
</article>
|
|
@ -0,0 +1,338 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="mac80211-developers-guide">
|
||||||
|
<bookinfo>
|
||||||
|
<title>The mac80211 subsystem for kernel developers</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Johannes</firstname>
|
||||||
|
<surname>Berg</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address><email>johannes@sipsolutions.net</email></address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2007-2009</year>
|
||||||
|
<holder>Johannes Berg</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation is free software; you can redistribute
|
||||||
|
it and/or modify it under the terms of the GNU General Public
|
||||||
|
License version 2 as published by the Free Software Foundation.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This documentation is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this documentation; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
|
||||||
|
<abstract>
|
||||||
|
!Pinclude/net/mac80211.h Introduction
|
||||||
|
!Pinclude/net/mac80211.h Warning
|
||||||
|
</abstract>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<!--
|
||||||
|
Generally, this document shall be ordered by increasing complexity.
|
||||||
|
It is important to note that readers should be able to read only
|
||||||
|
the first few sections to get a working driver and only advanced
|
||||||
|
usage should require reading the full document.
|
||||||
|
-->
|
||||||
|
|
||||||
|
<part>
|
||||||
|
<title>The basic mac80211 driver interface</title>
|
||||||
|
<partintro>
|
||||||
|
<para>
|
||||||
|
You should read and understand the information contained
|
||||||
|
within this part of the book while implementing a driver.
|
||||||
|
In some chapters, advanced usage is noted, that may be
|
||||||
|
skipped at first.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
This part of the book only covers station and monitor mode
|
||||||
|
functionality, additional information required to implement
|
||||||
|
the other modes is covered in the second part of the book.
|
||||||
|
</para>
|
||||||
|
</partintro>
|
||||||
|
|
||||||
|
<chapter id="basics">
|
||||||
|
<title>Basic hardware handling</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This chapter shall contain information on getting a hw
|
||||||
|
struct allocated and registered with mac80211.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Since it is required to allocate rates/modes before registering
|
||||||
|
a hw struct, this chapter shall also contain information on setting
|
||||||
|
up the rate/mode structs.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Additionally, some discussion about the callbacks and
|
||||||
|
the general programming model should be in here, including
|
||||||
|
the definition of ieee80211_ops which will be referred to
|
||||||
|
a lot.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Finally, a discussion of hardware capabilities should be done
|
||||||
|
with references to other parts of the book.
|
||||||
|
</para>
|
||||||
|
<!-- intentionally multiple !F lines to get proper order -->
|
||||||
|
!Finclude/net/mac80211.h ieee80211_hw
|
||||||
|
!Finclude/net/mac80211.h ieee80211_hw_flags
|
||||||
|
!Finclude/net/mac80211.h SET_IEEE80211_DEV
|
||||||
|
!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
|
||||||
|
!Finclude/net/mac80211.h ieee80211_ops
|
||||||
|
!Finclude/net/mac80211.h ieee80211_alloc_hw
|
||||||
|
!Finclude/net/mac80211.h ieee80211_register_hw
|
||||||
|
!Finclude/net/mac80211.h ieee80211_get_tx_led_name
|
||||||
|
!Finclude/net/mac80211.h ieee80211_get_rx_led_name
|
||||||
|
!Finclude/net/mac80211.h ieee80211_get_assoc_led_name
|
||||||
|
!Finclude/net/mac80211.h ieee80211_get_radio_led_name
|
||||||
|
!Finclude/net/mac80211.h ieee80211_unregister_hw
|
||||||
|
!Finclude/net/mac80211.h ieee80211_free_hw
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="phy-handling">
|
||||||
|
<title>PHY configuration</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This chapter should describe PHY handling including
|
||||||
|
start/stop callbacks and the various structures used.
|
||||||
|
</para>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_conf
|
||||||
|
!Finclude/net/mac80211.h ieee80211_conf_flags
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="iface-handling">
|
||||||
|
<title>Virtual interfaces</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This chapter should describe virtual interface basics
|
||||||
|
that are relevant to the driver (VLANs, MGMT etc are not.)
|
||||||
|
It should explain the use of the add_iface/remove_iface
|
||||||
|
callbacks as well as the interface configuration callbacks.
|
||||||
|
</para>
|
||||||
|
<para>Things related to AP mode should be discussed there.</para>
|
||||||
|
<para>
|
||||||
|
Things related to supporting multiple interfaces should be
|
||||||
|
in the appropriate chapter, a BIG FAT note should be here about
|
||||||
|
this though and the recommendation to allow only a single
|
||||||
|
interface in STA mode at first!
|
||||||
|
</para>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_if_init_conf
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="rx-tx">
|
||||||
|
<title>Receive and transmit processing</title>
|
||||||
|
<sect1>
|
||||||
|
<title>what should be here</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This should describe the receive and transmit
|
||||||
|
paths in mac80211/the drivers as well as
|
||||||
|
transmit status handling.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Frame format</title>
|
||||||
|
!Pinclude/net/mac80211.h Frame format
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Packet alignment</title>
|
||||||
|
!Pnet/mac80211/rx.c Packet alignment
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>Calling into mac80211 from interrupts</title>
|
||||||
|
!Pinclude/net/mac80211.h Calling mac80211 from interrupts
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>functions/definitions</title>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_rx_status
|
||||||
|
!Finclude/net/mac80211.h mac80211_rx_flags
|
||||||
|
!Finclude/net/mac80211.h ieee80211_tx_info
|
||||||
|
!Finclude/net/mac80211.h ieee80211_rx
|
||||||
|
!Finclude/net/mac80211.h ieee80211_rx_irqsafe
|
||||||
|
!Finclude/net/mac80211.h ieee80211_tx_status
|
||||||
|
!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
|
||||||
|
!Finclude/net/mac80211.h ieee80211_rts_get
|
||||||
|
!Finclude/net/mac80211.h ieee80211_rts_duration
|
||||||
|
!Finclude/net/mac80211.h ieee80211_ctstoself_get
|
||||||
|
!Finclude/net/mac80211.h ieee80211_ctstoself_duration
|
||||||
|
!Finclude/net/mac80211.h ieee80211_generic_frame_duration
|
||||||
|
!Finclude/net/mac80211.h ieee80211_wake_queue
|
||||||
|
!Finclude/net/mac80211.h ieee80211_stop_queue
|
||||||
|
!Finclude/net/mac80211.h ieee80211_wake_queues
|
||||||
|
!Finclude/net/mac80211.h ieee80211_stop_queues
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="filters">
|
||||||
|
<title>Frame filtering</title>
|
||||||
|
!Pinclude/net/mac80211.h Frame filtering
|
||||||
|
!Finclude/net/mac80211.h ieee80211_filter_flags
|
||||||
|
</chapter>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
<part id="advanced">
|
||||||
|
<title>Advanced driver interface</title>
|
||||||
|
<partintro>
|
||||||
|
<para>
|
||||||
|
Information contained within this part of the book is
|
||||||
|
of interest only for advanced interaction of mac80211
|
||||||
|
with drivers to exploit more hardware capabilities and
|
||||||
|
improve performance.
|
||||||
|
</para>
|
||||||
|
</partintro>
|
||||||
|
|
||||||
|
<chapter id="hardware-crypto-offload">
|
||||||
|
<title>Hardware crypto acceleration</title>
|
||||||
|
!Pinclude/net/mac80211.h Hardware crypto acceleration
|
||||||
|
<!-- intentionally multiple !F lines to get proper order -->
|
||||||
|
!Finclude/net/mac80211.h set_key_cmd
|
||||||
|
!Finclude/net/mac80211.h ieee80211_key_conf
|
||||||
|
!Finclude/net/mac80211.h ieee80211_key_alg
|
||||||
|
!Finclude/net/mac80211.h ieee80211_key_flags
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="powersave">
|
||||||
|
<title>Powersave support</title>
|
||||||
|
!Pinclude/net/mac80211.h Powersave support
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="beacon-filter">
|
||||||
|
<title>Beacon filter support</title>
|
||||||
|
!Pinclude/net/mac80211.h Beacon filter support
|
||||||
|
!Finclude/net/mac80211.h ieee80211_beacon_loss
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="qos">
|
||||||
|
<title>Multiple queues and QoS support</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_tx_queue_params
|
||||||
|
!Finclude/net/mac80211.h ieee80211_tx_queue_stats
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="AP">
|
||||||
|
<title>Access point mode support</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>Some parts of the if_conf should be discussed here instead</para>
|
||||||
|
<para>
|
||||||
|
Insert notes about VLAN interfaces with hw crypto here or
|
||||||
|
in the hw crypto chapter.
|
||||||
|
</para>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_get_buffered_bc
|
||||||
|
!Finclude/net/mac80211.h ieee80211_beacon_get
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="multi-iface">
|
||||||
|
<title>Supporting multiple virtual interfaces</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
Note: WDS with identical MAC address should almost always be OK
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Insert notes about having multiple virtual interfaces with
|
||||||
|
different MAC addresses here, note which configurations are
|
||||||
|
supported by mac80211, add notes about supporting hw crypto
|
||||||
|
with it.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="hardware-scan-offload">
|
||||||
|
<title>Hardware scan offload</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
!Finclude/net/mac80211.h ieee80211_scan_completed
|
||||||
|
</chapter>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
<part id="rate-control">
|
||||||
|
<title>Rate control interface</title>
|
||||||
|
<partintro>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This part of the book describes the rate control algorithm
|
||||||
|
interface and how it relates to mac80211 and drivers.
|
||||||
|
</para>
|
||||||
|
</partintro>
|
||||||
|
<chapter id="dummy">
|
||||||
|
<title>dummy chapter</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
</chapter>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
<part id="internal">
|
||||||
|
<title>Internals</title>
|
||||||
|
<partintro>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>
|
||||||
|
This part of the book describes mac80211 internals.
|
||||||
|
</para>
|
||||||
|
</partintro>
|
||||||
|
|
||||||
|
<chapter id="key-handling">
|
||||||
|
<title>Key handling</title>
|
||||||
|
<sect1>
|
||||||
|
<title>Key handling basics</title>
|
||||||
|
!Pnet/mac80211/key.c Key handling basics
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>MORE TBD</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="rx-processing">
|
||||||
|
<title>Receive processing</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="tx-processing">
|
||||||
|
<title>Transmit processing</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="sta-info">
|
||||||
|
<title>Station info handling</title>
|
||||||
|
<sect1>
|
||||||
|
<title>Programming information</title>
|
||||||
|
!Fnet/mac80211/sta_info.h sta_info
|
||||||
|
!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
|
||||||
|
</sect1>
|
||||||
|
<sect1>
|
||||||
|
<title>STA information lifetime rules</title>
|
||||||
|
!Pnet/mac80211/sta_info.c STA information lifetime rules
|
||||||
|
</sect1>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="synchronisation">
|
||||||
|
<title>Synchronisation</title>
|
||||||
|
<para>TBD</para>
|
||||||
|
<para>Locking, lots of RCU</para>
|
||||||
|
</chapter>
|
||||||
|
</part>
|
||||||
|
</book>
|
|
@ -0,0 +1,107 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
|
||||||
|
|
||||||
|
<book id="MCAGuide">
|
||||||
|
<bookinfo>
|
||||||
|
<title>MCA Driver Programming Interface</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Alan</firstname>
|
||||||
|
<surname>Cox</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>alan@lxorguk.ukuu.org.uk</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>David</firstname>
|
||||||
|
<surname>Weinehall</surname>
|
||||||
|
</author>
|
||||||
|
<author>
|
||||||
|
<firstname>Chris</firstname>
|
||||||
|
<surname>Beauregard</surname>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2000</year>
|
||||||
|
<holder>Alan Cox</holder>
|
||||||
|
<holder>David Weinehall</holder>
|
||||||
|
<holder>Chris Beauregard</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
This documentation 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.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
This program is distributed in the hope that it will be
|
||||||
|
useful, but WITHOUT ANY WARRANTY; without even the implied
|
||||||
|
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
See the GNU General Public License for more details.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You should have received a copy of the GNU General Public
|
||||||
|
License along with this program; if not, write to the Free
|
||||||
|
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
|
||||||
|
MA 02111-1307 USA
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
For more details see the file COPYING in the source
|
||||||
|
distribution of Linux.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<chapter id="intro">
|
||||||
|
<title>Introduction</title>
|
||||||
|
<para>
|
||||||
|
The MCA bus functions provide a generalised interface to find MCA
|
||||||
|
bus cards, to claim them for a driver, and to read and manipulate POS
|
||||||
|
registers without being aware of the motherboard internals or
|
||||||
|
certain deep magic specific to onboard devices.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The basic interface to the MCA bus devices is the slot. Each slot
|
||||||
|
is numbered and virtual slot numbers are assigned to the internal
|
||||||
|
devices. Using a pci_dev as other busses do does not really make
|
||||||
|
sense in the MCA context as the MCA bus resources require card
|
||||||
|
specific interpretation.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Finally the MCA bus functions provide a parallel set of DMA
|
||||||
|
functions mimicing the ISA bus DMA functions as closely as possible,
|
||||||
|
although also supporting the additional DMA functionality on the
|
||||||
|
MCA bus controllers.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
<chapter id="bugs">
|
||||||
|
<title>Known Bugs And Assumptions</title>
|
||||||
|
<para>
|
||||||
|
None.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="pubfunctions">
|
||||||
|
<title>Public Functions Provided</title>
|
||||||
|
!Edrivers/mca/mca-legacy.c
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="dmafunctions">
|
||||||
|
<title>DMA Functions Provided</title>
|
||||||
|
!Iarch/x86/include/asm/mca_dma.h
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
</book>
|
|
@ -0,0 +1,364 @@
|
||||||
|
<!-- Generated file! Do not edit. -->
|
||||||
|
|
||||||
|
<!-- Functions -->
|
||||||
|
<!ENTITY func-close "<link linkend='func-close'><function>close()</function></link>">
|
||||||
|
<!ENTITY func-ioctl "<link linkend='func-ioctl'><function>ioctl()</function></link>">
|
||||||
|
<!ENTITY func-mmap "<link linkend='func-mmap'><function>mmap()</function></link>">
|
||||||
|
<!ENTITY func-munmap "<link linkend='func-munmap'><function>munmap()</function></link>">
|
||||||
|
<!ENTITY func-open "<link linkend='func-open'><function>open()</function></link>">
|
||||||
|
<!ENTITY func-poll "<link linkend='func-poll'><function>poll()</function></link>">
|
||||||
|
<!ENTITY func-read "<link linkend='func-read'><function>read()</function></link>">
|
||||||
|
<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">
|
||||||
|
<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">
|
||||||
|
|
||||||
|
<!-- Ioctls -->
|
||||||
|
<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-DBG-G-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_G_REGISTER</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-DBG-S-REGISTER "<link linkend='vidioc-dbg-g-register'><constant>VIDIOC_DBG_S_REGISTER</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-DQBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_DQBUF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_ENCODER_CMD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUMAUDIO "<link linkend='vidioc-enumaudio'><constant>VIDIOC_ENUMAUDIO</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUMAUDOUT "<link linkend='vidioc-enumaudioout'><constant>VIDIOC_ENUMAUDOUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUMINPUT "<link linkend='vidioc-enuminput'><constant>VIDIOC_ENUMINPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUMOUTPUT "<link linkend='vidioc-enumoutput'><constant>VIDIOC_ENUMOUTPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUMSTD "<link linkend='vidioc-enumstd'><constant>VIDIOC_ENUMSTD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUM-FMT "<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUM-FRAMEINTERVALS "<link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-ENUM-FRAMESIZES "<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_G_AUDIO</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_G_AUDOUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_G_CROP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_G_CTRL</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-ENC-INDEX "<link linkend='vidioc-g-enc-index'><constant>VIDIOC_G_ENC_INDEX</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_G_EXT_CTRLS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_G_FBUF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_G_FREQUENCY</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_G_INPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_G_JPEGCOMP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-MPEGCOMP "<link linkend=''><constant>VIDIOC_G_MPEGCOMP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_G_MODULATOR</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_G_OUTPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_G_PARM</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_G_PRIORITY</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-SLICED-VBI-CAP "<link linkend='vidioc-g-sliced-vbi-cap'><constant>VIDIOC_G_SLICED_VBI_CAP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_G_STD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-G-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_G_TUNER</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-LOG-STATUS "<link linkend='vidioc-log-status'><constant>VIDIOC_LOG_STATUS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-OVERLAY "<link linkend='vidioc-overlay'><constant>VIDIOC_OVERLAY</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QBUF "<link linkend='vidioc-qbuf'><constant>VIDIOC_QBUF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QUERYBUF "<link linkend='vidioc-querybuf'><constant>VIDIOC_QUERYBUF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QUERYCAP "<link linkend='vidioc-querycap'><constant>VIDIOC_QUERYCAP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QUERYCTRL "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYCTRL</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QUERYMENU "<link linkend='vidioc-queryctrl'><constant>VIDIOC_QUERYMENU</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-QUERYSTD "<link linkend='vidioc-querystd'><constant>VIDIOC_QUERYSTD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-REQBUFS "<link linkend='vidioc-reqbufs'><constant>VIDIOC_REQBUFS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-STREAMOFF "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMOFF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-STREAMON "<link linkend='vidioc-streamon'><constant>VIDIOC_STREAMON</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-AUDIO "<link linkend='vidioc-g-audio'><constant>VIDIOC_S_AUDIO</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-AUDOUT "<link linkend='vidioc-g-audioout'><constant>VIDIOC_S_AUDOUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-CROP "<link linkend='vidioc-g-crop'><constant>VIDIOC_S_CROP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-CTRL "<link linkend='vidioc-g-ctrl'><constant>VIDIOC_S_CTRL</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_S_EXT_CTRLS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-FBUF "<link linkend='vidioc-g-fbuf'><constant>VIDIOC_S_FBUF</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-FREQUENCY "<link linkend='vidioc-g-frequency'><constant>VIDIOC_S_FREQUENCY</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-HW-FREQ-SEEK "<link linkend='vidioc-s-hw-freq-seek'><constant>VIDIOC_S_HW_FREQ_SEEK</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-INPUT "<link linkend='vidioc-g-input'><constant>VIDIOC_S_INPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-JPEGCOMP "<link linkend='vidioc-g-jpegcomp'><constant>VIDIOC_S_JPEGCOMP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-MPEGCOMP "<link linkend=''><constant>VIDIOC_S_MPEGCOMP</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-MODULATOR "<link linkend='vidioc-g-modulator'><constant>VIDIOC_S_MODULATOR</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-OUTPUT "<link linkend='vidioc-g-output'><constant>VIDIOC_S_OUTPUT</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-PARM "<link linkend='vidioc-g-parm'><constant>VIDIOC_S_PARM</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>">
|
||||||
|
<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">
|
||||||
|
|
||||||
|
<!-- Types -->
|
||||||
|
<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
|
||||||
|
|
||||||
|
<!-- Enums -->
|
||||||
|
<!ENTITY v4l2-buf-type "enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link>">
|
||||||
|
<!ENTITY v4l2-colorspace "enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link>">
|
||||||
|
<!ENTITY v4l2-ctrl-type "enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link>">
|
||||||
|
<!ENTITY v4l2-exposure-auto-type "enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link>">
|
||||||
|
<!ENTITY v4l2-field "enum <link linkend='v4l2-field'>v4l2_field</link>">
|
||||||
|
<!ENTITY v4l2-frmivaltypes "enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>">
|
||||||
|
<!ENTITY v4l2-frmsizetypes "enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>">
|
||||||
|
<!ENTITY v4l2-memory "enum <link linkend='v4l2-memory'>v4l2_memory</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-crc "enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-emphasis "enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-encoding "enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-l1-bitrate "enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-l2-bitrate "enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-l3-bitrate "enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-mode "enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-mode-extension "enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-audio-sampling-freq "enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link>">
|
||||||
|
<!ENTITY chroma-spatial-filter-type "enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link>">
|
||||||
|
<!ENTITY luma-spatial-filter-type "enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-cx2341x-video-median-filter-type "enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-cx2341x-video-spatial-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-cx2341x-video-temporal-filter-mode "enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-stream-type "enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-stream-vbi-fmt "enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-video-aspect "enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-video-bitrate-mode "enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-video-encoding "enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>">
|
||||||
|
<!ENTITY v4l2-power-line-frequency "enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>">
|
||||||
|
<!ENTITY v4l2-priority "enum <link linkend='v4l2-priority'>v4l2_priority</link>">
|
||||||
|
<!ENTITY v4l2-tuner-type "enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>">
|
||||||
|
<!ENTITY v4l2-preemphasis "enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>">
|
||||||
|
|
||||||
|
<!-- Structures -->
|
||||||
|
<!ENTITY v4l2-audio "struct <link linkend='v4l2-audio'>v4l2_audio</link>">
|
||||||
|
<!ENTITY v4l2-audioout "struct <link linkend='v4l2-audioout'>v4l2_audioout</link>">
|
||||||
|
<!ENTITY v4l2-buffer "struct <link linkend='v4l2-buffer'>v4l2_buffer</link>">
|
||||||
|
<!ENTITY v4l2-capability "struct <link linkend='v4l2-capability'>v4l2_capability</link>">
|
||||||
|
<!ENTITY v4l2-captureparm "struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
|
||||||
|
<!ENTITY v4l2-clip "struct <link linkend='v4l2-clip'>v4l2_clip</link>">
|
||||||
|
<!ENTITY v4l2-control "struct <link linkend='v4l2-control'>v4l2_control</link>">
|
||||||
|
<!ENTITY v4l2-crop "struct <link linkend='v4l2-crop'>v4l2_crop</link>">
|
||||||
|
<!ENTITY v4l2-cropcap "struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link>">
|
||||||
|
<!ENTITY v4l2-dbg-chip-ident "struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link>">
|
||||||
|
<!ENTITY v4l2-dbg-match "struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link>">
|
||||||
|
<!ENTITY v4l2-dbg-register "struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link>">
|
||||||
|
<!ENTITY v4l2-enc-idx "struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link>">
|
||||||
|
<!ENTITY v4l2-enc-idx-entry "struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link>">
|
||||||
|
<!ENTITY v4l2-encoder-cmd "struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link>">
|
||||||
|
<!ENTITY v4l2-ext-control "struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link>">
|
||||||
|
<!ENTITY v4l2-ext-controls "struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link>">
|
||||||
|
<!ENTITY v4l2-fmtdesc "struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link>">
|
||||||
|
<!ENTITY v4l2-format "struct <link linkend='v4l2-format'>v4l2_format</link>">
|
||||||
|
<!ENTITY v4l2-fract "struct <link linkend='v4l2-fract'>v4l2_fract</link>">
|
||||||
|
<!ENTITY v4l2-framebuffer "struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link>">
|
||||||
|
<!ENTITY v4l2-frequency "struct <link linkend='v4l2-frequency'>v4l2_frequency</link>">
|
||||||
|
<!ENTITY v4l2-frmival-stepwise "struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link>">
|
||||||
|
<!ENTITY v4l2-frmivalenum "struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link>">
|
||||||
|
<!ENTITY v4l2-frmsize-discrete "struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link>">
|
||||||
|
<!ENTITY v4l2-frmsize-stepwise "struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link>">
|
||||||
|
<!ENTITY v4l2-frmsizeenum "struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link>">
|
||||||
|
<!ENTITY v4l2-hw-freq-seek "struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>">
|
||||||
|
<!ENTITY v4l2-input "struct <link linkend='v4l2-input'>v4l2_input</link>">
|
||||||
|
<!ENTITY v4l2-jpegcompression "struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>">
|
||||||
|
<!ENTITY v4l2-modulator "struct <link linkend='v4l2-modulator'>v4l2_modulator</link>">
|
||||||
|
<!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>">
|
||||||
|
<!ENTITY v4l2-output "struct <link linkend='v4l2-output'>v4l2_output</link>">
|
||||||
|
<!ENTITY v4l2-outputparm "struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link>">
|
||||||
|
<!ENTITY v4l2-pix-format "struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link>">
|
||||||
|
<!ENTITY v4l2-queryctrl "struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>">
|
||||||
|
<!ENTITY v4l2-querymenu "struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link>">
|
||||||
|
<!ENTITY v4l2-rect "struct <link linkend='v4l2-rect'>v4l2_rect</link>">
|
||||||
|
<!ENTITY v4l2-requestbuffers "struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link>">
|
||||||
|
<!ENTITY v4l2-sliced-vbi-cap "struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>">
|
||||||
|
<!ENTITY v4l2-sliced-vbi-data "struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>">
|
||||||
|
<!ENTITY v4l2-sliced-vbi-format "struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>">
|
||||||
|
<!ENTITY v4l2-standard "struct <link linkend='v4l2-standard'>v4l2_standard</link>">
|
||||||
|
<!ENTITY v4l2-streamparm "struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link>">
|
||||||
|
<!ENTITY v4l2-timecode "struct <link linkend='v4l2-timecode'>v4l2_timecode</link>">
|
||||||
|
<!ENTITY v4l2-tuner "struct <link linkend='v4l2-tuner'>v4l2_tuner</link>">
|
||||||
|
<!ENTITY v4l2-vbi-format "struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">
|
||||||
|
<!ENTITY v4l2-window "struct <link linkend='v4l2-window'>v4l2_window</link>">
|
||||||
|
|
||||||
|
<!-- Error Codes -->
|
||||||
|
<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">
|
||||||
|
<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">
|
||||||
|
<!ENTITY EBADF "<errorcode>EBADF</errorcode> error code">
|
||||||
|
<!ENTITY EBUSY "<errorcode>EBUSY</errorcode> error code">
|
||||||
|
<!ENTITY EFAULT "<errorcode>EFAULT</errorcode> error code">
|
||||||
|
<!ENTITY EIO "<errorcode>EIO</errorcode> error code">
|
||||||
|
<!ENTITY EINTR "<errorcode>EINTR</errorcode> error code">
|
||||||
|
<!ENTITY EINVAL "<errorcode>EINVAL</errorcode> error code">
|
||||||
|
<!ENTITY ENFILE "<errorcode>ENFILE</errorcode> error code">
|
||||||
|
<!ENTITY ENOMEM "<errorcode>ENOMEM</errorcode> error code">
|
||||||
|
<!ENTITY ENOSPC "<errorcode>ENOSPC</errorcode> error code">
|
||||||
|
<!ENTITY ENOTTY "<errorcode>ENOTTY</errorcode> error code">
|
||||||
|
<!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code">
|
||||||
|
<!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code">
|
||||||
|
<!ENTITY EPERM "<errorcode>EPERM</errorcode> error code">
|
||||||
|
<!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code">
|
||||||
|
|
||||||
|
<!-- Subsections -->
|
||||||
|
<!ENTITY sub-biblio SYSTEM "v4l/biblio.xml">
|
||||||
|
<!ENTITY sub-common SYSTEM "v4l/common.xml">
|
||||||
|
<!ENTITY sub-compat SYSTEM "v4l/compat.xml">
|
||||||
|
<!ENTITY sub-controls SYSTEM "v4l/controls.xml">
|
||||||
|
<!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
|
||||||
|
<!ENTITY sub-dev-codec SYSTEM "v4l/dev-codec.xml">
|
||||||
|
<!ENTITY sub-dev-effect SYSTEM "v4l/dev-effect.xml">
|
||||||
|
<!ENTITY sub-dev-osd SYSTEM "v4l/dev-osd.xml">
|
||||||
|
<!ENTITY sub-dev-output SYSTEM "v4l/dev-output.xml">
|
||||||
|
<!ENTITY sub-dev-overlay SYSTEM "v4l/dev-overlay.xml">
|
||||||
|
<!ENTITY sub-dev-radio SYSTEM "v4l/dev-radio.xml">
|
||||||
|
<!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml">
|
||||||
|
<!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml">
|
||||||
|
<!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml">
|
||||||
|
<!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml">
|
||||||
|
<!ENTITY sub-driver SYSTEM "v4l/driver.xml">
|
||||||
|
<!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml">
|
||||||
|
<!ENTITY sub-remote_controllers SYSTEM "v4l/remote_controllers.xml">
|
||||||
|
<!ENTITY sub-fdl-appendix SYSTEM "v4l/fdl-appendix.xml">
|
||||||
|
<!ENTITY sub-close SYSTEM "v4l/func-close.xml">
|
||||||
|
<!ENTITY sub-ioctl SYSTEM "v4l/func-ioctl.xml">
|
||||||
|
<!ENTITY sub-mmap SYSTEM "v4l/func-mmap.xml">
|
||||||
|
<!ENTITY sub-munmap SYSTEM "v4l/func-munmap.xml">
|
||||||
|
<!ENTITY sub-open SYSTEM "v4l/func-open.xml">
|
||||||
|
<!ENTITY sub-poll SYSTEM "v4l/func-poll.xml">
|
||||||
|
<!ENTITY sub-read SYSTEM "v4l/func-read.xml">
|
||||||
|
<!ENTITY sub-select SYSTEM "v4l/func-select.xml">
|
||||||
|
<!ENTITY sub-write SYSTEM "v4l/func-write.xml">
|
||||||
|
<!ENTITY sub-io SYSTEM "v4l/io.xml">
|
||||||
|
<!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml">
|
||||||
|
<!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml">
|
||||||
|
<!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml">
|
||||||
|
<!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
|
||||||
|
<!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
|
||||||
|
<!ENTITY sub-sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml">
|
||||||
|
<!ENTITY sub-sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml">
|
||||||
|
<!ENTITY sub-sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml">
|
||||||
|
<!ENTITY sub-sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml">
|
||||||
|
<!ENTITY sub-uyvy SYSTEM "v4l/pixfmt-uyvy.xml">
|
||||||
|
<!ENTITY sub-vyuy SYSTEM "v4l/pixfmt-vyuy.xml">
|
||||||
|
<!ENTITY sub-y16 SYSTEM "v4l/pixfmt-y16.xml">
|
||||||
|
<!ENTITY sub-y41p SYSTEM "v4l/pixfmt-y41p.xml">
|
||||||
|
<!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
|
||||||
|
<!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
|
||||||
|
<!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
|
||||||
|
<!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
|
||||||
|
<!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
|
||||||
|
<!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
|
||||||
|
<!ENTITY sub-pixfmt SYSTEM "v4l/pixfmt.xml">
|
||||||
|
<!ENTITY sub-cropcap SYSTEM "v4l/vidioc-cropcap.xml">
|
||||||
|
<!ENTITY sub-dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml">
|
||||||
|
<!ENTITY sub-encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml">
|
||||||
|
<!ENTITY sub-enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml">
|
||||||
|
<!ENTITY sub-enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml">
|
||||||
|
<!ENTITY sub-enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml">
|
||||||
|
<!ENTITY sub-enumaudio SYSTEM "v4l/vidioc-enumaudio.xml">
|
||||||
|
<!ENTITY sub-enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">
|
||||||
|
<!ENTITY sub-enuminput SYSTEM "v4l/vidioc-enuminput.xml">
|
||||||
|
<!ENTITY sub-enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">
|
||||||
|
<!ENTITY sub-enumstd SYSTEM "v4l/vidioc-enumstd.xml">
|
||||||
|
<!ENTITY sub-g-audio SYSTEM "v4l/vidioc-g-audio.xml">
|
||||||
|
<!ENTITY sub-g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">
|
||||||
|
<!ENTITY sub-dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml">
|
||||||
|
<!ENTITY sub-g-crop SYSTEM "v4l/vidioc-g-crop.xml">
|
||||||
|
<!ENTITY sub-g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml">
|
||||||
|
<!ENTITY sub-g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml">
|
||||||
|
<!ENTITY sub-g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml">
|
||||||
|
<!ENTITY sub-g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml">
|
||||||
|
<!ENTITY sub-g-fmt SYSTEM "v4l/vidioc-g-fmt.xml">
|
||||||
|
<!ENTITY sub-g-frequency SYSTEM "v4l/vidioc-g-frequency.xml">
|
||||||
|
<!ENTITY sub-g-input SYSTEM "v4l/vidioc-g-input.xml">
|
||||||
|
<!ENTITY sub-g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml">
|
||||||
|
<!ENTITY sub-g-modulator SYSTEM "v4l/vidioc-g-modulator.xml">
|
||||||
|
<!ENTITY sub-g-output SYSTEM "v4l/vidioc-g-output.xml">
|
||||||
|
<!ENTITY sub-g-parm SYSTEM "v4l/vidioc-g-parm.xml">
|
||||||
|
<!ENTITY sub-g-priority SYSTEM "v4l/vidioc-g-priority.xml">
|
||||||
|
<!ENTITY sub-g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml">
|
||||||
|
<!ENTITY sub-g-std SYSTEM "v4l/vidioc-g-std.xml">
|
||||||
|
<!ENTITY sub-g-tuner SYSTEM "v4l/vidioc-g-tuner.xml">
|
||||||
|
<!ENTITY sub-log-status SYSTEM "v4l/vidioc-log-status.xml">
|
||||||
|
<!ENTITY sub-overlay SYSTEM "v4l/vidioc-overlay.xml">
|
||||||
|
<!ENTITY sub-qbuf SYSTEM "v4l/vidioc-qbuf.xml">
|
||||||
|
<!ENTITY sub-querybuf SYSTEM "v4l/vidioc-querybuf.xml">
|
||||||
|
<!ENTITY sub-querycap SYSTEM "v4l/vidioc-querycap.xml">
|
||||||
|
<!ENTITY sub-queryctrl SYSTEM "v4l/vidioc-queryctrl.xml">
|
||||||
|
<!ENTITY sub-querystd SYSTEM "v4l/vidioc-querystd.xml">
|
||||||
|
<!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
|
||||||
|
<!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
|
||||||
|
<!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml">
|
||||||
|
<!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml">
|
||||||
|
<!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml">
|
||||||
|
<!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml">
|
||||||
|
<!ENTITY sub-videodev2-h SYSTEM "v4l/videodev2.h.xml">
|
||||||
|
<!ENTITY sub-v4l2 SYSTEM "v4l/v4l2.xml">
|
||||||
|
<!ENTITY sub-intro SYSTEM "dvb/intro.xml">
|
||||||
|
<!ENTITY sub-frontend SYSTEM "dvb/frontend.xml">
|
||||||
|
<!ENTITY sub-isdbt SYSTEM "dvb/isdbt.xml">
|
||||||
|
<!ENTITY sub-demux SYSTEM "dvb/demux.xml">
|
||||||
|
<!ENTITY sub-video SYSTEM "dvb/video.xml">
|
||||||
|
<!ENTITY sub-audio SYSTEM "dvb/audio.xml">
|
||||||
|
<!ENTITY sub-ca SYSTEM "dvb/ca.xml">
|
||||||
|
<!ENTITY sub-net SYSTEM "dvb/net.xml">
|
||||||
|
<!ENTITY sub-kdapi SYSTEM "dvb/kdapi.xml">
|
||||||
|
<!ENTITY sub-examples SYSTEM "dvb/examples.xml">
|
||||||
|
<!ENTITY sub-dvbapi SYSTEM "dvb/dvbapi.xml">
|
||||||
|
<!ENTITY sub-media SYSTEM "media.xml">
|
||||||
|
<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">
|
||||||
|
<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
|
||||||
|
|
||||||
|
<!-- Function Reference -->
|
||||||
|
<!ENTITY close SYSTEM "v4l/func-close.xml">
|
||||||
|
<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">
|
||||||
|
<!ENTITY mmap SYSTEM "v4l/func-mmap.xml">
|
||||||
|
<!ENTITY munmap SYSTEM "v4l/func-munmap.xml">
|
||||||
|
<!ENTITY open SYSTEM "v4l/func-open.xml">
|
||||||
|
<!ENTITY poll SYSTEM "v4l/func-poll.xml">
|
||||||
|
<!ENTITY read SYSTEM "v4l/func-read.xml">
|
||||||
|
<!ENTITY select SYSTEM "v4l/func-select.xml">
|
||||||
|
<!ENTITY write SYSTEM "v4l/func-write.xml">
|
||||||
|
<!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml">
|
||||||
|
<!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml">
|
||||||
|
<!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml">
|
||||||
|
<!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
|
||||||
|
<!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
|
||||||
|
<!ENTITY sbggr16 SYSTEM "v4l/pixfmt-sbggr16.xml">
|
||||||
|
<!ENTITY sbggr8 SYSTEM "v4l/pixfmt-sbggr8.xml">
|
||||||
|
<!ENTITY sgbrg8 SYSTEM "v4l/pixfmt-sgbrg8.xml">
|
||||||
|
<!ENTITY sgrbg8 SYSTEM "v4l/pixfmt-sgrbg8.xml">
|
||||||
|
<!ENTITY uyvy SYSTEM "v4l/pixfmt-uyvy.xml">
|
||||||
|
<!ENTITY vyuy SYSTEM "v4l/pixfmt-vyuy.xml">
|
||||||
|
<!ENTITY y16 SYSTEM "v4l/pixfmt-y16.xml">
|
||||||
|
<!ENTITY y41p SYSTEM "v4l/pixfmt-y41p.xml">
|
||||||
|
<!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
|
||||||
|
<!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
|
||||||
|
<!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
|
||||||
|
<!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
|
||||||
|
<!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
|
||||||
|
<!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
|
||||||
|
<!ENTITY cropcap SYSTEM "v4l/vidioc-cropcap.xml">
|
||||||
|
<!ENTITY dbg-g-register SYSTEM "v4l/vidioc-dbg-g-register.xml">
|
||||||
|
<!ENTITY encoder-cmd SYSTEM "v4l/vidioc-encoder-cmd.xml">
|
||||||
|
<!ENTITY enum-fmt SYSTEM "v4l/vidioc-enum-fmt.xml">
|
||||||
|
<!ENTITY enum-frameintervals SYSTEM "v4l/vidioc-enum-frameintervals.xml">
|
||||||
|
<!ENTITY enum-framesizes SYSTEM "v4l/vidioc-enum-framesizes.xml">
|
||||||
|
<!ENTITY enumaudio SYSTEM "v4l/vidioc-enumaudio.xml">
|
||||||
|
<!ENTITY enumaudioout SYSTEM "v4l/vidioc-enumaudioout.xml">
|
||||||
|
<!ENTITY enuminput SYSTEM "v4l/vidioc-enuminput.xml">
|
||||||
|
<!ENTITY enumoutput SYSTEM "v4l/vidioc-enumoutput.xml">
|
||||||
|
<!ENTITY enumstd SYSTEM "v4l/vidioc-enumstd.xml">
|
||||||
|
<!ENTITY g-audio SYSTEM "v4l/vidioc-g-audio.xml">
|
||||||
|
<!ENTITY g-audioout SYSTEM "v4l/vidioc-g-audioout.xml">
|
||||||
|
<!ENTITY dbg-g-chip-ident SYSTEM "v4l/vidioc-dbg-g-chip-ident.xml">
|
||||||
|
<!ENTITY g-crop SYSTEM "v4l/vidioc-g-crop.xml">
|
||||||
|
<!ENTITY g-ctrl SYSTEM "v4l/vidioc-g-ctrl.xml">
|
||||||
|
<!ENTITY g-enc-index SYSTEM "v4l/vidioc-g-enc-index.xml">
|
||||||
|
<!ENTITY g-ext-ctrls SYSTEM "v4l/vidioc-g-ext-ctrls.xml">
|
||||||
|
<!ENTITY g-fbuf SYSTEM "v4l/vidioc-g-fbuf.xml">
|
||||||
|
<!ENTITY g-fmt SYSTEM "v4l/vidioc-g-fmt.xml">
|
||||||
|
<!ENTITY g-frequency SYSTEM "v4l/vidioc-g-frequency.xml">
|
||||||
|
<!ENTITY g-input SYSTEM "v4l/vidioc-g-input.xml">
|
||||||
|
<!ENTITY g-jpegcomp SYSTEM "v4l/vidioc-g-jpegcomp.xml">
|
||||||
|
<!ENTITY g-modulator SYSTEM "v4l/vidioc-g-modulator.xml">
|
||||||
|
<!ENTITY g-output SYSTEM "v4l/vidioc-g-output.xml">
|
||||||
|
<!ENTITY g-parm SYSTEM "v4l/vidioc-g-parm.xml">
|
||||||
|
<!ENTITY g-priority SYSTEM "v4l/vidioc-g-priority.xml">
|
||||||
|
<!ENTITY g-sliced-vbi-cap SYSTEM "v4l/vidioc-g-sliced-vbi-cap.xml">
|
||||||
|
<!ENTITY g-std SYSTEM "v4l/vidioc-g-std.xml">
|
||||||
|
<!ENTITY g-tuner SYSTEM "v4l/vidioc-g-tuner.xml">
|
||||||
|
<!ENTITY log-status SYSTEM "v4l/vidioc-log-status.xml">
|
||||||
|
<!ENTITY overlay SYSTEM "v4l/vidioc-overlay.xml">
|
||||||
|
<!ENTITY qbuf SYSTEM "v4l/vidioc-qbuf.xml">
|
||||||
|
<!ENTITY querybuf SYSTEM "v4l/vidioc-querybuf.xml">
|
||||||
|
<!ENTITY querycap SYSTEM "v4l/vidioc-querycap.xml">
|
||||||
|
<!ENTITY queryctrl SYSTEM "v4l/vidioc-queryctrl.xml">
|
||||||
|
<!ENTITY querystd SYSTEM "v4l/vidioc-querystd.xml">
|
||||||
|
<!ENTITY reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
|
||||||
|
<!ENTITY s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
|
||||||
|
<!ENTITY streamon SYSTEM "v4l/vidioc-streamon.xml">
|
|
@ -0,0 +1,85 @@
|
||||||
|
<!-- Generated file! Do not edit. -->
|
||||||
|
|
||||||
|
<index><title>List of Types</title>
|
||||||
|
<indexentry><primaryie><link linkend='v4l2-std-id'>v4l2_std_id</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-buf-type'>v4l2_buf_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-colorspace'>v4l2_colorspace</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-ctrl-type'>v4l2_ctrl_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-exposure-auto-type'>v4l2_exposure_auto_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-field'>v4l2_field</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-memory'>v4l2_memory</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-emphasis'>v4l2_mpeg_audio_emphasis</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-encoding'>v4l2_mpeg_audio_encoding</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l1-bitrate'>v4l2_mpeg_audio_l1_bitrate</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l2-bitrate'>v4l2_mpeg_audio_l2_bitrate</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-l3-bitrate'>v4l2_mpeg_audio_l3_bitrate</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode'>v4l2_mpeg_audio_mode</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-mode-extension'>v4l2_mpeg_audio_mode_extension</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-audio-sampling-freq'>v4l2_mpeg_audio_sampling_freq</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='chroma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='luma-spatial-filter-type'>v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-median-filter-type'>v4l2_mpeg_cx2341x_video_median_filter_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-spatial-filter-mode'>v4l2_mpeg_cx2341x_video_spatial_filter_mode</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-cx2341x-video-temporal-filter-mode'>v4l2_mpeg_cx2341x_video_temporal_filter_mode</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-type'>v4l2_mpeg_stream_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-stream-vbi-fmt'>v4l2_mpeg_stream_vbi_fmt</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-aspect'>v4l2_mpeg_video_aspect</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-bitrate-mode'>v4l2_mpeg_video_bitrate_mode</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-priority'>v4l2_priority</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-tuner-type'>v4l2_tuner_type</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>enum <link linkend='v4l2-preemphasis'>v4l2_preemphasis</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-audio'>v4l2_audio</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-audioout'>v4l2_audioout</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-buffer'>v4l2_buffer</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-capability'>v4l2_capability</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-captureparm'>v4l2_captureparm</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-clip'>v4l2_clip</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-control'>v4l2_control</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-crop'>v4l2_crop</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-cropcap'>v4l2_cropcap</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-dbg-chip-ident'>v4l2_dbg_chip_ident</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-dbg-match'>v4l2_dbg_match</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-dbg-register'>v4l2_dbg_register</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-enc-idx'>v4l2_enc_idx</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-enc-idx-entry'>v4l2_enc_idx_entry</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-encoder-cmd'>v4l2_encoder_cmd</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-ext-control'>v4l2_ext_control</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-ext-controls'>v4l2_ext_controls</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-fmtdesc'>v4l2_fmtdesc</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-format'>v4l2_format</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-fract'>v4l2_fract</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-framebuffer'>v4l2_framebuffer</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frequency'>v4l2_frequency</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frmival-stepwise'>v4l2_frmival_stepwise</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frmivalenum'>v4l2_frmivalenum</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frmsize-discrete'>v4l2_frmsize_discrete</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frmsize-stepwise'>v4l2_frmsize_stepwise</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-frmsizeenum'>v4l2_frmsizeenum</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-input'>v4l2_input</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-modulator'>v4l2_modulator</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-output'>v4l2_output</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-outputparm'>v4l2_outputparm</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-pix-format'>v4l2_pix_format</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-queryctrl'>v4l2_queryctrl</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-querymenu'>v4l2_querymenu</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-rect'>v4l2_rect</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-requestbuffers'>v4l2_requestbuffers</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-standard'>v4l2_standard</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-streamparm'>v4l2_streamparm</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-timecode'>v4l2_timecode</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-tuner'>v4l2_tuner</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-vbi-format'>v4l2_vbi_format</link></primaryie></indexentry>
|
||||||
|
<indexentry><primaryie>struct <link linkend='v4l2-window'>v4l2_window</link></primaryie></indexentry>
|
||||||
|
</index>
|
|
@ -0,0 +1,112 @@
|
||||||
|
<?xml version="1.0"?>
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
||||||
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
|
||||||
|
<!ENTITY % media-entities SYSTEM "./media-entities.tmpl"> %media-entities;
|
||||||
|
<!ENTITY media-indices SYSTEM "./media-indices.tmpl">
|
||||||
|
|
||||||
|
<!ENTITY eg "e. g.">
|
||||||
|
<!ENTITY ie "i. e.">
|
||||||
|
<!ENTITY fd "File descriptor returned by <link linkend='func-open'><function>open()</function></link>.">
|
||||||
|
<!ENTITY i2c "I<superscript>2</superscript>C">
|
||||||
|
<!ENTITY return-value "<title>Return Value</title><para>On success <returnvalue>0</returnvalue> is returned, on error <returnvalue>-1</returnvalue> and the <varname>errno</varname> variable is set appropriately:</para>">
|
||||||
|
<!ENTITY manvol "<manvolnum>2</manvolnum>">
|
||||||
|
|
||||||
|
<!-- Table templates: structs, structs w/union, defines. -->
|
||||||
|
<!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
|
||||||
|
<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />">
|
||||||
|
<!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />">
|
||||||
|
|
||||||
|
<!-- Video for Linux mailing list address. -->
|
||||||
|
<!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>">
|
||||||
|
|
||||||
|
<!-- LinuxTV v4l-dvb repository. -->
|
||||||
|
<!ENTITY v4l-dvb "<ulink url='http://linuxtv.org/repo/'>http://linuxtv.org/repo/</ulink>">
|
||||||
|
]>
|
||||||
|
|
||||||
|
<book id="media_api">
|
||||||
|
<bookinfo>
|
||||||
|
<title>LINUX MEDIA INFRASTRUCTURE API</title>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2009</year>
|
||||||
|
<holder>LinuxTV Developers</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
|
||||||
|
<para>Permission is granted to copy, distribute and/or modify
|
||||||
|
this document under the terms of the GNU Free Documentation License,
|
||||||
|
Version 1.1 or any later version published by the Free Software
|
||||||
|
Foundation. A copy of the license is included in the chapter entitled
|
||||||
|
"GNU Free Documentation License"</para>
|
||||||
|
</legalnotice>
|
||||||
|
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc> <!-- autogenerated -->
|
||||||
|
|
||||||
|
<preface>
|
||||||
|
<title>Introduction</title>
|
||||||
|
|
||||||
|
<para>This document covers the Linux Kernel to Userspace API's used by
|
||||||
|
video and radio straming devices, including video cameras,
|
||||||
|
analog and digital TV receiver cards, AM/FM receiver cards,
|
||||||
|
streaming capture devices.</para>
|
||||||
|
<para>It is divided into three parts.</para>
|
||||||
|
<para>The first part covers radio, capture,
|
||||||
|
cameras and analog TV devices.</para>
|
||||||
|
<para>The second part covers the
|
||||||
|
API used for digital TV and Internet reception via one of the
|
||||||
|
several digital tv standards. While it is called as DVB API,
|
||||||
|
in fact it covers several different video standards including
|
||||||
|
DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated
|
||||||
|
to documment support also for DVB-S2, ISDB-T and ISDB-S.</para>
|
||||||
|
<para>The third part covers other API's used by all media infrastructure devices</para>
|
||||||
|
<para>For additional information and for the latest development code,
|
||||||
|
see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
|
||||||
|
<para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para>
|
||||||
|
|
||||||
|
</preface>
|
||||||
|
|
||||||
|
<part id="v4l2spec">
|
||||||
|
&sub-v4l2;
|
||||||
|
</part>
|
||||||
|
<part id="dvbapi">
|
||||||
|
&sub-dvbapi;
|
||||||
|
</part>
|
||||||
|
<part id="v4ldvb_common">
|
||||||
|
<partinfo>
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>Mauro</firstname>
|
||||||
|
<surname>Chehab</surname>
|
||||||
|
<othername role="mi">Carvalho</othername>
|
||||||
|
<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
|
||||||
|
<contrib>Initial version.</contrib>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
<copyright>
|
||||||
|
<year>2009</year>
|
||||||
|
<holder>Mauro Carvalho Chehab</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<revhistory>
|
||||||
|
<!-- Put document revisions here, newest first. -->
|
||||||
|
<revision>
|
||||||
|
<revnumber>1.0.0</revnumber>
|
||||||
|
<date>2009-09-06</date>
|
||||||
|
<authorinitials>mcc</authorinitials>
|
||||||
|
<revremark>Initial revision</revremark>
|
||||||
|
</revision>
|
||||||
|
</revhistory>
|
||||||
|
</partinfo>
|
||||||
|
|
||||||
|
<title>Other API's used by media infrastructure drivers</title>
|
||||||
|
<chapter id="remote_controllers">
|
||||||
|
&sub-remote_controllers;
|
||||||
|
</chapter>
|
||||||
|
</part>
|
||||||
|
|
||||||
|
&sub-fdl-appendix;
|
||||||
|
|
||||||
|
</book>
|
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue