Project import generated by Copybara. NOKEYCHECK=True GitOrigin-RevId: d95bbe5db4ccaed056f9cda4fca5c452691ab898
diff --git a/.cocciconfig b/.cocciconfig new file mode 100644 index 0000000..43967c6 --- /dev/null +++ b/.cocciconfig
@@ -0,0 +1,3 @@ +[spatch] + options = --timeout 200 + options = --use-gitgrep
diff --git a/.get_maintainer.ignore b/.get_maintainer.ignore new file mode 100644 index 0000000..cca6d87 --- /dev/null +++ b/.get_maintainer.ignore
@@ -0,0 +1 @@ +Christoph Hellwig <hch@lst.de>
diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..89c411b --- /dev/null +++ b/.gitattributes
@@ -0,0 +1,2 @@ +*.c diff=cpp +*.h diff=cpp
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2ed4ec --- /dev/null +++ b/.gitignore
@@ -0,0 +1,116 @@ +# +# 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 +*.tar +*.gz +*.bz2 +*.lzma +*.xz +*.lz4 +*.lzo +*.patch +*.gcno +modules.builtin +Module.symvers +*.dwo +*.su +*.c.[012]*.* + +# +# Top-level generic files +# +/tags +/TAGS +/linux +/vmlinux +/vmlinux.32 +/vmlinux-gdb.py +/vmlinuz +/System.map +/Module.markers + +# +# Debian directory (make deb-pkg) +# +/debian/ + +# +# tar directory (make tar*-pkg) +# +/tar-install/ + +# +# git files that we don't want to ignore even if they are dot-files +# +!.gitignore +!.mailmap +!.cocciconfig + +# +# Generated include files +# +include/config +include/generated +arch/*/include/generated + +# stgit generated dirs +patches-* + +# quilt's files +patches +series + +# cscope files +cscope.* +ncscope.* + +# gnu global files +GPATH +GRTAGS +GSYMS +GTAGS + +# id-utils files +ID + +*.orig +*~ +\#*# + +# +# Leavings from module signing +# +extra_certificates +signing_key.pem +signing_key.priv +signing_key.x509 +x509.genkey + +# Kconfig presets +all.config + +# Kdevelop4 +*.kdev4
diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..02d2614 --- /dev/null +++ b/.mailmap
@@ -0,0 +1,172 @@ +# +# 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> +Adriana Reus <adi.reus@gmail.com> <adriana.reus@intel.com> +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> +Andrey Ryabinin <ryabinin.a.a@gmail.com> <a.ryabinin@samsung.com> +Andrew Morton <akpm@linux-foundation.org> +Andrew Vasquez <andrew.vasquez@qlogic.com> +Andy Adamson <andros@citi.umich.edu> +Antoine Tenart <antoine.tenart@free-electrons.com> +Antonio Ospite <ao2@ao2.it> <ao2@amarulasolutions.com> +Archit Taneja <archit@ti.com> +Arnaud Patard <arnaud.patard@rtp-net.org> +Arnd Bergmann <arnd@arndb.de> +Axel Dyks <xl@xlsigned.net> +Axel Lin <axel.lin@gmail.com> +Ben Gardner <bgardner@wabtec.com> +Ben M Cahill <ben.m.cahill@intel.com> +Björn Steinbrink <B.Steinbrink@gmx.de> +Boris Brezillon <boris.brezillon@free-electrons.com> +Boris Brezillon <boris.brezillon@free-electrons.com> <b.brezillon.dev@gmail.com> +Boris Brezillon <boris.brezillon@free-electrons.com> <b.brezillon@overkiz.com> +Brian Avery <b.avery@hp.com> +Brian King <brking@us.ibm.com> +Christoph Hellwig <hch@lst.de> +Christophe Ricard <christophe.ricard@gmail.com> +Corey Minyard <minyard@acm.org> +Damian Hobson-Garcia <dhobsong@igel.co.jp> +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 Rowand <frowand.list@gmail.com> <frowand@mvista.com> +Frank Rowand <frowand.list@gmail.com> <frank.rowand@am.sony.com> +Frank Rowand <frowand.list@gmail.com> <frank.rowand@sonymobile.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> +Henrik Rydberg <rydberg@bitmath.org> +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)> +Javi Merino <javi.merino@kernel.org> <javi.merino@arm.com> +<javier@osg.samsung.com> <javier.martinez@collabora.co.uk> +Jean Tourrilhes <jt@hpl.hp.com> +Jeff Garzik <jgarzik@pretzel.yyz.us> +Jens Axboe <axboe@suse.de> +Jens Osterkamp <Jens.Osterkamp@de.ibm.com> +Johan Hovold <johan@kernel.org> <jhovold@gmail.com> +Johan Hovold <johan@kernel.org> <johan@hovoldconsulting.com> +John Paul Adrian Glaubitz <glaubitz@physik.fu-berlin.de> +John Stultz <johnstul@us.ibm.com> +<josh@joshtriplett.org> <josh@freedesktop.org> +<josh@joshtriplett.org> <josh@kernel.org> +<josh@joshtriplett.org> <josht@linux.vnet.ibm.com> +<josh@joshtriplett.org> <josht@us.ibm.com> +<josh@joshtriplett.org> <josht@vnet.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> +Konstantin Khlebnikov <koct9i@gmail.com> <k.khlebnikov@samsung.com> +Koushik <raghavendra.koushik@neterion.com> +Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski@samsung.com> +Krzysztof Kozlowski <krzk@kernel.org> <k.kozlowski.k@gmail.com> +Kuninori Morimoto <kuninori.morimoto.gx@renesas.com> +Leonid I Ananiev <leonid.i.ananiev@intel.com> +Linas Vepstas <linas@austin.ibm.com> +Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@web.de> +Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch> +Mark Brown <broonie@sirena.org.uk> +Matthieu CASTET <castet.matthieu@free.fr> +Mauro Carvalho Chehab <mchehab@kernel.org> <mchehab@brturbo.com.br> +Mauro Carvalho Chehab <mchehab@kernel.org> <maurochehab@gmail.com> +Mauro Carvalho Chehab <mchehab@kernel.org> <mchehab@infradead.org> +Mauro Carvalho Chehab <mchehab@kernel.org> <mchehab@redhat.com> +Mauro Carvalho Chehab <mchehab@kernel.org> <m.chehab@samsung.com> +Mauro Carvalho Chehab <mchehab@kernel.org> <mchehab@osg.samsung.com> +Mauro Carvalho Chehab <mchehab@kernel.org> <mchehab@s-opensource.com> +Matt Ranostay <mranostay@gmail.com> Matthew Ranostay <mranostay@embeddedalley.com> +Matt Ranostay <mranostay@gmail.com> <matt.ranostay@intel.com> +Mayuresh Janorkar <mayur@ti.com> +Michael Buesch <m@bues.ch> +Michel Dänzer <michel@tungstengraphics.com> +Mitesh shah <mshah@teja.com> +Mohit Kumar <mohit.kumar@st.com> <mohit.kumar.dhaka@gmail.com> +Morten Welinder <terra@gnome.org> +Morten Welinder <welinder@anemone.rentec.com> +Morten Welinder <welinder@darter.rentec.com> +Morten Welinder <welinder@troll.com> +Mythri P K <mythripk@ti.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> +Pratyush Anand <pratyush.anand@gmail.com> <pratyush.anand@st.com> +Praveen BP <praveenbp@ti.com> +Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com> +Rajesh Shah <rajesh.shah@intel.com> +Ralf Baechle <ralf@linux-mips.org> +Ralf Wildenhues <Ralf.Wildenhues@gmx.de> +Randy Dunlap <rdunlap@infradead.org> <rdunlap@xenotime.net> +Rémi Denis-Courmont <rdenis@simphalempin.com> +Ricardo Ribalda Delgado <ricardo.ribalda@gmail.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> +Santosh Shilimkar <ssantosh@kernel.org> +Santosh Shilimkar <santosh.shilimkar@oracle.org> +Sascha Hauer <s.hauer@pengutronix.de> +S.Çağlar Onur <caglar@pardus.org.tr> +Shiraz Hashim <shiraz.linux.kernel@gmail.com> <shiraz.hashim@st.com> +Shuah Khan <shuah@kernel.org> <shuahkhan@gmail.com> +Shuah Khan <shuah@kernel.org> <shuah.khan@hp.com> +Shuah Khan <shuah@kernel.org> <shuahkh@osg.samsung.com> +Shuah Khan <shuah@kernel.org> <shuah.kh@samsung.com> +Simon Kelley <simon@thekelleys.org.uk> +Stéphane Witzmann <stephane.witzmann@ubpmes.univ-bpclermont.fr> +Stephen Hemminger <shemminger@osdl.org> +Sudeep Holla <sudeep.holla@arm.com> Sudeep KarkadaNagesha <sudeep.karkadanagesha@arm.com> +Sumit Semwal <sumit.semwal@ti.com> +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> +Viresh Kumar <vireshk@kernel.org> <viresh.kumar@st.com> +Viresh Kumar <vireshk@kernel.org> <viresh.linux@gmail.com> +Viresh Kumar <vireshk@kernel.org> <viresh.kumar2@arm.com> +Vlad Dogaru <ddvlad@gmail.com> <vlad.dogaru@intel.com> +Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@virtuozzo.com> +Vladimir Davydov <vdavydov.dev@gmail.com> <vdavydov@parallels.com> +Takashi YOSHII <takashi.yoshii.zj@renesas.com> +Yusuke Goda <goda.yusuke@renesas.com> +Gustavo Padovan <gustavo@las.ic.unicamp.br> +Gustavo Padovan <padovan@profusion.mobi>
diff --git a/COPYING b/COPYING new file mode 100644 index 0000000..ca442d3 --- /dev/null +++ b/COPYING
@@ -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.
diff --git a/CREDITS b/CREDITS new file mode 100644 index 0000000..d7ebdfb --- /dev/null +++ b/CREDITS
@@ -0,0 +1,4129 @@ + This is at least a partial credits-file of people that have + contributed to the Linux project. It is sorted by name and + formatted to allow easy grepping and beautification by + scripts. The fields are: name (N), email (E), web-address + (W), PGP key ID and fingerprint (P), description (D), and + snail-mail address (S). + Thanks, + + Linus +---------- + +N: Matt Mackal +E: mpm@selenic.com +D: SLOB slab allocator + +N: Matti Aarnio +E: mea@nic.funet.fi +D: Alpha systems hacking, IPv6 and other network related stuff +D: One of assisting postmasters for vger.kernel.org's lists +S: (ask for current address) +S: Finland + +N: Thomas Abraham +E: thomas.ab@samsung.com +D: Samsung pin controller driver + +N: Dragos Acostachioaie +E: dragos@iname.com +W: http://www.arbornet.org/~dragos +D: /proc/sysvipc +S: C. Negri 6, bl. D3 +S: Iasi 6600 +S: Romania + +N: Mark Adler +E: madler@alumni.caltech.edu +W: http://alumnus.caltech.edu/~madler/ +D: zlib decompression + +N: Monalisa Agrawal +E: magrawal@nortelnetworks.com +D: Basic Interphase 5575 driver with UBR and ABR support. +S: 75 Donald St, Apt 42 +S: Weymouth, MA 02188 +S: USA + +N: Dave Airlie +E: airlied@linux.ie +W: http://www.csn.ul.ie/~airlied +D: NFS over TCP patches +D: in-kernel DRM Maintainer +S: Longford, Ireland +S: Sydney, Australia + +N: Tigran A. Aivazian +E: tigran@aivazian.fsnet.co.uk +W: http://www.moses.uklinux.net/patches +D: BFS filesystem +D: Intel IA32 CPU microcode update support +D: Various kernel patches +S: United Kingdom + +N: Werner Almesberger +E: werner@almesberger.net +W: http://www.almesberger.net/ +D: dosfs, LILO, some fd features, ATM, various other hacks here and there +S: Buenos Aires +S: Argentina + +N: Tim Alpaerts +E: tim_alpaerts@toyota-motor-europe.com +D: 802.2 class II logical link control layer, +D: the humble start of an opening towards the IBM SNA protocols +S: Klaproosstraat 72 c 10 +S: B-2610 Wilrijk-Antwerpen +S: Belgium + +N: Anton Altaparmakov +E: aia21@cantab.net +W: http://www-stu.christs.cam.ac.uk/~aia21/ +D: Author of new NTFS driver, various other kernel hacks. +S: Christ's College +S: Cambridge CB2 3BU +S: United Kingdom + +N: C. Scott Ananian +E: cananian@alumni.princeton.edu +W: http://www.pdos.lcs.mit.edu/~cananian +P: 1024/85AD9EED AD C0 49 08 91 67 DF D7 FA 04 1A EE 09 E8 44 B0 +D: Unix98 pty support. +D: APM update to 1.2 spec. +D: /devfs hacking. +S: 7 Kiwi Loop +S: Howell, NJ 07731 +S: USA + +N: Erik Andersen +E: andersen@codepoet.org +W: http://www.codepoet.org/ +P: 1024D/30D39057 1BC4 2742 E885 E4DE 9301 0C82 5F9B 643E 30D3 9057 +D: Maintainer of ide-cd and Uniform CD-ROM driver, +D: ATAPI CD-Changer support, Major 2.1.x CD-ROM update. +S: 352 North 525 East +S: Springville, Utah 84663 +S: USA + +N: Michael Ang +E: mang@subcarrier.org +W: http://www.subcarrier.org/mang +D: Linux/PA-RISC hacker +S: 85 Frank St. +S: Ottawa, Ontario +S: Canada K2P 0X3 + +N: H. Peter Anvin +E: hpa@zytor.com +W: http://www.zytor.com/~hpa/ +P: 2047/2A960705 BA 03 D3 2C 14 A8 A8 BD 1E DF FE 69 EE 35 BD 74 +D: Author of the SYSLINUX boot loader, maintainer of the linux.* news +D: hierarchy and the Linux Device List; various kernel hacks +S: 4390 Albany Drive #46 +S: San Jose, California 95129 +S: USA + +N: Andrea Arcangeli +E: andrea@suse.de +W: http://www.kernel.org/pub/linux/kernel/people/andrea/ +P: 1024D/68B9CB43 13D9 8355 295F 4823 7C49 C012 DFA1 686E 68B9 CB43 +P: 1024R/CB4660B9 CC A0 71 81 F4 A0 63 AC C0 4B 81 1D 8C 15 C8 E5 +D: Parport hacker +D: Implemented a workaround for some interrupt buggy printers +D: Author of pscan that helps to fix lp/parport bugs +D: Author of lil (Linux Interrupt Latency benchmark) +D: Fixed the shm swap deallocation at swapoff time (try_to_unuse message) +D: VM hacker +D: Various other kernel hacks +S: Imola 40026 +S: Italy + +N: Derek Atkins +E: warlord@MIT.EDU +D: Linux-AFS Port, random kernel hacker, +D: VFS fixes (new notify_change in particular) +D: Moving all VFS access checks into the file systems +S: MIT Room E15-341 +S: 20 Ames Street +S: Cambridge, Massachusetts 02139 +S: USA + +N: Michel Aubry +E: giovanni <giovanni@sudfr.com> +D: Aladdin 1533/1543(C) chipset IDE +D: VIA MVP-3/TX Pro III chipset IDE + +N: Jens Axboe +E: axboe@suse.de +D: Linux CD-ROM maintainer, DVD support +D: elevator + block layer rewrites +D: highmem I/O support +D: misc hacking on IDE, SCSI, block drivers, etc +S: Peter Bangs Vej 258, 2TH +S: 2500 Valby +S: Denmark + +N: John Aycock +E: aycock@cpsc.ucalgary.ca +D: Adaptec 274x driver +S: Department of Computer Science +S: University of Calgary +S: Calgary, Alberta +S: Canada + +N: Miles Bader +E: miles@gnu.org +D: v850 port (uClinux) +S: NEC Corporation +S: 1753 Shimonumabe, Nakahara-ku +S: Kawasaki 211-8666 +S: Japan + +N: Ralf Baechle +E: ralf@gnu.org +P: 1024/AF7B30C1 CF 97 C2 CC 6D AE A7 FE C8 BA 9C FC 88 DE 32 C3 +D: Linux/MIPS port +D: Linux/68k hacker +S: Hauptstrasse 19 +S: 79837 St. Blasien +S: Germany + +N: Krishna Balasubramanian +E: balasub@cis.ohio-state.edu +D: Wrote SYS V IPC (part of standard kernel since 0.99.10) + +N: Chris Ball +E: chris@printf.net +D: Former maintainer of the MMC/SD/SDIO subsystem. + +N: Dario Ballabio +E: ballabio_dario@emc.com +E: dario.ballabio@tiscalinet.it +E: dario.ballabio@inwind.it +D: Author and maintainer of the Ultrastor 14F/34F SCSI driver +D: Author and maintainer of the EATA ISA/EISA/PCI SCSI driver +S: EMC Corporation +S: Milano +S: Italy + +N: Paul Bame +E: bame@debian.org +E: bame@puffin.external.hp.com +E: paul_bame@hp.com +W: http://www.parisc-linux.org +D: PA-RISC 32 and 64-bit early boot, firmware interface, interrupts, misc +S: MS42 +S: Hewlett-Packard +S: 3404 E Harmony Rd +S: Fort Collins, CO 80525 +S: USA + +N: Arindam Banerji +E: axb@cse.nd.edu +D: Contributed ESDI driver routines needed to port LINUX to the PS/2 MCA. +S: Department of Computer Science & Eng. +S: University of Notre Dame +S: Notre Dame, Indiana +S: USA + +N: Greg Banks +E: gnb@alphalink.com.au +D: IDT77105 ATM network driver +D: some SuperH port work +D: some trivial futzing with kconfig + +N: James Banks +E: james@sovereign.org +D: TLAN network driver +D: Logitech Busmouse driver + +N: Krzysztof G. Baranowski +E: kgb@manjak.knm.org.pl +P: 1024/FA6F16D1 96 D1 1A CF 5F CA 69 EC F9 4F 36 1F 6D 60 7B DA +D: Maintainer of the System V file system. +D: System V fs update for 2.1.x dcache. +D: Forward ported a couple of SCSI drivers. +D: Various bugfixes. +S: ul. Koscielna 12a +S: 62-300 Wrzesnia +S: Poland + +N: Fred Barnes +E: frmb2@ukc.ac.uk +D: Various parport/ppdev hacks and fixes +S: Computing Lab, The University +S: Canterbury, KENT +S: CT2 7NF +S: England + +N: Paul Barton-Davis +E: pbd@op.net +D: Driver for WaveFront soundcards (Turtle Beach Maui, Tropez, Tropez+) +D: Various bugfixes and changes to sound drivers +S: USA + +N: Carlos Henrique Bauer +E: chbauer@acm.org +E: bauer@atlas.unisinos.br +D: Some new sysctl entries for the parport driver. +D: New sysctl function for handling unsigned longs +S: Universidade do Vale do Rio dos Sinos - UNISINOS +S: DSI/IDASI +S: Av. Unisinos, 950 +S: 93022000 Sao Leopoldo RS +S: Brazil + +N: Peter Bauer +E: 100136.3530@compuserve.com +D: Driver for depca-ethernet-board +S: 69259 Wilhemsfeld +S: Rainweg 15 +S: Germany + +N: Fred Baumgarten +E: dc6iq@insl1.etec.uni-karlsruhe.de +E: dc6iq@adacom.org +E: dc6iq@db0ais.#hes.deu.eu (packet radio) +D: NET-2 & netstat(8) +S: Soevener Strasse 11 +S: 53773 Hennef +S: Germany + +N: Donald Becker +E: becker@cesdis.gsfc.nasa.gov +D: General low-level networking hacker +D: Most of the ethercard drivers +D: Original author of the NFS server +S: USRA Center of Excellence in Space Data and Information Sciences +S: Code 930.5, Goddard Space Flight Center +S: Greenbelt, Maryland 20771 +S: USA + +N: Adam Belay +E: ambx1@neo.rr.com +D: Linux Plug and Play Support +S: USA + +N: Daniele Bellucci +E: bellucda@tiscali.it +D: Various Janitor work. +W: http://web.tiscali.it/bellucda +S: Via Delle Palme, 9 +S: Terni 05100 +S: Italy + +N: Krzysztof Benedyczak +E: golbi@mat.uni.torun.pl +W: http://www.mat.uni.torun.pl/~golbi +D: POSIX message queues fs (with M. Wronski) +S: ul. Podmiejska 52 +S: Radunica +S: 83-000 Pruszcz Gdanski +S: Poland + +N: Randolph Bentson +E: bentson@grieg.seaslug.org +W: http://www.aa.net/~bentson/ +P: 1024/39ED5729 5C A8 7A F4 B2 7A D1 3E B5 3B 81 CF 47 30 11 71 +D: Author of driver for Cyclom-Y and Cyclades-Z async mux +S: 2322 37th Ave SW +S: Seattle, Washington 98126-2010 +S: USA + +N: Muli Ben-Yehuda +E: mulix@mulix.org +E: muli@il.ibm.com +W: http://www.mulix.org +D: trident OSS sound driver, x86-64 dma-ops and Calgary IOMMU, +D: KVM and Xen bits and other misc. hackery. +S: Haifa, Israel + +N: Johannes Berg +E: johannes@sipsolutions.net +W: http://johannes.sipsolutions.net/ +P: 4096R/7BF9099A C0EB C440 F6DA 091C 884D 8532 E0F3 73F3 7BF9 099A +D: powerpc & 802.11 hacker + +N: Stephen R. van den Berg (AKA BuGless) +E: berg@pool.informatik.rwth-aachen.de +D: General kernel, gcc, and libc hacker +D: Specialisation: tweaking, ensuring portability, tweaking, cleaning, +D: tweaking and occasionally debugging :-) +S: Bouwensstraat 22 +S: 6369 BG Simpelveld +S: The Netherlands + +N: Peter Berger +E: pberger@brimson.com +W: http://www.brimson.com +D: Author/maintainer of Digi AccelePort USB driver +S: 1549 Hiironen Rd. +S: Brimson, MN 55602 +S: USA + +N: Hennus Bergman +P: 1024/77D50909 76 99 FD 31 91 E1 96 1C 90 BB 22 80 62 F6 BD 63 +D: Author and maintainer of the QIC-02 tape driver +S: The Netherlands + +N: Tomas Berndtsson +E: tomas@nocrew.org +W: http://tomas.nocrew.org/ +D: dsp56k device driver + +N: Ross Biro +E: ross.biro@gmail.com +D: Original author of the Linux networking code + +N: Anton Blanchard +E: anton@samba.org +W: http://samba.org/~anton/ +P: 1024/8462A731 4C 55 86 34 44 59 A7 99 2B 97 88 4A 88 9A 0D 97 +D: sun4 port, Sparc hacker + +N: Hugh Blemings +E: hugh@blemings.org +W: http://blemings.org/hugh +D: Original author of the Keyspan USB to serial drivers, random PowerPC hacker +S: PO Box 234 +S: Belconnen ACT 2616 +S: Australia + +N: Philip Blundell +E: philb@gnu.org +D: Linux/ARM hacker +D: Device driver hacker (eexpress, 3c505, c-qcam, ...) +D: m68k port to HP9000/300 +D: AUN network protocols +D: Co-architect of the parallel port sharing system +D: IPv6 netfilter +S: FutureTV Labs Ltd +S: Brunswick House, 61-69 Newmarket Rd, Cambridge CB5 8EG +S: United Kingdom + +N: Thomas Bogendörfer +E: tsbogend@alpha.franken.de +D: PCnet32 driver, SONIC driver, JAZZ_ESP driver +D: newport abscon driver, g364 framebuffer driver +D: strace for Linux/Alpha +D: Linux/MIPS hacker +S: Schafhofstr. 40 +S: 90556 Cadolzburg +S: Germany + +N: Bill Bogstad +E: bogstad@pobox.com +D: wrote /proc/self hack, minor samba & dosemu patches + +N: Axel Boldt +E: axel@uni-paderborn.de +W: http://math-www.uni-paderborn.de/~axel/ +D: Configuration help text support +D: Linux CD and Support Giveaway List + +N: Erik Inge Bolsø +E: knan@mo.himolde.no +D: Misc kernel hacks +D: Updated PC speaker driver for 2.3 +S: Norway + +N: Andreas E. Bombe +E: andreas.bombe@munich.netsurf.de +W: http://home.pages.de/~andreas.bombe/ +P: 1024/04880A44 72E5 7031 4414 2EB6 F6B4 4CBD 1181 7032 0488 0A44 +D: IEEE 1394 subsystem rewrite and maintainer +D: Texas Instruments PCILynx IEEE 1394 driver + +N: Al Borchers +E: alborchers@steinerpoint.com +D: Author/maintainer of Digi AccelePort USB driver +D: work on usbserial and keyspan_pda drivers +S: 4912 Zenith Ave. S. +S: Minneapolis, MN 55410 +S: USA + +N: Marc Boucher +E: marc@mbsi.ca +P: CA 67 A5 1A 38 CE B6 F2 D5 83 51 03 D2 9C 30 9E CE D2 DD 65 +D: Netfilter core +D: IP policy routing by mark +D: Various fixes (mostly networking) +S: Montreal, Quebec +S: Canada + +N: Zoltán Böszörményi +E: zboszor@mail.externet.hu +D: MTRR emulation with Cyrix style ARR registers, Athlon MTRR support + +N: John Boyd +E: boyd@cis.ohio-state.edu +D: Co-author of wd7000 SCSI driver +S: 101 Curl Drive #591 +S: Columbus, Ohio 43210 +S: USA + +N: Peter Braam +E: braam@clusterfs.com +W: http://www.clusterfs.com/ +D: Coda & InterMezzo filesystems +S: 181 McNeil +S: Canmore, AB +S: Canada, T1W 2R9 + +N: Ryan Bradetich +E: rbradetich@uswest.net +D: Linux/PA-RISC hacker +S: 1200 Goldenrod Dr. +S: Nampa, Idaho 83686 +S: USA + +N: Dirk J. Brandewie +E: dirk.j.brandewie@intel.com +E: linux-wimax@intel.com +D: Intel Wireless WiMAX Connection 2400 SDIO driver + +N: Derrick J. Brashear +E: shadow@dementia.org +W: http://www.dementia.org/~shadow +P: 512/71EC9367 C5 29 0F BC 83 51 B9 F0 BC 05 89 A0 4F 1F 30 05 +D: Author of Sparc CS4231 audio driver, random Sparc work +S: 403 Gilmore Avenue +S: Trafford, Pennsylvania 15085 +S: USA + +N: Dag Brattli +E: dagb@cs.uit.no +W: http://www.cs.uit.no/~dagb +D: IrDA Subsystem +S: 19. Wellington Road +S: Lancaster, LA1 4DN +S: UK, England + +N: Lars Brinkhoff +E: lars@nocrew.org +W: http://lars.nocrew.org/ +D: dsp56k device driver +D: ptrace proxy in user mode kernel port +S: Kopmansg 2 +S: 411 13 Goteborg +S: Sweden + +N: Paul Bristow +E: paul@paulbristow.net +W: http://paulbristow.net/linux/idefloppy.html +D: Maintainer of IDE/ATAPI floppy driver + +N: Stefano Brivio +E: stefano.brivio@polimi.it +D: Broadcom B43 driver + +N: Dominik Brodowski +E: linux@brodo.de +W: http://www.brodo.de/ +P: 1024D/725B37C6 190F 3E77 9C89 3B6D BECD 46EE 67C3 0308 725B 37C6 +D: parts of CPUFreq code, ACPI bugfixes, PCMCIA rewrite, cpufrequtils +S: Tuebingen, Germany + +N: Andries Brouwer +E: aeb@cwi.nl +D: random Linux hacker +S: Bessemerstraat 21 +S: Amsterdam +S: The Netherlands + +N: NeilBrown +E: neil@brown.name +P: 4096R/566281B9 1BC6 29EB D390 D870 7B5F 497A 39EC 9EDD 5662 81B9 +D: NFSD Maintainer 2000-2007 +D: MD Maintainer 2001-2016 + +N: Zach Brown +E: zab@zabbo.net +D: maestro pci sound + +N: David Brownell +D: Kernel engineer, mentor, and friend. Maintained USB EHCI and +D: gadget layers, SPI subsystem, GPIO subsystem, and more than a few +D: device drivers. His encouragement also helped many engineers get +D: started working on the Linux kernel. David passed away in early +D: 2011, and will be greatly missed. +W: https://lkml.org/lkml/2011/4/5/36 + +N: Gary Brubaker +E: xavyer@ix.netcom.com +D: USB Serial Empeg Empeg-car Mark I/II Driver + +N: Matthias Bruestle +E: m@mbsks.franken.de +D: REINER SCT cyberJack pinpad/e-com USB chipcard reader driver +S: Germany + +N: Adrian Bunk +P: 1024D/4F12B400 B29C E71E FE19 6755 5C8A 84D4 99FC EA98 4F12 B400 +D: misc kernel hacking and testing + +N: Ray Burr +E: ryb@nightmare.com +D: Original author of Amiga FFS filesystem +S: Orlando, Florida +S: USA + +N: Lennert Buytenhek +E: kernel@wantstofly.org +D: Original (2.4) rewrite of the ethernet bridging code +D: Various ARM bits and pieces +S: Ravenhorst 58 +S: 2317 AK Leiden +S: The Netherlands + +N: Michael Callahan +E: callahan@maths.ox.ac.uk +D: PPP for Linux +S: The Mathematical Institute +S: 25-29 St Giles +S: Oxford +S: United Kingdom + +N: Luiz Fernando N. Capitulino +E: lcapitulino@mandriva.com.br +E: lcapitulino@gmail.com +W: http://www.cpu.eti.br +D: misc kernel hacking +S: Mandriva +S: Brazil + +N: Remy Card +E: Remy.Card@masi.ibp.fr +E: Remy.Card@linux.org +D: Extended file system [defunct] designer and developer +D: Second extended file system designer and developer +S: Institut Blaise Pascal +S: 4 Place Jussieu +S: 75252 Paris Cedex 05 +S: France + +N: Ulf Carlsson +D: SGI Indy audio (HAL2) drivers +E: ulfc@bun.falkenberg.se + +N: Ed Carp +E: ecarp@netcom.com +D: uucp, elm, pine, pico port +D: cron, at(1) developer +S: 48287 Sawleaf +S: Fremont, California 94539 +S: USA + +N: Florent Chabaud +E: florent.chabaud@polytechnique.org +D: software suspend +S: SGDN/DCSSI/SDS/LTI +S: 58, Bd Latour-Maubourg +S: 75700 Paris 07 SP +S: France + +N: Gordon Chaffee +E: chaffee@cs.berkeley.edu +W: http://bmrc.berkeley.edu/people/chaffee/ +D: vfat, fat32, joliet, native language support +S: 3700 Warwick Road +S: Fremont, California 94555 +S: USA + +N: Chih-Jen Chang +E: chihjenc@scf.usc.edu +E: chihjen@iis.sinica.edu.tw +D: IGMP(Internet Group Management Protocol) version 2 +S: 3F, 65 Tajen street +S: Tamsui town, Taipei county, +S: Taiwan 251 +S: Republic of China + +N: Reinette Chatre +E: reinette.chatre@intel.com +D: WiMedia Link Protocol implementation +D: UWB stack bits and pieces + +N: Michael Elizabeth Chastain +E: mec@shout.net +D: Configure, Menuconfig, xconfig + +N: Mauro Carvalho Chehab +E: m.chehab@samsung.org +E: mchehab@osg.samsung.com +E: mchehab@infradead.org +D: Media subsystem (V4L/DVB) drivers and core +D: EDAC drivers and EDAC 3.0 core rework +S: Brazil + +N: Raymond Chen +E: raymondc@microsoft.com +D: Author of Configure script +S: 14509 NE 39th Street #1096 +S: Bellevue, Washington 98007 +S: USA + +N: Chris Cheney +E: chris.cheney@gmail.com +E: ccheney@redhat.com +P: 1024D/8E384AF2 2D31 1927 87D7 1F24 9FF9 1BC5 D106 5AB3 8E38 4AF2 +D: Vista Imaging usb webcam driver +S: 2308 Therrell Way +S: McKinney, TX 75070 +S: USA + +N: Stuart Cheshire +E: cheshire@cs.stanford.edu +D: Author of Starmode Radio IP (STRIP) driver +D: Originator of design for new combined interrupt handlers +S: William Gates Department +S: Stanford University +S: Stanford, California 94305 +S: USA + +N: Carlos Chinea +E: carlos.chinea@nokia.com +E: cch.devel@gmail.com +D: Author of HSI Subsystem + +N: Randolph Chung +E: tausq@debian.org +D: Linux/PA-RISC hacker +S: Hong Kong + +N: Juan Jose Ciarlante +W: http://juanjox.kernelnotes.org/ +E: jjciarla@raiz.uncu.edu.ar +E: jjo@mendoza.gov.ar +D: Network driver alias support +D: IP masq hashing and app modules +D: IP masq 2.1 features and bugs +S: Las Cuevas 2385 - Bo Guemes +S: Las Heras, Mendoza CP 5539 +S: Argentina + +N: Steven P. Cole +E: scole@lanl.gov +E: elenstev@mesatop.com +D: Various build fixes and kernel documentation. +S: Los Alamos, New Mexico +S: USA + +N: Hamish Coleman +E: hamish@zot.apana.org.au +D: SEEQ8005 network driver +S: 98 Paxton Street +S: East Malvern, Victoria, 3145 +S: Australia + +N: Neil Conway +E: nconway.list@ukaea.org.uk +D: Assorted sched/mm titbits +S: Oxfordshire, UK. + +N: Kees Cook +E: kees@outflux.net +E: kees@ubuntu.com +E: keescook@chromium.org +W: http://outflux.net/blog/ +P: 4096R/DC6DC026 A5C3 F68F 229D D60F 723E 6E13 8972 F4DF DC6D C026 +D: Various security things, bug fixes, and documentation. +S: (ask for current address) +S: Portland, Oregon +S: USA + +N: Robin Cornelius +E: robincornelius@users.sourceforge.net +D: Ralink rt2x00 WLAN driver +S: Cornwall, U.K. + +N: Mark Corner +E: mcorner@umich.edu +W: http://www.eecs.umich.edu/~mcorner/ +D: USB Bluetooth Driver +S: University of Michigan +S: Ann Arbor, MI + +N: Michael Cornwell +E: cornwell@acm.org +D: Original designer and co-author of ATA Taskfile +D: Kernel module SMART utilities +S: Santa Cruz, California +S: USA + +N: Luis Correia +E: lfcorreia@users.sf.net +D: Ralink rt2x00 WLAN driver +S: Belas, Portugal + +N: Alan Cox +W: http://www.linux.org.uk/diary/ +D: Linux Networking (0.99.10->2.0.29) +D: Original Appletalk, AX.25, and IPX code +D: 3c501 hacker +D: Watchdog timer drivers +D: Linux/SMP x86 (up to 2.0 only) +D: Initial Mac68K port +D: Video4Linux design, bw-qcam and PMS driver ports. +D: IDE modularisation work +D: Z85230 driver +D: Former security contact point (please use vendor-sec@lst.de) +D: ex 2.2 maintainer +D: 2.1.x modular sound +D: Assigned major/minor numbers maintainer at lanana.org +S: c/o Red Hat UK Ltd +S: Alexandra House +S: Alexandra Terrace +S: Guildford, GU1 3DA +S: United Kingdom + +N: Cristian Mihail Craciunescu +W: http://www.dnt.ro/~cristi/ +E: cristi@dnt.ro +D: Support for Xircom PGSDB9 (firmware and host driver) +S: Bucharest +S: Romania + +N: Laurence Culhane +E: loz@holmes.demon.co.uk +D: Wrote the initial alpha SLIP code +S: 81 Hood Street +S: Northampton +S: NN1 3QT +S: United Kingdom + +N: Massimo Dal Zotto +E: dz@debian.org +D: i8k Dell laptop SMM driver + +N: Uwe Dannowski +E: Uwe.Dannowski@ira.uka.de +W: http://i30www.ira.uka.de/~dannowsk/ +D: FORE PCA-200E driver +S: University of Karlsruhe +S: Germany + +N: Ray Dassen +E: jdassen@wi.LeidenUniv.nl +W: http://www.wi.leidenuniv.nl/~jdassen/ +P: 1024/672D05C1 DD 60 32 60 F7 90 64 80 E7 6F D4 E4 F8 C9 4A 58 +D: Debian GNU/Linux: www.debian.org maintainer, FAQ co-maintainer, +D: packages testing, nit-picking & fixing. Enjoying BugFree (TM) kernels. +S: Zuidsingel 10A +S: 2312 SB Leiden +S: The Netherlands + +N: David Davies +E: davies@wanton.lkg.dec.com +D: Network driver author - depca, ewrk3 and de4x5 +D: Wrote shared interrupt support +S: Digital Equipment Corporation +S: 550 King Street +S: Littleton, Massachusetts 01460 +S: USA + +N: Frank Davis +E: fdavis@si.rr.com +E: fdavis112@juno.com +D: Various kernel patches +S: 8 Lakeview Terr. +S: Kerhonkson, NY 12446 +S: USA + +N: Wayne Davison +E: davison@borland.com +D: Second extended file system co-designer + +N: Terry Dawson +E: terry@perf.no.itg.telecom.com.au +E: terry@albert.vk2ktj.ampr.org (Amateur Radio use only) +D: trivial hack to add variable address length routing to Rose. +D: AX25-HOWTO, HAM-HOWTO, IPX-HOWTO, NET-2-HOWTO +D: ax25-utils maintainer. + +N: Helge Deller +E: deller@gmx.de +E: hdeller@redhat.de +D: PA-RISC Linux hacker, LASI-, ASP-, WAX-, LCD/LED-driver +S: Schimmelsrain 1 +S: D-69231 Rauenberg +S: Germany + +N: Jean Delvare +E: jdelvare@suse.de +W: http://jdelvare.nerim.net/ +D: Several hardware monitoring drivers +S: France + +N: Peter Denison +E: peterd@pnd-pc.demon.co.uk +W: http://www.pnd-pc.demon.co.uk/promise/ +D: Promise DC4030VL caching HD controller drivers + +N: Todd J. Derr +E: tjd@fore.com +W: http://www.wordsmith.org/~tjd +D: Random console hacks and other miscellaneous stuff +S: 3000 FORE Drive +S: Warrendale, Pennsylvania 15086 +S: USA + +N: Martin Devera +E: devik@cdi.cz +W: http://luxik.cdi.cz/~devik/qos/ +D: HTB qdisc and random networking hacks + +N: Alex deVries +E: alex@onefishtwo.ca +D: Various SGI parts, bits of HAL2 and Newport, PA-RISC Linux. +S: 41.5 William Street +S: Ottawa, Ontario +S: K1N 6Z9 +S: CANADA + +N: Jeff Dike +E: jdike@karaya.com +W: http://user-mode-linux.sourceforge.net +D: User mode kernel port +S: 375 Tubbs Hill Rd +S: Deering NH 03244 +S: USA + +N: Matt Domsch +E: Matt_Domsch@dell.com +W: http://www.dell.com/linux +W: http://domsch.com/linux +D: Linux/IA-64 +D: Dell PowerEdge server, SCSI layer, misc drivers, and other patches +S: Dell Inc. +S: One Dell Way +S: Round Rock, TX 78682 +S: USA + +N: Mattia Dongili +E: malattia@gmail.com +D: cpufrequtils (precursor to cpupowerutils) + +N: Ben Dooks +E: ben-linux@fluff.org +E: ben@simtec.co.uk +W: http://www.fluff.org/ben/ +W: http://www.simtec.co.uk/ +D: Samsung S3C2410/S3C2440 support, general ARM support +D: Maintaining Simtec Electronics development boards +S: Simtec Electronics +S: Avondale Drive +S: Tarleton +S: Preston +S: Lancs +S: PR4 6AX +S: United Kingdom + +N: Ivo van Doorn +E: IvDoorn@gmail.com +W: http://www.mendiosus.nl +D: Ralink rt2x00 WLAN driver +S: Haarlem, The Netherlands + +N: John G Dorsey +E: john+@cs.cmu.edu +D: ARM Linux ports to Assabet/Neponset, Spot +S: Department of Electrical and Computer Engineering +S: Carnegie Mellon University +S: Pittsburgh, PA 15213 +S: USA + +N: Eddie C. Dost +E: ecd@skynet.be +D: Linux/Sparc kernel hacker +D: Linux/Sparc maintainer +S: Rue de la Chapelle 51 +S: 4850 Moresnet +S: Belgium + +N: Cort Dougan +E: cort@fsmlabs.com +W: http://www.fsmlabs.com/linuxppcbk.html +D: PowerPC + +N: Daniel Drake +E: dsd@gentoo.org +D: USBAT02 CompactFlash support in usb-storage +S: UK + +N: Oleg Drokin +E: green@ccssu.crimea.ua +W: http://www.ccssu.crimea.ua/~green +D: Cleaning up sound drivers, SA1100 Watchdog. +S: Skvoznoy per., 14a +S: Evpatoria +S: Crimea +S: UKRAINE, 334320 + +N: Walt Drummond +E: drummond@valinux.com +D: Linux/IA-64 +S: 1382 Bordeaux Drive +S: Sunnyvale, CA 94087 +S: USA + +N: Bruno Ducrot +E: ducrot@poupinou.org +D: CPUFreq and ACPI bugfixes. +S: Mougin, France + +N: Don Dugger +E: n0ano@valinux.com +D: Linux/IA-64 +S: 1209 Pearl Street, #12 +S: Boulder, CO 80302 +S: USA + +N: Thomas Dunbar +E: tdunbar@vt.edu +D: TeX & METAFONT hacking/maintenance +S: Virginia Tech Computing Center +S: 1700 Pratt Drive +S: Blacksburg, Virginia 24061 +S: USA + +N: Randy Dunlap +E: rdunlap@infradead.org +W: http://www.infradead.org/~rdunlap/ +D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers +D: x86 SMP, ACPI, bootflag hacking +D: documentation, builds +S: (ask for current address) +S: USA + +N: Bob Dunlop +E: rjd@xyzzy.clara.co.uk +E: bob.dunlop@farsite.co.uk +W: www.farsite.co.uk +D: FarSync card device driver +S: FarSite Communications Ltd +S: Tempus Business Centre +S: 60 Kingsclere Road +S: Basingstoke RG21 6XG +S: UK + +N: Cyrus Durgin +E: cider@speakeasy.org +W: http://www.speakeasy.org/~cider/ +D: implemented kmod + +N: Torsten Duwe +E: Torsten.Duwe@informatik.uni-erlangen.de +D: Part-time kernel hacker +D: The Linux Support Team Erlangen +S: Grevenbroicher Str. 17 +S: 47807 Krefeld +S: Germany + +N: Tom Dyas +E: tdyas@eden.rutgers.edu +D: minor hacks and some sparc port stuff +S: New Jersey +S: USA + +N: Drew Eckhardt +E: drew@PoohSticks.ORG +D: SCSI code +D: Assorted snippets elsewhere +D: Boot sector "..." printing +S: 2037 Walnut #6 +S: Boulder, Colorado 80302 +S: USA + +N: Heiko Eißfeldt +E: heiko@colossus.escape.de heiko@unifix.de +D: verify_area stuff, generic SCSI fixes +D: SCSI Programming HOWTO +D: POSIX.1 compliance testing +S: Unifix Software GmbH +S: Bueltenweg 27a +S: D-38106 Braunschweig +S: Germany + +N: Bjorn Ekwall +E: bj0rn@blox.se +W: http://www.pi.se/blox/ +D: Extended support for loadable modules +D: D-Link pocket adapter drivers +S: Brevia 1043 +S: S-114 79 Stockholm +S: Sweden + +N: Pekka Enberg +E: penberg@cs.helsinki.fi +W: http://www.cs.helsinki.fi/u/penberg/ +D: Various kernel hacks, fixes, and cleanups. +D: Slab allocators +S: Finland + +N: David Engebretsen +E: engebret@us.ibm.com +D: Linux port to 64-bit PowerPC architecture + +N: Michael Engel +E: engel@unix-ag.org +D: DECstation framebuffer drivers +S: Germany + +N: Paal-Kristian Engstad +E: engstad@intermetrics.com +D: Kernel smbfs (to mount WfW, NT and OS/2 network drives.) +S: 17101 Springdale Street #225 +S: Huntington Beach, California 92649 +S: USA + +N: Stephane Eranian +E: eranian@hpl.hp.com +D: Linux/ia64 +S: 1501 Page Mill Rd, MS 1U17 +S: Palo Alto, CA 94304 +S: USA + +N: Johannes Erdfelt +E: johannes@erdfelt.com +D: Linux/IA-64 bootloader and kernel goop, USB +S: 6350 Stoneridge Mall Road +S: Pleasanton, CA 94588 +S: USA + +N: Dmitry Eremin-Solenikov +E: dbaryshkov@gmail.com +D: Power Supply Maintainer from v3.14 - v3.15 + +N: Doug Evans +E: dje@cygnus.com +D: Wrote Xenix FS (part of standard kernel since 0.99.15) + +N: Riccardo Facchetti +E: fizban@tin.it +P: 1024/6E657BB5 AF 22 90 33 78 76 04 8B AF F9 97 1E B5 E2 65 30 +D: Audio Excel DSP 16 init driver author +D: libmodem author +D: Yet Another Micro Monitor port and current maintainer +D: First ELF-HOWTO author +D: random kernel hacker +S: Via Paolo VI n.29 +S: 23900 - LECCO (Lc) +S: Italy + +N: Nils Faerber +E: nils@kernelconcepts.de +D: i810 TCO watchdog driver author +D: Mitsumi LU005 tests and fixes +D: port and fixes of cs46xx sounddriver +S: Dreisbachstrasse 24 +S: D-57250 Netphen +S: Germany + +N: Rik Faith +E: faith@acm.org +D: Future Domain TMC-16x0 SCSI driver (author) +D: APM driver (early port) +D: DRM drivers (author of several) + +N: János Farkas +E: chexum@shadow.banki.hu +D: romfs, various (mostly networking) fixes +P: 1024/F81FB2E1 41 B7 E4 E6 3E D4 A6 71 6D 9C F3 9F F2 BF DF 6E +S: Madarász Viktor utca 25 +S: 1131 Budapest +S: Hungary + +N: Ben Fennema +E: bfennema@falcon.csc.calpoly.edu +W: http://www.csc.calpoly.edu/~bfennema +D: UDF filesystem +S: (ask for current address) +S: USA + +N: Jürgen Fischer +E: fischer@norbit.de +D: Author of Adaptec AHA-152x SCSI driver +S: Schulstraße 18 +S: 26506 Norden +S: Germany + +N: Jeremy Fitzhardinge +E: jeremy@goop.org +W: http://www.goop.org/~jeremy +D: author of userfs filesystem +D: Improved mmap and munmap handling +D: General mm minor tidyups +D: autofs v4 maintainer +D: Xen subsystem +S: 987 Alabama St +S: San Francisco +S: CA, 94110 +S: USA + +N: Ralf Flaxa +E: rfflaxa@immd4.informatik.uni-erlangen.de +D: The Linux Support Team Erlangen +D: Creator of LST distribution +D: Author of installation tool LISA +S: Pfitznerweg 6 +S: 74523 Schwaebisch Hall +S: Germany + +N: Lawrence Foard +E: entropy@world.std.com +D: Floppy track reading, fs code +S: 217 Park Avenue, Suite 108 +S: Worcester, Massachusetts 01609 +S: USA + +N: Karl Fogel +E: kfogel@cs.oberlin.edu +D: Contributor, Linux User's Guide +S: 1123 North Oak Park Avenue +S: Oak Park, Illinois 60302 +S: USA + +N: Daniel J. Frasnelli +E: dfrasnel@alphalinux.org +W: http://www.alphalinux.org/ +P: 1024/3EF87611 B9 F1 44 50 D3 E8 C2 80 DA E5 55 AA 56 7C 42 DA +D: DEC Alpha hacker +D: Miscellaneous bug squisher + +N: Jim Freeman +E: jfree@sovereign.org +W: http://www.sovereign.org/ +D: Initial GPL'd Frame Relay driver +D: Dynamic PPP devices +D: Sundry modularizations (PPP, IPX, ...) and fixes + +N: Bob Frey +E: bobf@advansys.com +D: AdvanSys SCSI driver +S: 1150 Ringwood Court +S: San Jose, California 95131 +S: USA + +N: Adam Fritzler +E: mid@zigamorph.net + +N: Fernando Fuganti +E: fuganti@conectiva.com.br +E: fuganti@netbank.com.br +D: random kernel hacker, ZF MachZ Watchdog driver +S: Conectiva S.A. +S: R. Tocantins, 89 - Cristo Rei +S: 80050-430 - Curitiba - Paraná +S: Brazil + +N: Oded Gabbay +E: oded.gabbay@gmail.com +D: AMD KFD maintainer +S: 12 Shraga Raphaeli +S: Petah-Tikva, 4906418 +S: Israel + +N: Kumar Gala +E: galak@kernel.crashing.org +D: Embedded PowerPC 6xx/7xx/74xx/82xx/83xx/85xx support +S: Austin, Texas 78729 +S: USA + +N: Nigel Gamble +E: nigel@nrg.org +D: Interrupt-driven printer driver +D: Preemptible kernel +S: 120 Alley Way +S: Mountain View, California 94040 +S: USA + +N: Jeff Garzik +E: jgarzik@pobox.com + +N: Jacques Gelinas +E: jacques@solucorp.qc.ca +D: Author of the Umsdos file system +S: 1326 De Val-Brillant +S: Laval, Quebec +S: Canada H7Y 1V9 + +N: David Gentzel +E: gentzel@telerama.lm.com +D: Original BusLogic driver and original UltraStor driver +S: Whitfield Software Services +S: 600 North Bell Avenue, Suite 160 +S: Carnegie, Pennsylvania 15106-4304 +S: USA + +N: Kai Germaschewski +E: kai@germaschewski.name +D: Major kbuild rework during the 2.5 cycle +D: ISDN Maintainer +S: USA + +N: Philip Gladstone +E: philip@gladstonefamily.net +D: Kernel / timekeeping stuff +S: Carlisle, MA 01741 +S: USA + +N: Jan-Benedict Glaw +E: jbglaw@lug-owl.de +D: SRM environment driver (for Alpha systems) +P: 1024D/8399E1BB 250D 3BCF 7127 0D8C A444 A961 1DBD 5E75 8399 E1BB + +N: Thomas Gleixner +E: tglx@linutronix.de +D: NAND flash hardware support, JFFS2 on NAND flash + +N: Richard E. Gooch +E: rgooch@atnf.csiro.au +D: parent process death signal to children +D: prctl() syscall +D: /proc/mtrr support to manipulate MTRRs on Intel P6 family +D: Device FileSystem (devfs) +S: CSIRO Australia Telescope National Facility +S: P.O. Box 76, Epping +S: New South Wales, 2121 +S: Australia + +N: Carlos E. Gorges +E: carlos@techlinux.com.br +D: fix smp support on cmpci driver +P: 2048G/EA3C4B19 FF31 33A6 0362 4915 B7EB E541 17D0 0379 EA3C 4B19 +S: Brazil + +N: Dmitry S. Gorodchanin +E: pgmdsg@ibi.com +D: RISCom/8 driver, misc kernel fixes. +S: 4 Main Street +S: Woodbridge, Connecticut 06525 +S: USA + +N: Paul Gortmaker +E: p_gortmaker@yahoo.com +D: Author of RTC driver & several net drivers, Ethernet & BootPrompt Howto. +D: Made support for modules, ramdisk, generic-serial, etc. optional. +D: Transformed old user space bdflush into 1st kernel thread - kflushd. +D: Many other patches, documentation files, mini kernels, utilities, ... + +N: Masanori GOTO +E: gotom@debian.or.jp +D: Workbit NinjaSCSI-32Bi/UDE driver +S: Japan + +N: John E. Gotts +E: jgotts@linuxsavvy.com +D: kernel hacker +S: 8124 Constitution Apt. 7 +S: Sterling Heights, Michigan 48313 +S: USA + +N: Wolfgang Grandegger +E: wg@grandegger.com +D: Controller Area Network (device drivers) + +N: William Greathouse +E: wgreathouse@smva.com +E: wgreathouse@myfavoritei.com +D: Current Belkin USB Serial Adapter F5U103 hacker +D: Kernel hacker, embedded systems +S: 7802 Fitzwater Road +S: Brecksville, OH 44141-1334 +S: USA + +N: Tristan Greaves +E: tristan@extricate.org +W: http://www.extricate.org/ +D: Miscellaneous ipv4 sysctl patches + +N: Michael A. Griffith +E: grif@cs.ucr.edu +W: http://www.cs.ucr.edu/~grif +D: Loopback speedup, qlogic SCSI hacking, VT_LOCKSWITCH +S: Department of Computer Science +S: University of California, Riverside +S: Riverside, California 92521-0304 +S: USA + +N: Hans Grobler +E: grobh@sun.ac.za +D: Various AX.25/ROSE/NETROM + hamradio driver patches +D: Various X.25/LABP + driver patches +D: Misc kernel fixes and updates +S: Department of Electronic Engineering +S: University of Stellenbosch +S: Stellenbosch, Western Cape +S: South Africa + +N: Grant Grundler +E: grundler@parisc-linux.org +W: http://obmouse.sourceforge.net/ +W: http://www.parisc-linux.org/ +D: obmouse - rewrote Olivier Florent's Omnibook 600 "pop-up" mouse driver +D: PA-RISC - Interrupt/PCI HBA/IOMMU author and architect +S: Mountain View, California +S: USA + +N: Grant Guenther +E: grant@torque.net +W: http://www.torque.net/linux-pp.html +D: original author of ppa driver for parallel port ZIP drive +D: original architect of the parallel-port sharing scheme +D: PARIDE subsystem: drivers for parallel port IDE & ATAPI devices +S: 44 St. Joseph Street, Suite 506 +S: Toronto, Ontario, M4Y 2W4 +S: Canada + +N: Richard Günther +E: rguenth@tat.physik.uni-tuebingen.de +W: http://www.tat.physik.uni-tuebingen.de/~rguenth +P: 2048/2E829319 2F 83 FC 93 E9 E4 19 E2 93 7A 32 42 45 37 23 57 +D: binfmt_misc +S: 72074 Tübingen +S: Germany + +N: Justin Guyett +E: jguyett@andrew.cmu.edu +D: via-rhine net driver hacking + +N: Danny ter Haar +E: dth@cistron.nl +D: /proc/cpuinfo, reboot on panic , kernel pre-patch tester ;) +S: Cistron +S: PO-Box 297 +S: 2400 AG, Alphen aan den Rijn +S: The Netherlands + +N: Enver Haase +E: ehaase@inf.fu-berlin.de +W: http://www.inf.fu-berlin.de/~ehaase +D: Driver for the Commodore A2232 serial board + +N: Bruno Haible +E: haible@ma2s2.mathematik.uni-karlsruhe.de +D: SysV FS, shm swapping, memory management fixes +S: 17 rue Danton +S: F - 94270 Le Kremlin-Bicêtre +S: France + +N: Jack Hammer +D: IBM ServeRAID RAID (ips) driver maintenance + +N: Greg Hankins +E: gregh@cc.gatech.edu +D: fixed keyboard driver to separate LED and locking status +S: 25360 Georgia Tech Station +S: Atlanta, Georgia 30332 +S: USA + +N: Brad Hards +E: bradh@frogmouth.net +D: Various USB bits, other minor patches + +N: Angelo Haritsis +E: ah@computer.org +D: kernel patches (serial, watchdog) +D: xringd, vuzkern, greekXfonts +S: 77 Clarence Mews +S: London SE16 1GD +S: United Kingdom + +N: Jan Harkes +E: jaharkes@cs.cmu.edu +W: http://www.coda.cs.cmu.edu/ +D: Coda file system +S: Computer Science Department +S: Carnegie Mellon University +S: 5000 Forbes Avenue +S: Pittsburgh, Pennsylvania 15213 +S: USA + +N: Kai Harrekilde-Petersen +E: kai.harrekilde@get2net.dk +D: Original author of the ftape-HOWTO, i82078 fdc detection code. + +N: Bart Hartgers +E: bart@etpmod.phys.tue.nl +D: MTRR emulation with Centaur MCRs +S: Gen Stedmanstraat 212 +S: 5623 HZ Eindhoven +S: The Netherlands + +N: Oliver Hartkopp +E: oliver.hartkopp@volkswagen.de +W: http://www.volkswagen.de +D: Controller Area Network (network layer core) +S: Brieffach 1776 +S: 38436 Wolfsburg +S: Germany + +N: Andrew Haylett +E: ajh@primag.co.uk +D: Selection mechanism + +N: Andre Hedrick +E: andre@linux-ide.org +E: andre@linuxdiskcert.org +W: http://www.linux-ide.org/ +W: http://www.linuxdiskcert.org/ +D: Random SMP kernel hacker... +D: Uniform Multi-Platform E-IDE driver +D: Active-ATA-Chipset maddness.......... +D: Ultra DMA 133/100/66/33 w/48-bit Addressing +D: ATA-Disconnect, ATA-TCQ +D: ATA-Smart Kernel Daemon +D: Serial ATA +D: ATA Command Block and Taskfile +S: Linux ATA Development (LAD) +S: Concord, CA + +N: Jochen Hein +E: jochen@jochen.org +P: 1024/4A27F015 25 72 FB E3 85 9F DE 3B CB 0A DA DA 40 77 05 6C +P: 1024D/77D4FC9B F5C5 1C20 1DFC DEC3 3107 54A4 2332 ADFC 77D4 FC9B +D: National Language Support +D: Linux Internationalization Project +D: German Localization for Linux and GNU software +S: Auf der Fittel 18 +S: 53347 Alfter +S: Germany + +N: Christoph Hellwig +E: hch@infradead.org +D: all kinds of driver, filesystem & core kernel hacking +D: freevxfs driver +D: sysvfs maintainer +D: chief codingstyle nitpicker +S: Ampferstr. 50 / 4 +S: 6020 Innsbruck +S: Austria + +N: Richard Henderson +E: rth@twiddle.net +E: rth@cygnus.com +D: Alpha hacker, kernel and userland +S: 1668 California St. +S: Mountain View, California 94041 +S: USA + +N: Benjamin Herrenschmidt +E: benh@kernel.crashing.org +D: Various parts of PPC/PPC64 & PowerMac +S: 312/107 Canberra Avenue +S: Griffith, ACT 2603 +S: Australia + +N: Andreas Herrmann +E: herrmann.der.user@gmail.com +E: herrmann.der.user@googlemail.com +D: Key developer of x86/AMD64 +D: Author of AMD family 15h processor power monitoring driver +D: Maintainer of AMD Athlon 64 and Opteron processor frequency driver +S: Germany + +N: Sebastian Hetze +E: she@lunetix.de +D: German Linux Documentation, +D: Organization of German Linux Conferences +S: Danckelmannstr. 48 +S: 14059 Berlin +S: Germany + +N: David Hinds +E: dahinds@users.sourceforge.net +W: http://tao.stanford.edu/~dhinds +D: PCMCIA and CardBus stuff, PCMCIA-HOWTO, PCMCIA client drivers +S: 2019 W. Middlefield Rd #1 +S: Mountain View, CA 94043 +S: USA + +N: Michael Hipp +E: hippm@informatik.uni-tuebingen.de +D: drivers for the racal ni5210 & ni6510 Ethernet-boards +S: Talstr. 1 +S: D - 72072 Tuebingen +S: Germany + +N: Richard Hirst +E: richard@sleepie.demon.co.uk +E: rhirst@linuxcare.com +W: http://www.sleepie.demon.co.uk/ +D: linux-m68k VME support +D: PA-RISC port, scsi and network drivers +D: 53c700/53c710 driver author, 82596 driver maintainer +S: United Kingdom + +N: Jauder Ho +E: jauderho@carumba.com +W: http://www.carumba.com/ +D: bug toaster (A1 sauce makes all the difference) +D: Random linux hacker + +N: Tim Hockin +E: thockin@hockin.org +W: http://www.hockin.org/~thockin +D: Natsemi ethernet +D: Cobalt Networks (x86) support +D: This-and-That + +N: Mark M. Hoffman +E: mhoffman@lightlink.com +D: asb100, lm93 and smsc47b397 hardware monitoring drivers +D: hwmon subsystem core +D: hwmon subsystem maintainer +D: i2c-sis96x and i2c-stub SMBus drivers +S: USA + +N: Dirk Hohndel +E: hohndel@suse.de +D: The XFree86[tm] Project +D: USB mouse maintainer +S: SuSE Rhein/Main AG +S: Mergenthalerallee 45-47 +S: 65760 Eschborn +S: Germany + +N: Kenji Hollis +E: kenji@bitgate.com +W: http://www.bitgate.com/ +D: Berkshire PC Watchdog Driver +D: Small/Industrial Driver Project + +N: Nick Holloway +E: Nick.Holloway@pyrites.org.uk +W: http://www.pyrites.org.uk/ +P: 1024/36115A04 F4E1 3384 FCFD C055 15D6 BA4C AB03 FBF8 3611 5A04 +D: Occasional Linux hacker... +S: (ask for current address) +S: United Kingdom + +N: Ron Holt +E: ron@holt.org +E: rholt@netcom.com +W: http://www.holt.org/ +W: http://www.ronholt.com/ +D: Kernel development +D: Kernel LDT modifications to support Wabi and Wine +S: Holtron Internetics, Inc. +S: 998 East 900 South, Suite 26 +S: Provo, Utah 84606-5607 +S: USA + +N: Marcel Holtmann +E: marcel@holtmann.org +W: http://www.holtmann.org +D: Maintainer of the Linux Bluetooth Subsystem +D: Author and maintainer of the various Bluetooth HCI drivers +D: Author and maintainer of the CAPI message transport protocol driver +D: Author and maintainer of the Bluetooth HID protocol driver +D: Various other Bluetooth related patches, cleanups and fixes +S: Germany + +N: Rob W. W. Hooft +E: hooft@EMBL-Heidelberg.DE +D: Shared libs for graphics-tools and for the f2c compiler +D: Some kernel programming on the floppy and sound drivers in early days +D: Some other hacks to get different kinds of programs to work for linux +S: Panoramastrasse 18 +S: D-69126 Heidelberg +S: Germany + +N: Christopher Horn +E: chorn@warwick.net +D: Miscellaneous sysctl hacks +S: 36 Mudtown Road +S: Wantage, New Jersey 07461 +S: USA + +N: Harald Hoyer +E: harald@redhat.com +W: http://www.harald-hoyer.de +D: ip_masq_quake +D: md boot support +S: Am Strand 5 +S: D-19063 Schwerin +S: Germany + +N: Jan Hubicka +E: hubicka@freesoft.cz +E: hubicka@suse.cz +W: http://www.paru.cas.cz/~hubicka/ +D: Random kernel tweaks and fixes. +S: Dukelskych bojovniku 1944 +S: Tabor 390 03 +S: Czech Republic + +N: David Huggins-Daines +E: dhd@debian.org +E: dhd@eradicator.org +E: dhd@cepstral.com +D: PA-RISC port +D: Nubus subsystem +D: Generic 68k Macintosh framebuffer driver +D: STI framebuffer tweaks +D: LTPC driver tweaks +S: 110 S. 12th St., Apt. A +S: Pittsburgh, PA 15203-1250 +S: USA + +N: Gareth Hughes +E: gareth.hughes@acm.org +D: Pentium III FXSR, SSE support +D: Author/maintainer of most DRM drivers (especially ATI, MGA) +D: Core DRM templates, general DRM and 3D-related hacking +S: No fixed address + +N: Kenn Humborg +E: kenn@wombat.ie +D: Mods to loop device to support sparse backing files +S: Ballinagard +S: Roscommon +S: Ireland + +N: Michael Hunold +E: michael@mihu.de +W: http://www.mihu.de/linux/ +D: Generic saa7146 video4linux-2 driver core, +D: Driver for the "Multimedia eXtension Board", "dpc7146", +D: "Hexium Orion", "Hexium Gemini" + +N: Miguel de Icaza Amozurrutia +E: miguel@nuclecu.unam.mx +D: Linux/SPARC team, Midnight Commander maintainer +S: Avenida Copilco 162, 22-1003 +S: Mexico, DF +S: Mexico + +N: Ian Jackson +E: iwj10@cus.cam.ac.uk +E: ijackson@nyx.cs.du.edu +D: FAQ maintainer and poster of the daily postings +D: FSSTND group member +D: Debian core team member and maintainer of several Debian packages +S: 2 Lexington Close +S: Cambridge +S: CB3 0DS +S: United Kingdom + +N: Andreas Jaeger +E: aj@suse.de +D: Various smaller kernel fixes +D: glibc developer +S: Gottfried-Kinkel-Str. 18 +S: D 67659 Kaiserslautern +S: Germany + +N: Mike Jagdis +E: jaggy@purplet.demon.co.uk +E: Mike.Jagdis@purplet.demon.co.uk +D: iBCS personalities, socket and X interfaces, x.out loader, syscalls... +D: Purple Distribution maintainer +D: UK FidoNet support +D: ISODE && PP +D: Kernel and device driver hacking +S: 280 Silverdale Road +S: Earley +S: Reading +S: RG6 2NU +S: United Kingdom + +N: Dave Jeffery +E: dhjeffery@gmail.com +D: SCSI hacks and IBM ServeRAID RAID driver maintenance + +N: Jakub Jelinek +E: jakub@redhat.com +W: http://sunsite.mff.cuni.cz/~jj +P: 1024/0F7623C5 53 95 71 3C EB 73 99 97 02 49 40 47 F9 19 68 20 +D: Sparc hacker, SILO, mc +D: Maintain sunsite.mff.cuni.cz +S: K osmidomkum 723 +S: 160 00 Praha 6 +S: Czech Republic + +N: Niels Kristian Bech Jensen +E: nkbj1970@hotmail.com +D: Miscellaneous kernel updates and fixes. + +N: Michael K. Johnson +E: johnsonm@redhat.com +W: http://www.redhat.com/~johnsonm +P: 1024/4536A8DD 2A EC 88 08 40 64 CE D8 DD F8 12 2B 61 43 83 15 +D: The Linux Documentation Project +D: Kernel Hackers' Guide +D: Procps +D: Proc filesystem +D: Maintain tsx-11.mit.edu +D: LP driver +S: 201 Howell Street, Apartment 1C +S: Chapel Hill, North Carolina 27514-4818 +S: USA + +N: Dave Jones +E: davej@codemonkey.org.uk +W: http://www.codemonkey.org.uk +D: Assorted VIA x86 support. +D: 2.5 AGPGART overhaul. +D: CPUFREQ maintenance. +D: Fedora kernel maintenance (2003-2014). +D: 'Trinity' and similar fuzz testing work. +D: Misc/Other. + +N: Martin Josfsson +E: gandalf@wlug.westbo.se +P: 1024D/F6B6D3B1 7610 7CED 5C34 4AA6 DBA2 8BE1 5A6D AF95 F6B6 D3B1 +D: netfilter: SAME target +D: netfilter: helper target +D: netfilter: various other hacks +S: Ronneby +S: Sweden + +N: Ani Joshi +E: ajoshi@shell.unixbox.com +D: fbdev hacking + +N: Jesper Juhl +E: jj@chaosbits.net +D: Various fixes, cleanups and minor features all over the tree. +D: Wrote initial version of the hdaps driver (since passed on to others). +S: Lemnosvej 1, 3.tv +S: 2300 Copenhagen S. +S: Denmark + +N: Jozsef Kadlecsik +E: kadlec@blackhole.kfki.hu +P: 1024D/470DB964 4CB3 1A05 713E 9BF7 FAC5 5809 DD8C B7B1 470D B964 +D: netfilter: TCP window tracking code +D: netfilter: raw table +D: netfilter: iprange match +D: netfilter: new logging interfaces +D: netfilter: various other hacks +S: Tata +S: Hungary + +N: Bernhard Kaindl +E: bkaindl@netway.at +E: edv@bartelt.via.at +D: Author of a menu based configuration tool, kmenu, which +D: is the predecessor of 'make menuconfig' and 'make xconfig'. +D: digiboard driver update(modularisation work and 2.1.x upd) +S: Tallak 95 +S: 8103 Rein +S: Austria + +N: Mitsuru Kanda +E: mk@linux-ipv6.org +E: mk@isl.rdc.toshiba.co.jp +E: mk@karaba.org +W: http://www.karaba.org/~mk/ +P: 1024D/2EC7E30D 4DC3 949B 5A6C F0D6 375F 4472 8888 A8E1 2EC7 E30D +D: IPsec, IPv6 +D: USAGI/WIDE Project, TOSHIBA CORPORATION +S: 2-47-8, Takinogawa, +S: Kita, Tokyo 114-0023 +S: Japan + +N: Jan Kara +E: jack@atrey.karlin.mff.cuni.cz +E: jack@suse.cz +D: Quota fixes for 2.2 kernel +D: Quota fixes for 2.3 kernel +D: Few other fixes in filesystem area (buffer cache, isofs, loopback) +W: http://atrey.karlin.mff.cuni.cz/~jack/ +S: Krosenska' 543 +S: 181 00 Praha 8 +S: Czech Republic + +N: Jan "Yenya" Kasprzak +E: kas@fi.muni.cz +D: Author of the COSA/SRP sync serial board driver. +D: Port of the syncppp.c from the 2.0 to the 2.1 kernel. +P: 1024/D3498839 0D 99 A7 FB 20 66 05 D7 8B 35 FC DE 05 B1 8A 5E +W: http://www.fi.muni.cz/~kas/ +S: c/o Faculty of Informatics, Masaryk University +S: Botanicka' 68a +S: 602 00 Brno +S: Czech Republic + +N: Jakob Kemi +E: jakob.kemi@telia.com +D: V4L W9966 Webcam driver +S: Forsbyvägen 33 +S: 74143 Knivsta +S: Sweden + +N: Fred N. van Kempen +E: waltje@linux.com +D: NET-2 +D: Drivers +D: Kernel cleanups +S: Korte Heul 95 +S: 1403 ND BUSSUM +S: The Netherlands + +N: Martin Kepplinger +E: martink@posteo.de +E: martin.kepplinger@ginzinger.com +W: http://www.martinkepplinger.com +D: mma8452 accelerators iio driver +D: pegasus_notetaker input driver +D: Kernel fixes and cleanups +S: Garnisonstraße 26 +S: 4020 Linz +S: Austria + +N: Karl Keyte +E: karl@koft.com +D: Disk usage statistics and modifications to line printer driver +S: 26a Sheen Road +S: Richmond +S: Surrey +S: TW9 1AE +S: United Kingdom + +N: Marko Kiiskila +E: marko@iprg.nokia.com +D: Author of ATM Lan Emulation +S: 660 Harvard Ave. #7 +S: Santa Clara, CA 95051 +S: USA + +N: Russell King +E: rmk@arm.linux.org.uk +D: Linux/arm integrator, maintainer & hacker +D: Acornfb, Cyber2000fb author +S: Burgh Heath, Tadworth, Surrey. +S: England + +N: Olaf Kirch +E: okir@monad.swb.de +D: Author of the Linux Network Administrators' Guide +S: Kattreinstr 38 +S: D-64295 +S: Germany + +N: Avi Kivity +E: avi.kivity@gmail.com +D: Kernel-based Virtual Machine (KVM) +S: Ra'annana, Israel + +N: Andi Kleen +E: andi@firstfloor.org +W: http://www.halobates.de +D: network, x86, NUMA, various hacks +S: Schwalbenstr. 96 +S: 85551 Ottobrunn +S: Germany + +N: Ian Kluft +E: ikluft@thunder.sbay.org +W: http://www.kluft.com/~ikluft/ +D: NET-1 beta testing & minor patches, original Smail binary packages for +D: Slackware and Debian, vote-taker for 2nd comp.os.linux reorganization +S: Post Office Box 611311 +S: San Jose, California 95161-1311 +S: USA + +N: Thorsten Knabe +E: Thorsten Knabe <tek@rbg.informatik.tu-darmstadt.de> +E: Thorsten Knabe <tek01@hrzpub.tu-darmstadt.de> +W: http://www.student.informatik.tu-darmstadt.de/~tek +W: http://www.tu-darmstadt.de/~tek01 +P: 1024/3BC8D885 8C 29 C5 0A C0 D1 D6 F4 20 D4 2D AB 29 F6 D0 60 +D: AD1816 sound driver +S: Am Bergfried 10 +S: 63225 Langen +S: Germany + +N: Alain L. Knaff +E: Alain.Knaff@lll.lu +D: floppy driver +S: 19, rue Jean l'Aveugle +S: L-1148 Luxembourg-City +S: Luxembourg + +N: Gerd Knorr +W: http://bytesex.org +E: kraxel@bytesex.org +E: kraxel@suse.de +D: video4linux, bttv, vesafb, some scsi, misc fixes + +N: Hans J. Koch +D: USERSPACE I/O, MAX6650 +D: Hans passed away in June 2016, and will be greatly missed. +W: https://lwn.net/Articles/691000/ + +N: Harald Koenig +E: koenig@tat.physik.uni-tuebingen.de +D: XFree86 (S3), DCF77, some kernel hacks and fixes +S: Koenigsberger Str. 90 +S: D-72336 Balingen +S: Germany + +N: Rudolf Koenig +E: rfkoenig@immd4.informatik.uni-erlangen.de +D: The Linux Support Team Erlangen + +N: Andreas Koensgen +E: ajk@comnets.uni-bremen.de +D: 6pack driver for AX.25 + +N: Harald Koerfgen +E: hkoerfg@web.de +D: Linux/MIPS kernel hacks and fixes, +D: DECstation port, Sharp Mobilon port +S: D-50931 Koeln +S: Germany + +N: Willy Konynenberg +E: willy@xos.nl +W: http://www.xos.nl/ +D: IP transparent proxy support +S: X/OS Experts in Open Systems BV +S: Kruislaan 419 +S: 1098 VA Amsterdam +S: The Netherlands + +N: Goran Koruga +E: korugag@siol.net +D: cpufrequtils (precursor to cpupowerutils) +S: Slovenia + +N: Jiri Kosina +E: jikos@jikos.cz +E: jkosina@suse.cz +D: Generic HID layer - original code split, fixes +D: Various ACPI fixes, keeping correct battery state through suspend +D: various lockdep annotations, autofs and other random bugfixes +S: Prague, Czech Republic + +N: Gene Kozin +E: 74604.152@compuserve.com +W: http://www.sangoma.com +D: WAN Router & Sangoma WAN drivers +S: Sangoma Technologies Inc. +S: 7170 Warden Avenue, Unit 2 +S: Markham, Ontario +S: L3R 8B2 +S: Canada + +N: Maxim Krasnyansky +E: maxk@qualcomm.com +W: http://vtun.sf.net +W: http://bluez.sf.net +D: Author of the Universal TUN/TAP driver +D: Author of the Linux Bluetooth Subsystem (BlueZ) +D: Various other kernel patches, cleanups and fixes +S: 2213 La Terrace Circle +S: San Jose, CA 95123 +S: USA + +N: Andreas S. Krebs +E: akrebs@altavista.net +D: CYPRESS CY82C693 chipset IDE, Digital's PC-Alpha 164SX boards + +N: Greg Kroah-Hartman +E: greg@kroah.com +E: gregkh@suse.de +W: http://www.kroah.com/linux/ +D: USB Serial Converter driver framework, USB Handspring Visor driver +D: ConnectTech WHITEHeat USB driver, Generic USB Serial driver +D: USB I/O Edgeport driver, USB Serial IrDA driver +D: USB Bluetooth driver, USB Skeleton driver +D: bits and pieces of USB core code. +D: PCI Hotplug core, PCI Hotplug Compaq driver modifications +D: portions of the Linux Security Module (LSM) framework +D: parts of the driver core, debugfs. + +N: Russell Kroll +E: rkroll@exploits.org +W: http://www.exploits.org/ +D: V4L radio cards: radio-aztech (new), others (bugfixes/features) +D: Loopback block device: dynamic sizing ("max_loop" as module) +S: Post Office Box 691886 +S: San Antonio, Texas 78269-1886 +S: USA + +N: Denis O. Kropp +E: dok@directfb.org +D: NeoMagic framebuffer driver +S: Badensche Str. 46 +S: 10715 Berlin +S: Germany + +N: Andrzej M. Krzysztofowicz +E: ankry@mif.pg.gda.pl +D: Some 8-bit XT disk driver and devfs hacking +D: Aladdin 1533/1543(C) chipset IDE +D: PIIX chipset IDE +S: ul. Matemblewska 1B/10 +S: 80-283 Gdansk +S: Poland + +N: Gero Kuhlmann +E: gero@gkminix.han.de +D: mounting root via NFS +S: Donarweg 4 +S: D-30657 Hannover +S: Germany + +N: Markus Kuhn +E: mskuhn@cip.informatik.uni-erlangen.de +W: http://wwwcip.informatik.uni-erlangen.de/user/mskuhn +D: Unicode, real-time, time, standards +S: Schlehenweg 9 +S: D-91080 Uttenreuth +S: Germany + +N: Jaya Kumar +E: jayalk@intworks.biz +W: http://www.intworks.biz +D: Arc monochrome LCD framebuffer driver, x86 reboot fixups +D: pirq addr, CS5535 alsa audio driver +S: Gurgaon, India +S: Kuala Lumpur, Malaysia + +N: Mohit Kumar +D: ST Microelectronics SPEAr13xx PCI host bridge driver +D: Synopsys Designware PCI host bridge driver + +N: Gabor Kuti +E: seasons@falcon.sch.bme.hu +E: seasons@makosteszta.sote.hu +D: Original author of software suspend + +N: Jaroslav Kysela +E: perex@perex.cz +W: http://www.perex.cz +D: Original Author and Maintainer for HP 10/100 Mbit Network Adapters +D: ISA PnP +S: Sindlovy Dvory 117 +S: 370 01 Ceske Budejovice +S: Czech Republic + +N: Bas Laarhoven +E: sjml@xs4all.nl +D: Loadable modules and ftape driver +S: J. Obrechtstr 23 +S: NL-5216 GP 's-Hertogenbosch +S: The Netherlands + +N: Savio Lam +E: lam836@cs.cuhk.hk +D: Author of the dialog utility, foundation +D: for Menuconfig's lxdialog. + +N: Christoph Lameter +E: christoph@lameter.com +D: Digiboard PC/Xe and PC/Xi, Digiboard EPCA +D: NUMA support, Slab allocators, Page migration +D: Scalability, Time subsystem + +N: Paul Laufer +E: paul@laufernet.com +D: Soundblaster driver fixes, ISAPnP quirk +S: California, USA + +N: Jonathan Layes +D: ARPD support + +N: Tom Lees +E: tom@lpsg.demon.co.uk +W: http://www.lpsg.demon.co.uk/ +P: 1024/87D4D065 2A 66 86 9D 02 4D A6 1E B8 A2 17 9D 4F 9B 89 D6 +D: Original author and current maintainer of +D: PnP code. + +N: David van Leeuwen +E: david@tm.tno.nl +D: Philips/LMS cm206 cdrom driver, generic cdrom driver +S: Scheltemalaan 14 +S: 3817 KS Amersfoort +S: The Netherlands + +N: Volker Lendecke +E: vl@kki.org +D: Kernel smbfs (to mount WfW, NT and OS/2 network drives.) +D: NCP filesystem support (to mount NetWare volumes) +S: Von-Ossietzky-Str. 12 +S: 37085 Göttingen +S: Germany + +N: Kevin Lentin +E: kevinl@cs.monash.edu.au +D: NCR53C400/T130B SCSI extension to NCR5380 driver. +S: 18 Board Street +S: Doncaster VIC 3108 +S: Australia + +N: Hans Lermen +E: lermen@elserv.ffm.fgan.de +D: Author of the LOADLIN Linux loader, hacking on boot stuff +D: Coordinator of DOSEMU releases +S: Am Muehlenweg 38 +S: D53424 Remagen +S: Germany + +N: Colin Leroy +E: colin@colino.net +W: http://www.geekounet.org/ +D: PowerMac adt746x fan driver +D: Random fixing of various drivers (macintosh, usb, sound) +S: Toulouse +S: France + +N: Achim Leubner +E: achim_leubner@adaptec.com +D: GDT Disk Array Controller/Storage RAID controller driver +S: ICP vortex GmbH +S: Neckarsulm +S: Germany + +N: Phil Lewis +E: beans@bucket.ualr.edu +D: Promised to send money if I would put his name in the source tree. +S: Post Office Box 371 +S: North Little Rock, Arkansas 72115 +S: USA + +N: Stephan Linz +E: linz@mazet.de +E: Stephan.Linz@gmx.de +W: http://www.crosswinds.net/~tuxer +D: PCILynx patch to work with 1394a PHY and without local RAM +S: (ask for current address) +S: Germany + +N: Christophe Lizzi +E: lizzi@cnam.fr +W: http://cedric.cnam.fr/personne/lizzi +D: FORE Systems 200E-series ATM network driver, sparc64 port of ATM +S: CNAM, Laboratoire CEDRIC +S: 292, rue St-Martin +S: 75141 Paris Cedex 03 +S: France + +N: Siegfried "Frieder" Loeffler (dg1sek) +E: floeff@tunix.mathematik.uni-stuttgart.de, fl@LF.net +W: http://www.mathematik.uni-stuttgart.de/~floeff +D: Busmaster driver for HP 10/100 Mbit Network Adapters +S: University of Stuttgart, Germany and +S: Ecole Nationale Superieure des Telecommunications, Paris +S: France + +N: Jamie Lokier +E: jamie@shareable.org +W: http://www.shareable.org/ +D: Reboot-through-BIOS for broken 486 motherboards +D: Parport fixes, futex improvements +D: First instruction of x86 sysenter path :) +S: 51 Sunningwell Road +S: Oxford +S: OX1 4SZ +S: United Kingdom + +N: Mark Lord +E: mlord@pobox.com +D: EIDE driver, hd.c support +D: EIDE PCI and bus-master DMA support +D: Hard Disk Parameter (hdparm) utility +S: 33 Ridgefield Cr +S: Nepean, Ontario +S: Canada K2H 6S3 + +N: Warner Losh +E: imp@village.org +D: Linux/MIPS Deskstation support, Provided OI/OB for Linux +S: 8786 Niwot Road +S: Niwot, Colorado 80503 +S: USA + +N: Robert M. Love +E: rml@tech9.net +E: rml@novell.com +D: misc. kernel hacking and debugging +S: Cambridge, MA 02139 +S: USA + +N: Martin von Löwis +E: loewis@informatik.hu-berlin.de +D: script binary format +D: NTFS driver + +N: H.J. Lu +E: hjl@gnu.ai.mit.edu +D: GCC + libraries hacker + +N: Yanir Lubetkin +E: yanirx.lubatkin@intel.com +E: linux-wimax@intel.com +D: Intel Wireless WiMAX Connection 2400 driver + +N: Michal Ludvig +E: michal@logix.cz +E: michal.ludvig@asterisk.co.nz +W: http://www.logix.cz/michal +P: 1024D/C45B2218 1162 6471 D391 76E0 9F99 29DA 0C3A 2509 C45B 2218 +D: VIA PadLock driver +D: Netfilter pkttype module +S: Asterisk Ltd. +S: Auckland +S: New Zealand + +N: Tuomas J. Lukka +E: Tuomas.Lukka@Helsinki.FI +D: Original dual-monitor patches +D: Console-mouse-tracking patches +S: Puistokaari 1 E 18 +S: 00200 Helsinki +S: Finland + +N: Daniel J. Maas +E: dmaas@dcine.com +W: http://www.maasdigital.com +D: dv1394 + +N: Hamish Macdonald +E: hamishm@lucent.com +D: Linux/68k port +S: 32 Clydesdale Avenue +S: Kanata, Ontario +S: Canada K2M-2G7 + +N: Peter MacDonald +D: SLS distribution +D: Initial implementation of VC's, pty's and select() + +N: Pavel Machek +E: pavel@ucw.cz +P: 4096R/92DFCE96 4FA7 9EEF FCD4 C44F C585 B8C7 C060 2241 92DF CE96 +D: Softcursor for vga, hypertech cdrom support, vcsa bugfix, nbd, +D: sun4/330 port, capabilities for elf, speedup for rm on ext2, USB, +D: work on suspend-to-ram/disk, killing duplicates from ioctl32, +D: Altera SoCFPGA and Nokia N900 support. +S: Czech Republic + +N: Paul Mackerras +E: paulus@samba.org +D: PPP driver +D: Linux for PowerPC +D: Linux port for PCI Power Macintosh + +N: Pat Mackinlay +E: pat@it.com.au +D: 8 bit XT hard disk driver +D: Miscellaneous ST0x, TMC-8xx and other SCSI hacking +S: 25 McMillan Street +S: Victoria Park 6100 +S: Australia + +N: James B. MacLean +E: macleajb@ednet.ns.ca +W: http://www.ednet.ns.ca/~macleajb/dosemu.html +D: Former Coordinator of DOSEMU releases +D: Program in DOSEMU +S: PO BOX 220, HFX. CENTRAL +S: Halifax, Nova Scotia +S: Canada B3J 3C8 + +N: Kai Mäkisara +E: Kai.Makisara@kolumbus.fi +D: SCSI Tape Driver + +N: Asit Mallick +E: asit.k.mallick@intel.com +D: Linux/IA-64 +S: 2200 Mission College Blvd +S: Santa Clara, CA 95052 +S: USA + +N: Petko Manolov +E: petkan@users.sourceforge.net +D: USB ethernet pegasus/pegasus-II driver +D: USB ethernet rtl8150 driver +D: optimizing i[45]86 string routines +D: i386 task switching hacks +S: 482 Shadowgraph Dr. +S: San Jose, CA 95110 +S: USA + +N: Martin Mares +E: mj@ucw.cz +W: http://www.ucw.cz/~mj/ +D: BIOS video mode handling code +D: MOXA C-218 serial board driver +D: Network autoconfiguration +D: PCI subsystem +D: Random kernel hacking +S: Kankovskeho 1241 +S: 182 00 Praha 8 +S: Czech Republic + +N: John A. Martin +E: jam@acm.org +W: http://www.tux.org/~jam/ +P: 1024/04456D53 9D A3 6C 6B 88 80 8A 61 D7 06 22 4F 95 40 CE D2 +P: 1024/3B986635 5A61 7EE6 9E20 51FB 59FB 2DA5 3E18 DD55 3B98 6635 +D: FSSTND contributor +D: Credit file compilator + +N: Kevin E. Martin +E: martin@cs.unc.edu +D: Developed original accelerated X servers included in XFree86 +D: XF86_Mach64 +D: XF86_Mach32 +D: XF86_Mach8 +D: XF86_8514 +D: cfdisk (curses based disk partitioning program) + +N: John S. Marvin +E: jsm@fc.hp.com +D: PA-RISC port +S: Hewlett Packard +S: MS 42 +S: 3404 E. Harmony Road +S: Fort Collins, CO 80528 +S: USA + +N: Torben Mathiasen +E: torben.mathiasen@compaq.com +E: torben@kernel.dk +W: http://tlan.kernel.dk +D: ThunderLAN maintainer +D: ThunderLAN updates and other kernel fixes. +S: Bremensgade 29, st.th +S: 2300 Copenhagen S +S: Denmark + +N: Claudio S. Matsuoka +E: cmatsuoka@gmail.com +E: claudio@mandriva.com +W: http://helllabs.org/~claudio +D: V4L, OV511 and HDA-codec hacks +S: Conectiva S.A. +S: Souza Naves 1250 +S: 80050-040 Curitiba PR +S: Brazil + +N: Heinz Mauelshagen +E: mge@EZ-Darmstadt.Telekom.de +D: Logical Volume Manager +S: Bartningstr. 12 +S: 64289 Darmstadt +S: Germany + +N: Mark W. McClelland +E: mmcclell@bigfoot.com +E: mark@alpha.dyndns.org +W: http://alpha.dyndns.org/ov511/ +P: 1024D/357375CC 317C 58AC 1B39 2AB0 AB96 EB38 0B6F 731F 3573 75CC +D: OV511 driver +S: (address available on request) +S: USA + +N: Ian McDonald +E: ian.mcdonald@jandi.co.nz +E: imcdnzl@gmail.com +W: http://wand.net.nz/~iam4 +W: http://imcdnzl.blogspot.com +D: DCCP, CCID3 +S: Hamilton +S: New Zealand + +N: Patrick McHardy +E: kaber@trash.net +P: 1024D/12155E80 B128 7DE6 FF0A C2B2 48BE AB4C C9D4 964E 1215 5E80 +D: netfilter: endless number of bugfixes +D: netfilter: CLASSIFY target +D: netfilter: addrtype match +D: tc: HFSC scheduler +S: Freiburg +S: Germany + +N: Paul E. McKenney +E: paulmck@us.ibm.com +W: http://www.rdrop.com/users/paulmck/ +D: RCU and variants +D: rcutorture module + +N: Mike McLagan +E: mike.mclagan@linux.org +W: http://www.invlogic.com/~mmclagan +D: DLCI/FRAD drivers for Sangoma SDLAs +S: Innovative Logic Corp +S: Post Office Box 1068 +S: Laurel, Maryland 20732 +S: USA + +N: Bradley McLean +E: brad@bradpc.gaylord.com +D: Device driver hacker +D: General kernel debugger +S: 249 Nichols Avenue +S: Syracuse, New York 13206 +S: USA + +N: Kyle McMartin +E: kyle@parisc-linux.org +D: Linux/PARISC hacker +D: AD1889 sound driver +S: Ottawa, Canada + +N: Dirk Melchers +E: dirk@merlin.nbg.sub.org +D: 8 bit XT hard disk driver for OMTI5520 +S: Schloessleinsgasse 31 +S: D-90453 Nuernberg +S: Germany + +N: Arnaldo Carvalho de Melo +E: acme@ghostprotocols.net +E: arnaldo.melo@gmail.com +E: acme@redhat.com +W: http://oops.ghostprotocols.net:81/blog/ +P: 1024D/9224DF01 D5DF E3BB E3C8 BCBB F8AD 841A B6AB 4681 9224 DF01 +D: IPX, LLC, DCCP, cyc2x, wl3501_cs, net/ hacks +S: Brazil + +N: Karsten Merker +E: merker@linuxtag.org +D: DECstation framebuffer drivers +S: Germany + +N: Michael Meskes +E: meskes@debian.org +P: 1024/04B6E8F5 6C 77 33 CA CC D6 22 03 AB AB 15 A3 AE AD 39 7D +D: Kernel hacker. PostgreSQL hacker. Software watchdog daemon. +D: Maintainer of several Debian packages +S: Th.-Heuss-Str. 61 +S: D-41812 Erkelenz +S: Germany + +N: Nigel Metheringham +E: Nigel.Metheringham@ThePLAnet.net +P: 1024/31455639 B7 99 BD B8 00 17 BD 46 C1 15 B8 AB 87 BC 25 FA +D: IP Masquerading work and minor fixes +S: Planet Online +S: The White House, Melbourne Street, LEEDS +S: LS2 7PS, United Kingdom + +N: Craig Metz +E: cmetz@inner.net +D: Some of PAS 16 mixer & PCM support, inet6-apps + +N: William (Bill) Metzenthen +E: billm@suburbia.net +D: Author of the FPU emulator. +D: Minor kernel hacker for other lost causes (Hercules mono, etc). +S: 22 Parker Street +S: Ormond +S: Victoria 3163 +S: Australia + +N: Pauline Middelink +E: middelin@polyware.nl +D: General low-level bug fixes, /proc fixes, identd support +D: Author of IP masquerading +D: Zoran ZR36120 Video For Linux driver +S: Boterkorfhoek 34 +S: 7546 JA Enschede +S: Netherlands + +N: David S. Miller +E: davem@davemloft.net +D: Sparc and blue box hacker +D: Vger Linux mailing list co-maintainer +D: Linux Emacs elf/qmagic support + other libc/gcc things +D: Yee bore de yee bore! ;-) +S: 575 Harrison St. #103 +S: San Francisco, CA 94105 +S: USA + +N: Rick Miller +E: rdmiller@execpc.com +W: http://www.execpc.com/~rdmiller/ +D: Original Linux Device Registrar (Major/minor numbers) +D: au-play, bwBASIC +S: S78 W16203 Woods Road +S: Muskego, Wisconsin 53150 +S: USA + +N: Harald Milz +E: hm@seneca.linux.de +D: Linux Projects Map, Linux Commercial-HOWTO +D: general Linux publicity in Germany, vacation port +D: UUCP and CNEWS binary packages for LST +S: Editorial Board iX Mag +S: Helstorfer Str. 7 +S: D-30625 Hannover +S: Germany + +N: Corey Minyard +E: minyard@wf-rch.cirr.com +E: minyard@mvista.com +W: http://home.attbi.com/~minyard +D: Sony CDU31A CDROM Driver +D: IPMI driver +D: Various networking fixes long ago +D: Original ppc_md work +D: Shared zlib +S: 7406 Wheat Field Rd +S: Garland, Texas 75044 +S: USA + +N: Kazunori Miyazawa +E: miyazawa@linux-ipv6.org +E: Kazunori.Miyazawa@jp.yokogawa.com +E: kazunori@miyazawa.org +W: http://www.miyazawa.org/~kazunori/ +D: IPsec, IPv6 +D: USAGI/WIDE Project, Yokogawa Electric Corporation +S: 2-20-4-203, Nakacho, +S: Musashino, Tokyo 180-0006 +S: Japan + +N: Patrick Mochel +E: mochel@osdl.org +E: mochelp@infinity.powertie.org +D: PCI Power Management, ACPI work +S: 12725 SW Millikan Way, Suite 400 +S: Beaverton, Oregon 97005 +S: USA + +N: Eberhard Mönkeberg +E: emoenke@gwdg.de +D: CDROM driver "sbpcd" (Matsushita/Panasonic/Soundblaster) +S: Ruhstrathöhe 2 b. +S: D-37085 Göttingen +S: Germany + +N: Thomas Molina +E: tmolina@cablespeed.com +D: bug fixes, documentation, minor hackery + +N: Paul Moore +E: paul.moore@hp.com +D: NetLabel author +S: Hewlett-Packard +S: 110 Spit Brook Road +S: Nashua, NH 03062 + +N: James Morris +E: jmorris@namei.org +W: http://namei.org/ +D: Netfilter, Linux Security Modules (LSM), SELinux, IPSec, +D: Crypto API, general networking, miscellaneous. +S: PO Box 707 +S: Spit Junction NSW 2088 +S: Australia + +N: David Mosberger-Tang +E: davidm@hpl.hp.com if IA-64 related, else David.Mosberger@acm.org +D: Linux/Alpha and Linux/ia64 +S: 35706 Runckel Lane +S: Fremont, California 94536 +S: USA + +N: Sam Mosel +E: sam.mosel@computer.org +D: Wacom Intuos USB Support +S: 22 Seaview St +S: Fullarton 5063 +S: South Australia + +N: Wolfgang Muees +E: wolfgang@iksw-muees.de +D: Auerswald USB driver + +N: Paul Mundt +E: paul.mundt@gmail.com +D: SuperH maintainer + +N: Ian A. Murdock +E: imurdock@gnu.ai.mit.edu +D: Creator of Debian distribution +S: 30 White Tail Lane +S: Lafayette, Indiana 47905 +S: USA + +N: Scott Murray +E: scottm@somanetworks.com +E: scott@spiteful.org +D: OPL3-SA2, OPL3-SA3 sound driver +D: CompactPCI hotplug core +D: Ziatech ZT5550 and generic CompactPCI hotplug drivers +S: Toronto, Ontario +S: Canada + +N: Zwane Mwaikambo +E: zwanem@gmail.com +D: Various driver hacking +D: Lowlevel x86 kernel hacking +D: General debugging +S: (ask for current address) +S: Tanzania + +N: Trond Myklebust +E: trond.myklebust@fys.uio.no +D: current NFS client hacker. +S: Dagaliveien 31e +S: N-0391 Oslo +S: Norway + +N: Johan Myreen +E: jem@iki.fi +D: PS/2 mouse driver writer etc. +S: Dragonvagen 1 A 13 +S: FIN-00330 Helsingfors +S: Finland + +N: Matija Nalis +E: mnalis@jagor.srce.hr +E: mnalis@voyager.hr +D: Maintainer of the Umsdos file system +S: Listopadska 7 +S: 10000 Zagreb +S: Croatia + +N: Jonathan Naylor +E: g4klx@g4klx.demon.co.uk +E: g4klx@amsat.org +W: http://zone.pspt.fi/~jsn/ +D: AX.25, NET/ROM and ROSE amateur radio protocol suites +D: CCITT X.25 PLP and LAPB. +S: 24 Castle View Drive +S: Cromford +S: Matlock +S: Derbyshire DE4 3RL +S: United Kingdom + +N: Ian S. Nelson +E: nelsonis@earthlink.net +P: 1024D/00D3D983 3EFD 7B86 B888 D7E2 29B6 9E97 576F 1B97 00D3 D983 +D: Minor mmap and ide hacks +S: 1370 Atlantis Ave. +S: Lafayette CO, 80026 +S: USA + +N: Russell Nelson +E: nelson@crynwr.com +W: http://www.crynwr.com/~nelson +P: 1024/83942741 FF 68 EE 27 A0 5A AA C3 F5 DC 05 62 BD 5B 20 2F +D: Author of cs89x0, maintainer of kernel changelog through 1.3.3 +D: Wrote many packet drivers, from which some Ethernet drivers are derived. +S: 521 Pleasant Valley Road +S: Potsdam, New York 13676 +S: USA + +N: Dave Neuer +E: dave.neuer@pobox.com +D: Helped implement support for Compaq's H31xx series iPAQs +D: Other mostly minor tweaks & bugfixes + +N: Michael Neuffer +E: mike@i-Connect.Net +E: neuffer@goofy.zdv.uni-mainz.de +W: http://www.i-Connect.Net/~mike/ +D: Developer and maintainer of the EATA-DMA SCSI driver +D: Co-developer EATA-PIO SCSI driver +D: /proc/scsi and assorted other snippets +S: Zum Schiersteiner Grund 2 +S: 55127 Mainz +S: Germany + +N: Gustavo Niemeyer +E: niemeyer@conectiva.com +W: https://moin.conectiva.com.br/GustavoNiemeyer +D: wl3501 PCMCIA wireless card initial support for wireless extensions in 2.4 +S: Conectiva S.A. +S: R. Tocantins 89 +S: 80050-430 Curitiba PR +S: Brazil + +N: David C. Niemi +E: niemi@tux.org +W: http://www.tux.org/~niemi/ +D: Assistant maintainer of Mtools, fdutils, and floppy driver +D: Administrator of Tux.Org Linux Server, http://www.tux.org +S: 2364 Old Trail Drive +S: Reston, Virginia 20191 +S: USA + +N: Fredrik Noring +E: noring@nocrew.org +W: http://www.lysator.liu.se/~noring/ +D: dsp56k device driver + +N: Michael O'Reilly +E: michael@iinet.com.au +E: oreillym@tartarus.uwa.edu.au +D: Wrote the original dynamic sized disk cache stuff. I think the only +D: part that remains is the GFP_KERNEL et al #defines. :) +S: 192 Nichsolson Road +S: Subiaco, 6008 +S: Perth, Western Australia +S: Australia + +N: Miguel Ojeda Sandonis +E: miguel.ojeda.sandonis@gmail.com +W: http://miguelojeda.es +W: http://jair.lab.fi.uva.es/~migojed/ +D: Author of the ks0108, cfag12864b and cfag12864bfb auxiliary display drivers. +D: Maintainer of the auxiliary display drivers tree (drivers/auxdisplay/*) +S: C/ Mieses 20, 9-B +S: Valladolid 47009 +S: Spain + +N: Jens Osterkamp +E: jens@de.ibm.com +D: Maintainer of Spidernet network driver for Cell + +N: Gadi Oxman +E: gadio@netvision.net.il +D: Original author and maintainer of IDE/ATAPI floppy/tape drivers + +N: Greg Page +E: gpage@sovereign.org +D: IPX development and support + +N: Venkatesh Pallipadi (Venki) +D: x86/HPET + +N: David Parsons +E: orc@pell.chi.il.us +D: improved memory detection code. + +N: Ivan Passos +E: ivan@cyclades.com +D: Author of the Cyclades-PC300 synchronous card driver +D: Maintainer of the Cyclom-Y/Cyclades-Z asynchronous card driver +S: Cyclades Corp +S: 41934 Christy St +S: Fremont, CA 94538 +S: USA + +N: Mikulas Patocka +E: mikulas@artax.karlin.mff.cuni.cz +W: http://artax.karlin.mff.cuni.cz/~mikulas/ +P: 1024/BB11D2D5 A0 F1 28 4A C4 14 1E CF 92 58 7A 8F 69 BC A4 D3 +D: Read/write HPFS filesystem +S: Weissova 8 +S: 644 00 Brno +S: Czech Republic + +N: Vojtech Pavlik +E: vojtech@suse.cz +D: Joystick driver +D: arcnet-hardware readme +D: Minor ARCnet hacking +D: USB (HID, ACM, Printer ...) +S: Ucitelska 1576 +S: Prague 8 +S: 182 00 Czech Republic + +N: Rick Payne +D: RFC2385 Support for TCP + +N: Barak A. Pearlmutter +E: bap@cs.unm.edu +W: http://www.cs.unm.edu/~bap/ +P: 512/602D785D 9B A1 83 CD EE CB AD 93 20 C6 4C B7 F5 E9 60 D4 +D: Author of mark-and-sweep GC integrated by Alan Cox +S: Computer Science Department +S: FEC 313 +S: University of New Mexico +S: Albuquerque, New Mexico 87131 +S: USA + +N: Avery Pennarun +E: apenwarr@worldvisions.ca +W: http://www.worldvisions.ca/~apenwarr/ +D: ARCnet driver +D: "make xconfig" improvements +D: Various minor hacking +S: RR #5, 497 Pole Line Road +S: Thunder Bay, Ontario +S: CANADA P7C 5M9 + +N: Inaky Perez-Gonzalez +E: inaky.perez-gonzalez@intel.com +E: linux-wimax@intel.com +E: inakypg@yahoo.com +D: WiMAX stack +D: Intel Wireless WiMAX Connection 2400 driver + +N: Yuri Per +E: yuri@pts.mipt.ru +D: Some smbfs fixes +S: Demonstratsii 8-382 +S: Tula 300000 +S: Russia + +N: Inaky Perez-Gonzalez +E: inaky.perez-gonzalez@intel.com +D: UWB stack, HWA-RC driver and HWA-HC drivers +D: Wireless USB additions to the USB stack +D: WiMedia Link Protocol bits and pieces + +N: Gordon Peters +E: GordPeters@smarttech.com +D: Isochronous receive for IEEE 1394 driver (OHCI module). +D: Bugfixes for the aforementioned. +S: Calgary, Alberta +S: Canada + +N: Johnnie Peters +E: jpeters@phx.mcd.mot.com +D: Motorola PowerPC changes for PReP +S: 2900 S. Diable Way +S: Tempe, Arizona 85282 +S: USA + +N: Kirk Petersen +E: kirk@speakeasy.org +W: http://www.speakeasy.org/~kirk/ +D: implemented kmod +D: modularized BSD Unix domain sockets + +N: Martin Kasper Petersen +E: mkp@mkp.net +D: PA-RISC port +D: XFS file system +D: kiobuf based block I/O work +S: 314 Frank St. +S: Ottawa, Ontario +S: Canada K2P 0X8 + +N: Mikael Pettersson +E: mikpelinux@gmail.com +D: Miscellaneous fixes + +N: Reed H. Petty +E: rhp@draper.net +W: http://www.draper.net +D: Loop device driver extensions +D: Encryption transfer modules (no export) +S: Post Office Box 1815 +S: Harrison, Arkansas 72602-1815 +S: USA + +N: Kai Petzke +E: petzke@teltarif.de +W: http://www.teltarif.de/ +P: 1024/B42868C1 D9 59 B9 98 BB 93 05 38 2E 3E 31 79 C3 65 5D E1 +D: Driver for Laser Magnetic Storage CD-ROM +D: Some kernel bug fixes +D: Port of the database Postgres +D: Book: "Linux verstehen und anwenden" (Hanser-Verlag) +S: Triftstra=DFe 55 +S: 13353 Berlin +S: Germany + +N: Emanuel Pirker +E: epirker@edu.uni-klu.ac.at +D: AIC5800 IEEE 1394, RAW I/O on 1394 +D: Starter of Linux1394 effort +S: ask per mail for current address + +N: Nicolas Pitre +E: nico@fluxnic.net +D: StrongARM SA1100 support integrator & hacker +D: Xscale PXA architecture +D: unified SMC 91C9x/91C11x ethernet driver (smc91x) +S: Montreal, Quebec, Canada + +N: Ken Pizzini +E: ken@halcyon.com +D: CDROM driver "sonycd535" (Sony CDU-535/531) + +N: Stelian Pop +E: stelian@popies.net +P: 1024D/EDBB6147 7B36 0E07 04BC 11DC A7A0 D3F7 7185 9E7A EDBB 6147 +D: random kernel hacks +S: Paimpont, France + +N: Pete Popov +E: pete_popov@yahoo.com +D: Linux/MIPS AMD/Alchemy Port and mips hacking and debugging +S: San Jose, CA 95134 +S: USA + +N: Matt Porter +E: mporter@kernel.crashing.org +D: Motorola PowerPC PReP support +D: cPCI PowerPC support +D: Embedded PowerPC 4xx/6xx/7xx/74xx support +S: Chandler, Arizona 85249 +S: USA + +N: Frederic Potter +E: fpotter@cirpack.com +D: Some PCI kernel support + +N: Rui Prior +E: rprior@inescn.pt +D: ATM device driver for NICStAR based cards + +N: Stefan Probst +E: sp@caldera.de +D: The Linux Support Team Erlangen, 1993-97 +S: Caldera (Deutschland) GmbH +S: Lazarettstrasse 8 +S: 91054 Erlangen +S: Germany + +N: Giuliano Procida +E: myxie@debian.org,gprocida@madge.com +D: Madge Ambassador driver (Collage 155 Server ATM adapter) +D: Madge Horizon driver (Collage 25 and 155 Client ATM adapters) +P: 1024/93898735 D3 9E F4 F7 6D 8D 2F 3A 38 BA 06 7C 2B 33 43 7D +S: Madge Networks +S: Framewood Road +S: Wexham SL3 6PJ +S: United Kingdom + +N: Richard Purdie +E: rpurdie@rpsys.net +D: Backlight subsystem maintainer +S: United Kingdom + +N: Daniel Quinlan +E: quinlan@pathname.com +W: http://www.pathname.com/~quinlan/ +D: FSSTND coordinator; FHS editor +D: random Linux documentation, patches, and hacks +S: 4390 Albany Drive #41A +S: San Jose, California 95129 +S: USA + +N: Juan Quintela +E: quintela@fi.udc.es +D: Memory Management hacking +S: LFCIA +S: Departamento de Computación +S: Universidade da Coruña +S: E-15071 +S: A Coruña +S: Spain + +N: Augusto Cesar Radtke +E: bishop@sekure.org +W: http://bishop.sekure.org +D: {copy,get,put}_user calls updates +D: Miscellaneous hacks +S: R. Otto Marquardt, 226 - Garcia +S: 89020-350 Blumenau - Santa Catarina +S: Brazil + +N: Goutham Rao +E: goutham.rao@intel.com +D: Linux/IA-64 +S: 2200 Mission College Blvd +S: Santa Clara, CA 95052 +S: USA + +N: Anil Ravindranath +E: anil_ravindranath@pmc-sierra.com +D: PMC-Sierra MaxRAID driver + +N: Eric S. Raymond +E: esr@thyrsus.com +W: http://www.tuxedo.org/~esr/ +D: terminfo master file maintainer +D: Editor: Installation HOWTO, Distributions HOWTO, XFree86 HOWTO +D: Author: fetchmail, Emacs VC mode, Emacs GUD mode +S: 6 Karen Drive +S: Malvern, Pennsylvania 19355 +S: USA + +N: Stefan Reinauer +E: stepan@linux.de +W: http://www.freiburg.linux.de/~stepan/ +D: Modularization of some filesystems +D: /proc/sound, minor fixes +S: Schlossbergring 9 +S: 79098 Freiburg +S: Germany + +N: Thomas Renninger +E: trenn@suse.de +D: cpupowerutils +S: SUSE Linux GmbH +S: Germany + +N: Joerg Reuter +E: jreuter@yaina.de +W: http://yaina.de/jreuter/ +W: http://www.qsl.net/dl1bke/ +D: Generic Z8530 driver, AX.25 DAMA slave implementation +D: Several AX.25 hacks + +N: Ricardo Ribalda Delgado +E: ricardo.ribalda@gmail.com +W: http://ribalda.com +D: PLX USB338x driver +D: PCA9634 driver +D: Option GTM671WFS +D: Fintek F81216A +D: AD5761 iio driver +D: Various kernel hacks +S: Qtechnology A/S +S: Valby Langgade 142 +S: 2500 Valby +S: Denmark + +N: Francois-Rene Rideau +E: fare@tunes.org +W: http://www.tunes.org/~fare +D: petty kernel janitor (byteorder, ufs) +S: 6, rue Augustin Thierry +S: 75019 Paris +S: France + +N: Rik van Riel +E: riel@redhat.com +W: http://www.surriel.com/ +D: Linux-MM site, Documentation/sysctl/*, swap/mm readaround +D: kswapd fixes, random kernel hacker, rmap VM, +D: nl.linux.org administrator, minor scheduler additions +S: Red Hat Boston +S: 3 Lan Drive +S: Westford, MA 01886 +S: USA + +N: Pekka Riikonen +E: priikone@poseidon.pspt.fi +E: priikone@ssh.com +D: Random kernel hacking and bug fixes +D: International kernel patch project +S: Kasarmikatu 11 A4 +S: 70110 Kuopio +S: Finland + +N: Tobias Ringström +E: tori@unhappy.mine.nu +D: Davicom DM9102(A)/DM9132/DM9801 fast ethernet driver + +N: Luca Risolia +E: luca.risolia@studio.unibo.it +P: 1024D/FCE635A4 88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4 +D: V4L driver for W996[87]CF JPEG USB Dual Mode Camera Chips +D: V4L2 driver for SN9C10x PC Camera Controllers +D: V4L2 driver for ET61X151 and ET61X251 PC Camera Controllers +D: V4L2 driver for ZC0301 Image Processor and Control Chip +S: Via Liberta' 41/A +S: Osio Sotto, 24046, Bergamo +S: Italy + +N: William E. Roadcap +E: roadcapw@cfw.com +W: http://www.cfw.com/~roadcapw +D: Author of menu based configuration tool, Menuconfig. +S: 1407 Broad Street +S: Waynesboro, Virginia 22980 +S: USA + +N: Andrew J. Robinson +E: arobinso@nyx.net +W: http://www.nyx.net/~arobinso +D: Hayes ESP serial port driver + +N: Florian La Roche +E: rzsfl@rz.uni-sb.de +E: flla@stud.uni-sb.de +D: Net programs and kernel net hacker +S: Gaildorfer Str. 27 +S: 7000 Stuttgart 50 +S: Germany + +N: Christoph Rohland +E: hans-christoph.rohland@sap.com +E: ch.rohland@gmx.net +D: shm fs, SYSV semaphores, af_unix +S: Neue Heimat Str. 8 +S: D-68789 St.Leon-Rot +S: Germany + +N: Thiago Berlitz Rondon +E: maluco@mileniumnet.com.br +W: http://vivaldi.linuxms.com.br/~maluco +D: Miscellaneous kernel hacker +S: R. Anhanguera, 1487 - Ipiranga +S: 79080-740 - Campo Grande - Mato Grosso do Sul +S: Brazil + +N: Stephen Rothwell +E: sfr@canb.auug.org.au +W: http://www.canb.auug.org.au/~sfr +P: 1024/BD8C7805 CD A4 9D 01 10 6E 7E 3B 91 88 FA D9 C8 40 AA 02 +D: Boot/setup/build work for setup > 2K +D: Author, APM driver +D: Directory notification +S: 66 Maltby Circuit +S: Wanniassa ACT 2903 +S: Australia + +N: Gerard Roudier +E: groudier@free.fr +D: Contributed to asynchronous read-ahead improvement +S: 21 Rue Carnot +S: 95170 Deuil La Barre +S: France + +N: Sebastien Rougeaux +E: Sebastien.Rougeaux@syseng.anu.edu.au +D: IEEE 1394 OHCI module +S: Research School of Information Science and Engineering +S: The Australian National University, ACT 0200 +S: Australia + +N: Aristeu Sergio Rozanski Filho +E: aris@cathedrallabs.org +D: Support for EtherExpress 10 ISA (i82595) in eepro driver +D: User level driver support for input +S: R. Jose Serrato, 130 - Santa Candida +S: 82640-320 - Curitiba - Paraná +S: Brazil + +N: Alessandro Rubini +E: rubini@ipvvis.unipv.it +D: the gpm mouse server and kernel support for it + +N: Philipp Rumpf +E: prumpf@tux.org +D: random bugfixes +S: Drausnickstrasse 29 +S: 91052 Erlangen +S: Germany + +N: Paul `Rusty' Russell +E: rusty@rustcorp.com.au +W: http://ozlabs.org/~rusty +D: Ruggedly handsome. +D: netfilter, ipchains with Michael Neuling. +S: 52 Moore St +S: Turner ACT 2612 +S: Australia + +N: Richard Russon (FlatCap) +E: kernel@flatcap.org +W: http://www.flatcap.org +D: NTFS support +D: LDM support (Win2000/XP Logical Disk Manager/Dynamic Disks) +S: 50 Swansea Road +S: Reading +S: United Kingdom + +N: Bill Ryder +E: bryder@sgi.com +D: FTDI_SIO usb/serial converter driver +W: http://reality.sgi.com/bryder_wellington/ftdi_sio +S: I/3 Walter St +S: Wellington +S: New Zealand + +N: Sampo Saaristo +E: sambo@cs.tut.fi +D: Co-author of Multi-Protocol Over ATM (MPOA) +S: Tampere University of Technology / Telecom lab +S: Hermiankatu 12C +S: FIN-33720 Tampere +S: Finland + +N: Thomas Sailer +E: t.sailer@alumni.ethz.ch +E: HB9JNX@HB9W.CHE.EU (packet radio) +D: Baycom driver +S: Markusstrasse 18 +S: 8006 Zuerich +S: Switzerland + +N: Manuel Estrada Sainz +D: Firmware loader (request_firmware) + +N: Wayne Salamon +E: wsalamon@tislabs.com +E: wsalamon@nai.com +D: portions of the Linux Security Module (LSM) framework and security modules + +N: Robert Sanders +E: gt8134b@prism.gatech.edu +D: Dosemu + +N: Duncan Sands +E: duncan.sands@free.fr +W: http://topo.math.u-psud.fr/~sands +D: Alcatel SpeedTouch USB driver +S: 69 rue Dunois +S: 75013 Paris +S: France + +N: Aleksa Sarai +E: cyphar@cyphar.com +W: https://www.cyphar.com/ +D: `pids` cgroup subsystem + +N: Dipankar Sarma +E: dipankar@in.ibm.com +D: RCU + +N: Hannu Savolainen +E: hannu@opensound.com +D: Maintainer of the sound drivers until 2.1.x days. +D: Original compressed boot image support. +S: Valurink. 4A11 +S: 03600 Karkkila +S: Finland + +N: Deepak Saxena +E: dsaxena@plexity.net +D: I2O kernel layer (config, block, core, pci, net). I2O disk support for LILO +D: XScale(IOP, IXP) porting and other random ARM bits +S: Portland, OR + +N: Eric Schenk +E: Eric.Schenk@dna.lth.se +D: Random kernel debugging. +D: SYSV Semaphore code rewrite. +D: Network layer debugging. +D: Dial on demand facility (diald). +S: Dag Hammerskjolds v. 3E +S: S-226 64 LUND +S: Sweden + +N: Henning P. Schmiedehausen +E: hps@tanstaafl.de +D: added PCI support to the serial driver +S: Buckenhof, Germany + +N: Michael Schmitz +E: +D: Macintosh IDE Driver + +N: Peter De Schrijver +E: stud11@cc4.kuleuven.ac.be +D: Mitsumi CD-ROM driver patches March version +S: Molenbaan 29 +S: B2240 Zandhoven +S: Belgium + +N: Martin Schulze +E: joey@linux.de +W: http://home.pages.de/~joey/ +D: Random Linux Hacker, Linux Promoter +D: CD-List, Books-List, Ex-FAQ +D: Linux-Support, -Mailbox, -Stammtisch +D: several improvements to system programs +S: Oldenburg +S: Germany + +N: Robert Schwebel +E: robert@schwebel.de +W: http://www.schwebel.de +D: Embedded hacker and book author, +D: AMD Elan support for Linux +S: Pengutronix +S: Braunschweiger Strasse 79 +S: 31134 Hildesheim +S: Germany + +N: Darren Senn +E: sinster@darkwater.com +D: Whatever I notice needs doing (so far: itimers, /proc) +S: Post Office Box 64132 +S: Sunnyvale, California 94088-4132 +S: USA + +N: Stas Sergeev +E: stsp@users.sourceforge.net +D: PCM PC-Speaker driver +D: misc fixes +S: Russia + +N: Simon Shapiro +E: shimon@i-Connect.Net +W: http://www.-i-Connect.Net/~shimon +D: SCSI debugging +D: Maintainer of the Debian Kernel packages +S: 14355 SW Allen Blvd., Suite #140 +S: Beaverton, Oregon 97008 +S: USA + +N: Mike Shaver +E: shaver@hungry.org +W: http://www.hungry.org/~shaver/ +D: MIPS work, /proc/sys/net, misc net hacking +S: 149 Union St. +S: Kingston, Ontario +S: Canada K7L 2P4 + +N: John Shifflett +E: john@geolog.com +E: jshiffle@netcom.com +D: Always IN2000 SCSI driver +D: wd33c93 SCSI driver (linux-m68k) +S: San Jose, California +S: USA + +N: Robert Siemer +E: Robert.Siemer@gmx.de +P: 2048/C99A4289 2F DC 17 2E 56 62 01 C8 3D F2 AC 09 F2 E5 DD EE +D: miroSOUND PCM20 radio RDS driver, ACI rewrite +S: Klosterweg 28 / i309 +S: 76131 Karlsruhe +S: Germany + +N: James Simmons +E: jsimmons@infradead.org +E: jsimmons@users.sf.net +D: Frame buffer device maintainer +D: input layer development +D: tty/console layer +D: various mipsel devices +S: 115 Carmel Avenue +S: El Cerrito CA 94530 +S: USA + +N: Jaspreet Singh +E: jaspreet@sangoma.com +W: www.sangoma.com +D: WANPIPE drivers & API Support for Sangoma S508/FT1 cards +S: Sangoma Technologies Inc., +S: 1001 Denison Street +S: Suite 101 +S: Markham, Ontario L3R 2Z6 +S: Canada + +N: Rick Sladkey +E: jrs@world.std.com +D: utility hacker: Emacs, NFS server, mount, kmem-ps, UPS debugger, strace, GDB +D: library hacker: RPC, profil(3), realpath(3), regexp.h +D: kernel hacker: unnamed block devs, NFS client, fast select, precision timer +S: 24 Avon Place +S: Arlington, Massachusetts 02174 +S: USA + +N: Craig Small +E: csmall@triode.apana.org.au +E: vk2xlz@gonzo.vk2xlz.ampr.org (packet radio) +D: Gracilis PackeTwin device driver +D: RSPF daemon +S: 10 Stockalls Place +S: Minto, NSW, 2566 +S: Australia + +N: Stephen Smalley +E: sds@tycho.nsa.gov +D: portions of the Linux Security Module (LSM) framework and security modules + +N: Chris Smith +E: csmith@convex.com +D: Read only HPFS filesystem +S: Richardson, Texas +S: USA + +N: Christopher Smith +E: x@xman.org +D: Tulip net driver hacker + +N: Mark Smith +E: mark.smith@comdev.cc +D: Multicast support in bonding driver + +N: Miquel van Smoorenburg +E: miquels@cistron.nl +D: Kernel and net hacker. Sysvinit, minicom. doing Debian stuff. +S: Cistron Internet Services +S: PO-Box 297 +S: 2400 AG, Alphen aan den Rijn +S: The Netherlands + +N: Scott Snyder +E: snyder@fnald0.fnal.gov +D: ATAPI cdrom driver +S: MS 352, Fermilab +S: Post Office Box 500 +S: Batavia, Illinois 60510 +S: USA + +N: Leo Spiekman +E: leo@netlabs.net +W: http://www.netlabs.net/hp/leo/ +D: Optics Storage 8000AT cdrom driver +S: Cliffwood, New Jersey 07721 +S: USA + +N: Manfred Spraul +E: manfred@colorfullife.com +W: http://www.colorfullife.com/~manfred +D: Lots of tiny hacks. Larger improvements to SysV IPC msg, +D: slab, pipe, select. +S: 71701 Schwieberdingen +S: Germany + +N: Andrew Stanley-Jones +E: asj@lanmedia.com +D: LanMedia Corp. Device WAN card device driver +S: #102, 686 W. Maude Ave +S: Sunyvale, CA 94086 +S: USA + +N: Michael Still +E: mikal@stillhq.com +W: http://www.stillhq.com +D: Various janitorial patches +D: mandocs and mandocs_install build targets +S: (Email me and ask) +S: Australia + +N: Henrik Storner +E: storner@image.dk +W: http://www.image.dk/~storner/ +W: http://www.sslug.dk/ +D: Configure script: Invented tristate for module-configuration +D: vfat/msdos integration, kerneld docs, Linux promotion +D: Miscellaneous bug-fixes +S: Chr. Winthersvej 1 B, st.th. +S: DK-1860 Frederiksberg C +S: Denmark + +N: Drew Sullivan +E: drew@ss.org +W: http://www.ss.org/ +P: 1024/ACFFA969 5A 9C 42 AB E4 24 82 31 99 56 00 BF D3 2B 25 46 +D: iBCS2 developer +S: 22 Irvington Cres. +S: Willowdale, Ontario +S: Canada M2N 2Z1 + +N: Adam Sulmicki +E: adam@cfar.umd.edu +W: http://www.eax.com +D: core networking fixes +D: patch-kernel enhancements +D: misc kernel fixes and updates + +N: Adrian Sun +E: asun@cobaltnet.com +D: hfs support +D: alpha rtc port, random appletalk fixes +S: Department of Zoology, University of Washington +S: Seattle, WA 98195-1800 +S: USA + +N: Eugene Surovegin +E: ebs@ebshome.net +W: http://kernel.ebshome.net/ +P: 1024D/AE5467F1 FF22 39F1 6728 89F6 6E6C 2365 7602 F33D AE54 67F1 +D: Embedded PowerPC 4xx: EMAC, I2C, PIC and random hacks/fixes +S: Sunnyvale, California 94085 +S: USA + +N: Corey Thomas +E: corey@world.std.com +W: http://world.std.com/~corey/index.html +D: Raylink/WebGear wireless LAN device driver (ray_cs) author +S: 145 Howard St. +S: Northborough, MA 01532 +S: USA + +N: Doug Thompson +E: dougthompson@xmission.com +D: EDAC + +N: Tommy Thorn +E: Tommy.Thorn@irisa.fr +W: http://www.irisa.fr/prive/thorn/index.html +P: 512/B4AFC909 BC BF 6D B1 52 26 1E D6 E3 2F A3 24 2A 84 FE 21 +D: Device driver hacker (aha1542 & plip) +S: IRISA +S: Universit=E9 de Rennes I +S: F-35042 Rennes Cedex +S: France + +N: Urs Thuermann +E: urs.thuermann@volkswagen.de +W: http://www.volkswagen.de +D: Controller Area Network (network layer core) +S: Brieffach 1776 +S: 38436 Wolfsburg +S: Germany + +N: Jon Tombs +E: jon@gte.esi.us.es +W: http://www.esi.us.es/~jon +D: NFS mmap() +D: XF86_S3 +D: Kernel modules +D: Parts of various other programs (xfig, open, ...) +S: C/ Federico Garcia Lorca 1 10-A +S: Sevilla 41005 +S: Spain + +N: Linus Torvalds +E: torvalds@linux-foundation.org +D: Original kernel hacker +S: Portland, Oregon 97005 +S: USA + +N: Marcelo Tosatti +E: marcelo@kvack.org +D: v2.4 kernel maintainer +S: Brazil + +N: Stefan Traby +E: stefan@quant-x.com +D: Minor Alpha kernel hacks +S: Mitterlasznitzstr. 13 +S: 8302 Nestelbach +S: Austria + +N: Jeff Tranter +E: tranter@pobox.com +D: Enhancements to Joystick driver +D: Author of Sound HOWTO and CD-ROM HOWTO +D: Author of several small utilities +D: (bogomips, scope, eject, statserial) +S: 1 Laurie Court +S: Kanata, Ontario +S: Canada K2L 1S2 + +N: Andrew Tridgell +E: tridge@samba.org +W: http://samba.org/tridge/ +D: dosemu, networking, samba +S: 3 Ballow Crescent +S: MacGregor A.C.T 2615 +S: Australia + +N: Josh Triplett +E: josh@joshtriplett.org +P: 4096R/8AFF873D 758E 5042 E397 4BA3 3A9C 1E67 0ED9 A3DF 8AFF 873D +D: RCU and rcutorture +D: lock annotations, finding and fixing lock bugs +D: kernel tinification + +N: Winfried Trümper +E: winni@xpilot.org +W: http://www.shop.de/~winni/ +D: German HOWTO, Crash-Kurs Linux (German, 100 comprehensive pages) +D: CD-Writing HOWTO, various mini-HOWTOs +D: One-week tutorials on Linux twice a year (free of charge) +D: Linux-Workshop Köln (aka LUG Cologne, Germany), Installfests +S: Tacitusstr. 6 +S: D-50968 Köln + +N: Tsu-Sheng Tsao +E: tsusheng@scf.usc.edu +D: IGMP(Internet Group Management Protocol) version 2 +S: 2F 14 ALY 31 LN 166 SEC 1 SHIH-PEI RD +S: Taipei +S: Taiwan 112 +S: Republic of China +S: 24335 Delta Drive +S: Diamond Bar, California 91765 +S: USA + +N: Theodore Ts'o +E: tytso@mit.edu +D: Random Linux hacker +D: Maintainer of tsx-11.mit.edu ftp archive +D: Maintainer of c.o.l.* Usenet<->mail gateway +D: Author of serial driver +D: Author of the new e2fsck +D: Author of job control and system call restart code +D: Author of ramdisk device driver +D: Author of loopback device driver +D: Author of /dev/random driver +S: MIT Room E40-343 +S: 1 Amherst Street +S: Cambridge, Massachusetts 02139 +S: USA + +N: Simmule Turner +E: sturner@tele-tv.com +D: Added swapping to filesystem +S: 4226 Landgreen Street +S: Rockville, Maryland 20853 +S: USA + +N: Stephen Tweedie +E: sct@redhat.com +P: 1024/E7A417AD E2 FE A4 20 34 EC ED FC 7D 7E 67 8D E0 31 D1 69 +P: 1024D/43BE7544 D2A4 8556 08E6 90E7 076C BA3F 243F 20A4 43BE 7544 +D: Second extended file system developer +D: General filesystem hacker +D: kswap vm management code +S: 44 Campbell Park Crescent +S: Edinburgh EH13 0HT +S: United Kingdom + +N: Thomas Uhl +E: uhl@sun1.rz.fh-heilbronn.de +D: Application programmer +D: Linux promoter +D: Author of a German book on Linux +S: Obere Heerbergstrasse 17 +S: 97078 Wuerzburg +S: Germany + +N: Jason Uhlenkott +E: juhlenko@akamai.com +D: I3000 EDAC driver + +N: Greg Ungerer +E: gerg@snapgear.com +D: uClinux kernel hacker +D: Port uClinux to the Motorola ColdFire CPU +D: Author of Stallion multiport serial drivers +S: SnapGear Inc. +S: 825 Stanley St +S: Woolloongabba. QLD. 4102 +S: Australia + +N: Jeffrey A. Uphoff +E: juphoff@transmeta.com +E: jeff.uphoff@linux.org +P: 1024/9ED505C5 D7 BB CA AA 10 45 40 1B 16 19 0A C0 38 A0 3E CB +D: Linux Security/Alert mailing lists' moderator/maintainer. +D: NSM (rpc.statd) developer. +D: PAM S/Key module developer. +D: 'dip' contributor. +D: AIPS port, astronomical community support. +S: Transmeta Corporation +S: 2540 Mission College Blvd. +S: Santa Clara, CA 95054 +S: USA + +N: Matthias Urlichs +E: smurf@smurf.noris.de +E: smurf@debian.org +E: matthias@urlichs.de +D: Consultant, developer, kernel hacker +D: In a previous life, worked on Streams/ISDN/BSD networking code for Linux +S: Schleiermacherstrasse 12 +S: 90491 Nuernberg +S: Germany + +N: Geert Uytterhoeven +E: geert@linux-m68k.org +W: http://users.telenet.be/geertu/ +P: 4096R/4804B4BC3F55EEFB 750D 82B0 A781 5431 5E25 925B 4804 B4BC 3F55 EEFB +D: m68k/Amiga and PPC/CHRP Longtrail coordinator +D: Frame buffer device and XF68_FBDev maintainer +D: m68k IDE maintainer +D: Amiga Zorro maintainer +D: Amiga Buddha and Catweasel chipset IDE +D: Atari Falcon chipset IDE +D: Amiga Gayle chipset IDE +D: mipsel NEC DDB Vrc-5074 +S: Haterbeekstraat 55B +S: B-3200 Aarschot +S: Belgium + +N: Chris Vance +E: cvance@tislabs.com +E: cvance@nai.com +D: portions of the Linux Security Module (LSM) framework and security modules + +N: Petr Vandrovec +E: petr@vandrovec.name +D: Small contributions to ncpfs +D: Matrox framebuffer driver +S: 21513 Conradia Ct +S: Cupertino, CA 95014 +S: USA + +N: Thibaut Varene +E: T-Bone@parisc-linux.org +W: http://www.parisc-linux.org/~varenet/ +P: 1024D/B7D2F063 E67C 0D43 A75E 12A5 BB1C FA2F 1E32 C3DA B7D2 F063 +D: PA-RISC port minion, PDC and GSCPS2 drivers, debuglocks and other bits +D: Some ARM at91rm9200 bits, S1D13XXX FB driver, random patches here and there +D: AD1889 sound driver +S: Paris, France + +N: Heikki Vatiainen +E: hessu@cs.tut.fi +D: Co-author of Multi-Protocol Over ATM (MPOA), some LANE hacks +S: Tampere University of Technology / Telecom lab +S: Hermiankatu 12C +S: FIN-33720 Tampere +S: Finland + +N: Andrew Veliath +E: andrewtv@usa.net +D: Turtle Beach MultiSound sound driver +S: USA + +N: Dirk Verworner +D: Co-author of German book ``Linux-Kernel-Programmierung'' +D: Co-founder of Berlin Linux User Group + +N: Andrew Victor +E: linux@maxim.org.za +W: http://maxim.org.za/at91_26.html +D: First maintainer of Atmel ARM-based SoC, aka AT91 +D: Introduced support for at91rm9200, the first chip of AT91 family +S: South Africa + +N: Riku Voipio +E: riku.voipio@iki.fi +D: Author of PCA9532 LED and Fintek f75375s hwmon driver +D: Some random ARM board patches +S: Finland + +N: Patrick Volkerding +E: volkerdi@ftp.cdrom.com +D: Produced the Slackware distribution, updated the SVGAlib +D: patches for ghostscript, worked on color 'ls', etc. +S: 301 15th Street S. +S: Moorhead, Minnesota 56560 +S: USA + +N: Jos Vos +E: jos@xos.nl +W: http://www.xos.nl/ +D: Various IP firewall updates, ipfwadm +S: X/OS Experts in Open Systems BV +S: Kruislaan 419 +S: 1098 VA Amsterdam +S: The Netherlands + +N: Jeroen Vreeken +E: pe1rxq@amsat.org +W: http://www.chello.nl/~j.vreeken/ +D: SE401 usb webcam driver +D: ZD1201 usb wireless lan driver +S: Maastrichterweg 63 +S: 5554 GG Valkenswaard +S: The Netherlands + +N: Mark Wallis +E: mwallis@serialmonkey.com +W: http://mark.serialmonkey.com +D: Ralink rt2x00 WLAN driver +S: Newcastle, Australia + +N: Peter Shaobo Wang +E: pwang@mmdcorp.com +W: http://www.mmdcorp.com/pw/linux +D: Driver for Interphase ATM (i)Chip SAR adapter card family (x575, x525, x531). +S: 1513 Brewster Dr. +S: Carrollton, TX 75010 +S: USA + +N: Tim Waugh +E: tim@cyberelk.net +D: Co-architect of the parallel-port sharing system +S: 17 Curling Vale +S: GUILDFORD +S: Surrey +S: GU2 7PJ +S: United Kingdom + +N: Juergen Weigert +E: jnweiger@immd4.informatik.uni-erlangen.de +D: The Linux Support Team Erlangen + +N: David Weinehall +E: tao@acc.umu.se +P: 1024D/DC47CA16 7ACE 0FB0 7A74 F994 9B36 E1D1 D14E 8526 DC47 CA16 +W: http://www.acc.umu.se/~tao/ +D: v2.0 kernel maintainer +D: Fixes for the NE/2-driver +D: Miscellaneous MCA-support +D: Cleanup of the Config-files + +N: Matt Welsh +E: mdw@metalab.unc.edu +W: http://www.cs.berkeley.edu/~mdw +D: Original Linux Documentation Project coordinator +D: Author, "Running Linux" (O'Reilly) +D: Author, "Linux Installation and Getting Started" (LDP) and several HOWTOs +D: Linuxdoc-SGML formatting system (now SGML-Tools) +D: Device drivers for various high-speed network interfaces (Myrinet, ATM) +D: Keithley DAS1200 device driver +D: Original maintainer of sunsite WWW and FTP sites +D: Original moderator of c.o.l.announce and c.o.l.answers +S: Computer Science Division +S: UC Berkeley +S: Berkeley, CA 94720-1776 +S: USA + +N: Harald Welte +E: laforge@netfilter.org +P: 1024D/30F48BFF DBDE 6912 8831 9A53 879B 9190 5DA5 C655 30F4 8BFF +W: http://gnumonks.org/users/laforge +D: netfilter: new nat helper infrastructure +D: netfilter: ULOG, ECN, DSCP target +D: netfilter: TTL match +D: netfilter: IPv6 mangle table +D: netfilter: various other hacks +S: Berlin +S: Germany + +N: Bill Wendling +E: wendling@ganymede.isdn.uiuc.edu +W: http://www.ncsa.uiuc.edu/~wendling/ +D: Various random hacks. Mostly on poll/select logic. +S: 605 E. Springfield Ave. +S: Champaign, IL 61820 +S: USA + +N: Mike Westall +D: IBM Turboways 25 ATM Device Driver +E: westall@cs.clemson.edu +S: Department of Computer Science +S: Clemson University +S: Clemson SC 29634 USA + +N: Greg Wettstein +E: greg@wind.rmcc.com +D: Filesystem valid flag for MINIX filesystem. +D: Minor kernel debugging. +D: Development and maintenance of sysklogd. +D: Monitoring of development kernels for long-term stability. +D: Early implementations of Linux in a commercial environment. +S: Dr. Greg Wettstein, Ph.D. +S: Oncology Research Division Computing Facility +S: Roger Maris Cancer Center +S: 820 4th St. N. +S: Fargo, North Dakota 58122 +S: USA + +N: Steven Whitehouse +E: steve@chygwyn.com +W: http://www.chygwyn.com/~steve +D: Linux DECnet project +D: Minor debugging of other networking protocols. +D: Misc bug fixes and GFS2 filesystem development + +N: Hans-Joachim Widmaier +E: hjw@zvw.de +D: AFFS rewrite +S: Eichenweg 16 +S: 73650 Winterbach +S: Germany + +N: Urban Widmark +E: urban@svenskatest.se +D: via-rhine, misc net driver hacking + +N: Marco van Wieringen +E: mvw@planets.elm.net +D: Author of process accounting and diskquota +S: Breeburgsingel 12 +S: 2135 CN Hoofddorp +S: The Netherlands + +N: Matthew Wilcox +E: matthew@wil.cx +W: ftp://ftp.uk.linux.org/pub/linux/people/willy/ +D: Linux/PARISC hacker. Filesystem hacker. Random other hacking. Custom +D: PPC port hacking. + +N: G\"unter Windau +E: gunter@mbfys.kun.nl +D: Some bug fixes in the polling printer driver (lp.c) +S: University of Nijmegen +S: Geert-Grooteplein Noord 21 +S: 6525 EZ Nijmegen +S: The Netherlands + +N: Ulrich Windl +E: Ulrich.Windl@rz.uni-regensburg.de +P: 1024/E843660D CF D7 43 A1 5A 49 14 25 7C 04 A0 6E 4C 3A AC 6D +D: Supports NTP on Linux. Added PPS code. Fixed bugs in adjtimex(). +S: Alte Regensburger Str. 11a +S: 93149 Nittenau +S: Germany + +N: Gertjan van Wingerde +E: gwingerde@gmail.com +D: Ralink rt2x00 WLAN driver +D: Minix V2 file-system +D: Misc fixes +S: Geessinkweg 177 +S: 7544 TX Enschede +S: The Netherlands + +N: Lars Wirzenius +E: liw@iki.fi +D: Linux System Administrator's Guide, author, former maintainer +D: comp.os.linux.announce, former moderator +D: Linux Documentation Project, co-founder +D: Original sprintf in kernel +D: Original kernel README (for version 0.97) +D: Linux News (electronic magazine, now dead), founder and former editor +D: Meta-FAQ, originator, former maintainer +D: INFO-SHEET, former maintainer +D: Author of the longest-living linux bug + +N: Jonathan Woithe +E: jwoithe@just42.net +W: http:/www.just42.net/jwoithe +D: ALS-007 sound card extensions to Sound Blaster driver +S: 20 Jordan St +S: Valley View, SA 5093 +S: Australia + +N: Clifford Wolf +E: god@clifford.at +W: http://www.clifford.at/ +D: Menuconfig/lxdialog improvement +S: Foehrengasse 16 +S: A-2333 Leopoldsdorf b. Wien +S: Austria + +N: Roger E. Wolff +E: R.E.Wolff@BitWizard.nl +D: Written kmalloc/kfree +D: Written Specialix IO8+ driver +D: Written Specialix SX driver +S: van Bronckhorststraat 12 +S: 2612 XV Delft +S: The Netherlands + +N: Thomas Woller +D: CS461x Cirrus Logic sound driver + +N: David Woodhouse +E: dwmw2@infradead.org +D: JFFS2 file system, Memory Technology Device subsystem, +D: various other stuff that annoyed me by not working. +S: c/o Intel Corporation +S: Pipers Way +S: Swindon. SN3 1RJ +S: England + +N: Chris Wright +E: chrisw@sous-sol.org +D: hacking on LSM framework and security modules. +S: Portland, OR +S: USA + +N: Michal Wronski +E: michal.wronski@gmail.com +D: POSIX message queues fs (with K. Benedyczak) +S: Krakow +S: Poland + +N: Frank Xia +E: qx@math.columbia.edu +D: Xiafs filesystem [defunct] +S: 542 West 112th Street, 5N +S: New York, New York 10025 +S: USA + +N: Li Yang +E: leoli@freescale.com +D: Freescale Highspeed USB device driver +D: Freescale QE SoC support and Ethernet driver +S: B-1206 Jingmao Guojigongyu +S: 16 Baliqiao Nanjie, Beijing 101100 +S: People's Repulic of China + +N: Victor Yodaiken +E: yodaiken@fsmlabs.com +D: RTLinux (RealTime Linux) +S: POB 1822 +S: Socorro NM, 87801 +S: USA + +N: Hiroshi YOKOTA +E: yokota@netlab.is.tsukuba.ac.jp +D: Workbit NinjaSCSI-3/32Bi PCMCIA driver +D: Workbit NinjaSCSI-32Bi/UDE driver +S: Japan + +N: Hideaki YOSHIFUJI +E: hideaki@yoshifuji.org +E: yoshfuji@linux-ipv6.org +W: http://www.yoshifuji.org/~hideaki/ +P: 1024D/E0620EEA 9022 65EB 1ECF 3AD1 0BDF 80D8 4807 F894 E062 0EEA +D: IPv6 and other networking related stuff +D: USAGI/WIDE Project, Keio University +S: Jeunet Palace Kawasaki #1-201, 10-2, Furukawa-cho, Saiwai-ku +S: Kawasaki, Kanagawa 212-0025 +S: Japan + +N: Eric Youngdale +E: eric@andante.org +W: http://www.andante.org +D: General kernel hacker +D: SCSI iso9660 and ELF +S: 6389 Hawk View Lane +S: Alexandria, Virginia 22312 +S: USA + +N: Niibe Yutaka +E: gniibe@mri.co.jp +D: PLIP driver +D: Asynchronous socket I/O in the NET code +S: Mitsubishi Research Institute, Inc. +S: ARCO Tower 1-8-1 Shimomeguro Meguro-ku +S: Tokyo 153 +S: Japan + +N: James R. Van Zandt +E: jrv@vanzandt.mv.com +P: 1024/E298966D F0 37 4F FD E5 7E C5 E6 F1 A0 1E 22 6F 46 DA 0C +D: Author and maintainer of the Double Talk speech synthesizer driver +S: 27 Spencer Drive +S: Nashua, New Hampshire 03062 +S: USA + +N: Orest Zborowski +E: orestz@eskimo.com +D: XFree86 and kernel development +S: 1507 145th Place SE #B5 +S: Bellevue, Washington 98007 +S: USA + +N: Richard Zidlicky +E: rz@linux-m68k.org, rdzidlic@geocities.com +W: http://www.geocities.com/rdzidlic +D: Q40 port - see arch/m68k/q40/README +D: various m68k hacks +S: Germany + +N: Werner Zimmermann +E: Werner.Zimmermann@fht-esslingen.de +D: CDROM driver "aztcd" (Aztech/Okano/Orchid/Wearnes) +S: Flandernstrasse 101 +S: D-73732 Esslingen +S: Germany + +N: Roman Zippel +E: zippel@linux-m68k.org +D: AFFS and HFS filesystems, m68k maintainer, new kernel configuration in 2.5 + +N: Leonard N. Zubkoff +W: http://www.dandelion.com/Linux/ +D: BusLogic SCSI driver +D: Mylex DAC960 PCI RAID driver +D: Miscellaneous kernel fixes + +N: Alessandro Zummo +E: a.zummo@towertech.it +D: CMI8330 support is sb_card.c +D: ISAPnP fixes in sb_card.c +D: ZyXEL omni.net lcd plus driver +D: RTC subsystem +S: Italy + +N: Marc Zyngier +E: maz@wild-wind.fr.eu.org +W: http://www.misterjones.org +D: MD driver +D: EISA/sysfs subsystem +S: France + + +# Don't add your name here, unless you really _are_ after Marc +# alphabetically. Leonard used to be very proud of being the +# last entry, and he'll get positively pissed if he can't even +# be second-to-last. (and this file really _is_ supposed to be +# in alphabetic order)
diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 0000000..e74fec8 --- /dev/null +++ b/Documentation/.gitignore
@@ -0,0 +1,2 @@ +output +*.pyc
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX new file mode 100644 index 0000000..4a5a887 --- /dev/null +++ b/Documentation/00-INDEX
@@ -0,0 +1,492 @@ + +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 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@listserv.linux.or.jp), at + http://linuxjf.sourceforge.jp/ + +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 maintainers expect the C code in the kernel to look. +DMA-API.txt + - DMA API, pci_ API & extensions for non-consistent memory machines. +DMA-API-HOWTO.txt + - Dynamic DMA mapping Guide +DMA-ISA-LPC.txt + - How to do DMA with ISA (and LPC) devices. +DMA-attributes.txt + - listing of the various possible attributes a DMA region can have +DocBook/ + - directory with DocBook templates etc. for kernel documentation. +EDID/ + - directory with info on customizing EDID for broken gfx/displays. +HOWTO + - the process and procedures of how to do Linux kernel development. +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-domain.txt + - info on interrupt numbering and setting up IRQ domains. +IRQ.txt + - description of what an IRQ is. +Intel-IOMMU.txt + - basic info on the Intel IOMMU virtualization support. +Makefile + - This file does nothing. Removing it breaks make htmldocs and + make distclean. +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. +arm64/ + - directory with info about Linux on the 64 bit ARM architecture. +assoc_array.txt + - generic associative array intro. +atomic_ops.txt + - semantics and behavior of atomic and bitmask operations. +auxdisplay/ + - misc. LCD driver documentation (cfag12864b, ks0108). +backlight/ + - directory with info on controlling backlights in flat panel displays +bad_memory.txt + - how to use kernel parameters to exclude bad RAM regions. +basic_profiling.txt + - basic instructions for those who wants to profile Linux kernel. +bcache.txt + - Block-layer cache on fast SSDs to improve slow (raid) I/O performance. +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 +braille-console.txt + - info on how to use serial devices for Braille support. +bt8xxgpio.txt + - info on how to modify a bt8xx video card for GPIO usage. +btmrvl.txt + - info on Marvell Bluetooth driver usage. +bus-devices/ + - directory with info on TI GPMC (General Purpose Memory Controller) +bus-virt-phys-mapping.txt + - how to access I/O mapped memory from within device drivers. +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. +circular-buffers.txt + - how to make use of the existing circular buffer infrastructure +clk.txt + - info on the common clock framework +coccinelle.txt + - info on how to get and use the Coccinelle code checking tool. +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. +crc32.txt + - brief tutorial on CRC computation +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. +debugging-via-ohci1394.txt + - how to use firewire like a hardware debugger memory reader. +dell_rbu.txt + - document demonstrating the use of the Dell Remote BIOS Update driver. +development-process/ + - how to work with the mainline kernel development process. +device-mapper/ + - directory with info on Device Mapper. +devices.txt + - plain ASCII listing of all the nodes in /dev/ with major minor #'s. +devicetree/ + - directory with info on device tree files used by OF/PowerPC/ARM +digsig.txt + -info on the Digital Signature Verification API +dma-buf-sharing.txt + - the DMA Buffer Sharing API Guide +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. +dynamic-debug-howto.txt + - how to use the dynamic debug (dyndbg) feature. +early-userspace/ + - info about initramfs, klibc, and userspace early during boot. +edac.txt + - information on EDAC - Error Detection And Correction +efi-stub.txt + - How to use the EFI boot stub to bypass GRUB or elilo on EFI systems. +eisa.txt + - info on EISA bus support. +email-clients.txt + - info on how to use e-mail to send un-mangled (git) patches. +extcon/ + - directory with porting guide for Android kernel switch driver. +fault-injection/ + - dir with docs about the fault injection capabilities infrastructure. +fb/ + - directory with info on the frame buffer graphics abstraction layer. +filesystems/ + - info on the vfs and the various filesystems that Linux supports. +firmware_class/ + - request_firmware() hotplug interface info. +flexible-arrays.txt + - how to make use of flexible sized arrays in linux +fmc/ + - information about the FMC bus abstraction +frv/ + - Fujitsu FR-V Linux documentation. +futex-requeue-pi.txt + - info on requeueing of tasks from a non-PI futex to a PI futex +gcov.txt + - use of GCC's coverage testing tool "gcov" with the Linux kernel +gpio/ + - gpio related documentation +hid/ + - directory with information on human interface devices +highuid.txt + - notes on the change from 16 bit to 32 bit user/group IDs. +hsi.txt + - HSI subsystem overview. +hwspinlock.txt + - hardware spinlock provides hardware assistance for synchronization +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. +init.txt + - what to do when the kernel can't find the 1st process to run. +initrd.txt + - how to use the RAM disk as an initial/temporary root filesystem. +input/ + - info on Linux input device support. +intel_txt.txt + - info on intel Trusted Execution Technology (intel TXT). +io-mapping.txt + - description of io_mapping functions in linux/io-mapping.h +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). +ja_JP/ + - directory with Japanese translations of various documents +kbuild/ + - directory with info about the kernel build process. +kdump/ + - directory with mini HowTo on getting the crash dump code to work. +kernel-docs.txt + - listing of various WWW + books that document kernel internals. +kernel-documentation.rst + - how to write and format reStructuredText kernel documentation +kernel-parameters.txt + - summary listing of command line / boot prompt args for the kernel. +kernel-per-CPU-kthreads.txt + - List of all per-CPU kthreads and how they introduce jitter. +kmemcheck.txt + - info on dynamic checker that detects uses of uninitialized memory. +kmemleak.txt + - info on how to make use of the kernel memory leak detection system +ko_KR/ + - directory with Korean translations of various documents +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. +kselftest.txt + - small unittests for (some) individual codepaths in the kernel. +laptops/ + - directory with laptop related info and laptop driver documentation. +ldm.txt + - a brief description of LDM (Windows Dynamic Disks). +leds/ + - directory with info about LED handling under Linux. +local_ops.txt + - semantics and behavior of local atomic operations. +locking/ + - directory with info about kernel locking primitives +lockup-watchdogs.txt + - info on soft and hard lockup detectors (aka nmi_watchdog). +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. +lzo.txt + - kernel LZO decompressor input formats +m68k/ + - directory with info about Linux on Motorola 68k architecture. +magic-number.txt + - list of magic numbers used to mark/protect kernel data structures. +mailbox.txt + - How to write drivers for the common mailbox framework (IPC). +md.txt + - info on boot arguments for the multiple devices driver. +media-framework.txt + - info on media framework, its data structures, functions and usage. +memory-barriers.txt + - info on Linux kernel memory barriers. +memory-devices/ + - directory with info on parts like the Texas Instruments EMIF driver +memory-hotplug.txt + - Hotpluggable memory support, how to use and current status. +metag/ + - directory with info about Linux on Meta architecture. +mips/ + - directory with info about Linux on MIPS architecture. +misc-devices/ + - directory with info about devices using the misc dev subsystem +mmc/ + - directory with info about the MMC subsystem +mn10300/ + - directory with info about the mn10300 architecture port +module-signing.txt + - Kernel module signing for increased security when loading modules. +mtd/ + - directory with info about memory technology devices (flash) +mono.txt + - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. +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. +nfc/ + - directory relating info about Near Field Communications support. +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. +padata.txt + - An introduction to the "padata" parallel execution API +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. +percpu-rw-semaphore.txt + - RCU based read-write semaphore optimized for locking for reading +phy.txt + - Description of the generic PHY framework. +pi-futex.txt + - documentation on lightweight priority inheritance futexes. +pinctrl.txt + - info on pinctrl subsystem and the PINMUX/PINCONF and drivers +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. +prctl/ + - directory with info on the priveledge control subsystem +preempt-locking.txt + - info on locking under a preemptive kernel. +printk-formats.txt + - how to get printk format specifiers right +pps/ + - directory with information on the pulse-per-second support +ptp/ + - directory with info on support for IEEE 1588 PTP clocks in Linux. +pwm.txt + - info on the pulse width modulation driver subsystem +ramoops.txt + - documentation of the ramoops oops/panic logging module. +rapidio/ + - directory with info on RapidIO packet-based fabric interconnect +rbtree.txt + - info on what red-black trees are and what they are for. +remoteproc.txt + - info on how to handle remote processor (e.g. AMP) offloads/usage. +rfkill.txt + - info on the radio frequency kill switch subsystem/support. +robust-futex-ABI.txt + - documentation of the robust futex ABI. +robust-futexes.txt + - a description of what robust futexes are. +rpmsg.txt + - info on the Remote Processor Messaging (rpmsg) Framework +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. +security/ + - directory that contains security-related info +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. +sh/ + - directory with info on porting Linux to a new architecture. +smsc_ece1099.txt + -info on the smsc Keyboard Scan Expansion/GPIO Expansion device. +sound/ + - directory with info on sound card support. +sparse.txt + - info on how to obtain and use the sparse tool for typechecking. +spi/ + - overview of Linux kernel Serial Peripheral Interface (SPI) support. +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. +static-keys.txt + - info on how static keys allow debug code in hotpaths via patching +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. +target/ + - directory with info on generating TCM v4 fabric .ko modules +tee.txt + - info on the TEE subsystem and drivers +this_cpu_ops.txt + - List rationale behind and the way to use this_cpu operations. +thermal/ + - directory with information on managing thermal issues (CPU/temp) +trace/ + - directory with info on tracing technologies within linux +unaligned-memory-access.txt + - info on how to avoid arch breaking unaligned memory access in code. +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. +vDSO/ + - directory with info regarding virtual dynamic shared objects +vfio.txt + - info on Virtual Function I/O used in guest/hypervisor instances. +vgaarbiter.txt + - info on enable/disable the legacy decoding on different VGA devices +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. +virtual/ + - directory with information on the various linux virtualizations. +vm/ + - directory with info on the Linux vm code. +vme_api.txt + - file relating info on the VME bus API in linux +volatile-considered-harmful.txt + - Why the "volatile" type class should not be used +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". ;-) +wimax/ + - directory with info about Intel Wireless Wimax Connections +workqueue.txt + - information on the Concurrency Managed Workqueue implementation +x86/x86_64/ + - directory with info on Linux support for AMD x86-64 (Hammer) machines. +xillybus.txt + - Overview and basic ui of xillybus driver +xtensa/ + - directory with documents relating to arch/xtensa port/implementation +xz.txt + - how to make use of the XZ data compression within linux kernel +zh_CN/ + - directory with Chinese translations of various documents +zorro.txt + - info on writing drivers for Zorro bus devices found on Amigas.
diff --git a/Documentation/80211/cfg80211.rst b/Documentation/80211/cfg80211.rst new file mode 100644 index 0000000..b1e149e --- /dev/null +++ b/Documentation/80211/cfg80211.rst
@@ -0,0 +1,345 @@ +================== +cfg80211 subsystem +================== + +Device registration +=================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Device registration + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_rate_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_rate + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_sta_ht_cap + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_supported_band + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_signal_type + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_params_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy + +.. kernel-doc:: include/net/cfg80211.h + :functions: wireless_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_new + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_register + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_unregister + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_free + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_name + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_priv + +.. kernel-doc:: include/net/cfg80211.h + :functions: priv_to_wiphy + +.. kernel-doc:: include/net/cfg80211.h + :functions: set_wiphy_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wdev_priv + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_iface_limit + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_iface_combination + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_check_combinations + +Actions and configuration +========================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Actions and configuration + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ops + +.. kernel-doc:: include/net/cfg80211.h + :functions: vif_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: key_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: survey_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: survey_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_beacon_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ap_settings + +.. kernel-doc:: include/net/cfg80211.h + :functions: station_parameters + +.. kernel-doc:: include/net/cfg80211.h + :functions: rate_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: rate_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: station_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: monitor_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: mpath_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: mpath_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: bss_parameters + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_txq_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_crypto_settings + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_auth_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_assoc_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_deauth_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_disassoc_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ibss_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_pmksa + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_mlme_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_auth_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_assoc_resp + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_assoc_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_tx_mlme_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ibss_joined + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_result + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_roamed + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_disconnected + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ready_on_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_remain_on_channel_expired + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_new_sta + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_mgmt_tx_status + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_cqm_rssi_notify + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_cqm_pktloss_notify + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_michael_mic_failure + +Scanning and BSS list handling +============================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Scanning and BSS list handling + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ssid + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_scan_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_scan_done + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss_frame_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_unlink_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_find_ie + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_bss_get_ie + +Utility functions +================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Utility functions + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel_to_frequency + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_frequency_to_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_response_rate + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_hdrlen + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_hdrlen_from_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_radiotap_iterator + +Data path helpers +================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Data path helpers + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_data_to_8023 + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_data_from_8023 + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_amsdu_to_8023s + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_classify8021d + +Regulatory enforcement infrastructure +===================================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Regulatory enforcement infrastructure + +.. kernel-doc:: include/net/cfg80211.h + :functions: regulatory_hint + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_apply_custom_regulatory + +.. kernel-doc:: include/net/cfg80211.h + :functions: freq_reg_info + +RFkill integration +================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: RFkill integration + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_set_hw_state + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_start_polling + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_stop_polling + +Test mode +========= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Test mode + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_alloc_reply_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_reply + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_alloc_event_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_event
diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py new file mode 100644 index 0000000..20c7c27 --- /dev/null +++ b/Documentation/80211/conf.py
@@ -0,0 +1,5 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Linux 802.11 Driver Developer's Guide" + +tags.add("subproject")
diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst new file mode 100644 index 0000000..90bba47 --- /dev/null +++ b/Documentation/80211/index.rst
@@ -0,0 +1,17 @@ +===================================== +Linux 802.11 Driver Developer's Guide +===================================== + +.. toctree:: + + introduction + cfg80211 + mac80211 + mac80211-advanced + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex`
diff --git a/Documentation/80211/introduction.rst b/Documentation/80211/introduction.rst new file mode 100644 index 0000000..4938fa8 --- /dev/null +++ b/Documentation/80211/introduction.rst
@@ -0,0 +1,17 @@ +============ +Introduction +============ + +Explaining wireless 802.11 networking in the Linux kernel + +Copyright 2007-2009 Johannes Berg + +These books attempt to give a description of the various subsystems +that play a role in 802.11 wireless networking in Linux. Since these +books are for kernel developers they attempts to document the +structures and functions used in the kernel as well as giving a +higher-level overview. + +The reader is expected to be familiar with the 802.11 standard as +published by the IEEE in 802.11-2007 (or possibly later versions). +References to this standard will be given as "802.11-2007 8.1.5".
diff --git a/Documentation/80211/mac80211-advanced.rst b/Documentation/80211/mac80211-advanced.rst new file mode 100644 index 0000000..70a89b2 --- /dev/null +++ b/Documentation/80211/mac80211-advanced.rst
@@ -0,0 +1,295 @@ +============================= +mac80211 subsystem (advanced) +============================= + +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. + +LED support +=========== + +Mac80211 supports various ways of blinking LEDs. Wherever possible, +device LEDs should be exposed as LED class devices and hooked up to the +appropriate trigger, which will then be triggered appropriately by +mac80211. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tx_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_rx_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_assoc_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_radio_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tpt_blink + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tpt_led_trigger_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_create_tpt_led_trigger + +Hardware crypto acceleration +============================ + +.. kernel-doc:: include/net/mac80211.h + :doc: Hardware crypto acceleration + +.. kernel-doc:: include/net/mac80211.h + :functions: set_key_cmd + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_key_conf + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_key_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p1k + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p1k_iv + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p2k + +Powersave support +================= + +.. kernel-doc:: include/net/mac80211.h + :doc: Powersave support + +Beacon filter support +===================== + +.. kernel-doc:: include/net/mac80211.h + :doc: Beacon filter support + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_beacon_loss + +Multiple queues and QoS support +=============================== + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_queue_params + +Access point mode support +========================= + +TBD + +Some parts of the if_conf should be discussed here instead + +Insert notes about VLAN interfaces with hw crypto here or in the hw +crypto chapter. + +support for powersaving clients +------------------------------- + +.. kernel-doc:: include/net/mac80211.h + :doc: AP support for powersaving clients + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_buffered_bc + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_beacon_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_eosp + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_frame_release_type + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_ps_transition + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_ps_transition_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_set_buffered + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_block_awake + +Supporting multiple virtual interfaces +====================================== + +TBD + +Note: WDS with identical MAC address should almost always be OK + +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. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_iterate_active_interfaces + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_iterate_active_interfaces_atomic + +Station handling +================ + +TODO + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta + +.. kernel-doc:: include/net/mac80211.h + :functions: sta_notify_cmd + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_find_sta + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_find_sta_by_ifaddr + +Hardware scan offload +===================== + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_scan_completed + +Aggregation +=========== + +TX A-MPDU aggregation +--------------------- + +.. kernel-doc:: net/mac80211/agg-tx.c + :doc: TX A-MPDU aggregation + +.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-tx.c + +RX A-MPDU aggregation +--------------------- + +.. kernel-doc:: net/mac80211/agg-rx.c + :doc: RX A-MPDU aggregation + +.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-rx.c + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ampdu_mlme_action + +Spatial Multiplexing Powersave (SMPS) +===================================== + +.. kernel-doc:: include/net/mac80211.h + :doc: Spatial multiplexing power save + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_request_smps + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_smps_mode + +TBD + +This part of the book describes the rate control algorithm interface and +how it relates to mac80211 and drivers. + +Rate Control API +================ + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_start_tx_ba_session + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_start_tx_ba_cb_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_tx_ba_session + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_tx_ba_cb_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rate_control_changed + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_rate_control + +.. kernel-doc:: include/net/mac80211.h + :functions: rate_control_send_low + +TBD + +This part of the book describes mac80211 internals. + +Key handling +============ + +Key handling basics +------------------- + +.. kernel-doc:: net/mac80211/key.c + :doc: Key handling basics + +MORE TBD +-------- + +TBD + +Receive processing +================== + +TBD + +Transmit processing +=================== + +TBD + +Station info handling +===================== + +Programming information +----------------------- + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: sta_info + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: ieee80211_sta_info_flags + +STA information lifetime rules +------------------------------ + +.. kernel-doc:: net/mac80211/sta_info.c + :doc: STA information lifetime rules + +Aggregation +=========== + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: sta_ampdu_mlme + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: tid_ampdu_tx + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: tid_ampdu_rx + +Synchronisation +=============== + +TBD + +Locking, lots of RCU
diff --git a/Documentation/80211/mac80211.rst b/Documentation/80211/mac80211.rst new file mode 100644 index 0000000..85a8335 --- /dev/null +++ b/Documentation/80211/mac80211.rst
@@ -0,0 +1,216 @@ +=========================== +mac80211 subsystem (basics) +=========================== + +You should read and understand the information contained within this +part of the book while implementing a mac80211 driver. In some chapters, +advanced usage is noted, those may be skipped if this isn't needed. + +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. + +Basic hardware handling +======================= + +TBD + +This chapter shall contain information on getting a hw struct allocated +and registered with mac80211. + +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. + +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. + +Finally, a discussion of hardware capabilities should be done with +references to other parts of the book. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_hw_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: SET_IEEE80211_DEV + +.. kernel-doc:: include/net/mac80211.h + :functions: SET_IEEE80211_PERM_ADDR + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ops + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_alloc_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_register_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_unregister_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_free_hw + +PHY configuration +================= + +TBD + +This chapter should describe PHY handling including start/stop callbacks +and the various structures used. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_conf + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_conf_flags + +Virtual interfaces +================== + +TBD + +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. + +Things related to AP mode should be discussed there. + +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! + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_vif + +Receive and transmit processing +=============================== + +what should be here +------------------- + +TBD + +This should describe the receive and transmit paths in mac80211/the +drivers as well as transmit status handling. + +Frame format +------------ + +.. kernel-doc:: include/net/mac80211.h + :doc: Frame format + +Packet alignment +---------------- + +.. kernel-doc:: net/mac80211/rx.c + :doc: Packet alignment + +Calling into mac80211 from interrupts +------------------------------------- + +.. kernel-doc:: include/net/mac80211.h + :doc: Calling mac80211 from interrupts + +functions/definitions +--------------------- + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_status + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_rx_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_tx_info_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_tx_control_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_rate_control_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_rate + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_info + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_info_clear_status + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rts_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rts_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ctstoself_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ctstoself_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_generic_frame_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_wake_queue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_queue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_wake_queues + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_queues + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_stopped + +Frame filtering +=============== + +.. kernel-doc:: include/net/mac80211.h + :doc: Frame filtering + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_filter_flags + +The mac80211 workqueue +====================== + +.. kernel-doc:: include/net/mac80211.h + :doc: mac80211 workqueue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_work + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_delayed_work
diff --git a/Documentation/ABI/README b/Documentation/ABI/README new file mode 100644 index 0000000..1fafc4b --- /dev/null +++ b/Documentation/ABI/README
@@ -0,0 +1,87 @@ +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. + + 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. + + +Notable bits of non-ABI, which should not under any circumstances be considered +stable: + +- Kconfig. Userspace should not rely on the presence or absence of any + particular Kconfig symbol, in /proc/config.gz, in the copy of .config + commonly installed to /boot, or in any invocation of the kernel build + process. + +- Kernel-internal symbols. Do not rely on the presence, absence, location, or + type of any kernel symbol, either in System.map files or the kernel binary + itself. See Documentation/stable_api_nonsense.txt.
diff --git a/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads b/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads new file mode 100644 index 0000000..b0b0eeb --- /dev/null +++ b/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads
@@ -0,0 +1,5 @@ +What: /proc/sys/vm/nr_pdflush_threads +Date: June 2012 +Contact: Wanpeng Li <liwp@linux.vnet.ibm.com> +Description: Since pdflush is replaced by per-BDI flusher, the interface of old pdflush + exported in /proc/sys/vm/ should be removed.
diff --git a/Documentation/ABI/obsolete/sysfs-block-zram b/Documentation/ABI/obsolete/sysfs-block-zram new file mode 100644 index 0000000..720ea92 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-block-zram
@@ -0,0 +1,119 @@ +What: /sys/block/zram<id>/num_reads +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The num_reads file is read-only and specifies the number of + reads (failed or successful) done on this device. + Now accessible via zram<id>/stat node. + +What: /sys/block/zram<id>/num_writes +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The num_writes file is read-only and specifies the number of + writes (failed or successful) done on this device. + Now accessible via zram<id>/stat node. + +What: /sys/block/zram<id>/invalid_io +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The invalid_io file is read-only and specifies the number of + non-page-size-aligned I/O requests issued to this device. + Now accessible via zram<id>/io_stat node. + +What: /sys/block/zram<id>/failed_reads +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The failed_reads file is read-only and specifies the number of + failed reads happened on this device. + Now accessible via zram<id>/io_stat node. + +What: /sys/block/zram<id>/failed_writes +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The failed_writes file is read-only and specifies the number of + failed writes happened on this device. + Now accessible via zram<id>/io_stat node. + +What: /sys/block/zram<id>/notify_free +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The notify_free file is read-only. Depending on device usage + scenario it may account a) the number of pages freed because + of swap slot free notifications or b) the number of pages freed + because of REQ_DISCARD requests sent by bio. The former ones + are sent to a swap block device when a swap slot is freed, which + implies that this disk is being used as a swap disk. The latter + ones are sent by filesystem mounted with discard option, + whenever some data blocks are getting discarded. + Now accessible via zram<id>/io_stat node. + +What: /sys/block/zram<id>/zero_pages +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The zero_pages file is read-only and specifies number of zero + filled pages written to this disk. No memory is allocated for + such pages. + Now accessible via zram<id>/mm_stat node. + +What: /sys/block/zram<id>/orig_data_size +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The orig_data_size file is read-only and specifies uncompressed + size of data stored in this disk. This excludes zero-filled + pages (zero_pages) since no memory is allocated for them. + Unit: bytes + Now accessible via zram<id>/mm_stat node. + +What: /sys/block/zram<id>/compr_data_size +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The compr_data_size file is read-only and specifies compressed + size of data stored in this disk. So, compression ratio can be + calculated using orig_data_size and this statistic. + Unit: bytes + Now accessible via zram<id>/mm_stat node. + +What: /sys/block/zram<id>/mem_used_total +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The mem_used_total file is read-only and specifies the amount + of memory, including allocator fragmentation and metadata + overhead, allocated for this disk. So, allocator space + efficiency can be calculated using compr_data_size and this + statistic. + Unit: bytes + Now accessible via zram<id>/mm_stat node. + +What: /sys/block/zram<id>/mem_used_max +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The mem_used_max file is read/write and specifies the amount + of maximum memory zram have consumed to store compressed data. + For resetting the value, you should write "0". Otherwise, + you could see -EINVAL. + Unit: bytes + Downgraded to write-only node: so it's possible to set new + value only; its current value is stored in zram<id>/mm_stat + node. + +What: /sys/block/zram<id>/mem_limit +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The mem_limit file is read/write and specifies the maximum + amount of memory ZRAM can use to store the compressed data. + The limit could be changed in run time and "0" means disable + the limit. No limit is the initial state. Unit: bytes + Downgraded to write-only node: so it's possible to set new + value only; its current value is stored in zram<id>/mm_stat + node.
diff --git a/Documentation/ABI/obsolete/sysfs-bus-usb b/Documentation/ABI/obsolete/sysfs-bus-usb new file mode 100644 index 0000000..bd096d3 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-bus-usb
@@ -0,0 +1,31 @@ +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, either "on" or "auto". + + "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. + + During normal use, devices should be left in the "auto" + level. The "on" level is 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. + + Device not capable of proper suspend and resume should be + left in the "on" level. Although the USB spec requires + devices to support suspend/resume, many of them do not. + In fact so many don't that by default, the USB core + initializes all non-hub devices in the "on" level. Some + drivers may change this setting when they are bound. + + This file is deprecated and will be removed after 2010. + Use the power/control file instead; it does exactly the + same thing.
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo new file mode 100644 index 0000000..55e281b --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-arvo
@@ -0,0 +1,53 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/actual_profile +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-5. + When read, this attribute returns the number of the actual + profile which is also the profile that's active on device startup. + When written this attribute activates the selected profile + immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/button +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard can store short macros with consist of 1 button with + several modifier keys internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 24 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/info +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns some info about the device like the + installed firmware version. + The size of the data is 8 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/key_mask +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard lets the user deactivate 5 certain keys like the + windows and application keys, to protect the user from the outcome + of accidentally pressing them. + The integer value of this attribute has bits 0-4 set depending + on the state of the corresponding key. + When read, this file returns the current state of the buttons. + When written, the given buttons are activated/deactivated + immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/arvo/roccatarvo<minor>/mode_key +Date: Januar 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The keyboard has a condensed layout without num-lock key. + Instead it uses a mode-key which activates a gaming mode where + the assignment of the number block changes. + The integer value of this attribute ranges from 0 (OFF) to 1 (ON). + When read, this file returns the actual state of the key. + When written, the key is activated/deactivated immediately. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku new file mode 100644 index 0000000..c601d0f --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-isku
@@ -0,0 +1,153 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/actual_profile +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the actual + profile. This value is persistent, so its equivalent to the + profile that's active when the device is powered on next time. + When written, this file sets the number of the startup profile + and the device activates this profile immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/info +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + The data is 6 bytes long. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/key_mask +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one deactivate certain keys like + windows and application keys, to prevent accidental presses. + Profile number for which this settings occur is included in + written data. The data has to be 6 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_capslock +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + capslock key for a specific profile. Profile number is included + in written data. The data has to be 6 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_easyzone +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + easyzone keys for a specific profile. Profile number is included + in written data. The data has to be 65 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_function +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + function keys for a specific profile. Profile number is included + in written data. The data has to be 41 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_macro +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the macro + keys for a specific profile. Profile number is included in + written data. The data has to be 35 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_media +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the media + keys for a specific profile. Profile number is included in + written data. The data has to be 29 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_thumbster +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + thumbster keys for a specific profile. Profile number is included + in written data. The data has to be 23 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/last_set +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the time in secs since + epoch in which the last configuration took place. + The data has to be 20 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/light +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the backlight intensity for + a specific profile. Profile number is included in written data. + The data has to be 10 bytes long for Isku, IskuFX needs 16 bytes + of data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/macro +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one store macros with max 500 + keystrokes for a specific button for a specific profile. + Button and profile numbers are included in written data. + The data has to be 2083 bytes long. + Before reading this file, control has to be written to select + which profile and key to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/reset +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one reset the device. + The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/control +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/talk +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one trigger easyshift functionality + from the host. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/talkfx +Date: February 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one trigger temporary color schemes + from the host. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus new file mode 100644 index 0000000..545e69f --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus
@@ -0,0 +1,145 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/actual_profile +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the actual + profile. This value is persistent, so its equivalent to the + profile that's active when the mouse is powered on next time. + When written, this file sets the number of the startup profile + and the mouse activates this profile immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/startup_profile +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the actual + profile. This value is persistent, so its equivalent to the + profile that's active when the mouse is powered on next time. + When written, this file sets the number of the startup profile + and the mouse activates this profile immediately. + Please use actual_profile, it does the same thing. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/firmware_version +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 121 means 1.21 + This file is readonly. + Please read binary attribute info which contains firmware version. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 8 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store a macro with max 500 key/button strokes + internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 2082 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 77 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 77 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 43 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 43 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a tracking- and a distance-control-unit. These + can be activated/deactivated and the lift-off distance can be + set. The data has to be 6 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/talk +Date: May 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: Used to active some easy* functions of the mouse from outside. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written a calibration process for the tracking control unit + can be initiated/cancelled. Also lets one read/write sensor + registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read the mouse returns a 30x30 pixel image of the + sampled underground. This works only in the course of a + calibration process initiated with tcu. + The returned data is 1028 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure new file mode 100644 index 0000000..41a9b7f --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-konepure
@@ -0,0 +1,105 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/actual_profile +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. actual_profile holds number of actual profile. + This value is persistent, so its value determines the profile + that's active when the mouse is powered on next time. + When written, the mouse activates the set profile immediately. + The data has to be 3 bytes long. + The mouse will reject invalid data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/control +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/info +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/macro +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store a macro with max 500 key/button strokes + internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 2082 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_buttons +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 59 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_settings +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 31 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/sensor +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a tracking- and a distance-control-unit. These + can be activated/deactivated and the lift-off distance can be + set. The data has to be 6 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/talk +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: Used to active some easy* functions of the mouse from outside. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written a calibration process for the tracking control unit + can be initiated/cancelled. Also lets one read/write sensor + registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu_image +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read the mouse returns a 30x30 pixel image of the + sampled underground. This works only in the course of a + calibration process initiated with tcu. + The returned data is 1028 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus new file mode 100644 index 0000000..ab01631 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus
@@ -0,0 +1,116 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_cpi +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-4. + When read, this attribute returns the number of the active + cpi level. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the active + profile. + When written, the mouse activates this profile immediately. + The profile that's active when powered down is the same that's + active when the mouse is powered on. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in x direction. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_y +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in y direction. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/firmware_version +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 121 means 1.21 + This file is readonly. + Obsoleted by binary sysfs attribute "info". +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 23 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 23 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 16 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 16 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua new file mode 100644 index 0000000..31c6c4c --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-lua
@@ -0,0 +1,7 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/control +Date: October 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, cpi, button and light settings can be configured. + When read, actual cpi setting and sensor data are returned. + The data has to be 8 bytes long. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra new file mode 100644 index 0000000..16020b3 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
@@ -0,0 +1,123 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: It is possible to switch the cpi setting of the mouse with the + press of a button. + When read, this file returns the raw number of the actual cpi + setting reported by the mouse. This number has to be further + processed to receive the real dpi value. + + VALUE DPI + 1 400 + 2 800 + 4 1600 + + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the number of the actual profile in + range 0-4. + This file is readonly. + Please use binary attribute "settings" which provides this information. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/firmware_version +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 138 means 1.38 + This file is readonly. + Please use binary attribute "info" which provides this information. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 19 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 19 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 13 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 13 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the settings stored in the mouse. + The size of the data is 3 bytes and holds information on the + startup_profile. + When written, this file lets write settings back to the mouse. + The data has to be 3 bytes long. The mouse will reject invalid + data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the profile + that's active when the mouse is powered on. + This file is readonly. + Please use binary attribute "settings" which provides this information. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos new file mode 100644 index 0000000..1d6a8cf --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-ryos
@@ -0,0 +1,178 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/control +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/profile +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. profile holds index of actual profile. + This value is persistent, so its value determines the profile + that's active when the device is powered on next time. + When written, the device activates the set profile immediately. + The data has to be 3 bytes long. + The device will reject invalid data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_primary +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the default of all keys for + a specific profile. Profile index is included in written data. + The data has to be 125 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_function +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + function keys for a specific profile. Profile index is included + in written data. The data has to be 95 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_macro +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the macro + keys for a specific profile. Profile index is included in + written data. The data has to be 35 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_thumbster +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + thumbster keys for a specific profile. Profile index is included + in written data. The data has to be 23 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_extra +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + capslock and function keys for a specific profile. Profile index + is included in written data. The data has to be 8 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/keys_easyzone +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + easyzone keys for a specific profile. Profile index is included + in written data. The data has to be 294 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/key_mask +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one deactivate certain keys like + windows and application keys, to prevent accidental presses. + Profile index for which this settings occur is included in + written data. The data has to be 6 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the backlight intensity for + a specific profile. Profile index is included in written data. + This attribute is only valid for the glow and pro variant. + The data has to be 16 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/macro +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one store macros with max 480 + keystrokes for a specific button for a specific profile. + Button and profile indexes are included in written data. + The data has to be 2002 bytes long. + Before reading this file, control has to be written to select + which profile and key to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/info +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + The data is 8 bytes long. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/reset +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one reset the device. + The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/talk +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one trigger easyshift functionality + from the host. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light_control +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one switch between stored and custom + light settings. + This attribute is only valid for the pro variant. + The data has to be 8 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/stored_lights +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set per-key lighting for different + layers. + This attribute is only valid for the pro variant. + The data has to be 1382 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/custom_lights +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the actual per-key lighting. + This attribute is only valid for the pro variant. + The data has to be 20 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/ryos/roccatryos<minor>/light_macro +Date: October 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set a light macro that is looped + whenever the device gets in dimness mode. + This attribute is only valid for the pro variant. + The data has to be 2002 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu new file mode 100644 index 0000000..99fda67 --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-savu
@@ -0,0 +1,77 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/buttons +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split into general settings and + button settings. The buttons variable holds information about + button layout. When written, this file lets one write the + respective profile buttons to the mouse. The data has to be + 47 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/control +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/general +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split into general settings and + button settings. A profile holds information like resolution, + sensitivity and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 43 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/info +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 8 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/macro +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one store macros with max 500 + keystrokes for a specific button for a specific profile. + Button and profile numbers are included in written data. + The data has to be 2083 bytes long. + Before reading this file, control has to be written to select + which profile and key to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/profile +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. profile holds number of actual profile. + This value is persistent, so its value determines the profile + that's active when the mouse is powered on next time. + When written, the mouse activates the set profile immediately. + The data has to be 3 bytes long. + The mouse will reject invalid data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/sensor +Date: July 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a Avago ADNS-3090 sensor. + This file allows reading and writing of the mouse sensors registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio new file mode 100644 index 0000000..867c1fa --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -0,0 +1,30 @@ +What: /sys/class/gpio/ +Date: July 2008 +KernelVersion: 2.6.27 +Contact: Linus Walleij <linusw@kernel.org> +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 OR + /<LINE-NAME> ... for a properly named GPIO line + /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) + + This ABI is deprecated and will be removed after 2020. It is + replaced with the GPIO character device.
diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs new file mode 100644 index 0000000..0020c49 --- /dev/null +++ b/Documentation/ABI/removed/devfs
@@ -0,0 +1,12 @@ +What: devfs +Date: July 2005 (scheduled), finally removed in kernel v2.6.18 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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:
diff --git a/Documentation/ABI/removed/dv1394 b/Documentation/ABI/removed/dv1394 new file mode 100644 index 0000000..c2310b6 --- /dev/null +++ b/Documentation/ABI/removed/dv1394
@@ -0,0 +1,14 @@ +What: dv1394 (a.k.a. "OHCI-DV I/O support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/dv1394/* were character device files, one for each FireWire + controller and for NTSC and PAL respectively, from which DV data + could be received by read() or transmitted by write(). A few + ioctl()s allowed limited control. + This special-purpose interface has been superseded by libraw1394 + + libiec61883 which are functionally equivalent, support HDV, and + transparently work on top of the newer firewire kernel drivers. + +Users: + ffmpeg/libavformat (if configured for DV1394)
diff --git a/Documentation/ABI/removed/ip_queue b/Documentation/ABI/removed/ip_queue new file mode 100644 index 0000000..3243613 --- /dev/null +++ b/Documentation/ABI/removed/ip_queue
@@ -0,0 +1,9 @@ +What: ip_queue +Date: finally removed in kernel v3.5.0 +Contact: Pablo Neira Ayuso <pablo@netfilter.org> +Description: + ip_queue has been replaced by nfnetlink_queue which provides + more advanced queueing mechanism to user-space. The ip_queue + module was already announced to become obsolete years ago. + +Users:
diff --git a/Documentation/ABI/removed/net_dma b/Documentation/ABI/removed/net_dma new file mode 100644 index 0000000..a173aec --- /dev/null +++ b/Documentation/ABI/removed/net_dma
@@ -0,0 +1,8 @@ +What: tcp_dma_copybreak sysctl +Date: Removed in kernel v3.13 +Contact: Dan Williams <dan.j.williams@intel.com> +Description: + Formerly the lower limit, in bytes, of the size of socket reads + that will be offloaded to a DMA copy engine. Removed due to + coherency issues of the cpu potentially touching the buffers + while dma is in flight.
diff --git a/Documentation/ABI/removed/o2cb b/Documentation/ABI/removed/o2cb new file mode 100644 index 0000000..20c91ad --- /dev/null +++ b/Documentation/ABI/removed/o2cb
@@ -0,0 +1,10 @@ +What: /sys/o2cb symlink +Date: May 2011 +KernelVersion: 3.0 +Contact: ocfs2-devel@oss.oracle.com +Description: This is a symlink: /sys/o2cb to /sys/fs/o2cb. The symlink is + 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. +Users: ocfs2-tools. It's sufficient to mail proposed changes to + ocfs2-devel@oss.oracle.com.
diff --git a/Documentation/ABI/removed/raw1394 b/Documentation/ABI/removed/raw1394 new file mode 100644 index 0000000..ec333e6 --- /dev/null +++ b/Documentation/ABI/removed/raw1394
@@ -0,0 +1,15 @@ +What: raw1394 (a.k.a. "Raw IEEE1394 I/O support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/raw1394 was a character device file that allowed low-level + access to FireWire buses. Its major drawbacks were its inability + to implement sensible device security policies, and its low level + of abstraction that required userspace clients to duplicate much + of the kernel's ieee1394 core functionality. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of + firewire-core. + +Users: + libraw1394 (works with firewire-cdev too, transparent to library ABI + users)
diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill new file mode 100644 index 0000000..3ce6231 --- /dev/null +++ b/Documentation/ABI/removed/sysfs-class-rfkill
@@ -0,0 +1,13 @@ +rfkill - radio frequency (RF) connector kill switch support + +For details to this subsystem look at Documentation/rfkill.txt. + +What: /sys/class/rfkill/rfkill[0-9]+/claim +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: This file was deprecated because there no longer was a way to + claim just control over a single rfkill instance. + This file was scheduled to be removed in 2012, and was removed + in 2016. +Values: 0: Kernel handles events
diff --git a/Documentation/ABI/removed/video1394 b/Documentation/ABI/removed/video1394 new file mode 100644 index 0000000..c39c25a --- /dev/null +++ b/Documentation/ABI/removed/video1394
@@ -0,0 +1,16 @@ +What: video1394 (a.k.a. "OHCI-1394 Video support" for FireWire) +Date: May 2010 (scheduled), finally removed in kernel v2.6.37 +Contact: linux1394-devel@lists.sourceforge.net +Description: + /dev/video1394/* were character device files, one for each FireWire + controller, which were used for isochronous I/O. It was added as an + alternative to raw1394's isochronous I/O functionality which had + performance issues in its first generation. Any video1394 user had + to use raw1394 + libraw1394 too because video1394 did not provide + asynchronous I/O for device discovery and configuration. + Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of + firewire-core. + +Users: + libdc1394 (works with firewire-cdev too, transparent to library ABI + users)
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev new file mode 100644 index 0000000..f72ed65 --- /dev/null +++ b/Documentation/ABI/stable/firewire-cdev
@@ -0,0 +1,104 @@ +What: /dev/fw[0-9]+ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + The character device files /dev/fw* are the interface between + firewire-core and IEEE 1394 device drivers implemented in + userspace. The ioctl(2)- and read(2)-based ABI is defined and + documented in <linux/firewire-cdev.h>. + + This ABI offers most of the features which firewire-core also + exposes to kernelspace IEEE 1394 drivers. + + Each /dev/fw* is associated with one IEEE 1394 node, which can + be remote or local nodes. Operations on a /dev/fw* file have + different scope: + - The 1394 node which is associated with the file: + - Asynchronous request transmission + - Get the Configuration ROM + - Query node ID + - Query maximum speed of the path between this node + and local node + - The 1394 bus (i.e. "card") to which the node is attached to: + - Isochronous stream transmission and reception + - Asynchronous stream transmission and reception + - Asynchronous broadcast request transmission + - PHY packet transmission and reception + - Allocate, reallocate, deallocate isochronous + resources (channels, bandwidth) at the bus's IRM + - Query node IDs of local node, root node, IRM, bus + manager + - Query cycle time + - Bus reset initiation, bus reset event reception + - All 1394 buses: + - Allocation of IEEE 1212 address ranges on the local + link layers, reception of inbound requests to such + an address range, asynchronous response transmission + to inbound requests + - Addition of descriptors or directories to the local + nodes' Configuration ROM + + Due to the different scope of operations and in order to let + userland implement different access permission models, some + operations are restricted to /dev/fw* files that are associated + with a local node: + - Addition of descriptors or directories to the local + nodes' Configuration ROM + - PHY packet transmission and reception + + A /dev/fw* file remains associated with one particular node + during its entire life time. Bus topology changes, and hence + node ID changes, are tracked by firewire-core. ABI users do not + need to be aware of topology. + + The following file operations are supported: + + open(2) + Currently the only useful flags are O_RDWR. + + ioctl(2) + Initiate various actions. Some take immediate effect, others + are performed asynchronously while or after the ioctl returns. + See the inline documentation in <linux/firewire-cdev.h> for + descriptions of all ioctls. + + poll(2), select(2), epoll_wait(2) etc. + Watch for events to become available to be read. + + read(2) + Receive various events. There are solicited events like + outbound asynchronous transaction completion or isochronous + buffer completion, and unsolicited events such as bus resets, + request reception, or PHY packet reception. Always use a read + buffer which is large enough to receive the largest event that + could ever arrive. See <linux/firewire-cdev.h> for descriptions + of all event types and for which ioctls affect reception of + events. + + mmap(2) + Allocate a DMA buffer for isochronous reception or transmission + and map it into the process address space. The arguments should + be used as follows: addr = NULL, length = the desired buffer + size, i.e. number of packets times size of largest packet, + prot = at least PROT_READ for reception and at least PROT_WRITE + for transmission, flags = MAP_SHARED, fd = the handle to the + /dev/fw*, offset = 0. + + Isochronous reception works in packet-per-buffer fashion except + for multichannel reception which works in buffer-fill mode. + + munmap(2) + Unmap the isochronous I/O buffer from the process address space. + + close(2) + Besides stopping and freeing I/O contexts that were associated + with the file descriptor, back out any changes to the local + nodes' Configuration ROM. Deallocate isochronous channels and + bandwidth at the IRM that were marked for kernel-assisted + re- and deallocation. + +Users: libraw1394 + libdc1394 + libhinawa + tools like linux-firewire-utils, fwhack, ...
diff --git a/Documentation/ABI/stable/o2cb b/Documentation/ABI/stable/o2cb new file mode 100644 index 0000000..5eb1545 --- /dev/null +++ b/Documentation/ABI/stable/o2cb
@@ -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.
diff --git a/Documentation/ABI/stable/syscalls b/Documentation/ABI/stable/syscalls new file mode 100644 index 0000000..c3ae3e7 --- /dev/null +++ b/Documentation/ABI/stable/syscalls
@@ -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.
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile new file mode 100644 index 0000000..964c7a8 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -0,0 +1,22 @@ +What: /sys/firmware/acpi/pm_profile +Date: 03-Nov-2011 +KernelVersion: v3.2 +Contact: linux-acpi@vger.kernel.org +Description: The ACPI pm_profile sysfs interface exports the platform + power management (and performance) requirement expectations + as provided by BIOS. The integer value is directly passed as + retrieved from the FADT ACPI table. +Values: For possible values see ACPI specification: + 5.2.9 Fixed ACPI Description Table (FADT) + Field: Preferred_PM_Profile + + Currently these values are defined by spec: + 0 Unspecified + 1 Desktop + 2 Mobile + 3 Workstation + 4 Enterprise Server + 5 SOHO Server + 6 Appliance PC + 7 Performance Server + >7 Reserved
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire new file mode 100644 index 0000000..41e5a0c --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -0,0 +1,133 @@ +What: /sys/bus/firewire/devices/fw[0-9]+/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attributes. + Read-only. Mutable during the node device's lifetime. + See IEEE 1212 for semantic definitions. + + config_rom + Contents of the Configuration ROM register. + Binary attribute; an array of host-endian u32. + + guid + The node's EUI-64 in the bus information block of + Configuration ROM. + Hexadecimal string representation of an u64. + + +What: /sys/bus/firewire/devices/fw[0-9]+/units +Date: June 2009 +KernelVersion: 2.6.31 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attribute. + Read-only. Mutable during the node device's lifetime. + See IEEE 1212 for semantic definitions. + + units + Summary of all units present in an IEEE 1394 node. + Contains space-separated tuples of specifier_id and + version of each unit present in the node. Specifier_id + and version are hexadecimal string representations of + u24 of the respective unit directory entries. + Specifier_id and version within each tuple are separated + by a colon. + +Users: udev rules to set ownership and access permissions or ACLs of + /dev/fw[0-9]+ character device files + + +What: /sys/bus/firewire/devices/fw[0-9]+/is_local +Date: July 2012 +KernelVersion: 3.6 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attribute. + Read-only and immutable. +Values: 1: The sysfs entry represents a local node (a controller card). + 0: The sysfs entry represents a remote node. + + +What: /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 unit device attributes. + Read-only. Immutable during the unit device's lifetime. + See IEEE 1212 for semantic definitions. + + modalias + Same as MODALIAS in the uevent at device creation. + + rom_index + Offset of the unit directory within the parent device's + (node device's) Configuration ROM, in quadlets. + Decimal string representation. + + +What: /sys/bus/firewire/devices/*/ +Date: May 2007 +KernelVersion: 2.6.22 +Contact: linux1394-devel@lists.sourceforge.net +Description: + Attributes common to IEEE 1394 node devices and unit devices. + Read-only. Mutable during the node device's lifetime. + Immutable during the unit device's lifetime. + See IEEE 1212 for semantic definitions. + + These attributes are only created if the root directory of an + IEEE 1394 node or the unit directory of an IEEE 1394 unit + actually contains according entries. + + hardware_version + Hexadecimal string representation of an u24. + + hardware_version_name + Contents of a respective textual descriptor leaf. + + model + Hexadecimal string representation of an u24. + + model_name + Contents of a respective textual descriptor leaf. + + specifier_id + Hexadecimal string representation of an u24. + Mandatory in unit directories according to IEEE 1212. + + vendor + Hexadecimal string representation of an u24. + Mandatory in the root directory according to IEEE 1212. + + vendor_name + Contents of a respective textual descriptor leaf. + + version + Hexadecimal string representation of an u24. + Mandatory in unit directories according to IEEE 1212. + + +What: /sys/bus/firewire/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id + formerly + /sys/bus/ieee1394/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id +Date: Feb 2004 +KernelVersion: 2.6.4 +Contact: linux1394-devel@lists.sourceforge.net +Description: + SCSI target port identifier and logical unit identifier of a + logical unit of an SBP-2 target. The identifiers are specified + in SAM-2...SAM-4 annex A. They are persistent and world-wide + unique properties the SBP-2 attached target. + + Read-only attribute, immutable during the target's lifetime. + Format, as exposed by firewire-sbp2 since 2.6.22, May 2007: + Colon-separated hexadecimal string representations of + u64 EUI-64 : u24 directory_ID : u16 LUN + without 0x prefixes, without whitespace. The former sbp2 driver + (removed in 2.6.37 after being superseded by firewire-sbp2) used + a somewhat shorter format which was not as close to SAM. + +Users: udev rules to create /dev/disk/by-id/ symlinks
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb new file mode 100644 index 0000000..831f15d --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -0,0 +1,140 @@ +What: /sys/bus/usb/devices/.../power/persist +Date: May 2007 +KernelVersion: 2.6.23 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + USB device directories can 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. For + hubs this facility is always enabled and their device + directories will not contain this file. + + For more information, see Documentation/usb/persist.txt. + +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/device/.../power/connected_duration +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + If CONFIG_PM is 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 <powertop@lists.01.org> + https://01.org/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 is 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 <powertop@lists.01.org> + https://01.org/powertop/ + +What: /sys/bus/usb/devices/<busnum>-<port[.port]>...:<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/.../avoid_reset_quirk +Date: December 2009 +Contact: Oliver Neukum <oliver@neukum.org> +Description: + Writing 1 to this file tells the kernel that this + device will morph into another mode when it is reset. + Drivers will not use reset for error handling for + such devices. +Users: + usb_modeswitch + +What: /sys/bus/usb/devices/.../devnum +KernelVersion: since at least 2.6.18 +Description: + Device address on the USB bus. +Users: + libusb + +What: /sys/bus/usb/devices/.../bConfigurationValue +KernelVersion: since at least 2.6.18 +Description: + bConfigurationValue of the *active* configuration for the + device. Writing 0 or -1 to bConfigurationValue will reset the + active configuration (unconfigure the device). Writing + another value will change the active configuration. + + Note that some devices, in violation of the USB spec, have a + configuration with a value equal to 0. Writing 0 to + bConfigurationValue for these devices will install that + configuration, rather then unconfigure the device. + + Writing -1 will always unconfigure the device. +Users: + libusb + +What: /sys/bus/usb/devices/.../busnum +KernelVersion: 2.6.22 +Description: + Bus-number of the USB-bus the device is connected to. +Users: + libusb + +What: /sys/bus/usb/devices/.../descriptors +KernelVersion: 2.6.26 +Description: + Binary file containing cached descriptors of the device. The + binary data consists of the device descriptor followed by the + descriptors for each configuration of the device. + Note that the wTotalLength of the config descriptors can not + be trusted, as the device may have a smaller config descriptor + than it advertises. The bLength field of each (sub) descriptor + can be trusted, and can be used to seek forward one (sub) + descriptor at a time until the next config descriptor is found. + All descriptors read from this file are in bus-endian format +Users: + libusb + +What: /sys/bus/usb/devices/.../speed +KernelVersion: since at least 2.6.18 +Description: + Speed the device is connected with to the usb-host in + Mbit / second. IE one of 1.5 / 12 / 480 / 5000. +Users: + libusb
diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus new file mode 100644 index 0000000..5d0125f --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-vmbus
@@ -0,0 +1,43 @@ +What: /sys/bus/vmbus/devices/vmbus_*/id +Date: Jul 2009 +KernelVersion: 2.6.31 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The VMBus child_relid of the device's primary channel +Users: tools/hv/lsvmbus + +What: /sys/bus/vmbus/devices/vmbus_*/class_id +Date: Jul 2009 +KernelVersion: 2.6.31 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The VMBus interface type GUID of the device +Users: tools/hv/lsvmbus + +What: /sys/bus/vmbus/devices/vmbus_*/device_id +Date: Jul 2009 +KernelVersion: 2.6.31 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The VMBus interface instance GUID of the device +Users: tools/hv/lsvmbus + +What: /sys/bus/vmbus/devices/vmbus_*/channel_vp_mapping +Date: Jul 2015 +KernelVersion: 4.2.0 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The mapping of which primary/sub channels are bound to which + Virtual Processors. + Format: <channel's child_relid:the bound cpu's number> +Users: tools/hv/lsvmbus + +What: /sys/bus/vmbus/devices/vmbus_*/device +Date: Dec. 2015 +KernelVersion: 4.5 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The 16 bit device ID of the device +Users: tools/hv/lsvmbus and user level RDMA libraries + +What: /sys/bus/vmbus/devices/vmbus_*/vendor +Date: Dec. 2015 +KernelVersion: 4.5 +Contact: K. Y. Srinivasan <kys@microsoft.com> +Description: The 16 bit vendor ID of the device +Users: tools/hv/lsvmbus and user level RDMA libraries
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1 new file mode 100644 index 0000000..140d85b --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -0,0 +1,11 @@ +What: /sys/bus/w1/devices/.../w1_master_timeout_us +Date: April 2015 +Contact: Dmitry Khromov <dk@icelogic.net> +Description: Bus scanning interval, microseconds component. + Some of 1-Wire devices commonly associated with physical access + control systems are attached/generate presence for as short as + 100 ms - hence the tens-to-hundreds milliseconds scan intervals + are required. + see Documentation/w1/w1.generic for detailed information. +Users: any user space application which wants to know bus scanning + interval
diff --git a/Documentation/ABI/stable/sysfs-bus-xen-backend b/Documentation/ABI/stable/sysfs-bus-xen-backend new file mode 100644 index 0000000..3d5951c --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-xen-backend
@@ -0,0 +1,75 @@ +What: /sys/bus/xen-backend/devices/*/devtype +Date: Feb 2009 +KernelVersion: 2.6.38 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The type of the device. e.g., one of: 'vbd' (block), + 'vif' (network), or 'vfb' (framebuffer). + +What: /sys/bus/xen-backend/devices/*/nodename +Date: Feb 2009 +KernelVersion: 2.6.38 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + XenStore node (under /local/domain/NNN/) for this + backend device. + +What: /sys/bus/xen-backend/devices/vbd-*/physical_device +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The major:minor number (in hexidecimal) of the + physical device providing the storage for this backend + block device. + +What: /sys/bus/xen-backend/devices/vbd-*/mode +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Whether the block device is read-only ('r') or + read-write ('w'). + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/f_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of flush requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/oo_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of requests delayed because the backend was too + busy processing previous requests. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/rd_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of read requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/rd_sect +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of sectors read by the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/wr_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of write requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/wr_sect +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of sectors written by the frontend.
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight new file mode 100644 index 0000000..70302f3 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -0,0 +1,56 @@ +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 + +What: /sys/class/backlight/<backlight>/type +Date: September 2010 +KernelVersion: 2.6.37 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + The type of interface controlled by <backlight>. + "firmware": The driver uses a standard firmware interface + "platform": The driver uses a platform-specific interface + "raw": The driver controls hardware registers directly + + In the general case, when multiple backlight + interfaces are available for a single device, firmware + control should be preferred to platform control should + be preferred to raw control. Using a firmware + interface reduces the probability of confusion with + the hardware and the OS independently updating the + backlight state. Platform interfaces are mostly a + holdover from pre-standardisation of firmware + interfaces.
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill new file mode 100644 index 0000000..e1ba4a1 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -0,0 +1,88 @@ +rfkill - radio frequency (RF) connector kill switch support + +For details to this subsystem look at Documentation/rfkill.txt. + +For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in +Documentation/ABI/removed/sysfs-class-rfkill. + +What: /sys/class/rfkill +Date: 09-Jul-2007 +KernelVersion: v2.6.22 +Contact: linux-wireless@vger.kernel.org, +Description: The rfkill class subsystem folder. + Each registered rfkill driver is represented by an rfkillX + subfolder (X being an integer > 0). + + +What: /sys/class/rfkill/rfkill[0-9]+/name +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Name assigned by driver to this key (interface or driver name). +Values: arbitrary string. + + +What: /sys/class/rfkill/rfkill[0-9]+/type +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Driver type string ("wlan", "bluetooth", etc). +Values: See include/linux/rfkill.h. + + +What: /sys/class/rfkill/rfkill[0-9]+/persistent +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Whether the soft blocked state is initialised from non-volatile + storage at startup. +Values: A numeric value. + 0: false + 1: true + + +What: /sys/class/rfkill/rfkill[0-9]+/state +Date: 09-Jul-2007 +KernelVersion v2.6.22 +Contact: linux-wireless@vger.kernel.org +Description: Current state of the transmitter. + This file was scheduled to be removed in 2014, but due to its + large number of users it will be sticking around for a bit + longer. Despite it being marked as stabe, the newer "hard" and + "soft" interfaces should be preffered, since it is not possible + to express the 'soft and hard block' state of the rfkill driver + through this interface. There will likely be another attempt to + remove it in the future. +Values: A numeric value. + 0: RFKILL_STATE_SOFT_BLOCKED + transmitter is turned off by software + 1: RFKILL_STATE_UNBLOCKED + transmitter is (potentially) active + 2: RFKILL_STATE_HARD_BLOCKED + transmitter is forced off by something outside of + the driver's control. + + +What: /sys/class/rfkill/rfkill[0-9]+/hard +Date: 12-March-2010 +KernelVersion v2.6.34 +Contact: linux-wireless@vger.kernel.org +Description: Current hardblock state. This file is read only. +Values: A numeric value. + 0: inactive + The transmitter is (potentially) active. + 1: active + The transmitter is forced off by something outside of + the driver's control. + + +What: /sys/class/rfkill/rfkill[0-9]+/soft +Date: 12-March-2010 +KernelVersion v2.6.34 +Contact: linux-wireless@vger.kernel.org +Description: Current softblock state. This file is read and write. +Values: A numeric value. + 0: inactive + The transmitter is (potentially) active. + 1: active + The transmitter is turned off by software.
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm new file mode 100644 index 0000000..c0e2383 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -0,0 +1,185 @@ +What: /sys/class/tpm/tpmX/device/ +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The device/ directory under a specific TPM instance exposes + the properties of that TPM chip + + +What: /sys/class/tpm/tpmX/device/active +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "active" property prints a '1' if the TPM chip is accepting + commands. An inactive TPM chip still contains all the state of + an active chip (Storage Root Key, NVRAM, etc), and can be + visible to the OS, but will only accept a restricted set of + commands. See the TPM Main Specification part 2, Structures, + section 17 for more information on which commands are + available. + +What: /sys/class/tpm/tpmX/device/cancel +Date: June 2005 +KernelVersion: 2.6.13 +Contact: tpmdd-devel@lists.sf.net +Description: The "cancel" property allows you to cancel the currently + pending TPM command. Writing any value to cancel will call the + TPM vendor specific cancel operation. + +What: /sys/class/tpm/tpmX/device/caps +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "caps" property contains TPM manufacturer and version info. + + Example output: + + Manufacturer: 0x53544d20 + TCG version: 1.2 + Firmware version: 8.16 + + Manufacturer is a hex dump of the 4 byte manufacturer info + space in a TPM. TCG version shows the TCG TPM spec level that + the chip supports. Firmware version is that of the chip and + is manufacturer specific. + +What: /sys/class/tpm/tpmX/device/durations +Date: March 2011 +KernelVersion: 3.1 +Contact: tpmdd-devel@lists.sf.net +Description: The "durations" property shows the 3 vendor-specific values + used to wait for a short, medium and long TPM command. All + TPM commands are categorized as short, medium or long in + execution time, so that the driver doesn't have to wait + any longer than necessary before starting to poll for a + result. + + Example output: + + 3015000 4508000 180995000 [original] + + Here the short, medium and long durations are displayed in + usecs. "[original]" indicates that the values are displayed + unmodified from when they were queried from the chip. + Durations can be modified in the case where a buggy chip + reports them in msec instead of usec and they need to be + scaled to be displayed in usecs. In this case "[adjusted]" + will be displayed in place of "[original]". + +What: /sys/class/tpm/tpmX/device/enabled +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "enabled" property prints a '1' if the TPM chip is enabled, + meaning that it should be visible to the OS. This property + may be visible but produce a '0' after some operation that + disables the TPM. + +What: /sys/class/tpm/tpmX/device/owned +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "owned" property produces a '1' if the TPM_TakeOwnership + ordinal has been executed successfully in the chip. A '0' + indicates that ownership hasn't been taken. + +What: /sys/class/tpm/tpmX/device/pcrs +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "pcrs" property will dump the current value of all Platform + Configuration Registers in the TPM. Note that since these + values may be constantly changing, the output is only valid + for a snapshot in time. + + Example output: + + PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + ... + + The number of PCRs and hex bytes needed to represent a PCR + value will vary depending on TPM chip version. For TPM 1.1 and + 1.2 chips, PCRs represent SHA-1 hashes, which are 20 bytes + long. Use the "caps" property to determine TPM version. + +What: /sys/class/tpm/tpmX/device/pubek +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "pubek" property will return the TPM's public endorsement + key if possible. If the TPM has had ownership established and + is version 1.2, the pubek will not be available without the + owner's authorization. Since the TPM driver doesn't store any + secrets, it can't authorize its own request for the pubek, + making it unaccessible. The public endorsement key is gener- + ated at TPM manufacture time and exists for the life of the + chip. + + Example output: + + Algorithm: 00 00 00 01 + Encscheme: 00 03 + Sigscheme: 00 01 + Parameters: 00 00 08 00 00 00 00 02 00 00 00 00 + Modulus length: 256 + Modulus: + B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C + 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6 + 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB + 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3 + D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B + 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26 + 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E + 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D + 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0 + A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6 + 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6 + 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70 + E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A + F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6 + F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B + C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B + + Possible values: + + Algorithm: TPM_ALG_RSA (1) + Encscheme: TPM_ES_RSAESPKCSv15 (2) + TPM_ES_RSAESOAEP_SHA1_MGF1 (3) + Sigscheme: TPM_SS_NONE (1) + Parameters, a byte string of 3 u32 values: + Key Length (bits): 00 00 08 00 (2048) + Num primes: 00 00 00 02 (2) + Exponent Size: 00 00 00 00 (0 means the + default exp) + Modulus Length: 256 (bytes) + Modulus: The 256 byte Endorsement Key modulus + +What: /sys/class/tpm/tpmX/device/temp_deactivated +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "temp_deactivated" property returns a '1' if the chip has + been temporarily deactivated, usually until the next power + cycle. Whether a warm boot (reboot) will clear a TPM chip + from a temp_deactivated state is platform specific. + +What: /sys/class/tpm/tpmX/device/timeouts +Date: March 2011 +KernelVersion: 3.1 +Contact: tpmdd-devel@lists.sf.net +Description: The "timeouts" property shows the 4 vendor-specific values + for the TPM's interface spec timeouts. The use of these + timeouts is defined by the TPM interface spec that the chip + conforms to. + + Example output: + + 750000 750000 750000 750000 [original] + + The four timeout values are shown in usecs, with a trailing + "[original]" or "[adjusted]" depending on whether the values + were scaled by the driver to be reported in usec from msecs.
diff --git a/Documentation/ABI/stable/sysfs-class-ubi b/Documentation/ABI/stable/sysfs-class-ubi new file mode 100644 index 0000000..a6b3240 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-ubi
@@ -0,0 +1,221 @@ +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/ro_mode +Date: April 2016 +KernelVersion: 4.7 +Contact: linux-mtd@lists.infradead.org +Description: + Contains ASCII "1\n" if the read-only flag is set on this + device, and "0\n" if it is cleared. UBI devices mark themselves + as read-only when they detect an unrecoverable error. + +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.
diff --git a/Documentation/ABI/stable/sysfs-class-udc b/Documentation/ABI/stable/sysfs-class-udc new file mode 100644 index 0000000..85d3dac --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-udc
@@ -0,0 +1,93 @@ +What: /sys/class/udc/<udc>/a_alt_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at an alternate port. +Users: + +What: /sys/class/udc/<udc>/a_hnp_support +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host supports HNP at this port. +Users: + +What: /sys/class/udc/<udc>/b_hnp_enable +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates if an OTG A-Host enabled HNP support. +Users: + +What: /sys/class/udc/<udc>/current_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the current negotiated speed at this port. +Users: + +What: /sys/class/udc/<udc>/is_a_peripheral +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port is the default Host on an OTG session + but HNP was used to switch roles. +Users: + +What: /sys/class/udc/<udc>/is_otg +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates that this port support OTG. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/maximum_speed +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates the maximum USB speed supported by this port. +Users: + +What: /sys/class/udc/<udc>/soft_connect +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to disconnect data pullup resistors thus causing a + logical disconnection from the USB Host. +Users: + +What: /sys/class/udc/<udc>/srp +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Allows users to manually start Session Request Protocol. +Users: + +What: /sys/class/udc/<udc>/state +Date: June 2011 +KernelVersion: 3.1 +Contact: Felipe Balbi <balbi@kernel.org> +Description: + Indicates current state of the USB Device Controller. Valid + states are: 'not-attached', 'attached', 'powered', + 'reconnecting', 'unauthenticated', 'default', 'addressed', + 'configured', and 'suspended'; however not all USB Device + Controllers support reporting all states. +Users:
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices new file mode 100644 index 0000000..df449d7 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-devices
@@ -0,0 +1,10 @@ +# Note: This documents additional properties of any device beyond what +# is documented in Documentation/sysfs-rules.txt + +What: /sys/devices/*/of_node +Date: February 2015 +Contact: Device Tree mailing list <devicetree@vger.kernel.org> +Description: + Any device associated with a device-tree node will have + an of_path symlink pointing to the corresponding device + node in /sys/firmware/devicetree/
diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node new file mode 100644 index 0000000..5b2d0f0 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-devices-node
@@ -0,0 +1,93 @@ +What: /sys/devices/system/node/possible +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that could be possibly become online at some point. + +What: /sys/devices/system/node/online +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that are online. + +What: /sys/devices/system/node/has_normal_memory +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have regular memory. + +What: /sys/devices/system/node/has_cpu +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have one or more CPUs. + +What: /sys/devices/system/node/has_high_memory +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have regular or high memory. + Depends on CONFIG_HIGHMEM. + +What: /sys/devices/system/node/nodeX +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + When CONFIG_NUMA is enabled, this is a directory containing + information on node X such as what CPUs are local to the + node. Each file is detailed next. + +What: /sys/devices/system/node/nodeX/cpumap +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's cpumap. + +What: /sys/devices/system/node/nodeX/cpulist +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The CPUs associated to the node. + +What: /sys/devices/system/node/nodeX/meminfo +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Provides information about the node's distribution and memory + utilization. Similar to /proc/meminfo, see Documentation/filesystems/proc.txt + +What: /sys/devices/system/node/nodeX/numastat +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's hit/miss statistics, in units of pages. + See Documentation/numastat.txt + +What: /sys/devices/system/node/nodeX/distance +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Distance between the node and all the other nodes + in the system. + +What: /sys/devices/system/node/nodeX/vmstat +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's zoned virtual memory statistics. + This is a superset of numastat. + +What: /sys/devices/system/node/nodeX/compact +Date: February 2010 +Contact: Mel Gorman <mel@csn.ul.ie> +Description: + When this file is written to, all memory within that node + will be compacted. When it completes, memory will be freed + into blocks which have as many contiguous pages as possible + +What: /sys/devices/system/node/nodeX/hugepages/hugepages-<size>/ +Date: December 2009 +Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> +Description: + The node's huge page size control/query attributes. + See Documentation/vm/hugetlbpage.txt \ No newline at end of file
diff --git a/Documentation/ABI/stable/sysfs-devices-system-cpu b/Documentation/ABI/stable/sysfs-devices-system-cpu new file mode 100644 index 0000000..33c133e --- /dev/null +++ b/Documentation/ABI/stable/sysfs-devices-system-cpu
@@ -0,0 +1,25 @@ +What: /sys/devices/system/cpu/dscr_default +Date: 13-May-2014 +KernelVersion: v3.15.0 +Contact: +Description: Writes are equivalent to writing to + /sys/devices/system/cpu/cpuN/dscr on all CPUs. + Reads return the last written value or 0. + This value is not a global default: it is a way to set + all per-CPU defaults at the same time. +Values: 64 bit unsigned integer (bit field) + +What: /sys/devices/system/cpu/cpu[0-9]+/dscr +Date: 13-May-2014 +KernelVersion: v3.15.0 +Contact: +Description: Default value for the Data Stream Control Register (DSCR) on + a CPU. + This default value is used when the kernel is executing and + for any process that has not set the DSCR itself. + If a process ever sets the DSCR (via direct access to the + SPR) that value will be persisted for that process and used + on any CPU where it executes (overriding the value described + here). + If set by a process it will be inherited by child processes. +Values: 64 bit unsigned integer (bit field)
diff --git a/Documentation/ABI/stable/sysfs-devices-system-xen_memory b/Documentation/ABI/stable/sysfs-devices-system-xen_memory new file mode 100644 index 0000000..caa311d --- /dev/null +++ b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
@@ -0,0 +1,77 @@ +What: /sys/devices/system/xen_memory/xen_memory0/max_retry_count +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The maximum number of times the balloon driver will + attempt to increase the balloon before giving up. See + also 'retry_count' below. + A value of zero means retry forever and is the default one. + +What: /sys/devices/system/xen_memory/xen_memory0/max_schedule_delay +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The limit that 'schedule_delay' (see below) will be + increased to. The default value is 32 seconds. + +What: /sys/devices/system/xen_memory/xen_memory0/retry_count +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The current number of times that the balloon driver + has attempted to increase the size of the balloon. + The default value is one. With max_retry_count being + zero (unlimited), this means that the driver will attempt + to retry with a 'schedule_delay' delay. + +What: /sys/devices/system/xen_memory/xen_memory0/schedule_delay +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The time (in seconds) to wait between attempts to + increase the balloon. Each time the balloon cannot be + increased, 'schedule_delay' is increased (until + 'max_schedule_delay' is reached at which point it + will use the max value). + +What: /sys/devices/system/xen_memory/xen_memory0/target +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The target number of pages to adjust this domain's + memory reservation to. + +What: /sys/devices/system/xen_memory/xen_memory0/target_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + As target above, except the value is in KiB. + +What: /sys/devices/system/xen_memory/xen_memory0/info/current_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Current size (in KiB) of this domain's memory + reservation. + +What: /sys/devices/system/xen_memory/xen_memory0/info/high_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Amount (in KiB) of high memory in the balloon. + +What: /sys/devices/system/xen_memory/xen_memory0/info/low_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Amount (in KiB) of low (or normal) memory in the + balloon.
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp new file mode 100644 index 0000000..7049a2b --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -0,0 +1,189 @@ +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/add_target +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: Interface for making ib_srp connect to a new target. + One can request ib_srp to connect to a new target by writing + a comma-separated list of login parameters to this sysfs + attribute. The supported parameters are: + * id_ext, a 16-digit hexadecimal number specifying the eight + byte identifier extension in the 16-byte SRP target port + identifier. The target port identifier is sent by ib_srp + to the target in the SRP_LOGIN_REQ request. + * ioc_guid, a 16-digit hexadecimal number specifying the eight + byte I/O controller GUID portion of the 16-byte target port + identifier. + * dgid, a 32-digit hexadecimal number specifying the + destination GID. + * pkey, a four-digit hexadecimal number specifying the + InfiniBand partition key. + * service_id, a 16-digit hexadecimal number specifying the + InfiniBand service ID used to establish communication with + the SRP target. How to find out the value of the service ID + is specified in the documentation of the SRP target. + * max_sect, a decimal number specifying the maximum number of + 512-byte sectors to be transferred via a single SCSI command. + * max_cmd_per_lun, a decimal number specifying the maximum + number of outstanding commands for a single LUN. + * io_class, a hexadecimal number specifying the SRP I/O class. + Must be either 0xff00 (rev 10) or 0x0100 (rev 16a). The I/O + class defines the format of the SRP initiator and target + port identifiers. + * initiator_ext, a 16-digit hexadecimal number specifying the + identifier extension portion of the SRP initiator port + identifier. This data is sent by the initiator to the target + in the SRP_LOGIN_REQ request. + * cmd_sg_entries, a number in the range 1..255 that specifies + the maximum number of data buffer descriptors stored in the + SRP_CMD information unit itself. With allow_ext_sg=0 the + parameter cmd_sg_entries defines the maximum S/G list length + for a single SRP_CMD, and commands whose S/G list length + exceeds this limit after S/G list collapsing will fail. + * allow_ext_sg, whether ib_srp is allowed to include a partial + memory descriptor list in an SRP_CMD instead of the entire + list. If a partial memory descriptor list has been included + in an SRP_CMD the remaining memory descriptors are + communicated from initiator to target via an additional RDMA + transfer. Setting allow_ext_sg to 1 increases the maximum + amount of data that can be transferred between initiator and + target via a single SCSI command. Since not all SRP target + implementations support partial memory descriptor lists the + default value for this option is 0. + * sg_tablesize, a number in the range 1..2048 specifying the + maximum S/G list length the SCSI layer is allowed to pass to + ib_srp. Specifying a value that exceeds cmd_sg_entries is + only safe with partial memory descriptor list support enabled + (allow_ext_sg=1). + * comp_vector, a number in the range 0..n-1 specifying the + MSI-X completion vector of the first RDMA channel. Some + HCA's allocate multiple (n) MSI-X vectors per HCA port. If + the IRQ affinity masks of these interrupts have been + configured such that each MSI-X interrupt is handled by a + different CPU then the comp_vector parameter can be used to + spread the SRP completion workload over multiple CPU's. + * tl_retry_count, a number in the range 2..7 specifying the + IB RC retry count. + * queue_size, the maximum number of commands that the + initiator is allowed to queue per SCSI host. The default + value for this parameter is 62. The lowest supported value + is 2. + +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: HCA name (<hca>). + +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/port +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: HCA port number (<port_number>). + +What: /sys/class/scsi_host/host<n>/allow_ext_sg +Date: May 19, 2011 +KernelVersion: 2.6.39 +Contact: linux-rdma@vger.kernel.org +Description: Whether ib_srp is allowed to include a partial memory + descriptor list in an SRP_CMD when communicating with an SRP + target. + +What: /sys/class/scsi_host/host<n>/ch_count +Date: April 1, 2015 +KernelVersion: 3.19 +Contact: linux-rdma@vger.kernel.org +Description: Number of RDMA channels used for communication with the SRP + target. + +What: /sys/class/scsi_host/host<n>/cmd_sg_entries +Date: May 19, 2011 +KernelVersion: 2.6.39 +Contact: linux-rdma@vger.kernel.org +Description: Maximum number of data buffer descriptors that may be sent to + the target in a single SRP_CMD request. + +What: /sys/class/scsi_host/host<n>/comp_vector +Date: September 2, 2013 +KernelVersion: 3.11 +Contact: linux-rdma@vger.kernel.org +Description: Completion vector used for the first RDMA channel. + +What: /sys/class/scsi_host/host<n>/dgid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand destination GID used for communication with the SRP + target. Differs from orig_dgid if port redirection has happened. + +What: /sys/class/scsi_host/host<n>/id_ext +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: Eight-byte identifier extension portion of the 16-byte target + port identifier. + +What: /sys/class/scsi_host/host<n>/ioc_guid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: Eight-byte I/O controller GUID portion of the 16-byte target + port identifier. + +What: /sys/class/scsi_host/host<n>/local_ib_device +Date: November 29, 2006 +KernelVersion: 2.6.19 +Contact: linux-rdma@vger.kernel.org +Description: Name of the InfiniBand HCA used for communicating with the + SRP target. + +What: /sys/class/scsi_host/host<n>/local_ib_port +Date: November 29, 2006 +KernelVersion: 2.6.19 +Contact: linux-rdma@vger.kernel.org +Description: Number of the HCA port used for communicating with the + SRP target. + +What: /sys/class/scsi_host/host<n>/orig_dgid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand destination GID specified in the parameters + written to the add_target sysfs attribute. + +What: /sys/class/scsi_host/host<n>/pkey +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: A 16-bit number representing the InfiniBand partition key used + for communication with the SRP target. + +What: /sys/class/scsi_host/host<n>/req_lim +Date: October 20, 2010 +KernelVersion: 2.6.36 +Contact: linux-rdma@vger.kernel.org +Description: Number of requests ib_srp can send to the target before it has + to wait for more credits. For more information see also the + SRP credit algorithm in the SRP specification. + +What: /sys/class/scsi_host/host<n>/service_id +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand service ID used for establishing communication with + the SRP target. + +What: /sys/class/scsi_host/host<n>/sgid +Date: February 1, 2014 +KernelVersion: 3.13 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand GID of the source port used for communication with + the SRP target. + +What: /sys/class/scsi_host/host<n>/zero_req_lim +Date: September 20, 2006 +KernelVersion: 2.6.18 +Contact: linux-rdma@vger.kernel.org +Description: Number of times the initiator had to wait before sending a + request to the target because it ran out of credits. For more + information see also the SRP credit algorithm in the SRP + specification.
diff --git a/Documentation/ABI/stable/sysfs-driver-qla2xxx b/Documentation/ABI/stable/sysfs-driver-qla2xxx new file mode 100644 index 0000000..9a59d84 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-qla2xxx
@@ -0,0 +1,8 @@ +What: /sys/bus/pci/drivers/qla2xxx/.../devices/* +Date: September 2009 +Contact: QLogic Linux Driver <linux-driver@qlogic.com> +Description: qla2xxx-udev.sh currently looks for uevent CHANGE events to + signal a firmware-dump has been generated by the driver and is + ready for retrieval. +Users: qla2xxx-udev.sh. Proposed changes should be mailed to + linux-driver@qlogic.com
diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc new file mode 100644 index 0000000..e960cd0 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc
@@ -0,0 +1,62 @@ +What: /sys/bus/usb/drivers/usbtmc/*/interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/device_capabilities +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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/*/usb488_interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/usb488_device_capabilities +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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/*/TermChar +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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/*/TermCharEnabled +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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/*/auto_abort +Date: August 2008 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: + This file determines if 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.
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 new file mode 100644 index 0000000..26579ee --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -0,0 +1,15 @@ +What: /sys/bus/w1/devices/.../pio +Date: May 2012 +Contact: Markus Franke <franm@hrz.tu-chemnitz.de> +Description: read/write the contents of the two PIO's of the DS28E04-100 + see Documentation/w1/slaves/w1_ds28e04 for detailed information +Users: any user space application which wants to communicate with DS28E04-100 + + + +What: /sys/bus/w1/devices/.../eeprom +Date: May 2012 +Contact: Markus Franke <franm@hrz.tu-chemnitz.de> +Description: read/write the contents of the EEPROM memory of the DS28E04-100 + see Documentation/w1/slaves/w1_ds28e04 for detailed information +Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 new file mode 100644 index 0000000..e928def --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -0,0 +1,6 @@ +What: /sys/bus/w1/devices/.../w1_seq +Date: Apr 2015 +Contact: Matt Campbell <mattrcampbell@gmail.com> +Description: Support for the DS28EA00 chain sequence function + see Documentation/w1/slaves/w1_therm for detailed information +Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars new file mode 100644 index 0000000..5def20b --- /dev/null +++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars
@@ -0,0 +1,75 @@ +What: /sys/firmware/efi/vars +Date: April 2004 +Contact: Matt Domsch <Matt_Domsch@dell.com> +Description: + This directory exposes interfaces for interactive with + EFI variables. For more information on EFI variables, + see 'Variable Services' in the UEFI specification + (section 7.2 in specification version 2.3 Errata D). + + In summary, EFI variables are named, and are classified + into separate namespaces through the use of a vendor + GUID. They also have an arbitrary binary value + associated with them. + + The efivars module enumerates these variables and + creates a separate directory for each one found. Each + directory has a name of the form "<key>-<vendor guid>" + and contains the following files: + + attributes: A read-only text file enumerating the + EFI variable flags. Potential values + include: + + EFI_VARIABLE_NON_VOLATILE + EFI_VARIABLE_BOOTSERVICE_ACCESS + EFI_VARIABLE_RUNTIME_ACCESS + EFI_VARIABLE_HARDWARE_ERROR_RECORD + EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS + + See the EFI documentation for an + explanation of each of these variables. + + data: A read-only binary file that can be read + to attain the value of the EFI variable + + guid: The vendor GUID of the variable. This + should always match the GUID in the + variable's name. + + raw_var: A binary file that can be read to obtain + a structure that contains everything + there is to know about the variable. + For structure definition see "struct + efi_variable" in the kernel sources. + + This file can also be written to in + order to update the value of a variable. + For this to work however, all fields of + the "struct efi_variable" passed must + match byte for byte with the structure + read out of the file, save for the value + portion. + + **Note** the efi_variable structure + read/written with this file contains a + 'long' type that may change widths + depending on your underlying + architecture. + + size: As ASCII representation of the size of + the variable's value. + + + In addition, two other magic binary files are provided + in the top-level directory and are used for adding and + removing variables: + + new_var: Takes a "struct efi_variable" and + instructs the EFI firmware to create a + new variable. + + del_var: Takes a "struct efi_variable" and + instructs the EFI firmware to remove any + variable that has a matching vendor GUID + and variable key name.
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump new file mode 100644 index 0000000..32fe7f5 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -0,0 +1,41 @@ +What: /sys/firmware/opal/dump +Date: Feb 2014 +Contact: Stewart Smith <stewart@linux.vnet.ibm.com> +Description: + This directory exposes interfaces for interacting with + the FSP and platform dumps through OPAL firmware interface. + + This is only for the powerpc/powernv platform. + + initiate_dump: When '1' is written to it, + we will initiate a dump. + Read this file for supported commands. + + 0xXX-0xYYYY: A directory for dump of type 0xXX and + id 0xYYYY (in hex). The name of this + directory should not be relied upon to + be in this format, only that it's unique + among all dumps. For determining the type + and ID of the dump, use the id and type files. + Do not rely on any particular size of dump + type or dump id. + + Each dump has the following files: + id: An ASCII representation of the dump ID + in hex (e.g. '0x01') + type: An ASCII representation of the type of + dump in the format "0x%x %s" with the ID + in hex and a description of the dump type + (or 'unknown'). + Type '0xffffffff unknown' is used when + we could not get the type from firmware. + e.g. '0x02 System/Platform Dump' + dump: A binary file containing the dump. + The size of the dump is the size of this file. + acknowledge: When 'ack' is written to this, we will + acknowledge that we've retrieved the + dump to the service processor. It will + then remove it, making the dump + inaccessible. + Reading this file will get a list of + supported actions.
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog new file mode 100644 index 0000000..2536434 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -0,0 +1,60 @@ +What: /sys/firmware/opal/elog +Date: Feb 2014 +Contact: Stewart Smith <stewart@linux.vnet.ibm.com> +Description: + This directory exposes error log entries retrieved + through the OPAL firmware interface. + + Each error log is identified by a unique ID and will + exist until explicitly acknowledged to firmware. + + Each log entry has a directory in /sys/firmware/opal/elog. + + Log entries may be purged by the service processor + before retrieved by firmware or retrieved/acknowledged by + Linux if there is no room for more log entries. + + In the event that Linux has retrieved the log entries + but not explicitly acknowledged them to firmware and + the service processor needs more room for log entries, + the only remaining copy of a log message may be in + Linux. + + Typically, a user space daemon will monitor for new + entries, read them out and acknowledge them. + + The service processor may be able to store more log + entries than firmware can, so after you acknowledge + an event from Linux you may instantly get another one + from the queue that was generated some time in the past. + + The raw log format is a binary format. We currently + do not parse this at all in kernel, leaving it up to + user space to solve the problem. In future, we may + do more parsing in kernel and add more files to make + it easier for simple user space processes to extract + more information. + + For each log entry (directory), there are the following + files: + + id: An ASCII representation of the ID of the + error log, in hex - e.g. "0x01". + + type: An ASCII representation of the type id and + description of the type of error log. + Currently just "0x00 PEL" - platform error log. + In the future there may be additional types. + + raw: A read-only binary file that can be read + to get the raw log entry. These are + <16kb, often just hundreds of bytes and + "average" 2kb. + + acknowledge: Writing 'ack' to this file will acknowledge + the error log to firmware (and in turn + the service processor, if applicable). + Shortly after acknowledging it, the log + entry will be removed from sysfs. + Reading this file will list the supported + operations (currently just acknowledge).
diff --git a/Documentation/ABI/stable/sysfs-fs-orangefs b/Documentation/ABI/stable/sysfs-fs-orangefs new file mode 100644 index 0000000..affdb11 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-fs-orangefs
@@ -0,0 +1,87 @@ +What: /sys/fs/orangefs/perf_counters/* +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Counters and settings for various caches. + Read only. + + +What: /sys/fs/orangefs/perf_counter_reset +Date: June 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + echo a 0 or a 1 into perf_counter_reset to + reset all the counters in + /sys/fs/orangefs/perf_counters + except ones with PINT_PERF_PRESERVE set. + + +What: /sys/fs/orangefs/perf_time_interval_secs +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Length of perf counter intervals in + seconds. + + +What: /sys/fs/orangefs/perf_history_size +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + The perf_counters cache statistics have N, or + perf_history_size, samples. The default is + one. + + Every perf_time_interval_secs the (first) + samples are reset. + + If N is greater than one, the "current" set + of samples is reset, and the samples from the + other N-1 intervals remain available. + + +What: /sys/fs/orangefs/op_timeout_secs +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Service operation timeout in seconds. + + +What: /sys/fs/orangefs/slot_timeout_secs +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + "Slot" timeout in seconds. A "slot" + is an indexed buffer in the shared + memory segment used for communication + between the kernel module and userspace. + Slots are requested and waited for, + the wait times out after slot_timeout_secs. + + +What: /sys/fs/orangefs/acache/* +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Attribute cache configurable settings. + + +What: /sys/fs/orangefs/ncache/* +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Name cache configurable settings. + + +What: /sys/fs/orangefs/capcache/* +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Capability cache configurable settings. + + +What: /sys/fs/orangefs/ccache/* +Date: Jun 2015 +Contact: Mike Marshall <hubcap@omnibond.com> +Description: + Credential cache configurable settings.
diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module new file mode 100644 index 0000000..6272ae5 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-module
@@ -0,0 +1,34 @@ +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 always show up if the module is loaded as a + dynamic module. If it is built directly into the kernel, it + will only show up if it has a version or at least one + parameter. + + Note: The conditions of creation in the built-in case are not + by design and may be removed in the future. + + /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.
diff --git a/Documentation/ABI/stable/sysfs-transport-srp b/Documentation/ABI/stable/sysfs-transport-srp new file mode 100644 index 0000000..ec7af69 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-transport-srp
@@ -0,0 +1,58 @@ +What: /sys/class/srp_remote_ports/port-<h>:<n>/delete +Date: June 1, 2012 +KernelVersion: 3.7 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: Instructs an SRP initiator to disconnect from a target and to + remove all LUNs imported from that target. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/dev_loss_tmo +Date: February 1, 2014 +KernelVersion: 3.13 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: Number of seconds the SCSI layer will wait after a transport + layer error has been observed before removing a target port. + Zero means immediate removal. Setting this attribute to "off" + will disable the dev_loss timer. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/fast_io_fail_tmo +Date: February 1, 2014 +KernelVersion: 3.13 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: Number of seconds the SCSI layer will wait after a transport + layer error has been observed before failing I/O. Zero means + failing I/O immediately. Setting this attribute to "off" will + disable the fast_io_fail timer. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/port_id +Date: June 27, 2007 +KernelVersion: 2.6.24 +Contact: linux-scsi@vger.kernel.org +Description: 16-byte local SRP port identifier in hexadecimal format. An + example: 4c:49:4e:55:58:20:56:49:4f:00:00:00:00:00:00:00. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/reconnect_delay +Date: February 1, 2014 +KernelVersion: 3.13 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: Number of seconds the SCSI layer will wait after a reconnect + attempt failed before retrying. Setting this attribute to + "off" will disable time-based reconnecting. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/roles +Date: June 27, 2007 +KernelVersion: 2.6.24 +Contact: linux-scsi@vger.kernel.org +Description: Role of the remote port. Either "SRP Initiator" or "SRP Target". + +What: /sys/class/srp_remote_ports/port-<h>:<n>/state +Date: February 1, 2014 +KernelVersion: 3.13 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: State of the transport layer used for communication with the + remote port. "running" if the transport layer is operational; + "blocked" if a transport layer error has been encountered but + the fast_io_fail_tmo timer has not yet fired; "fail-fast" + after the fast_io_fail_tmo timer has fired and before the + "dev_loss_tmo" timer has fired; "lost" after the + "dev_loss_tmo" timer has fired and before the port is finally + removed.
diff --git a/Documentation/ABI/stable/thermal-notification b/Documentation/ABI/stable/thermal-notification new file mode 100644 index 0000000..9723e8b --- /dev/null +++ b/Documentation/ABI/stable/thermal-notification
@@ -0,0 +1,4 @@ +What: A notification mechanism for thermal related events +Description: + This interface enables notification for thermal related events. + The notification is in the form of a netlink event.
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso new file mode 100644 index 0000000..7cdfc28 --- /dev/null +++ b/Documentation/ABI/stable/vdso
@@ -0,0 +1,27 @@ +On some architectures, when the kernel loads any userspace program it +maps an ELF DSO into that program's address space. This DSO is called +the vDSO and it often contains useful and highly-optimized alternatives +to real syscalls. + +These functions are called just like ordinary C function according to +your platform's ABI. Call them from a sensible context. (For example, +if you set CS on x86 to something strange, the vDSO functions are +within their rights to crash.) In addition, if you pass a bad +pointer to a vDSO function, you might get SIGSEGV instead of -EFAULT. + +To find the DSO, parse the auxiliary vector passed to the program's +entry point. The AT_SYSINFO_EHDR entry will point to the vDSO. + +The vDSO uses symbol versioning; whenever you request a symbol from the +vDSO, specify the version you are expecting. + +Programs that dynamically link to glibc will use the vDSO automatically. +Otherwise, you can use the reference parser in Documentation/vDSO/parse_vdso.c. + +Unless otherwise noted, the set of symbols with any given version and the +ABI of those symbols is considered stable. It may vary across architectures, +though. + +(As of this writing, this ABI documentation as been confirmed for x86_64. + The maintainers of the other vDSO-using architectures should confirm + that it is correct for their architecture.)
diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi new file mode 100644 index 0000000..4ab4e99 --- /dev/null +++ b/Documentation/ABI/testing/configfs-acpi
@@ -0,0 +1,36 @@ +What: /config/acpi +Date: July 2016 +KernelVersion: 4.8 +Contact: linux-acpi@vger.kernel.org +Description: + This represents the ACPI subsystem entry point directory. It + contains sub-groups corresponding to ACPI configurable options. + +What: /config/acpi/table +Date: July 2016 +KernelVersion: 4.8 +Description: + + This group contains the configuration for user defined ACPI + tables. The attributes of a user define table are: + + aml - a binary attribute that the user can use to + fill in the ACPI aml definitions. Once the aml + data is written to this file and the file is + closed the table will be loaded and ACPI devices + will be enumerated. To check if the operation is + successful the user must check the error code + for close(). If the operation is successful, + subsequent writes to this attribute will fail. + + The rest of the attributes are read-only and are valid only + after the table has been loaded by filling the aml entry: + + signature - ASCII table signature + length - length of table in bytes, including the header + revision - ACPI Specification minor version number + oem_id - ASCII OEM identification + oem_table_id - ASCII OEM table identification + oem_revision - OEM revision number + asl_compiler_id - ASCII ASL compiler vendor ID + asl_compiler_revision - ASL compiler version
diff --git a/Documentation/ABI/testing/configfs-iio b/Documentation/ABI/testing/configfs-iio new file mode 100644 index 0000000..aebda53 --- /dev/null +++ b/Documentation/ABI/testing/configfs-iio
@@ -0,0 +1,34 @@ +What: /config/iio +Date: October 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + This represents Industrial IO configuration entry point + directory. It contains sub-groups corresponding to IIO + objects. + +What: /config/iio/triggers +Date: October 2015 +KernelVersion: 4.4 +Description: + Industrial IO software triggers directory. + +What: /config/iio/triggers/hrtimers +Date: October 2015 +KernelVersion: 4.4 +Description: + High resolution timers directory. Creating a directory here + will result in creating a hrtimer trigger in the IIO subsystem. + +What: /config/iio/devices +Date: April 2016 +KernelVersion: 4.7 +Description: + Industrial IO software devices directory. + +What: /config/iio/devices/dummy +Date: April 2016 +KernelVersion: 4.7 +Description: + Dummy IIO devices directory. Creating a directory here will result + in creating a dummy IIO device in the IIO subystem.
diff --git a/Documentation/ABI/testing/configfs-rdma_cm b/Documentation/ABI/testing/configfs-rdma_cm new file mode 100644 index 0000000..5c389aa --- /dev/null +++ b/Documentation/ABI/testing/configfs-rdma_cm
@@ -0,0 +1,22 @@ +What: /config/rdma_cm +Date: November 29, 2015 +KernelVersion: 4.4.0 +Description: Interface is used to configure RDMA-cable HCAs in respect to + RDMA-CM attributes. + + Attributes are visible only when configfs is mounted. To mount + configfs in /config directory use: + # mount -t configfs none /config/ + + In order to set parameters related to a specific HCA, a directory + for this HCA has to be created: + mkdir -p /config/rdma_cm/<hca> + + +What: /config/rdma_cm/<hca>/ports/<port-num>/default_roce_mode +Date: November 29, 2015 +KernelVersion: 4.4.0 +Description: RDMA-CM based connections from HCA <hca> at port <port-num> + will be initiated with this RoCE type as default. + The possible RoCE types are either "IB/RoCE v1" or "RoCE v2". + This parameter has RW access.
diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget new file mode 100644 index 0000000..840c324 --- /dev/null +++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget
@@ -0,0 +1,31 @@ +What: /config/pcie-gadget +Date: Feb 2011 +KernelVersion: 2.6.37 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + + Interface is used to configure selected dual mode PCIe controller + as device and then program its various registers to configure it + as a particular device type. + This interfaces can be used to show spear's PCIe device capability. + + Nodes are only visible when configfs is mounted. To mount configfs + in /config directory use: + # mount -t configfs none /config/ + + For nth PCIe Device Controller + /config/pcie-gadget.n/ + link ... used to enable ltssm and read its status. + int_type ...used to configure and read type of supported + interrupt + no_of_msi ... used to configure number of MSI vector needed and + to read no of MSI granted. + inta ... write 1 to assert INTA and 0 to de-assert. + send_msi ... write MSI vector to be sent. + vendor_id ... used to write and read vendor id (hex) + device_id ... used to write and read device id (hex) + bar0_size ... used to write and read bar0_size + bar0_address ... used to write and read bar0 mapped area in hex. + bar0_rw_offset ... used to write and read offset of bar0 where + bar0_data will be written or read. + bar0_data ... used to write and read data at bar0_rw_offset.
diff --git a/Documentation/ABI/testing/configfs-stp-policy b/Documentation/ABI/testing/configfs-stp-policy new file mode 100644 index 0000000..421ce68 --- /dev/null +++ b/Documentation/ABI/testing/configfs-stp-policy
@@ -0,0 +1,48 @@ +What: /config/stp-policy +Date: June 2015 +KernelVersion: 4.3 +Description: + This group contains policies mandating Master/Channel allocation + for software sources wishing to send trace data over an STM + device. + +What: /config/stp-policy/<device>.<policy> +Date: June 2015 +KernelVersion: 4.3 +Description: + This group is the root of a policy; its name is a concatenation + of an stm device name to which this policy applies and an + arbitrary string. If <device> part doesn't match an existing + stm device, mkdir will fail with ENODEV; if that device already + has a policy assigned to it, mkdir will fail with EBUSY. + +What: /config/stp-policy/<device>.<policy>/device +Date: June 2015 +KernelVersion: 4.3 +Description: + STM device to which this policy applies, read only. Same as the + <device> component of its parent directory. + +What: /config/stp-policy/<device>.<policy>/<node> +Date: June 2015 +KernelVersion: 4.3 +Description: + Policy node is a string identifier that software clients will + use to request a master/channel to be allocated and assigned to + them. + +What: /config/stp-policy/<device>.<policy>/<node>/masters +Date: June 2015 +KernelVersion: 4.3 +Description: + Range of masters from which to allocate for users of this node. + Write two numbers: the first master and the last master number. + +What: /config/stp-policy/<device>.<policy>/<node>/channels +Date: June 2015 +KernelVersion: 4.3 +Description: + Range of channels from which to allocate for users of this node. + Write two numbers: the first channel and the last channel + number. +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget new file mode 100644 index 0000000..95a3658 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget
@@ -0,0 +1,126 @@ +What: /config/usb-gadget +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains sub-groups corresponding to created + USB gadgets. + +What: /config/usb-gadget/gadget +Date: Jun 2013 +KernelVersion: 3.11 +Description: + + The attributes of a gadget: + + UDC - bind a gadget to UDC/unbind a gadget; + write UDC's name found in /sys/class/udc/* + to bind a gadget, empty string "" to unbind. + + bDeviceClass - USB device class code + bDeviceSubClass - USB device subclass code + bDeviceProtocol - USB device protocol code + bMaxPacketSize0 - maximum endpoint 0 packet size + bcdDevice - bcd device release number + bcdUSB - bcd USB specification version number + idProduct - product ID + idVendor - vendor ID + +What: /config/usb-gadget/gadget/configs +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains a USB gadget's configurations + +What: /config/usb-gadget/gadget/configs/config +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes of a configuration: + + bmAttributes - configuration characteristics + MaxPower - maximum power consumption from the bus + +What: /config/usb-gadget/gadget/configs/config/strings +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this configuration. + +What: /config/usb-gadget/gadget/configs/config/strings/language +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + configuration - configuration description + + +What: /config/usb-gadget/gadget/functions +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains functions available to this USB gadget. + +What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n> +Date: May 2014 +KernelVersion: 3.16 +Description: + This group contains "Feature Descriptors" specific for one + gadget's USB interface or one interface group described + by an IAD. + + The attributes: + + compatible_id - 8-byte string for "Compatible ID" + sub_compatible_id - 8-byte string for "Sub Compatible ID" + +What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property> +Date: May 2014 +KernelVersion: 3.16 +Description: + This group contains "Extended Property Descriptors" specific for one + gadget's USB interface or one interface group described + by an IAD. + + The attributes: + + type - value 1..7 for interpreting the data + 1: unicode string + 2: unicode string with environment variable + 3: binary + 4: little-endian 32-bit + 5: big-endian 32-bit + 6: unicode string with a symbolic link + 7: multiple unicode strings + data - blob of data to be interpreted depending on + type + +What: /config/usb-gadget/gadget/strings +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this gadget. + +What: /config/usb-gadget/gadget/strings/language +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + serialnumber - gadget's serial number (string) + product - gadget's product description + manufacturer - gadget's manufacturer description + +What: /config/usb-gadget/gadget/os_desc +Date: May 2014 +KernelVersion: 3.16 +Description: + This group contains "OS String" extension handling attributes. + + use - flag turning "OS Desctiptors" support on/off + b_vendor_code - one-byte value used for custom per-device and + per-interface requests + qw_sign - an identifier to be reported as "OS String" + proper
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm new file mode 100644 index 0000000..d21092d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-acm
@@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/acm.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with acm function's instance "name".
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm new file mode 100644 index 0000000..0addf77 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm
@@ -0,0 +1,16 @@ +What: /config/usb-gadget/gadget/functions/ecm.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem new file mode 100644 index 0000000..a4c5715 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-eem
@@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/eem.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ffs b/Documentation/ABI/testing/configfs-usb-gadget-ffs new file mode 100644 index 0000000..e39b276 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ffs
@@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/ffs.name +Date: Nov 2013 +KernelVersion: 3.13 +Description: The purpose of this directory is to create and remove it. + + A corresponding USB function instance is created/removed. + There are no attributes here. + + All parameters are set through FunctionFS.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid new file mode 100644 index 0000000..f12e00e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-hid
@@ -0,0 +1,11 @@ +What: /config/usb-gadget/gadget/functions/hid.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + protocol - HID protocol to use + report_desc - blob corresponding to HID report descriptors + except the data passed through /dev/hidg<N> + report_length - HID report length + subclass - HID device subclass to use
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-loopback b/Documentation/ABI/testing/configfs-usb-gadget-loopback new file mode 100644 index 0000000..06beefb --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-loopback
@@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/Loopback.name +Date: Nov 2013 +KernelVersion: 3.13 +Description: + The attributes: + + qlen - depth of loopback queue + buflen - buffer length
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage new file mode 100644 index 0000000..9931fb0 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
@@ -0,0 +1,31 @@ +What: /config/usb-gadget/gadget/functions/mass_storage.name +Date: Oct 2013 +KernelVersion: 3.13 +Description: + The attributes: + + stall - Set to permit function to halt bulk endpoints. + Disabled on some USB devices known not to work + correctly. You should set it to true. + num_buffers - Number of pipeline buffers. Valid numbers + are 2..4. Available only if + CONFIG_USB_GADGET_DEBUG_FILES is set. + +What: /config/usb-gadget/gadget/functions/mass_storage.name/lun.name +Date: Oct 2013 +KernelVersion: 3.13 +Description: + The attributes: + + file - The path to the backing file for the LUN. + Required if LUN is not marked as removable. + ro - Flag specifying access to the LUN shall be + read-only. This is implied if CD-ROM emulation + is enabled as well as when it was impossible + to open "filename" in R/W mode. + removable - Flag specifying that LUN shall be indicated as + being removable. + cdrom - Flag specifying that LUN shall be reported as + being a CD-ROM. + nofua - Flag specifying that FUA flag + in SCSI WRITE(10,12)
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi new file mode 100644 index 0000000..6b341df --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-midi
@@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/midi.name +Date: Nov 2014 +KernelVersion: 3.19 +Description: + The attributes: + + index - index value for the USB MIDI adapter + id - ID string for the USB MIDI adapter + buflen - MIDI buffer length + qlen - USB read request queue length + in_ports - number of MIDI input ports + out_ports - number of MIDI output ports
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ncm b/Documentation/ABI/testing/configfs-usb-gadget-ncm new file mode 100644 index 0000000..6fe723e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ncm
@@ -0,0 +1,15 @@ +What: /config/usb-gadget/gadget/functions/ncm.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-obex b/Documentation/ABI/testing/configfs-usb-gadget-obex new file mode 100644 index 0000000..a6a9327 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-obex
@@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/obex.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with obex function's instance "name". +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-phonet b/Documentation/ABI/testing/configfs-usb-gadget-phonet new file mode 100644 index 0000000..7037a35 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-phonet
@@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/phonet.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + + This item contains just one readonly attribute: ifname. + It contains the network interface name assigned during + network device registration.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-printer b/Documentation/ABI/testing/configfs-usb-gadget-printer new file mode 100644 index 0000000..6b0714e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-printer
@@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/printer.name +Date: Apr 2015 +KernelVersion: 4.1 +Description: + The attributes: + + pnp_string - Data to be passed to the host in pnp string + q_len - Number of requests per endpoint +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis new file mode 100644 index 0000000..e32879b --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis
@@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/rndis.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-serial b/Documentation/ABI/testing/configfs-usb-gadget-serial new file mode 100644 index 0000000..474d249 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-serial
@@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/gser.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with gser function's instance "name". +
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink new file mode 100644 index 0000000..f56335a --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
@@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/SourceSink.name +Date: Nov 2013 +KernelVersion: 3.13 +Description: + The attributes: + + pattern - 0 (all zeros), 1 (mod63), 2 (none) + isoc_interval - 1..16 + isoc_maxpacket - 0 - 1023 (fs), 0 - 1024 (hs/ss) + isoc_mult - 0..2 (hs/ss only) + isoc_maxburst - 0..15 (ss only) + buflen - buffer length + bulk_qlen - depth of queue for bulk + iso_qlen - depth of queue for iso
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset new file mode 100644 index 0000000..9373e2c --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-subset
@@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/geth.name +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-tcm b/Documentation/ABI/testing/configfs-usb-gadget-tcm new file mode 100644 index 0000000..a29ed2d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-tcm
@@ -0,0 +1,6 @@ +What: /config/usb-gadget/gadget/functions/tcm.name +Date: Dec 2015 +KernelVersion: 4.5 +Description: + There are no attributes because all the configuration + is performed in the "target" subsystem of configfs.
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1 new file mode 100644 index 0000000..8ba9a12 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1
@@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/uac1.name +Date: Sep 2014 +KernelVersion: 3.18 +Description: + The attributes: + + audio_buf_size - audio buffer size + fn_cap - capture pcm device file name + fn_cntl - control device file name + fn_play - playback pcm device file name + req_buf_size - ISO OUT endpoint request buffer size + req_count - ISO OUT endpoint request count
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2 new file mode 100644 index 0000000..2bfdd4e --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2
@@ -0,0 +1,12 @@ +What: /config/usb-gadget/gadget/functions/uac2.name +Date: Sep 2014 +KernelVersion: 3.18 +Description: + The attributes: + + c_chmask - capture channel mask + c_srate - capture sampling rate + c_ssize - capture sample size (bytes) + p_chmask - playback channel mask + p_srate - playback sampling rate + p_ssize - playback sample size (bytes)
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc new file mode 100644 index 0000000..1ba0d0f --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc
@@ -0,0 +1,265 @@ +What: /config/usb-gadget/gadget/functions/uvc.name +Date: Dec 2014 +KernelVersion: 4.0 +Description: UVC function directory + + streaming_maxburst - 0..15 (ss only) + streaming_maxpacket - 1..1023 (fs), 1..3072 (hs/ss) + streaming_interval - 1..16 + +What: /config/usb-gadget/gadget/functions/uvc.name/control +Date: Dec 2014 +KernelVersion: 4.0 +Description: Control descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class +Date: Dec 2014 +KernelVersion: 4.0 +Description: Class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class/ss +Date: Dec 2014 +KernelVersion: 4.0 +Description: Super speed control class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/class/fs +Date: Dec 2014 +KernelVersion: 4.0 +Description: Full speed control class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal +Date: Dec 2014 +KernelVersion: 4.0 +Description: Terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output +Date: Dec 2014 +KernelVersion: 4.0 +Description: Output terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/output/default +Date: Dec 2014 +KernelVersion: 4.0 +Description: Default output terminal descriptors + + All attributes read only: + iTerminal - index of string descriptor + bSourceID - id of the terminal to which this terminal + is connected + bAssocTerminal - id of the input terminal to which this output + terminal is associated + wTerminalType - terminal type + bTerminalID - a non-zero id of this terminal + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera +Date: Dec 2014 +KernelVersion: 4.0 +Description: Camera terminal descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera/default +Date: Dec 2014 +KernelVersion: 4.0 +Description: Default camera terminal descriptors + + All attributes read only: + bmControls - bitmap specifying which controls are + supported for the video stream + wOcularFocalLength - the value of Locular + wObjectiveFocalLengthMax- the value of Lmin + wObjectiveFocalLengthMin- the value of Lmax + iTerminal - index of string descriptor + bAssocTerminal - id of the output terminal to which + this terminal is connected + wTerminalType - terminal type + bTerminalID - a non-zero id of this terminal + +What: /config/usb-gadget/gadget/functions/uvc.name/control/processing +Date: Dec 2014 +KernelVersion: 4.0 +Description: Processing unit descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/processing/default +Date: Dec 2014 +KernelVersion: 4.0 +Description: Default processing unit descriptors + + All attributes read only: + iProcessing - index of string descriptor + bmControls - bitmap specifying which controls are + supported for the video stream + wMaxMultiplier - maximum digital magnification x100 + bSourceID - id of the terminal to which this unit is + connected + bUnitID - a non-zero id of this unit + +What: /config/usb-gadget/gadget/functions/uvc.name/control/header +Date: Dec 2014 +KernelVersion: 4.0 +Description: Control header descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/control/header/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific control header descriptors + +dwClockFrequency +bcdUVC +What: /config/usb-gadget/gadget/functions/uvc.name/streaming +Date: Dec 2014 +KernelVersion: 4.0 +Description: Streaming descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class +Date: Dec 2014 +KernelVersion: 4.0 +Description: Streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/ss +Date: Dec 2014 +KernelVersion: 4.0 +Description: Super speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/hs +Date: Dec 2014 +KernelVersion: 4.0 +Description: High speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class/fs +Date: Dec 2014 +KernelVersion: 4.0 +Description: Full speed streaming class descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching +Date: Dec 2014 +KernelVersion: 4.0 +Description: Color matching descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/color_matching/default +Date: Dec 2014 +KernelVersion: 4.0 +Description: Default color matching descriptors + + All attributes read only: + bMatrixCoefficients - matrix used to compute luma and + chroma values from the color primaries + bTransferCharacteristics- optoelectronic transfer + characteristic of the source picutre, + also called the gamma function + bColorPrimaries - color primaries and the reference + white + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg +Date: Dec 2014 +KernelVersion: 4.0 +Description: MJPEG format descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific MJPEG format descriptors + + All attributes read only, + except bmaControls and bDefaultFrameIndex: + bmaControls - this format's data for bmaControls in + the streaming header + bmInterfaceFlags - specifies interlace information, + read-only + bAspectRatioY - the X dimension of the picture aspect + ratio, read-only + bAspectRatioX - the Y dimension of the picture aspect + ratio, read-only + bmFlags - characteristics of this format, + read-only + bDefaultFrameIndex - optimum frame index for this stream + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific MJPEG frame descriptors + + dwFrameInterval - indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval - the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize- the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate - the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate - the minimum bit rate at the longest + frame interval in bps + wHeight - height of decoded bitmap frame in px + wWidth - width of decoded bitmam frame in px + bmCapabilities - still image support, fixed frame-rate + support + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed +Date: Dec 2014 +KernelVersion: 4.0 +Description: Uncompressed format descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific uncompressed format descriptors + + bmaControls - this format's data for bmaControls in + the streaming header + bmInterfaceFlags - specifies interlace information, + read-only + bAspectRatioY - the X dimension of the picture aspect + ratio, read-only + bAspectRatioX - the Y dimension of the picture aspect + ratio, read-only + bDefaultFrameIndex - optimum frame index for this stream + bBitsPerPixel - number of bits per pixel used to + specify color in the decoded video + frame + guidFormat - globally unique id used to identify + stream-encoding format + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific uncompressed frame descriptors + + dwFrameInterval - indicates how frame interval can be + programmed; a number of values + separated by newline can be specified + dwDefaultFrameInterval - the frame interval the device would + like to use as default + dwMaxVideoFrameBufferSize- the maximum number of bytes the + compressor will produce for a video + frame or still image + dwMaxBitRate - the maximum bit rate at the shortest + frame interval in bps + dwMinBitRate - the minimum bit rate at the longest + frame interval in bps + wHeight - height of decoded bitmap frame in px + wWidth - width of decoded bitmam frame in px + bmCapabilities - still image support, fixed frame-rate + support + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header +Date: Dec 2014 +KernelVersion: 4.0 +Description: Streaming header descriptors + +What: /config/usb-gadget/gadget/functions/uvc.name/streaming/header/name +Date: Dec 2014 +KernelVersion: 4.0 +Description: Specific streaming header descriptors + + All attributes read only: + bTriggerUsage - how the host software will respond to + a hardware trigger interrupt event + bTriggerSupport - flag specifying if hardware + triggering is supported + bStillCaptureMethod - method of still image caputre + supported + bTerminalLink - id of the output terminal to which + the video endpoint of this interface + is connected + bmInfo - capabilities of this video streaming + interface
diff --git a/Documentation/ABI/testing/debugfs-driver-genwqe b/Documentation/ABI/testing/debugfs-driver-genwqe new file mode 100644 index 0000000..1c2f256 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-driver-genwqe
@@ -0,0 +1,91 @@ +What: /sys/kernel/debug/genwqe/genwqe<n>_card/ddcb_info +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: DDCB queue dump used for debugging queueing problems. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/curr_regs +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Dump of the current error registers. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/curr_dbg_uid0 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID0 (unit id 0). + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/curr_dbg_uid1 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID1. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/curr_dbg_uid2 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID2. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_regs +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Dump of the error registers before the last reset of + the card occured. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid0 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID0 before card was reset. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid1 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID1 before card was reset. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/prev_dbg_uid2 +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Internal chip state of UID2 before card was reset. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/info +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Comprehensive summary of bitstream version and software + version. Used bitstream and bitstream clocking information. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/err_inject +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Possibility to inject error cases to ensure that the drivers + error handling code works well. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/vf<0..14>_jobtimeout_msec +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Default VF timeout 250ms. Testing might require 1000ms. + Using 0 will use the cards default value (whatever that is). + + The timeout depends on the max number of available cards + in the system and the maximum allowed queue size. + + The driver ensures that the settings are done just before + the VFs get enabled. Changing the timeouts in flight is not + possible. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/jobtimer +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Dump job timeout register values for PF and VFs. + Only available for PF. + +What: /sys/kernel/debug/genwqe/genwqe<n>_card/queue_working_time +Date: Dec 2013 +Contact: haver@linux.vnet.ibm.com +Description: Dump queue working time register values for PF and VFs. + Only available for PF.
diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec new file mode 100644 index 0000000..6546115 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-ec
@@ -0,0 +1,20 @@ +What: /sys/kernel/debug/ec/*/{gpe,use_global_lock,io} +Date: July 2010 +Contact: Thomas Renninger <trenn@suse.de> +Description: + +General information like which GPE is assigned to the EC and whether +the global lock should get used. +Knowing the EC GPE one can watch the amount of HW events related to +the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe): +/sys/firmware/acpi/interrupts/gpeXY + +The io file is binary and a userspace tool located here: +ftp://ftp.suse.com/pub/people/trenn/sources/ec/ +should get used to read out the 256 Embedded Controller registers +or writing to them. + +CAUTION: Do not write to the Embedded Controller if you don't know +what you are doing! Rebooting afterwards also is a good idea. +This can influence the way your machine is cooled and fans may +not get switched on again after you did a wrong write.
diff --git a/Documentation/ABI/testing/debugfs-ideapad b/Documentation/ABI/testing/debugfs-ideapad new file mode 100644 index 0000000..7079c0b --- /dev/null +++ b/Documentation/ABI/testing/debugfs-ideapad
@@ -0,0 +1,19 @@ +What: /sys/kernel/debug/ideapad/cfg +Date: Sep 2011 +KernelVersion: 3.2 +Contact: Ike Panhc <ike.pan@canonical.com> +Description: + +cfg shows the return value of _CFG method in VPC2004 device. It tells machine +capability and what graphic component within the machine. + + +What: /sys/kernel/debug/ideapad/status +Date: Sep 2011 +KernelVersion: 3.2 +Contact: Ike Panhc <ike.pan@canonical.com> +Description: + +status shows infos we can read and tells its meaning and value. + +
diff --git a/Documentation/ABI/testing/debugfs-olpc b/Documentation/ABI/testing/debugfs-olpc new file mode 100644 index 0000000..bd76cc6 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-olpc
@@ -0,0 +1,16 @@ +What: /sys/kernel/debug/olpc-ec/cmd +Date: Dec 2011 +KernelVersion: 3.4 +Contact: devel@lists.laptop.org +Description: + +A generic interface for executing OLPC Embedded Controller commands and +reading their responses. + +To execute a command, write data with the format: CC:N A A A A +CC is the (hex) command, N is the count of expected reply bytes, and A A A A +are optional (hex) arguments. + +To read the response (if any), read from the generic node after executing +a command. Hex reply bytes will be returned, *whether or not* they came from +the immediately previous command.
diff --git a/Documentation/ABI/testing/debugfs-pfo-nx-crypto b/Documentation/ABI/testing/debugfs-pfo-nx-crypto new file mode 100644 index 0000000..685d5a4 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-pfo-nx-crypto
@@ -0,0 +1,45 @@ +What: /sys/kernel/debug/nx-crypto/* +Date: March 2012 +KernelVersion: 3.4 +Contact: Kent Yoder <key@linux.vnet.ibm.com> +Description: + + These debugfs interfaces are built by the nx-crypto driver, built in +arch/powerpc/crypto/nx. + +Error Detection +=============== + +errors: +- A u32 providing a total count of errors since the driver was loaded. The +only errors counted here are those returned from the hcall, H_COP_OP. + +last_error: +- The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not +recorded here (the hcall will retry until -EBUSY goes away). + +last_error_pid: +- The process ID of the process who received the most recent error from the +hcall. + +Device Use +========== + +aes_bytes: +- The total number of bytes encrypted using AES in any of the driver's +supported modes. + +aes_ops: +- The total number of AES operations submitted to the hardware. + +sha256_bytes: +- The total number of bytes hashed by the hardware using SHA-256. + +sha256_ops: +- The total number of SHA-256 operations submitted to the hardware. + +sha512_bytes: +- The total number of bytes hashed by the hardware using SHA-512. + +sha512_ops: +- The total number of SHA-512 operations submitted to the hardware.
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd new file mode 100644 index 0000000..cf11736 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-pktcdvd
@@ -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
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg new file mode 100644 index 0000000..fff817e --- /dev/null +++ b/Documentation/ABI/testing/dev-kmsg
@@ -0,0 +1,110 @@ +What: /dev/kmsg +Date: Mai 2012 +KernelVersion: 3.5 +Contact: Kay Sievers <kay@vrfy.org> +Description: The /dev/kmsg character device node provides userspace access + to the kernel's printk buffer. + + Injecting messages: + Every write() to the opened device node places a log entry in + the kernel's printk buffer. + + The logged line can be prefixed with a <N> syslog prefix, which + carries the syslog priority and facility. The single decimal + prefix number is composed of the 3 lowest bits being the syslog + priority and the higher bits the syslog facility number. + + If no prefix is given, the priority number is the default kernel + log priority and the facility number is set to LOG_USER (1). It + is not possible to inject messages from userspace with the + facility number LOG_KERN (0), to make sure that the origin of + the messages can always be reliably determined. + + Accessing the buffer: + Every read() from the opened device node receives one record + of the kernel's printk buffer. + + The first read() directly following an open() always returns + first message in the buffer; there is no kernel-internal + persistent state; many readers can concurrently open the device + and read from it, without affecting other readers. + + Every read() will receive the next available record. If no more + records are available read() will block, or if O_NONBLOCK is + used -EAGAIN returned. + + Messages in the record ring buffer get overwritten as whole, + there are never partial messages received by read(). + + In case messages get overwritten in the circular buffer while + the device is kept open, the next read() will return -EPIPE, + and the seek position be updated to the next available record. + Subsequent reads() will return available records again. + + Unlike the classic syslog() interface, the 64 bit record + sequence numbers allow to calculate the amount of lost + messages, in case the buffer gets overwritten. And they allow + to reconnect to the buffer and reconstruct the read position + if needed, without limiting the interface to a single reader. + + The device supports seek with the following parameters: + SEEK_SET, 0 + seek to the first entry in the buffer + SEEK_END, 0 + seek after the last entry in the buffer + SEEK_DATA, 0 + seek after the last record available at the time + the last SYSLOG_ACTION_CLEAR was issued. + + The output format consists of a prefix carrying the syslog + prefix including priority and facility, the 64 bit message + sequence number and the monotonic timestamp in microseconds, + and a flag field. All fields are separated by a ','. + + Future extensions might add more comma separated values before + the terminating ';'. Unknown fields and values should be + gracefully ignored. + + The human readable text string starts directly after the ';' + and is terminated by a '\n'. Untrusted values derived from + hardware or other facilities are printed, therefore + all non-printable characters and '\' itself in the log message + are escaped by "\x00" C-style hex encoding. + + A line starting with ' ', is a continuation line, adding + key/value pairs to the log message, which provide the machine + readable context of the message, for reliable processing in + userspace. + + Example: + 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) + SUBSYSTEM=acpi + DEVICE=+acpi:PNP0A03:00 + 6,339,5140900,-;NET: Registered protocol family 10 + 30,340,5690716,-;udevd[80]: starting version 181 + + The DEVICE= key uniquely identifies devices the following way: + b12:8 - block dev_t + c127:3 - char dev_t + n8 - netdev ifindex + +sound:card0 - subsystem:devname + + The flags field carries '-' by default. A 'c' indicates a + fragment of a line. All following fragments are flagged with + '+'. Note, that these hints about continuation lines are not + necessarily correct, and the stream could be interleaved with + unrelated messages, but merging the lines in the output + usually produces better human readable results. A similar + logic is used internally when messages are printed to the + console, /proc/kmsg or the syslog() syscall. + + By default, kernel tries to avoid fragments by concatenating + when it can and fragments are rare; however, when extended + console support is enabled, the in-kernel concatenation is + disabled and /dev/kmsg output will contain more fragments. If + the log consumer performs concatenation, the end result + should be the same. In the future, the in-kernel concatenation + may be removed entirely and /dev/kmsg users are recommended to + implement fragment handling. + +Users: dmesg(1), userspace kernel log consumers
diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm new file mode 100644 index 0000000..8374d45 --- /dev/null +++ b/Documentation/ABI/testing/evm
@@ -0,0 +1,23 @@ +What: security/evm +Date: March 2011 +Contact: Mimi Zohar <zohar@us.ibm.com> +Description: + EVM protects a file's security extended attributes(xattrs) + against integrity attacks. The initial method maintains an + HMAC-sha1 value across the extended attributes, storing the + value as the extended attribute 'security.evm'. + + EVM depends on the Kernel Key Retention System to provide it + with a trusted/encrypted key for the HMAC-sha1 operation. + The key is loaded onto the root's keyring using keyctl. Until + EVM receives notification that the key has been successfully + loaded onto the keyring (echo 1 > <securityfs>/evm), EVM + can not create or validate the 'security.evm' xattr, but + returns INTEGRITY_UNKNOWN. Loading the key and signaling EVM + should be done as early as possible. Normally this is done + in the initramfs, which has already been measured as part + of the trusted boot. For more information on creating and + loading existing trusted/encrypted keys, refer to: + Documentation/keys-trusted-encrypted.txt. (A sample dracut + patch, which loads the trusted/encrypted key and enables + EVM, is available from http://linux-ima.sourceforge.net/#EVM.)
diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev new file mode 100644 index 0000000..7b265fb --- /dev/null +++ b/Documentation/ABI/testing/gpio-cdev
@@ -0,0 +1,26 @@ +What: /dev/gpiochip[0-9]+ +Date: November 2015 +KernelVersion: 4.4 +Contact: linux-gpio@vger.kernel.org +Description: + The character device files /dev/gpiochip* are the interface + between GPIO chips and userspace. + + The ioctl(2)-based ABI is defined and documented in + [include/uapi]<linux/gpio.h>. + + The following file operations are supported: + + open(2) + Currently the only useful flags are O_RDWR. + + ioctl(2) + Initiate various actions. + See the inline documentation in [include/uapi]<linux/gpio.h> + for descriptions of all ioctls. + + close(2) + Stops and free up the I/O contexts that was associated + with the file descriptor. + +Users: TBD
diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy new file mode 100644 index 0000000..bb0f9a1 --- /dev/null +++ b/Documentation/ABI/testing/ima_policy
@@ -0,0 +1,98 @@ +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. + + IMA appraisal, if configured, uses these file measurements + for local measurement appraisal. + + rule format: action [condition ...] + + action: measure | dont_measure | appraise | dont_appraise | audit + condition:= base | lsm [option] + base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=] + [euid=] [fowner=]] + lsm: [[subj_user=] [subj_role=] [subj_type=] + [obj_user=] [obj_role=] [obj_type=]] + option: [[appraise_type=]] [permit_directio] + + base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK] + [FIRMWARE_CHECK] + [KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK] + mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND] + [[^]MAY_EXEC] + fsmagic:= hex value + fsuuid:= file system UUID (e.g 8bcbe394-4f13-4144-be8e-5aa9ea2ce2f6) + uid:= decimal value + euid:= decimal value + fowner:=decimal value + lsm: are LSM specific + option: appraise_type:= [imasig] + + default policy: + # PROC_SUPER_MAGIC + dont_measure fsmagic=0x9fa0 + dont_appraise fsmagic=0x9fa0 + # SYSFS_MAGIC + dont_measure fsmagic=0x62656572 + dont_appraise fsmagic=0x62656572 + # DEBUGFS_MAGIC + dont_measure fsmagic=0x64626720 + dont_appraise fsmagic=0x64626720 + # TMPFS_MAGIC + dont_measure fsmagic=0x01021994 + dont_appraise fsmagic=0x01021994 + # RAMFS_MAGIC + dont_appraise fsmagic=0x858458f6 + # DEVPTS_SUPER_MAGIC + dont_measure fsmagic=0x1cd1 + dont_appraise fsmagic=0x1cd1 + # BINFMTFS_MAGIC + dont_measure fsmagic=0x42494e4d + dont_appraise fsmagic=0x42494e4d + # SECURITYFS_MAGIC + dont_measure fsmagic=0x73636673 + dont_appraise fsmagic=0x73636673 + # SELINUX_MAGIC + dont_measure fsmagic=0xf97cff8c + dont_appraise fsmagic=0xf97cff8c + # CGROUP_SUPER_MAGIC + dont_measure fsmagic=0x27e0eb + dont_appraise fsmagic=0x27e0eb + # NSFS_MAGIC + dont_measure fsmagic=0x6e736673 + dont_appraise fsmagic=0x6e736673 + + measure func=BPRM_CHECK + measure func=FILE_MMAP mask=MAY_EXEC + measure func=FILE_CHECK mask=MAY_READ uid=0 + measure func=MODULE_CHECK + measure func=FIRMWARE_CHECK + appraise fowner=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 do_filp_open. The default appraisal + policy appraises all files owned by root. + + Examples of LSM specific definitions: + + SELinux: + dont_measure obj_type=var_log_t + dont_appraise obj_type=var_log_t + dont_measure obj_type=auditd_log_t + dont_appraise obj_type=auditd_log_t + measure subj_user=system_u func=FILE_CHECK mask=MAY_READ + measure subj_role=system_r func=FILE_CHECK mask=MAY_READ + + Smack: + measure subj_user=_ func=FILE_CHECK mask=MAY_READ
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats new file mode 100644 index 0000000..f91a973 --- /dev/null +++ b/Documentation/ABI/testing/procfs-diskstats
@@ -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 successfully + 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
diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore new file mode 100644 index 0000000..5fca9f5 --- /dev/null +++ b/Documentation/ABI/testing/pstore
@@ -0,0 +1,47 @@ +Where: /sys/fs/pstore/... (or /dev/pstore/...) +Date: March 2011 +Kernel Version: 2.6.39 +Contact: tony.luck@intel.com +Description: Generic interface to platform dependent persistent storage. + + Platforms that provide a mechanism to preserve some data + across system reboots can register with this driver to + provide a generic interface to show records captured in + the dying moments. In the case of a panic the last part + of the console log is captured, but other interesting + data can also be saved. + + # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore + + $ ls -l /sys/fs/pstore/ + total 0 + -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1 + + Different users of this interface will result in different + filename prefixes. Currently two are defined: + + "dmesg" - saved console log + "mce" - architecture dependent data from fatal h/w error + + Once the information in a file has been read, removing + the file will signal to the underlying persistent storage + device that it can reclaim the space for later re-use. + + $ rm /sys/fs/pstore/dmesg-erst-1 + + The expectation is that all files in /sys/fs/pstore/ + will be saved elsewhere and erased from persistent store + soon after boot to free up space ready for the next + catastrophe. + + The 'kmsg_bytes' mount option changes the target amount of + data saved on each oops/panic. Pstore saves (possibly + multiple) files based on the record size of the underlying + persistent storage until at least this amount is reached. + Default is 10 Kbytes. + + Pstore only supports one backend at a time. If multiple + backends are available, the preferred backend may be + set by passing the pstore.backend= argument to the kernel at + boot time. +
diff --git a/Documentation/ABI/testing/sysfs-ata b/Documentation/ABI/testing/sysfs-ata new file mode 100644 index 0000000..aa42964 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-ata
@@ -0,0 +1,110 @@ +What: /sys/class/ata_... +Date: August 2008 +Contact: Gwendal Grignou<gwendal@google.com> +Description: + +Provide a place in sysfs for storing the ATA topology of the system. This allows +retrieving various information about ATA objects. + +Files under /sys/class/ata_port +------------------------------- + + For each port, a directory ataX is created where X is the ata_port_id of + the port. The device parent is the ata host device. + +idle_irq (read) + + Number of IRQ received by the port while idle [some ata HBA only]. + +nr_pmp_links (read) + + If a SATA Port Multiplier (PM) is connected, number of link behind it. + +Files under /sys/class/ata_link +------------------------------- + + Behind each port, there is a ata_link. If there is a SATA PM in the + topology, 15 ata_link objects are created. + + If a link is behind a port, the directory name is linkX, where X is + ata_port_id of the port. + If a link is behind a PM, its name is linkX.Y where X is ata_port_id + of the parent port and Y the PM port. + +hw_sata_spd_limit + + Maximum speed supported by the connected SATA device. + +sata_spd_limit + + Maximum speed imposed by libata. + +sata_spd + + Current speed of the link [1.5, 3Gps,...]. + +Files under /sys/class/ata_device +--------------------------------- + + Behind each link, up to two ata device are created. + The name of the directory is devX[.Y].Z where: + - X is ata_port_id of the port where the device is connected, + - Y the port of the PM if any, and + - Z the device id: for PATA, there is usually 2 devices [0,1], + only 1 for SATA. + +class + Device class. Can be "ata" for disk, "atapi" for packet device, + "pmp" for PM, or "none" if no device was found behind the link. + +dma_mode + + Transfer modes supported by the device when in DMA mode. + Mostly used by PATA device. + +pio_mode + + Transfer modes supported by the device when in PIO mode. + Mostly used by PATA device. + +xfer_mode + + Current transfer mode. + +id + + Cached result of IDENTIFY command, as described in ATA8 7.16 and 7.17. + Only valid if the device is not a PM. + +gscr + + Cached result of the dump of PM GSCR register. + Valid registers are: + 0: SATA_PMP_GSCR_PROD_ID, + 1: SATA_PMP_GSCR_REV, + 2: SATA_PMP_GSCR_PORT_INFO, + 32: SATA_PMP_GSCR_ERROR, + 33: SATA_PMP_GSCR_ERROR_EN, + 64: SATA_PMP_GSCR_FEAT, + 96: SATA_PMP_GSCR_FEAT_EN, + 130: SATA_PMP_GSCR_SII_GPIO + Only valid if the device is a PM. + +trim + + Shows the DSM TRIM mode currently used by the device. Valid + values are: + unsupported: Drive does not support DSM TRIM + unqueued: Drive supports unqueued DSM TRIM only + queued: Drive supports queued DSM TRIM + forced_unqueued: Drive's queued DSM support is known to be + buggy and only unqueued TRIM commands + are sent + +spdn_cnt + + Number of time libata decided to lower the speed of link due to errors. + +ering + + Formatted output of the error ring of the device.
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block new file mode 100644 index 0000000..71d184d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block
@@ -0,0 +1,237 @@ +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 successfully + 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/device_is_integrity_capable +Date: July 2014 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Indicates whether a storage device is capable of storing + integrity metadata. Set if the device is T10 PI-capable. + +What: /sys/block/<disk>/integrity/protection_interval_bytes +Date: July 2015 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Describes the number of data bytes which are protected + by one integrity tuple. Typically the device's logical + block size. + +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. + +What: /sys/block/<disk>/queue/nomerges +Date: January 2010 +Contact: +Description: + Standard I/O elevator operations include attempts to + merge contiguous I/Os. For known random I/O loads these + attempts will always fail and result in extra cycles + being spent in the kernel. This allows one to turn off + this behavior on one of two ways: When set to 1, complex + merge checks are disabled, but the simple one-shot merges + with the previous I/O request are enabled. When set to 2, + all merge tries are disabled. The default value is 0 - + which enables all types of merge tries. + +What: /sys/block/<disk>/discard_alignment +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may + internally allocate space in units that are bigger than + the exported logical block size. The discard_alignment + parameter indicates how many bytes the beginning of the + device is offset from the internal allocation unit's + natural alignment. + +What: /sys/block/<disk>/<partition>/discard_alignment +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may + internally allocate space in units that are bigger than + the exported logical block size. The discard_alignment + parameter indicates how many bytes the beginning of the + partition is offset from the internal allocation unit's + natural alignment. + +What: /sys/block/<disk>/queue/discard_granularity +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may + internally allocate space using units that are bigger + than the logical block size. The discard_granularity + parameter indicates the size of the internal allocation + unit in bytes if reported by the device. Otherwise the + discard_granularity will be set to match the device's + physical block size. A discard_granularity of 0 means + that the device does not support discard functionality. + +What: /sys/block/<disk>/queue/discard_max_bytes +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may have + internal limits on the number of bytes that can be + trimmed or unmapped in a single operation. Some storage + protocols also have inherent limits on the number of + blocks that can be described in a single command. The + discard_max_bytes parameter is set by the device driver + to the maximum number of bytes that can be discarded in + a single operation. Discard requests issued to the + device must not exceed this limit. A discard_max_bytes + value of 0 means that the device does not support + discard functionality. + +What: /sys/block/<disk>/queue/discard_zeroes_data +Date: May 2011 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Devices that support discard functionality may return + stale or random data when a previously discarded block + is read back. This can cause problems if the filesystem + expects discarded blocks to be explicitly cleared. If a + device reports that it deterministically returns zeroes + when a discarded area is read the discard_zeroes_data + parameter will be set to one. Otherwise it will be 0 and + the result of reading a discarded area is undefined. + +What: /sys/block/<disk>/queue/write_same_max_bytes +Date: January 2012 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Some devices support a write same operation in which a + single data block can be written to a range of several + contiguous blocks on storage. This can be used to wipe + areas on disk or to initialize drives in a RAID + configuration. write_same_max_bytes indicates how many + bytes can be written in a single write same command. If + write_same_max_bytes is 0, write same is not supported + by the device. +
diff --git a/Documentation/ABI/testing/sysfs-block-bcache b/Documentation/ABI/testing/sysfs-block-bcache new file mode 100644 index 0000000..9e4bbc5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-bcache
@@ -0,0 +1,156 @@ +What: /sys/block/<disk>/bcache/unregister +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + A write to this file causes the backing device or cache to be + unregistered. If a backing device had dirty data in the cache, + writeback mode is automatically disabled and all dirty data is + flushed before the device is unregistered. Caches unregister + all associated backing devices before unregistering themselves. + +What: /sys/block/<disk>/bcache/clear_stats +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Writing to this file resets all the statistics for the device. + +What: /sys/block/<disk>/bcache/cache +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a backing device that has cache, a symlink to + the bcache/ dir of that cache. + +What: /sys/block/<disk>/bcache/cache_hits +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: integer number of full cache hits, + counted per bio. A partial cache hit counts as a miss. + +What: /sys/block/<disk>/bcache/cache_misses +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: integer number of cache misses. + +What: /sys/block/<disk>/bcache/cache_hit_ratio +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: cache hits as a percentage. + +What: /sys/block/<disk>/bcache/sequential_cutoff +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: Threshold past which sequential IO will + skip the cache. Read and written as bytes in human readable + units (i.e. echo 10M > sequntial_cutoff). + +What: /sys/block/<disk>/bcache/bypassed +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Sum of all reads and writes that have bypassed the cache (due + to the sequential cutoff). Expressed as bytes in human + readable units. + +What: /sys/block/<disk>/bcache/writeback +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: When on, writeback caching is enabled and + writes will be buffered in the cache. When off, caching is in + writethrough mode; reads and writes will be added to the + cache but no write buffering will take place. + +What: /sys/block/<disk>/bcache/writeback_running +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: when off, dirty data will not be written + from the cache to the backing device. The cache will still be + used to buffer writes until it is mostly full, at which point + writes transparently revert to writethrough mode. Intended only + for benchmarking/testing. + +What: /sys/block/<disk>/bcache/writeback_delay +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: In writeback mode, when dirty data is + written to the cache and the cache held no dirty data for that + backing device, writeback from cache to backing device starts + after this delay, expressed as an integer number of seconds. + +What: /sys/block/<disk>/bcache/writeback_percent +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: If nonzero, writeback from cache to + backing device only takes place when more than this percentage + of the cache is used, allowing more write coalescing to take + place and reducing total number of writes sent to the backing + device. Integer between 0 and 40. + +What: /sys/block/<disk>/bcache/synchronous +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, a boolean that allows synchronous mode to be + switched on and off. In synchronous mode all writes are ordered + such that the cache can reliably recover from unclean shutdown; + if disabled bcache will not generally wait for writes to + complete but if the cache is not shut down cleanly all data + will be discarded from the cache. Should not be turned off with + writeback caching enabled. + +What: /sys/block/<disk>/bcache/discard +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, a boolean allowing discard/TRIM to be turned off + or back on if the device supports it. + +What: /sys/block/<disk>/bcache/bucket_size +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, bucket size in human readable units, as set at + cache creation time; should match the erase block size of the + SSD for optimal performance. + +What: /sys/block/<disk>/bcache/nbuckets +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, the number of usable buckets. + +What: /sys/block/<disk>/bcache/tree_depth +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, height of the btree excluding leaf nodes (i.e. a + one node tree will have a depth of 0). + +What: /sys/block/<disk>/bcache/btree_cache_size +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Number of btree buckets/nodes that are currently cached in + memory; cache dynamically grows and shrinks in response to + memory pressure from the rest of the system. + +What: /sys/block/<disk>/bcache/written +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, total amount of data in human readable units + written to the cache, excluding all metadata. + +What: /sys/block/<disk>/bcache/btree_written +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, sum of all btree writes in human readable units.
diff --git a/Documentation/ABI/testing/sysfs-block-dm b/Documentation/ABI/testing/sysfs-block-dm new file mode 100644 index 0000000..f9f2339 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-dm
@@ -0,0 +1,47 @@ +What: /sys/block/dm-<num>/dm/name +Date: January 2009 +KernelVersion: 2.6.29 +Contact: dm-devel@redhat.com +Description: Device-mapper device name. + Read-only string containing mapped device name. +Users: util-linux, device-mapper udev rules + +What: /sys/block/dm-<num>/dm/uuid +Date: January 2009 +KernelVersion: 2.6.29 +Contact: dm-devel@redhat.com +Description: Device-mapper device UUID. + Read-only string containing DM-UUID or empty string + if DM-UUID is not set. +Users: util-linux, device-mapper udev rules + +What: /sys/block/dm-<num>/dm/suspended +Date: June 2009 +KernelVersion: 2.6.31 +Contact: dm-devel@redhat.com +Description: Device-mapper device suspend state. + Contains the value 1 while the device is suspended. + Otherwise it contains 0. Read-only attribute. +Users: util-linux, device-mapper udev rules + +What: /sys/block/dm-<num>/dm/rq_based_seq_io_merge_deadline +Date: March 2015 +KernelVersion: 4.1 +Contact: dm-devel@redhat.com +Description: Allow control over how long a request that is a + reasonable merge candidate can be queued on the request + queue. The resolution of this deadline is in + microseconds (ranging from 1 to 100000 usecs). + Setting this attribute to 0 (the default) will disable + request-based DM's merge heuristic and associated extra + accounting. This attribute is not applicable to + bio-based DM devices so it will only ever report 0 for + them. + +What: /sys/block/dm-<num>/dm/use_blk_mq +Date: March 2015 +KernelVersion: 4.1 +Contact: dm-devel@redhat.com +Description: Request-based Device-mapper blk-mq I/O path mode. + Contains the value 1 if the device is using blk-mq. + Otherwise it contains 0. Read-only attribute.
diff --git a/Documentation/ABI/testing/sysfs-block-rssd b/Documentation/ABI/testing/sysfs-block-rssd new file mode 100644 index 0000000..beef30c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-rssd
@@ -0,0 +1,5 @@ +What: /sys/block/rssd*/status +Date: April 2012 +KernelVersion: 3.4 +Contact: Asai Thambi S P <asamymuthupa@micron.com> +Description: This is a read-only file. Indicates the status of the device.
diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram new file mode 100644 index 0000000..4518d30 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-zram
@@ -0,0 +1,177 @@ +What: /sys/block/zram<id>/disksize +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The disksize file is read-write and specifies the disk size + which represents the limit on the *uncompressed* worth of data + that can be stored in this disk. + Unit: bytes + +What: /sys/block/zram<id>/initstate +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The initstate file is read-only and shows the initialization + state of the device. + +What: /sys/block/zram<id>/reset +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The reset file is write-only and allows resetting the + device. The reset operation frees all the memory associated + with this device. + +What: /sys/block/zram<id>/num_reads +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The num_reads file is read-only and specifies the number of + reads (failed or successful) done on this device. + +What: /sys/block/zram<id>/num_writes +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The num_writes file is read-only and specifies the number of + writes (failed or successful) done on this device. + +What: /sys/block/zram<id>/invalid_io +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The invalid_io file is read-only and specifies the number of + non-page-size-aligned I/O requests issued to this device. + +What: /sys/block/zram<id>/failed_reads +Date: February 2014 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The failed_reads file is read-only and specifies the number of + failed reads happened on this device. + +What: /sys/block/zram<id>/failed_writes +Date: February 2014 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The failed_writes file is read-only and specifies the number of + failed writes happened on this device. + +What: /sys/block/zram<id>/max_comp_streams +Date: February 2014 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The max_comp_streams file is read-write and specifies the + number of backend's zcomp_strm compression streams (number of + concurrent compress operations). + +What: /sys/block/zram<id>/comp_algorithm +Date: February 2014 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The comp_algorithm file is read-write and lets to show + available and selected compression algorithms, change + compression algorithm selection. + +What: /sys/block/zram<id>/notify_free +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The notify_free file is read-only. Depending on device usage + scenario it may account a) the number of pages freed because + of swap slot free notifications or b) the number of pages freed + because of REQ_DISCARD requests sent by bio. The former ones + are sent to a swap block device when a swap slot is freed, which + implies that this disk is being used as a swap disk. The latter + ones are sent by filesystem mounted with discard option, + whenever some data blocks are getting discarded. + +What: /sys/block/zram<id>/zero_pages +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The zero_pages file is read-only and specifies number of zero + filled pages written to this disk. No memory is allocated for + such pages. + +What: /sys/block/zram<id>/orig_data_size +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The orig_data_size file is read-only and specifies uncompressed + size of data stored in this disk. This excludes zero-filled + pages (zero_pages) since no memory is allocated for them. + Unit: bytes + +What: /sys/block/zram<id>/compr_data_size +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The compr_data_size file is read-only and specifies compressed + size of data stored in this disk. So, compression ratio can be + calculated using orig_data_size and this statistic. + Unit: bytes + +What: /sys/block/zram<id>/mem_used_total +Date: August 2010 +Contact: Nitin Gupta <ngupta@vflare.org> +Description: + The mem_used_total file is read-only and specifies the amount + of memory, including allocator fragmentation and metadata + overhead, allocated for this disk. So, allocator space + efficiency can be calculated using compr_data_size and this + statistic. + Unit: bytes + +What: /sys/block/zram<id>/mem_used_max +Date: August 2014 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The mem_used_max file is read/write and specifies the amount + of maximum memory zram have consumed to store compressed data. + For resetting the value, you should write "0". Otherwise, + you could see -EINVAL. + Unit: bytes + +What: /sys/block/zram<id>/mem_limit +Date: August 2014 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The mem_limit file is read/write and specifies the maximum + amount of memory ZRAM can use to store the compressed data. The + limit could be changed in run time and "0" means disable the + limit. No limit is the initial state. Unit: bytes + +What: /sys/block/zram<id>/compact +Date: August 2015 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The compact file is write-only and trigger compaction for + allocator zrm uses. The allocator moves some objects so that + it could free fragment space. + +What: /sys/block/zram<id>/io_stat +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The io_stat file is read-only and accumulates device's I/O + statistics not accounted by block layer. For example, + failed_reads, failed_writes, etc. File format is similar to + block layer statistics file format. + +What: /sys/block/zram<id>/mm_stat +Date: August 2015 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The mm_stat file is read-only and represents device's mm + statistics (orig_data_size, compr_data_size, etc.) in a format + similar to block layer statistics file format. + +What: /sys/block/zram<id>/debug_stat +Date: July 2016 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The debug_stat file is read-only and represents various + device's debugging info useful for kernel developers. Its + format is not documented intentionally and may change + anytime without any notice.
diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi new file mode 100644 index 0000000..7fa9cbc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-acpi
@@ -0,0 +1,58 @@ +What: /sys/bus/acpi/devices/.../path +Date: December 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the full path of ACPI namespace + object associated with the device object. For example, + \_SB_.PCI0. + This file is not present for device objects representing + fixed ACPI hardware features (like power and sleep + buttons). + +What: /sys/bus/acpi/devices/.../modalias +Date: July 2007 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the PNP IDs of the device object. + That is acpi:HHHHHHHH:[CCCCCCC:]. Where each HHHHHHHH or + CCCCCCCC contains device object's PNPID (_HID or _CID). + +What: /sys/bus/acpi/devices/.../hid +Date: April 2005 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the hardware ID (_HID) of the + device object. For example, PNP0103. + This file is present for device objects having the _HID + control method. + +What: /sys/bus/acpi/devices/.../description +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _STR control method, if present. + +What: /sys/bus/acpi/devices/.../adr +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _ADR control method, which is present for ACPI device + objects representing devices having standard enumeration + algorithms, such as PCI. + +What: /sys/bus/acpi/devices/.../uid +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _UID control method, if present. + +What: /sys/bus/acpi/devices/.../eject +Date: December 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + Writing 1 to this attribute will trigger hot removal of + this device object. This file exists for every device + object that has _EJ0 method.
diff --git a/Documentation/ABI/testing/sysfs-bus-amba b/Documentation/ABI/testing/sysfs-bus-amba new file mode 100644 index 0000000..e7b5467 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-amba
@@ -0,0 +1,20 @@ +What: /sys/bus/amba/devices/.../driver_override +Date: September 2014 +Contact: Antonios Motakis <a.motakis@virtualopensystems.com> +Description: + This file allows the driver for a device to be specified which + will override standard OF, ACPI, ID table, and name matching. + When specified, only a driver with a name matching the value + written to driver_override will have an opportunity to bind to + the device. The override is specified by writing a string to the + driver_override file (echo vfio-amba > driver_override) and may + be cleared with an empty string (echo > driver_override). + This returns the device to standard matching rules binding. + Writing to driver_override does not automatically unbind the + device from its current driver or make any attempt to + automatically load the specified driver. If no driver with a + matching name is currently loaded in the kernel, the device will + not bind to any driver. This also allows devices to opt-out of + driver binding using a driver_override name such as "none". + Only a single driver may be specified in the override, there is + no support for parsing delimiters.
diff --git a/Documentation/ABI/testing/sysfs-bus-bcma b/Documentation/ABI/testing/sysfs-bus-bcma new file mode 100644 index 0000000..721b4ae --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-bcma
@@ -0,0 +1,31 @@ +What: /sys/bus/bcma/devices/.../manuf +Date: May 2011 +KernelVersion: 3.0 +Contact: Rafał Miłecki <zajec5@gmail.com> +Description: + Each BCMA core has it's manufacturer id. See + include/linux/bcma/bcma.h for possible values. + +What: /sys/bus/bcma/devices/.../id +Date: May 2011 +KernelVersion: 3.0 +Contact: Rafał Miłecki <zajec5@gmail.com> +Description: + There are a few types of BCMA cores, they can be identified by + id field. + +What: /sys/bus/bcma/devices/.../rev +Date: May 2011 +KernelVersion: 3.0 +Contact: Rafał Miłecki <zajec5@gmail.com> +Description: + BCMA cores of the same type can still slightly differ depending + on their revision. Use it for detailed programming. + +What: /sys/bus/bcma/devices/.../class +Date: May 2011 +KernelVersion: 3.0 +Contact: Rafał Miłecki <zajec5@gmail.com> +Description: + Each BCMA core is identified by few fields, including class it + belongs to. See include/linux/bcma/bcma.h for possible values.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 new file mode 100644 index 0000000..b5f5260 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
@@ -0,0 +1,79 @@ +What: /sys/bus/coresight/devices/<memory_map>.etb/enable_sink +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Add/remove a sink from a trace path. There can be multiple + source for a single sink. + ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink + +What: /sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. The number of 32-bit words written + into the Trace RAM following the trigger event is equal to the + value stored in this register+1 (from ARM ETB-TRM). + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rdp +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Defines the depth, in words, of the trace RAM in powers of + 2. The value is read directly from HW register RDP, 0x004. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/sts +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB status register. The value + is read directly from HW register STS, 0x00C. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rrp +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB RAM Read Pointer register + that is used to read entries from the Trace RAM over the APB + interface. The value is read directly from HW register RRP, + 0x014. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/rwp +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB RAM Write Pointer register + that is used to sets the write pointer to write entries from + the CoreSight bus into the Trace RAM. The value is read directly + from HW register RWP, 0x018. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/trg +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Similar to "trigger_cntr" above except that this value is + read directly from HW register TRG, 0x01C. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ctl +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB Control register. The value + is read directly from HW register CTL, 0x020. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffsr +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB Formatter and Flush Status + register. The value is read directly from HW register FFSR, + 0x300. + +What: /sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffcr +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the ETB Formatter and Flush Control + register. The value is read directly from HW register FFCR, + 0x304.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x new file mode 100644 index 0000000..924265a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
@@ -0,0 +1,322 @@ +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_source +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enable/disable tracing on this specific trace entiry. + Enabling a source implies the source has been configured + properly and a sink has been identidifed for it. The path + of coresight components linking the source to the sink is + configured and managed automatically by the coresight framework. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: Select which address comparator or pair (of comparators) to + work with. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_acctype +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies + characteristics about the address comparator being configure, + for example the access type, the kind of instruction to trace, + processor contect ID to trigger on, etc. Individual fields in + the access type register may vary on the version of the trace + entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_range +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the range of + addresses to trigger on. Inclusion or exclusion is specificed + in the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_single +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to trigger on, highly influenced by the configuration + options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_start +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to start tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/addr_stop +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with @addr_idx. Specifies the single + address to stop tracing on, highly influenced by the + configuration options of the corresponding access type register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the counter to work on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_val +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload value register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cntr_rld_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used in conjunction with cntr_idx, give access to the + counter reload event register. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_idx +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Specifies the index of the context ID register to be + selected. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_mask +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Mask to apply to all the context ID comparator. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/ctxid_pid +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used with the ctxid_idx, specify with context ID to trigger + on. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/enable_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines which event triggers a trace. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/etmsr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Gives access to the ETM status register, which holds + programming information and status on certains events. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/fifofull_level +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Number of byte left in the fifo before considering it full. + Depending on the tracer's version, can also hold threshold for + data suppression. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mode +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Interface with the driver's 'mode' field, controlling + various aspect of the trace entity such as time stamping, + context ID size and cycle accurate tracing. Driver specific + and bound to change depending on the driver. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of address comparators pairs accessible + on a trace unit, as specified by bit 3:0 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of counters accessible on a trace unit, + as specified by bit 15:13 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Provides the number of context ID comparator available on a + trace unit, as specified by bit 25:24 of register ETMCCR. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (W) Cancels all configuration on a trace unit and set it back + to its boot configuration. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_13_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 1 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_21_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_23_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 2 to state 3. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_31_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 1. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_32_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines the event that causes the sequencer to transition + from state 3 to state 2. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Holds the current state of the sequencer. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace synchronization frequency value - must be + programmed with the various implementation behavior in mind. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/timestamp_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines an event that requests the insertion of a timestamp + into the trace stream. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/traceid +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace ID that will appear in the trace stream + coming from this trace entity. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/trigger_event +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Define the event that controls the trigger. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/cpu +Date: October 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Holds the cpu number this tracer is affined to. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Configuration Code register + (0x004). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmccer +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Configuration Code Extension + register (0x1e8). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmscr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM System Configuration + register (0x014). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmidr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM ID register (0x1e4). The + value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmcr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Main Control register (0x000). + The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtraceidr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace ID register (0x200). + The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmteevr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace Enable Event register + (0x020). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtsscr +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Trace Start/Stop Conrol + register (0x018). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr1 +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Enable Conrol #1 + register (0x024). The value is read directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.[etm|ptm]/mgmt/etmtecr2 +Date: September 2015 +KernelVersion: 4.4 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RO) Print the content of the ETM Enable Conrol #2 + register (0x01c). The value is read directly from the HW.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x new file mode 100644 index 0000000..36258bc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
@@ -0,0 +1,463 @@ +What: /sys/bus/coresight/devices/<memory_map>.etm/enable_source +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enable/disable tracing on this specific trace entiry. + Enabling a source implies the source has been configured + properly and a sink has been identidifed for it. The path + of coresight components linking the source to the sink is + configured and managed automatically by the coresight framework. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cpu +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) The CPU this tracing entity is associated with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_pe_cmp +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of PE comparator inputs that are + available for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_addr_cmp +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of address comparator pairs that are + available for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_cntr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of counters that are available for + tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_ext_inp +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates how many external inputs are implemented. + +What: /sys/bus/coresight/devices/<memory_map>.etm/numcidc +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of Context ID comparators that are + available for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/numvmidc +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of VMID comparators that are available + for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nrseqstate +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of sequencer states that are + implemented. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_resource +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of resource selection pairs that are + available for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/nr_ss_cmp +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the number of single-shot comparator controls that + are available for tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/reset +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (W) Cancels all configuration on a trace unit and set it back + to its boot configuration. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mode +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls various modes supported by this ETM, for example + P0 instruction tracing, branch broadcast, cycle counting and + context ID tracing. + +What: /sys/bus/coresight/devices/<memory_map>.etm/pe +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls which PE to trace. + +What: /sys/bus/coresight/devices/<memory_map>.etm/event +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls the tracing of arbitrary events from bank 0 to 3. + +What: /sys/bus/coresight/devices/<memory_map>.etm/event_instren +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls the behavior of the events in bank 0 to 3. + +What: /sys/bus/coresight/devices/<memory_map>.etm/event_ts +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls the insertion of global timestamps in the trace + streams. + +What: /sys/bus/coresight/devices/<memory_map>.etm/syncfreq +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls how often trace synchronization requests occur. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cyc_threshold +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Sets the threshold value for cycle counting. + +What: /sys/bus/coresight/devices/<memory_map>.etm/bb_ctrl +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls which regions in the memory map are enabled to + use branch broadcasting. + +What: /sys/bus/coresight/devices/<memory_map>.etm/event_vinst +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls instruction trace filtering. + +What: /sys/bus/coresight/devices/<memory_map>.etm/s_exlevel_vinst +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) In Secure state, each bit controls whether instruction + tracing is enabled for the corresponding exception level. + +What: /sys/bus/coresight/devices/<memory_map>.etm/ns_exlevel_vinst +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) In non-secure state, each bit controls whether instruction + tracing is enabled for the corresponding exception level. + +What: /sys/bus/coresight/devices/<memory_map>.etm/addr_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which address comparator or pair (of comparators) to + work with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/addr_instdatatype +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls what type of comparison the trace unit performs. + +What: /sys/bus/coresight/devices/<memory_map>.etm/addr_single +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used to setup single address comparator values. + +What: /sys/bus/coresight/devices/<memory_map>.etm/addr_range +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used to setup address range comparator values. + +What: /sys/bus/coresight/devices/<memory_map>.etm/seq_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which sequensor. + +What: /sys/bus/coresight/devices/<memory_map>.etm/seq_state +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Use this to set, or read, the sequencer state. + +What: /sys/bus/coresight/devices/<memory_map>.etm/seq_event +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Moves the sequencer state to a specific state. + +What: /sys/bus/coresight/devices/<memory_map>.etm/seq_reset_event +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Moves the sequencer to state 0 when a programmed event + occurs. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cntr_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which counter unit to work with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cntrldvr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) This sets or returns the reload count value of the + specific counter. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cntr_val +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) This sets or returns the current count value of the + specific counter. + +What: /sys/bus/coresight/devices/<memory_map>.etm/cntr_ctrl +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls the operation of the selected counter. + +What: /sys/bus/coresight/devices/<memory_map>.etm/res_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which resource selection unit to work with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/res_ctrl +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Controls the selection of the resources in the trace unit. + +What: /sys/bus/coresight/devices/<memory_map>.etm/ctxid_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which context ID comparator to work with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/ctxid_pid +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Get/Set the context ID comparator value to trigger on. + +What: /sys/bus/coresight/devices/<memory_map>.etm/ctxid_masks +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Mask for all 8 context ID comparator value + registers (if implemented). + +What: /sys/bus/coresight/devices/<memory_map>.etm/vmid_idx +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Select which virtual machine ID comparator to work with. + +What: /sys/bus/coresight/devices/<memory_map>.etm/vmid_val +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Get/Set the virtual machine ID comparator value to + trigger on. + +What: /sys/bus/coresight/devices/<memory_map>.etm/vmid_masks +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Mask for all 8 virtual machine ID comparator value + registers (if implemented). + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcoslsr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the OS Lock Status Register (0x304). + The value it taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpdcr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Power Down Control Register + (0x310). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpdsr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Power Down Status Register + (0x314). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trclsr +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the SW Lock Status Register + (0xFB4). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcauthstatus +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Authentication Status Register + (0xFB8). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcdevid +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Device ID Register + (0xFC8). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcdevtype +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Device Type Register + (0xFCC). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr0 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Peripheral ID0 Register + (0xFE0). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr1 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Peripheral ID1 Register + (0xFE4). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr2 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Peripheral ID2 Register + (0xFE8). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcpidr3 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the Peripheral ID3 Register + (0xFEC). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trcconfig +Date: February 2016 +KernelVersion: 4.07 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the trace configuration register + (0x010) as currently set by SW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/mgmt/trctraceid +Date: February 2016 +KernelVersion: 4.07 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Print the content of the trace ID register (0x040). + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr0 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the tracing capabilities of the trace unit (0x1E0). + The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr1 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the tracing capabilities of the trace unit (0x1E4). + The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr2 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the maximum size of the data value, data address, + VMID, context ID and instuction address in the trace unit + (0x1E8). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr3 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the value associated with various resources + available to the trace unit. See the Trace Macrocell + architecture specification for more details (0x1E8). + The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr4 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns how many resources the trace unit supports (0x1F0). + The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr5 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns how many resources the trace unit supports (0x1F4). + The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr8 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the maximum speculation depth of the instruction + trace stream. (0x180). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr9 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the number of P0 right-hand keys that the trace unit + can use (0x184). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr10 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the number of P1 right-hand keys that the trace unit + can use (0x188). The value is taken directly from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr11 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the number of special P1 right-hand keys that the + trace unit can use (0x18C). The value is taken directly from + the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr12 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the number of conditional P1 right-hand keys that + the trace unit can use (0x190). The value is taken directly + from the HW. + +What: /sys/bus/coresight/devices/<memory_map>.etm/trcidr/trcidr13 +Date: April 2015 +KernelVersion: 4.01 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Returns the number of special conditional P1 right-hand keys + that the trace unit can use (0x194). The value is taken + directly from the HW.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel new file mode 100644 index 0000000..d75acda --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-funnel
@@ -0,0 +1,12 @@ +What: /sys/bus/coresight/devices/<memory_map>.funnel/funnel_ctrl +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enables the slave ports and defines the hold time of the + slave ports. + +What: /sys/bus/coresight/devices/<memory_map>.funnel/priority +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Defines input port priority order.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm new file mode 100644 index 0000000..1dffabe --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
@@ -0,0 +1,53 @@ +What: /sys/bus/coresight/devices/<memory_map>.stm/enable_source +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Enable/disable tracing on this specific trace macrocell. + Enabling the trace macrocell implies it has been configured + properly and a sink has been identified for it. The path + of coresight components linking the source to the sink is + configured and managed automatically by the coresight framework. + +What: /sys/bus/coresight/devices/<memory_map>.stm/hwevent_enable +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Provides access to the HW event enable register, used in + conjunction with HW event bank select register. + +What: /sys/bus/coresight/devices/<memory_map>.stm/hwevent_select +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Gives access to the HW event block select register + (STMHEBSR) in order to configure up to 256 channels. Used in + conjunction with "hwevent_enable" register as described above. + +What: /sys/bus/coresight/devices/<memory_map>.stm/port_enable +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Provides access to the stimulus port enable register + (STMSPER). Used in conjunction with "port_select" described + below. + +What: /sys/bus/coresight/devices/<memory_map>.stm/port_select +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Used to determine which bank of stimulus port bit in + register STMSPER (see above) apply to. + +What: /sys/bus/coresight/devices/<memory_map>.stm/status +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) List various control and status registers. The specific + layout and content is driver specific. + +What: /sys/bus/coresight/devices/<memory_map>.stm/traceid +Date: April 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Holds the trace ID that will appear in the trace stream + coming from this trace entity.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc new file mode 100644 index 0000000..4fe677e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
@@ -0,0 +1,85 @@ +What: /sys/bus/coresight/devices/<memory_map>.tmc/trigger_cntr +Date: November 2014 +KernelVersion: 3.19 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (RW) Disables write access to the Trace RAM by stopping the + formatter after a defined number of words have been stored + following the trigger event. Additional interface for this + driver are expected to be added as it matures. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rsz +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Defines the size, in 32-bit words, of the local RAM buffer. + The value is read directly from HW register RSZ, 0x004. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/sts +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC status register. The value + is read directly from HW register STS, 0x00C. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rrp +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC RAM Read Pointer register + that is used to read entries from the Trace RAM over the APB + interface. The value is read directly from HW register RRP, + 0x014. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rwp +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC RAM Write Pointer register + that is used to sets the write pointer to write entries from + the CoreSight bus into the Trace RAM. The value is read directly + from HW register RWP, 0x018. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/trg +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Similar to "trigger_cntr" above except that this value is + read directly from HW register TRG, 0x01C. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ctl +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC Control register. The value + is read directly from HW register CTL, 0x020. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffsr +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC Formatter and Flush Status + register. The value is read directly from HW register FFSR, + 0x300. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffcr +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC Formatter and Flush Control + register. The value is read directly from HW register FFCR, + 0x304. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/mode +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Shows the value held by the TMC Mode register, which + indicate the mode the device has been configured to enact. The + The value is read directly from the MODE register, 0x028. + +What: /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/devid +Date: March 2016 +KernelVersion: 4.7 +Contact: Mathieu Poirier <mathieu.poirier@linaro.org> +Description: (R) Indicates the capabilities of the Coresight TMC. + The value is read directly from the DEVID register, 0xFC8,
diff --git a/Documentation/ABI/testing/sysfs-bus-css b/Documentation/ABI/testing/sysfs-bus-css new file mode 100644 index 0000000..2979c40 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-css
@@ -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 necessarily + in sync with the values current in the channel subsystem). + Note: This is an I/O-subchannel specific attribute. +Users: s390-tools, HAL
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events new file mode 100644 index 0000000..505f080 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events
@@ -0,0 +1,94 @@ +What: /sys/devices/cpu/events/ + /sys/devices/cpu/events/branch-misses + /sys/devices/cpu/events/cache-references + /sys/devices/cpu/events/cache-misses + /sys/devices/cpu/events/stalled-cycles-frontend + /sys/devices/cpu/events/branch-instructions + /sys/devices/cpu/events/stalled-cycles-backend + /sys/devices/cpu/events/instructions + /sys/devices/cpu/events/cpu-cycles + +Date: 2013/01/08 + +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> + +Description: Generic performance monitoring events + + A collection of performance monitoring events that may be + supported by many/most CPUs. These events can be monitored + using the 'perf(1)' tool. + + The contents of each file would look like: + + event=0xNNNN + + where 'N' is a hex digit and the number '0xNNNN' shows the + "raw code" for the perf event identified by the file's + "basename". + + +What: /sys/bus/event_source/devices/<pmu>/events/<event> +Date: 2014/02/24 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Per-pmu performance monitoring events specific to the running system + + Each file (except for some of those with a '.' in them, '.unit' + and '.scale') in the 'events' directory describes a single + performance monitoring event supported by the <pmu>. The name + of the file is the name of the event. + + File contents: + + <term>[=<value>][,<term>[=<value>]]... + + Where <term> is one of the terms listed under + /sys/bus/event_source/devices/<pmu>/format/ and <value> is + a number is base-16 format with a '0x' prefix (lowercase only). + If a <term> is specified alone (without an assigned value), it + is implied that 0x1 is assigned to that <term>. + + Examples (each of these lines would be in a seperate file): + + event=0x2abc + event=0x423,inv,cmask=0x3 + domain=0x1,offset=0x8,starting_index=0xffff + domain=0x1,offset=0x8,core=? + + Each of the assignments indicates a value to be assigned to a + particular set of bits (as defined by the format file + corresponding to the <term>) in the perf_event structure passed + to the perf_open syscall. + + In the case of the last example, a value replacing "?" would + need to be provided by the user selecting the particular event. + This is referred to as "event parameterization". Event + parameters have the format 'param=?'. + +What: /sys/bus/event_source/devices/<pmu>/events/<event>.unit +Date: 2014/02/24 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Perf event units + + A string specifying the English plural numerical unit that <event> + (once multiplied by <event>.scale) represents. + + Example: + + Joules + +What: /sys/bus/event_source/devices/<pmu>/events/<event>.scale +Date: 2014/02/24 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Perf event scaling factors + + A string representing a floating point value expressed in + scientific notation to be multiplied by the event count + recieved from the kernel to match the unit specified in the + <event>.unit file. + + Example: + + 2.3283064365386962890625e-10 + + This is provided to avoid performing floating point arithmetic + in the kernel.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format new file mode 100644 index 0000000..77f47ff --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -0,0 +1,20 @@ +Where: /sys/bus/event_source/devices/<dev>/format +Date: January 2012 +Kernel Version: 3.3 +Contact: Jiri Olsa <jolsa@redhat.com> +Description: + Attribute group to describe the magic bits that go into + perf_event_attr::config[012] for a particular pmu. + Each attribute of this group defines the 'hardware' bitmask + we want to export, so that userspace can deal with sane + name/value pairs. + + Userspace must be prepared for the possibility that attributes + define overlapping bit ranges. For example: + attr1 = 'config:0-23' + attr2 = 'config:0-7' + attr3 = 'config:12-35' + + Example: 'config1:1,6-10,44' + Defines contents of attribute that occupies bits 1,6-10,44 of + perf_event_attr::config1.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 new file mode 100644 index 0000000..ec27c6c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
@@ -0,0 +1,45 @@ +What: /sys/bus/event_source/devices/hv_24x7/interface/catalog +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Provides access to the binary "24x7 catalog" provided by the + hypervisor on POWER7 and 8 systems. This catalog lists events + available from the powerpc "hv_24x7" pmu. Its format is + documented here: + https://raw.githubusercontent.com/jmesmon/catalog-24x7/master/hv-24x7-catalog.h + +What: /sys/bus/event_source/devices/hv_24x7/interface/catalog_length +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + A number equal to the length in bytes of the catalog. This is + also extractable from the provided binary "catalog" sysfs entry. + +What: /sys/bus/event_source/devices/hv_24x7/interface/catalog_version +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Exposes the "version" field of the 24x7 catalog. This is also + extractable from the provided binary "catalog" sysfs entry. + +What: /sys/bus/event_source/devices/hv_24x7/event_descs/<event-name> +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Provides the description of a particular event as provided by + the firmware. If firmware does not provide a description, no + file will be created. + + Note that the event-name lacks the domain suffix appended for + events in the events/ dir. + +What: /sys/bus/event_source/devices/hv_24x7/event_long_descs/<event-name> +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + Provides the "long" description of a particular event as + provided by the firmware. If firmware does not provide a + description, no file will be created. + + Note that the event-name lacks the domain suffix appended for + events in the events/ dir.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci new file mode 100644 index 0000000..3ca4e55 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
@@ -0,0 +1,43 @@ +What: /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + '0' if the hypervisor is configured to forbid access to event + counters being accumulated by other guests and to physical + domain event counters. + '1' if that access is allowed. + +What: /sys/bus/event_source/devices/hv_gpci/interface/ga +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + 0 or 1. Indicates whether we have access to "GA" events (listed + in arch/powerpc/perf/hv-gpci.h). + +What: /sys/bus/event_source/devices/hv_gpci/interface/expanded +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + 0 or 1. Indicates whether we have access to "EXPANDED" events (listed + in arch/powerpc/perf/hv-gpci.h). + +What: /sys/bus/event_source/devices/hv_gpci/interface/lab +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + 0 or 1. Indicates whether we have access to "LAB" events (listed + in arch/powerpc/perf/hv-gpci.h). + +What: /sys/bus/event_source/devices/hv_gpci/interface/version +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + A number indicating the version of the gpci interface that the + hypervisor reports supporting. + +What: /sys/bus/event_source/devices/hv_gpci/interface/kernel_version +Date: February 2014 +Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> +Description: + A number indicating the latest version of the gpci interface + that the kernel is aware of.
diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe new file mode 100644 index 0000000..657df13 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-fcoe
@@ -0,0 +1,116 @@ +What: /sys/bus/fcoe/ +Date: August 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: The FCoE bus. Attributes in this directory are control interfaces. +Attributes: + + ctlr_create: 'FCoE Controller' instance creation interface. Writing an + <ifname> to this file will allocate and populate sysfs with a + fcoe_ctlr_device (ctlr_X). The user can then configure any + per-port settings and finally write to the fcoe_ctlr_device's + 'start' attribute to begin the kernel's discovery and login + process. + + ctlr_destroy: 'FCoE Controller' instance removal interface. Writing a + fcoe_ctlr_device's sysfs name to this file will log the + fcoe_ctlr_device out of the fabric or otherwise connected + FCoE devices. It will also free all kernel memory allocated + for this fcoe_ctlr_device and any structures associated + with it, this includes the scsi_host. + +What: /sys/bus/fcoe/devices/ctlr_X +Date: March 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: 'FCoE Controller' instances on the fcoe bus. + The FCoE Controller now has a three stage creation process. + 1) Write interface name to ctlr_create 2) Configure the FCoE + Controller (ctlr_X) 3) Enable the FCoE Controller to begin + discovery and login. The FCoE Controller is destroyed by + writing it's name, i.e. ctlr_X to the ctlr_delete file. + +Attributes: + + fcf_dev_loss_tmo: Device loss timeout period (see below). Changing + this value will change the dev_loss_tmo for all + FCFs discovered by this controller. + + mode: Display or change the FCoE Controller's mode. Possible + modes are 'Fabric' and 'VN2VN'. If a FCoE Controller + is started in 'Fabric' mode then FIP FCF discovery is + initiated and ultimately a fabric login is attempted. + If a FCoE Controller is started in 'VN2VN' mode then + FIP VN2VN discovery and login is performed. A FCoE + Controller only supports one mode at a time. + + enabled: Whether an FCoE controller is enabled or disabled. + 0 if disabled, 1 if enabled. Writing either 0 or 1 + to this file will enable or disable the FCoE controller. + + lesb/link_fail: Link Error Status Block (LESB) link failure count. + + lesb/vlink_fail: Link Error Status Block (LESB) virtual link + failure count. + + lesb/miss_fka: Link Error Status Block (LESB) missed FCoE + Initialization Protocol (FIP) Keep-Alives (FKA). + + lesb/symb_err: Link Error Status Block (LESB) symbolic error count. + + lesb/err_block: Link Error Status Block (LESB) block error count. + + lesb/fcs_error: Link Error Status Block (LESB) Fibre Channel + Services error count. + +Notes: ctlr_X (global increment starting at 0) + +What: /sys/bus/fcoe/devices/fcf_X +Date: March 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: 'FCoE FCF' instances on the fcoe bus. A FCF is a Fibre Channel + Forwarder, which is a FCoE switch that can accept FCoE + (Ethernet) packets, unpack them, and forward the embedded + Fibre Channel frames into a FC fabric. It can also take + outbound FC frames and pack them in Ethernet packets to + be sent to their destination on the Ethernet segment. +Attributes: + + fabric_name: Identifies the fabric that the FCF services. + + switch_name: Identifies the FCF. + + priority: The switch's priority amongst other FCFs on the same + fabric. + + selected: 1 indicates that the switch has been selected for use; + 0 indicates that the switch will not be used. + + fc_map: The Fibre Channel MAP + + vfid: The Virtual Fabric ID + + mac: The FCF's MAC address + + fka_period: The FIP Keep-Alive period + + fabric_state: The internal kernel state + "Unknown" - Initialization value + "Disconnected" - No link to the FCF/fabric + "Connected" - Host is connected to the FCF + "Deleted" - FCF is being removed from the system + + dev_loss_tmo: The device loss timeout period for this FCF. + +Notes: A device loss infrastructure similar to the FC Transport's + is present in fcoe_sysfs. It is nice to have so that a + link flapping adapter doesn't continually advance the count + used to identify the discovered FCF. FCFs will exist in a + "Disconnected" state until either the timer expires and the + FCF becomes "Deleted" or the FCF is rediscovered and becomes + "Connected." + + +Users: The first user of this interface will be the fcoeadm application, + which is commonly packaged in the fcoe-utils package.
diff --git a/Documentation/ABI/testing/sysfs-bus-hsi b/Documentation/ABI/testing/sysfs-bus-hsi new file mode 100644 index 0000000..1b1b282 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-hsi
@@ -0,0 +1,19 @@ +What: /sys/bus/hsi +Date: April 2012 +KernelVersion: 3.4 +Contact: Carlos Chinea <carlos.chinea@nokia.com> +Description: + High Speed Synchronous Serial Interface (HSI) is a + serial interface mainly used for connecting application + engines (APE) with cellular modem engines (CMT) in cellular + handsets. + The bus will be populated with devices (hsi_clients) representing + the protocols available in the system. Bus drivers implement + those protocols. + +What: /sys/bus/hsi/devices/.../modalias +Date: April 2012 +KernelVersion: 3.4 +Contact: Carlos Chinea <carlos.chinea@nokia.com> +Description: Stores the same MODALIAS value emitted by uevent + Format: hsi:<hsi_client device name>
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 new file mode 100644 index 0000000..9de269b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
@@ -0,0 +1,21 @@ +What: /sys/bus/i2c/devices/.../device +Date: February 2011 +Contact: Minkyu Kang <mk7.kang@samsung.com> +Description: + show what device is attached + NONE - no device + USB - USB device is attached + UART - UART is attached + CHARGER - Charger is attaced + JIG - JIG is attached + +What: /sys/bus/i2c/devices/.../switch +Date: February 2011 +Contact: Minkyu Kang <mk7.kang@samsung.com> +Description: + show or set the state of manual switch + VAUDIO - switch to VAUDIO path + UART - switch to UART path + AUDIO - switch to AUDIO path + DHOST - switch to DHOST path + AUTO - switch automatically by device
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 new file mode 100644 index 0000000..feb2e4a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
@@ -0,0 +1,21 @@ +Where: /sys/bus/i2c/devices/.../heading0_input +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Reports the current heading from the compass as a floating + point value in degrees. + +Where: /sys/bus/i2c/devices/.../power_state +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Sets the power state of the device. 0 sets the device into + sleep mode, 1 wakes it up. + +Where: /sys/bus/i2c/devices/.../calibration +Date: April 2010 +Kernel Version: 2.6.36? +Contact: alan.cox@intel.com +Description: Sets the calibration on or off (1 = on, 0 = off). See the + chip data sheet. +
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533 new file mode 100644 index 0000000..1b62230 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533
@@ -0,0 +1,15 @@ +What: /sys/bus/i2c/devices/.../output_hvled[n] +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the controlling backlight device for high-voltage current + sink HVLED[n] (n = 1, 2) (0, 1). + +What: /sys/bus/i2c/devices/.../output_lvled[n] +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the controlling led device for low-voltage current sink + LVLED[n] (n = 1..5) (0..3).
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio new file mode 100644 index 0000000..fee35c0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -0,0 +1,1581 @@ +What: /sys/bus/iio/devices/iio:deviceX +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware chip or device accessed by one communication port. + Corresponds to a grouping of sensor channels. X is the IIO + index of the device. + +What: /sys/bus/iio/devices/triggerX +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + An event driven driver of data capture to an in kernel buffer. + May be provided by a device driver that also has an IIO device + based on hardware generated events (e.g. data ready) or + provided by a separate driver for other hardware (e.g. + periodic timer, GPIO or high resolution timer). + Contains trigger type specific elements. These do not + generalize well and hence are not documented in this file. + X is the IIO index of the trigger. + +What: /sys/bus/iio/devices/iio:deviceX/buffer +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Directory of attributes relating to the buffer for the device. + +What: /sys/bus/iio/devices/iio:deviceX/name +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Description of the physical chip / device for device X. + Typically a part number. + +What: /sys/bus/iio/devices/iio:deviceX/timestamp_clock +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + String identifying current posix clock used to timestamp + buffered samples and events for device X. + +What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency +What: /sys/bus/iio/devices/iio:deviceX/buffer/sampling_frequency +What: /sys/bus/iio/devices/triggerX/sampling_frequency +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Some devices have internal clocks. This parameter sets the + resulting sampling frequency. In many devices this + parameter has an effect on input filters etc. rather than + simply controlling when the input is sampled. As this + effects data ready triggers, hardware buffers and the sysfs + direct access interfaces, it may be found in any of the + relevant directories. If it effects all of the above + then it is to be found in the base device directory. + +What: /sys/bus/iio/devices/iio:deviceX/sampling_frequency_available +What: /sys/.../iio:deviceX/buffer/sampling_frequency_available +What: /sys/bus/iio/devices/triggerX/sampling_frequency_available +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + When the internal sampling clock can only take a small + discrete set of values, this file lists those available. + +What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Hardware dependent ADC oversampling. Controls the sampling ratio + of the digital filter if available. + +What: /sys/bus/iio/devices/iio:deviceX/oversampling_ratio_available +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Hardware dependent values supported by the oversampling filter. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_i_raw +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc.) voltage measurement from + channel Y. In special cases where the channel does not + correspond to externally available input one of the named + versions may be used. The number must always be specified and + unique to allow association with event codes. Units after + application of scale and offset are millivolts. + + Channels with 'i' and 'q' modifiers always exist in pairs and both + channels refer to the same signal. The 'i' channel contains the in-phase + component of the signal while the 'q' channel contains the quadrature + component. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY-voltageZ_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled) differential voltage measurement equivalent to + channel Y - channel Z where these channel numbers apply to the + physically equivalent inputs when non differential readings are + separately available. In differential only parts, then all that + is required is a consistent labeling. Units after application + of scale and offset are millivolts. + +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_raw +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc.) current measurement from + channel Y. In special cases where the channel does not + correspond to externally available input one of the named + versions may be used. The number must always be specified and + unique to allow association with event codes. Units after + application of scale and offset are milliamps. + +What: /sys/bus/iio/devices/iio:deviceX/in_capacitanceY_raw +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + Raw capacitance measurement from channel Y. Units after + application of scale and offset are nanofarads. + +What: /sys/.../iio:deviceX/in_capacitanceY-in_capacitanceZ_raw +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + Raw differential capacitance measurement equivalent to + channel Y - channel Z where these channel numbers apply to the + physically equivalent inputs when non differential readings are + separately available. In differential only parts, then all that + is required is a consistent labeling. Units after application + of scale and offset are nanofarads. + +What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_ambient_raw +What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no bias removal etc.) temperature measurement. + If an axis is specified it generally means that the temperature + sensor is associated with one part of a compound device (e.g. + a gyroscope axis). The ambient and object modifiers distinguish + between ambient (reference) and distant temperature for contact- + less measurements. Units after application of scale and offset + are milli degrees Celsius. + +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_input +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Scaled temperature measurement in milli degrees Celsius. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Acceleration in direction x, y or z (may be arbitrarily assigned + but should match other such assignments on device). + Has all of the equivalent parameters as per voltageY. Units + after application of scale and offset are m/s^2. + +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Angular velocity about axis x, y or z (may be arbitrarily + assigned). Has all the equivalent parameters as per voltageY. + Units after application of scale and offset are radians per + second. + +What: /sys/bus/iio/devices/iio:deviceX/in_incli_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_incli_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_incli_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Inclination raw reading about axis x, y or z (may be + arbitrarily assigned). Data converted by application of offset + and scale to degrees. + +What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_raw +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Magnetic field along axis x, y or z (may be arbitrarily + assigned). Data converted by application of offset + then scale to Gauss. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_peak_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_peak_raw +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_peak_raw +KernelVersion: 2.6.36 +Contact: linux-iio@vger.kernel.org +Description: + Highest value since some reset condition. These + attributes allow access to this and are otherwise + the direct equivalent of the <type>Y[_name]_raw attributes. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_xyz_squared_peak_raw +KernelVersion: 2.6.36 +Contact: linux-iio@vger.kernel.org +Description: + A computed peak value based on the sum squared magnitude of + the underlying value in the specified directions. + +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_raw +KernelVersion: 3.8 +Contact: linux-iio@vger.kernel.org +Description: + Raw pressure measurement from channel Y. Units after + application of scale and offset are kilopascal. + +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_input +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_input +KernelVersion: 3.8 +Contact: linux-iio@vger.kernel.org +Description: + Scaled pressure measurement from channel Y, in kilopascal. + +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_raw +KernelVersion: 3.14 +Contact: linux-iio@vger.kernel.org +Description: + Raw humidity measurement of air. Units after application of + scale and offset are milli percent. + +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_input +KernelVersion: 3.14 +Contact: linux-iio@vger.kernel.org +Description: + Scaled humidity measurement in milli percent. + +What: /sys/bus/iio/devices/iio:deviceX/in_X_mean_raw +KernelVersion: 3.5 +Contact: linux-iio@vger.kernel.org +Description: + Averaged raw measurement from channel X. The number of values + used for averaging is device specific. The converting rules for + normal raw values also applies to the averaged raw values. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_i_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_q_offset +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_i_offset +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_current_offset +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_i_offset +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_q_offset +What: /sys/bus/iio/devices/iio:deviceX/in_current_q_offset +What: /sys/bus/iio/devices/iio:deviceX/in_current_i_offset +What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_temp_offset +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_offset +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_offset +What: /sys/bus/iio/devices/iio:deviceX/in_magn_offset +What: /sys/bus/iio/devices/iio:deviceX/in_rot_offset +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + If known for a device, offset to be added to <type>[Y]_raw prior + to scaling by <type>[Y]_scale in order to obtain value in the + <type> units as specified in <type>[Y]_raw documentation. + Not present if the offset is always 0 or unknown. If Y or + axis <x|y|z> is not present, then the offset applies to all + in channels of <type>. + May be writable if a variable offset can be applied on the + device. Note that this is different to calibbias which + is for devices (or drivers) that apply offsets to compensate + for variation between different instances of the part, typically + adjusted by using some hardware supported calibration procedure. + Calibbias is applied internally, offset is applied in userspace + to the _raw output. + +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_i_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_i_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage_q_scale +What: /sys/bus/iio/devices/iio:deviceX/in_voltage-voltage_scale +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_supply_scale +What: /sys/bus/iio/devices/iio:deviceX/in_current_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_i_scale +What: /sys/bus/iio/devices/iio:deviceX/in_currentY_q_scale +What: /sys/bus/iio/devices/iio:deviceX/in_current_i_scale +What: /sys/bus/iio/devices/iio:deviceX/in_current_q_scale +What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale +What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale +What: /sys/bus/iio/devices/iio:deviceX/in_energy_scale +What: /sys/bus/iio/devices/iio:deviceX/in_distance_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_scale +What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_scale +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_scale +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_scale +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_tilt_comp_scale +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_tilt_comp_scale +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_scale +What: /sys/bus/iio/devices/iio:deviceX/in_humidityrelative_scale +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_scale +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_scale +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + If known for a device, scale to be applied to <type>Y[_name]_raw + post addition of <type>[Y][_name]_offset in order to obtain the + measured value in <type> units as specified in + <type>[Y][_name]_raw documentation. If shared across all in + channels then Y and <x|y|z> are not present and the value is + called <type>[Y][_name]_scale. The peak modifier means this + value is applied to <type>Y[_name]_peak_raw values. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibbias +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration offset (assumed to fix production + inaccuracies). + +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_i_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltageY_q_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltage_i_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltage_q_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_voltage_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale +What /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance_calibscale +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied calibration scale factor (assumed to fix + production inaccuracies). If shared across all channels, + <type>_calibscale is used. + +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibgender +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibgender +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Gender of the user (e.g.: male, female) used by some pedometers + to compute the stride length, distance, speed and activity + type. + +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibgender_available +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibgender_available +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Lists all available gender values (e.g.: male, female). + +What: /sys/bus/iio/devices/iio:deviceX/in_activity_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_distance_calibheight +What: /sys/bus/iio/devices/iio:deviceX/in_velocity_calibheight +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Height of the user (in meters) used by some pedometers + to compute the stride length, distance, speed and activity + type. + +What: /sys/bus/iio/devices/iio:deviceX/in_energy_calibweight +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Weight of the user (in kg). It is needed by some pedometers + to compute the calories burnt by the user. + +What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available +What: /sys/.../iio:deviceX/in_anglvel_scale_available +What: /sys/.../iio:deviceX/in_magn_scale_available +What: /sys/.../iio:deviceX/in_illuminance_scale_available +What: /sys/.../iio:deviceX/in_intensity_scale_available +What: /sys/.../iio:deviceX/in_proximity_scale_available +What: /sys/.../iio:deviceX/in_voltageX_scale_available +What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available +What: /sys/.../iio:deviceX/out_voltageX_scale_available +What: /sys/.../iio:deviceX/out_altvoltageX_scale_available +What: /sys/.../iio:deviceX/in_capacitance_scale_available +What: /sys/.../iio:deviceX/in_pressure_scale_available +What: /sys/.../iio:deviceX/in_pressureY_scale_available +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + If a discrete set of scale values is available, they + are listed in this attribute. + +What /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_red_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_green_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_blue_hardwaregain +What: /sys/bus/iio/devices/iio:deviceX/in_intensity_clear_hardwaregain +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied gain factor. If shared across all channels, + <type>_hardwaregain is used. + +What: /sys/.../in_accel_filter_low_pass_3db_frequency +What: /sys/.../in_magn_filter_low_pass_3db_frequency +What: /sys/.../in_anglvel_filter_low_pass_3db_frequency +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + If a known or controllable low pass filter is applied + to the underlying data channel, then this parameter + gives the 3dB frequency of the filter in Hz. + +What: /sys/.../in_accel_filter_high_pass_3db_frequency +What: /sys/.../in_anglvel_filter_high_pass_3db_frequency +What: /sys/.../in_magn_filter_high_pass_3db_frequency +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + If a known or controllable high pass filter is applied + to the underlying data channel, then this parameter + gives the 3dB frequency of the filter in Hz. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_raw +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled, no bias etc.) output voltage for + channel Y. The number must always be specified and + unique if the output corresponds to a single channel. + While DAC like devices typically use out_voltage, + a continuous frequency generating device, such as + a DDS or PLL should use out_altvoltage. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY&Z_raw +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY&Z_raw +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled, no bias etc.) output voltage for an aggregate of + channel Y, channel Z, etc. This interface is available in cases + where a single output sets the value for multiple channels + simultaneously. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown_mode +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the output powerdown mode. + DAC output stage is disconnected from the amplifier and + 1kohm_to_gnd: connected to ground via an 1kOhm resistor, + 6kohm_to_gnd: connected to ground via a 6kOhm resistor, + 20kohm_to_gnd: connected to ground via a 20kOhm resistor, + 90kohm_to_gnd: connected to ground via a 90kOhm resistor, + 100kohm_to_gnd: connected to ground via an 100kOhm resistor, + 125kohm_to_gnd: connected to ground via an 125kOhm resistor, + 500kohm_to_gnd: connected to ground via a 500kOhm resistor, + 640kohm_to_gnd: connected to ground via a 640kOhm resistor, + three_state: left floating. + For a list of available output power down options read + outX_powerdown_mode_available. If Y is not present the + mode is shared across all outputs. + +What: /sys/.../iio:deviceX/out_voltageY_powerdown_mode_available +What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available +What: /sys/.../iio:deviceX/out_altvoltageY_powerdown_mode_available +What: /sys/.../iio:deviceX/out_altvoltage_powerdown_mode_available +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Lists all available output power down modes. + If Y is not present the mode is shared across all outputs. + +What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + Writing 1 causes output Y to enter the power down mode specified + by the corresponding outY_powerdown_mode. DAC output stage is + disconnected from the amplifier. Clearing returns to normal + operation. Y may be suppressed if all outputs are controlled + together. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Output frequency for channel Y in Hz. The number must always be + specified and unique if the output corresponds to a single + channel. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Phase in radians of one frequency/clock output Y + (out_altvoltageY) relative to another frequency/clock output + (out_altvoltageZ) of the device X. The number must always be + specified and unique if the output corresponds to a single + channel. + +What: /sys/bus/iio/devices/iio:deviceX/events +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Configuration of which hardware generated events are passed up + to user-space. + +What: /sys/.../iio:deviceX/events/in_accel_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_x_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_x_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_y_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_y_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_magn_z_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_magn_z_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_tilt_comp_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_tilt_comp_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_tilt_comp_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_tilt_comp_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_thresh_either_en +What: /sys/.../iio:deviceX/events/in_tempY_thresh_rising_en +What: /sys/.../iio:deviceX/events/in_tempY_thresh_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold in the specified + (_rising|_falling) direction. If the direction is not specified, + then either the device will report an event which ever direction + a single threshold value is passed in (e.g. + <type>[Y][_name]_<raw|input>_thresh_value) or + <type>[Y][_name]_<raw|input>_thresh_rising_value and + <type>[Y][_name]_<raw|input>_thresh_falling_value may take + different values, but the device can only enable both thresholds + or neither. + Note the driver will assume the last p events requested are + to be enabled where p is how many it supports (which may vary + depending on the exact set requested. So if you want to be + sure you have set what you think you have, check the contents of + these attributes after everything is configured. Drivers may + have to buffer any parameters so that they are consistent when + a given event type is enabled at a future point (and not those for + whatever event was previously enabled). + +What: /sys/.../iio:deviceX/events/in_accel_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_anglvel_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_x_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_x_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_y_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_y_roc_falling_en +What: /sys/.../iio:deviceX/events/in_magn_z_roc_rising_en +What: /sys/.../iio:deviceX/events/in_magn_z_roc_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_roc_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_roc_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_roc_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_roc_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_tilt_comp_roc_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_magnetic_tilt_comp_roc_falling_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_tilt_comp_roc_rising_en +What: /sys/.../iio:deviceX/events/in_rot_from_north_true_tilt_comp_roc_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_roc_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_supply_roc_falling_en +What: /sys/.../iio:deviceX/events/in_voltageY_roc_rising_en +What: /sys/.../iio:deviceX/events/in_voltageY_roc_falling_en +What: /sys/.../iio:deviceX/events/in_tempY_roc_rising_en +What: /sys/.../iio:deviceX/events/in_tempY_roc_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold on the rate of + change (1st differential) in the specified (_rising|_falling) + direction. If the direction is not specified, then either the + device will report an event which ever direction a single + threshold value is passed in (e.g. + <type>[Y][_name]_<raw|input>_roc_value) or + <type>[Y][_name]_<raw|input>_roc_rising_value and + <type>[Y][_name]_<raw|input>_roc_falling_value may take + different values, but the device can only enable both rate of + change thresholds or neither. + Note the driver will assume the last p events requested are + to be enabled where p is however many it supports (which may + vary depending on the exact set requested. So if you want to be + sure you have set what you think you have, check the contents of + these attributes after everything is configured. Drivers may + have to buffer any parameters so that they are consistent when + a given event type is enabled a future point (and not those for + whatever event was previously enabled). + +What: /sys/.../events/in_accel_thresh_rising_value +What: /sys/.../events/in_accel_thresh_falling_value +What: /sys/.../events/in_accel_x_raw_thresh_rising_value +What: /sys/.../events/in_accel_x_raw_thresh_falling_value +What: /sys/.../events/in_accel_y_raw_thresh_rising_value +What: /sys/.../events/in_accel_y_raw_thresh_falling_value +What: /sys/.../events/in_accel_z_raw_thresh_rising_value +What: /sys/.../events/in_accel_z_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_x_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_x_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_y_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_y_raw_thresh_falling_value +What: /sys/.../events/in_anglvel_z_raw_thresh_rising_value +What: /sys/.../events/in_anglvel_z_raw_thresh_falling_value +What: /sys/.../events/in_magn_x_raw_thresh_rising_value +What: /sys/.../events/in_magn_x_raw_thresh_falling_value +What: /sys/.../events/in_magn_y_raw_thresh_rising_value +What: /sys/.../events/in_magn_y_raw_thresh_falling_value +What: /sys/.../events/in_magn_z_raw_thresh_rising_value +What: /sys/.../events/in_magn_z_raw_thresh_falling_value +What: /sys/.../events/in_rot_from_north_magnetic_raw_thresh_rising_value +What: /sys/.../events/in_rot_from_north_magnetic_raw_thresh_falling_value +What: /sys/.../events/in_rot_from_north_true_raw_thresh_rising_value +What: /sys/.../events/in_rot_from_north_true_raw_thresh_falling_value +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_raw_thresh_rising_value +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_raw_thresh_falling_value +What: /sys/.../events/in_rot_from_north_true_tilt_comp_raw_thresh_rising_value +What: /sys/.../events/in_rot_from_north_true_tilt_comp_raw_thresh_falling_value +What: /sys/.../events/in_voltageY_supply_raw_thresh_rising_value +What: /sys/.../events/in_voltageY_supply_raw_thresh_falling_value +What: /sys/.../events/in_voltageY_raw_thresh_rising_value +What: /sys/.../events/in_voltageY_raw_thresh_falling_value +What: /sys/.../events/in_tempY_raw_thresh_rising_value +What: /sys/.../events/in_tempY_raw_thresh_falling_value +What: /sys/.../events/in_illuminance0_thresh_falling_value +what: /sys/.../events/in_illuminance0_thresh_rising_value +what: /sys/.../events/in_proximity0_thresh_falling_value +what: /sys/.../events/in_proximity0_thresh_rising_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of threshold that the device is comparing + against for the events enabled by + <type>Y[_name]_thresh[_rising|falling]_en. + If separate attributes exist for the two directions, but + direction is not specified for this attribute, then a single + threshold value applies to both directions. + The raw or input element of the name indicates whether the + value is in raw device units or in processed units (as _raw + and _input do on sysfs direct channel read attributes). + +What: /sys/.../events/in_accel_scale +What: /sys/.../events/in_accel_peak_scale +What: /sys/.../events/in_anglvel_scale +What: /sys/.../events/in_magn_scale +What: /sys/.../events/in_rot_from_north_magnetic_scale +What: /sys/.../events/in_rot_from_north_true_scale +What: /sys/.../events/in_voltage_scale +What: /sys/.../events/in_voltage_supply_scale +What: /sys/.../events/in_temp_scale +What: /sys/.../events/in_illuminance_scale +What: /sys/.../events/in_proximity_scale +KernelVersion: 3.21 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the conversion factor from the standard units + to device specific units used to set the event trigger + threshold. + +What: /sys/.../events/in_accel_x_thresh_rising_hysteresis +What: /sys/.../events/in_accel_x_thresh_falling_hysteresis +What: /sys/.../events/in_accel_x_thresh_either_hysteresis +What: /sys/.../events/in_accel_y_thresh_rising_hysteresis +What: /sys/.../events/in_accel_y_thresh_falling_hysteresis +What: /sys/.../events/in_accel_y_thresh_either_hysteresis +What: /sys/.../events/in_accel_z_thresh_rising_hysteresis +What: /sys/.../events/in_accel_z_thresh_falling_hysteresis +What: /sys/.../events/in_accel_z_thresh_either_hysteresis +What: /sys/.../events/in_anglvel_x_thresh_rising_hysteresis +What: /sys/.../events/in_anglvel_x_thresh_falling_hysteresis +What: /sys/.../events/in_anglvel_x_thresh_either_hysteresis +What: /sys/.../events/in_anglvel_y_thresh_rising_hysteresis +What: /sys/.../events/in_anglvel_y_thresh_falling_hysteresis +What: /sys/.../events/in_anglvel_y_thresh_either_hysteresis +What: /sys/.../events/in_anglvel_z_thresh_rising_hysteresis +What: /sys/.../events/in_anglvel_z_thresh_falling_hysteresis +What: /sys/.../events/in_anglvel_z_thresh_either_hysteresis +What: /sys/.../events/in_magn_x_thresh_rising_hysteresis +What: /sys/.../events/in_magn_x_thresh_falling_hysteresis +What: /sys/.../events/in_magn_x_thresh_either_hysteresis +What: /sys/.../events/in_magn_y_thresh_rising_hysteresis +What: /sys/.../events/in_magn_y_thresh_falling_hysteresis +What: /sys/.../events/in_magn_y_thresh_either_hysteresis +What: /sys/.../events/in_magn_z_thresh_rising_hysteresis +What: /sys/.../events/in_magn_z_thresh_falling_hysteresis +What: /sys/.../events/in_magn_z_thresh_either_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_thresh_rising_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_thresh_falling_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_thresh_either_hysteresis +What: /sys/.../events/in_rot_from_north_true_thresh_rising_hysteresis +What: /sys/.../events/in_rot_from_north_true_thresh_falling_hysteresis +What: /sys/.../events/in_rot_from_north_true_thresh_either_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_thresh_rising_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_thresh_falling_hysteresis +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_thresh_either_hysteresis +What: /sys/.../events/in_rot_from_north_true_tilt_comp_thresh_rising_hysteresis +What: /sys/.../events/in_rot_from_north_true_tilt_comp_thresh_falling_hysteresis +What: /sys/.../events/in_rot_from_north_true_tilt_comp_thresh_either_hysteresis +What: /sys/.../events/in_voltageY_thresh_rising_hysteresis +What: /sys/.../events/in_voltageY_thresh_falling_hysteresis +What: /sys/.../events/in_voltageY_thresh_either_hysteresis +What: /sys/.../events/in_tempY_thresh_rising_hysteresis +What: /sys/.../events/in_tempY_thresh_falling_hysteresis +What: /sys/.../events/in_tempY_thresh_either_hysteresis +What: /sys/.../events/in_illuminance0_thresh_falling_hysteresis +what: /sys/.../events/in_illuminance0_thresh_rising_hysteresis +what: /sys/.../events/in_illuminance0_thresh_either_hysteresis +what: /sys/.../events/in_proximity0_thresh_falling_hysteresis +what: /sys/.../events/in_proximity0_thresh_rising_hysteresis +what: /sys/.../events/in_proximity0_thresh_either_hysteresis +KernelVersion: 3.13 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the hysteresis of threshold that the device is comparing + against for the events enabled by + <type>Y[_name]_thresh[_(rising|falling)]_hysteresis. + If separate attributes exist for the two directions, but + direction is not specified for this attribute, then a single + hysteresis value applies to both directions. + For falling events the hysteresis is added to the _value attribute for + this event to get the upper threshold for when the event goes back to + normal, for rising events the hysteresis is subtracted from the _value + attribute. E.g. if in_voltage0_raw_thresh_rising_value is set to 1200 + and in_voltage0_raw_thresh_rising_hysteresis is set to 50. The event + will get activated once in_voltage0_raw goes above 1200 and will become + deactived again once the value falls below 1150. + +What: /sys/.../events/in_accel_x_raw_roc_rising_value +What: /sys/.../events/in_accel_x_raw_roc_falling_value +What: /sys/.../events/in_accel_y_raw_roc_rising_value +What: /sys/.../events/in_accel_y_raw_roc_falling_value +What: /sys/.../events/in_accel_z_raw_roc_rising_value +What: /sys/.../events/in_accel_z_raw_roc_falling_value +What: /sys/.../events/in_anglvel_x_raw_roc_rising_value +What: /sys/.../events/in_anglvel_x_raw_roc_falling_value +What: /sys/.../events/in_anglvel_y_raw_roc_rising_value +What: /sys/.../events/in_anglvel_y_raw_roc_falling_value +What: /sys/.../events/in_anglvel_z_raw_roc_rising_value +What: /sys/.../events/in_anglvel_z_raw_roc_falling_value +What: /sys/.../events/in_magn_x_raw_roc_rising_value +What: /sys/.../events/in_magn_x_raw_roc_falling_value +What: /sys/.../events/in_magn_y_raw_roc_rising_value +What: /sys/.../events/in_magn_y_raw_roc_falling_value +What: /sys/.../events/in_magn_z_raw_roc_rising_value +What: /sys/.../events/in_magn_z_raw_roc_falling_value +What: /sys/.../events/in_rot_from_north_magnetic_raw_roc_rising_value +What: /sys/.../events/in_rot_from_north_magnetic_raw_roc_falling_value +What: /sys/.../events/in_rot_from_north_true_raw_roc_rising_value +What: /sys/.../events/in_rot_from_north_true_raw_roc_falling_value +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_raw_roc_rising_value +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_raw_roc_falling_value +What: /sys/.../events/in_rot_from_north_true_tilt_comp_raw_roc_rising_value +What: /sys/.../events/in_rot_from_north_true_tilt_comp_raw_roc_falling_value +What: /sys/.../events/in_voltageY_supply_raw_roc_rising_value +What: /sys/.../events/in_voltageY_supply_raw_roc_falling_value +What: /sys/.../events/in_voltageY_raw_roc_rising_value +What: /sys/.../events/in_voltageY_raw_roc_falling_value +What: /sys/.../events/in_tempY_raw_roc_rising_value +What: /sys/.../events/in_tempY_raw_roc_falling_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of rate of change threshold that the + device is comparing against for the events enabled by + <type>[Y][_name]_roc[_rising|falling]_en. + If separate attributes exist for the two directions, + but direction is not specified for this attribute, + then a single threshold value applies to both directions. + The raw or input element of the name indicates whether the + value is in raw device units or in processed units (as _raw + and _input do on sysfs direct channel read attributes). + +What: /sys/.../events/in_accel_x_thresh_rising_period +What: /sys/.../events/in_accel_x_thresh_falling_period +What: /sys/.../events/in_accel_x_roc_rising_period +What: /sys/.../events/in_accel_x_roc_falling_period +What: /sys/.../events/in_accel_y_thresh_rising_period +What: /sys/.../events/in_accel_y_thresh_falling_period +What: /sys/.../events/in_accel_y_roc_rising_period +What: /sys/.../events/in_accel_y_roc_falling_period +What: /sys/.../events/in_accel_z_thresh_rising_period +What: /sys/.../events/in_accel_z_thresh_falling_period +What: /sys/.../events/in_accel_z_roc_rising_period +What: /sys/.../events/in_accel_z_roc_falling_period +What: /sys/.../events/in_anglvel_x_thresh_rising_period +What: /sys/.../events/in_anglvel_x_thresh_falling_period +What: /sys/.../events/in_anglvel_x_roc_rising_period +What: /sys/.../events/in_anglvel_x_roc_falling_period +What: /sys/.../events/in_anglvel_y_thresh_rising_period +What: /sys/.../events/in_anglvel_y_thresh_falling_period +What: /sys/.../events/in_anglvel_y_roc_rising_period +What: /sys/.../events/in_anglvel_y_roc_falling_period +What: /sys/.../events/in_anglvel_z_thresh_rising_period +What: /sys/.../events/in_anglvel_z_thresh_falling_period +What: /sys/.../events/in_anglvel_z_roc_rising_period +What: /sys/.../events/in_anglvel_z_roc_falling_period +What: /sys/.../events/in_magn_x_thresh_rising_period +What: /sys/.../events/in_magn_x_thresh_falling_period +What: /sys/.../events/in_magn_x_roc_rising_period +What: /sys/.../events/in_magn_x_roc_falling_period +What: /sys/.../events/in_magn_y_thresh_rising_period +What: /sys/.../events/in_magn_y_thresh_falling_period +What: /sys/.../events/in_magn_y_roc_rising_period +What: /sys/.../events/in_magn_y_roc_falling_period +What: /sys/.../events/in_magn_z_thresh_rising_period +What: /sys/.../events/in_magn_z_thresh_falling_period +What: /sys/.../events/in_magn_z_roc_rising_period +What: /sys/.../events/in_magn_z_roc_falling_period +What: /sys/.../events/in_rot_from_north_magnetic_thresh_rising_period +What: /sys/.../events/in_rot_from_north_magnetic_thresh_falling_period +What: /sys/.../events/in_rot_from_north_magnetic_roc_rising_period +What: /sys/.../events/in_rot_from_north_magnetic_roc_falling_period +What: /sys/.../events/in_rot_from_north_true_thresh_rising_period +What: /sys/.../events/in_rot_from_north_true_thresh_falling_period +What: /sys/.../events/in_rot_from_north_true_roc_rising_period +What: /sys/.../events/in_rot_from_north_true_roc_falling_period +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_thresh_rising_period +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_thresh_falling_period +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_roc_rising_period +What: /sys/.../events/in_rot_from_north_magnetic_tilt_comp_roc_falling_period +What: /sys/.../events/in_rot_from_north_true_tilt_comp_thresh_rising_period +What: /sys/.../events/in_rot_from_north_true_tilt_comp_thresh_falling_period +What: /sys/.../events/in_rot_from_north_true_tilt_comp_roc_rising_period +What: /sys/.../events/in_rot_from_north_true_tilt_comp_roc_falling_period +What: /sys/.../events/in_voltageY_supply_thresh_rising_period +What: /sys/.../events/in_voltageY_supply_thresh_falling_period +What: /sys/.../events/in_voltageY_supply_roc_rising_period +What: /sys/.../events/in_voltageY_supply_roc_falling_period +What: /sys/.../events/in_voltageY_thresh_rising_period +What: /sys/.../events/in_voltageY_thresh_falling_period +What: /sys/.../events/in_voltageY_roc_rising_period +What: /sys/.../events/in_voltageY_roc_falling_period +What: /sys/.../events/in_tempY_thresh_rising_period +What: /sys/.../events/in_tempY_thresh_falling_period +What: /sys/.../events/in_tempY_roc_rising_period +What: /sys/.../events/in_tempY_roc_falling_period +What: /sys/.../events/in_accel_x&y&z_mag_falling_period +What: /sys/.../events/in_intensity0_thresh_period +What: /sys/.../events/in_proximity0_thresh_period +What: /sys/.../events/in_activity_still_thresh_rising_period +What: /sys/.../events/in_activity_still_thresh_falling_period +What: /sys/.../events/in_activity_walking_thresh_rising_period +What: /sys/.../events/in_activity_walking_thresh_falling_period +What: /sys/.../events/in_activity_jogging_thresh_rising_period +What: /sys/.../events/in_activity_jogging_thresh_falling_period +What: /sys/.../events/in_activity_running_thresh_rising_period +What: /sys/.../events/in_activity_running_thresh_falling_period +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Period of time (in seconds) for which the condition must be + met before an event is generated. If direction is not + specified then this period applies to both directions. + +What: /sys/.../events/in_accel_thresh_rising_low_pass_filter_3db +What: /sys/.../events/in_anglvel_thresh_rising_low_pass_filter_3db +What: /sys/.../events/in_magn_thresh_rising_low_pass_filter_3db +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + If a low pass filter can be applied to the event generation + this property gives its 3db frequency in Hz. + A value of zero disables the filter. + +What: /sys/.../events/in_accel_thresh_rising_high_pass_filter_3db +What: /sys/.../events/in_anglvel_thresh_rising_high_pass_filter_3db +What: /sys/.../events/in_magn_thresh_rising_high_pass_filter_3db +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + If a high pass filter can be applied to the event generation + this property gives its 3db frequency in Hz. + A value of zero disables the filter. + +What: /sys/.../events/in_activity_still_thresh_rising_en +What: /sys/.../events/in_activity_still_thresh_falling_en +What: /sys/.../events/in_activity_walking_thresh_rising_en +What: /sys/.../events/in_activity_walking_thresh_falling_en +What: /sys/.../events/in_activity_jogging_thresh_rising_en +What: /sys/.../events/in_activity_jogging_thresh_falling_en +What: /sys/.../events/in_activity_running_thresh_rising_en +What: /sys/.../events/in_activity_running_thresh_falling_en +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Enables or disables activitity events. Depending on direction + an event is generated when sensor ENTERS or LEAVES a given state. + +What: /sys/.../events/in_activity_still_thresh_rising_value +What: /sys/.../events/in_activity_still_thresh_falling_value +What: /sys/.../events/in_activity_walking_thresh_rising_value +What: /sys/.../events/in_activity_walking_thresh_falling_value +What: /sys/.../events/in_activity_jogging_thresh_rising_value +What: /sys/.../events/in_activity_jogging_thresh_falling_value +What: /sys/.../events/in_activity_running_thresh_rising_value +What: /sys/.../events/in_activity_running_thresh_falling_value +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Confidence value (in units as percentage) to be used + for deciding when an event should be generated. E.g for + running: If the confidence value reported by the sensor + is greater than in_activity_running_thresh_rising_value + then the sensor ENTERS running state. Conversely, if the + confidence value reported by the sensor is lower than + in_activity_running_thresh_falling_value then the sensor + is LEAVING running state. + +What: /sys/.../iio:deviceX/events/in_accel_mag_en +What: /sys/.../iio:deviceX/events/in_accel_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_y_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_z_mag_falling_en +What: /sys/.../iio:deviceX/events/in_accel_x&y&z_mag_rising_en +What: /sys/.../iio:deviceX/events/in_accel_x&y&z_mag_falling_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Similar to in_accel_x_thresh[_rising|_falling]_en, but here the + magnitude of the channel is compared to the threshold, not its + signed value. + +What: /sys/.../events/in_accel_raw_mag_value +What: /sys/.../events/in_accel_x_raw_mag_rising_value +What: /sys/.../events/in_accel_y_raw_mag_rising_value +What: /sys/.../events/in_accel_z_raw_mag_rising_value +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + The value to which the magnitude of the channel is compared. If + number or direction is not specified, applies to all channels of + this type. + +What: /sys/.../events/in_steps_change_en +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Event generated when channel passes a threshold on the absolute + change in value. E.g. for steps: a step change event is + generated each time the user takes N steps, where N is set using + in_steps_change_value. + +What: /sys/.../events/in_steps_change_value +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the value of change threshold that the + device is comparing against for the events enabled by + <type>[Y][_name]_roc[_rising|falling|]_en. E.g. for steps: + if set to 3, a step change event will be generated every 3 + steps. + +What: /sys/bus/iio/devices/iio:deviceX/trigger/current_trigger +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + The name of the trigger source being used, as per string given + in /sys/class/iio/triggerY/name. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/length +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Number of scans contained by the buffer. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/enable +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Actually start the buffer capture up. Will start trigger + if first device and appropriate. + +What: /sys/bus/iio/devices/iio:deviceX/scan_elements +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Directory containing interfaces for elements that will be + captured for a single triggered sample set in the buffer. + +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_en +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_en +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_en +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_en +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_en +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY-voltageZ_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_i_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_q_en +What: /sys/.../iio:deviceX/scan_elements/in_voltage_i_en +What: /sys/.../iio:deviceX/scan_elements/in_voltage_q_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en +What: /sys/.../iio:deviceX/scan_elements/in_pressure_en +What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en +What: /sys/.../iio:deviceX/scan_elements/in_proximity_en +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Scan element control for triggered data capture. + +What: /sys/.../iio:deviceX/scan_elements/in_accel_type +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_type +What: /sys/.../iio:deviceX/scan_elements/in_magn_type +What: /sys/.../iio:deviceX/scan_elements/in_incli_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_type +What: /sys/.../iio:deviceX/scan_elements/in_voltage_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_i_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_q_type +What: /sys/.../iio:deviceX/scan_elements/in_voltage_i_type +What: /sys/.../iio:deviceX/scan_elements/in_voltage_q_type +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type +What: /sys/.../iio:deviceX/scan_elements/in_pressure_type +What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type +What: /sys/.../iio:deviceX/scan_elements/in_proximity_type +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + Description of the scan element data storage within the buffer + and hence the form in which it is read from user-space. + Form is [be|le]:[s|u]bits/storagebits[>>shift]. + be or le specifies big or little endian. s or u specifies if + signed (2's complement) or unsigned. bits is the number of bits + of data and storagebits is the space (after padding) that it + occupies in the buffer. shift if specified, is the shift that + needs to be applied prior to masking out unused bits. Some + devices put their data in the middle of the transferred elements + with additional information on both sides. Note that some + devices will have additional information in the unused bits + so to get a clean value, the bits value must be used to mask + the buffer output value appropriately. The storagebits value + also specifies the data alignment. So s48/64>>2 will be a + signed 48 bit integer stored in a 64 bit location aligned to + a 64 bit boundary. To obtain the clean value, shift right 2 + and apply a mask to zero the top 16 bits of the result. + For other storage combinations this attribute will be extended + appropriately. + +What: /sys/.../iio:deviceX/scan_elements/in_accel_type_available +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + If the type parameter can take one of a small set of values, + this attribute lists them. + +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_i_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_q_index +What: /sys/.../iio:deviceX/scan_elements/in_voltage_i_index +What: /sys/.../iio:deviceX/scan_elements/in_voltage_q_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_index +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_index +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_index +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_magnetic_tilt_comp_index +What: /sys/.../iio:deviceX/scan_elements/in_rot_from_north_true_tilt_comp_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index +What: /sys/.../iio:deviceX/scan_elements/in_pressure_index +What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index +What: /sys/.../iio:deviceX/scan_elements/in_proximity_index +KernelVersion: 2.6.37 +Contact: linux-iio@vger.kernel.org +Description: + A single positive integer specifying the position of this + scan element in the buffer. Note these are not dependent on + what is enabled and may not be contiguous. Thus for user-space + to establish the full layout these must be used in conjunction + with all _en attributes to establish which channels are present, + and the relevant _type attributes to establish the data storage + format. + +What: /sys/.../iio:deviceX/in_activity_still_input +What: /sys/.../iio:deviceX/in_activity_walking_input +What: /sys/.../iio:deviceX/in_activity_jogging_input +What: /sys/.../iio:deviceX/in_activity_running_input +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the confidence for an activity + expressed in units as percentage. + +What: /sys/.../iio:deviceX/in_anglvel_z_quadrature_correction_raw +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the amount of quadrature error + present in the device at a given time. + +What: /sys/.../iio:deviceX/in_accelX_power_mode +KernelVersion: 3.11 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the chip power mode. + low_noise: reduce noise level from ADC, + low_power: enable low current consumption. + For a list of available output power modes read + in_accel_power_mode_available. + +What: /sys/.../iio:deviceX/in_energy_input +What: /sys/.../iio:deviceX/in_energy_raw +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the energy value reported by the + device (e.g.: human activity sensors report energy burnt by the + user). Units after application of scale are Joules. + +What: /sys/.../iio:deviceX/in_distance_input +What: /sys/.../iio:deviceX/in_distance_raw +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the distance covered by the user + since the last reboot while activated. Units after application + of scale are meters. + +What: /sys/bus/iio/devices/iio:deviceX/store_eeprom +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Writing '1' stores the current device configuration into + on-chip EEPROM. After power-up or chip reset the device will + automatically load the saved configuration. + +What: /sys/.../iio:deviceX/in_proximity_raw +What: /sys/.../iio:deviceX/in_proximity_input +What: /sys/.../iio:deviceX/in_proximityY_raw +KernelVersion: 3.4 +Contact: linux-iio@vger.kernel.org +Description: + Proximity measurement indicating that some + object is near the sensor, usually by observing + reflectivity of infrared or ultrasound emitted. + Often these sensors are unit less and as such conversion + to SI units is not possible. Higher proximity measurements + indicate closer objects, and vice versa. + +What: /sys/.../iio:deviceX/in_illuminance_input +What: /sys/.../iio:deviceX/in_illuminance_raw +What: /sys/.../iio:deviceX/in_illuminanceY_input +What: /sys/.../iio:deviceX/in_illuminanceY_raw +What: /sys/.../iio:deviceX/in_illuminanceY_mean_raw +What: /sys/.../iio:deviceX/in_illuminance_ir_raw +What: /sys/.../iio:deviceX/in_illuminance_clear_raw +KernelVersion: 3.4 +Contact: linux-iio@vger.kernel.org +Description: + Illuminance measurement, units after application of scale + and offset are lux. + +What: /sys/.../iio:deviceX/in_intensityY_raw +What: /sys/.../iio:deviceX/in_intensityY_ir_raw +What: /sys/.../iio:deviceX/in_intensityY_both_raw +What: /sys/.../iio:deviceX/in_intensityY_uv_raw +KernelVersion: 3.4 +Contact: linux-iio@vger.kernel.org +Description: + Unit-less light intensity. Modifiers both and ir indicate + that measurements contains visible and infrared light + components or just infrared light, respectively. Modifier uv indicates + that measurements contain ultraviolet light components. + +What: /sys/.../iio:deviceX/in_uvindex_input +KernelVersion: 4.6 +Contact: linux-iio@vger.kernel.org +Description: + UV light intensity index measuring the human skin's response to + different wavelength of sunlight weighted according to the + standardised CIE Erythemal Action Spectrum. UV index values range + from 0 (low) to >=11 (extreme). + +What: /sys/.../iio:deviceX/in_intensity_red_integration_time +What: /sys/.../iio:deviceX/in_intensity_green_integration_time +What: /sys/.../iio:deviceX/in_intensity_blue_integration_time +What: /sys/.../iio:deviceX/in_intensity_clear_integration_time +What: /sys/.../iio:deviceX/in_illuminance_integration_time +KernelVersion: 3.12 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to get/set the integration time in + seconds. + +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_integration_time +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Number of seconds in which to compute speed. + +What: /sys/bus/iio/devices/iio:deviceX/in_rot_quaternion_raw +KernelVersion: 3.15 +Contact: linux-iio@vger.kernel.org +Description: + Raw value of quaternion components using a format + x y z w. Here x, y, and z component represents the axis about + which a rotation will occur and w component represents the + amount of rotation. + +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_tilt_comp_raw +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_tilt_comp_raw +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_magnetic_raw +What: /sys/bus/iio/devices/iio:deviceX/in_rot_from_north_true_raw +KernelVersion: 3.15 +Contact: linux-iio@vger.kernel.org +Description: + Raw value of rotation from true/magnetic north measured with + or without compensation from tilt sensors. + +What: /sys/bus/iio/devices/iio:deviceX/in_currentX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentX_i_raw +What: /sys/bus/iio/devices/iio:deviceX/in_currentX_q_raw +KernelVersion: 3.18 +Contact: linux-iio@vger.kernel.org +Description: + Raw current measurement from channel X. Units are in milliamps + after application of scale and offset. If no offset or scale is + present, output should be considered as processed with the + unit in milliamps. + + Channels with 'i' and 'q' modifiers always exist in pairs and both + channels refer to the same signal. The 'i' channel contains the in-phase + component of the signal while the 'q' channel contains the quadrature + component. + +What: /sys/.../iio:deviceX/in_energy_en +What: /sys/.../iio:deviceX/in_distance_en +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_en +What: /sys/.../iio:deviceX/in_steps_en +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + Activates a device feature that runs in firmware/hardware. + E.g. for steps: the pedometer saves power while not used; + when activated, it will count the steps taken by the user in + firmware and export them through in_steps_input. + +What: /sys/.../iio:deviceX/in_steps_input +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the number of steps taken by the user + since the last reboot while activated. + +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_input +What: /sys/.../iio:deviceX/in_velocity_sqrt(x^2+y^2+z^2)_raw +KernelVersion: 3.19 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to read the current speed value of the + user (which is the norm or magnitude of the velocity vector). + Units after application of scale are m/s. + +What: /sys/.../iio:deviceX/in_steps_debounce_count +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the number of steps that must occur within + in_steps_filter_debounce_time for the pedometer to decide the + consumer is making steps. + +What: /sys/.../iio:deviceX/in_steps_debounce_time +KernelVersion: 4.0 +Contact: linux-iio@vger.kernel.org +Description: + Specifies number of seconds in which we compute the steps + that occur in order to decide if the consumer is making steps. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/watermark +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + A single positive integer specifying the maximum number of scan + elements to wait for. + Poll will block until the watermark is reached. + Blocking read will wait until the minimum between the requested + read amount or the low water mark is available. + Non-blocking read will retrieve the available samples from the + buffer even if there are less samples then watermark level. This + allows the application to block on poll with a timeout and read + the available samples after the timeout expires and thus have a + maximum delay guarantee. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_enabled +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + A read-only boolean value that indicates if the hardware fifo is + currently enabled or disabled. If the device does not have a + hardware fifo this entry is not present. + The hardware fifo is enabled when the buffer is enabled if the + current hardware fifo watermark level is set and other current + device settings allows it (e.g. if a trigger is set that samples + data differently that the hardware fifo does then hardware fifo + will not enabled). + If the hardware fifo is enabled and the level of the hardware + fifo reaches the hardware fifo watermark level the device will + flush its hardware fifo to the device buffer. Doing a non + blocking read on the device when no samples are present in the + device buffer will also force a flush. + When the hardware fifo is enabled there is no need to use a + trigger to use buffer mode since the watermark settings + guarantees that the hardware fifo is flushed to the device + buffer. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_watermark +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + Read-only entry that contains a single integer specifying the + current watermark level for the hardware fifo. If the device + does not have a hardware fifo this entry is not present. + The watermark level for the hardware fifo is set by the driver + based on the value set by the user in buffer/watermark but + taking into account hardware limitations (e.g. most hardware + buffers are limited to 32-64 samples, some hardware buffers + watermarks are fixed or have minimum levels). A value of 0 + means that the hardware watermark is unset. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_watermark_min +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + A single positive integer specifying the minimum watermark level + for the hardware fifo of this device. If the device does not + have a hardware fifo this entry is not present. + If the user sets buffer/watermark to a value less than this one, + then the hardware watermark will remain unset. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_watermark_max +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + A single positive integer specifying the maximum watermark level + for the hardware fifo of this device. If the device does not + have a hardware fifo this entry is not present. + If the user sets buffer/watermark to a value greater than this + one, then the hardware watermark will be capped at this value. + +What: /sys/bus/iio/devices/iio:deviceX/buffer/hwfifo_watermark_available +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + A list of positive integers specifying the available watermark + levels for the hardware fifo. This entry is optional and if it + is not present it means that all the values between + hwfifo_watermark_min and hwfifo_watermark_max are supported. + If the user sets buffer/watermark to a value greater than + hwfifo_watermak_min but not equal to any of the values in this + list, the driver will chose an appropriate value for the + hardware fifo watermark level. + +What: /sys/bus/iio/devices/iio:deviceX/in_temp_calibemissivity +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_calibemissivity +What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_calibemissivity +What: /sys/bus/iio/devices/iio:deviceX/in_tempX_object_calibemissivity +KernelVersion: 4.1 +Contact: linux-iio@vger.kernel.org +Description: + The emissivity ratio of the surface in the field of view of the + contactless temperature sensor. Emissivity varies from 0 to 1, + with 1 being the emissivity of a black body. + +What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_oversampling_ratio +What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_oversampling_ratio +What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_oversampling_ratio +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied number of measurements for acquiring one + data point. The HW will do <type>[_name]_oversampling_ratio + measurements and return the average value as output data. Each + value resulted from <type>[_name]_oversampling_ratio measurements + is considered as one sample for <type>[_name]_sampling_frequency. + +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_voc_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) percentage reading of a substance. + +What: /sys/bus/iio/devices/iio:deviceX/in_resistance_raw +What: /sys/bus/iio/devices/iio:deviceX/in_resistanceX_raw +What: /sys/bus/iio/devices/iio:deviceX/out_resistance_raw +What: /sys/bus/iio/devices/iio:deviceX/out_resistanceX_raw +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) resistance reading that can be processed + into an ohm value. + +What: /sys/bus/iio/devices/iio:deviceX/heater_enable +KernelVersion: 4.1.0 +Contact: linux-iio@vger.kernel.org +Description: + '1' (enable) or '0' (disable) specifying the enable + of heater function. Same reading values apply + This ABI is especially applicable for humidity sensors + to heatup the device and get rid of any condensation + in some humidity environment + +What: /sys/bus/iio/devices/iio:deviceX/in_ph_raw +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) pH reading of a substance as a negative + base-10 logarithm of hydrodium ions in a litre of water. + +What: /sys/bus/iio/devices/iio:deviceX/mount_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_mount_matrix +What: /sys/bus/iio/devices/iio:deviceX/out_mount_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_mount_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_accel_mount_matrix +KernelVersion: 4.6 +Contact: linux-iio@vger.kernel.org +Description: + Mounting matrix for IIO sensors. This is a rotation matrix which + informs userspace about sensor chip's placement relative to the + main hardware it is mounted on. + Main hardware placement is defined according to the local + reference frame related to the physical quantity the sensor + measures. + Given that the rotation matrix is defined in a board specific + way (platform data and / or device-tree), the main hardware + reference frame definition is left to the implementor's choice + (see below for a magnetometer example). + Applications should apply this rotation matrix to samples so + that when main hardware reference frame is aligned onto local + reference frame, then sensor chip reference frame is also + perfectly aligned with it. + Matrix is a 3x3 unitary matrix and typically looks like + [0, 1, 0; 1, 0, 0; 0, 0, -1]. Identity matrix + [1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and main hardware + are perfectly aligned with each other. + + For example, a mounting matrix for a magnetometer sensor informs + userspace about sensor chip's ORIENTATION relative to the main + hardware. + More specifically, main hardware orientation is defined with + respect to the LOCAL EARTH GEOMAGNETIC REFERENCE FRAME where : + * Y is in the ground plane and positive towards magnetic North ; + * X is in the ground plane, perpendicular to the North axis and + positive towards the East ; + * Z is perpendicular to the ground plane and positive upwards. + + An implementor might consider that for a hand-held device, a + 'natural' orientation would be 'front facing camera at the top'. + The main hardware reference frame could then be described as : + * Y is in the plane of the screen and is positive towards the + top of the screen ; + * X is in the plane of the screen, perpendicular to Y axis, and + positive towards the right hand side of the screen ; + * Z is perpendicular to the screen plane and positive out of the + screen. + Another example for a quadrotor UAV might be : + * Y is in the plane of the propellers and positive towards the + front-view camera; + * X is in the plane of the propellers, perpendicular to Y axis, + and positive towards the starboard side of the UAV ; + * Z is perpendicular to propellers plane and positive upwards. + +What: /sys/bus/iio/devices/iio:deviceX/in_electricalconductivity_raw +KernelVersion: 4.8 +Contact: linux-iio@vger.kernel.org +Description: + Raw (unscaled no offset etc.) electric conductivity reading that + can be processed to siemens per meter.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150 b/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150 new file mode 100644 index 0000000..99847a9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-accel-bmc150
@@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/triggerX/name = "bmc150_accel-any-motion-devX" +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + The BMC150 accelerometer kernel module provides an additional trigger, + which sets driver in a mode, where data is pushed to the buffer + only when there is any motion.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 new file mode 100644 index 0000000..f30b4c4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
@@ -0,0 +1,43 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_sensing_mode +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Program sensor type for threshold detector inputs. + Could be either "GND-Open" or "Supply-Open" mode. Y is a + threshold detector input channel. Channels 0..7, 8..15, 16..23 + and 24..31 has common sensor types. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_falling_value +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Channel Y low voltage threshold. If sensor input voltage goes lower then + this value then the threshold falling event is pushed. + Depending on in_voltageY_sensing_mode the low voltage threshold + is separately set for "GND-Open" and "Supply-Open" modes. + Channels 0..31 have common low threshold values, but could have different + sensing_modes. + The low voltage threshold range is between 2..21V. + Hysteresis between low and high thresholds can not be lower then 2 and + can not be odd. + If falling threshold results hysteresis to odd value then rising + threshold is automatically subtracted by one. + +What: /sys/bus/iio/devices/iio:deviceX/events/in_voltageY_thresh_rising_value +Date: August 2015 +KernelVersion: 4.2.0 +Contact: source@cogentembedded.com +Description: + Channel Y high voltage threshold. If sensor input voltage goes higher then + this value then the threshold rising event is pushed. + Depending on in_voltageY_sensing_mode the high voltage threshold + is separately set for "GND-Open" and "Supply-Open" modes. + Channels 0..31 have common high threshold values, but could have different + sensing_modes. + The high voltage threshold range is between 3..22V. + Hysteresis between low and high thresholds can not be lower then 2 and + can not be odd. + If rising threshold results hysteresis to odd value then falling + threshold is automatically appended by one.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x new file mode 100644 index 0000000..c0c1ea9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-chemical-vz89x
@@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_VOC_short_raw +Date: September 2015 +KernelVersion: 4.3 +Contact: Matt Ranostay <mranostay@gmail.com> +Description: + Get the raw calibration VOC value from the sensor. + This value has little application outside of calibration.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 new file mode 100644 index 0000000..a91aeab --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
@@ -0,0 +1,29 @@ +What: /sys/bus/iio/devices/iio:deviceX/pll2_feedback_clk_present +What: /sys/bus/iio/devices/iio:deviceX/pll2_reference_clk_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_a_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_b_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_test_present +What: /sys/bus/iio/devices/iio:deviceX/vcxo_clk_present +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. + '1' means that the clock in question is present. + '0' means that the clock is missing. + +What: /sys/bus/iio/devices/iio:deviceX/pllY_locked +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. '1' means that the + pllY is locked. + +What: /sys/bus/iio/devices/iio:deviceX/sync_dividers +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Writing '1' triggers the clock distribution synchronization + functionality. All dividers are reset and the channels start + with their predefined phase offsets (out_altvoltageY_phase). + Writing this file has the effect as driving the external + /SYNC pin low.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350 new file mode 100644 index 0000000..1254457 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350
@@ -0,0 +1,21 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_resolution +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Stores channel Y frequency resolution/channel spacing in Hz. + The value given directly influences the MODULUS used by + the fractional-N PLL. It is assumed that the algorithm + that is used to compute the various dividers, is able to + generate proper values for multiples of channel spacing. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_refin_frequency +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Sets channel Y REFin frequency in Hz. In some clock chained + applications, the reference frequency used by the PLL may + change during runtime. This attribute allows the user to + adjust the reference frequency accordingly. + The value written has no effect until out_altvoltageY_frequency + is updated. Consider to use out_altvoltageY_powerdown to power + down the PLL and its RFOut buffers during REFin changes.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160 b/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160 new file mode 100644 index 0000000..e98209c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-gyro-bmg160
@@ -0,0 +1,7 @@ +What: /sys/bus/iio/devices/triggerX/name = "bmg160-any-motion-devX" +KernelVersion: 3.17 +Contact: linux-iio@vger.kernel.org +Description: + The BMG160 gyro kernel module provides an additional trigger, + which sets driver in a mode, where data is pushed to the buffer + only when there is any motion.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x new file mode 100644 index 0000000..6adba90 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
@@ -0,0 +1,41 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_raw +Date: May 2016 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get measured values from the ADC for these stages. Y is the + specific stage number corresponding to datasheet stage names + as follows: + 1 -> LED2 + 2 -> ALED2/LED3 + 3 -> LED1 + 4 -> ALED1/LED4 + Note that channels 5 and 6 represent LED2-ALED2 and LED1-ALED1 + respectively which simply helper channels containing the + calculated difference in the value of stage 1 - 2 and 3 - 4. + The values are expressed in 24-bit twos complement. + +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_offset +Date: May 2016 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the offset cancellation DAC setting for these + stages. The values are expressed in 5-bit sign-magnitude. + +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_resistance +What: /sys/bus/iio/devices/iio:deviceX/in_intensityY_capacitance +Date: May 2016 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the resistance and the capacitance settings for the + Transimpedance Amplifier during the associated stage. + +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw +Date: May 2016 +KernelVersion: +Contact: Andrew F. Davis <afd@ti.com> +Description: + Get and set the LED current for the specified LED active during + this stage. Y is the specific stage number.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x new file mode 100644 index 0000000..b72bb62 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x
@@ -0,0 +1,9 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw +What: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available +KernelVersion: 4.3 +Contact: linux-iio@vger.kernel.org +Description: + Controls the heater device within the humidity sensor to get + rid of excess condensation. + + Valid control values are 0 = OFF, and 1 = ON.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc new file mode 100644 index 0000000..8916f7e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-ina2xx-adc
@@ -0,0 +1,24 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_allow_async_readout +Date: December 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + By default (value '0'), the capture thread checks for the Conversion + Ready Flag to being set prior to committing a new value to the sample + buffer. This synchronizes the in-chip conversion rate with the + in-driver readout rate at the cost of an additional register read. + + Writing '1' will remove the polling for the Conversion Ready Flags to + save the additional i2c transaction, which will improve the bandwidth + available for reading data. However, samples can be occasionally skipped + or repeated, depending on the beat between the capture and conversion + rates. + +What: /sys/bus/iio/devices/iio:deviceX/in_shunt_resistor +Date: December 2015 +KernelVersion: 4.4 +Contact: linux-iio@vger.kernel.org +Description: + The value of the shunt resistor may be known only at runtime fom an + eeprom content read by a client application. This attribute allows to + set its value in ohms.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als new file mode 100644 index 0000000..22c5ea6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
@@ -0,0 +1,61 @@ +What: /sys/.../events/in_illuminance0_thresh_either_en +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Event generated when channel passes one of the four thresholds + in each direction (rising|falling) and a zone change occurs. + The corresponding light zone can be read from + in_illuminance0_zone. + +What: /sys/.../events/in_illuminance0_threshY_hysteresis +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the hysteresis for thresholds Y, that is, + threshY_hysteresis = threshY_raising - threshY_falling + +What: /sys/.../events/illuminance_threshY_falling_value +What: /sys/.../events/illuminance_threshY_raising_value +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Specifies the value of threshold that the device is comparing + against for the events enabled by + in_illuminance0_thresh_either_en (0..255), where Y in 0..3. + + Note that threshY_falling must be less than or equal to + threshY_raising. + + These thresholds correspond to the eight zone-boundary + registers (boundaryY_{low,high}) and define the five light + zones. + +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_zone +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the current light zone (0..4) as defined by the + in_illuminance0_threshY_{falling,rising} thresholds. + +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get output current for channel Y (0..255), that is, + out_currentY_currentZ_raw, where Z is the current zone. + +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the output current for channel out_currentY when in zone + Z (0..255), where Y in 0..2 and Z in 0..4. + + These values correspond to the ALS-mapper target registers for + ALS-mapper Y + 1.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 new file mode 100644 index 0000000..6275e9f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
@@ -0,0 +1,15 @@ +What: /sys/bus/iio/devices/iio:deviceX/meas_conf +What: /sys/bus/iio/devices/iio:deviceX/meas_conf_available +KernelVersion: 4.5 +Contact: linux-iio@vger.kernel.org +Description: + Current configuration and available configurations + for the bias current. + normal - Normal measurement configurations (default) + positivebias - Positive bias configuration + negativebias - Negative bias configuration + disabled - Only available on HMC5983. Disables magnetic + sensor and enables temperature sensor. + Note: The effect of this configuration may vary + according to the device. For exact documentation + check the device's datasheet.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-meas-spec b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec new file mode 100644 index 0000000..1a6265e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-meas-spec
@@ -0,0 +1,8 @@ +What: /sys/bus/iio/devices/iio:deviceX/battery_low +KernelVersion: 4.1.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. '1' means that the + battery level supplied to sensor is below 2.25V. + This ABI is available for tsys02d, htu21, ms8607 + This ABI is available for htu21, ms8607
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-mpu6050 b/Documentation/ABI/testing/sysfs-bus-iio-mpu6050 new file mode 100644 index 0000000..cb53737 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-mpu6050
@@ -0,0 +1,13 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_gyro_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_accel_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_magn_matrix +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + This is mounting matrix for motion sensors. Mounting matrix + is a 3x3 unitary matrix. A typical mounting matrix would look like + [0, 1, 0; 1, 0, 0; 0, 0, -1]. Using this information, it would be + easy to tell the relative positions among sensors as well as their + positions relative to the board that holds these sensors. Identity matrix + [1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and device are perfectly + aligned with each other. All axes are exactly the same.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 new file mode 100644 index 0000000..33e96f7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
@@ -0,0 +1,16 @@ +What /sys/bus/iio/devices/iio:deviceX/in_proximity_input +Date: March 2014 +KernelVersion: 3.15 +Contact: Matt Ranostay <mranostay@gmail.com> +Description: + Get the current distance in meters of storm (1km steps) + 1000-40000 = distance in meters + +What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity +Date: March 2014 +KernelVersion: 3.15 +Contact: Matt Ranostay <mranostay@gmail.com> +Description: + Show or set the gain boost of the amp, from 0-31 range. + 18 = indoors (default) + 14 = outdoors
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs new file mode 100644 index 0000000..04ac623 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-trigger-sysfs
@@ -0,0 +1,42 @@ +What: /sys/bus/iio/devices/triggerX/trigger_now +KernelVersion: 2.6.38 +Contact: linux-iio@vger.kernel.org +Description: + This file is provided by the iio-trig-sysfs stand-alone trigger + driver. Writing this file with any value triggers an event + driven driver, associated with this trigger, to capture data + into an in kernel buffer. This approach can be valuable during + automated testing or in situations, where other trigger methods + are not applicable. For example no RTC or spare GPIOs. + X is the IIO index of the trigger. + +What: /sys/bus/iio/devices/triggerX/name +KernelVersion: 2.6.39 +Contact: linux-iio@vger.kernel.org +Description: + The name attribute holds a description string for the current + trigger. In order to associate the trigger with an IIO device + one should write this name string to + /sys/bus/iio/devices/iio:deviceY/trigger/current_trigger. + +What: /sys/bus/iio/devices/iio_sysfs_trigger/add_trigger +KernelVersion: 2.6.39 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is provided by the iio-trig-sysfs stand-alone + driver and it is used to activate the creation of a new trigger. + In order to achieve this, one should write a positive integer + into the associated file, which will serve as the id of the + trigger. If the trigger with the specified id is already present + in the system, an invalid argument message will be returned. + +What: /sys/bus/iio/devices/iio_sysfs_trigger/remove_trigger +KernelVersion: 2.6.39 +Contact: linux-iio@vger.kernel.org +Description: + This attribute is used to unregister and delete a previously + created trigger from the list of available triggers. In order to + achieve this, one should write a positive integer into the + associated file, representing the id of the trigger that needs + to be removed. If the trigger can't be found, an invalid + argument message will be returned to the user.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-vf610 b/Documentation/ABI/testing/sysfs-bus-iio-vf610 new file mode 100644 index 0000000..308a675 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-vf610
@@ -0,0 +1,16 @@ +What: /sys/bus/iio/devices/iio:deviceX/conversion_mode +KernelVersion: 4.2 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the hardware conversion mode used. The three + available modes are "normal", "high-speed" and "low-power", + where the last is the default mode. + + +What: /sys/bus/iio/devices/iio:deviceX/out_conversion_mode +KernelVersion: 4.6 +Contact: linux-iio@vger.kernel.org +Description: + Specifies the hardware conversion mode used within DAC. + The two available modes are "high-power" and "low-power", + where "low-power" mode is the default mode.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth new file mode 100644 index 0000000..22d0843 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
@@ -0,0 +1,49 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/masters/* +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure output ports for STP masters. Writing -1 + disables a master; any + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_port +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Output port type: + 0: not present, + 1: MSU (Memory Storage Unit) + 2: CTP (Common Trace Port) + 4: PTI (MIPI PTI). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_drop +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Data retention policy setting: keep (0) or drop (1) + incoming data while output port is in reset. + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_null +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) STP NULL packet generation: enabled (1) or disabled (0). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_flush +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Force flush data from byte packing buffer for the output + port. + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_reset +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Output port is in reset (1). + +What: /sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_smcfreq +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) STP sync packet frequency for the port. Specifies the + number of clocks between mainenance packets.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc new file mode 100644 index 0000000..b940c5d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
@@ -0,0 +1,33 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/wrap +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC buffer wrapping. 1 == wrapping enabled. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/mode +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC operating mode: + - "single", for contiguous buffer mode (high-order alloc); + - "multi", for multiblock mode; + - "ExI", for DCI handler mode; + - "debug", for debug mode. + If operating mode changes, existing buffer is deallocated, + provided there are no active users and tracing is not enabled, + otherwise the write will fail. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/nr_pages +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure MSC buffer size for "single" or "multi" modes. + In single mode, this is a single number of pages, has to be + power of 2. In multiblock mode, this is a comma-separated list + of numbers of pages for each window to be allocated. Number of + windows is not limited. + Writing to this file deallocates existing buffer (provided + there are no active users and tracing is not enabled) and then + allocates a new one. + +
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti new file mode 100644 index 0000000..df0b24f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-pti
@@ -0,0 +1,24 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/mode +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure PTI output width. Currently supported values + are 4, 8, 12, 16. + +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/freerunning_clock +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) 0: PTI trace clock acts as a strobe which only toggles + when there is trace data to send. 1: PTI trace clock is a + free-running clock. + +What: /sys/bus/intel_th/devices/<intel_th_id>-pti/clock_divider +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Configure PTI port clock divider: + - 0: Intel TH clock rate, + - 1: 1/2 Intel TH clock rate, + - 2: 1/4 Intel TH clock rate, + - 3: 1/8 Intel TH clock rate.
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices new file mode 100644 index 0000000..4d48a94 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices
@@ -0,0 +1,13 @@ +What: /sys/bus/intel_th/devices/<intel_th_id>-<device><id>/active +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RW) Writes of 1 or 0 enable or disable trace output to this + output device. Reads return current status. + +What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/port +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: (RO) Port number, corresponding to this output device on the + switch (GTH).
diff --git a/Documentation/ABI/testing/sysfs-bus-mcb b/Documentation/ABI/testing/sysfs-bus-mcb new file mode 100644 index 0000000..77947c5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mcb
@@ -0,0 +1,29 @@ +What: /sys/bus/mcb/devices/mcb:X +Date: March 2016 +KernelVersion: 4.7 +Contact: Johannes Thumshirn <jth@kernel.org> +Description: Hardware chip or device hosting the MEN chameleon bus + +What: /sys/bus/mcb/devices/mcb:X/revision +Date: March 2016 +KernelVersion: 4.7 +Contact: Johannes Thumshirn <jth@kernel.org> +Description: The FPGA's revision number + +What: /sys/bus/mcb/devices/mcb:X/minor +Date: March 2016 +KernelVersion: 4.7 +Contact: Johannes Thumshirn <jth@kernel.org> +Description: The FPGA's minor number + +What: /sys/bus/mcb/devices/mcb:X/model +Date: March 2016 +KernelVersion: 4.7 +Contact: Johannes Thumshirn <jth@kernel.org> +Description: The FPGA's model number + +What: /sys/bus/mcb/devices/mcb:X/name +Date: March 2016 +KernelVersion: 4.7 +Contact: Johannes Thumshirn <jth@kernel.org> +Description: The FPGA's name
diff --git a/Documentation/ABI/testing/sysfs-bus-mdio b/Documentation/ABI/testing/sysfs-bus-mdio new file mode 100644 index 0000000..491baaf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mdio
@@ -0,0 +1,29 @@ +What: /sys/bus/mdio_bus/devices/.../phy_id +Date: November 2012 +KernelVersion: 3.8 +Contact: netdev@vger.kernel.org +Description: + This attribute contains the 32-bit PHY Identifier as reported + by the device during bus enumeration, encoded in hexadecimal. + This ID is used to match the device with the appropriate + driver. + +What: /sys/bus/mdio_bus/devices/.../phy_interface +Date: February 2014 +KernelVersion: 3.15 +Contact: netdev@vger.kernel.org +Description: + This attribute contains the PHY interface as configured by the + Ethernet driver during bus enumeration, encoded in string. + This interface mode is used to configure the Ethernet MAC with the + appropriate mode for its data lines to the PHY hardware. + +What: /sys/bus/mdio_bus/devices/.../phy_has_fixups +Date: February 2014 +KernelVersion: 3.15 +Contact: netdev@vger.kernel.org +Description: + This attribute contains the boolean value whether a given PHY + device has had any "fixup" workaround running on it, encoded as + a boolean. This information is provided to help troubleshooting + PHY configurations.
diff --git a/Documentation/ABI/testing/sysfs-bus-media b/Documentation/ABI/testing/sysfs-bus-media new file mode 100644 index 0000000..7057e57 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-media
@@ -0,0 +1,6 @@ +What: /sys/bus/media/devices/.../model +Date: January 2011 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + linux-media@vger.kernel.org +Description: Contains the device model name in UTF-8. The device version is + is not be appended to the model name.
diff --git a/Documentation/ABI/testing/sysfs-bus-mei b/Documentation/ABI/testing/sysfs-bus-mei new file mode 100644 index 0000000..6bd4534 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mei
@@ -0,0 +1,28 @@ +What: /sys/bus/mei/devices/.../modalias +Date: March 2013 +KernelVersion: 3.10 +Contact: Samuel Ortiz <sameo@linux.intel.com> + linux-mei@linux.intel.com +Description: Stores the same MODALIAS value emitted by uevent + Format: mei:<mei device name>:<device uuid>: + +What: /sys/bus/mei/devices/.../name +Date: May 2015 +KernelVersion: 4.2 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Stores mei client device name + Format: string + +What: /sys/bus/mei/devices/.../uuid +Date: May 2015 +KernelVersion: 4.2 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Stores mei client device uuid + Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + +What: /sys/bus/mei/devices/.../version +Date: Aug 2015 +KernelVersion: 4.3 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Stores mei client protocol version + Format: %d
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci new file mode 100644 index 0000000..b3bc50f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -0,0 +1,296 @@ +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. + +What: /sys/bus/pci/devices/.../msi_bus +Date: September 2014 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + Writing a zero value to this attribute disallows MSI and + MSI-X for any future drivers of the device. If the device + is a bridge, MSI and MSI-X will be disallowed for future + drivers of all child devices under the bridge. Drivers + must be reloaded for the new setting to take effect. + +What: /sys/bus/pci/devices/.../msi_irqs/ +Date: September, 2011 +Contact: Neil Horman <nhorman@tuxdriver.com> +Description: + The /sys/devices/.../msi_irqs directory contains a variable set + of files, with each file being named after a corresponding msi + irq vector allocated to that device. + +What: /sys/bus/pci/devices/.../msi_irqs/<N> +Date: September 2011 +Contact: Neil Horman <nhorman@tuxdriver.com> +Description: + This attribute indicates the mode that the irq vector named by + the file is in (msi vs. msix) + +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. + +What: /sys/bus/pci/devices/.../pci_bus/.../rescan +Date: May 2011 +Contact: Linux PCI developers <linux-pci@vger.kernel.org> +Description: + Writing a non-zero value to this attribute will + force a rescan of the bus and all child buses, + and re-discover devices removed earlier from this + part of the device tree. + +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. + +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 <bwh@kernel.org> +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. + +What: /sys/bus/pci/devices/.../label +Date: July 2010 +Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com +Description: + Reading this attribute will provide the firmware + given name (SMBIOS type 41 string or ACPI _DSM string) of + the PCI device. The attribute will be created only + if the firmware has given a name to the PCI device. + ACPI _DSM string name will be given priority if the + system firmware provides SMBIOS type 41 string also. +Users: + Userspace applications interested in knowing the + firmware assigned name of the PCI device. + +What: /sys/bus/pci/devices/.../index +Date: July 2010 +Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com +Description: + Reading this attribute will provide the firmware + given instance (SMBIOS type 41 device type instance) of the + PCI device. The attribute will be created only if the firmware + has given an instance number to the PCI device. +Users: + Userspace applications interested in knowing the + firmware assigned device type instance of the PCI + device that can help in understanding the firmware + intended order of the PCI device. + +What: /sys/bus/pci/devices/.../acpi_index +Date: July 2010 +Contact: Narendra K <narendra_k@dell.com>, linux-bugs@dell.com +Description: + Reading this attribute will provide the firmware + given instance (ACPI _DSM instance number) of the PCI device. + The attribute will be created only if the firmware has given + an instance number to the PCI device. ACPI _DSM instance number + will be given priority if the system firmware provides SMBIOS + type 41 device type instance also. +Users: + Userspace applications interested in knowing the + firmware assigned instance number of the PCI + device that can help in understanding the firmware + intended order of the PCI device. + +What: /sys/bus/pci/devices/.../d3cold_allowed +Date: July 2012 +Contact: Huang Ying <ying.huang@intel.com> +Description: + d3cold_allowed is bit to control whether the corresponding PCI + device can be put into D3Cold state. If it is cleared, the + device will never be put into D3Cold state. If it is set, the + device may be put into D3Cold state if other requirements are + satisfied too. Reading this attribute will show the current + value of d3cold_allowed bit. Writing this attribute will set + the value of d3cold_allowed bit. + +What: /sys/bus/pci/devices/.../sriov_totalvfs +Date: November 2012 +Contact: Donald Dutile <ddutile@redhat.com> +Description: + This file appears when a physical PCIe device supports SR-IOV. + Userspace applications can read this file to determine the + maximum number of Virtual Functions (VFs) a PCIe physical + function (PF) can support. Typically, this is the value reported + in the PF's SR-IOV extended capability structure's TotalVFs + element. Drivers have the ability at probe time to reduce the + value read from this file via the pci_sriov_set_totalvfs() + function. + +What: /sys/bus/pci/devices/.../sriov_numvfs +Date: November 2012 +Contact: Donald Dutile <ddutile@redhat.com> +Description: + This file appears when a physical PCIe device supports SR-IOV. + Userspace applications can read and write to this file to + determine and control the enablement or disablement of Virtual + Functions (VFs) on the physical function (PF). A read of this + file will return the number of VFs that are enabled on this PF. + A number written to this file will enable the specified + number of VFs. A userspace application would typically read the + file and check that the value is zero, and then write the number + of VFs that should be enabled on the PF; the value written + should be less than or equal to the value in the sriov_totalvfs + file. A userspace application wanting to disable the VFs would + write a zero to this file. The core ensures that valid values + are written to this file, and returns errors when values are not + valid. For example, writing a 2 to this file when sriov_numvfs + is not 0 and not 2 already will return an error. Writing a 10 + when the value of sriov_totalvfs is 8 will return an error. + +What: /sys/bus/pci/devices/.../driver_override +Date: April 2014 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + This file allows the driver for a device to be specified which + will override standard static and dynamic ID matching. When + specified, only a driver with a name matching the value written + to driver_override will have an opportunity to bind to the + device. The override is specified by writing a string to the + driver_override file (echo pci-stub > driver_override) and + may be cleared with an empty string (echo > driver_override). + This returns the device to standard matching rules binding. + Writing to driver_override does not automatically unbind the + device from its current driver or make any attempt to + automatically load the specified driver. If no driver with a + matching name is currently loaded in the kernel, the device + will not bind to any driver. This also allows devices to + opt-out of driver binding using a driver_override name such as + "none". Only a single driver may be specified in the override, + there is no support for parsing delimiters. + +What: /sys/bus/pci/devices/.../numa_node +Date: Oct 2014 +Contact: Prarit Bhargava <prarit@redhat.com> +Description: + This file contains the NUMA node to which the PCI device is + attached, or -1 if the node is unknown. The initial value + comes from an ACPI _PXM method or a similar firmware + source. If that is missing or incorrect, this file can be + written to override the node. In that case, please report + a firmware bug to the system vendor. Writing to this file + taints the kernel with TAINT_FIRMWARE_WORKAROUND, which + reduces the supportability of your system.
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss new file mode 100644 index 0000000..53d99ed --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
@@ -0,0 +1,80 @@ +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. + +Where: /sys/bus/pci/devices/<dev>/ccissX/resettable +Date: February 2011 +Kernel Version: 2.6.38 +Contact: iss_storagedev@hp.com +Description: Value of 1 indicates the controller can honor the reset_devices + kernel parameter. Value of 0 indicates reset_devices cannot be + honored. This is to allow, for example, kexec tools to be able + to warn the user if they designate an unresettable device as + a dump device, as kdump requires resetting the device in order + to work reliably. + +Where: /sys/bus/pci/devices/<dev>/ccissX/transport_mode +Date: July 2011 +Kernel Version: 3.0 +Contact: iss_storagedev@hp.com +Description: Value of "simple" indicates that the controller has been placed + in "simple mode". Value of "performant" indicates that the + controller has been placed in "performant mode".
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd new file mode 100644 index 0000000..60c60fa --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
@@ -0,0 +1,46 @@ +What: /sys/bus/pci/drivers/ehci_hcd/.../companion + /sys/bus/usb/devices/usbN/../companion +Date: January 2007 +KernelVersion: 2.6.21 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + PCI-based EHCI USB controllers (i.e., high-speed USB-2.0 + controllers) are often implemented along with a set of + "companion" full/low-speed USB-1.1 controllers. When a + high-speed device is plugged in, the connection is routed + to the EHCI controller; when a full- or low-speed device + is plugged in, the connection is routed to the companion + controller. + + Sometimes you want to force a high-speed device to connect + at full speed, which can be accomplished by forcing the + connection to be routed to the companion controller. + That's what this file does. Writing a port number to the + file causes connections on that port to be routed to the + companion controller, and writing the negative of a port + number returns the port to normal operation. + + For example: To force the high-speed device attached to + port 4 on bus 2 to run at full speed: + + echo 4 >/sys/bus/usb/devices/usb2/../companion + + To return the port to high-speed operation: + + echo -4 >/sys/bus/usb/devices/usb2/../companion + + Reading the file gives the list of ports currently forced + to the companion controller. + + Note: Some EHCI controllers do not have companions; they + may contain an internal "transaction translator" or they + may be attached directly to a "rate-matching hub". This + mechanism will not work with such controllers. Also, it + cannot be used to force a port on a high-speed hub to + connect at full speed. + + Note: When this file was first added, it appeared in a + different sysfs directory. The location given above is + correct for 2.6.35 (and probably several earlier kernel + versions as well). +
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio b/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio new file mode 100644 index 0000000..4d08f28 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-janz-cmodio
@@ -0,0 +1,8 @@ +What: /sys/bus/pci/drivers/janz-cmodio/.../modulbus_number +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Ira W. Snyder <ira.snyder@gmail.com> +Description: + Value representing the HEX switch S2 of the janz carrier board CMOD-IO or CAN-PCI2 + + Read-only: value of the configuration switch (0..15)
diff --git a/Documentation/ABI/testing/sysfs-bus-platform b/Documentation/ABI/testing/sysfs-bus-platform new file mode 100644 index 0000000..5172a61 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-platform
@@ -0,0 +1,20 @@ +What: /sys/bus/platform/devices/.../driver_override +Date: April 2014 +Contact: Kim Phillips <kim.phillips@freescale.com> +Description: + This file allows the driver for a device to be specified which + will override standard OF, ACPI, ID table, and name matching. + When specified, only a driver with a name matching the value + written to driver_override will have an opportunity to bind + to the device. The override is specified by writing a string + to the driver_override file (echo vfio-platform > \ + driver_override) and may be cleared with an empty string + (echo > driver_override). This returns the device to standard + matching rules binding. Writing to driver_override does not + automatically unbind the device from its current driver or make + any attempt to automatically load the specified driver. If no + driver with a matching name is currently loaded in the kernel, + the device will not bind to any driver. This also allows + devices to opt-out of driver binding using a driver_override + name such as "none". Only a single driver may be specified in + the override, there is no support for parsing delimiters.
diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd new file mode 100644 index 0000000..f208ac5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-rbd
@@ -0,0 +1,121 @@ +What: /sys/bus/rbd/ +Date: November 2010 +Contact: Yehuda Sadeh <yehuda@newdream.net>, + Sage Weil <sage@newdream.net> +Description: + +Being used for adding and removing rbd block devices. + +Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>] + + $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add + +The snapshot name can be "-" or omitted to map the image read/write. A <dev-id> +will be assigned for any registered block device. If snapshot is used, it will +be mapped read-only. + +Usage: <dev-id> [force] + + $ echo 2 > /sys/bus/rbd/remove + +Optional "force" argument which when passed will wait for running requests and +then unmap the image. Requests sent to the driver after initiating the removal +will be failed. (August 2016, since 4.9.) + +What: /sys/bus/rbd/add_single_major +Date: December 2013 +KernelVersion: 3.14 +Contact: Sage Weil <sage@inktank.com> +Description: Available only if rbd module is inserted with single_major + parameter set to true. + Usage is the same as for /sys/bus/rbd/add. If present, + should be used instead of the latter: any attempts to use + /sys/bus/rbd/add if /sys/bus/rbd/add_single_major is + available will fail for backwards compatibility reasons. + +What: /sys/bus/rbd/remove_single_major +Date: December 2013 +KernelVersion: 3.14 +Contact: Sage Weil <sage@inktank.com> +Description: Available only if rbd module is inserted with single_major + parameter set to true. + Usage is the same as for /sys/bus/rbd/remove. If present, + should be used instead of the latter: any attempts to use + /sys/bus/rbd/remove if /sys/bus/rbd/remove_single_major is + available will fail for backwards compatibility reasons. + +Entries under /sys/bus/rbd/devices/<dev-id>/ +-------------------------------------------- + +client_addr + + The ceph unique client entity_addr_t (address + nonce). + The format is <address>:<port>/<nonce>: '1.2.3.4:1234/5678' or + '[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.) + +client_id + + The ceph unique client id that was assigned for this specific session. + +cluster_fsid + + The ceph cluster UUID. (August 2016, since 4.9.) + +config_info + + The string written into /sys/bus/rbd/add{,_single_major}. (August + 2016, since 4.9.) + +features + + A hexadecimal encoding of the feature bits for this image. + +major + + The block device major number. + +minor + + The block device minor number. (December 2013, since 3.14.) + +name + + The name of the rbd image. + +image_id + + The unique id for the rbd image. (For rbd image format 1 + this is empty.) + +pool + + The name of the storage pool where this rbd image resides. + An rbd image name is unique within its pool. + +pool_id + + The unique identifier for the rbd image's pool. This is + a permanent attribute of the pool. A pool's id will never + change. + +size + + The size (in bytes) of the mapped block device. + +refresh + + Writing to this file will reread the image header data and set + all relevant datastructures accordingly. + +current_snap + + The current snapshot for which the device is mapped. + +snap_id + + The current snapshot's id. (August 2016, since 4.9.) + +parent + + Information identifying the chain of parent images in a layered rbd + image. Entries are separated by empty lines.
diff --git a/Documentation/ABI/testing/sysfs-bus-rpmsg b/Documentation/ABI/testing/sysfs-bus-rpmsg new file mode 100644 index 0000000..189e419 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-rpmsg
@@ -0,0 +1,75 @@ +What: /sys/bus/rpmsg/devices/.../name +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels are identified with a (textual) name, + which is maximum 32 bytes long (defined as RPMSG_NAME_SIZE in + rpmsg.h). + + This sysfs entry contains the name of this channel. + +What: /sys/bus/rpmsg/devices/.../src +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels have a local ("source") rpmsg address, + and remote ("destination") rpmsg address. When an entity + starts listening on one end of a channel, it assigns it with + a unique rpmsg address (a 32 bits integer). This way when + inbound messages arrive to this address, the rpmsg core + dispatches them to the listening entity (a kernel driver). + + This sysfs entry contains the src (local) rpmsg address + of this channel. If it contains 0xffffffff, then an address + wasn't assigned (can happen if no driver exists for this + channel). + +What: /sys/bus/rpmsg/devices/.../dst +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels have a local ("source") rpmsg address, + and remote ("destination") rpmsg address. When an entity + starts listening on one end of a channel, it assigns it with + a unique rpmsg address (a 32 bits integer). This way when + inbound messages arrive to this address, the rpmsg core + dispatches them to the listening entity. + + This sysfs entry contains the dst (remote) rpmsg address + of this channel. If it contains 0xffffffff, then an address + wasn't assigned (can happen if the kernel driver that + is attached to this channel is exposing a service to the + remote processor. This make it a local rpmsg server, + and it is listening for inbound messages that may be sent + from any remote rpmsg client; it is not bound to a single + remote entity). + +What: /sys/bus/rpmsg/devices/.../announce +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels are identified by a textual name (see + /sys/bus/rpmsg/devices/.../name above) and have a local + ("source") rpmsg address, and remote ("destination") rpmsg + address. + + A channel is first created when an entity, whether local + or remote, starts listening on it for messages (and is thus + called an rpmsg server). + + When that happens, a "name service" announcement is sent + to the other processor, in order to let it know about the + creation of the channel (this way remote clients know they + can start sending messages). + + This sysfs entry tells us whether the channel is a local + server channel that is announced (values are either + true or false).
diff --git a/Documentation/ABI/testing/sysfs-bus-umc b/Documentation/ABI/testing/sysfs-bus-umc new file mode 100644 index 0000000..948fec4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-umc
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb new file mode 100644 index 0000000..0bd731c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -0,0 +1,228 @@ +What: /sys/bus/usb/devices/INTERFACE/authorized +Date: August 2015 +Description: + This allows to authorize (1) or deauthorize (0) + individual interfaces instead a whole device + in contrast to the device authorization. + If a deauthorized interface will be authorized + so the driver probing must be triggered manually + by writing INTERFACE to /sys/bus/usb/drivers_probe + This allows to avoid side-effects with drivers + that need multiple interfaces. + A deauthorized interface cannot be probed or claimed. + +What: /sys/bus/usb/devices/usbX/interface_authorized_default +Date: August 2015 +Description: + This is used as value that determines if interfaces + would be authorized by default. + The value can be 1 or 0. It's by default 1. + +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). + +What: /sys/bus/usb/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org +Description: + Writing a device ID to this file will attempt to + dynamically add a new device ID to a USB 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: + idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct + The vendor ID and device ID fields are required, the + rest is optional. The Ref* tuple can be used to tell the + driver to use the same driver_data for the new device as + it is used for the reference device. + 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/usb/drivers/foo/new_id + + Here add a new device (0458:7045) using driver_data from + an already supported device (0458:704c): + # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id + + Reading from this file will list all dynamically added + device IDs in the same format, with one entry per + line. For example: + # cat /sys/bus/usb/drivers/foo/new_id + 8086 10f5 + dead beef 06 + f00d cafe + + The list will be truncated at PAGE_SIZE bytes due to + sysfs restrictions. + +What: /sys/bus/usb-serial/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org +Description: + For serial USB drivers, this attribute appears under the + extra bus folder "usb-serial" in sysfs; apart from that + difference, all descriptions from the entry + "/sys/bus/usb/drivers/.../new_id" apply. + +What: /sys/bus/usb/drivers/.../remove_id +Date: November 2009 +Contact: CHENG Renquan <rqcheng@smu.edu.sg> +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: + idVendor idProduct. 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 "046d c315" > /sys/bus/usb/drivers/foo/remove_id + + Reading from this file will list the dynamically added + device IDs, exactly like reading from the entry + "/sys/bus/usb/drivers/.../new_id" + +What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm +Date: September 2011 +Contact: Andiry Xu <andiry.xu@amd.com> +Description: + If CONFIG_PM is set and a USB 2.0 lpm-capable device is plugged + in to a xHCI host which support link PM, it will perform a LPM + test; if the test is passed and host supports USB2 hardware LPM + (xHCI 1.0 feature), USB2 hardware LPM will be enabled for the + device and the USB device directory will contain a file named + power/usb2_hardware_lpm. The file holds a string value (enable + or disable) indicating whether or not USB2 hardware LPM is + enabled for the device. Developer can write y/Y/1 or n/N/0 to + the file to enable/disable the feature. + +What: /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u1 + /sys/bus/usb/devices/.../power/usb3_hardware_lpm_u2 +Date: November 2015 +Contact: Kevin Strasser <kevin.strasser@linux.intel.com> + Lu Baolu <baolu.lu@linux.intel.com> +Description: + If CONFIG_PM is set and a USB 3.0 lpm-capable device is plugged + in to a xHCI host which supports link PM, it will check if U1 + and U2 exit latencies have been set in the BOS descriptor; if + the check is passed and the host supports USB3 hardware LPM, + USB3 hardware LPM will be enabled for the device and the USB + device directory will contain two files named + power/usb3_hardware_lpm_u1 and power/usb3_hardware_lpm_u2. These + files hold a string value (enable or disable) indicating whether + or not USB3 hardware LPM U1 or U2 is enabled for the device. + +What: /sys/bus/usb/devices/.../removable +Date: February 2012 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + Some information about whether a given USB device is + physically fixed to the platform can be inferred from a + combination of hub descriptor bits and platform-specific data + such as ACPI. This file will read either "removable" or + "fixed" if the information is available, and "unknown" + otherwise. + +What: /sys/bus/usb/devices/.../ltm_capable +Date: July 2012 +Contact: Sarah Sharp <sarah.a.sharp@linux.intel.com> +Description: + USB 3.0 devices may optionally support Latency Tolerance + Messaging (LTM). They indicate their support by setting a bit + in the bmAttributes field of their SuperSpeed BOS descriptors. + If that bit is set for the device, ltm_capable will read "yes". + If the device doesn't support LTM, the file will read "no". + The file will be present for all speeds of USB devices, and will + always read "no" for USB 1.1 and USB 2.0 devices. + +What: /sys/bus/usb/devices/.../(hub interface)/portX +Date: August 2012 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + The /sys/bus/usb/devices/.../(hub interface)/portX + is usb port device's sysfs directory. + +What: /sys/bus/usb/devices/.../(hub interface)/portX/connect_type +Date: January 2013 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + Some platforms provide usb port connect types through ACPI. + This attribute is to expose these information to user space. + The file will read "hotplug", "wired" and "not used" if the + information is available, and "unknown" otherwise. + +What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit +Date: November 2015 +Contact: Lu Baolu <baolu.lu@linux.intel.com> +Description: + Some USB3.0 devices are not friendly to USB3 LPM. usb3_lpm_permit + attribute allows enabling/disabling usb3 lpm of a port. It takes + effect both before and after a usb device is enumerated. Supported + values are "0" if both u1 and u2 are NOT permitted, "u1" if only u1 + is permitted, "u2" if only u2 is permitted, "u1_u2" if both u1 and + u2 are permitted. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices may support hardware link power management (LPM) + L1 sleep state. The usb2_lpm_l1_timeout attribute allows + tuning the timeout for L1 inactivity timer (LPM timer), e.g. + needed inactivity time before host requests the device to go to L1 sleep. + Useful for power management tuning. + Supported values are 0 - 65535 microseconds. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_besl +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices that support hardware link power management (LPM) + L1 sleep state now use a best effort service latency value (BESL) to + indicate the best effort to resumption of service to the device after the + initiation of the resume event. + If the device does not have a preferred besl value then the host can select + one instead. This usb2_lpm_besl attribute allows to tune the host selected besl + value in order to tune power saving and service latency. + + Supported values are 0 - 15. + More information on how besl values map to microseconds can be found in + USB 2.0 ECN Errata for Link Power Management, section 4.10)
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg new file mode 100644 index 0000000..70d00df --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-lvstest b/Documentation/ABI/testing/sysfs-bus-usb-lvstest new file mode 100644 index 0000000..5151290 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-usb-lvstest
@@ -0,0 +1,47 @@ +Link Layer Validation Device is a standard device for testing of Super +Speed Link Layer tests. These nodes are available in sysfs only when lvs +driver is bound with root hub device. + +What: /sys/bus/usb/devices/.../get_dev_desc +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Write to this node to issue "Get Device Descriptor" + for Link Layer Validation device. It is needed for TD.7.06. + +What: /sys/bus/usb/devices/.../u1_timeout +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Set "U1 timeout" for the downstream port where Link Layer + Validation device is connected. Timeout value must be between 0 + and 127. It is needed for TD.7.18, TD.7.19, TD.7.20 and TD.7.21. + +What: /sys/bus/usb/devices/.../u2_timeout +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Set "U2 timeout" for the downstream port where Link Layer + Validation device is connected. Timeout value must be between 0 + and 127. It is needed for TD.7.18, TD.7.19, TD.7.20 and TD.7.21. + +What: /sys/bus/usb/devices/.../hot_reset +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Write to this node to issue "Reset" for Link Layer Validation + device. It is needed for TD.7.29, TD.7.31, TD.7.34 and TD.7.35. + +What: /sys/bus/usb/devices/.../u3_entry +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Write to this node to issue "U3 entry" for Link Layer + Validation device. It is needed for TD.7.35 and TD.7.36. + +What: /sys/bus/usb/devices/.../u3_exit +Date: March 2014 +Contact: Pratyush Anand <pratyush.anand@gmail.com> +Description: + Write to this node to issue "U3 exit" for Link Layer + Validation device. It is needed for TD.7.36.
diff --git a/Documentation/ABI/testing/sysfs-c2port b/Documentation/ABI/testing/sysfs-c2port new file mode 100644 index 0000000..716cffc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-c2port
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-cfq-target-latency b/Documentation/ABI/testing/sysfs-cfq-target-latency new file mode 100644 index 0000000..df0f782 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-cfq-target-latency
@@ -0,0 +1,8 @@ +What: /sys/block/<device>/iosched/target_latency +Date: March 2012 +contact: Tao Ma <boyu.mt@taobao.com> +Description: + The /sys/block/<device>/iosched/target_latency only exists + when the user sets cfq to /sys/block/<device>/scheduler. + It contains an estimated latency time for the cfq. cfq will + use it to calculate the time slice used for every task.
diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class new file mode 100644 index 0000000..676530f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class
@@ -0,0 +1,16 @@ +What: /sys/class/ +Date: Febuary 2006 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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>
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 new file mode 100644 index 0000000..33e6488 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
@@ -0,0 +1,56 @@ +What: /sys/class/backlight/<backlight>/<ambient light zone>_max +What: /sys/class/backlight/<backlight>/l1_daylight_max +What: /sys/class/backlight/<backlight>/l2_bright_max +What: /sys/class/backlight/<backlight>/l3_office_max +What: /sys/class/backlight/<backlight>/l4_indoor_max +What: /sys/class/backlight/<backlight>/l5_dark_max +Date: May 2011 +KernelVersion: 3.0 +Contact: device-drivers-devel@blackfin.uclinux.org +Description: + Control the maximum brightness for <ambient light zone> + on this <backlight>. Values are between 0 and 127. This file + will also show the brightness level stored for this + <ambient light zone>. + +What: /sys/class/backlight/<backlight>/<ambient light zone>_dim +What: /sys/class/backlight/<backlight>/l2_bright_dim +What: /sys/class/backlight/<backlight>/l3_office_dim +What: /sys/class/backlight/<backlight>/l4_indoor_dim +What: /sys/class/backlight/<backlight>/l5_dark_dim +Date: May 2011 +KernelVersion: 3.0 +Contact: device-drivers-devel@blackfin.uclinux.org +Description: + Control the dim brightness for <ambient light zone> + on this <backlight>. Values are between 0 and 127, typically + set to 0. Full off when the backlight is disabled. + This file will also show the dim brightness level stored for + this <ambient light zone>. + +What: /sys/class/backlight/<backlight>/ambient_light_level +Date: May 2011 +KernelVersion: 3.0 +Contact: device-drivers-devel@blackfin.uclinux.org +Description: + Get conversion value of the light sensor. + This value is updated every 80 ms (when the light sensor + is enabled). Returns integer between 0 (dark) and + 8000 (max ambient brightness) + +What: /sys/class/backlight/<backlight>/ambient_light_zone +Date: May 2011 +KernelVersion: 3.0 +Contact: device-drivers-devel@blackfin.uclinux.org +Description: + Get/Set current ambient light zone. Reading returns + integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark). + Writing a value between 1..5 forces the backlight controller + to enter the corresponding ambient light zone. + Writing 0 returns to normal/automatic ambient light level + operation. The ambient light sensing feature on these devices + is an extension to the API documented in + Documentation/ABI/stable/sysfs-class-backlight. + It can be enabled by writing the value stored in + /sys/class/backlight/<backlight>/max_brightness to + /sys/class/backlight/<backlight>/brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 new file mode 100644 index 0000000..77cf7ac --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
@@ -0,0 +1,48 @@ +What: /sys/class/backlight/<backlight>/als_channel +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the ALS output channel used as input in + ALS-current-control mode (0, 1), where + + 0 - out_current0 (backlight 0) + 1 - out_current1 (backlight 1) + +What: /sys/class/backlight/<backlight>/als_en +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Enable ALS-current-control mode (0, 1). + +What: /sys/class/backlight/<backlight>/id +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the id of this backlight (0, 1). + +What: /sys/class/backlight/<backlight>/linear +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the brightness-mapping mode (0, 1), where + + 0 - exponential mode + 1 - linear mode + +What: /sys/class/backlight/<backlight>/pwm +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the PWM-input control mask (5 bits), where + + bit 5 - PWM-input enabled in Zone 4 + bit 4 - PWM-input enabled in Zone 3 + bit 3 - PWM-input enabled in Zone 2 + bit 2 - PWM-input enabled in Zone 1 + bit 1 - PWM-input enabled in Zone 0 + bit 0 - PWM-input enabled
diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi new file mode 100644 index 0000000..d773d56 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-bdi
@@ -0,0 +1,55 @@ +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. + +stable_pages_required (read-only) + + If set, the backing device requires that all pages comprising a write + request must not be changed until writeout is complete.
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl new file mode 100644 index 0000000..640f65e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -0,0 +1,246 @@ +Note: Attributes that are shared between devices are stored in the directory +pointed to by the symlink device/. +Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is +/sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max. + + +Slave contexts (eg. /sys/class/cxl/afu0.0s): + +What: /sys/class/cxl/<afu>/afu_err_buf +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + AFU Error Buffer contents. The contents of this file are + application specific and depends on the AFU being used. + Applications interacting with the AFU can use this attribute + to know about the current error condition and take appropriate + action like logging the event etc. + + +What: /sys/class/cxl/<afu>/irqs_max +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Decimal value of maximum number of interrupts that can be + requested by userspace. The default on probe is the maximum + that hardware can support (eg. 2037). Write values will limit + userspace applications to that many userspace interrupts. Must + be >= irqs_min. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/irqs_min +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the minimum number of interrupts that + userspace must request on a CXL_START_WORK ioctl. Userspace may + omit the num_interrupts field in the START_WORK IOCTL to get + this minimum automatically. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/mmio_size +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the size of the MMIO space that may be mmaped + by userspace. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/modes_supported +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + List of the modes this AFU supports. One per line. + Valid entries are: "dedicated_process" and "afu_directed" +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/mode +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + The current mode the AFU is using. Will be one of the modes + given in modes_supported. Writing will change the mode + provided that no user contexts are attached. +Users: https://github.com/ibm-capi/libcxl + + +What: /sys/class/cxl/<afu>/prefault_mode +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Set the mode for prefaulting in segments into the segment table + when performing the START_WORK ioctl. Possible values: + none: No prefaulting (default) + work_element_descriptor: Treat the work element + descriptor as an effective address and + prefault what it points to. + all: all segments process calling START_WORK maps. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/reset +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: write only + Writing 1 here will reset the AFU provided there are not + contexts active on the AFU. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/api_version +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the current version of the kernel/user API. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/api_version_compatible +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the the lowest version of the userspace API + this this kernel supports. +Users: https://github.com/ibm-capi/libcxl + + +AFU configuration records (eg. /sys/class/cxl/afu0.0/cr0): + +An AFU may optionally export one or more PCIe like configuration records, known +as AFU configuration records, which will show up here (if present). + +What: /sys/class/cxl/<afu>/cr<config num>/vendor +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the vendor ID found in this AFU + configuration record. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/cr<config num>/device +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the device ID found in this AFU + configuration record. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/cr<config num>/class +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Hexadecimal value of the class code found in this AFU + configuration record. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>/cr<config num>/config +Date: February 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + This binary file provides raw access to the AFU configuration + record. The format is expected to match the either the standard + or extended configuration space defined by the PCIe + specification. +Users: https://github.com/ibm-capi/libcxl + + + +Master contexts (eg. /sys/class/cxl/afu0.0m) + +What: /sys/class/cxl/<afu>m/mmio_size +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the size of the MMIO space that may be mmaped + by userspace. This includes all slave contexts space also. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>m/pp_mmio_len +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the Per Process MMIO space length. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<afu>m/pp_mmio_off (not in a guest) +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Decimal value of the Per Process MMIO space offset. +Users: https://github.com/ibm-capi/libcxl + + +Card info (eg. /sys/class/cxl/card0) + +What: /sys/class/cxl/<card>/caia_version +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the CAIA Version the card implements. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/psl_revision +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the revision level of the PSL. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/base_image (not in a guest) +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Identifies the revision level of the base image for devices + that support loadable PSLs. For FPGAs this field identifies + the image contained in the on-adapter flash which is loaded + during the initial program load. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/image_loaded (not in a guest) +Date: September 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Will return "user" or "factory" depending on the image loaded + onto the card. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/load_image_on_perst (not in a guest) +Date: December 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Valid entries are "none", "user", and "factory". + "none" means PERST will not cause image to be loaded to the + card. A power cycle is required to load the image. + "none" could be useful for debugging because the trace arrays + are preserved. + "user" and "factory" means PERST will cause either the user or + user or factory image to be loaded. + Default is to reload on PERST whichever image the card has + loaded. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/reset +Date: October 2014 +Contact: linuxppc-dev@lists.ozlabs.org +Description: write only + Writing 1 will issue a PERST to card provided there are no + contexts active on any one of the card AFUs. This may cause + the card to reload the FPGA depending on load_image_on_perst. + Writing -1 will do a force PERST irrespective of any active + contexts on the card AFUs. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/perst_reloads_same_image (not in a guest) +Date: July 2015 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read/write + Trust that when an image is reloaded via PERST, it will not + have changed. + 0 = don't trust, the image may be different (default) + 1 = trust that the image will not change. +Users: https://github.com/ibm-capi/libcxl + +What: /sys/class/cxl/<card>/psl_timebase_synced +Date: March 2016 +Contact: linuxppc-dev@lists.ozlabs.org +Description: read only + Returns 1 if the psl timebase register is synchronized + with the core timebase register, 0 otherwise. +Users: https://github.com/ibm-capi/libcxl
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq new file mode 100644 index 0000000..ee39aca --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -0,0 +1,100 @@ +What: /sys/class/devfreq/.../ +Date: September 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + Provide a place in sysfs for the devfreq objects. + This allows accessing various devfreq specific variables. + The name of devfreq object denoted as ... is same as the + name of device using devfreq. + +What: /sys/class/devfreq/.../governor +Date: September 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../governor show or set the name of the + governor used by the corresponding devfreq object. + +What: /sys/class/devfreq/.../cur_freq +Date: September 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../cur_freq shows the current + frequency of the corresponding devfreq object. Same as + target_freq when get_cur_freq() is not implemented by + devfreq driver. + +What: /sys/class/devfreq/.../target_freq +Date: September 2012 +Contact: Rajagopal Venkat <rajagopal.venkat@linaro.org> +Description: + The /sys/class/devfreq/.../target_freq shows the next governor + predicted target frequency of the corresponding devfreq object. + +What: /sys/class/devfreq/.../polling_interval +Date: September 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../polling_interval shows and sets + the requested polling interval of the corresponding devfreq + object. The values are represented in ms. If the value is + less than 1 jiffy, it is considered to be 0, which means + no polling. This value is meaningless if the governor is + not polling; thus. If the governor is not using + devfreq-provided central polling + (/sys/class/devfreq/.../central_polling is 0), this value + may be useless. + +What: /sys/class/devfreq/.../trans_stat +Date: October 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Descrtiption: + This ABI shows the statistics of devfreq behavior on a + specific device. It shows the time spent in each state and + the number of transitions between states. + In order to activate this ABI, the devfreq target device + driver should provide the list of available frequencies + with its profile. + +What: /sys/class/devfreq/.../userspace/set_freq +Date: September 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../userspace/set_freq shows and + sets the requested frequency for the devfreq object if + userspace governor is in effect. + +What: /sys/class/devfreq/.../available_frequencies +Date: October 2012 +Contact: Nishanth Menon <nm@ti.com> +Description: + The /sys/class/devfreq/.../available_frequencies shows + the available frequencies of the corresponding devfreq object. + This is a snapshot of available frequencies and not limited + by the min/max frequency restrictions. + +What: /sys/class/devfreq/.../available_governors +Date: October 2012 +Contact: Nishanth Menon <nm@ti.com> +Description: + The /sys/class/devfreq/.../available_governors shows + currently available governors in the system. + +What: /sys/class/devfreq/.../min_freq +Date: January 2013 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../min_freq shows and stores + the minimum frequency requested by users. It is 0 if + the user does not care. min_freq overrides the + frequency requested by governors. + +What: /sys/class/devfreq/.../max_freq +Date: January 2013 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../max_freq shows and stores + the maximum frequency requested by users. It is 0 if + the user does not care. max_freq overrides the + frequency requested by governors and min_freq. + The max_freq overrides min_freq because max_freq may be + used to throttle devices to avoid overheating.
diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon new file mode 100644 index 0000000..57a7262 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-extcon
@@ -0,0 +1,97 @@ +What: /sys/class/extcon/.../ +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + Provide a place in sysfs for the extcon objects. + This allows accessing extcon specific variables. + The name of extcon object denoted as ... is the name given + with extcon_dev_register. + + One extcon device denotes a single external connector + port. An external connector may have multiple cables + attached simultaneously. Many of docks, cradles, and + accessory cables have such capability. For example, + the 30-pin port of Nuri board (/arch/arm/mach-exynos) + may have both HDMI and Charger attached, or analog audio, + video, and USB cables attached simultaneously. + + If there are cables mutually exclusive with each other, + such binary relations may be expressed with extcon_dev's + mutually_exclusive array. + +What: /sys/class/extcon/.../name +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../name shows the name of the extcon + object. If the extcon object has an optional callback + "show_name" defined, the callback will provide the name with + this sysfs node. + +What: /sys/class/extcon/.../state +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../state shows and stores the cable + attach/detach information of the corresponding extcon object. + If the extcon object has an optional callback "show_state" + defined, the showing function is overridden with the optional + callback. + + If the default callback for showing function is used, the + format is like this: + # cat state + USB_OTG=1 + HDMI=0 + TA=1 + EAR_JACK=0 + # + In this example, the extcon device has USB_OTG and TA + cables attached and HDMI and EAR_JACK cables detached. + + In order to update the state of an extcon device, enter a hex + state number starting with 0x: + # echo 0xHEX > state + + This updates the whole state of the extcon device. + Inputs of all the methods are required to meet the + mutually_exclusive conditions if they exist. + + It is recommended to use this "global" state interface if + you need to set the value atomically. The later state + interface associated with each cable cannot update + multiple cable states of an extcon device simultaneously. + +What: /sys/class/extcon/.../cable.x/name +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../cable.x/name shows the name of cable + "x" (integer between 0 and 31) of an extcon device. + +What: /sys/class/extcon/.../cable.x/state +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../cable.x/state shows and stores the + state of cable "x" (integer between 0 and 31) of an extcon + device. The state value is either 0 (detached) or 1 + (attached). + +What: /sys/class/extcon/.../mutually_exclusive/... +Date: December 2011 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + Shows the relations of mutually exclusiveness. For example, + if the mutually_exclusive array of extcon device is + {0x3, 0x5, 0xC, 0x0}, then the output is: + # ls mutually_exclusive/ + 0x3 + 0x5 + 0xc + # + + Note that mutually_exclusive is a sub-directory of the extcon + device and the file names under the mutually_exclusive + directory show the mutually-exclusive sets, not the contents + of the files.
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-manager b/Documentation/ABI/testing/sysfs-class-fpga-manager new file mode 100644 index 0000000..23056c5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-fpga-manager
@@ -0,0 +1,37 @@ +What: /sys/class/fpga_manager/<fpga>/name +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <atull@opensource.altera.com> +Description: Name of low level fpga manager driver. + +What: /sys/class/fpga_manager/<fpga>/state +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <atull@opensource.altera.com> +Description: Read fpga manager state as a string. + The intent is to provide enough detail that if something goes + wrong during FPGA programming (something that the driver can't + fix) then userspace can know, i.e. if the firmware request + fails, that could be due to not being able to find the firmware + file. + + This is a superset of FPGA states and fpga manager driver + states. The fpga manager driver is walking through these steps + to get the FPGA into a known operating state. It's a sequence, + though some steps may get skipped. Valid FPGA states will vary + by manufacturer; this is a superset. + + * unknown = can't determine state + * power off = FPGA power is off + * power up = FPGA reports power is up + * reset = FPGA held in reset state + * firmware request = firmware class request in progress + * firmware request error = firmware request failed + * write init = preparing FPGA for programming + * write init error = Error while preparing FPGA for + programming + * write = FPGA ready to receive image data + * write error = Error while programming + * write complete = Doing post programming steps + * write complete error = Error while doing post programming + * operating = FPGA is programmed and operating
diff --git a/Documentation/ABI/testing/sysfs-class-infiniband b/Documentation/ABI/testing/sysfs-class-infiniband new file mode 100644 index 0000000..a86abe6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-infiniband
@@ -0,0 +1,16 @@ +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/ndevs/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The net-device's name associated with the GID resides + at index <gid-index>. + +What: /sys/class/infiniband/<hca>/ports/<port-number>/gid_attrs/types/<gid-index> +Date: November 29, 2015 +KernelVersion: 4.4.0 +Contact: linux-rdma@vger.kernel.org +Description: The RoCE type of the associated GID resides at index <gid-index>. + This could either be "IB/RoCE v1" for IB and RoCE v1 based GODs + or "RoCE v2" for RoCE v2 based GIDs. + +
diff --git a/Documentation/ABI/testing/sysfs-class-iommu b/Documentation/ABI/testing/sysfs-class-iommu new file mode 100644 index 0000000..6d0a1b4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-iommu
@@ -0,0 +1,17 @@ +What: /sys/class/iommu/<iommu>/devices/ +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + IOMMU drivers are able to link devices managed by a + given IOMMU here to allow association of IOMMU to + device. + +What: /sys/devices/.../iommu +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + IOMMU drivers are able to link the IOMMU for a + given device here to allow association of device to + IOMMU.
diff --git a/Documentation/ABI/testing/sysfs-class-iommu-amd-iommu b/Documentation/ABI/testing/sysfs-class-iommu-amd-iommu new file mode 100644 index 0000000..d6ba8e8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-iommu-amd-iommu
@@ -0,0 +1,14 @@ +What: /sys/class/iommu/<iommu>/amd-iommu/cap +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + IOMMU capability header as documented in the AMD IOMMU + specification. Format: %x + +What: /sys/class/iommu/<iommu>/amd-iommu/features +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + Extended features of the IOMMU. Format: %llx
diff --git a/Documentation/ABI/testing/sysfs-class-iommu-intel-iommu b/Documentation/ABI/testing/sysfs-class-iommu-intel-iommu new file mode 100644 index 0000000..258cc24 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-iommu-intel-iommu
@@ -0,0 +1,32 @@ +What: /sys/class/iommu/<iommu>/intel-iommu/address +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + Physical address of the VT-d DRHD for this IOMMU. + Format: %llx. This allows association of a sysfs + intel-iommu with a DMAR DRHD table entry. + +What: /sys/class/iommu/<iommu>/intel-iommu/cap +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + The cached hardware capability register value + of this DRHD unit. Format: %llx. + +What: /sys/class/iommu/<iommu>/intel-iommu/ecap +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + The cached hardware extended capability register + value of this DRHD unit. Format: %llx. + +What: /sys/class/iommu/<iommu>/intel-iommu/version +Date: June 2014 +KernelVersion: 3.17 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: + The architecture version as reported from the + VT-d VER_REG. Format: %d:%d, major:minor
diff --git a/Documentation/ABI/testing/sysfs-class-lcd b/Documentation/ABI/testing/sysfs-class-lcd new file mode 100644 index 0000000..35906bf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-lcd
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led new file mode 100644 index 0000000..86ace28 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led
@@ -0,0 +1,38 @@ +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. For + their documentation see sysfs-class-led-trigger-*. + +What: /sys/class/leds/<led>/inverted +Date: January 2011 +KernelVersion: 2.6.38 +Contact: Richard Purdie <rpurdie@rpsys.net> +Description: + Invert the LED on/off state. This parameter is specific to + gpio and backlight triggers. In case of the backlight trigger, + it is useful when driving a LED which is intended to indicate + a device in a standby like state.
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 new file mode 100644 index 0000000..620ebb3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
@@ -0,0 +1,65 @@ +What: /sys/class/leds/<led>/als_channel +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the ALS output channel to use as input in + ALS-current-control mode (1, 2), where + + 1 - out_current1 + 2 - out_current2 + +What: /sys/class/leds/<led>/als_en +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Enable ALS-current-control mode (0, 1). + +What: /sys/class/leds/<led>/falltime +What: /sys/class/leds/<led>/risetime +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the pattern generator fall and rise times (0..7), where + + 0 - 2048 us + 1 - 262 ms + 2 - 524 ms + 3 - 1.049 s + 4 - 2.097 s + 5 - 4.194 s + 6 - 8.389 s + 7 - 16.78 s + +What: /sys/class/leds/<led>/id +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the id of this led (0..3). + +What: /sys/class/leds/<led>/linear +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the brightness-mapping mode (0, 1), where + + 0 - exponential mode + 1 - linear mode + +What: /sys/class/leds/<led>/pwm +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the PWM-input control mask (5 bits), where + + bit 5 - PWM-input enabled in Zone 4 + bit 4 - PWM-input enabled in Zone 3 + bit 3 - PWM-input enabled in Zone 2 + bit 2 - PWM-input enabled in Zone 1 + bit 1 - PWM-input enabled in Zone 0 + bit 0 - PWM-input enabled
diff --git a/Documentation/ABI/testing/sysfs-class-led-flash b/Documentation/ABI/testing/sysfs-class-led-flash new file mode 100644 index 0000000..220a027 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-flash
@@ -0,0 +1,80 @@ +What: /sys/class/leds/<led>/flash_brightness +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read/write + Set the brightness of this LED in the flash strobe mode, in + microamperes. The file is created only for the flash LED devices + that support setting flash brightness. + + The value is between 0 and + /sys/class/leds/<led>/max_flash_brightness. + +What: /sys/class/leds/<led>/max_flash_brightness +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read only + Maximum brightness level for this LED in the flash strobe mode, + in microamperes. + +What: /sys/class/leds/<led>/flash_timeout +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read/write + Hardware timeout for flash, in microseconds. The flash strobe + is stopped after this period of time has passed from the start + of the strobe. The file is created only for the flash LED + devices that support setting flash timeout. + +What: /sys/class/leds/<led>/max_flash_timeout +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read only + Maximum flash timeout for this LED, in microseconds. + +What: /sys/class/leds/<led>/flash_strobe +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read/write + Flash strobe state. When written with 1 it triggers flash strobe + and when written with 0 it turns the flash off. + + On read 1 means that flash is currently strobing and 0 means + that flash is off. + +What: /sys/class/leds/<led>/flash_fault +Date: March 2015 +KernelVersion: 4.0 +Contact: Jacek Anaszewski <j.anaszewski@samsung.com> +Description: read only + Space separated list of flash faults that may have occurred. + Flash faults are re-read after strobing the flash. Possible + flash faults: + + * led-over-voltage - flash controller voltage to the flash LED + has exceeded the limit specific to the flash controller + * flash-timeout-exceeded - the flash strobe was still on when + the timeout set by the user has expired; not all flash + controllers may set this in all such conditions + * controller-over-temperature - the flash controller has + overheated + * controller-short-circuit - the short circuit protection + of the flash controller has been triggered + * led-power-supply-over-current - current in the LED power + supply has exceeded the limit specific to the flash + controller + * indicator-led-fault - the flash controller has detected + a short or open circuit condition on the indicator LED + * led-under-voltage - flash controller voltage to the flash + LED has been below the minimum limit specific to + the flash + * controller-under-voltage - the input voltage of the flash + controller is below the limit under which strobing the + flash at full current will not be possible; + the condition persists until this flag is no longer set + * led-over-temperature - the temperature of the LED has exceeded + its allowed upper limit
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot new file mode 100644 index 0000000..378a3a4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
@@ -0,0 +1,36 @@ +What: /sys/class/leds/<led>/delay_on +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Specifies for how many milliseconds the LED has to stay at + LED_FULL brightness after it has been armed. + Defaults to 100 ms. + +What: /sys/class/leds/<led>/delay_off +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Specifies for how many milliseconds the LED has to stay at + LED_OFF brightness after it has been armed. + Defaults to 100 ms. + +What: /sys/class/leds/<led>/invert +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Reverse the blink logic. If set to 0 (default) blink on for + delay_on ms, then blink off for delay_off ms, leaving the LED + normally off. If set to 1, blink off for delay_off ms, then + blink on for delay_on ms, leaving the LED normally on. + Setting this value also immediately changes the LED state. + +What: /sys/class/leds/<led>/shot +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Write any non-empty string to signal an events, this starts a + blink sequence if not already running.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport new file mode 100644 index 0000000..f440e69 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
@@ -0,0 +1,12 @@ +What: /sys/class/leds/<led>/ports/<port> +Date: September 2016 +KernelVersion: 4.9 +Contact: linux-leds@vger.kernel.org + linux-usb@vger.kernel.org +Description: + Every dir entry represents a single USB port that can be + selected for the USB port trigger. Selecting ports makes trigger + observing them for any connected devices and lighting on LED if + there are any. + Echoing "1" value selects USB port. Echoing "0" unselects it. + Current state can be also read.
diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r b/Documentation/ABI/testing/sysfs-class-leds-gt683r new file mode 100644 index 0000000..e4fae60 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r
@@ -0,0 +1,16 @@ +What: /sys/class/leds/<led>/gt683r/mode +Date: Jun 2014 +KernelVersion: 3.17 +Contact: Janne Kanniainen <janne.kanniainen@gmail.com> +Description: + Set the mode of LEDs. You should notice that changing the mode + of one LED will update the mode of its two sibling devices as + well. + + 0 - normal + 1 - audio + 2 - breathing + + Normal: LEDs are fully on when enabled + Audio: LEDs brightness depends on sound level + Breathing: LEDs brightness varies at human breathing rate \ No newline at end of file
diff --git a/Documentation/ABI/testing/sysfs-class-mei b/Documentation/ABI/testing/sysfs-class-mei new file mode 100644 index 0000000..80d9888 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-mei
@@ -0,0 +1,31 @@ +What: /sys/class/mei/ +Date: May 2014 +KernelVersion: 3.17 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: + The mei/ class sub-directory belongs to mei device class + + +What: /sys/class/mei/meiN/ +Date: May 2014 +KernelVersion: 3.17 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: + The /sys/class/mei/meiN directory is created for + each probed mei device + +What: /sys/class/mei/meiN/fw_status +Date: Nov 2014 +KernelVersion: 3.19 +Contact: Tomas Winkler <tomas.winkler@intel.com> +Description: Display fw status registers content + + The ME FW writes its status information into fw status + registers for BIOS and OS to monitor fw health. + + The register contains running state, power management + state, error codes, and others. The way the registers + are decoded depends on PCH or SoC generation. + Also number of registers varies between 1 and 6 + depending on generation. +
diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic.txt new file mode 100644 index 0000000..6ef6826 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-mic.txt
@@ -0,0 +1,166 @@ +What: /sys/class/mic/ +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + The mic class directory belongs to Intel MIC devices and + provides information per MIC device. An Intel MIC device is a + PCIe form factor add-in Coprocessor card based on the Intel Many + Integrated Core (MIC) architecture that runs a Linux OS. + +What: /sys/class/mic/mic(x) +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + The directories /sys/class/mic/mic0, /sys/class/mic/mic1 etc., + represent MIC devices (0,1,..etc). Each directory has + information specific to that MIC device. + +What: /sys/class/mic/mic(x)/family +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + Provides information about the Coprocessor family for an Intel + MIC device. For example - "x100" + +What: /sys/class/mic/mic(x)/stepping +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + Provides information about the silicon stepping for an Intel + MIC device. For example - "A0" or "B0" + +What: /sys/class/mic/mic(x)/state +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + When read, this entry provides the current state of an Intel + MIC device in the context of the card OS. Possible values that + will be read are: + "ready" - The MIC device is ready to boot the card OS. On + reading this entry after an OSPM resume, a "boot" has to be + written to this entry if the card was previously shutdown + during OSPM suspend. + "booting" - The MIC device has initiated booting a card OS. + "online" - The MIC device has completed boot and is online + "shutting_down" - The card OS is shutting down. + "resetting" - A reset has been initiated for the MIC device + "reset_failed" - The MIC device has failed to reset. + + When written, this sysfs entry triggers different state change + operations depending upon the current state of the card OS. + Acceptable values are: + "boot" - Boot the card OS image specified by the combination + of firmware, ramdisk, cmdline and bootmode + sysfs entries. + "reset" - Initiates device reset. + "shutdown" - Initiates card OS shutdown. + +What: /sys/class/mic/mic(x)/shutdown_status +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + An Intel MIC device runs a Linux OS during its operation. This + OS can shutdown because of various reasons. When read, this + entry provides the status on why the card OS was shutdown. + Possible values are: + "nop" - shutdown status is not applicable, when the card OS is + "online" + "crashed" - Shutdown because of a HW or SW crash. + "halted" - Shutdown because of a halt command. + "poweroff" - Shutdown because of a poweroff command. + "restart" - Shutdown because of a restart command. + +What: /sys/class/mic/mic(x)/cmdline +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + An Intel MIC device runs a Linux OS during its operation. Before + booting this card OS, it is possible to pass kernel command line + options to configure various features in it, similar to + self-bootable machines. When read, this entry provides + information about the current kernel command line options set to + boot the card OS. This entry can be written to change the + existing kernel command line options. Typically, the user would + want to read the current command line options, append new ones + or modify existing ones and then write the whole kernel command + line back to this entry. + +What: /sys/class/mic/mic(x)/firmware +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + When read, this sysfs entry provides the path name under + /lib/firmware/ where the firmware image to be booted on the + card can be found. The entry can be written to change the + firmware image location under /lib/firmware/. + +What: /sys/class/mic/mic(x)/ramdisk +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + When read, this sysfs entry provides the path name under + /lib/firmware/ where the ramdisk image to be used during card + OS boot can be found. The entry can be written to change + the ramdisk image location under /lib/firmware/. + +What: /sys/class/mic/mic(x)/bootmode +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + When read, this sysfs entry provides the current bootmode for + the card. This sysfs entry can be written with the following + valid strings: + a) linux - Boot a Linux image. + b) flash - Boot an image for flash updates. + +What: /sys/class/mic/mic(x)/log_buf_addr +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + An Intel MIC device runs a Linux OS during its operation. For + debugging purpose and early kernel boot messages, the user can + access the card OS log buffer via debugfs. When read, this entry + provides the kernel virtual address of the buffer where the card + OS log buffer can be read. This entry is written by the host + configuration daemon to set the log buffer address. The correct + log buffer address to be written can be found in the System.map + file of the card OS. + +What: /sys/class/mic/mic(x)/log_buf_len +Date: October 2013 +KernelVersion: 3.13 +Contact: Sudeep Dutt <sudeep.dutt@intel.com> +Description: + An Intel MIC device runs a Linux OS during its operation. For + debugging purpose and early kernel boot messages, the user can + access the card OS log buffer via debugfs. When read, this entry + provides the kernel virtual address where the card OS log buffer + length can be read. This entry is written by host configuration + daemon to set the log buffer length address. The correct log + buffer length address to be written can be found in the + System.map file of the card OS. + +What: /sys/class/mic/mic(x)/heartbeat_enable +Date: March 2015 +KernelVersion: 4.4 +Contact: Ashutosh Dixit <ashutosh.dixit@intel.com> +Description: + The MIC drivers detect and inform user space about card crashes + via a heartbeat mechanism (see the description of + shutdown_status above). User space can turn off this + notification by setting heartbeat_enable to 0 and enable it by + setting this entry to 1. If this notification is disabled it is + the responsibility of user space to detect card crashes via + alternative means such as a network ping. This setting is + enabled by default.
diff --git a/Documentation/ABI/testing/sysfs-class-mtd b/Documentation/ABI/testing/sysfs-class-mtd new file mode 100644 index 0000000..3b5c3bc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-mtd
@@ -0,0 +1,234 @@ +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. + +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/ . + +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, mlc-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. + +What: /sys/class/mtd/mtdX/ecc_strength +Date: April 2012 +KernelVersion: 3.4 +Contact: linux-mtd@lists.infradead.org +Description: + Maximum number of bit errors that the device is capable of + correcting within each region covering an ECC step (see + ecc_step_size). This will always be a non-negative integer. + + In the case of devices lacking any ECC capability, it is 0. + +What: /sys/class/mtd/mtdX/bitflip_threshold +Date: April 2012 +KernelVersion: 3.4 +Contact: linux-mtd@lists.infradead.org +Description: + This allows the user to examine and adjust the criteria by which + mtd returns -EUCLEAN from mtd_read() and mtd_read_oob(). If the + maximum number of bit errors that were corrected on any single + region comprising an ecc step (as reported by the driver) equals + or exceeds this value, -EUCLEAN is returned. Otherwise, absent + an error, 0 is returned. Higher layers (e.g., UBI) use this + return code as an indication that an erase block may be + degrading and should be scrutinized as a candidate for being + marked as bad. + + The initial value may be specified by the flash device driver. + If not, then the default value is ecc_strength. + + The introduction of this feature brings a subtle change to the + meaning of the -EUCLEAN return code. Previously, it was + interpreted to mean simply "one or more bit errors were + corrected". Its new interpretation can be phrased as "a + dangerously high number of bit errors were corrected on one or + more regions comprising an ecc step". The precise definition of + "dangerously high" can be adjusted by the user with + bitflip_threshold. Users are discouraged from doing this, + however, unless they know what they are doing and have intimate + knowledge of the properties of their device. Broadly speaking, + bitflip_threshold should be low enough to detect genuine erase + block degradation, but high enough to avoid the consequences of + a persistent return value of -EUCLEAN on devices where sticky + bitflips occur. Note that if bitflip_threshold exceeds + ecc_strength, -EUCLEAN is never returned by the read operations. + Conversely, if bitflip_threshold is zero, -EUCLEAN is always + returned, absent a hard error. + + This is generally applicable only to NAND flash devices with ECC + capability. It is ignored on devices lacking ECC capability; + i.e., devices for which ecc_strength is zero. + +What: /sys/class/mtd/mtdX/ecc_step_size +Date: May 2013 +KernelVersion: 3.10 +Contact: linux-mtd@lists.infradead.org +Description: + The size of a single region covered by ECC, known as the ECC + step. Devices may have several equally sized ECC steps within + each writesize region. + + It will always be a non-negative integer. In the case of + devices lacking any ECC capability, it is 0. + +What: /sys/class/mtd/mtdX/ecc_failures +Date: June 2014 +KernelVersion: 3.17 +Contact: linux-mtd@lists.infradead.org +Description: + The number of failures reported by this device's ECC. Typically, + these failures are associated with failed read operations. + + It will always be a non-negative integer. In the case of + devices lacking any ECC capability, it is 0. + +What: /sys/class/mtd/mtdX/corrected_bits +Date: June 2014 +KernelVersion: 3.17 +Contact: linux-mtd@lists.infradead.org +Description: + The number of bits that have been corrected by means of the + device's ECC. + + It will always be a non-negative integer. In the case of + devices lacking any ECC capability, it is 0. + +What: /sys/class/mtd/mtdX/bad_blocks +Date: June 2014 +KernelVersion: 3.17 +Contact: linux-mtd@lists.infradead.org +Description: + The number of blocks marked as bad, if any, in this partition. + +What: /sys/class/mtd/mtdX/bbt_blocks +Date: June 2014 +KernelVersion: 3.17 +Contact: linux-mtd@lists.infradead.org +Description: + The number of blocks that are marked as reserved, if any, in + this partition. These are typically used to store the in-flash + bad block table (BBT). + +What: /sys/class/mtd/mtdX/offset +Date: March 2015 +KernelVersion: 4.1 +Contact: linux-mtd@lists.infradead.org +Description: + For a partition, the offset of that partition from the start + of the master device in bytes. This attribute is absent on + main devices, so it can be used to distinguish between + partitions and devices that aren't partitions.
diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net new file mode 100644 index 0000000..668604f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net
@@ -0,0 +1,253 @@ +What: /sys/class/net/<iface>/name_assign_type +Date: July 2014 +KernelVersion: 3.17 +Contact: netdev@vger.kernel.org +Description: + Indicates the name assignment type. Possible values are: + 1: enumerated by the kernel, possibly in an unpredictable way + 2: predictably named by the kernel + 3: named by userspace + 4: renamed + +What: /sys/class/net/<iface>/addr_assign_type +Date: July 2010 +KernelVersion: 3.2 +Contact: netdev@vger.kernel.org +Description: + Indicates the address assignment type. Possible values are: + 0: permanent address + 1: randomly generated + 2: stolen from another device + 3: set using dev_set_mac_address + +What: /sys/class/net/<iface>/addr_len +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the hardware address size in bytes. + Values vary based on the lower-level protocol used by the + interface (Ethernet, FDDI, ATM, IEEE 802.15.4...). See + include/uapi/linux/if_*.h for actual values. + +What: /sys/class/net/<iface>/address +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Hardware address currently assigned to this interface. + Format is a string, e.g: 00:11:22:33:44:55 for an Ethernet MAC + address. + +What: /sys/class/net/<bridge iface>/bridge/group_fwd_mask +Date: January 2012 +KernelVersion: 3.2 +Contact: netdev@vger.kernel.org +Description: + Bitmask to allow forwarding of link local frames with address + 01-80-C2-00-00-0X on a bridge device. Only values that set bits + not matching BR_GROUPFWD_RESTRICTED in net/bridge/br_private.h + allowed. + Default value 0 does not forward any link local frames. + + Restricted bits: + 0: 01-80-C2-00-00-00 Bridge Group Address used for STP + 1: 01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE + 2: 01-80-C2-00-00-02 (Link Aggregation) 802.3ad + + Any values not setting these bits can be used. Take special + care when forwarding control frames e.g. 802.1X-PAE or LLDP. + +What: /sys/class/net/<iface>/broadcast +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Hardware broadcast address for this interface. Format is a + string, e.g: ff:ff:ff:ff:ff:ff for an Ethernet broadcast MAC + address. + +What: /sys/class/net/<iface>/carrier +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the current physical link state of the interface. + Posssible values are: + 0: physical link is down + 1: physical link is up + + Note: some special devices, e.g: bonding and team drivers will + allow this attribute to be written to force a link state for + operating correctly and designating another fallback interface. + +What: /sys/class/net/<iface>/dev_id +Date: April 2008 +KernelVersion: 2.6.26 +Contact: netdev@vger.kernel.org +Description: + Indicates the device unique identifier. Format is an hexadecimal + value. This is used to disambiguate interfaces which might be + stacked (e.g: VLAN interfaces) but still have the same MAC + address as their parent device. + +What: /sys/class/net/<iface>/dormant +Date: March 2006 +KernelVersion: 2.6.17 +Contact: netdev@vger.kernel.org +Description: + Indicates whether the interface is in dormant state. Possible + values are: + 0: interface is not dormant + 1: interface is dormant + + This attribute can be used by supplicant software to signal that + the device is not usable unless some supplicant-based + authentication is performed (e.g: 802.1x). 'link_mode' attribute + will also reflect the dormant state. + +What: /sys/clas/net/<iface>/duplex +Date: October 2009 +KernelVersion: 2.6.33 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface latest or current duplex value. Possible + values are: + half: half duplex + full: full duplex + + Note: This attribute is only valid for interfaces that implement + the ethtool get_settings method (mostly Ethernet). + +What: /sys/class/net/<iface>/flags +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface flags as a bitmask in hexadecimal. See + include/uapi/linux/if.h for a list of all possible values and + the flags semantics. + +What: /sys/class/net/<iface>/ifalias +Date: September 2008 +KernelVersion: 2.6.28 +Contact: netdev@vger.kernel.org +Description: + Indicates/stores an interface alias name as a string. This can + be used for system management purposes. + +What: /sys/class/net/<iface>/ifindex +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the system-wide interface unique index identifier as a + decimal number. This attribute is used for mapping an interface + identifier to an interface name. It is used throughout the + networking stack for specifying the interface specific + requests/events. + +What: /sys/class/net/<iface>/iflink +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the system-wide interface unique index identifier a + the interface is linked to. Format is decimal. This attribute is + used to resolve interfaces chaining, linking and stacking. + Physical interfaces have the same 'ifindex' and 'iflink' values. + +What: /sys/class/net/<iface>/link_mode +Date: March 2006 +KernelVersion: 2.6.17 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface link mode, as a decimal number. This + attribute should be used in conjunction with 'dormant' attribute + to determine the interface usability. Possible values: + 0: default link mode + 1: dormant link mode + +What: /sys/class/net/<iface>/mtu +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface currently configured MTU value, in + bytes, and in decimal format. Specific values depends on the + lower-level interface protocol used. Ethernet devices will show + a 'mtu' attribute value of 1500 unless changed. + +What: /sys/class/net/<iface>/netdev_group +Date: January 2011 +KernelVersion: 2.6.39 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface network device group, as a decimal + integer. Default value is 0 which corresponds to the initial + network devices group. The group can be changed to affect + routing decisions (see: net/ipv4/fib_rules and + net/ipv6/fib6_rules.c). + +What: /sys/class/net/<iface>/operstate +Date: March 2006 +KernelVersion: 2.6.17 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface RFC2863 operational state as a string. + Possible values are: + "unknown", "notpresent", "down", "lowerlayerdown", "testing", + "dormant", "up". + +What: /sys/class/net/<iface>/phys_port_id +Date: July 2013 +KernelVersion: 3.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface unique physical port identifier within + the NIC, as a string. + +What: /sys/class/net/<iface>/phys_port_name +Date: March 2015 +KernelVersion: 4.0 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface physical port name within the NIC, + as a string. + +What: /sys/class/net/<iface>/speed +Date: October 2009 +KernelVersion: 2.6.33 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface latest or current speed value. Value is + an integer representing the link speed in Mbits/sec. + + Note: this attribute is only valid for interfaces that implement + the ethtool get_settings method (mostly Ethernet ). + +What: /sys/class/net/<iface>/tx_queue_len +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface transmit queue len in number of packets, + as an integer value. Value depend on the type of interface, + Ethernet network adapters have a default value of 1000 unless + configured otherwise + +What: /sys/class/net/<iface>/type +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the interface protocol type as a decimal value. See + include/uapi/linux/if_arp.h for all possible values. + +What: /sys/class/net/<iface>/phys_switch_id +Date: November 2014 +KernelVersion: 3.19 +Contact: netdev@vger.kernel.org +Description: + Indicates the unique physical switch identifier of a switch this + port belongs to, as a string.
diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/testing/sysfs-class-net-batman-adv new file mode 100644 index 0000000..8981068 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-batman-adv
@@ -0,0 +1,30 @@ + +What: /sys/class/net/<iface>/batman-adv/elp_interval +Date: Feb 2014 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Defines the interval in milliseconds in which batman + emits probing packets for neighbor sensing (ELP). + +What: /sys/class/net/<iface>/batman-adv/iface_status +Date: May 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Indicates the status of <iface> as it is seen by batman. + +What: /sys/class/net/<iface>/batman-adv/mesh_iface +Date: May 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + The /sys/class/net/<iface>/batman-adv/mesh_iface file + displays the batman mesh interface this <iface> + currently is associated with. + +What: /sys/class/net/<iface>/batman-adv/throughput_override +Date: Feb 2014 +Contact: Antonio Quartulli <a@unstable.cc> +description: + Defines the throughput value to be used by B.A.T.M.A.N. V + when estimating the link throughput using this interface. + If the value is set to 0 then batman-adv will try to + estimate the throughput by itself.
diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm new file mode 100644 index 0000000..f7be0e8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
@@ -0,0 +1,168 @@ +What: /sys/class/net/<iface>/cdc_ncm/min_tx_pkt +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + The driver will pad NCM Transfer Blocks (NTBs) longer + than this to tx_max, allowing the device to receive + tx_max sized frames with no terminating short + packet. NTBs shorter than this limit are transmitted + as-is, without any padding, and are terminated with a + short USB packet. + + Padding to tx_max allows the driver to transmit NTBs + back-to-back without any interleaving short USB + packets. This reduces the number of short packet + interrupts in the device, and represents a tradeoff + between USB bus bandwidth and device DMA optimization. + + Set to 0 to pad all frames. Set greater than tx_max to + disable all padding. + +What: /sys/class/net/<iface>/cdc_ncm/ndp_to_end +Date: Dec 2015 +KernelVersion: 4.5 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Boolean attribute showing the status of the "NDP to + end" quirk. Defaults to 'N', except for devices + already known to need it enabled. + + The "NDP to end" quirk makes the driver place the NDP + (the packet index table) after the payload. The NCM + specification does not mandate this, but some devices + are known to be more restrictive. Write 'Y' to this + attribute for temporary testing of a suspect device + failing to work with the default driver settings. + + A device entry should be added to the driver if this + quirk is found to be required. + +What: /sys/class/net/<iface>/cdc_ncm/rx_max +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + The maximum NTB size for RX. Cannot exceed the + maximum value supported by the device. Must allow at + least one max sized datagram plus headers. + + The actual limits are device dependent. See + dwNtbInMaxSize. + + Note: Some devices will silently ignore changes to + this value, resulting in oversized NTBs and + corresponding framing errors. + +What: /sys/class/net/<iface>/cdc_ncm/tx_max +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + The maximum NTB size for TX. Cannot exceed the + maximum value supported by the device. Must allow at + least one max sized datagram plus headers. + + The actual limits are device dependent. See + dwNtbOutMaxSize. + +What: /sys/class/net/<iface>/cdc_ncm/tx_timer_usecs +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Datagram aggregation timeout in µs. The driver will + wait up to 3 times this timeout for more datagrams to + aggregate before transmitting an NTB frame. + + Valid range: 5 to 4000000 + + Set to 0 to disable aggregation. + +The following read-only attributes all represent fields of the +structure defined in section 6.2.1 "GetNtbParameters" of "Universal +Serial Bus Communications Class Subclass Specifications for Network +Control Model Devices" (CDC NCM), Revision 1.0 (Errata 1), November +24, 2010 from USB Implementers Forum, Inc. The descriptions are +quoted from table 6-3 of CDC NCM: "NTB Parameter Structure". + +What: /sys/class/net/<iface>/cdc_ncm/bmNtbFormatsSupported +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Bit 0: 16-bit NTB supported (set to 1) + Bit 1: 32-bit NTB supported + Bits 2 – 15: reserved (reset to zero; must be ignored by host) + +What: /sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + IN NTB Maximum Size in bytes + +What: /sys/class/net/<iface>/cdc_ncm/wNdpInDivisor +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Divisor used for IN NTB Datagram payload alignment + +What: /sys/class/net/<iface>/cdc_ncm/wNdpInPayloadRemainder +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Remainder used to align input datagram payload within + the NTB: (Payload Offset) mod (wNdpInDivisor) = + wNdpInPayloadRemainder + +What: /sys/class/net/<iface>/cdc_ncm/wNdpInAlignment +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + NDP alignment modulus for NTBs on the IN pipe. Shall + be a power of 2, and shall be at least 4. + +What: /sys/class/net/<iface>/cdc_ncm/dwNtbOutMaxSize +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + OUT NTB Maximum Size + +What: /sys/class/net/<iface>/cdc_ncm/wNdpOutDivisor +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + OUT NTB Datagram alignment modulus + +What: /sys/class/net/<iface>/cdc_ncm/wNdpOutPayloadRemainder +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Remainder used to align output datagram payload + offsets within the NTB: Padding, shall be transmitted + as zero by function, and ignored by host. (Payload + Offset) mod (wNdpOutDivisor) = wNdpOutPayloadRemainder + +What: /sys/class/net/<iface>/cdc_ncm/wNdpOutAlignment +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + NDP alignment modulus for use in NTBs on the OUT + pipe. Shall be a power of 2, and shall be at least 4. + +What: /sys/class/net/<iface>/cdc_ncm/wNtbOutMaxDatagrams +Date: May 2014 +KernelVersion: 3.16 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Maximum number of datagrams that the host may pack + into a single OUT NTB. Zero means that the device + imposes no limit.
diff --git a/Documentation/ABI/testing/sysfs-class-net-grcan b/Documentation/ABI/testing/sysfs-class-net-grcan new file mode 100644 index 0000000..f418c92 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-grcan
@@ -0,0 +1,35 @@ + +What: /sys/class/net/<iface>/grcan/enable0 +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Hardware configuration of physical interface 0. This file reads + and writes the "Enable 0" bit of the configuration register. + Possible values: 0 or 1. See the GRCAN chapter of the GRLIB IP + core library documentation for details. The default value is 0 + or set by the module parameter grcan.enable0 and can be read at + /sys/module/grcan/parameters/enable0. + +What: /sys/class/net/<iface>/grcan/enable1 +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Hardware configuration of physical interface 1. This file reads + and writes the "Enable 1" bit of the configuration register. + Possible values: 0 or 1. See the GRCAN chapter of the GRLIB IP + core library documentation for details. The default value is 0 + or set by the module parameter grcan.enable1 and can be read at + /sys/module/grcan/parameters/enable1. + +What: /sys/class/net/<iface>/grcan/select +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Configuration of which physical interface to be used. Possible + values: 0 or 1. See the GRCAN chapter of the GRLIB IP core + library documentation for details. The default value is 0 or is + set by the module parameter grcan.select and can be read at + /sys/module/grcan/parameters/select.
diff --git a/Documentation/ABI/testing/sysfs-class-net-janz-ican3 b/Documentation/ABI/testing/sysfs-class-net-janz-ican3 new file mode 100644 index 0000000..fdbc03a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-janz-ican3
@@ -0,0 +1,19 @@ +What: /sys/class/net/<iface>/termination +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Ira W. Snyder <ira.snyder@gmail.com> +Description: + Value representing the can bus termination + + Default: 1 (termination active) + Reading: get actual termination state + Writing: set actual termination state (0=no termination, 1=termination active) + +What: /sys/class/net/<iface>/fwinfo +Date: May 2015 +KernelVersion: 3.19 +Contact: Andreas Gröger <andreas24groeger@gmail.com> +Description: + Firmware stamp of ican3 module + Read-only: 32 byte string identification of the ICAN3 module + (known values: "JANZ-ICAN3 ICANOS 1.xx", "JANZ-ICAN3 CAL/CANopen 1.xx")
diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/testing/sysfs-class-net-mesh new file mode 100644 index 0000000..c2b956d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-mesh
@@ -0,0 +1,108 @@ + +What: /sys/class/net/<mesh_iface>/mesh/aggregated_ogms +Date: May 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Indicates whether the batman protocol messages of the + mesh <mesh_iface> shall be aggregated or not. + +What: /sys/class/net/<mesh_iface>/mesh/<vlan_subdir>/ap_isolation +Date: May 2011 +Contact: Antonio Quartulli <a@unstable.cc> +Description: + Indicates whether the data traffic going from a + wireless client to another wireless client will be + silently dropped. <vlan_subdir> is empty when referring + to the untagged lan. + +What: /sys/class/net/<mesh_iface>/mesh/bonding +Date: June 2010 +Contact: Simon Wunderlich <sw@simonwunderlich.de> +Description: + Indicates whether the data traffic going through the + mesh will be sent using multiple interfaces at the + same time (if available). + +What: /sys/class/net/<mesh_iface>/mesh/bridge_loop_avoidance +Date: November 2011 +Contact: Simon Wunderlich <sw@simonwunderlich.de> +Description: + Indicates whether the bridge loop avoidance feature + is enabled. This feature detects and avoids loops + between the mesh and devices bridged with the soft + interface <mesh_iface>. + +What: /sys/class/net/<mesh_iface>/mesh/fragmentation +Date: October 2010 +Contact: Andreas Langer <an.langer@gmx.de> +Description: + Indicates whether the data traffic going through the + mesh will be fragmented or silently discarded if the + packet size exceeds the outgoing interface MTU. + +What: /sys/class/net/<mesh_iface>/mesh/gw_bandwidth +Date: October 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Defines the bandwidth which is propagated by this + node if gw_mode was set to 'server'. + +What: /sys/class/net/<mesh_iface>/mesh/gw_mode +Date: October 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Defines the state of the gateway features. Can be + either 'off', 'client' or 'server'. + +What: /sys/class/net/<mesh_iface>/mesh/gw_sel_class +Date: October 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Defines the selection criteria this node will use + to choose a gateway if gw_mode was set to 'client'. + +What: /sys/class/net/<mesh_iface>/mesh/hop_penalty +Date: Oct 2010 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Defines the penalty which will be applied to an + originator message's tq-field on every hop. + +What: /sys/class/net/<mesh_iface>/mesh/isolation_mark +Date: Nov 2013 +Contact: Antonio Quartulli <a@unstable.cc> +Description: + Defines the isolation mark (and its bitmask) which + is used to classify clients as "isolated" by the + Extended Isolation feature. + +What: /sys/class/net/<mesh_iface>/mesh/multicast_mode +Date: Feb 2014 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Indicates whether multicast optimizations are enabled + or disabled. If set to zero then all nodes in the + mesh are going to use classic flooding for any + multicast packet with no optimizations. + +What: /sys/class/net/<mesh_iface>/mesh/network_coding +Date: Nov 2012 +Contact: Martin Hundeboll <martin@hundeboll.net> +Description: + Controls whether Network Coding (using some magic + to send fewer wifi packets but still the same + content) is enabled or not. + +What: /sys/class/net/<mesh_iface>/mesh/orig_interval +Date: May 2010 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Defines the interval in milliseconds in which batman + sends its protocol messages. + +What: /sys/class/net/<mesh_iface>/mesh/routing_algo +Date: Dec 2011 +Contact: Marek Lindner <mareklindner@neomailbox.ch> +Description: + Defines the routing procotol this mesh instance + uses to find the optimal paths through the mesh.
diff --git a/Documentation/ABI/testing/sysfs-class-net-qmi b/Documentation/ABI/testing/sysfs-class-net-qmi new file mode 100644 index 0000000..fa5a00b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-qmi
@@ -0,0 +1,23 @@ +What: /sys/class/net/<iface>/qmi/raw_ip +Date: Dec 2015 +KernelVersion: 4.4 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Boolean. Default: 'N' + + Set this to 'Y' to change the network device link + framing from '802.3' to 'raw-ip'. + + The netdev will change to reflect the link framing + mode. The netdev is an ordinary ethernet device in + '802.3' mode, and the driver expects to exchange + frames with an ethernet header over the USB link. The + netdev is a headerless p-t-p device in 'raw-ip' mode, + and the driver expects to echange IPv4 or IPv6 packets + without any L2 header over the USB link. + + Userspace is in full control of firmware configuration + through the delegation of the QMI protocol. Userspace + is responsible for coordination of driver and firmware + link framing mode, changing this setting to 'Y' if the + firmware is configured for 'raw-ip' mode.
diff --git a/Documentation/ABI/testing/sysfs-class-net-queues b/Documentation/ABI/testing/sysfs-class-net-queues new file mode 100644 index 0000000..0c0df91 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-queues
@@ -0,0 +1,87 @@ +What: /sys/class/<iface>/queues/rx-<queue>/rps_cpus +Date: March 2010 +KernelVersion: 2.6.35 +Contact: netdev@vger.kernel.org +Description: + Mask of the CPU(s) currently enabled to participate into the + Receive Packet Steering packet processing flow for this + network device queue. Possible values depend on the number + of available CPU(s) in the system. + +What: /sys/class/<iface>/queues/rx-<queue>/rps_flow_cnt +Date: April 2010 +KernelVersion: 2.6.35 +Contact: netdev@vger.kernel.org +Description: + Number of Receive Packet Steering flows being currently + processed by this particular network device receive queue. + +What: /sys/class/<iface>/queues/tx-<queue>/tx_timeout +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of transmit timeout events seen by this + network interface transmit queue. + +What: /sys/class/<iface>/queues/tx-<queue>/tx_maxrate +Date: March 2015 +KernelVersion: 4.1 +Contact: netdev@vger.kernel.org +Description: + A Mbps max-rate set for the queue, a value of zero means disabled, + default is disabled. + +What: /sys/class/<iface>/queues/tx-<queue>/xps_cpus +Date: November 2010 +KernelVersion: 2.6.38 +Contact: netdev@vger.kernel.org +Description: + Mask of the CPU(s) currently enabled to participate into the + Transmit Packet Steering packet processing flow for this + network device transmit queue. Possible vaules depend on the + number of available CPU(s) in the system. + +What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/hold_time +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the hold time in milliseconds to measure the slack + of this particular network device transmit queue. + Default value is 1000. + +What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/inflight +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of bytes (objects) in flight on this + network device transmit queue. + +What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the current limit of bytes allowed to be queued + on this network device transmit queue. This value is clamped + to be within the bounds defined by limit_max and limit_min. + +What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_max +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the absolute maximum limit of bytes allowed to be + queued on this network device transmit queue. See + include/linux/dynamic_queue_limits.h for the default value. + +What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_min +Date: November 2011 +KernelVersion: 3.3 +Contact: netdev@vger.kernel.org +Description: + Indicates the absolute minimum limit of bytes allowed to be + queued on this network device transmit queue. Default value is + 0.
diff --git a/Documentation/ABI/testing/sysfs-class-net-statistics b/Documentation/ABI/testing/sysfs-class-net-statistics new file mode 100644 index 0000000..397118d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-statistics
@@ -0,0 +1,201 @@ +What: /sys/class/<iface>/statistics/collisions +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of collisions seen by this network device. + This value might not be relevant with all MAC layers. + +What: /sys/class/<iface>/statistics/multicast +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of multicast packets received by this + network device. + +What: /sys/class/<iface>/statistics/rx_bytes +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of bytes received by this network device. + See the network driver for the exact meaning of when this + value is incremented. + +What: /sys/class/<iface>/statistics/rx_compressed +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of compressed packets received by this + network device. This value might only be relevant for interfaces + that support packet compression (e.g: PPP). + +What: /sys/class/<iface>/statistics/rx_crc_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets received with a CRC (FCS) error + by this network device. Note that the specific meaning might + depend on the MAC layer used by the interface. + +What: /sys/class/<iface>/statistics/rx_dropped +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets received by the network device + but dropped, that are not forwarded to the upper layers for + packet processing. See the network driver for the exact + meaning of this value. + +What: /sys/class/<iface>/statistics/rx_fifo_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of receive FIFO errors seen by this + network device. See the network driver for the exact + meaning of this value. + +What: /sys/class/<iface>/statistics/rx_frame_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of received frames with error, such as + alignment errors. Note that the specific meaning depends on + on the MAC layer protocol used. See the network driver for + the exact meaning of this value. + +What: /sys/class/<iface>/statistics/rx_length_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of received error packet with a length + error, oversized or undersized. See the network driver for the + exact meaning of this value. + +What: /sys/class/<iface>/statistics/rx_missed_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of received packets that have been missed + due to lack of capacity in the receive side. See the network + driver for the exact meaning of this value. + +What: /sys/class/<iface>/statistics/rx_over_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of received packets that are oversized + compared to what the network device is configured to accept + (e.g: larger than MTU). See the network driver for the exact + meaning of this value. + +What: /sys/class/<iface>/statistics/rx_packets +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the total number of good packets received by this + network device. + +What: /sys/class/<iface>/statistics/tx_aborted_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets that have been aborted + during transmission by a network device (e.g: because of + a medium collision). See the network driver for the exact + meaning of this value. + +What: /sys/class/<iface>/statistics/tx_bytes +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of bytes transmitted by a network + device. See the network driver for the exact meaning of this + value, in particular whether this accounts for all successfully + transmitted packets or all packets that have been queued for + transmission. + +What: /sys/class/<iface>/statistics/tx_carrier_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets that could not be transmitted + because of carrier errors (e.g: physical link down). See the + network driver for the exact meaning of this value. + +What: /sys/class/<iface>/statistics/tx_compressed +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of transmitted compressed packets. Note + this might only be relevant for devices that support + compression (e.g: PPP). + +What: /sys/class/<iface>/statistics/tx_dropped +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets dropped during transmission. + See the driver for the exact reasons as to why the packets were + dropped. + +What: /sys/class/<iface>/statistics/tx_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets in error during transmission by + a network device. See the driver for the exact reasons as to + why the packets were dropped. + +What: /sys/class/<iface>/statistics/tx_fifo_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets having caused a transmit + FIFO error. See the driver for the exact reasons as to why the + packets were dropped. + +What: /sys/class/<iface>/statistics/tx_heartbeat_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets transmitted that have been + reported as heartbeat errors. See the driver for the exact + reasons as to why the packets were dropped. + +What: /sys/class/<iface>/statistics/tx_packets +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets transmitted by a network + device. See the driver for whether this reports the number of all + attempted or successful transmissions. + +What: /sys/class/<iface>/statistics/tx_window_errors +Date: April 2005 +KernelVersion: 2.6.12 +Contact: netdev@vger.kernel.org +Description: + Indicates the number of packets not successfully transmitted + due to a window collision. The specific meaning depends on the + MAC layer used. On Ethernet this is usually used to report + late collisions errors.
diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd new file mode 100644 index 0000000..b1c3f02 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pktcdvd
@@ -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
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power new file mode 100644 index 0000000..f85ce9e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-power
@@ -0,0 +1,134 @@ +What: /sys/class/power/ds2760-battery.*/charge_now +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Daniel Mack <daniel@caiaq.de> +Description: + This file is writeable and can be used to set the current + coloumb counter value inside the battery monitor chip. This + is needed for unavoidable corrections of aging batteries. + A userspace daemon can monitor the battery charging logic + and once the counter drops out of considerable bounds, take + appropriate action. + +What: /sys/class/power/ds2760-battery.*/charge_full +Date: May 2010 +KernelVersion: 2.6.35 +Contact: Daniel Mack <daniel@caiaq.de> +Description: + This file is writeable and can be used to set the assumed + battery 'full level'. As batteries age, this value has to be + amended over time. + +What: /sys/class/power_supply/max14577-charger/device/fast_charge_timer +Date: October 2014 +KernelVersion: 3.18.0 +Contact: Krzysztof Kozlowski <krzk@kernel.org> +Description: + This entry shows and sets the maximum time the max14577 + charger operates in fast-charge mode. When the timer expires + the device will terminate fast-charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 5, 6 or 7 (hours), + - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/fast_charge_timer +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <krzk@kernel.org> +Description: + This entry shows and sets the maximum time the max77693 + charger operates in fast-charge mode. When the timer expires + the device will terminate fast-charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 4 - 16 (hours), step by 2 (rounded down) + - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/top_off_threshold_current +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <krzk@kernel.org> +Description: + This entry shows and sets the charging current threshold for + entering top-off charging mode. When charging current in fast + charge mode drops below this value, the charger will trigger + interrupt and start top-off charging mode. + + Valid values: + - 100000 - 200000 (microamps), step by 25000 (rounded down) + - 200000 - 350000 (microamps), step by 50000 (rounded down) + - 0: disabled. + +What: /sys/class/power_supply/max77693-charger/device/top_off_timer +Date: January 2015 +KernelVersion: 3.19.0 +Contact: Krzysztof Kozlowski <krzk@kernel.org> +Description: + This entry shows and sets the maximum time the max77693 + charger operates in top-off charge mode. When the timer expires + the device will terminate top-off charge mode (charging current + will drop to 0 A) and will trigger interrupt. + + Valid values: + - 0 - 70 (minutes), step by 10 (rounded down) + +What: /sys/class/power_supply/bq24257-charger/ovp_voltage +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry configures the overvoltage protection feature of bq24257- + type charger devices. This feature protects the device and other + components against damage from overvoltage on the input supply. See + device datasheet for details. + + Valid values: + - 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000, + 10500000 (all uV) + +What: /sys/class/power_supply/bq24257-charger/in_dpm_voltage +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry configures the input dynamic power path management voltage of + bq24257-type charger devices. Once the supply drops to the configured + voltage, the input current limit is reduced down to prevent the further + drop of the supply. When the IC enters this mode, the charge current is + lower than the set value. See device datasheet for details. + + Valid values: + - 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000, + 4760000 (all uV) + +What: /sys/class/power_supply/bq24257-charger/high_impedance_enable +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry allows enabling the high-impedance mode of bq24257-type + charger devices. If enabled, it places the charger IC into low power + standby mode with the switch mode controller disabled. When disabled, + the charger operates normally. See device datasheet for details. + + Valid values: + - 1: enabled + - 0: disabled + +What: /sys/class/power_supply/bq24257-charger/sysoff_enable +Date: October 2015 +KernelVersion: 4.4.0 +Contact: Andreas Dannenberg <dannenberg@ti.com> +Description: + This entry allows enabling the sysoff mode of bq24257-type charger + devices. If enabled and the input is removed, the internal battery FET + is turned off in order to reduce the leakage from the BAT pin to less + than 1uA. Note that on some devices/systems this disconnects the battery + from the system. See device datasheet for details. + + Valid values: + - 1: enabled + - 0: disabled
diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030 new file mode 100644 index 0000000..be26af0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
@@ -0,0 +1,45 @@ +What: /sys/class/power_supply/twl4030_ac/max_current + /sys/class/power_supply/twl4030_usb/max_current +Description: + Read/Write limit on current which may + be drawn from the ac (Accessory Charger) or + USB port. + + Value is in micro-Amps. + + Value is set automatically to an appropriate + value when a cable is plugged or unplugged. + + Value can the set by writing to the attribute. + The change will only persist until the next + plug event. These event are reported via udev. + + +What: /sys/class/power_supply/twl4030_usb/mode +Description: + Changing mode for USB port. + Writing to this can disable charging. + + Possible values are: + "auto" - draw power as appropriate for detected + power source and battery status. + "off" - do not draw any power. + "continuous" + - activate mode described as "linear" in + TWL data sheets. This uses whatever + current is available and doesn't switch off + when voltage drops. + + This is useful for unstable power sources + such as bicycle dynamo, but care should + be taken that battery is not over-charged. + +What: /sys/class/power_supply/twl4030_ac/mode +Description: + Changing mode for 'ac' port. + Writing to this can disable charging. + + Possible values are: + "auto" - draw power as appropriate for detected + power source and battery status. + "off" - do not draw any power.
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap new file mode 100644 index 0000000..db3b3ff --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -0,0 +1,152 @@ +What: /sys/class/powercap/ +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + The powercap/ class sub directory belongs to the power cap + subsystem. Refer to + Documentation/power/powercap/powercap.txt for details. + +What: /sys/class/powercap/<control type> +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + A <control type> is a unique name under /sys/class/powercap. + Here <control type> determines how the power is going to be + controlled. A <control type> can contain multiple power zones. + +What: /sys/class/powercap/<control type>/enabled +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + This allows to enable/disable power capping for a "control type". + This status affects every power zone using this "control_type. + +What: /sys/class/powercap/<control type>/<power zone> +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + A power zone is a single or a collection of devices, which can + be independently monitored and controlled. A power zone sysfs + entry is qualified with the name of the <control type>. + E.g. intel-rapl:0:1:1. + +What: /sys/class/powercap/<control type>/<power zone>/<child power zone> +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Power zones may be organized in a hierarchy in which child + power zones provide monitoring and control for a subset of + devices under the parent. For example, if there is a parent + power zone for a whole CPU package, each CPU core in it can + be a child power zone. + +What: /sys/class/powercap/.../<power zone>/name +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Specifies the name of this power zone. + +What: /sys/class/powercap/.../<power zone>/energy_uj +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Current energy counter in micro-joules. Write "0" to reset. + If the counter can not be reset, then this attribute is + read-only. + +What: /sys/class/powercap/.../<power zone>/max_energy_range_uj +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Range of the above energy counter in micro-joules. + + +What: /sys/class/powercap/.../<power zone>/power_uw +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Current power in micro-watts. + +What: /sys/class/powercap/.../<power zone>/max_power_range_uw +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Range of the above power value in micro-watts. + +What: /sys/class/powercap/.../<power zone>/constraint_X_name +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Each power zone can define one or more constraints. Each + constraint can have an optional name. Here "X" can have values + from 0 to max integer. + +What: /sys/class/powercap/.../<power zone>/constraint_X_power_limit_uw +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Power limit in micro-watts should be applicable for + the time window specified by "constraint_X_time_window_us". + Here "X" can have values from 0 to max integer. + +What: /sys/class/powercap/.../<power zone>/constraint_X_time_window_us +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Time window in micro seconds. This is used along with + constraint_X_power_limit_uw to define a power constraint. + Here "X" can have values from 0 to max integer. + + +What: /sys/class/powercap/<control type>/.../constraint_X_max_power_uw +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Maximum allowed power in micro watts for this constraint. + Here "X" can have values from 0 to max integer. + +What: /sys/class/powercap/<control type>/.../constraint_X_min_power_uw +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Minimum allowed power in micro watts for this constraint. + Here "X" can have values from 0 to max integer. + +What: /sys/class/powercap/.../<power zone>/constraint_X_max_time_window_us +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Maximum allowed time window in micro seconds for this + constraint. Here "X" can have values from 0 to max integer. + +What: /sys/class/powercap/.../<power zone>/constraint_X_min_time_window_us +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description: + Minimum allowed time window in micro seconds for this + constraint. Here "X" can have values from 0 to max integer. + +What: /sys/class/powercap/.../<power zone>/enabled +Date: September 2013 +KernelVersion: 3.13 +Contact: linux-pm@vger.kernel.org +Description + This allows to enable/disable power capping at power zone level. + This applies to current power zone and its children.
diff --git a/Documentation/ABI/testing/sysfs-class-pwm b/Documentation/ABI/testing/sysfs-class-pwm new file mode 100644 index 0000000..c20e613 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pwm
@@ -0,0 +1,88 @@ +What: /sys/class/pwm/ +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + The pwm/ class sub-directory belongs to the Generic PWM + Framework and provides a sysfs interface for using PWM + channels. + +What: /sys/class/pwm/pwmchipN/ +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + A /sys/class/pwm/pwmchipN directory is created for each + probed PWM controller/chip where N is the base of the + PWM chip. + +What: /sys/class/pwm/pwmchipN/npwm +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + The number of PWM channels supported by the PWM chip. + +What: /sys/class/pwm/pwmchipN/export +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Exports a PWM channel from the PWM chip for sysfs control. + Value is between 0 and /sys/class/pwm/pwmchipN/npwm - 1. + +What: /sys/class/pwm/pwmchipN/unexport +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Unexports a PWM channel. + +What: /sys/class/pwm/pwmchipN/pwmX +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + A /sys/class/pwm/pwmchipN/pwmX directory is created for + each exported PWM channel where X is the exported PWM + channel number. + +What: /sys/class/pwm/pwmchipN/pwmX/period +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the PWM signal period in nanoseconds. + +What: /sys/class/pwm/pwmchipN/pwmX/duty_cycle +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the PWM signal duty cycle in nanoseconds. + +What: /sys/class/pwm/pwmchipN/pwmX/polarity +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the output polarity of the PWM signal to "normal" or + "inversed". + +What: /sys/class/pwm/pwmchipN/pwmX/enable +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Enable/disable the PWM signal. + 0 is disabled + 1 is enabled + +What: /sys/class/pwm/pwmchipN/pwmX/capture +Date: June 2016 +KernelVersion: 4.8 +Contact: Lee Jones <lee.jones@linaro.org> +Description: + Capture information about a PWM signal. The output format is a + pair unsigned integers (period and duty cycle), separated by a + single space.
diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc new file mode 100644 index 0000000..b65674d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rc
@@ -0,0 +1,111 @@ +What: /sys/class/rc/ +Date: Apr 2010 +KernelVersion: 2.6.35 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + The rc/ class sub-directory belongs to the Remote Controller + core and provides a sysfs interface for configuring infrared + remote controller receivers. + +What: /sys/class/rc/rcN/ +Date: Apr 2010 +KernelVersion: 2.6.35 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + A /sys/class/rc/rcN directory is created for each remote + control receiver device where N is the number of the receiver. + +What: /sys/class/rc/rcN/protocols +Date: Jun 2010 +KernelVersion: 2.6.36 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Reading this file returns a list of available protocols, + something like: + "rc5 [rc6] nec jvc [sony]" + Enabled protocols are shown in [] brackets. + Writing "+proto" will add a protocol to the list of enabled + protocols. + Writing "-proto" will remove a protocol from the list of enabled + protocols. + Writing "proto" will enable only "proto". + Writing "none" will disable all protocols. + Write fails with EINVAL if an invalid protocol combination or + unknown protocol name is used. + +What: /sys/class/rc/rcN/filter +Date: Jan 2014 +KernelVersion: 3.15 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Sets the scancode filter expected value. + Use in combination with /sys/class/rc/rcN/filter_mask to set the + expected value of the bits set in the filter mask. + If the hardware supports it then scancodes which do not match + the filter will be ignored. Otherwise the write will fail with + an error. + This value may be reset to 0 if the current protocol is altered. + +What: /sys/class/rc/rcN/filter_mask +Date: Jan 2014 +KernelVersion: 3.15 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Sets the scancode filter mask of bits to compare. + Use in combination with /sys/class/rc/rcN/filter to set the bits + of the scancode which should be compared against the expected + value. A value of 0 disables the filter to allow all valid + scancodes to be processed. + If the hardware supports it then scancodes which do not match + the filter will be ignored. Otherwise the write will fail with + an error. + This value may be reset to 0 if the current protocol is altered. + +What: /sys/class/rc/rcN/wakeup_protocols +Date: Feb 2014 +KernelVersion: 3.15 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Reading this file returns a list of available protocols to use + for the wakeup filter, something like: + "rc5 rc6 nec jvc [sony]" + The enabled wakeup protocol is shown in [] brackets. + Writing "+proto" will add a protocol to the list of enabled + wakeup protocols. + Writing "-proto" will remove a protocol from the list of enabled + wakeup protocols. + Writing "proto" will use "proto" for wakeup events. + Writing "none" will disable wakeup. + Write fails with EINVAL if an invalid protocol combination or + unknown protocol name is used, or if wakeup is not supported by + the hardware. + +What: /sys/class/rc/rcN/wakeup_filter +Date: Jan 2014 +KernelVersion: 3.15 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Sets the scancode wakeup filter expected value. + Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to + set the expected value of the bits set in the wakeup filter mask + to trigger a system wake event. + If the hardware supports it and wakeup_filter_mask is not 0 then + scancodes which match the filter will wake the system from e.g. + suspend to RAM or power off. + Otherwise the write will fail with an error. + This value may be reset to 0 if the wakeup protocol is altered. + +What: /sys/class/rc/rcN/wakeup_filter_mask +Date: Jan 2014 +KernelVersion: 3.15 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Sets the scancode wakeup filter mask of bits to compare. + Use in combination with /sys/class/rc/rcN/wakeup_filter to set + the bits of the scancode which should be compared against the + expected value to trigger a system wake event. + If the hardware supports it and wakeup_filter_mask is not 0 then + scancodes which match the filter will wake the system from e.g. + suspend to RAM or power off. + Otherwise the write will fail with an error. + This value may be reset to 0 if the wakeup protocol is altered.
diff --git a/Documentation/ABI/testing/sysfs-class-rc-nuvoton b/Documentation/ABI/testing/sysfs-class-rc-nuvoton new file mode 100644 index 0000000..905bcde --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rc-nuvoton
@@ -0,0 +1,15 @@ +What: /sys/class/rc/rcN/wakeup_data +Date: Mar 2016 +KernelVersion: 4.6 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> +Description: + Reading this file returns the stored CIR wakeup sequence. + It starts with a pulse, followed by a space, pulse etc. + All values are in microseconds. + The same format can be used to store a wakeup sequence + in the Nuvoton chip by writing to this file. + + Note: Some systems reset the stored wakeup sequence to a + factory default on each boot. On such systems store the + wakeup sequence in a file and set it on boot using e.g. + a udev rule.
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator new file mode 100644 index 0000000..bc578bc --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -0,0 +1,372 @@ +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. + +What: /sys/class/regulator/.../bypass +Date: September 2012 +KernelVersion: 3.7 +Contact: Mark Brown <broonie@opensource.wolfsonmicro.com> +Description: + Some regulator directories will contain a field called + bypass. This indicates if the device is in bypass mode. + + This will be one of the following strings: + + 'enabled' + 'disabled' + 'unknown' + + 'enabled' means the regulator is in bypass mode. + + 'disabled' means that the regulator is regulating. + + 'unknown' means software cannot determine the state, or + the reported state is invalid.
diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration new file mode 100644 index 0000000..4cf1e72 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
@@ -0,0 +1,12 @@ +What: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock +Date: Oct 2011 +KernelVersion: 3.0 +Contact: Mark Godfrey <mark.godfrey@stericsson.com> +Description: The rtc_calibration attribute allows the userspace to + calibrate the AB8500.s 32KHz Real Time Clock. + Every 60 seconds the AB8500 will correct the RTC's value + by adding to it the value of this attribute. + The range of the attribute is -127 to +127 in units of + 30.5 micro-seconds (half-parts-per-million of the 32KHz clock) +Users: The /vendor/st-ericsson/base_utilities/core/rtc_calibration + daemon uses this interface.
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host new file mode 100644 index 0000000..0eb255e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-scsi_host
@@ -0,0 +1,29 @@ +What: /sys/class/scsi_host/hostX/isci_id +Date: June 2011 +Contact: Dave Jiang <dave.jiang@intel.com> +Description: + This file contains the enumerated host ID for the Intel + SCU controller. The Intel(R) C600 Series Chipset SATA/SAS + Storage Control Unit embeds up to two 4-port controllers in + a single PCI device. The controllers are enumerated in order + which usually means the lowest number scsi_host corresponds + with the first controller, but this association is not + guaranteed. The 'isci_id' attribute unambiguously identifies + the controller index: '0' for the first controller, + '1' for the second. + +What: /sys/class/scsi_host/hostX/acciopath_status +Date: November 2013 +Contact: Stephen M. Cameron <scameron@beardog.cce.hp.com> +Description: This file contains the current status of the "SSD Smart Path" + feature of HP Smart Array RAID controllers using the hpsa + driver. SSD Smart Path, when enabled permits the driver to + send i/o requests directly to physical devices that are part + of a logical drive, bypassing the controllers firmware RAID + stack for a performance advantage when possible. A value of + '1' indicates the feature is enabled, and the controller may + use the direct i/o path to physical devices. A value of zero + means the feature is disabled and the controller may not use + the direct i/o path to physical devices. This setting is + controller wide, affecting all configured logical drives on the + controller. This file is readable and writable.
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_tape b/Documentation/ABI/testing/sysfs-class-scsi_tape new file mode 100644 index 0000000..9be398b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-scsi_tape
@@ -0,0 +1,109 @@ +What: /sys/class/scsi_tape/*/stats/in_flight +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Show the number of I/Os currently in-flight between the st + module and the SCSI mid-layer. +Users: + + +What: /sys/class/scsi_tape/*/stats/io_ns +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total amount of time spent waiting for all I/O + to and from the tape drive to complete. This includes all + reads, writes, and other SCSI commands issued to the tape + drive. An example of other SCSI commands would be tape + movement such as a rewind when a rewind tape device is + closed. This item is measured in nanoseconds. + + To determine the amount of time spent waiting for other I/O + to complete subtract read_ns and write_ns from this value. +Users: + + +What: /sys/class/scsi_tape/*/stats/other_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + The number of I/O requests issued to the tape drive other + than SCSI read/write requests. +Users: + + +What: /sys/class/scsi_tape/*/stats/read_byte_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total number of bytes requested from the tape drive. + This value is presented in bytes because tape drives support + variable length block sizes. +Users: + + +What: /sys/class/scsi_tape/*/stats/read_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total number of read requests issued to the tape + drive. +Users: + + +What: /sys/class/scsi_tape/*/stats/read_ns +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total amount of time in nanoseconds waiting for + read I/O requests to complete. +Users: + + +What: /sys/class/scsi_tape/*/stats/write_byte_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total number of bytes written to the tape drive. + This value is presented in bytes because tape drives support + variable length block sizes. +Users: + + +What: /sys/class/scsi_tape/*/stats/write_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total number of write requests issued to the tape + drive. +Users: + + +What: /sys/class/scsi_tape/*/stats/write_ms +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the total amount of time in nanoseconds waiting for + write I/O requests to complete. +Users: + + +What: /sys/class/scsi_tape/*/stats/resid_cnt +Date: Apr 2015 +KernelVersion: 4.2 +Contact: Shane Seymour <shane.seymour@hp.com> +Description: + Shows the number of times we found that a residual >0 + was found when the SCSI midlayer indicated that there was + an error. For reads this may be a case of someone issuing + reads greater than the block size. +Users:
diff --git a/Documentation/ABI/testing/sysfs-class-stm b/Documentation/ABI/testing/sysfs-class-stm new file mode 100644 index 0000000..77ed3da --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-stm
@@ -0,0 +1,24 @@ +What: /sys/class/stm/<stm>/masters +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + Shows first and last available to software master numbers on + this STM device. + +What: /sys/class/stm/<stm>/channels +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + Shows the number of channels per master on this STM device. + +What: /sys/class/stm/<stm>/hw_override +Date: March 2016 +KernelVersion: 4.7 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + Reads as 0 if master numbers in the STP stream produced by + this stm device will match the master numbers assigned by + the software or 1 if the stm hardware overrides software + assigned masters.
diff --git a/Documentation/ABI/testing/sysfs-class-stm_source b/Documentation/ABI/testing/sysfs-class-stm_source new file mode 100644 index 0000000..57b8dd3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-stm_source
@@ -0,0 +1,11 @@ +What: /sys/class/stm_source/<stm_source>/stm_source_link +Date: June 2015 +KernelVersion: 4.3 +Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> +Description: + stm_source device linkage to stm device, where its tracing data + is directed. Reads return an existing connection or "<none>" if + this stm_source is not connected to any stm device yet. + Write an existing (registered) stm device's name here to + connect that device. If a device is already connected to this + stm_source, it will first be disconnected.
diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec new file mode 100644 index 0000000..d4a3d23 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-typec
@@ -0,0 +1,276 @@ +USB Type-C port devices (eg. /sys/class/typec/port0/) + +What: /sys/class/typec/<port>/data_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The supported USB data roles. This attribute can be used for + requesting data role swapping on the port. Swapping is supported + as synchronous operation, so write(2) to the attribute will not + return until the operation has finished. The attribute is + notified about role changes so that poll(2) on the attribute + wakes up. Change on the role will also generate uevent + KOBJ_CHANGE on the port. The current role is show in brackets, + for example "[host] device" when DRP port is in host mode. + + Valid values: host, device + +What: /sys/class/typec/<port>/power_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The supported power roles. This attribute can be used to request + power role swap on the port when the port supports USB Power + Delivery. Swapping is supported as synchronous operation, so + write(2) to the attribute will not return until the operation + has finished. The attribute is notified about role changes so + that poll(2) on the attribute wakes up. Change on the role will + also generate uevent KOBJ_CHANGE. The current role is show in + brackets, for example "[source] sink" when in source mode. + + Valid values: source, sink + +What: /sys/class/typec/<port>/vconn_source +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows is the port VCONN Source. This attribute can be used to + request VCONN swap to change the VCONN Source during connection + when both the port and the partner support USB Power Delivery. + Swapping is supported as synchronous operation, so write(2) to + the attribute will not return until the operation has finished. + The attribute is notified about VCONN source changes so that + poll(2) on the attribute wakes up. Change on VCONN source also + generates uevent KOBJ_CHANGE. + + Valid values: + - "no" when the port is not the VCONN Source + - "yes" when the port is the VCONN Source + +What: /sys/class/typec/<port>/power_operation_mode +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the current power operational mode the port is in. The + power operation mode means current level for VBUS. In case USB + Power Delivery communication is used for negotiating the levels, + power operation mode should show "usb_power_delivery". + + Valid values: + - default + - 1.5A + - 3.0A + - usb_power_delivery + +What: /sys/class/typec/<port>/preferred_role +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The user space can notify the driver about the preferred role. + It should be handled as enabling of Try.SRC or Try.SNK, as + defined in USB Type-C specification, in the port drivers. By + default the preferred role should come from the platform. + + Valid values: source, sink, none (to remove preference) + +What: /sys/class/typec/<port>/supported_accessory_modes +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Space separated list of accessory modes, defined in the USB + Type-C specification, the port supports. + +What: /sys/class/typec/<port>/usb_power_delivery_revision +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Revision number of the supported USB Power Delivery + specification, or 0 when USB Power Delivery is not supported. + +What: /sys/class/typec/<port>/usb_typec_revision +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Revision number of the supported USB Type-C specification. + + +USB Type-C partner devices (eg. /sys/class/typec/port0-partner/) + +What: /sys/class/typec/<port>-partner/accessory_mode +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the Accessory Mode name when the partner is an Accessory. + The Accessory Modes are defined in USB Type-C Specification. + +What: /sys/class/typec/<port>-partner/supports_usb_power_delivery +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the partner supports USB Power Delivery communication: + Valid values: yes, no + +What: /sys/class/typec/<port>-partner>/identity/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This directory appears only if the port device driver is capable + of showing the result of Discover Identity USB power delivery + command. That will not always be possible even when USB power + delivery is supported, for example when USB power delivery + communication for the port is mostly handled in firmware. If the + directory exists, it will have an attribute file for every VDO + in Discover Identity command result. + +What: /sys/class/typec/<port>-partner/identity/id_header +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + ID Header VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-partner/identity/cert_stat +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Cert Stat VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-partner/identity/product +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Product VDO part of Discover Identity command result. The value + will show 0 until Discover Identity command result becomes + available. The value can be polled. + + +USB Type-C cable devices (eg. /sys/class/typec/port0-cable/) + +Note: Electronically Marked Cables will have a device also for one cable plug +(eg. /sys/class/typec/port0-plug0). If the cable is active and has also SOP +Double Prime controller (USB Power Deliver specification ch. 2.4) it will have +second device also for the other plug. Both plugs may have alternate modes as +described in USB Type-C and USB Power Delivery specifications. + +What: /sys/class/typec/<port>-cable/type +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the cable is active. + Valid values: active, passive + +What: /sys/class/typec/<port>-cable/plug_type +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows type of the plug on the cable: + - type-a - Standard A + - type-b - Standard B + - type-c + - captive + +What: /sys/class/typec/<port>-cable/identity/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This directory appears only if the port device driver is capable + of showing the result of Discover Identity USB power delivery + command. That will not always be possible even when USB power + delivery is supported. If the directory exists, it will have an + attribute for every VDO returned by Discover Identity command. + +What: /sys/class/typec/<port>-cable/identity/id_header +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + ID Header VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-cable/identity/cert_stat +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Cert Stat VDO part of Discover Identity command result. The + value will show 0 until Discover Identity command result becomes + available. The value can be polled. + +What: /sys/class/typec/<port>-cable/identity/product +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Product VDO part of Discover Identity command result. The value + will show 0 until Discover Identity command result becomes + available. The value can be polled. + + +Alternate Mode devices. + +The alternate modes will have Standard or Vendor ID (SVID) assigned by USB-IF. +The ports, partners and cable plugs can have alternate modes. A supported SVID +will consist of a set of modes. Every SVID a port/partner/plug supports will +have a device created for it, and every supported mode for a supported SVID will +have its own directory under that device. Below <dev> refers to the device for +the alternate mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/svid +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + The SVID (Standard or Vendor ID) assigned by USB-IF for this + alternate mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/ +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Every supported mode will have its own directory. The name of + a mode will be "mode<index>" (for example mode1), where <index> + is the actual index to the mode VDO returned by Discover Modes + USB power delivery command. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows description of the mode. The description is optional for + the drivers, just like with the Billboard Devices. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows the VDO in hexadecimal returned by Discover Modes command + for this mode. + +What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Shows if the mode is active or not. The attribute can be used + for entering/exiting the mode with partners and cable plugs, and + with the port alternate modes it can be used for disabling + support for specific alternate modes. Entering/exiting modes is + supported as synchronous operation so write(2) to the attribute + does not return until the enter/exit mode operation has + finished. The attribute is notified when the mode is + entered/exited so poll(2) on the attribute wakes up. + Entering/exiting a mode will also generate uevent KOBJ_CHANGE. + + Valid values: yes, no + +What: /sys/class/typec/<port>/<dev>/mode<index>/supported_roles +Date: April 2017 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + Space separated list of the supported roles. + + This attribute is available for the devices describing the + alternate modes a port supports, and it will not be exposed with + the devices presenting the alternate modes the partners or cable + plugs support. + + Valid values: source, sink
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc new file mode 100644 index 0000000..85f4875 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc
@@ -0,0 +1,159 @@ +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/ASIE +Date: August 2014 +KernelVersion: 3.18 +Contact: linux-usb@vger.kernel.org +Description: + + The application-specific information element (ASIE) + included in this device's beacon, in space separated + hex octets. + + Reading returns the current ASIE. Writing replaces + the current ASIE with the one written. + +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.
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc new file mode 100644 index 0000000..5977e28 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc
@@ -0,0 +1,57 @@ +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. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_phy_rate +Date: August 2009 +KernelVersion: 2.6.32 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + The maximum PHY rate to use for all connected devices. + This is only of limited use for testing and + development as the hardware's automatic rate + adaptation is better then this simple control. + + Refer to [ECMA-368] section 10.3.1.1 for the value to + use. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_dnts +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The device notification time slot (DNTS) count and inverval in + milliseconds that the WUSB host should use. This controls how + often the devices will have the opportunity to send + notifications to the host. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_retry_count +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The number of retries that the WUSB host should attempt + before reporting an error for a bus transaction. The range of + valid values is [0..15], where 0 indicates infinite retries.
diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog new file mode 100644 index 0000000..736046b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-watchdog
@@ -0,0 +1,51 @@ +What: /sys/class/watchdog/watchdogn/bootstatus +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains status of the watchdog + device at boot. It is equivalent to WDIOC_GETBOOTSTATUS of + ioctl interface. + +What: /sys/class/watchdog/watchdogn/identity +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains identity string of + watchdog device. + +What: /sys/class/watchdog/watchdogn/nowayout +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. While reading, it gives '1' if that + device supports nowayout feature else, it gives '0'. + +What: /sys/class/watchdog/watchdogn/state +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It gives active/inactive status of + watchdog device. + +What: /sys/class/watchdog/watchdogn/status +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains watchdog device's + internal status bits. It is equivalent to WDIOC_GETSTATUS + of ioctl interface. + +What: /sys/class/watchdog/watchdogn/timeleft +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It contains value of time left for + reset generation. It is equivalent to WDIOC_GETTIMELEFT of + ioctl interface. + +What: /sys/class/watchdog/watchdogn/timeout +Date: August 2015 +Contact: Wim Van Sebroeck <wim@iguana.be> +Description: + It is a read only file. It is read to know about current + value of timeout programmed.
diff --git a/Documentation/ABI/testing/sysfs-class-zram b/Documentation/ABI/testing/sysfs-class-zram new file mode 100644 index 0000000..48ddacb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-zram
@@ -0,0 +1,24 @@ +What: /sys/class/zram-control/ +Date: August 2015 +KernelVersion: 4.2 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + The zram-control/ class sub-directory belongs to zram + device class + +What: /sys/class/zram-control/hot_add +Date: August 2015 +KernelVersion: 4.2 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + RO attribute. Read operation will cause zram to add a new + device and return its device id back to user (so one can + use /dev/zram<id>), or error code. + +What: /sys/class/zram-control/hot_remove +Date: August 2015 +KernelVersion: 4.2 +Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> +Description: + WO attribute. Remove a specific /dev/zramX device, where X + is a device_id provided by user.
diff --git a/Documentation/ABI/testing/sysfs-dev b/Documentation/ABI/testing/sysfs-dev new file mode 100644 index 0000000..a9f2b8b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-dev
@@ -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>
diff --git a/Documentation/ABI/testing/sysfs-devices b/Documentation/ABI/testing/sysfs-devices new file mode 100644 index 0000000..5fcc943 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices
@@ -0,0 +1,25 @@ +What: /sys/devices +Date: February 2006 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +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>
diff --git a/Documentation/ABI/testing/sysfs-devices-edac b/Documentation/ABI/testing/sysfs-devices-edac new file mode 100644 index 0000000..6568e00 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-edac
@@ -0,0 +1,140 @@ +What: /sys/devices/system/edac/mc/mc*/reset_counters +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This write-only control file will zero all the statistical + counters for UE and CE errors on the given memory controller. + Zeroing the counters will also reset the timer indicating how + long since the last counter were reset. This is useful for + computing errors/time. Since the counters are always reset + at driver initialization time, no module/kernel parameter + is available. + +What: /sys/devices/system/edac/mc/mc*/seconds_since_reset +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays how many seconds have elapsed + since the last counter reset. This can be used with the error + counters to measure error rates. + +What: /sys/devices/system/edac/mc/mc*/mc_name +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the type of memory controller + that is being utilized. + +What: /sys/devices/system/edac/mc/mc*/size_mb +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays, in count of megabytes, of memory + that this memory controller manages. + +What: /sys/devices/system/edac/mc/mc*/ue_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the total count of uncorrectable + errors that have occurred on this memory controller. If + panic_on_ue is set, this counter will not have a chance to + increment, since EDAC will panic the system + +What: /sys/devices/system/edac/mc/mc*/ue_noinfo_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the number of UEs that have + occurred on this memory controller with no information as to + which DIMM slot is having errors. + +What: /sys/devices/system/edac/mc/mc*/ce_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the total count of correctable + errors that have occurred on this memory controller. This + count is very important to examine. CEs provide early + indications that a DIMM is beginning to fail. This count + field should be monitored for non-zero values and report + such information to the system administrator. + +What: /sys/devices/system/edac/mc/mc*/ce_noinfo_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the number of CEs that + have occurred on this memory controller wherewith no + information as to which DIMM slot is having errors. Memory is + handicapped, but operational, yet no information is available + to indicate which slot the failing memory is in. This count + field should be also be monitored for non-zero values. + +What: /sys/devices/system/edac/mc/mc*/sdram_scrub_rate +Date: February 2007 +Contact: linux-edac@vger.kernel.org +Description: Read/Write attribute file that controls memory scrubbing. + The scrubbing rate used by the memory controller is set by + writing a minimum bandwidth in bytes/sec to the attribute file. + The rate will be translated to an internal value that gives at + least the specified rate. + Reading the file will return the actual scrubbing rate employed. + If configuration fails or memory scrubbing is not implemented, + the value of the attribute file will be -1. + +What: /sys/devices/system/edac/mc/mc*/max_location +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file displays the information about the last + available memory slot in this memory controller. It is used by + userspace tools in order to display the memory filling layout. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/size +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display the size of dimm or rank. + For dimm*/size, this is the size, in MB of the DIMM memory + stick. For rank*/size, this is the size, in MB for one rank + of the DIMM memory stick. On single rank memories (1R), this + is also the total size of the dimm. On dual rank (2R) memories, + this is half the size of the total DIMM memories. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_dev_type +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of DRAM device is + being utilized on this DIMM (x1, x2, x4, x8, ...). + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_edac_mode +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of Error detection + and correction is being utilized. For example: S4ECD4ED would + mean a Chipkill with x4 DRAM. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_label +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This control file allows this DIMM to have a label assigned + to it. With this label in the module, when errors occur + the output can provide the DIMM label in the system log. + This becomes vital for panic events to isolate the + cause of the UE event. + DIMM Labels must be assigned after booting, with information + that correctly identifies the physical slot with its + silk screen label. This information is currently very + motherboard specific and determination of this information + must occur in userland at this time. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_location +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display the location (csrow/channel, + branch/channel/slot or channel/slot) of the dimm or rank. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_mem_type +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of memory is + currently on this csrow. Normally, either buffered or + unbuffered memory (for example, Unbuffered-DDR3).
diff --git a/Documentation/ABI/testing/sysfs-devices-firmware_node b/Documentation/ABI/testing/sysfs-devices-firmware_node new file mode 100644 index 0000000..46badc9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-firmware_node
@@ -0,0 +1,17 @@ +What: /sys/devices/.../firmware_node/ +Date: September 2012 +Contact: <> +Description: + The /sys/devices/.../firmware_node directory contains attributes + allowing the user space to check and modify some firmware + related properties of given device. + +What: /sys/devices/.../firmware_node/description +Date: September 2012 +Contact: Lance Ortiz <lance.ortiz@hp.com> +Description: + The /sys/devices/.../firmware/description attribute contains a string + that describes the device as provided by the _STR method in the ACPI + namespace. This attribute is read-only. If the device does not have + an _STR method associated with it in the ACPI namespace, this + attribute is not present.
diff --git a/Documentation/ABI/testing/sysfs-devices-lpss_ltr b/Documentation/ABI/testing/sysfs-devices-lpss_ltr new file mode 100644 index 0000000..ea9298d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-lpss_ltr
@@ -0,0 +1,44 @@ +What: /sys/devices/.../lpss_ltr/ +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/ directory is only present for + devices included into the Intel Lynxpoint Low Power Subsystem + (LPSS). If present, it contains attributes containing the LTR + mode and the values of LTR registers of the device. + +What: /sys/devices/.../lpss_ltr/ltr_mode +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/ltr_mode attribute contains an + integer number (0 or 1) indicating whether or not the devices' + LTR functionality is working in the software mode (1). + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned. + +What: /sys/devices/.../lpss_ltr/auto_ltr +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/auto_ltr attribute contains the + current value of the device's AUTO_LTR register (raw) + represented as an 8-digit hexadecimal number. + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned. + +What: /sys/devices/.../lpss_ltr/sw_ltr +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/auto_ltr attribute contains the + current value of the device's SW_LTR register (raw) represented + as an 8-digit hexadecimal number. + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned.
diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory new file mode 100644 index 0000000..deef3b5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-memory
@@ -0,0 +1,93 @@ +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 + http://www.ibm.com/developerworks/wikis/display/LinuxP/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 + http://www.ibm.com/developerworks/wikis/display/LinuxP/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, its 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 + http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils + + +What: /sys/devices/system/memory/memoryX/valid_zones +Date: July 2014 +Contact: Zhang Zhen <zhenzhang.zhang@huawei.com> +Description: + The file /sys/devices/system/memory/memoryX/valid_zones is + read-only and is designed to show which zone this memory + block can be onlined to. + +What: /sys/devices/system/memoryX/nodeY +Date: October 2009 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + When CONFIG_NUMA is enabled, a symbolic link that + points to the corresponding NUMA node directory. + + For example, the following symbolic link is created for + memory section 9 on node0: + /sys/devices/system/memory/memory9/node0 -> ../../node/node0 + + +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
diff --git a/Documentation/ABI/testing/sysfs-devices-mmc b/Documentation/ABI/testing/sysfs-devices-mmc new file mode 100644 index 0000000..5a50ab6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-mmc
@@ -0,0 +1,21 @@ +What: /sys/devices/.../mmc_host/mmcX/mmcX:XXXX/enhanced_area_offset +Date: January 2011 +Contact: Chuanxiao Dong <chuanxiao.dong@intel.com> +Description: + Enhanced area is a new feature defined in eMMC4.4 standard. + eMMC4.4 or later card can support such feature. This kind of + area can help to improve the card performance. If the feature + is enabled, this attribute will indicate the start address of + enhanced data area. If not, this attribute will be -EINVAL. + Unit Byte. Format decimal. + +What: /sys/devices/.../mmc_host/mmcX/mmcX:XXXX/enhanced_area_size +Date: January 2011 +Contact: Chuanxiao Dong <chuanxiao.dong@intel.com> +Description: + Enhanced area is a new feature defined in eMMC4.4 standard. + eMMC4.4 or later card can support such feature. This kind of + area can help to improve the card performance. If the feature + is enabled, this attribute will indicate the size of enhanced + data area. If not, this attribute will be -EINVAL. + Unit KByte. Format decimal.
diff --git a/Documentation/ABI/testing/sysfs-devices-online b/Documentation/ABI/testing/sysfs-devices-online new file mode 100644 index 0000000..f990026 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-online
@@ -0,0 +1,20 @@ +What: /sys/devices/.../online +Date: April 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../online attribute is only present for + devices whose bus types provide .online() and .offline() + callbacks. The number read from it (0 or 1) reflects the value + of the device's 'offline' field. If that number is 1 and '0' + (or 'n', or 'N') is written to this file, the device bus type's + .offline() callback is executed for the device and (if + successful) its 'offline' field is updated accordingly. In + turn, if that number is 0 and '1' (or 'y', or 'Y') is written to + this file, the device bus type's .online() callback is executed + for the device and (if successful) its 'offline' field is + updated as appropriate. + + After a successful execution of the bus type's .offline() + callback the device cannot be used for any purpose until either + it is removed (i.e. device_del() is called for it), or its bus + type's .online() is exeucted successfully.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget new file mode 100644 index 0000000..d548eaa --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
@@ -0,0 +1,21 @@ +What: /sys/devices/platform/_UDC_/gadget/suspended +Date: April 2010 +Contact: Fabien Chouteau <fabien.chouteau@barco.com> +Description: + Show the suspend state of an USB composite gadget. + 1 -> suspended + 0 -> resumed + + (_UDC_ is the name of the USB Device Controller driver) + +What: /sys/devices/platform/_UDC_/gadget/gadget-lunX/nofua +Date: July 2010 +Contact: Andy Shevchenko <andy.shevchenko@gmail.com> +Description: + Show or set the reaction on the FUA (Force Unit Access) bit in + the SCSI WRITE(10,12) commands when a gadget in USB Mass + Storage mode. + + Possible values are: + 1 -> ignore the FUA flag + 0 -> obey the FUA flag
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3 new file mode 100644 index 0000000..8aa3671 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3
@@ -0,0 +1,34 @@ +What: /sys/devices/platform/docg3/f[0-3]_dps[01]_is_keylocked +Date: November 2011 +KernelVersion: 3.3 +Contact: Robert Jarzmik <robert.jarzmik@free.fr> +Description: + Show whether the floor (0 to 4), protection area (0 or 1) is + keylocked. Each docg3 chip (or floor) has 2 protection areas, + which can cover any part of it, block aligned, called DPS. + The protection has information embedded whether it blocks reads, + writes or both. + The result is: + 0 -> the DPS is not keylocked + 1 -> the DPS is keylocked +Users: None identified so far. + +What: /sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key +Date: November 2011 +KernelVersion: 3.3 +Contact: Robert Jarzmik <robert.jarzmik@free.fr> +Description: + Enter the protection key for the floor (0 to 4), protection area + (0 or 1). Each docg3 chip (or floor) has 2 protection areas, + which can cover any part of it, block aligned, called DPS. + The protection has information embedded whether it blocks reads, + writes or both. + The protection key is a string of 8 bytes (value 0-255). + Entering the correct value toggle the lock, and can be observed + through f[0-3]_dps[01]_is_keylocked. + Possible values are: + - 8 bytes + Typical values are: + - "00000000" + - "12345678" +Users: None identified so far.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb new file mode 100644 index 0000000..2107082 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
@@ -0,0 +1,44 @@ +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_alpha +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the alpha blending value for the overlay. Values range + from 0 (transparent) to 255 (opaque). The value is ignored if + the mode is not set to Alpha Blending. + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_mode +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Selects the composition mode for the overlay. Possible values + are + + 0 - Alpha Blending + 1 - ROP3 + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the x,y overlay position on the display in pixels. The + position format is `[0-9]+,[0-9]+'. + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3 +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the raster operation (ROP3) for the overlay. Values + range from 0 to 255. The value is ignored if the mode is not + set to ROP3.
diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power new file mode 100644 index 0000000..676fdf5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power
@@ -0,0 +1,276 @@ +What: /sys/devices/.../power/ +Date: January 2009 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power directory contains attributes + allowing the user space to check and modify some power + management related properties of given device. + +What: /sys/devices/.../power/wakeup +Date: January 2009 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/wakeup attribute allows the user + space to check if the device is enabled to wake up the system + from sleep states, such as the memory sleep state (suspend to + RAM) and hibernation (suspend to disk), and to enable or disable + it to do that as desired. + + Some devices support "wakeup" events, which are hardware signals + used to activate the system from a sleep state. Such devices + have one of the following two values for the sysfs power/wakeup + file: + + + "enabled\n" to issue the events; + + "disabled\n" not to do so; + + In that cases the user space can change the setting represented + by the contents of this file by writing either "enabled", or + "disabled" to it. + + For the devices that are not capable of generating system wakeup + events this file is not present. In that case the device cannot + be enabled to wake up the system from sleep states. + +What: /sys/devices/.../power/control +Date: January 2009 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/control attribute allows the user + space to control the run-time power management of the device. + + All devices have one of the following two values for the + power/control file: + + + "auto\n" to allow the device to be power managed at run time; + + "on\n" to prevent the device from being power managed; + + The default for all devices is "auto", which means that they may + be subject to automatic power management, depending on their + drivers. Changing this attribute to "on" prevents the driver + from power managing the device at run time. Doing that while + the device is suspended causes it to be woken up. + +What: /sys/devices/.../power/async +Date: January 2009 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../async attribute allows the user space to + enable or diasble the device's suspend and resume callbacks to + be executed asynchronously (ie. in separate threads, in parallel + with the main suspend/resume thread) during system-wide power + transitions (eg. suspend to RAM, hibernation). + + All devices have one of the following two values for the + power/async file: + + + "enabled\n" to permit the asynchronous suspend/resume; + + "disabled\n" to forbid it; + + The value of this attribute may be changed by writing either + "enabled", or "disabled" to it. + + It generally is unsafe to permit the asynchronous suspend/resume + of a device unless it is certain that all of the PM dependencies + of the device are known to the PM core. However, for some + devices this attribute is set to "enabled" by bus type code or + device drivers and in that cases it should be safe to leave the + default value. + +What: /sys/devices/.../power/wakeup_count +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_count attribute contains the number + of signaled wakeup events associated with the device. This + attribute is read-only. If the device is not capable to wake up + the system from sleep states, this attribute is not present. + If the device is not enabled to wake up the system from sleep + states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_active_count +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_active_count attribute contains the + number of times the processing of wakeup events associated with + the device was completed (at the kernel level). This attribute + is read-only. If the device is not capable to wake up the + system from sleep states, this attribute is not present. If + the device is not enabled to wake up the system from sleep + states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_abort_count +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_abort_count attribute contains the + number of times the processing of a wakeup event associated with + the device might have aborted system transition into a sleep + state in progress. This attribute is read-only. If the device + is not capable to wake up the system from sleep states, this + attribute is not present. If the device is not enabled to wake + up the system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_expire_count +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_expire_count attribute contains the + number of times a wakeup event associated with the device has + been reported with a timeout that expired. This attribute is + read-only. If the device is not capable to wake up the system + from sleep states, this attribute is not present. If the + device is not enabled to wake up the system from sleep states, + this attribute is empty. + +What: /sys/devices/.../power/wakeup_active +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_active attribute contains either 1, + or 0, depending on whether or not a wakeup event associated with + the device is being processed (1). This attribute is read-only. + If the device is not capable to wake up the system from sleep + states, this attribute is not present. If the device is not + enabled to wake up the system from sleep states, this attribute + is empty. + +What: /sys/devices/.../power/wakeup_total_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_total_time_ms attribute contains + the total time of processing wakeup events associated with the + device, in milliseconds. This attribute is read-only. If the + device is not capable to wake up the system from sleep states, + this attribute is not present. If the device is not enabled to + wake up the system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_max_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_max_time_ms attribute contains + the maximum time of processing a single wakeup event associated + with the device, in milliseconds. This attribute is read-only. + If the device is not capable to wake up the system from sleep + states, this attribute is not present. If the device is not + enabled to wake up the system from sleep states, this attribute + is empty. + +What: /sys/devices/.../power/wakeup_last_time_ms +Date: September 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_last_time_ms attribute contains + the value of the monotonic clock corresponding to the time of + signaling the last wakeup event associated with the device, in + milliseconds. This attribute is read-only. If the device is + not enabled to wake up the system from sleep states, this + attribute is not present. If the device is not enabled to wake + up the system from sleep states, this attribute is empty. + +What: /sys/devices/.../power/wakeup_prevent_sleep_time_ms +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_prevent_sleep_time_ms attribute + contains the total time the device has been preventing + opportunistic transitions to sleep states from occurring. + This attribute is read-only. If the device is not capable to + wake up the system from sleep states, this attribute is not + present. If the device is not enabled to wake up the system + from sleep states, this attribute is empty. + +What: /sys/devices/.../power/autosuspend_delay_ms +Date: September 2010 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + The /sys/devices/.../power/autosuspend_delay_ms attribute + contains the autosuspend delay value (in milliseconds). Some + drivers do not want their device to suspend as soon as it + becomes idle at run time; they want the device to remain + inactive for a certain minimum period of time first. That + period is called the autosuspend delay. Negative values will + prevent the device from being suspended at run time (similar + to writing "on" to the power/control attribute). Values >= + 1000 will cause the autosuspend timer expiration to be rounded + up to the nearest second. + + Not all drivers support this attribute. If it isn't supported, + attempts to read or write it will yield I/O errors. + +What: /sys/devices/.../power/pm_qos_resume_latency_us +Date: March 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_resume_latency_us attribute + contains the PM QoS resume latency limit for the given device, + which is the maximum allowed time it can take to resume the + device, after it has been suspended at run time, from a resume + request to the moment the device will be ready to process I/O, + in microseconds. If it is equal to 0, however, this means that + the PM QoS resume latency may be arbitrary. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation. + +What: /sys/devices/.../power/pm_qos_latency_tolerance_us +Date: January 2014 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_latency_tolerance_us attribute + contains the PM QoS active state latency tolerance limit for the + given device in microseconds. That is the maximum memory access + latency the device can suffer without any visible adverse + effects on user space functionality. If that value is the + string "any", the latency does not matter to user space at all, + but hardware should not be allowed to set the latency tolerance + for the device automatically. + + Reading "auto" from this file means that the maximum memory + access latency for the device may be determined automatically + by the hardware as needed. Writing "auto" to it allows the + hardware to be switched to this mode if there are no other + latency tolerance requirements from the kernel side. + + This attribute is only present if the feature controlled by it + is supported by the hardware. + + This attribute has no effect on runtime suspend and resume of + devices and on system-wide suspend/resume and hibernation. + +What: /sys/devices/.../power/pm_qos_no_power_off +Date: September 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_no_power_off attribute + is used for manipulating the PM QoS "no power off" flag. If + set, this flag indicates to the kernel that power should not + be removed entirely from the device. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation. + +What: /sys/devices/.../power/pm_qos_remote_wakeup +Date: September 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_remote_wakeup attribute + is used for manipulating the PM QoS "remote wakeup required" + flag. If set, this flag indicates to the kernel that the + device is a source of user events that have to be signaled from + its low-power states. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D0 b/Documentation/ABI/testing/sysfs-devices-power_resources_D0 new file mode 100644 index 0000000..73b77a6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D0
@@ -0,0 +1,13 @@ +What: /sys/devices/.../power_resources_D0/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D0/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D0. The names + of the links are the same as the names of the directories they + point to.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D1 b/Documentation/ABI/testing/sysfs-devices-power_resources_D1 new file mode 100644 index 0000000..30c2070 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D1
@@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D1/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D1/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D1. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D1. The names + of the links are the same as the names of the directories they + point to.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D2 b/Documentation/ABI/testing/sysfs-devices-power_resources_D2 new file mode 100644 index 0000000..fd9d84b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D2
@@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D2/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D2/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D2. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D2. The names + of the links are the same as the names of the directories they + point to.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot b/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot new file mode 100644 index 0000000..3df32c2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot
@@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D3hot/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D3hot/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D3hot. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D3hot. The + names of the links are the same as the names of the directories + they point to.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup b/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup new file mode 100644 index 0000000..e0588fe --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup
@@ -0,0 +1,13 @@ +What: /sys/devices/.../power_resources_wakeup/ +Date: April 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_wakeup/ directory is only + present for device objects representing ACPI device nodes that + require ACPI power resources for wakeup signaling. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be able to signal wakeup. The names of + the links are the same as the names of the directories they + point to.
diff --git a/Documentation/ABI/testing/sysfs-devices-power_state b/Documentation/ABI/testing/sysfs-devices-power_state new file mode 100644 index 0000000..7ad9546 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_state
@@ -0,0 +1,20 @@ +What: /sys/devices/.../power_state +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_state attribute is only present for + device objects representing ACPI device nodes that provide power + management methods. + + If present, it contains a string representing the current ACPI + power state of the given device node. Its possible values, + "D0", "D1", "D2", "D3hot", and "D3cold", reflect the power state + names defined by the ACPI specification (ACPI 4 and above). + + If the device node uses shared ACPI power resources, this state + determines a list of power resources required not to be turned + off. However, some power resources needed by the device node in + higher-power (lower-number) states may also be ON because of + some other devices using them at the moment. + + This attribute is read-only.
diff --git a/Documentation/ABI/testing/sysfs-devices-real_power_state b/Documentation/ABI/testing/sysfs-devices-real_power_state new file mode 100644 index 0000000..8b3527c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-real_power_state
@@ -0,0 +1,23 @@ +What: /sys/devices/.../real_power_state +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../real_power_state attribute is only present + for device objects representing ACPI device nodes that provide + power management methods and use ACPI power resources for power + management. + + If present, it contains a string representing the real ACPI + power state of the given device node as returned by the _PSC + control method or inferred from the configuration of power + resources. Its possible values, "D0", "D1", "D2", "D3hot", and + "D3cold", reflect the power state names defined by the ACPI + specification (ACPI 4 and above). + + In some situations the value of this attribute may be different + from the value of the /sys/devices/.../power_state attribute for + the same device object. If that happens, some shared power + resources used by the device node are only ON because of some + other devices using them at the moment. + + This attribute is read-only.
diff --git a/Documentation/ABI/testing/sysfs-devices-resource_in_use b/Documentation/ABI/testing/sysfs-devices-resource_in_use new file mode 100644 index 0000000..b4a3bc5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-resource_in_use
@@ -0,0 +1,12 @@ +What: /sys/devices/.../resource_in_use +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../resource_in_use attribute is only present + for device objects representing ACPI power resources. + + If present, it contains a number (0 or 1) representing the + current status of the given power resource (0 means that the + resource is not in use and therefore it has been turned off). + + This attribute is read-only.
diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc new file mode 100644 index 0000000..6d9cc25 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-soc
@@ -0,0 +1,58 @@ +What: /sys/devices/socX +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + The /sys/devices/ directory contains a sub-directory for each + System-on-Chip (SoC) device on a running platform. Information + regarding each SoC can be obtained by reading sysfs files. This + functionality is only available if implemented by the platform. + + The directory created for each SoC will also house information + about devices which are commonly contained in /sys/devices/platform. + It has been agreed that if an SoC device exists, its supported + devices would be better suited to appear as children of that SoC. + +What: /sys/devices/socX/machine +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute common to all SoCs. Contains the SoC machine + name (e.g. Ux500). + +What: /sys/devices/socX/family +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute common to all SoCs. Contains SoC family name + (e.g. DB8500). + +What: /sys/devices/socX/soc_id +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported by most SoCs. In the case of + ST-Ericsson's chips this contains the SoC serial number. + +What: /sys/devices/socX/revision +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported by most SoCs. Contains the SoC's + manufacturing revision number. + +What: /sys/devices/socX/process +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported ST-Ericsson's silicon. Contains the + the process by which the silicon chip was manufactured. + +What: /sys/bus/soc +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + The /sys/bus/soc/ directory contains the usual sub-folders + expected under most buses. /sys/bus/soc/devices is of particular + interest, as it contains a symlink for each SoC device found on + the system. Each symlink points back into the aforementioned + /sys/devices/socX devices.
diff --git a/Documentation/ABI/testing/sysfs-devices-sun b/Documentation/ABI/testing/sysfs-devices-sun new file mode 100644 index 0000000..625ce4b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-sun
@@ -0,0 +1,14 @@ +What: /sys/devices/.../sun +Date: October 2012 +Contact: Yasuaki Ishimatsu <isimatu.yasuaki@jp.fujitsu.com> +Description: + The file contains a Slot-unique ID which provided by the _SUN + method in the ACPI namespace. The value is written in Advanced + Configuration and Power Interface Specification as follows: + + "The _SUN value is required to be unique among the slots of + the same type. It is also recommended that this number match + the slot number printed on the physical slot whenever possible." + + So reading the sysfs file, we can identify a physical position + of the slot in the system.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu new file mode 100644 index 0000000..dfd56ec --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -0,0 +1,368 @@ +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/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/probe + /sys/devices/system/cpu/release +Date: November 2009 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Dynamic addition and removal of CPU's. This is not hotplug + removal, this is meant complete removal/addition of the CPU + from the system. + + probe: writes to this file will dynamically add a CPU to the + system. Information written to the file to add CPU's is + architecture specific. + + release: writes to this file dynamically remove a CPU from + the system. Information writtento the file to remove CPU's + is architecture specific. + +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#/cpufreq/* +Date: pre-git history +Contact: linux-pm@vger.kernel.org +Description: Discover and change clock speed of CPUs + + Clock scaling allows you to change the clock speed of the + CPUs on the fly. This is a nice method to save battery + power, because the lower the clock speed, the less power + the CPU consumes. + + There are many knobs to tweak in this directory. + + See files in Documentation/cpu-freq/ for more information. + + In particular, read Documentation/cpu-freq/user-guide.txt + to learn how to control the knobs. + + +What: /sys/devices/system/cpu/cpu#/cpufreq/freqdomain_cpus +Date: June 2013 +Contact: linux-pm@vger.kernel.org +Description: Discover CPUs in the same CPU frequency coordination domain + + freqdomain_cpus is the list of CPUs (online+offline) that share + the same clock/freq domain (possibly at the hardware level). + That information may be hidden from the cpufreq core and the + value of related_cpus may be different from freqdomain_cpus. This + attribute is useful for user space DVFS controllers to get better + power/performance results for platforms using acpi-cpufreq. + + This file is only present if the acpi-cpufreq driver is in use. + + +What: /sys/devices/system/cpu/cpu*/cache/index3/cache_disable_{0,1} +Date: August 2008 +KernelVersion: 2.6.27 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Disable L3 cache indices + + These files exist in every CPU's cache/index3 directory. Each + cache_disable_{0,1} file corresponds to one disable slot which + can be used to disable a cache index. Reading from these files + on a processor with this functionality will return the currently + disabled index for that node. There is one L3 structure per + node, or per internal node on MCM machines. Writing a valid + index to one of these files will cause the specificed cache + index to be disabled. + + All AMD processors with L3 caches provide this functionality. + For details, see BKDGs at + http://developer.amd.com/documentation/guides/Pages/default.aspx + + +What: /sys/devices/system/cpu/cpufreq/boost +Date: August 2012 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Processor frequency boosting control + + This switch controls the boost setting for the whole system. + Boosting allows the CPU and the firmware to run at a frequency + beyound it's nominal limit. + More details can be found in Documentation/cpu-freq/boost.txt + + +What: /sys/devices/system/cpu/cpu#/crash_notes + /sys/devices/system/cpu/cpu#/crash_notes_size +Date: April 2013 +Contact: kexec@lists.infradead.org +Description: address and size of the percpu note. + + crash_notes: the physical address of the memory that holds the + note of cpu#. + + crash_notes_size: size of the note of cpu#. + + +What: /sys/devices/system/cpu/intel_pstate/max_perf_pct + /sys/devices/system/cpu/intel_pstate/min_perf_pct + /sys/devices/system/cpu/intel_pstate/no_turbo +Date: February 2013 +Contact: linux-pm@vger.kernel.org +Description: Parameters for the Intel P-state driver + + Logic for selecting the current P-state in Intel + Sandybridge+ processors. The three knobs control + limits for the P-state that will be requested by the + driver. + + max_perf_pct: limits the maximum P state that will be requested by + the driver stated as a percentage of the available performance. + + min_perf_pct: limits the minimum P state that will be requested by + the driver stated as a percentage of the available performance. + + no_turbo: limits the driver to selecting P states below the turbo + frequency range. + + More details can be found in Documentation/cpu-freq/intel-pstate.txt + +What: /sys/devices/system/cpu/cpu*/cache/index*/<set_of_attributes_mentioned_below> +Date: July 2014(documented, existed before August 2008) +Contact: Sudeep Holla <sudeep.holla@arm.com> + Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Parameters for the CPU cache attributes + + allocation_policy: + - WriteAllocate: allocate a memory location to a cache line + on a cache miss because of a write + - ReadAllocate: allocate a memory location to a cache line + on a cache miss because of a read + - ReadWriteAllocate: both writeallocate and readallocate + + attributes: LEGACY used only on IA64 and is same as write_policy + + coherency_line_size: the minimum amount of data in bytes that gets + transferred from memory to cache + + level: the cache hierarchy in the multi-level cache configuration + + number_of_sets: total number of sets in the cache, a set is a + collection of cache lines with the same cache index + + physical_line_partition: number of physical cache line per cache tag + + shared_cpu_list: the list of logical cpus sharing the cache + + shared_cpu_map: logical cpu mask containing the list of cpus sharing + the cache + + size: the total cache size in kB + + type: + - Instruction: cache that only holds instructions + - Data: cache that only caches data + - Unified: cache that holds both data and instructions + + ways_of_associativity: degree of freedom in placing a particular block + of memory in the cache + + write_policy: + - WriteThrough: data is written to both the cache line + and to the block in the lower-level memory + - WriteBack: data is written only to the cache line and + the modified cache line is written to main + memory only when it is replaced + +What: /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/turbo_stat + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/sub_turbo_stat + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/unthrottle + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/powercap + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/overtemp + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/supply_fault + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/overcurrent + /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats/occ_reset +Date: March 2016 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> + Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org> +Description: POWERNV CPUFreq driver's frequency throttle stats directory and + attributes + + 'cpuX/cpufreq/throttle_stats' directory contains the CPU frequency + throttle stat attributes for the chip. The throttle stats of a cpu + is common across all the cpus belonging to a chip. Below are the + throttle attributes exported in the 'throttle_stats' directory: + + - turbo_stat : This file gives the total number of times the max + frequency is throttled to lower frequency in turbo (at and above + nominal frequency) range of frequencies. + + - sub_turbo_stat : This file gives the total number of times the + max frequency is throttled to lower frequency in sub-turbo(below + nominal frequency) range of frequencies. + + - unthrottle : This file gives the total number of times the max + frequency is unthrottled after being throttled. + + - powercap : This file gives the total number of times the max + frequency is throttled due to 'Power Capping'. + + - overtemp : This file gives the total number of times the max + frequency is throttled due to 'CPU Over Temperature'. + + - supply_fault : This file gives the total number of times the + max frequency is throttled due to 'Power Supply Failure'. + + - overcurrent : This file gives the total number of times the + max frequency is throttled due to 'Overcurrent'. + + - occ_reset : This file gives the total number of times the max + frequency is throttled due to 'OCC Reset'. + + The sysfs attributes representing different throttle reasons like + powercap, overtemp, supply_fault, overcurrent and occ_reset map to + the reasons provided by OCC firmware for throttling the frequency. + +What: /sys/devices/system/cpu/cpufreq/policyX/throttle_stats + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/turbo_stat + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/sub_turbo_stat + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/unthrottle + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/powercap + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/overtemp + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/supply_fault + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/overcurrent + /sys/devices/system/cpu/cpufreq/policyX/throttle_stats/occ_reset +Date: March 2016 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> + Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org> +Description: POWERNV CPUFreq driver's frequency throttle stats directory and + attributes + + 'policyX/throttle_stats' directory and all the attributes are same as + the /sys/devices/system/cpu/cpuX/cpufreq/throttle_stats directory and + attributes which give the frequency throttle information of the chip. + +What: /sys/devices/system/cpu/cpuX/regs/ + /sys/devices/system/cpu/cpuX/regs/identification/ + /sys/devices/system/cpu/cpuX/regs/identification/midr_el1 + /sys/devices/system/cpu/cpuX/regs/identification/revidr_el1 +Date: June 2016 +Contact: Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org> +Description: AArch64 CPU registers + 'identification' directory exposes the CPU ID registers for + identifying model and revision of the CPU. + +What: /sys/devices/system/cpu/vulnerabilities + /sys/devices/system/cpu/vulnerabilities/meltdown + /sys/devices/system/cpu/vulnerabilities/spectre_v1 + /sys/devices/system/cpu/vulnerabilities/spectre_v2 +Date: January 2018 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Information about CPU vulnerabilities + + The files are named after the code names of CPU + vulnerabilities. The output of those files reflects the + state of the CPUs in the system. Possible output values: + + "Not affected" CPU is not affected by the vulnerability + "Vulnerable" CPU is affected and no mitigation in effect + "Mitigation: $M" CPU is affected and mitigation $M is in effect
diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl new file mode 100644 index 0000000..470def0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
@@ -0,0 +1,22 @@ +What: /sys/devices/system/ibm_rtl/state +Date: Sep 2010 +KernelVersion: 2.6.37 +Contact: Vernon Mauery <vernux@us.ibm.com> +Description: The state file allows a means by which to change in and + out of Premium Real-Time Mode (PRTM), as well as the + ability to query the current state. + 0 => PRTM off + 1 => PRTM enabled +Users: The ibm-prtm userspace daemon uses this interface. + + +What: /sys/devices/system/ibm_rtl/version +Date: Sep 2010 +KernelVersion: 2.6.37 +Contact: Vernon Mauery <vernux@us.ibm.com> +Description: The version file provides a means by which to query + the RTL table version that lives in the Extended + BIOS Data Area (EBDA). +Users: The ibm-prtm userspace daemon uses this interface. + +
diff --git a/Documentation/ABI/testing/sysfs-devices-system-xen_cpu b/Documentation/ABI/testing/sysfs-devices-system-xen_cpu new file mode 100644 index 0000000..9ca02fb --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-system-xen_cpu
@@ -0,0 +1,20 @@ +What: /sys/devices/system/xen_cpu/ +Date: May 2012 +Contact: Liu, Jinsong <jinsong.liu@intel.com> +Description: + A collection of global/individual Xen physical cpu attributes + + Individual physical cpu attributes are contained in + subdirectories named by the Xen's logical cpu number, e.g.: + /sys/devices/system/xen_cpu/xen_cpu#/ + + +What: /sys/devices/system/xen_cpu/xen_cpu#/online +Date: May 2012 +Contact: Liu, Jinsong <jinsong.liu@intel.com> +Description: + Interface to online/offline Xen physical cpus + + When running under Xen platform, it provide user interface + to online/offline physical cpus, except cpu0 due to several + logic restrictions and assumptions.
diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe new file mode 100644 index 0000000..64ac6d5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-genwqe
@@ -0,0 +1,71 @@ +What: /sys/class/genwqe/genwqe<n>_card/version +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Unique bitstream identification e.g. + '0000000330336283.00000000475a4950'. + +What: /sys/class/genwqe/genwqe<n>_card/appid +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Identifies the currently active card application e.g. 'GZIP' + for compression/decompression. + +What: /sys/class/genwqe/genwqe<n>_card/type +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Type of the card e.g. 'GenWQE5-A7'. + +What: /sys/class/genwqe/genwqe<n>_card/curr_bitstream +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Currently active bitstream. 1 is default, 0 is backup. + +What: /sys/class/genwqe/genwqe<n>_card/next_bitstream +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Interface to set the next bitstream to be used. + +What: /sys/class/genwqe/genwqe<n>_card/reload_bitstream +Date: May 2014 +Contact: klebers@linux.vnet.ibm.com +Description: Interface to trigger a PCIe card reset to reload the bitstream. + sudo sh -c 'echo 1 > \ + /sys/class/genwqe/genwqe0_card/reload_bitstream' + If successfully, the card will come back with the bitstream set + on 'next_bitstream'. + +What: /sys/class/genwqe/genwqe<n>_card/tempsens +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Interface to read the cards temperature sense register. + +What: /sys/class/genwqe/genwqe<n>_card/freerunning_timer +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Interface to read the cards free running timer. + Used for performance and utilization measurements. + +What: /sys/class/genwqe/genwqe<n>_card/queue_working_time +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Interface to read queue working time. + Used for performance and utilization measurements. + +What: /sys/class/genwqe/genwqe<n>_card/state +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: State of the card: "unused", "used", "error". + +What: /sys/class/genwqe/genwqe<n>_card/base_clock +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Base clock frequency of the card. + +What: /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs +Date: Oct 2013 +Contact: haver@linux.vnet.ibm.com +Description: Enable VFs (1..15): + sudo sh -c 'echo 15 > \ + /sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs' + Disable VFs: + Write a 0 into the same sysfs entry.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid b/Documentation/ABI/testing/sysfs-driver-hid new file mode 100644 index 0000000..48942ca --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid
@@ -0,0 +1,20 @@ +What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor + For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/report_descriptor + Symlink : /sys/class/hidraw/hidraw<num>/device/report_descriptor +Date: Jan 2011 +KernelVersion: 2.0.39 +Contact: Alan Ott <alan@signal11.us> +Description: When read, this file returns the device's raw binary HID + report descriptor. + This file cannot be written. +Users: HIDAPI library (http://www.signal11.us/oss/hidapi) + +What: For USB devices : /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/country + For BT devices : /sys/class/bluetooth/hci<addr>/<hid-bus>:<vendor-id>:<product-id>.<num>/country + Symlink : /sys/class/hidraw/hidraw<num>/device/country +Date: February 2015 +KernelVersion: 3.19 +Contact: Olivier Gay <ogay@logitech.com> +Description: When read, this file returns the hex integer value in ASCII + of the device's HID country code (e.g. 21 for US). + This file cannot be written.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-corsair b/Documentation/ABI/testing/sysfs-driver-hid-corsair new file mode 100644 index 0000000..b8827f0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-corsair
@@ -0,0 +1,15 @@ +What: /sys/bus/drivers/corsair/<dev>/macro_mode +Date: August 2015 +KernelVersion: 4.2 +Contact: Clement Vuchener <clement.vuchener@gmail.com> +Description: Get/set the current playback mode. "SW" for software mode + where G-keys triggers their regular key codes. "HW" for + hardware playback mode where the G-keys play their macro + from the on-board memory. + + +What: /sys/bus/drivers/corsair/<dev>/current_profile +Date: August 2015 +KernelVersion: 4.2 +Contact: Clement Vuchener <clement.vuchener@gmail.com> +Description: Get/set the current selected profile. Values are from 1 to 3.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-lenovo b/Documentation/ABI/testing/sysfs-driver-hid-lenovo new file mode 100644 index 0000000..53a0725 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-lenovo
@@ -0,0 +1,50 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_to_select +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be + is being controlled by press_speed. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: For details regarding this setting please refer to http://www.pc.ibm.com/ww/healthycomputing/trkpntb.html + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/select_right +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate + a left or right mouse button click. + Values are 0 or 1. + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This file contains the trackpoint sensitivity. + Values are decimal integers from 1 (lowest sensitivity) to 255 (highest sensitivity). + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_speed +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled. + Values are decimal integers from 1 (slowest) to 255 (fastest). + Applies to Thinkpad USB Keyboard with TrackPoint. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fn_lock +Date: July 2014 +Contact: linux-input@vger.kernel.org +Description: This setting controls whether Fn Lock is enabled on the keyboard (i.e. if F1 is Mute or F1) + Values are 0 or 1 + Applies to ThinkPad Compact (USB|Bluetooth) Keyboard with TrackPoint.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff new file mode 100644 index 0000000..305dffd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
@@ -0,0 +1,67 @@ +What: /sys/bus/hid/drivers/logitech/<dev>/range +Date: July 2011 +KernelVersion: 3.2 +Contact: Michal Malý <madcatxster@devoid-pointer.net> +Description: Display minimum, maximum and current range of the steering + wheel. Writing a value within min and max boundaries sets the + range of the wheel. + +What: /sys/bus/hid/drivers/logitech/<dev>/alternate_modes +Date: Feb 2015 +KernelVersion: 4.1 +Contact: Michal Malý <madcatxster@devoid-pointer.net> +Description: Displays a set of alternate modes supported by a wheel. Each + mode is listed as follows: + Tag: Mode Name + Currently active mode is marked with an asterisk. List also + contains an abstract item "native" which always denotes the + native mode of the wheel. Echoing the mode tag switches the + wheel into the corresponding mode. Depending on the exact model + of the wheel not all listed modes might always be selectable. + If a wheel cannot be switched into the desired mode, -EINVAL + is returned accompanied with an explanatory message in the + kernel log. + This entry is not created for devices that have only one mode. + + Currently supported mode switches: + Driving Force Pro: + DF-EX --> DFP + + G25: + DF-EX --> DFP --> G25 + + G27: + DF-EX <*> DFP <-> G25 <-> G27 + DF-EX <*--------> G25 <-> G27 + DF-EX <*----------------> G27 + + G29: + DF-EX <*> DFP <-> G25 <-> G27 <-> G29 + DF-EX <*--------> G25 <-> G27 <-> G29 + DF-EX <*----------------> G27 <-> G29 + DF-EX <*------------------------> G29 + + DFGT: + DF-EX <*> DFP <-> DFGT + DF-EX <*--------> DFGT + + * hid_logitech module must be loaded with lg4ff_no_autoswitch=1 + parameter set in order for the switch to DF-EX mode to work. + +What: /sys/bus/hid/drivers/logitech/<dev>/real_id +Date: Feb 2015 +KernelVersion: 4.1 +Contact: Michal Malý <madcatxster@devoid-pointer.net> +Description: Displays the real model of the wheel regardless of any + alternate mode the wheel might be switched to. + It is a read-only value. + This entry is not created for devices that have only one mode. + +What: /sys/bus/hid/drivers/logitech/<dev>/combine_pedals +Date: Sep 2016 +KernelVersion: 4.9 +Contact: Simon Wood <simon@mungewell.org> +Description: Controls whether a combined value of accelerator and brake is + reported on the Y axis of the controller. Useful for older games + which can do not work with separate accelerator/brake axis. + Off ('0') by default, enabled by setting '1'.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-multitouch b/Documentation/ABI/testing/sysfs-driver-hid-multitouch new file mode 100644 index 0000000..f79839d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-multitouch
@@ -0,0 +1,9 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/quirks +Date: November 2011 +Contact: Benjamin Tissoires <benjamin.tissoires@gmail.com> +Description: The integer value of this attribute corresponds to the + quirks actually in place to handle the device's protocol. + When read, this attribute returns the current settings (see + MT_QUIRKS_* in hid-multitouch.c). + When written this attribute change on the fly the quirks, then + the protocol to handle the device.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-picolcd b/Documentation/ABI/testing/sysfs-driver-hid-picolcd new file mode 100644 index 0000000..98fd81a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-picolcd
@@ -0,0 +1,43 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/operation_mode +Date: March 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Make it possible to switch the PicoLCD device between LCD + (firmware) and bootloader (flasher) operation modes. + + Reading: returns list of available modes, the active mode being + enclosed in brackets ('[' and ']') + + Writing: causes operation mode switch. Permitted values are + the non-active mode names listed when read. + + Note: when switching mode the current PicoLCD HID device gets + disconnected and reconnects after above delay (see attribute + operation_mode_delay for its value). + + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/operation_mode_delay +Date: April 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Delay PicoLCD waits before restarting in new mode when + operation_mode has changed. + + Reading/Writing: It is expressed in ms and permitted range is + 0..30000ms. + + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fb_update_rate +Date: March 2010 +Contact: Bruno Prémont <bonbons@linux-vserver.org> +Description: Make it possible to adjust defio refresh rate. + + Reading: returns list of available refresh rates (expressed in Hz), + the active refresh rate being enclosed in brackets ('[' and ']') + + Writing: accepts new refresh rate expressed in integer Hz + within permitted rates. + + Note: As device can barely do 2 complete refreshes a second + it only makes sense to adjust this value if only one or two + tiles get changed and it's not appropriate to expect the application + to flush its tiny changes explicitly at higher than default rate. +
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-prodikeys b/Documentation/ABI/testing/sysfs-driver-hid-prodikeys new file mode 100644 index 0000000..05d988c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-prodikeys
@@ -0,0 +1,29 @@ +What: /sys/bus/hid/drivers/prodikeys/.../channel +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Allows control (via software) the midi channel to which + that the pc-midi keyboard will output.midi data. + Range: 0..15 + Type: Read/write +What: /sys/bus/hid/drivers/prodikeys/.../sustain +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Allows control (via software) the sustain duration of a + note held by the pc-midi driver. + 0 means sustain mode is disabled. + Range: 0..5000 (milliseconds) + Type: Read/write +What: /sys/bus/hid/drivers/prodikeys/.../octave +Date: April 2010 +KernelVersion: 2.6.34 +Contact: Don Prince <dhprince.devel@yahoo.co.uk> +Description: + Controls the octave shift modifier in the pc-midi driver. + The octave can be shifted via software up/down 2 octaves. + 0 means the no ocatve shift. + Range: -2..2 (minus 2 to plus 2) + Type: Read/Write
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone new file mode 100644 index 0000000..3ca3971 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
@@ -0,0 +1,106 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/actual_dpi +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: It is possible to switch the dpi setting of the mouse with the + press of a button. + When read, this file returns the raw number of the actual dpi + setting reported by the mouse. This number has to be further + processed to receive the real dpi value. + + VALUE DPI + 1 800 + 2 1200 + 3 1600 + 4 2000 + 5 2400 + 6 3200 + + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/actual_profile +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the number of the actual profile. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/firmware_version +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 138 means 1.38 + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/profile[1-5] +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile holds information like button + mappings, sensitivity, the colors of the 5 leds and light + effects. + When read, these files return the respective profile. The + returned data is 975 bytes in size. + When written, this file lets one write the respective profile + data back to the mouse. The data has to be 975 bytes long. + The mouse will reject invalid data, whereas the profile number + stored in the profile doesn't need to fit the number of the + store. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/settings +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the settings stored in the mouse. + The size of the data is 36 bytes and holds information like the + startup_profile, tcu state and calibration_data. + When written, this file lets write settings back to the mouse. + The data has to be 36 bytes long. The mouse will reject invalid + data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/startup_profile +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1 to 5. + When read, this attribute returns the number of the profile + that's active when the mouse is powered on. + When written, this file sets the number of the startup profile + and the mouse activates this profile immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/tcu +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a "Tracking Control Unit" which lets the user + calibrate the laser power to fit the mousepad surface. + When read, this file returns the current state of the TCU, + where 0 means off and 1 means on. + Writing 0 in this file will switch the TCU off. + Writing 1 in this file will start the calibration which takes + around 6 seconds to complete and activates the TCU. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/weight +Date: March 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can be equipped with one of four supplied weights + ranging from 5 to 20 grams which are recognized by the mouse + and its value can be read out. When read, this file returns the + raw value returned by the mouse which eases further processing + in other software. + The values map to the weights as follows: + + VALUE WEIGHT + 0 none + 1 5g + 2 10g + 3 15g + 4 20g + + This file is readonly. +Users: http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-srws1 b/Documentation/ABI/testing/sysfs-driver-hid-srws1 new file mode 100644 index 0000000..d0eba70 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-srws1
@@ -0,0 +1,21 @@ +What: /sys/class/leds/SRWS1::<serial>::RPM1 +What: /sys/class/leds/SRWS1::<serial>::RPM2 +What: /sys/class/leds/SRWS1::<serial>::RPM3 +What: /sys/class/leds/SRWS1::<serial>::RPM4 +What: /sys/class/leds/SRWS1::<serial>::RPM5 +What: /sys/class/leds/SRWS1::<serial>::RPM6 +What: /sys/class/leds/SRWS1::<serial>::RPM7 +What: /sys/class/leds/SRWS1::<serial>::RPM8 +What: /sys/class/leds/SRWS1::<serial>::RPM9 +What: /sys/class/leds/SRWS1::<serial>::RPM10 +What: /sys/class/leds/SRWS1::<serial>::RPM11 +What: /sys/class/leds/SRWS1::<serial>::RPM12 +What: /sys/class/leds/SRWS1::<serial>::RPM13 +What: /sys/class/leds/SRWS1::<serial>::RPM14 +What: /sys/class/leds/SRWS1::<serial>::RPM15 +What: /sys/class/leds/SRWS1::<serial>::RPMALL +Date: Jan 2013 +KernelVersion: 3.9 +Contact: Simon Wood <simon@mungewell.org> +Description: Provides a control for turning on/off the LEDs which form + an RPM meter on the front of the controller
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote new file mode 100644 index 0000000..39dfa5c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
@@ -0,0 +1,77 @@ +What: /sys/bus/hid/drivers/wiimote/<dev>/led1 +What: /sys/bus/hid/drivers/wiimote/<dev>/led2 +What: /sys/bus/hid/drivers/wiimote/<dev>/led3 +What: /sys/bus/hid/drivers/wiimote/<dev>/led4 +Date: July 2011 +KernelVersion: 3.1 +Contact: David Herrmann <dh.herrmann@googlemail.com> +Description: Make it possible to set/get current led state. Reading from it + returns 0 if led is off and 1 if it is on. Writing 0 to it + disables the led, writing 1 enables it. + +What: /sys/bus/hid/drivers/wiimote/<dev>/extension +Date: August 2011 +KernelVersion: 3.2 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: This file contains the currently connected and initialized + extensions. It can be one of: none, motionp, nunchuck, classic, + motionp+nunchuck, motionp+classic + motionp is the official Nintendo Motion+ extension, nunchuck is + the official Nintendo Nunchuck extension and classic is the + Nintendo Classic Controller extension. The motionp extension can + be combined with the other two. + Starting with kernel-version 3.11 Motion Plus hotplugging is + supported and if detected, it's no longer reported as static + extension. You will get uevent notifications for the motion-plus + device then. + +What: /sys/bus/hid/drivers/wiimote/<dev>/devtype +Date: May 2013 +KernelVersion: 3.11 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: While a device is initialized by the wiimote driver, we perform + a device detection and signal a "change" uevent after it is + done. This file shows the detected device type. "pending" means + that the detection is still ongoing, "unknown" means, that the + device couldn't be detected or loaded. "generic" means, that the + device couldn't be detected but supports basic Wii Remote + features and can be used. + Other strings for each device-type are available and may be + added if new device-specific detections are added. + Currently supported are: + gen10: First Wii Remote generation + gen20: Second Wii Remote Plus generation (builtin MP) + balanceboard: Wii Balance Board + +What: /sys/bus/hid/drivers/wiimote/<dev>/bboard_calib +Date: May 2013 +KernelVersion: 3.11 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: This attribute is only provided if the device was detected as a + balance board. It provides a single line with 3 calibration + values for all 4 sensors. The values are separated by colons and + are each 2 bytes long (encoded as 4 digit hexadecimal value). + First, 0kg values for all 4 sensors are written, followed by the + 17kg values for all 4 sensors and last the 34kg values for all 4 + sensors. + Calibration data is already applied by the kernel to all input + values but may be used by user-space to perform other + transformations. + +What: /sys/bus/hid/drivers/wiimote/<dev>/pro_calib +Date: October 2013 +KernelVersion: 3.13 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: This attribute is only provided if the device was detected as a + pro-controller. It provides a single line with 4 calibration + values for all 4 analog sticks. Format is: "x1:y1 x2:y2". Data + is prefixed with a +/-. Each value is a signed 16bit number. + Data is encoded as decimal numbers and specifies the offsets of + the analog sticks of the pro-controller. + Calibration data is already applied by the kernel to all input + values but may be used by user-space to perform other + transformations. + Calibration data is detected by the kernel during device setup. + You can write "scan\n" into this file to re-trigger calibration. + You can also write data directly in the form "x1:y1 x2:y2" to + set the calibration values manually.
diff --git a/Documentation/ABI/testing/sysfs-driver-input-axp-pek b/Documentation/ABI/testing/sysfs-driver-input-axp-pek new file mode 100644 index 0000000..a5e671b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-input-axp-pek
@@ -0,0 +1,11 @@ +What: /sys/class/input/input(x)/device/startup +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Startup time in us. Board is powered on if the button is pressed + for more than <startup_time> + +What: /sys/class/input/input(x)/device/shutdown +Date: March 2014 +Contact: Carlo Caione <carlo@caione.org> +Description: Shutdown time in us. Board is powered off if the button is pressed + for more than <shutdown_time>
diff --git a/Documentation/ABI/testing/sysfs-driver-intel-rapid-start b/Documentation/ABI/testing/sysfs-driver-intel-rapid-start new file mode 100644 index 0000000..5a7d2e2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-intel-rapid-start
@@ -0,0 +1,21 @@ +What: /sys/bus/acpi/intel-rapid-start/wakeup_events +Date: July 2, 2013 +KernelVersion: 3.11 +Contact: Matthew Garrett <mjg59@srcf.ucam.org> +Description: An integer representing a set of wakeup events as follows: + 1: Wake to enter hibernation when the wakeup timer expires + 2: Wake to enter hibernation when the battery reaches a + critical level + + These values are ORed together. For example, a value of 3 + indicates that the system will wake to enter hibernation when + either the wakeup timer expires or the battery reaches a + critical level. + +What: /sys/bus/acpi/intel-rapid-start/wakeup_time +Date: July 2, 2013 +KernelVersion: 3.11 +Contact: Matthew Garrett <mjg59@srcf.ucam.org> +Description: An integer representing the length of time the system will + remain asleep before waking up to enter hibernation. + This value is in minutes.
diff --git a/Documentation/ABI/testing/sysfs-driver-pciback b/Documentation/ABI/testing/sysfs-driver-pciback new file mode 100644 index 0000000..6a733bf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-pciback
@@ -0,0 +1,13 @@ +What: /sys/bus/pci/drivers/pciback/quirks +Date: Oct 2011 +KernelVersion: 3.1 +Contact: xen-devel@lists.xenproject.org +Description: + If the permissive attribute is set, then writing a string in + the format of DDDD:BB:DD.F-REG:SIZE:MASK will allow the guest + to write and read from the PCI device. That is Domain:Bus: + Device.Function-Register:Size:Mask (Domain is optional). + For example: + #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks + will allow the guest to read and write to the configuration + register 0x0E.
diff --git a/Documentation/ABI/testing/sysfs-driver-ppi b/Documentation/ABI/testing/sysfs-driver-ppi new file mode 100644 index 0000000..9921ef2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-ppi
@@ -0,0 +1,75 @@ +What: /sys/class/tpm/tpmX/ppi/ +Date: August 2012 +Kernel Version: 3.6 +Contact: xiaoyan.zhang@intel.com +Description: + This folder includes the attributes related with PPI (Physical + Presence Interface). Only if TPM is supported by BIOS, this + folder makes sense. The folder path can be got by command + 'find /sys/ -name 'pcrs''. For the detail information of PPI, + please refer to the PPI specification from + + http://www.trustedcomputinggroup.org/ + + In Linux 4.2 ppi was moved to the character device directory. + A symlink from tpmX/device/ppi to tpmX/ppi to provide backwards + compatibility. + +What: /sys/class/tpm/tpmX/ppi/version +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the version of the PPI supported by the + platform. + This file is readonly. + +What: /sys/class/tpm/tpmX/ppi/request +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the request for an operation to be + executed in the pre-OS environment. It is the only input from + the OS to the pre-OS environment. The request should be an + integer value range from 1 to 160, and 0 means no request. + This file can be read and written. + +What: /sys/class/tpm/tpmX/ppi/response +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the response to the most recent operation + request it acted upon. The format is "<request> <response num> + : <response description>". + This file is readonly. + +What: /sys/class/tpm/tpmX/ppi/transition_action +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the platform-specific action that should + take place in order to transition to the BIOS for execution of + a requested operation. The format is "<action num>: <action + description>". + This file is readonly. + +What: /sys/class/tpm/tpmX/ppi/tcg_operations +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows whether it is allowed to request an + operation to be executed in the pre-OS environment by the BIOS + for the requests defined by TCG, i.e. requests from 1 to 22. + The format is "<request> <status num>: <status description>". + This attribute is only supported by PPI version 1.2+. + This file is readonly. + +What: /sys/class/tpm/tpmX/ppi/vs_operations +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows whether it is allowed to request an + operation to be executed in the pre-OS environment by the BIOS + for the verdor specific requests, i.e. requests from 128 to + 255. The format is same with tcg_operations. This attribute + is also only supported by PPI version 1.2+. + This file is readonly.
diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop new file mode 100644 index 0000000..63c1ad0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
@@ -0,0 +1,45 @@ +What: /sys/devices/platform/samsung/performance_level +Date: January 1, 2010 +KernelVersion: 2.6.33 +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> +Description: Some Samsung laptops have different "performance levels" + that are can be modified by a function key, and by this + sysfs file. These values don't always make a whole lot + of sense, but some users like to modify them to keep + their fans quiet at all costs. Reading from this file + will show the current performance level. Writing to the + file can change this value. + Valid options: + "silent" + "normal" + "overclock" + Note that not all laptops support all of these options. + Specifically, not all support the "overclock" option, + and it's still unknown if this value even changes + anything, other than making the user feel a bit better. + +What: /sys/devices/platform/samsung/battery_life_extender +Date: December 1, 2011 +KernelVersion: 3.3 +Contact: Corentin Chary <corentin.chary@gmail.com> +Description: Max battery charge level can be modified, battery cycle + life can be extended by reducing the max battery charge + level. + 0 means normal battery mode (100% charge) + 1 means battery life extender mode (80% charge) + +What: /sys/devices/platform/samsung/usb_charge +Date: December 1, 2011 +KernelVersion: 3.3 +Contact: Corentin Chary <corentin.chary@gmail.com> +Description: Use your USB ports to charge devices, even + when your laptop is powered off. + 1 means enabled, 0 means disabled. + +What: /sys/devices/platform/samsung/lid_handling +Date: December 11, 2014 +KernelVersion: 3.19 +Contact: Julijonas Kikutis <julijonas.kikutis@gmail.com> +Description: Some Samsung laptops handle lid closing quicker and + only handle lid opening with this mode enabled. + 1 means enabled, 0 means disabled.
diff --git a/Documentation/ABI/testing/sysfs-driver-st b/Documentation/ABI/testing/sysfs-driver-st new file mode 100644 index 0000000..ba5d770 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-st
@@ -0,0 +1,12 @@ +What: /sys/bus/scsi/drivers/st/debug_flag +Date: October 2015 +Kernel Version: ?.? +Contact: shane.seymour@hpe.com +Description: + This file allows you to turn debug output from the st driver + off if you write a '0' to the file or on if you write a '1'. + Note that debug output requires that the module be compiled + with the #define DEBUG set to a non-zero value (this is the + default). If DEBUG is set to 0 then this file will not + appear in sysfs as its presence is conditional upon debug + output support being compiled into the module.
diff --git a/Documentation/ABI/testing/sysfs-driver-tegra-fuse b/Documentation/ABI/testing/sysfs-driver-tegra-fuse new file mode 100644 index 0000000..69f5af6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-tegra-fuse
@@ -0,0 +1,11 @@ +What: /sys/devices/*/<our-device>/fuse +Date: February 2014 +Contact: Peter De Schrijver <pdeschrijver@nvidia.com> +Description: read-only access to the efuses on Tegra20, Tegra30, Tegra114 + and Tegra124 SoC's from NVIDIA. The efuses contain write once + data programmed at the factory. The data is layed out in 32bit + words in LSB first format. Each bit represents a single value + as decoded from the fuse registers. Bits order/assignment + exactly matches the HW registers, including any unused bits. +Users: any user space application which wants to read the efuses on + Tegra SoC's
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi new file mode 100644 index 0000000..f34221b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
@@ -0,0 +1,197 @@ +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/kbd_backlight_mode +Date: June 8, 2014 +KernelVersion: 3.15 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the keyboard backlight operation mode, valid + values are: + * 0x1 -> FN-Z + * 0x2 -> AUTO (also called TIMER) + * 0x8 -> ON + * 0x10 -> OFF + Note that from kernel 3.16 onwards this file accepts all listed + parameters, kernel 3.15 only accepts the first two (FN-Z and + AUTO). + Also note that toggling this value on type 1 devices, requires + a reboot for changes to take effect. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/kbd_backlight_timeout +Date: June 8, 2014 +KernelVersion: 3.15 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the timeout of the keyboard backlight + whenever the operation mode is set to AUTO (or TIMER), + valid values range from 0-60. + Note that the kernel 3.15 only had support for the first + keyboard type, the kernel 3.16 added support for the second + type and the range accepted for type 2 is 1-60. + See the entry named "kbd_type" +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/position +Date: June 8, 2014 +KernelVersion: 3.15 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file shows the absolute position of the built-in + accelereometer. + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/touchpad +Date: June 8, 2014 +KernelVersion: 3.15 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This files controls the status of the touchpad and pointing + stick (if available), valid values are: + * 0 -> OFF + * 1 -> ON +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes +Date: August 3, 2014 +KernelVersion: 3.16 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file shows the supported keyboard backlight modes + the system supports, which can be: + * 0x1 -> FN-Z + * 0x2 -> AUTO (also called TIMER) + * 0x8 -> ON + * 0x10 -> OFF + Note that not all keyboard types support the listed modes. + See the entry named "available_kbd_modes" +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/kbd_type +Date: August 3, 2014 +KernelVersion: 3.16 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file shows the current keyboard backlight type, + which can be: + * 1 -> Type 1, supporting modes FN-Z and AUTO + * 2 -> Type 2, supporting modes TIMER, ON and OFF +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/usb_sleep_charge +Date: January 23, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the USB Sleep & Charge charging mode, which + can be: + * 0 -> Disabled (0x00) + * 1 -> Alternate (0x09) + * 2 -> Auto (0x21) + * 3 -> Typical (0x11) + Note that from kernel 4.1 onwards this file accepts all listed + values, kernel 4.0 only supports the first three. + Note that this feature only works when connected to power, if + you want to use it under battery, see the entry named + "sleep_functions_on_battery" +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/sleep_functions_on_battery +Date: January 23, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the USB Sleep Functions under battery, and + set the level at which point they will be disabled, accepted + values can be: + * 0 -> Disabled + * 1-100 -> Battery level to disable sleep functions + Currently it prints two values, the first one indicates if the + feature is enabled or disabled, while the second one shows the + current battery level set. + Note that when the value is set to disabled, the sleep function + will only work when connected to power. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/usb_rapid_charge +Date: January 23, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the USB Rapid Charge state, which can be: + * 0 -> Disabled + * 1 -> Enabled + Note that toggling this value requires a reboot for changes to + take effect. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/usb_sleep_music +Date: January 23, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the Sleep & Music state, which values can be: + * 0 -> Disabled + * 1 -> Enabled + Note that this feature only works when connected to power, if + you want to use it under battery, see the entry named + "sleep_functions_on_battery" +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/version +Date: February 12, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file shows the current version of the driver +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/fan +Date: February 12, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the state of the internal fan, valid + values are: + * 0 -> OFF + * 1 -> ON + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/kbd_function_keys +Date: February 12, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the Special Functions (hotkeys) operation + mode, valid values are: + * 0 -> Normal Operation + * 1 -> Special Functions + In the "Normal Operation" mode, the F{1-12} keys are as usual + and the hotkeys are accessed via FN-F{1-12}. + In the "Special Functions" mode, the F{1-12} keys trigger the + hotkey and the F{1-12} keys are accessed via FN-F{1-12}. + Note that toggling this value requires a reboot for changes to + take effect. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/panel_power_on +Date: February 12, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls whether the laptop should turn ON whenever + the LID is opened, valid values are: + * 0 -> Disabled + * 1 -> Enabled + Note that toggling this value requires a reboot for changes to + take effect. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/usb_three +Date: February 12, 2015 +KernelVersion: 4.0 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the USB 3 functionality, valid values are: + * 0 -> Disabled (Acts as a regular USB 2) + * 1 -> Enabled (Full USB 3 functionality) + Note that toggling this value requires a reboot for changes to + take effect. +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/cooling_method +Date: 2016 +KernelVersion: 4.6 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the Cooling Method feature. + Reading this file prints two values, the first is the actual cooling method + and the second is the maximum cooling method supported. + When the maximum cooling method is ONE, valid values are: + * 0 -> Maximum Performance + * 1 -> Battery Optimized + When the maximum cooling method is TWO, valid values are: + * 0 -> Maximum Performance + * 1 -> Performance + * 2 -> Battery Optimized +Users: KToshiba
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps new file mode 100644 index 0000000..a662370 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
@@ -0,0 +1,20 @@ +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/protection_level +Date: August 16, 2014 +KernelVersion: 3.17 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file controls the built-in accelerometer protection level, + valid values are: + * 0 -> Disabled + * 1 -> Low + * 2 -> Medium + * 3 -> High + The default potection value is set to 2 (Medium). +Users: KToshiba + +What: /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/reset_protection +Date: August 16, 2014 +KernelVersion: 3.17 +Contact: Azael Avalos <coproscefalo@gmail.com> +Description: This file turns off the built-in accelerometer for a few + seconds and then restore normal operation. Accepting 1 as the + only parameter.
diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom new file mode 100644 index 0000000..2aa5503 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-wacom
@@ -0,0 +1,103 @@ +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed +Date: April 2010 +Kernel Version: 2.6.35 +Contact: linux-bluetooth@vger.kernel.org +Description: + The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file + controls reporting speed of Wacom bluetooth tablet. Reading + from this file returns 1 if tablet reports in high speed mode + or 0 otherwise. Writing to this file one of these values + switches reporting speed. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/led +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + Attribute group for control of the status LEDs and the OLEDs. + This attribute group is only available for Intuos 4 M, L, + and XL (with LEDs and OLEDs), Intuos 4 WL, Intuos 5 (LEDs only), + Intuos Pro (LEDs only) and Cintiq 21UX2 and Cintiq 24HD + (LEDs only). Therefore its presence implicitly signifies the + presence of said LEDs and OLEDs on the tablet device. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status0_luminance +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + <obsoleted by the LED class API now exported by the driver> + Writing to this file sets the status LED luminance (1..127) + when the stylus does not touch the tablet surface, and no + button is pressed on the stylus. This luminance level is + normally lower than the level when a button is pressed. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status1_luminance +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + <obsoleted by the LED class API now exported by the driver> + Writing to this file sets the status LED luminance (1..127) + when the stylus touches the tablet surface, or any button is + pressed on the stylus. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status_led0_select +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + <obsoleted by the LED class API now exported by the driver> + Writing to this file sets which one of the four (for Intuos 4 + and Intuos 5) or of the right four (for Cintiq 21UX2 and Cintiq + 24HD) status LEDs is active (0..3). The other three LEDs on the + same side are always inactive. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/status_led1_select +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + <obsoleted by the LED class API now exported by the driver> + Writing to this file sets which one of the left four (for Cintiq 21UX2 + and Cintiq 24HD) status LEDs is active (0..3). The other three LEDs on + the left are always inactive. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/buttons_luminance +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + Writing to this file sets the overall luminance level (0..15) + of all eight button OLED displays. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_led/button<n>_rawimg +Date: August 2014 +Contact: linux-input@vger.kernel.org +Description: + When writing a 1024 byte raw image in Wacom Intuos 4 + interleaving format to the file, the image shows up on Button N + of the device. The image is a 64x32 pixel 4-bit gray image. The + 1024 byte binary is split up into 16x 64 byte chunks. Each 64 + byte chunk encodes the image data for two consecutive lines on + the display. The low nibble of each byte contains the first + line, and the high nibble contains the second line. + When the Wacom Intuos 4 is connected over Bluetooth, the + image has to contain 256 bytes (64x32 px 1 bit colour). + The format is also scrambled, like in the USB mode, and it can + be summarized by converting 76543210 into GECA6420. + HGFEDCBA HFDB7531 + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote +Date: July 2015 +Contact: linux-input@vger.kernel.org +Description: + Writing the character sequence '*' followed by a newline to + this file will delete all of the current pairings on the + device. Other character sequences are reserved. This file is + write only. + +What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/<serial_number>/remote_mode +Date: July 2015 +Contact: linux-input@vger.kernel.org +Description: + <obsoleted by the LED class API now exported by the driver> + Reading from this file reports the mode status of the + remote as indicated by the LED lights on the device. If no + reports have been received from the paired device, reading + from this file will report '-1'. The mode is read-only + and cannot be set through the driver.
diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkback b/Documentation/ABI/testing/sysfs-driver-xen-blkback new file mode 100644 index 0000000..8bb43b6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkback
@@ -0,0 +1,17 @@ +What: /sys/module/xen_blkback/parameters/max_buffer_pages +Date: March 2013 +KernelVersion: 3.11 +Contact: Roger Pau Monné <roger.pau@citrix.com> +Description: + Maximum number of free pages to keep in each block + backend buffer. + +What: /sys/module/xen_blkback/parameters/max_persistent_grants +Date: March 2013 +KernelVersion: 3.11 +Contact: Roger Pau Monné <roger.pau@citrix.com> +Description: + Maximum number of grants to map persistently in + blkback. If the frontend tries to use more than + max_persistent_grants, the LRU kicks in and starts + removing 5% of max_persistent_grants every 100ms.
diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkfront b/Documentation/ABI/testing/sysfs-driver-xen-blkfront new file mode 100644 index 0000000..c0a6cb7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkfront
@@ -0,0 +1,10 @@ +What: /sys/module/xen_blkfront/parameters/max +Date: June 2013 +KernelVersion: 3.11 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Maximum number of segments that the frontend will negotiate + with the backend for indirect descriptors. The default value + is 32 - higher value means more potential throughput but more + memory usage. The backend picks the minimum of the frontend + and its default backend value.
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi new file mode 100644 index 0000000..c7fc72d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -0,0 +1,206 @@ +What: /sys/firmware/acpi/bgrt/ +Date: January 2012 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + The BGRT is an ACPI 5.0 feature that allows the OS + to obtain a copy of the firmware boot splash and + some associated metadata. This is intended to be used + by boot splash applications in order to interact with + the firmware boot splash in order to avoid jarring + transitions. + + image: The image bitmap. Currently a 32-bit BMP. + status: 1 if the image is valid, 0 if firmware invalidated it. + type: 0 indicates image is in BMP format. + version: The version of the BGRT. Currently 1. + xoffset: The number of pixels between the left of the screen + and the left edge of the image. + yoffset: The number of pixels between the top of the screen + and the top edge of the image. + +What: /sys/firmware/acpi/hotplug/ +Date: February 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + There are separate hotplug profiles for different classes of + devices supported by ACPI, such as containers, memory modules, + processors, PCI root bridges etc. A hotplug profile for a given + class of devices is a collection of settings defining the way + that class of devices will be handled by the ACPI core hotplug + code. Those profiles are represented in sysfs as subdirectories + of /sys/firmware/acpi/hotplug/. + + The following setting is available to user space for each + hotplug profile: + + enabled: If set, the ACPI core will handle notifications of + hotplug events associated with the given class of + devices and will allow those devices to be ejected with + the help of the _EJ0 control method. Unsetting it + effectively disables hotplug for the correspoinding + class of devices. + + The value of the above attribute is an integer number: 1 (set) + or 0 (unset). Attempts to write any other values to it will + cause -EINVAL to be returned. + +What: /sys/firmware/acpi/hotplug/force_remove +Date: May 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The number in this file (0 or 1) determines whether (1) or not + (0) the ACPI subsystem will allow devices to be hot-removed even + if they cannot be put offline gracefully (from the kernel's + viewpoint). That number can be changed by writing a boolean + value to this file. + +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 writing 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 +
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries new file mode 100644 index 0000000..210ad44 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
@@ -0,0 +1,110 @@ +What: /sys/firmware/dmi/entries/ +Date: February 2011 +Contact: Mike Waychison <mikew@google.com> +Description: + Many machines' firmware (x86 and ia64) export DMI / + SMBIOS tables to the operating system. Getting at this + information is often valuable to userland, especially in + cases where there are OEM extensions used. + + The kernel itself does not rely on the majority of the + information in these tables being correct. It equally + cannot ensure that the data as exported to userland is + without error either. + + DMI is structured as a large table of entries, where + each entry has a common header indicating the type and + length of the entry, as well as a firmware-provided + 'handle' that is supposed to be unique amongst all + entries. + + Some entries are required by the specification, but many + others are optional. In general though, users should + never expect to find a specific entry type on their + system unless they know for certain what their firmware + is doing. Machine to machine experiences will vary. + + Multiple entries of the same type are allowed. In order + to handle these duplicate entry types, each entry is + assigned by the operating system an 'instance', which is + derived from an entry type's ordinal position. That is + to say, if there are 'N' multiple entries with the same type + 'T' in the DMI tables (adjacent or spread apart, it + doesn't matter), they will be represented in sysfs as + entries "T-0" through "T-(N-1)": + + Example entry directories: + + /sys/firmware/dmi/entries/17-0 + /sys/firmware/dmi/entries/17-1 + /sys/firmware/dmi/entries/17-2 + /sys/firmware/dmi/entries/17-3 + ... + + Instance numbers are used in lieu of the firmware + assigned entry handles as the kernel itself makes no + guarantees that handles as exported are unique, and + there are likely firmware images that get this wrong in + the wild. + + Each DMI entry in sysfs has the common header values + exported as attributes: + + handle : The 16bit 'handle' that is assigned to this + entry by the firmware. This handle may be + referred to by other entries. + length : The length of the entry, as presented in the + entry itself. Note that this is _not the + total count of bytes associated with the + entry_. This value represents the length of + the "formatted" portion of the entry. This + "formatted" region is sometimes followed by + the "unformatted" region composed of nul + terminated strings, with termination signalled + by a two nul characters in series. + raw : The raw bytes of the entry. This includes the + "formatted" portion of the entry, the + "unformatted" strings portion of the entry, + and the two terminating nul characters. + type : The type of the entry. This value is the same + as found in the directory name. It indicates + how the rest of the entry should be interpreted. + instance: The instance ordinal of the entry for the + given type. This value is the same as found + in the parent directory name. + position: The ordinal position (zero-based) of the entry + within the entirety of the DMI entry table. + + === Entry Specialization === + + Some entry types may have other information available in + sysfs. Not all types are specialized. + + --- Type 15 - System Event Log --- + + This entry allows the firmware to export a log of + events the system has taken. This information is + typically backed by nvram, but the implementation + details are abstracted by this table. This entry's data + is exported in the directory: + + /sys/firmware/dmi/entries/15-0/system_event_log + + and has the following attributes (documented in the + SMBIOS / DMI specification under "System Event Log (Type 15)": + + area_length + header_start_offset + data_start_offset + access_method + status + change_token + access_method_address + header_format + per_log_type_descriptor_length + type_descriptors_supported_count + + As well, the kernel exports the binary attribute: + + raw_event_log : The raw binary bits of the event log + as described by the DMI entry.
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-tables b/Documentation/ABI/testing/sysfs-firmware-dmi-tables new file mode 100644 index 0000000..ff3cac8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-tables
@@ -0,0 +1,22 @@ +What: /sys/firmware/dmi/tables/ +Date: April 2015 +Contact: Ivan Khoronzhuk <ivan.khoronzhuk@globallogic.com> +Description: + The firmware provides DMI structures as a packed list of + data referenced by a SMBIOS table entry point. The SMBIOS + entry point contains general information, like SMBIOS + version, DMI table size, etc. The structure, content and + size of SMBIOS entry point is dependent on SMBIOS version. + The format of SMBIOS entry point and DMI structures + can be read in SMBIOS specification. + + The dmi/tables provides raw SMBIOS entry point and DMI tables + through sysfs as an alternative to utilities reading them + from /dev/mem. The raw SMBIOS entry point and DMI table are + presented as binary attributes and are accessible via: + + /sys/firmware/dmi/tables/smbios_entry_point + /sys/firmware/dmi/tables/DMI + + The complete DMI information can be obtained using these two + tables.
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi b/Documentation/ABI/testing/sysfs-firmware-efi new file mode 100644 index 0000000..e794eac --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-efi
@@ -0,0 +1,30 @@ +What: /sys/firmware/efi/fw_vendor +Date: December 2013 +Contact: Dave Young <dyoung@redhat.com> +Description: It shows the physical address of firmware vendor field in the + EFI system table. +Users: Kexec + +What: /sys/firmware/efi/runtime +Date: December 2013 +Contact: Dave Young <dyoung@redhat.com> +Description: It shows the physical address of runtime service table entry in + the EFI system table. +Users: Kexec + +What: /sys/firmware/efi/config_table +Date: December 2013 +Contact: Dave Young <dyoung@redhat.com> +Description: It shows the physical address of config table entry in the EFI + system table. +Users: Kexec + +What: /sys/firmware/efi/systab +Date: April 2005 +Contact: linux-efi@vger.kernel.org +Description: Displays the physical addresses of all EFI Configuration + Tables found via the EFI System Table. The order in + which the tables are printed forms an ABI and newer + versions are always printed first, i.e. ACPI20 comes + before ACPI. +Users: dmidecode
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-esrt b/Documentation/ABI/testing/sysfs-firmware-efi-esrt new file mode 100644 index 0000000..6e431d1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-efi-esrt
@@ -0,0 +1,81 @@ +What: /sys/firmware/efi/esrt/ +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: Provides userland access to read the EFI System Resource Table + (ESRT), a catalog of firmware for which can be updated with + the UEFI UpdateCapsule mechanism described in section 7.5 of + the UEFI Standard. +Users: fwupdate - https://github.com/rhinstaller/fwupdate + +What: /sys/firmware/efi/esrt/fw_resource_count +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The number of entries in the ESRT + +What: /sys/firmware/efi/esrt/fw_resource_count_max +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The maximum number of entries that /could/ be registered + in the allocation the table is currently in. This is + really only useful to the system firmware itself. + +What: /sys/firmware/efi/esrt/fw_resource_version +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The version of the ESRT structure provided by the firmware. + +What: /sys/firmware/efi/esrt/entries/entry$N/ +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: Each ESRT entry is identified by a GUID, and each gets a + subdirectory under entries/ . + example: /sys/firmware/efi/esrt/entries/entry0/ + +What: /sys/firmware/efi/esrt/entries/entry$N/fw_type +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: What kind of firmware entry this is: + 0 - Unknown + 1 - System Firmware + 2 - Device Firmware + 3 - UEFI Driver + +What: /sys/firmware/efi/esrt/entries/entry$N/fw_class +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: This is the entry's guid, and will match the directory name. + +What: /sys/firmware/efi/esrt/entries/entry$N/fw_version +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The version of the firmware currently installed. This is a + 32-bit unsigned integer. + +What: /sys/firmware/efi/esrt/entries/entry$N/lowest_supported_fw_version +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The lowest version of the firmware that can be installed. + +What: /sys/firmware/efi/esrt/entries/entry$N/capsule_flags +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: Flags that must be passed to UpdateCapsule() + +What: /sys/firmware/efi/esrt/entries/entry$N/last_attempt_version +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The last firmware version for which an update was attempted. + +What: /sys/firmware/efi/esrt/entries/entry$N/last_attempt_status +Date: February 2015 +Contact: Peter Jones <pjones@redhat.com> +Description: The result of the last firmware update attempt for the + firmware resource entry. + 0 - Success + 1 - Insufficient resources + 2 - Incorrect version + 3 - Invalid format + 4 - Authentication error + 5 - AC power event + 6 - Battery power event +
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map new file mode 100644 index 0000000..c61b9b3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
@@ -0,0 +1,34 @@ +What: /sys/firmware/efi/runtime-map/ +Date: December 2013 +Contact: Dave Young <dyoung@redhat.com> +Description: Switching efi runtime services to virtual mode requires + that all efi memory ranges which have the runtime attribute + bit set to be mapped to virtual addresses. + + The efi runtime services can only be switched to virtual + mode once without rebooting. The kexec kernel must maintain + the same physical to virtual address mappings as the first + kernel. The mappings are exported to sysfs so userspace tools + can reassemble them and pass them into the kexec kernel. + + /sys/firmware/efi/runtime-map/ is the directory the kernel + exports that information in. + + subdirectories are named with the number of the memory range: + + /sys/firmware/efi/runtime-map/0 + /sys/firmware/efi/runtime-map/1 + /sys/firmware/efi/runtime-map/2 + /sys/firmware/efi/runtime-map/3 + ... + + Each subdirectory contains five files: + + attribute : The attributes of the memory range. + num_pages : The size of the memory range in pages. + phys_addr : The physical address of the memory range. + type : The type of the memory range. + virt_addr : The virtual address of the memory range. + + Above values are all hexadecimal numbers with the '0x' prefix. +Users: Kexec
diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi new file mode 100644 index 0000000..0faa0aa --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
@@ -0,0 +1,58 @@ +What: /sys/firmware/gsmi +Date: March 2011 +Contact: Mike Waychison <mikew@google.com> +Description: + Some servers used internally at Google have firmware + that provides callback functionality via explicit SMI + triggers. Some of the callbacks are similar to those + provided by the EFI runtime services page, but due to + historical reasons this different entry-point has been + used. + + The gsmi driver implements the kernel's abstraction for + these firmware callbacks. Currently, this functionality + is limited to handling the system event log and getting + access to EFI-style variables stored in nvram. + + Layout: + + /sys/firmware/gsmi/vars: + + This directory has the same layout (and + underlying implementation as /sys/firmware/efi/vars. + See Documentation/ABI/*/sysfs-firmware-efi-vars + for more information on how to interact with + this structure. + + /sys/firmware/gsmi/append_to_eventlog - write-only: + + This file takes a binary blob and passes it onto + the firmware to be timestamped and appended to + the system eventlog. The binary format is + interpreted by the firmware and may change from + platform to platform. The only kernel-enforced + requirement is that the blob be prefixed with a + 32bit host-endian type used as part of the + firmware call. + + /sys/firmware/gsmi/clear_config - write-only: + + Writing any value to this file will cause the + entire firmware configuration to be reset to + "factory defaults". Callers should assume that + a reboot is required for the configuration to be + cleared. + + /sys/firmware/gsmi/clear_eventlog - write-only: + + This file is used to clear out a portion/the + whole of the system event log. Values written + should be values between 1 and 100 inclusive (in + ASCII) representing the fraction of the log to + clear. Not all platforms support fractional + clearing though, and this writes to this file + will error out if the firmware doesn't like your + submitted fraction. + + Callers should assume that a reboot is needed + for this operation to complete.
diff --git a/Documentation/ABI/testing/sysfs-firmware-log b/Documentation/ABI/testing/sysfs-firmware-log new file mode 100644 index 0000000..9b58e7c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-log
@@ -0,0 +1,7 @@ +What: /sys/firmware/log +Date: February 2011 +Contact: Mike Waychison <mikew@google.com> +Description: + The /sys/firmware/log is a binary file that represents a + read-only copy of the firmware's log if one is + available.
diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap new file mode 100644 index 0000000..eca0d65 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-memmap
@@ -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 ----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-firmware-ofw b/Documentation/ABI/testing/sysfs-firmware-ofw new file mode 100644 index 0000000..f562b18 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-ofw
@@ -0,0 +1,28 @@ +What: /sys/firmware/devicetree/* +Date: November 2013 +Contact: Grant Likely <grant.likely@linaro.org> +Description: + When using OpenFirmware or a Flattened Device Tree to enumerate + hardware, the device tree structure will be exposed in this + directory. + + It is possible for multiple device-tree directories to exist. + Some device drivers use a separate detached device tree which + have no attachment to the system tree and will appear in a + different subdirectory under /sys/firmware/devicetree. + + Userspace must not use the /sys/firmware/devicetree/base + path directly, but instead should follow /proc/device-tree + symlink. It is possible that the absolute path will change + in the future, but the symlink is the stable ABI. + + The /proc/device-tree symlink replaces the devicetree /proc + filesystem support, and has largely the same semantics and + should be compatible with existing userspace. + + The contents of /sys/firmware/devicetree/ is a + hierarchy of directories, one per device tree node. The + directory name is the resolved path component name (node + name plus address). Properties are represented as files + in the directory. The contents of each file is the exact + binary data from the device tree.
diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg new file mode 100644 index 0000000..011dda4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
@@ -0,0 +1,100 @@ +What: /sys/firmware/qemu_fw_cfg/ +Date: August 2015 +Contact: Gabriel Somlo <somlo@cmu.edu> +Description: + Several different architectures supported by QEMU (x86, arm, + sun4*, ppc/mac) are provisioned with a firmware configuration + (fw_cfg) device, originally intended as a way for the host to + provide configuration data to the guest firmware. Starting + with QEMU v2.4, arbitrary fw_cfg file entries may be specified + by the user on the command line, which makes fw_cfg additionally + useful as an out-of-band, asynchronous mechanism for providing + configuration data to the guest userspace. + + The authoritative guest-side hardware interface documentation + to the fw_cfg device can be found in "docs/specs/fw_cfg.txt" + in the QEMU source tree. + + === SysFS fw_cfg Interface === + + The fw_cfg sysfs interface described in this document is only + intended to display discoverable blobs (i.e., those registered + with the file directory), as there is no way to determine the + presence or size of "legacy" blobs (with selector keys between + 0x0002 and 0x0018) programmatically. + + All fw_cfg information is shown under: + + /sys/firmware/qemu_fw_cfg/ + + The only legacy blob displayed is the fw_cfg device revision: + + /sys/firmware/qemu_fw_cfg/rev + + --- Discoverable fw_cfg blobs by selector key --- + + All discoverable blobs listed in the fw_cfg file directory are + displayed as entries named after their unique selector key + value, e.g.: + + /sys/firmware/qemu_fw_cfg/by_key/32 + /sys/firmware/qemu_fw_cfg/by_key/33 + /sys/firmware/qemu_fw_cfg/by_key/34 + ... + + Each such fw_cfg sysfs entry has the following values exported + as attributes: + + name : The 56-byte nul-terminated ASCII string used as the + blob's 'file name' in the fw_cfg directory. + size : The length of the blob, as given in the fw_cfg + directory. + key : The value of the blob's selector key as given in the + fw_cfg directory. This value is the same as used in + the parent directory name. + raw : The raw bytes of the blob, obtained by selecting the + entry via the control register, and reading a number + of bytes equal to the blob size from the data + register. + + --- Listing fw_cfg blobs by file name --- + + While the fw_cfg device does not impose any specific naming + convention on the blobs registered in the file directory, + QEMU developers have traditionally used path name semantics + to give each blob a descriptive name. For example: + + "bootorder" + "genroms/kvmvapic.bin" + "etc/e820" + "etc/boot-fail-wait" + "etc/system-states" + "etc/table-loader" + "etc/acpi/rsdp" + "etc/acpi/tables" + "etc/smbios/smbios-tables" + "etc/smbios/smbios-anchor" + ... + + In addition to the listing by unique selector key described + above, the fw_cfg sysfs driver also attempts to build a tree + of directories matching the path name components of fw_cfg + blob names, ending in symlinks to the by_key entry for each + "basename", as illustrated below (assume current directory is + /sys/firmware): + + qemu_fw_cfg/by_name/bootorder -> ../by_key/38 + qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35 + qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41 + ... + + Construction of the directory tree and symlinks is done on a + "best-effort" basis, as there is no guarantee that components + of fw_cfg blob names are always "well behaved". I.e., there is + the possibility that a symlink (basename) will conflict with + a dirname component of another fw_cfg blob, in which case the + creation of the offending /sys/firmware/qemu_fw_cfg/by_name + entry will be skipped. + + The authoritative list of entries will continue to be found + under the /sys/firmware/qemu_fw_cfg/by_key directory.
diff --git a/Documentation/ABI/testing/sysfs-firmware-sfi b/Documentation/ABI/testing/sysfs-firmware-sfi new file mode 100644 index 0000000..4be7d44 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-sfi
@@ -0,0 +1,15 @@ +What: /sys/firmware/sfi/tables/ +Date: May 2010 +Contact: Len Brown <lenb@kernel.org> +Description: + SFI defines a number of small static memory tables + so the kernel can get platform information from firmware. + + The tables are defined in the latest SFI specification: + http://simplefirmware.org/documentation + + While the tables are used by the kernel, user-space + can observe them this way: + + # cd /sys/firmware/sfi/tables + # cat $TABLENAME > $TABLENAME.bin
diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv new file mode 100644 index 0000000..4573fd4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv
@@ -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
diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4 new file mode 100644 index 0000000..c631253 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-ext4
@@ -0,0 +1,111 @@ +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_blks +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 preference to + all other allocation heuristics. This is intended for + debugging use only, and should be 0 on production + systems. + +What: /sys/fs/ext4/<disk>/max_writeback_mb_bump +Date: September 2009 +Contact: "Theodore Ts'o" <tytso@mit.edu> +Description: + The maximum number of megabytes the writeback code will + try to write out before move on to another inode. + +What: /sys/fs/ext4/<disk>/extent_max_zeroout_kb +Date: August 2012 +Contact: "Theodore Ts'o" <tytso@mit.edu> +Description: + The maximum number of kilobytes which will be zeroed + out in preference to creating a new uninitialized + extent when manipulating an inode's extent tree. Note + that using a larger value will increase the + variability of time necessary to complete a random + write operation (since a 4k random write might turn + into a much larger write due to the zeroout + operation).
diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs new file mode 100644 index 0000000..a809f60 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-f2fs
@@ -0,0 +1,114 @@ +What: /sys/fs/f2fs/<disk>/gc_max_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the maximun sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_min_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the minimum sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_no_gc_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the default sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_idle +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the victim selection policy for garbage collection. + +What: /sys/fs/f2fs/<disk>/reclaim_segments +Date: October 2013 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the issue rate of segment discard commands. + +What: /sys/fs/f2fs/<disk>/ipu_policy +Date: November 2013 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the in-place-update policy. + +What: /sys/fs/f2fs/<disk>/min_ipu_util +Date: November 2013 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the FS utilization condition for the in-place-update + policies. + +What: /sys/fs/f2fs/<disk>/min_fsync_blocks +Date: September 2014 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the dirty page count condition for the in-place-update + policies. + +What: /sys/fs/f2fs/<disk>/max_small_discards +Date: November 2013 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the issue rate of small discard commands. + +What: /sys/fs/f2fs/<disk>/max_victim_search +Date: January 2014 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the number of trials to find a victim segment. + +What: /sys/fs/f2fs/<disk>/dir_level +Date: March 2014 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the directory level for large directory. + +What: /sys/fs/f2fs/<disk>/ram_thresh +Date: March 2014 +Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> +Description: + Controls the memory footprint used by f2fs. + +What: /sys/fs/f2fs/<disk>/trim_sections +Date: February 2015 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the trimming rate in batch mode. + +What: /sys/fs/f2fs/<disk>/cp_interval +Date: October 2015 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the checkpoint timing. + +What: /sys/fs/f2fs/<disk>/idle_interval +Date: January 2016 +Contact: "Jaegeuk Kim" <jaegeuk@kernel.org> +Description: + Controls the idle timing. + +What: /sys/fs/f2fs/<disk>/ra_nid_pages +Date: October 2015 +Contact: "Chao Yu" <chao2.yu@samsung.com> +Description: + Controls the count of nid pages to be readaheaded. + +What: /sys/fs/f2fs/<disk>/dirty_nats_ratio +Date: January 2016 +Contact: "Chao Yu" <chao2.yu@samsung.com> +Description: + Controls dirty nat entries ratio threshold, if current + ratio exceeds configured threshold, checkpoint will + be triggered for flushing dirty nat entries. + +What: /sys/fs/f2fs/<disk>/lifetime_write_kbytes +Date: January 2016 +Contact: "Shuoran Liu" <liushuoran@huawei.com> +Description: + Shows total written kbytes issued to disk.
diff --git a/Documentation/ABI/testing/sysfs-fs-nilfs2 b/Documentation/ABI/testing/sysfs-fs-nilfs2 new file mode 100644 index 0000000..304ba84 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-nilfs2
@@ -0,0 +1,269 @@ + +What: /sys/fs/nilfs2/features/revision +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show current revision of NILFS file system driver. + This value informs about file system revision that + driver is ready to support. + +What: /sys/fs/nilfs2/features/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/features group. + +What: /sys/fs/nilfs2/<device>/revision +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show NILFS file system revision on volume. + This value informs about metadata structures' + revision on mounted volume. + +What: /sys/fs/nilfs2/<device>/blocksize +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show volume's block size in bytes. + +What: /sys/fs/nilfs2/<device>/device_size +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show volume size in bytes. + +What: /sys/fs/nilfs2/<device>/free_blocks +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show count of free blocks on volume. + +What: /sys/fs/nilfs2/<device>/uuid +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show volume's UUID (Universally Unique Identifier). + +What: /sys/fs/nilfs2/<device>/volume_name +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show volume's label. + +What: /sys/fs/nilfs2/<device>/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device> group. + +What: /sys/fs/nilfs2/<device>/superblock/sb_write_time +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show last write time of super block in human-readable + format. + +What: /sys/fs/nilfs2/<device>/superblock/sb_write_time_secs +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show last write time of super block in seconds. + +What: /sys/fs/nilfs2/<device>/superblock/sb_write_count +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show current write count of super block. + +What: /sys/fs/nilfs2/<device>/superblock/sb_update_frequency +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show/Set interval of periodical update of superblock + (in seconds). + +What: /sys/fs/nilfs2/<device>/superblock/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device>/superblock + group. + +What: /sys/fs/nilfs2/<device>/segctor/last_pseg_block +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show start block number of the latest segment. + +What: /sys/fs/nilfs2/<device>/segctor/last_seg_sequence +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show sequence value of the latest segment. + +What: /sys/fs/nilfs2/<device>/segctor/last_seg_checkpoint +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show checkpoint number of the latest segment. + +What: /sys/fs/nilfs2/<device>/segctor/current_seg_sequence +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show segment sequence counter. + +What: /sys/fs/nilfs2/<device>/segctor/current_last_full_seg +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show index number of the latest full segment. + +What: /sys/fs/nilfs2/<device>/segctor/next_full_seg +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show index number of the full segment index + to be used next. + +What: /sys/fs/nilfs2/<device>/segctor/next_pseg_offset +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show offset of next partial segment in the current + full segment. + +What: /sys/fs/nilfs2/<device>/segctor/next_checkpoint +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show next checkpoint number. + +What: /sys/fs/nilfs2/<device>/segctor/last_seg_write_time +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show write time of the last segment in + human-readable format. + +What: /sys/fs/nilfs2/<device>/segctor/last_seg_write_time_secs +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show write time of the last segment in seconds. + +What: /sys/fs/nilfs2/<device>/segctor/last_nongc_write_time +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show write time of the last segment not for cleaner + operation in human-readable format. + +What: /sys/fs/nilfs2/<device>/segctor/last_nongc_write_time_secs +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show write time of the last segment not for cleaner + operation in seconds. + +What: /sys/fs/nilfs2/<device>/segctor/dirty_data_blocks_count +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of dirty data blocks. + +What: /sys/fs/nilfs2/<device>/segctor/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device>/segctor + group. + +What: /sys/fs/nilfs2/<device>/segments/segments_number +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of segments on a volume. + +What: /sys/fs/nilfs2/<device>/segments/blocks_per_segment +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of blocks in segment. + +What: /sys/fs/nilfs2/<device>/segments/clean_segments +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show count of clean segments. + +What: /sys/fs/nilfs2/<device>/segments/dirty_segments +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show count of dirty segments. + +What: /sys/fs/nilfs2/<device>/segments/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device>/segments + group. + +What: /sys/fs/nilfs2/<device>/checkpoints/checkpoints_number +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of checkpoints on volume. + +What: /sys/fs/nilfs2/<device>/checkpoints/snapshots_number +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of snapshots on volume. + +What: /sys/fs/nilfs2/<device>/checkpoints/last_seg_checkpoint +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show checkpoint number of the latest segment. + +What: /sys/fs/nilfs2/<device>/checkpoints/next_checkpoint +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show next checkpoint number. + +What: /sys/fs/nilfs2/<device>/checkpoints/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device>/checkpoints + group. + +What: /sys/fs/nilfs2/<device>/mounted_snapshots/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe content of /sys/fs/nilfs2/<device>/mounted_snapshots + group. + +What: /sys/fs/nilfs2/<device>/mounted_snapshots/<id>/inodes_count +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of inodes for snapshot. + +What: /sys/fs/nilfs2/<device>/mounted_snapshots/<id>/blocks_count +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Show number of blocks for snapshot. + +What: /sys/fs/nilfs2/<device>/mounted_snapshots/<id>/README +Date: April 2014 +Contact: "Vyacheslav Dubeyko" <slava@dubeyko.com> +Description: + Describe attributes of /sys/fs/nilfs2/<device>/mounted_snapshots/<id> + group.
diff --git a/Documentation/ABI/testing/sysfs-fs-xfs b/Documentation/ABI/testing/sysfs-fs-xfs new file mode 100644 index 0000000..ea0cc8c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-xfs
@@ -0,0 +1,39 @@ +What: /sys/fs/xfs/<disk>/log/log_head_lsn +Date: July 2014 +KernelVersion: 3.17 +Contact: xfs@oss.sgi.com +Description: + The log sequence number (LSN) of the current head of the + log. The LSN is exported in "cycle:basic block" format. +Users: xfstests + +What: /sys/fs/xfs/<disk>/log/log_tail_lsn +Date: July 2014 +KernelVersion: 3.17 +Contact: xfs@oss.sgi.com +Description: + The log sequence number (LSN) of the current tail of the + log. The LSN is exported in "cycle:basic block" format. + +What: /sys/fs/xfs/<disk>/log/reserve_grant_head +Date: July 2014 +KernelVersion: 3.17 +Contact: xfs@oss.sgi.com +Description: + The current state of the log reserve grant head. It + represents the total log reservation of all currently + outstanding transactions. The grant head is exported in + "cycle:bytes" format. +Users: xfstests + +What: /sys/fs/xfs/<disk>/log/write_grant_head +Date: July 2014 +KernelVersion: 3.17 +Contact: xfs@oss.sgi.com +Description: + The current state of the log write grant head. It + represents the total log reservation of all currently + oustanding transactions, including regrants due to + rolling transactions. The grant head is exported in + "cycle:bytes" format. +Users: xfstests
diff --git a/Documentation/ABI/testing/sysfs-hypervisor-pmu b/Documentation/ABI/testing/sysfs-hypervisor-pmu new file mode 100644 index 0000000..224faa1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-hypervisor-pmu
@@ -0,0 +1,23 @@ +What: /sys/hypervisor/pmu/pmu_mode +Date: August 2015 +KernelVersion: 4.3 +Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com> +Description: + Describes mode that Xen's performance-monitoring unit (PMU) + uses. Accepted values are + "off" -- PMU is disabled + "self" -- The guest can profile itself + "hv" -- The guest can profile itself and, if it is + privileged (e.g. dom0), the hypervisor + "all" -- The guest can profile itself, the hypervisor + and all other guests. Only available to + privileged guests. + +What: /sys/hypervisor/pmu/pmu_features +Date: August 2015 +KernelVersion: 4.3 +Contact: Boris Ostrovsky <boris.ostrovsky@oracle.com> +Description: + Describes Xen PMU features (as an integer). A set bit indicates + that the corresponding feature is enabled. See + include/xen/interface/xenpmu.h for available features
diff --git a/Documentation/ABI/testing/sysfs-ibft b/Documentation/ABI/testing/sysfs-ibft new file mode 100644 index 0000000..7d6725f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-ibft
@@ -0,0 +1,33 @@ +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. + Usually this contains the IP address, MAC, and gateway of the NIC. + +What: /sys/firmware/ibft/acpi_header +Date: March 2016 +Contact: David Bond <dbond@suse.com> +Description: The /sys/firmware/ibft/acpi_header directory will contain files + that expose the SIGNATURE, OEM_ID, and OEM_TABLE_ID fields of the + acpi table header of the iBFT structure. This will allow for + identification of the creator of the table which is useful in + determining quirks associated with some adapters when used in + hardware vs software iscsi initiator mode.
diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params new file mode 100644 index 0000000..eca38ce --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-boot_params
@@ -0,0 +1,38 @@ +What: /sys/kernel/boot_params +Date: December 2013 +Contact: Dave Young <dyoung@redhat.com> +Description: The /sys/kernel/boot_params directory contains two + files: "data" and "version" and one subdirectory "setup_data". + It is used to export the kernel boot parameters of an x86 + platform to userspace for kexec and debugging purpose. + + If there's no setup_data in boot_params the subdirectory will + not be created. + + "data" file is the binary representation of struct boot_params. + + "version" file is the string representation of boot + protocol version. + + "setup_data" subdirectory contains the setup_data data + structure in boot_params. setup_data is maintained in kernel + as a link list. In "setup_data" subdirectory there's one + subdirectory for each link list node named with the number + of the list nodes. The list node subdirectory contains two + files "type" and "data". "type" file is the string + representation of setup_data type. "data" file is the binary + representation of setup_data payload. + + The whole boot_params directory structure is like below: + /sys/kernel/boot_params + |__ data + |__ setup_data + | |__ 0 + | | |__ data + | | |__ type + | |__ 1 + | |__ data + | |__ type + |__ version + +Users: Kexec
diff --git a/Documentation/ABI/testing/sysfs-kernel-fscaps b/Documentation/ABI/testing/sysfs-kernel-fscaps new file mode 100644 index 0000000..50a3033 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-fscaps
@@ -0,0 +1,8 @@ +What: /sys/kernel/fscaps +Date: February 2011 +KernelVersion: 2.6.38 +Contact: Ludwig Nussel <ludwig.nussel@suse.de> +Description + Shows whether file system capabilities are honored + when executing a binary +
diff --git a/Documentation/ABI/testing/sysfs-kernel-iommu_groups b/Documentation/ABI/testing/sysfs-kernel-iommu_groups new file mode 100644 index 0000000..9b31556 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-iommu_groups
@@ -0,0 +1,14 @@ +What: /sys/kernel/iommu_groups/ +Date: May 2012 +KernelVersion: v3.5 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: /sys/kernel/iommu_groups/ contains a number of sub- + directories, each representing an IOMMU group. The + name of the sub-directory matches the iommu_group_id() + for the group, which is an integer value. Within each + subdirectory is another directory named "devices" with + links to the sysfs devices contained in this group. + The group directory also optionally contains a "name" + file if the IOMMU driver has chosen to register a more + common name for the group. +Users:
diff --git a/Documentation/ABI/testing/sysfs-kernel-irq b/Documentation/ABI/testing/sysfs-kernel-irq new file mode 100644 index 0000000..eb074b1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-irq
@@ -0,0 +1,53 @@ +What: /sys/kernel/irq +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: Directory containing information about the system's IRQs. + Specifically, data from the associated struct irq_desc. + The information here is similar to that in /proc/interrupts + but in a more machine-friendly format. This directory contains + one subdirectory for each Linux IRQ number. + +What: /sys/kernel/irq/<irq>/actions +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: The IRQ action chain. A comma-separated list of zero or more + device names associated with this interrupt. + +What: /sys/kernel/irq/<irq>/chip_name +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: Human-readable chip name supplied by the associated device + driver. + +What: /sys/kernel/irq/<irq>/hwirq +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: When interrupt translation domains are used, this file contains + the underlying hardware IRQ number used for this Linux IRQ. + +What: /sys/kernel/irq/<irq>/name +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: Human-readable flow handler name as defined by the irq chip + driver. + +What: /sys/kernel/irq/<irq>/per_cpu_count +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: The number of times the interrupt has fired since boot. This + is a comma-separated list of counters; one per CPU in CPU id + order. NOTE: This file consistently shows counters for all + CPU ids. This differs from the behavior of /proc/interrupts + which only shows counters for online CPUs. + +What: /sys/kernel/irq/<irq>/type +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek <kraig@google.com> +Description: The type of the interrupt. Either the string 'level' or 'edge'.
diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch new file mode 100644 index 0000000..da87f43 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch
@@ -0,0 +1,48 @@ +What: /sys/kernel/livepatch +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + Interface for kernel live patching + + The /sys/kernel/livepatch directory contains subdirectories for + each loaded live patch module. + +What: /sys/kernel/livepatch/<patch> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The patch directory contains subdirectories for each kernel + object (vmlinux or a module) in which it patched functions. + +What: /sys/kernel/livepatch/<patch>/enabled +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + A writable attribute that indicates whether the patched + code is currently applied. Writing 0 will disable the patch + while writing 1 will re-enable the patch. + +What: /sys/kernel/livepatch/<patch>/<object> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The object directory contains subdirectories for each function + that is patched within the object. + +What: /sys/kernel/livepatch/<patch>/<object>/<function,sympos> +Date: Nov 2014 +KernelVersion: 3.19.0 +Contact: live-patching@vger.kernel.org +Description: + The function directory contains attributes regarding the + properties and state of the patched function. + + The directory name contains the patched function name and a + sympos number corresponding to the nth occurrence of the symbol + name in kallsyms for the patched object. + + There are currently no such attributes.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm b/Documentation/ABI/testing/sysfs-kernel-mm new file mode 100644 index 0000000..190d523 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm
@@ -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/.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages new file mode 100644 index 0000000..e21c005 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm new file mode 100644 index 0000000..73e653e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
@@ -0,0 +1,52 @@ +What: /sys/kernel/mm/ksm +Date: September 2009 +KernelVersion: 2.6.32 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Interface for Kernel Samepage Merging (KSM) + +What: /sys/kernel/mm/ksm/full_scans +What: /sys/kernel/mm/ksm/pages_shared +What: /sys/kernel/mm/ksm/pages_sharing +What: /sys/kernel/mm/ksm/pages_to_scan +What: /sys/kernel/mm/ksm/pages_unshared +What: /sys/kernel/mm/ksm/pages_volatile +What: /sys/kernel/mm/ksm/run +What: /sys/kernel/mm/ksm/sleep_millisecs +Date: September 2009 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Kernel Samepage Merging daemon sysfs interface + + full_scans: how many times all mergeable areas have been + scanned. + + pages_shared: how many shared pages are being used. + + pages_sharing: how many more sites are sharing them i.e. how + much saved. + + pages_to_scan: how many present pages to scan before ksmd goes + to sleep. + + pages_unshared: how many pages unique but repeatedly checked + for merging. + + pages_volatile: how many pages changing too fast to be placed + in a tree. + + run: write 0 to disable ksm, read 0 while ksm is disabled. + write 1 to run ksm, read 1 while ksm is running. + write 2 to disable ksm and unmerge all its pages. + + sleep_millisecs: how many milliseconds ksm should sleep between + scans. + + See Documentation/vm/ksm.txt for more information. + +What: /sys/kernel/mm/ksm/merge_across_nodes +Date: January 2013 +KernelVersion: 3.9 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Control merging pages across different NUMA nodes. + + When it is set to 0 only pages from the same node are merged, + otherwise pages from all nodes can be merged together (default).
diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab new file mode 100644 index 0000000..91bd6ca --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -0,0 +1,490 @@ +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 shows how many objects have been + allocated using the fast path. It can be written to clear the + current count. + 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 shows 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. It can be written to clear the current + count. + 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 shows how many times the per-cpu freelist + was empty but there were objects available as the result of + remote cpu frees. It can be written to clear the current count. + 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 shows how many times a new slab had to + be allocated from the page allocator. It can be written to + clear the current count. + 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 shows how many objects have been + allocated using the slow path because of a refill or + allocation from a partial or new slab. It can be written to + clear the current count. + 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 shows 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. It can be written to clear the + current count. + 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 deactivate_empty file shows how many times an empty cpu slab + was deactivated. It can be written to clear the current count. + 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 deactivate_full file shows how many times a full cpu slab + was deactivated. It can be written to clear the current count. + 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 deactivate_remote_frees file shows how many times a cpu slab + has been deactivated and contained free objects that were freed + remotely. It can be written to clear the current count. + 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 deactivate_to_head file shows how many times a partial cpu + slab was deactivated and added to the head of its node's partial + list. It can be written to clear the current count. + 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 deactivate_to_tail file shows how many times a partial cpu + slab was deactivated and added to the tail of its node's partial + list. It can be written to clear the current count. + 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 free_add_partial file shows how many times an object has + been freed in a full slab so that it had to added to its node's + partial list. It can be written to clear the current count. + 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 shows how many objects have been freed + using the fast path because it was an object from the cpu slab. + It can be written to clear the current count. + 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 shows how many objects have been freed to + a frozen slab (i.e. a remote cpu slab). It can be written to + clear the current count. + 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 free_remove_partial file shows 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. It can be written to clear the current + count. + 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 shows how many times an empty slab has been + freed back to the page allocator. It can be written to clear + the current count. + 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 shows how many objects have been freed + using the slow path (i.e. to a full or partial slab). It can + be written to clear the current count. + 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. + When debug_guardpage_minorder=N (N > 0) parameter is specified + (see Documentation/kernel-parameters.txt), the minimum possible + order is used and this sysfs entry can not be used to change + the order at run time. + +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 order_fallback file shows 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. It can be written to + clear the current count. + 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.
diff --git a/Documentation/ABI/testing/sysfs-kernel-uids b/Documentation/ABI/testing/sysfs-kernel-uids new file mode 100644 index 0000000..28f1469 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-uids
@@ -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
diff --git a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo new file mode 100644 index 0000000..7bd8116 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
@@ -0,0 +1,14 @@ +What: /sys/kernel/vmcoreinfo +Date: October 2007 +KernelVersion: 2.6.24 +Contact: Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp> + Kexec Mailing List <kexec@lists.infradead.org> + Vivek Goyal <vgoyal@redhat.com> +Description + Shows physical address and size of vmcoreinfo ELF note. + First value contains physical address of note in hex and + second value contains the size of note in hex. This ELF + note info is parsed by second kernel and exported to user + space as part of ELF note in /proc/vmcore file. This note + contains various information like struct size, symbol + values, page size etc.
diff --git a/Documentation/ABI/testing/sysfs-memory-page-offline b/Documentation/ABI/testing/sysfs-memory-page-offline new file mode 100644 index 0000000..e14703f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-memory-page-offline
@@ -0,0 +1,44 @@ +What: /sys/devices/system/memory/soft_offline_page +Date: Sep 2009 +KernelVersion: 2.6.33 +Contact: andi@firstfloor.org +Description: + Soft-offline the memory page containing the physical address + written into this file. Input is a hex number specifying the + physical address of the page. The kernel will then attempt + to soft-offline it, by moving the contents elsewhere or + dropping it if possible. The kernel will then be placed + on the bad page list and never be reused. + + The offlining is done in kernel specific granuality. + Normally it's the base page size of the kernel, but + this might change. + + The page must be still accessible, not poisoned. The + kernel will never kill anything for this, but rather + fail the offline. Return value is the size of the + number, or a error when the offlining failed. Reading + the file is not allowed. + +What: /sys/devices/system/memory/hard_offline_page +Date: Sep 2009 +KernelVersion: 2.6.33 +Contact: andi@firstfloor.org +Description: + Hard-offline the memory page containing the physical + address written into this file. Input is a hex number + specifying the physical address of the page. The + kernel will then attempt to hard-offline the page, by + trying to drop the page or killing any owner or + triggering IO errors if needed. Note this may kill + any processes owning the page. The kernel will avoid + to access this page assuming it's poisoned by the + hardware. + + The offlining is done in kernel specific granuality. + Normally it's the base page size of the kernel, but + this might change. + + Return value is the size of the number, or a error when + the offlining failed. + Reading the file is not allowed.
diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module new file mode 100644 index 0000000..0aac02e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-module
@@ -0,0 +1,52 @@ +What: /sys/module/pch_phub/drivers/.../pch_mac +Date: August 2010 +KernelVersion: 2.6.35 +Contact: masa-korg@dsn.okisemi.com +Description: Write/read GbE MAC address. + +What: /sys/module/pch_phub/drivers/.../pch_firmware +Date: August 2010 +KernelVersion: 2.6.35 +Contact: masa-korg@dsn.okisemi.com +Description: Write/read Option ROM data. + + +What: /sys/module/ehci_hcd/drivers/.../uframe_periodic_max +Date: July 2011 +KernelVersion: 3.1 +Contact: Kirill Smelkov <kirr@mns.spb.ru> +Description: Maximum time allowed for periodic transfers per microframe (μs) + + [ USB 2.0 sets maximum allowed time for periodic transfers per + microframe to be 80%, that is 100 microseconds out of 125 + microseconds (full microframe). + + However there are cases, when 80% max isochronous bandwidth is + too limiting. For example two video streams could require 110 + microseconds of isochronous bandwidth per microframe to work + together. ] + + Through this setting it is possible to raise the limit so that + the host controller would allow allocating more than 100 + microseconds of periodic bandwidth per microframe. + + Beware, non-standard modes are usually not thoroughly tested by + hardware designers, and the hardware can malfunction when this + setting differ from default 100. + +What: /sys/module/*/{coresize,initsize} +Date: Jan 2012 +KernelVersion:»·3.3 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: Module size in bytes. + +What: /sys/module/*/taint +Date: Jan 2012 +KernelVersion:»·3.3 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: Module taint flags: + P - proprietary module + O - out-of-tree module + F - force-loaded module + C - staging driver module + E - unsigned module
diff --git a/Documentation/ABI/testing/sysfs-ocfs2 b/Documentation/ABI/testing/sysfs-ocfs2 new file mode 100644 index 0000000..b7cc516 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-ocfs2
@@ -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>
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop new file mode 100644 index 0000000..cd9d667 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -0,0 +1,66 @@ +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 items of information. + 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 wlan device. 1 means on, 0 means off. + This may control the led, the device or both. +Users: Lapsus + +What: /sys/devices/platform/asus_laptop/wimax +Date: October 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the wimax device. 1 means on, 0 means off. + +What: /sys/devices/platform/asus_laptop/wwan +Date: October 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the wwan (3G) device. 1 means on, 0 means off.
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi new file mode 100644 index 0000000..019e1e2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi
@@ -0,0 +1,38 @@ +What: /sys/devices/platform/<platform>/cpufv +Date: Oct 2010 +KernelVersion: 2.6.37 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Change CPU clock configuration (write-only). + There are three available clock configuration: + * 0 -> Super Performance Mode + * 1 -> High Performance Mode + * 2 -> Power Saving Mode + +What: /sys/devices/platform/<platform>/camera +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the camera. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/cardr +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the card reader. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/touchpad +Date: Jan 2010 +KernelVersion: 2.6.39 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + Control the card touchpad. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/lid_resume +Date: May 2012 +KernelVersion: 3.5 +Contact: "AceLan Kao" <acelan.kao@canonical.com> +Description: + Resume on lid open. 1 means on, 0 means off.
diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91 new file mode 100644 index 0000000..4cc6a86 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-at91
@@ -0,0 +1,25 @@ +What: /sys/devices/platform/at91_can/net/<iface>/mb0_id +Date: January 2011 +KernelVersion: 2.6.38 +Contact: Marc Kleine-Budde <kernel@pengutronix.de> +Description: + Value representing the can_id of mailbox 0. + + Default: 0x7ff (standard frame) + + Due to a chip bug (errata 50.2.6.3 & 50.3.5.3 in + "AT91SAM9263 Preliminary 6249H-ATARM-27-Jul-09") the + contents of mailbox 0 may be send under certain + conditions (even if disabled or in rx mode). + + The workaround in the errata suggests not to use the + mailbox and load it with an unused identifier. + + In order to use an extended can_id add the + CAN_EFF_FLAG (0x80000000U) to the can_id. Example: + + - standard id 0x7ff: + echo 0x7ff > /sys/class/net/can0/mb0_id + + - extended id 0x1fffffff: + echo 0x9fffffff > /sys/class/net/can0/mb0_id
diff --git a/Documentation/ABI/testing/sysfs-platform-brcmstb-gisb-arb b/Documentation/ABI/testing/sysfs-platform-brcmstb-gisb-arb new file mode 100644 index 0000000..f1bad92 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-brcmstb-gisb-arb
@@ -0,0 +1,8 @@ +What: /sys/devices/../../gisb_arb_timeout +Date: May 2014 +KernelVersion: 3.17 +Contact: Florian Fainelli <f.fainelli@gmail.com> +Description: + Returns the currently configured raw timeout value of the + Broadcom Set Top Box internal GISB bus arbiter. Minimum value + is 1, and maximum value is 0xffffffff.
diff --git a/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg new file mode 100644 index 0000000..151c595 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg
@@ -0,0 +1,56 @@ +What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req +Date: Feb 2014 +Contact: Li Jun <b47624@freescale.com> +Description: + Can be set and read. + Set a_bus_req(A-device bus request) input to be 1 if + the application running on the A-device wants to use the bus, + and to be 0 when the application no longer wants to use + the bus(or wants to work as peripheral). a_bus_req can also + be set to 1 by kernel in response to remote wakeup signaling + from the B-device, the A-device should decide to resume the bus. + + Valid values are "1" and "0". + + Reading: returns 1 if the application running on the A-device + is using the bus as host role, otherwise 0. + +What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop +Date: Feb 2014 +Contact: Li Jun <b47624@freescale.com> +Description: + Can be set and read + The a_bus_drop(A-device bus drop) input is 1 when the + application running on the A-device wants to power down + the bus, and is 0 otherwise, When a_bus_drop is 1, then + the a_bus_req shall be 0. + + Valid values are "1" and "0". + + Reading: returns 1 if the bus is off(vbus is turned off) by + A-device, otherwise 0. + +What: /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req +Date: Feb 2014 +Contact: Li Jun <b47624@freescale.com> +Description: + Can be set and read. + The b_bus_req(B-device bus request) input is 1 during the time + that the application running on the B-device wants to use the + bus as host, and is 0 when the application no longer wants to + work as host and decides to switch back to be peripheral. + + Valid values are "1" and "0". + + Reading: returns if the application running on the B device + is using the bus as host role, otherwise 0. + +What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_clr_err +Date: Feb 2014 +Contact: Li Jun <b47624@freescale.com> +Description: + Only can be set. + The a_clr_err(A-device Vbus error clear) input is used to clear + vbus error, then A-device will power down the bus. + + Valid value is "1"
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop new file mode 100644 index 0000000..8c6a0b8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop
@@ -0,0 +1,69 @@ +What: /sys/class/leds/dell::kbd_backlight/als_enabled +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to control the automatic keyboard + illumination mode on some systems that have an ambient + light sensor. Write 1 to this file to enable the auto + mode, 0 to disable it. + +What: /sys/class/leds/dell::kbd_backlight/als_setting +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to specifiy the on/off threshold value, + as reported by the ambient light sensor. + +What: /sys/class/leds/dell::kbd_backlight/start_triggers +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to control the input triggers that + turn on the keyboard backlight illumination that is + disabled because of inactivity. + Read the file to see the triggers available. The ones + enabled are preceded by '+', those disabled by '-'. + + To enable a trigger, write its name preceded by '+' to + this file. To disable a trigger, write its name preceded + by '-' instead. + + For example, to enable the keyboard as trigger run: + echo +keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers + To disable it: + echo -keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers + + Note that not all the available triggers can be configured. + +What: /sys/class/leds/dell::kbd_backlight/stop_timeout +Date: December 2014 +KernelVersion: 3.19 +Contact: Gabriele Mazzotta <gabriele.mzt@gmail.com>, + Pali Rohár <pali.rohar@gmail.com> +Description: + This file allows to specify the interval after which the + keyboard illumination is disabled because of inactivity. + The timeouts are expressed in seconds, minutes, hours and + days, for which the symbols are 's', 'm', 'h' and 'd' + respectively. + + To configure the timeout, write to this file a value along + with any the above units. If no unit is specified, the value + is assumed to be expressed in seconds. + + For example, to set the timeout to 10 minutes run: + echo 10m > /sys/class/leds/dell::kbd_backlight/stop_timeout + + Note that when this file is read, the returned value might be + expressed in a different unit than the one used when the timeout + was set. + + Also note that only some timeouts are supported and that + some systems might fall back to a specific timeout in case + an invalid timeout is written to this file.
diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop new file mode 100644 index 0000000..5b026c6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
@@ -0,0 +1,50 @@ +What: /sys/devices/platform/eeepc/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/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/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/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/available_cpufv +Date: Jun 2009 +KernelVersion: 2.6.31 +Contact: "Corentin Chary" <corentincj@iksaif.net> +Description: + List available cpufv modes.
diff --git a/Documentation/ABI/testing/sysfs-platform-hidma b/Documentation/ABI/testing/sysfs-platform-hidma new file mode 100644 index 0000000..d364415 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-hidma
@@ -0,0 +1,9 @@ +What: /sys/devices/platform/hidma-*/chid + /sys/devices/platform/QCOM8061:*/chid +Date: Dec 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains the ID of the channel within the HIDMA instance. + It is used to associate a given HIDMA channel with the + priority and weight calls in the management interface.
diff --git a/Documentation/ABI/testing/sysfs-platform-hidma-mgmt b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt new file mode 100644 index 0000000..c2fb5d0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-hidma-mgmt
@@ -0,0 +1,97 @@ +What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/priority + /sys/devices/platform/QCOM8060:*/chanops/chan*/priority +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains either 0 or 1 and indicates if the DMA channel is a + low priority (0) or high priority (1) channel. + +What: /sys/devices/platform/hidma-mgmt*/chanops/chan*/weight + /sys/devices/platform/QCOM8060:*/chanops/chan*/weight +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains 0..15 and indicates the weight of the channel among + equal priority channels during round robin scheduling. + +What: /sys/devices/platform/hidma-mgmt*/chreset_timeout_cycles + /sys/devices/platform/QCOM8060:*/chreset_timeout_cycles +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains the platform specific cycle value to wait after a + reset command is issued. If the value is chosen too short, + then the HW will issue a reset failure interrupt. The value + is platform specific and should not be changed without + consultance. + +What: /sys/devices/platform/hidma-mgmt*/dma_channels + /sys/devices/platform/QCOM8060:*/dma_channels +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains the number of dma channels supported by one instance + of HIDMA hardware. The value may change from chip to chip. + +What: /sys/devices/platform/hidma-mgmt*/hw_version_major + /sys/devices/platform/QCOM8060:*/hw_version_major +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Version number major for the hardware. + +What: /sys/devices/platform/hidma-mgmt*/hw_version_minor + /sys/devices/platform/QCOM8060:*/hw_version_minor +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Version number minor for the hardware. + +What: /sys/devices/platform/hidma-mgmt*/max_rd_xactions + /sys/devices/platform/QCOM8060:*/max_rd_xactions +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains a value between 0 and 31. Maximum number of + read transactions that can be issued back to back. + Choosing a higher number gives better performance but + can also cause performance reduction to other peripherals + sharing the same bus. + +What: /sys/devices/platform/hidma-mgmt*/max_read_request + /sys/devices/platform/QCOM8060:*/max_read_request +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Size of each read request. The value needs to be a power + of two and can be between 128 and 1024. + +What: /sys/devices/platform/hidma-mgmt*/max_wr_xactions + /sys/devices/platform/QCOM8060:*/max_wr_xactions +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Contains a value between 0 and 31. Maximum number of + write transactions that can be issued back to back. + Choosing a higher number gives better performance but + can also cause performance reduction to other peripherals + sharing the same bus. + + +What: /sys/devices/platform/hidma-mgmt*/max_write_request + /sys/devices/platform/QCOM8060:*/max_write_request +Date: Nov 2015 +KernelVersion: 4.4 +Contact: "Sinan Kaya <okaya@cudeaurora.org>" +Description: + Size of each write request. The value needs to be a power + of two and can be between 128 and 1024.
diff --git a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl new file mode 100644 index 0000000..3c35148 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
@@ -0,0 +1,18 @@ +What: /sys/devices/platform/<i2c-demux-name>/available_masters +Date: January 2016 +KernelVersion: 4.6 +Contact: Wolfram Sang <wsa@the-dreams.de> +Description: + Reading the file will give you a list of masters which can be + selected for a demultiplexed bus. The format is + "<index>:<name>". Example from a Renesas Lager board: + + 0:/i2c@e6500000 1:/i2c@e6508000 + +What: /sys/devices/platform/<i2c-demux-name>/current_master +Date: January 2016 +KernelVersion: 4.6 +Contact: Wolfram Sang <wsa@the-dreams.de> +Description: + This file selects/shows the active I2C master for a demultiplexed + bus. It uses the <index> value from the file 'available_masters'.
diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop new file mode 100644 index 0000000..b31e782 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
@@ -0,0 +1,19 @@ +What: /sys/devices/platform/ideapad/camera_power +Date: Dec 2010 +KernelVersion: 2.6.37 +Contact: "Ike Panhc <ike.pan@canonical.com>" +Description: + Control the power of camera module. 1 means on, 0 means off. + +What: /sys/devices/platform/ideapad/fan_mode +Date: June 2012 +KernelVersion: 3.6 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Change fan mode + There are four available modes: + * 0 -> Super Silent Mode + * 1 -> Standard Mode + * 2 -> Dust Cleaning + * 4 -> Efficient Thermal Dissipation Mode +
diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim new file mode 100644 index 0000000..c165327 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-kim
@@ -0,0 +1,48 @@ +What: /sys/devices/platform/kim/dev_name +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + Name of the UART device at which the WL128x chip + is connected. example: "/dev/ttyS0". + The device name flows down to architecture specific board + initialization file from the SFI/ATAGS bootloader + firmware. The name exposed is read from the user-space + dameon and opens the device when install is requested. + +What: /sys/devices/platform/kim/baud_rate +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The maximum reliable baud-rate the host can support. + Different platforms tend to have different high-speed + UART configurations, so the baud-rate needs to be set + locally and also sent across to the WL128x via a HCI-VS + command. The entry is read and made use by the user-space + daemon when the ldisc install is requested. + +What: /sys/devices/platform/kim/flow_cntrl +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + The WL128x makes use of flow control mechanism, and this + entry most often should be 1, the host's UART is required + to have the capability of flow-control, or else this + entry can be made use of for exceptions. + +What: /sys/devices/platform/kim/install +Date: January 2010 +KernelVersion: 2.6.38 +Contact: "Pavan Savoy" <pavan_savoy@ti.com> +Description: + When one of the protocols Bluetooth, FM or GPS wants to make + use of the shared UART transport, it registers to the shared + transport driver, which will signal the user-space for opening, + configuring baud and install line discipline via this sysfs + entry. This entry would be polled upon by the user-space + daemon managing the UART, and is notified about the change + by the sysfs_notify. The value would be '1' when UART needs + to be opened/ldisc installed, and would be '0' when UART + is no more required and needs to be closed.
diff --git a/Documentation/ABI/testing/sysfs-platform-msi-laptop b/Documentation/ABI/testing/sysfs-platform-msi-laptop new file mode 100644 index 0000000..307a247 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-msi-laptop
@@ -0,0 +1,83 @@ +What: /sys/devices/platform/msi-laptop-pf/lcd_level +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Screen brightness: contains a single integer in the range 0..8. + +What: /sys/devices/platform/msi-laptop-pf/auto_brightness +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Enable automatic brightness control: contains either 0 or 1. If + set to 1 the hardware adjusts the screen brightness + automatically when the power cord is plugged/unplugged. + +What: /sys/devices/platform/msi-laptop-pf/wlan +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + WLAN subsystem enabled: contains either 0 or 1. + +What: /sys/devices/platform/msi-laptop-pf/bluetooth +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Bluetooth subsystem enabled: contains either 0 or 1. Please + note that this file is constantly 0 if no Bluetooth hardware is + available. + +What: /sys/devices/platform/msi-laptop-pf/touchpad +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if touchpad is turned on. + Touchpad state can only be toggled by pressing Fn+F3. + +What: /sys/devices/platform/msi-laptop-pf/turbo_mode +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if turbo mode is turned + on. In turbo mode power LED is orange and processor is + overclocked. Turbo mode is available only if charging. It is + only possible to toggle turbo mode state by pressing Fn+F10, + and there is a few seconds cooldown between subsequent toggles. + If user presses Fn+F10 too frequent, turbo mode state is not + changed. + +What: /sys/devices/platform/msi-laptop-pf/eco_mode +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if ECO mode is turned on. + In ECO mode power LED is green and userspace should do some + powersaving actions. ECO mode is available only on battery + power. ECO mode can only be toggled by pressing Fn+F10. + +What: /sys/devices/platform/msi-laptop-pf/turbo_cooldown +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains value in range 0..3: + * 0 -> Turbo mode is off + * 1 -> Turbo mode is on, cannot be turned off yet + * 2 -> Turbo mode is off, cannot be turned on yet + * 3 -> Turbo mode is on + +What: /sys/devices/platform/msi-laptop-pf/auto_fan +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if fan speed is controlled + automatically (1) or fan runs at maximal speed (0). Can be + toggled in software. +
diff --git a/Documentation/ABI/testing/sysfs-platform-tahvo-usb b/Documentation/ABI/testing/sysfs-platform-tahvo-usb new file mode 100644 index 0000000..f6e20ce --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-tahvo-usb
@@ -0,0 +1,16 @@ +What: /sys/bus/platform/devices/tahvo-usb/otg_mode +Date: December 2013 +Contact: Aaro Koskinen <aaro.koskinen@iki.fi> +Description: + Set or read the current OTG mode. Valid values are "host" and + "peripheral". + + Reading: returns the current mode. + +What: /sys/bus/platform/devices/tahvo-usb/vbus +Date: December 2013 +Contact: Aaro Koskinen <aaro.koskinen@iki.fi> +Description: + Read the current VBUS state. + + Reading: returns "on" or "off".
diff --git a/Documentation/ABI/testing/sysfs-platform-ts5500 b/Documentation/ABI/testing/sysfs-platform-ts5500 new file mode 100644 index 0000000..e685957 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-ts5500
@@ -0,0 +1,54 @@ +What: /sys/devices/platform/ts5500/adc +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of an A/D Converter. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/ereset +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of an external reset. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/id +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Product ID of the TS board. TS-5500 ID is 0x60. + +What: /sys/devices/platform/ts5500/jumpers +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Bitfield showing the jumpers' state. If a jumper is present, + the corresponding bit is set. For instance, 0x0e means jumpers + 2, 3 and 4 are set. + +What: /sys/devices/platform/ts5500/name +Date: July 2014 +KernelVersion: 3.16 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Model name of the TS board, e.g. "TS-5500". + +What: /sys/devices/platform/ts5500/rs485 +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of the RS485 option. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/sram +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of the SRAM option. If it is present, + it will display "1", otherwise "0".
diff --git a/Documentation/ABI/testing/sysfs-platform-twl4030-usb b/Documentation/ABI/testing/sysfs-platform-twl4030-usb new file mode 100644 index 0000000..512c51b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-twl4030-usb
@@ -0,0 +1,8 @@ +What: /sys/bus/platform/devices/*twl4030-usb/vbus +Description: + Read-only status reporting if VBUS (approx 5V) + is being supplied by the USB bus. + + Possible values: "on", "off". + + Changes are notified via select/poll.
diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc new file mode 100644 index 0000000..81fcfb4 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
@@ -0,0 +1,35 @@ +What: /sys/devices/platform/usbip-vudc.%d/dev_desc +Date: April 2016 +KernelVersion: 4.6 +Contact: Krzysztof Opasiak <k.opasiak@samsung.com> +Description: + This file allows to read device descriptor of + gadget driver which is currently bound to this + controller. It is possible to read this file + only if gadget driver is bound, otherwise error + is returned. + +What: /sys/devices/platform/usbip-vudc.%d/usbip_status +Date: April 2016 +KernelVersion: 4.6 +Contact: Krzysztof Opasiak <k.opasiak@samsung.com> +Description: + Current status of the device. + Allowed values: + 1 - Device is available and can be exported + 2 - Device is currently exported + 3 - Fatal error occurred during communication + with peer + +What: /sys/devices/platform/usbip-vudc.%d/usbip_sockfd +Date: April 2016 +KernelVersion: 4.6 +Contact: Krzysztof Opasiak <k.opasiak@samsung.com> +Description: + This file allows to export usb device to + connection peer. It is done by writing to this + file socket fd (as a string for example "8") + associated with a connection to remote peer who + would like to use this device. It is possible to + close the connection by writing -1 instead of + socked fd.
diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power new file mode 100644 index 0000000..50b368d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-power
@@ -0,0 +1,270 @@ +What: /sys/power/ +Date: August 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power directory will contain files that will + provide a unified interface to the power management + subsystem. + +What: /sys/power/state +Date: May 2014 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/state file controls system sleep states. + Reading from this file returns the available sleep state + labels, which may be "mem", "standby", "freeze" and "disk" + (hibernation). The meanings of the first three labels depend on + the relative_sleep_states command line argument as follows: + 1) relative_sleep_states = 1 + "mem", "standby", "freeze" represent non-hibernation sleep + states from the deepest ("mem", always present) to the + shallowest ("freeze"). "standby" and "freeze" may or may + not be present depending on the capabilities of the + platform. "freeze" can only be present if "standby" is + present. + 2) relative_sleep_states = 0 (default) + "mem" - "suspend-to-RAM", present if supported. + "standby" - "power-on suspend", present if supported. + "freeze" - "suspend-to-idle", always present. + + Writing to this file one of these strings causes the system to + transition into the corresponding state, if available. See + Documentation/power/states.txt for a description of what + "suspend-to-RAM", "power-on suspend" and "suspend-to-idle" mean. + +What: /sys/power/disk +Date: September 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +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@rjwysocki.net> +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@rjwysocki.net> +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' + + If you do not get any matches (or they appear to be false + positives), it is possible that the last PM event point + referred to a device created by a loadable kernel module. In + this case cat /sys/power/pm_trace_dev_match (see below) after + your system is started up and the kernel modules are loaded. + + CAUTION: Using it will cause your machine's real-time (CMOS) + clock to be set to a random invalid time after a resume. + +What; /sys/power/pm_trace_dev_match +Date: October 2010 +Contact: James Hogan <james@albanarts.com> +Description: + The /sys/power/pm_trace_dev_match file contains the name of the + device associated with the last PM event point saved in the RTC + across reboots when pm_trace has been used. More precisely it + contains the list of current devices (including those + registered by loadable kernel modules since boot) which match + the device hash in the RTC at boot, with a newline after each + one. + + The advantage of this file over the hash matches printed to the + kernel log (see /sys/power/pm_trace), is that it includes + devices created after boot by loadable kernel modules. + + Due to the small hash size necessary to fit in the RTC, it is + possible that more than one device matches the hash, in which + case further investigation is required to determine which + device is causing the problem. Note that genuine RTC clock + values (such as when pm_trace has not been used), can still + match a device and output it's name here. + +What: /sys/power/pm_async +Date: January 2009 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/pm_async file controls the switch allowing the + user space to enable or disable asynchronous suspend and resume + of devices. If enabled, this feature will cause some device + drivers' suspend and resume callbacks to be executed in parallel + with each other and with the main suspend thread. It is enabled + if this file contains "1", which is the default. It may be + disabled by writing "0" to this file, in which case all devices + will be suspended and resumed synchronously. + +What: /sys/power/wakeup_count +Date: July 2010 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/wakeup_count file allows user space to put the + system into a sleep state while taking into account the + concurrent arrival of wakeup events. Reading from it returns + the current number of registered wakeup events and it blocks if + some wakeup events are being processed at the time the file is + read from. Writing to it will only succeed if the current + number of wakeup events is equal to the written value and, if + successful, will make the kernel abort a subsequent transition + to a sleep state if any wakeup events are reported after the + write has returned. + +What: /sys/power/reserved_size +Date: May 2011 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/reserved_size file allows user space to control + the amount of memory reserved for allocations made by device + drivers during the "device freeze" stage of hibernation. It can + be written a string representing a non-negative integer that + will be used as the amount of memory to reserve for allocations + made by device drivers' "freeze" callbacks, in bytes. + + Reading from this file will display the current value, which is + set to 1 MB by default. + +What: /sys/power/autosleep +Date: April 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/autosleep file can be written one of the strings + returned by reads from /sys/power/state. If that happens, a + work item attempting to trigger a transition of the system to + the sleep state represented by that string is queued up. This + attempt will only succeed if there are no active wakeup sources + in the system at that time. After every execution, regardless + of whether or not the attempt to put the system to sleep has + succeeded, the work item requeues itself until user space + writes "off" to /sys/power/autosleep. + + Reading from this file causes the last string successfully + written to it to be returned. + +What: /sys/power/wake_lock +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/wake_lock file allows user space to create + wakeup source objects and activate them on demand (if one of + those wakeup sources is active, reads from the + /sys/power/wakeup_count file block or return false). When a + string without white space is written to /sys/power/wake_lock, + it will be assumed to represent a wakeup source name. If there + is a wakeup source object with that name, it will be activated + (unless active already). Otherwise, a new wakeup source object + will be registered, assigned the given name and activated. + If a string written to /sys/power/wake_lock contains white + space, the part of the string preceding the white space will be + regarded as a wakeup source name and handled as descrived above. + The other part of the string will be regarded as a timeout (in + nanoseconds) such that the wakeup source will be automatically + deactivated after it has expired. The timeout, if present, is + set regardless of the current state of the wakeup source object + in question. + + Reads from this file return a string consisting of the names of + wakeup sources created with the help of it that are active at + the moment, separated with spaces. + + +What: /sys/power/wake_unlock +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/wake_unlock file allows user space to deactivate + wakeup sources created with the help of /sys/power/wake_lock. + When a string is written to /sys/power/wake_unlock, it will be + assumed to represent the name of a wakeup source to deactivate. + If a wakeup source object of that name exists and is active at + the moment, it will be deactivated. + + Reads from this file return a string consisting of the names of + wakeup sources created with the help of /sys/power/wake_lock + that are inactive at the moment, separated with spaces. + +What: /sys/power/pm_print_times +Date: May 2012 +Contact: Sameer Nanda <snanda@chromium.org> +Description: + The /sys/power/pm_print_times file allows user space to + control whether the time taken by devices to suspend and + resume is printed. These prints are useful for hunting down + devices that take too long to suspend or resume. + + Writing a "1" enables this printing while writing a "0" + disables it. The default value is "0". Reading from this file + will display the current value. + +What: /sys/power/pm_wakeup_irq +Date: April 2015 +Contact: Alexandra Yates <alexandra.yates@linux.intel.org> +Description: + The /sys/power/pm_wakeup_irq file reports to user space the IRQ + number of the first wakeup interrupt (that is, the first + interrupt from an IRQ line armed for system wakeup) seen by the + kernel during the most recent system suspend/resume cycle. + + This output is useful for system wakeup diagnostics of spurious + wakeup interrupts.
diff --git a/Documentation/ABI/testing/sysfs-pps b/Documentation/ABI/testing/sysfs-pps new file mode 100644 index 0000000..25028c7 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-pps
@@ -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.
diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling new file mode 100644 index 0000000..8a8e466 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-profiling
@@ -0,0 +1,13 @@ +What: /sys/kernel/profiling +Date: September 2008 +Contact: Dave Hansen <dave@linux.vnet.ibm.com> +Description: + /sys/kernel/profiling is the runtime equivalent + of the boot-time profile= option. + + You can get the same effect running: + + echo 2 > /sys/kernel/profiling + + as you would by issuing profile=2 on the boot + command line.
diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp new file mode 100644 index 0000000..a17f817 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-ptp
@@ -0,0 +1,122 @@ +What: /sys/class/ptp/ +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This directory contains files and directories + providing a standardized interface to the ancillary + features of PTP hardware clocks. + +What: /sys/class/ptp/ptpN/ +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This directory contains the attributes of the Nth PTP + hardware clock registered into the PTP class driver + subsystem. + +What: /sys/class/ptp/ptpN/clock_name +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the name of the PTP hardware clock + as a human readable string. The purpose of this + attribute is to provide the user with a "friendly + name" and to help distinguish PHY based devices from + MAC based ones. The string does not necessarily have + to be any kind of unique id. + +What: /sys/class/ptp/ptpN/max_adjustment +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the PTP hardware clock's maximum + frequency adjustment value (a positive integer) in + parts per billion. + +What: /sys/class/ptp/ptpN/n_alarms +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the number of periodic or one shot + alarms offer by the PTP hardware clock. + +What: /sys/class/ptp/ptpN/n_external_timestamps +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the number of external timestamp + channels offered by the PTP hardware clock. + +What: /sys/class/ptp/ptpN/n_periodic_outputs +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the number of programmable periodic + output channels offered by the PTP hardware clock. + +What: /sys/class/ptp/ptpN/n_pins +Date: March 2014 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file contains the number of programmable pins + offered by the PTP hardware clock. + +What: /sys/class/ptp/ptpN/pins +Date: March 2014 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This directory contains one file for each programmable + pin offered by the PTP hardware clock. The file name + is the hardware dependent pin name. Reading from this + file produces two numbers, the assigned function (see + the PTP_PF_ enumeration values in linux/ptp_clock.h) + and the channel number. The function and channel + assignment may be changed by two writing numbers into + the file. + +What: /sys/class/ptp/ptpN/pps_available +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file indicates whether the PTP hardware clock + supports a Pulse Per Second to the host CPU. Reading + "1" means that the PPS is supported, while "0" means + not supported. + +What: /sys/class/ptp/ptpN/extts_enable +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This write-only file enables or disables external + timestamps. To enable external timestamps, write the + channel index followed by a "1" into the file. + To disable external timestamps, write the channel + index followed by a "0" into the file. + +What: /sys/class/ptp/ptpN/fifo +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This file provides timestamps on external events, in + the form of three integers: channel index, seconds, + and nanoseconds. + +What: /sys/class/ptp/ptpN/period +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This write-only file enables or disables periodic + outputs. To enable a periodic output, write five + integers into the file: channel index, start time + seconds, start time nanoseconds, period seconds, and + period nanoseconds. To disable a periodic output, set + all the seconds and nanoseconds values to zero. + +What: /sys/class/ptp/ptpN/pps_enable +Date: September 2010 +Contact: Richard Cochran <richardcochran@gmail.com> +Description: + This write-only file enables or disables delivery of + PPS events to the Linux PPS subsystem. To enable PPS + events, write a "1" into the file. To disable events, + write a "0" into the file.
diff --git a/Documentation/ABI/testing/sysfs-tty b/Documentation/ABI/testing/sysfs-tty new file mode 100644 index 0000000..9eb3c2b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-tty
@@ -0,0 +1,156 @@ +What: /sys/class/tty/console/active +Date: Nov 2010 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: + Shows the list of currently configured + console devices, like 'tty1 ttyS0'. + The last entry in the file is the active + device connected to /dev/console. + The file supports poll() to detect virtual + console switches. + +What: /sys/class/tty/tty0/active +Date: Nov 2010 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: + Shows the currently active virtual console + device, like 'tty1'. + The file supports poll() to detect virtual + console switches. + +What: /sys/class/tty/ttyS0/uartclk +Date: Sep 2012 +Contact: Tomas Hlavacek <tmshlvck@gmail.com> +Description: + Shows the current uartclk value associated with the + UART port in serial_core, that is bound to TTY like ttyS0. + uartclk = 16 * baud_base + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/type +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty type for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/line +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty line number for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/port +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty port I/O address for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/irq +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current primary interrupt for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/flags +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the tty port status flags for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/xmit_fifo_size +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the transmit FIFO size for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/close_delay +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the closing delay time for this port in ms. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/closing_wait +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the close wait time for this port in ms. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/custom_divisor +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the custom divisor if any that is set on this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/io_type +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the I/O type that is to be used with the iomem base + address. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/iomem_base +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + The I/O memory base for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/iomem_reg_shift +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the register shift indicating the spacing to be used + for accesses on this iomem address. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/rx_trig_bytes +Date: May 2014 +Contact: Yoshihiro YUNOMAE <yoshihiro.yunomae.ez@hitachi.com> +Description: + Shows current RX interrupt trigger bytes or sets the + user specified value to change it for the FIFO buffer. + Users can show or set this value regardless of opening the + serial device file or not. + + The RX trigger can be set one of four kinds of values for UART + serials. When users input a meaning less value to this I/F, + the RX trigger is changed to the nearest lower value for the + device specification. For example, when user sets 7bytes on + 16550A, which has 1/4/8/14 bytes trigger, the RX trigger is + automatically changed to 4 bytes.
diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf new file mode 100644 index 0000000..a99c5f8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-wusb_cbaf
@@ -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.
diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING new file mode 100644 index 0000000..65022a8 --- /dev/null +++ b/Documentation/BUG-HUNTING
@@ -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.
diff --git a/Documentation/Changes b/Documentation/Changes new file mode 100644 index 0000000..22797a1 --- /dev/null +++ b/Documentation/Changes
@@ -0,0 +1,485 @@ +.. _changes: + +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + +Intro +===== + +This document is designed to provide a list of the minimum levels of +software necessary to run the 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 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. + +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version +====================== =============== ======================================== + +.. [#f1] Sphinx is needed only to build the Kernel documentation + +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. + +BC +-- + +You will need bc to build kernels 3.10 and higher + + +OpenSSL +------- + +Module signing and external certificate handling use the OpenSSL program and +crypto library to do key creation and signature generation. + +You will need openssl to build kernels 3.7 and higher if module signing is +enabled. You will also need openssl development packages to build kernels 4.3 +and higher. + + +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. +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: + +- ``fsck.jfs`` - initiate replay of the transaction log, and check + and repair a JFS formatted partition. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- 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``. 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. + +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. + +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 ancient (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 modern kernels 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 +------ + +On x86 kernels the mcelog utility is needed to process and log machine check +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. + +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. + +Getting updated software +======================== + +Kernel compilation +****************** + +gcc +--- + +- <ftp://ftp.gnu.org/gnu/gcc/> + +Make +---- + +- <ftp://ftp.gnu.org/gnu/make/> + +Binutils +-------- + +- <ftp://ftp.kernel.org/pub/linux/devel/binutils/> + +OpenSSL +------- + +- <https://www.openssl.org/> + +System utilities +**************** + +Util-linux +---------- + +- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> + +Ksymoops +-------- + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> + +Module-Init-Tools +----------------- + +- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> + +Mkinitrd +-------- + +- <https://code.launchpad.net/initrd-tools/main> + +E2fsprogs +--------- + +- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> + +JFSutils +-------- + +- <http://jfs.sourceforge.net/> + +Reiserfsprogs +------------- + +- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> + +Xfsprogs +-------- + +- <ftp://oss.sgi.com/projects/xfs/> + +Pcmciautils +----------- + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> + +Quota-tools +----------- + +- <http://sourceforge.net/projects/linuxquota/> + +DocBook Stylesheets +------------------- + +- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> + +XMLTO XSLT Frontend +------------------- + +- <http://cyberelk.net/tim/xmlto/> + +Intel P6 microcode +------------------ + +- <https://downloadcenter.intel.com/> + +udev +---- + +- <http://www.freedesktop.org/software/systemd/man/udev.html> + +FUSE +---- + +- <http://sourceforge.net/projects/fuse> + +mcelog +------ + +- <http://www.mcelog.org/> + +Networking +********** + +PPP +--- + +- <ftp://ftp.samba.org/pub/ppp/> + +Isdn4k-utils +------------ + +- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> + +NFS-utils +--------- + +- <http://sourceforge.net/project/showfiles.php?group_id=14> + +Iptables +-------- + +- <http://www.iptables.org/downloads.html> + +Ip-route2 +--------- + +- <https://www.kernel.org/pub/linux/utils/net/iproute2/> + +OProfile +-------- + +- <http://oprofile.sf.net/download/> + +NFS-Utils +--------- + +- <http://nfs.sourceforge.net/> + +Kernel documentation +******************** + +Sphinx +------ + +- <http://www.sphinx-doc.org/>
diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict new file mode 100644 index 0000000..49a8ecc --- /dev/null +++ b/Documentation/CodeOfConflict
@@ -0,0 +1,27 @@ +Code of Conflict +---------------- + +The Linux kernel development effort is a very personal process compared +to "traditional" ways of developing software. Your code and ideas +behind it will be carefully reviewed, often resulting in critique and +criticism. The review will almost always require improvements to the +code before it can be included in the kernel. Know that this happens +because everyone involved wants to see the best possible solution for +the overall success of Linux. This development process has been proven +to create the most robust operating system kernel ever, and we do not +want to do anything to cause the quality of submission and eventual +result to ever decrease. + +If however, anyone feels personally abused, threatened, or otherwise +uncomfortable due to this process, that is not acceptable. If so, +please contact the Linux Foundation's Technical Advisory Board at +<tab@lists.linux-foundation.org>, or the individual members, and they +will work to resolve the issue to the best of their ability. For more +information on who is on the Technical Advisory Board and what their +role is, please see: + http://www.linuxfoundation.org/projects/linux/tab + +As a reviewer of code, please strive to keep things civil and focused on +the technical issues involved. We are all humans, and frustrations can +be high on both sides of the process. Try to keep in mind the immortal +words of Bill and Ted, "Be excellent to each other."
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle new file mode 100644 index 0000000..9c61c03 --- /dev/null +++ b/Documentation/CodingStyle
@@ -0,0 +1,1062 @@ +.. _codingstyle: + +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: + + +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.: + +.. code-block:: c + + 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: + +.. code-block:: c + + 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. + + +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, unless +exceeding 80 columns significantly increases readability and does not hide +information. 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. However, never break user-visible strings such as +printk messages, because that breaks the ability to grep for them. + + +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: + +.. code-block:: c + + if (x is true) { + we do y + } + +This applies to all non-function statement blocks (if, switch, for, +while, do). E.g.: + +.. code-block:: c + + 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: + +.. code-block:: c + + 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: + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +and + +.. code-block:: c + + 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. + +.. code-block:: c + + if (condition) + action(); + +and + +.. code-block:: none + + if (condition) + do_this(); + else + do_that(); + +This does not apply if only one branch of a conditional statement is a single +statement; in the latter case use braces in both branches: + +.. code-block:: c + + 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., + +.. code-block:: c + + + s = sizeof(struct file); + +Do not add spaces around (inside) parenthesized expressions. This example is +**bad**: + +.. code-block:: c + + + 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: + +.. code-block:: c + + + 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. + + +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). + + +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 + +.. code-block:: c + + + vps_t a; + +in the source, what does it mean? +In contrast, if it says + +.. code-block:: c + + 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. + + +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.: + +.. code-block:: c + + 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. + + +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. If there is no +cleanup needed then just return directly. + +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. +Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to +renumber them if you ever add or remove exit paths, and they make correctness +difficult to verify anyway. + +The rationale for using gotos 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 ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +A common type of bug to be aware of is ``one err bugs`` which look like this: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths ``foo`` is NULL. Normally the +fix for this is to split it up into two error labels ``err_free_bar:`` and +``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Ideally you should simulate errors to test all exit paths. + + +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-documentation.rst and scripts/kernel-doc +for details. + +The preferred style for long (multi-line) comments is: + +.. code-block:: c + + /* + * 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. + */ + +For files in net/ and drivers/net/ the preferred style for long (multi-line) +comments is a little different. + +.. code-block:: c + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + +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. + + +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: + +.. code-block:: none + + (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) + (setq show-trailing-whitespace 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. + + +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. + +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. + + +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. + + +12) Macros, Enums and RTL +------------------------- + +Names of macros defining constants and labels in enums are capitalized. + +.. code-block:: c + + #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: + +.. code-block:: c + + #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: + +.. code-block:: c + + #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: + +.. code-block:: c + + #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. + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) namespace collisions when defining local variables in macros resembling +functions: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret is a common name for a local variable - __foo_ret is less likely +to collide with an existing variable. + +The cpp manual deals with macros exhaustively. The gcc internals manual also +covers RTL which is used frequently with assembly language in the kernel. + + +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/printk.h> defines pr_notice(), pr_info(), +pr_warn(), pr_err(), etc. + +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. However +debug message printing is handled differently than printing other non-debug +messages. While the other pr_XXX() functions print unconditionally, +pr_debug() does not; it is compiled out by default, unless either DEBUG is +defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, +and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to +the ones already enabled by DEBUG. + +Many subsystems have Kconfig debug options to turn on -DDEBUG in the +corresponding Makefile; in other cases specific files #define DEBUG. And +when a debug message should be unconditionally printed, such as if it is +already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be +used. + + +14) Allocating memory +--------------------- + +The kernel provides the following general purpose memory allocators: +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and +vzalloc(). Please refer to the API documentation for further information +about them. + +The preferred form for passing a size of a struct is the following: + +.. code-block:: c + + 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. + +The preferred form for allocating an array is the following: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +The preferred form for allocating a zeroed array is the following: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Both forms check for overflow on the allocation size n * sizeof(...), +and return NULL if that occurred. + + +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. + + +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. + + +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 + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + +.. code-block:: c + + #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. + + +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: + +.. code-block:: c + + -*- mode: c -*- + +Or like this: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interprets markers that look like this: + +.. code-block:: c + + /* 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. + + +19) Inline assembly +------------------- + +In architecture-specific code, you may need to use inline assembly to interface +with CPU or platform functionality. Don't hesitate to do so when necessary. +However, don't use inline assembly gratuitously when C can do the job. You can +and should poke hardware from C when possible. + +Consider writing simple helper functions that wrap common bits of inline +assembly, rather than repeatedly writing them with slight variations. Remember +that inline assembly can use C parameters. + +Large, non-trivial assembly functions should go in .S files, with corresponding +C prototypes defined in C header files. The C prototypes for assembly +functions should use ``asmlinkage``. + +You may need to mark your asm statement as volatile, to prevent GCC from +removing it if GCC doesn't notice any side effects. You don't always need to +do so, though, and doing so unnecessarily can limit optimization. + +When writing a single inline assembly statement containing multiple +instructions, put each instruction on a separate line in a separate quoted +string, and end each string except the last with \n\t to properly indent the +next instruction in the assembly output: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) Conditional Compilation +--------------------------- + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +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). + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +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/
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt new file mode 100644 index 0000000..979228b --- /dev/null +++ b/Documentation/DMA-API-HOWTO.txt
@@ -0,0 +1,967 @@ + Dynamic DMA mapping Guide + ========================= + + David S. Miller <davem@redhat.com> + Richard Henderson <rth@cygnus.com> + Jakub Jelinek <jakub@redhat.com> + +This is a guide to device driver writers on how to use the DMA API +with example pseudo-code. For a concise description of the API, see +DMA-API.txt. + + CPU and DMA addresses + +There are several kinds of addresses involved in the DMA API, and it's +important to understand the differences. + +The kernel normally uses virtual addresses. Any address returned by +kmalloc(), vmalloc(), and similar interfaces is a virtual address and can +be stored in a "void *". + +The virtual memory system (TLB, page tables, etc.) translates virtual +addresses to CPU physical addresses, which are stored as "phys_addr_t" or +"resource_size_t". The kernel manages device resources like registers as +physical addresses. These are the addresses in /proc/iomem. The physical +address is not directly useful to a driver; it must use ioremap() to map +the space and produce a virtual address. + +I/O devices use a third kind of address: a "bus address". If a device has +registers at an MMIO address, or if it performs DMA to read or write system +memory, the addresses used by the device are bus addresses. In some +systems, bus addresses are identical to CPU physical addresses, but in +general they are not. IOMMUs and host bridges can produce arbitrary +mappings between physical and bus addresses. + +From a device's point of view, DMA uses the bus address space, but it may +be restricted to a subset of that space. For example, even if a system +supports 64-bit addresses for main memory and PCI BARs, it may use an IOMMU +so devices only need to use 32-bit DMA addresses. + +Here's a picture and some examples: + + CPU CPU Bus + Virtual Physical Address + Address Address Space + Space Space + + +-------+ +------+ +------+ + | | |MMIO | Offset | | + | | Virtual |Space | applied | | + C +-------+ --------> B +------+ ----------> +------+ A + | | mapping | | by host | | + +-----+ | | | | bridge | | +--------+ + | | | | +------+ | | | | + | CPU | | | | RAM | | | | Device | + | | | | | | | | | | + +-----+ +-------+ +------+ +------+ +--------+ + | | Virtual |Buffer| Mapping | | + X +-------+ --------> Y +------+ <---------- +------+ Z + | | mapping | RAM | by IOMMU + | | | | + | | | | + +-------+ +------+ + +During the enumeration process, the kernel learns about I/O devices and +their MMIO space and the host bridges that connect them to the system. For +example, if a PCI device has a BAR, the kernel reads the bus address (A) +from the BAR and converts it to a CPU physical address (B). The address B +is stored in a struct resource and usually exposed via /proc/iomem. When a +driver claims a device, it typically uses ioremap() to map physical address +B at a virtual address (C). It can then use, e.g., ioread32(C), to access +the device registers at bus address A. + +If the device supports DMA, the driver sets up a buffer using kmalloc() or +a similar interface, which returns a virtual address (X). The virtual +memory system maps X to a physical address (Y) in system RAM. The driver +can use virtual address X to access the buffer, but the device itself +cannot because DMA doesn't go through the CPU virtual memory system. + +In some simple systems, the device can do DMA directly to physical address +Y. But in many others, there is IOMMU hardware that translates DMA +addresses to physical addresses, e.g., it translates Z to Y. This is part +of the reason for the DMA API: the driver can give a virtual address X to +an interface like dma_map_single(), which sets up any required IOMMU +mapping and returns the DMA address Z. The driver then tells the device to +do DMA to Z, and the IOMMU maps it to the buffer at address Y in system +RAM. + +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. + +Note that the DMA API works with any bus independent of the underlying +microprocessor architecture. You should use the DMA API rather than the +bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the +pci_map_*() interfaces. + +First of all, you should make sure + +#include <linux/dma-mapping.h> + +is in your driver, which provides the definition of dma_addr_t. This type +can hold any valid DMA address for the platform and should be used +everywhere you hold a DMA 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? +If so, you need to inform the kernel of this fact. + +By default, the kernel assumes that your device can address the full +32-bits. For a 64-bit capable device, this needs to be increased. +And for a device with limitations, as discussed in the previous +paragraph, it needs to be decreased. + +Special note about PCI: 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. + +For correct operation, you must interrogate the kernel in your device +probe routine to see if the DMA 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 dma_set_mask_and_coherent(): + + int dma_set_mask_and_coherent(struct device *dev, u64 mask); + +which will query the mask for both streaming and coherent APIs together. +If you have some special requirements, then the following two separate +queries can be used instead: + + The query for streaming mappings is performed via a call to + dma_set_mask(): + + int dma_set_mask(struct device *dev, u64 mask); + + The query for consistent allocations is performed via a call + to dma_set_coherent_mask(): + + int dma_set_coherent_mask(struct device *dev, u64 mask); + +Here, dev is a pointer to the device struct of your device, and mask +is a bit mask describing which bits of an address your device +supports. It returns zero if your card can perform DMA properly on +the machine given the address mask you provided. In general, the +device struct of your device is embedded in the bus-specific device +struct of your device. For example, &pdev->dev is a pointer to the +device struct of a PCI device (pdev is a pointer to the PCI device +struct of your device). + +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 device would do something like this: + + if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) { + dev_warn(dev, "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 addressing, but back down to a 32-bit mask that +should not fail. The kernel 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 addressing is done more efficiently +than 64-bit addressing. For example, Sparc64 PCI SAC addressing is +more efficient than DAC addressing. + +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 (!dma_set_mask(dev, DMA_BIT_MASK(64))) { + using_dac = 1; + } else if (!dma_set_mask(dev, DMA_BIT_MASK(32))) { + using_dac = 0; + } else { + dev_warn(dev, "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 (!dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) { + using_dac = 1; + consistent_using_dac = 1; + } else if (!dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) { + using_dac = 0; + consistent_using_dac = 0; + } else { + dev_warn(dev, "mydev: No suitable DMA available\n"); + goto ignore_this_device; + } + +The coherent mask will always be able to set the same or a smaller mask as +the streaming mask. However for the rare case that a device driver only +uses consistent allocations, one would have to check the return value from +dma_set_coherent_mask(). + +Finally, if your device can only drive the low 24-bits of +address you might do something like: + + if (dma_set_mask(dev, DMA_BIT_MASK(24))) { + dev_warn(dev, "mydev: 24-bit DMA addressing not available\n"); + goto ignore_this_device; + } + +When dma_set_mask() or dma_set_mask_and_coherent() is successful, and +returns zero, the kernel saves away this mask you have provided. The +kernel 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 dma_set_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 DMA_BIT_MASK(24) + + struct my_sound_card *card; + struct device *dev; + + ... + if (!dma_set_mask(dev, PLAYBACK_ADDRESS_BITS)) { + card->playback_enabled = 1; + } else { + card->playback_enabled = 0; + dev_warn(dev, "%s: Playback disabled due to DMA limitations\n", + card->name); + } + if (!dma_set_mask(dev, RECORD_ADDRESS_BITS)) { + card->record_enabled = 1; + } else { + card->record_enabled = 0; + dev_warn(dev, "%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 DMA 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 dma_sync_* below) + and for which hardware can optimize for sequential accesses. + + Think 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 +the underlying bus, 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 = dma_alloc_coherent(dev, size, &dma_handle, gfp); + +where device is a struct device *. This may be called in interrupt +context with the GFP_ATOMIC flag. + +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 dma_pool interface, described below. + +The consistent DMA mapping interfaces, for non-NULL dev, will by +default return a DMA address which is 32-bit addressable. Even if the +device indicates (via DMA mask) that it may address the upper 32-bits, +consistent allocation will only return > 32-bit addresses for DMA if +the consistent DMA mask has been explicitly changed via +dma_set_coherent_mask(). This is true of the dma_pool interface as +well. + +dma_alloc_coherent() 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 virtual address and the DMA 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: + + dma_free_coherent(dev, size, cpu_addr, dma_handle); + +where dev, size are the same as in the above call and cpu_addr and +dma_handle are the values dma_alloc_coherent() 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 dma_alloc_coherent(), +or you can use the dma_pool API to do that. A dma_pool is like +a kmem_cache, but it uses dma_alloc_coherent(), 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 dma_pool like this: + + struct dma_pool *pool; + + pool = dma_pool_create(name, dev, size, align, boundary); + +The "name" is for diagnostics (like a kmem_cache name); dev 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 boundary; passing 4096 says memory allocated from this pool +must not cross 4KByte boundaries (but at that time it may be better to +use dma_alloc_coherent() directly instead). + +Allocate memory from a DMA pool like this: + + cpu_addr = dma_pool_alloc(pool, flags, &dma_handle); + +flags are GFP_KERNEL if blocking is permitted (not in_interrupt nor +holding SMP locks), GFP_ATOMIC otherwise. Like dma_alloc_coherent(), +this returns two values, cpu_addr and dma_handle. + +Free memory that was allocated from a dma_pool like this: + + dma_pool_free(pool, cpu_addr, dma_handle); + +where pool is what you passed to dma_pool_alloc(), and cpu_addr and +dma_handle are the values dma_pool_alloc() returned. This function +may be called in interrupt context. + +Destroy a dma_pool by calling: + + dma_pool_destroy(pool); + +Make sure you've called dma_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: + + DMA_BIDIRECTIONAL + DMA_TO_DEVICE + DMA_FROM_DEVICE + DMA_NONE + +You should provide the exact DMA direction if you know it. + +DMA_TO_DEVICE means "from main memory to the device" +DMA_FROM_DEVICE means "from the 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 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 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 DMA controller hardware detects violation of the +permission setting. + +Only streaming mappings specify a direction, consistent mappings +implicitly have a direction attribute setting of +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 DMA_TO_DEVICE direction +specifier. For receive packets, just the opposite, map/unmap them +with the DMA_FROM_DEVICE 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 device *dev = &my_dev->dev; + dma_addr_t dma_handle; + void *addr = buffer->ptr; + size_t size = buffer->len; + + dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + +and to unmap it: + + dma_unmap_single(dev, dma_handle, size, direction); + +You should call dma_mapping_error() as dma_map_single() could fail and return +error. Not all DMA implementations support the dma_mapping_error() interface. +However, it is a good practice to call dma_mapping_error() interface, which +will invoke the generic mapping error check interface. Doing so will ensure +that the mapping code will work correctly on all DMA implementations without +any dependency on the specifics of the underlying implementation. Using the +returned address without checking for errors could result in failures ranging +from panics to silent data corruption. A couple of examples of incorrect ways +to check for errors that make assumptions about the underlying DMA +implementation are as follows and these are applicable to dma_map_page() as +well. + +Incorrect example 1: + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if ((dma_handle & 0xffff != 0) || (dma_handle >= 0x1000000)) { + goto map_error; + } + +Incorrect example 2: + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_handle == DMA_ERROR_CODE) { + goto map_error; + } + +You should call dma_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 dma_{map,unmap}_single(). These +interfaces deal with page/offset pairs instead of CPU pointers. +Specifically: + + struct device *dev = &my_dev->dev; + dma_addr_t dma_handle; + struct page *page = buffer->page; + unsigned long offset = buffer->offset; + size_t size = buffer->len; + + dma_handle = dma_map_page(dev, page, offset, size, direction); + if (dma_mapping_error(dev, dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + + ... + + dma_unmap_page(dev, dma_handle, size, direction); + +Here, "offset" means byte offset within the given page. + +You should call dma_mapping_error() as dma_map_page() could fail and return +error as outlined under the dma_map_single() discussion. + +You should call dma_unmap_page() when the DMA activity is finished, e.g., +from the interrupt which told you that the DMA transfer is done. + +With scatterlists, you map a region gathered from several regions by: + + 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. 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: + + dma_unmap_sg(dev, sglist, nents, direction); + +Again, make sure DMA activity has already finished. + +PLEASE NOTE: The 'nents' argument to the dma_unmap_sg call must be + the _same_ one you passed into the dma_map_sg call, + it should _NOT_ be the 'count' value _returned_ from the + dma_map_sg call. + +Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}() +counterpart, because the DMA address space is a shared resource and +you could render the machine unusable by consuming all DMA 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 up-to-date and +correct copy of the DMA buffer. + +So, firstly, just map it with dma_map_{single,sg}(), and after each DMA +transfer call either: + + dma_sync_single_for_cpu(dev, dma_handle, size, direction); + +or: + + dma_sync_sg_for_cpu(dev, 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: + + dma_sync_single_for_device(dev, dma_handle, size, direction); + +or: + + dma_sync_sg_for_device(dev, sglist, nents, direction); + +as appropriate. + +PLEASE NOTE: The 'nents' argument to dma_sync_sg_for_cpu() and + dma_sync_sg_for_device() must be the same passed to + dma_map_sg(). It is _NOT_ the count returned by + dma_map_sg(). + +After the last DMA transfer call one of the DMA unmap routines +dma_unmap_{single,sg}(). If you don't touch the data from the first +dma_map_*() call till dma_unmap_*(), then you don't have to call the +dma_sync_*() routines at all. + +Here is pseudo code which shows a situation in which you would need +to use the dma_sync_*() interfaces. + + my_card_setup_receive_buffer(struct my_card *cp, char *buffer, int len) + { + dma_addr_t mapping; + + mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); + if (dma_mapping_error(cp->dev, mapping)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + + 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. + */ + dma_sync_single_for_cpu(&cp->dev, cp->rx_dma, + cp->rx_len, + DMA_FROM_DEVICE); + + /* Now it is safe to examine the buffer. */ + hp = (struct my_card_header *) cp->rx_buf; + if (header_is_ok(hp)) { + dma_unmap_single(&cp->dev, cp->rx_dma, cp->rx_len, + DMA_FROM_DEVICE); + pass_to_upper_layers(cp->rx_buf); + make_and_setup_new_rx_buf(cp); + } else { + /* CPU should not write to + * DMA_FROM_DEVICE-mapped area, + * so dma_sync_single_for_device() is + * not needed here. It would be required + * for DMA_BIDIRECTIONAL mapping if + * the memory was modified. + */ + 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 dma_alloc_coherent(), dma_pool_alloc(), and dma_map_single() +calls (dma_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 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. + + Handling Errors + +DMA address space is limited on some architectures and an allocation +failure can be determined by: + +- checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0 + +- checking the dma_addr_t returned from dma_map_single() and dma_map_page() + by using dma_mapping_error(): + + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + +- unmap pages that are already mapped, when mapping error occurs in the middle + of a multiple page mapping attempt. These example are applicable to + dma_map_page() as well. + +Example 1: + dma_addr_t dma_handle1; + dma_addr_t dma_handle2; + + dma_handle1 = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle1)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling1; + } + dma_handle2 = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle2)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling2; + } + + ... + + map_error_handling2: + dma_unmap_single(dma_handle1); + map_error_handling1: + +Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when + mapping error is detected in the middle) + + dma_addr_t dma_addr; + dma_addr_t array[DMA_BUFFERS]; + int save_index = 0; + + for (i = 0; i < DMA_BUFFERS; i++) { + + ... + + dma_addr = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_addr)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + array[i].dma_addr = dma_addr; + save_index++; + } + + ... + + map_error_handling: + + for (i = 0; i < save_index; i++) { + + ... + + dma_unmap_single(array[i].dma_addr); + } + +Networking drivers must call dev_kfree_skb() to free the socket buffer +and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook +(ndo_start_xmit). This means that the socket buffer is just dropped in +the failure case. + +SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping +fails in the queuecommand hook. This means that the SCSI subsystem +passes the command to the driver again later. + + Optimizing Unmap State Space Consumption + +On many platforms, dma_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 DEFINE_DMA_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; + DEFINE_DMA_UNMAP_ADDR(mapping); + DEFINE_DMA_UNMAP_LEN(len); + }; + +2) Use dma_unmap_{addr,len}_set() to set these values. + Example, before: + + ringp->mapping = FOO; + ringp->len = BAR; + + after: + + dma_unmap_addr_set(ringp, mapping, FOO); + dma_unmap_len_set(ringp, len, BAR); + +3) Use dma_unmap_{addr,len}() to access these values. + Example, before: + + dma_unmap_single(dev, ringp->mapping, ringp->len, + DMA_FROM_DEVICE); + + after: + + dma_unmap_single(dev, + dma_unmap_addr(ringp, mapping), + dma_unmap_len(ringp, len), + DMA_FROM_DEVICE); + +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. + + You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture + supports IOMMUs (including software IOMMU). + +2) ARCH_DMA_MINALIGN + + Architectures must ensure that kmalloc'ed buffer is + DMA-safe. Drivers and subsystems depend on it. If an architecture + isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in + the CPU cache is identical to data in main memory), + ARCH_DMA_MINALIGN must be set so that the memory allocator + makes sure that kmalloc'ed buffer doesn't share a cache line with + the others. See arch/arm/include/asm/cache.h as an example. + + Note that ARCH_DMA_MINALIGN is about DMA memory alignment + constraints. You don't need to worry about the architecture data + alignment constraints (e.g. the alignment constraints about 64-bit + objects). + + Closing + +This document, and the API itself, would not be in its 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>
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt new file mode 100644 index 0000000..6b20128 --- /dev/null +++ b/Documentation/DMA-API.txt
@@ -0,0 +1,705 @@ + 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 +of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt. + +This API is split into two pieces. Part I describes the basic API. +Part II describes extensions 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 - dma_ API +------------------------------------- + +To get the dma_ API, you must #include <linux/dma-mapping.h>. This +provides dma_addr_t and the interfaces described below. + +A dma_addr_t can hold any valid DMA address for the platform. It can be +given to a device to use as a DMA source or target. A CPU cannot reference +a dma_addr_t directly because there may be translation between its physical +address space and the DMA address space. + +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) + +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 returns a pointer to the allocated region (in the processor's virtual +address space) or NULL if the allocation failed. + +It also returns a <dma_handle> which may be cast to an unsigned integer the +same width as the bus and given to the device as the DMA address base of +the region. + +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). + +void * +dma_zalloc_coherent(struct device *dev, size_t size, + dma_addr_t *dma_handle, gfp_t flag) + +Wraps dma_alloc_coherent() and also zeroes the returned memory if the +allocation attempt succeeded. + +void +dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, + dma_addr_t dma_handle) + +Free a region of consistent memory you previously allocated. dev, +size and dma_handle must all be the same as those passed into +dma_alloc_coherent(). cpu_addr must be the virtual address returned by +the dma_alloc_coherent(). + +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); + +dma_pool_create() initializes 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_zalloc(struct dma_pool *pool, gfp_t mem_flags, + dma_addr_t *handle) + +Wraps dma_pool_alloc() and also zeroes the returned memory if the +allocation attempt succeeded. + + + void *dma_pool_alloc(struct dma_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); + +This puts memory back into the pool. The pool is what was passed to +dma_pool_alloc(); 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); + +dma_pool_destroy() frees the resources of the pool. It 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_set_mask_and_coherent(struct device *dev, u64 mask) + +Checks to see if the mask is possible and updates the device +streaming and coherent DMA mask parameters if it is. + +Returns: 0 if successful and a negative error if not. + +int +dma_set_mask(struct 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. + +int +dma_set_coherent_mask(struct 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) + +Maps a piece of processor virtual memory so it can be accessed by the +device and returns the DMA address of the memory. + +The direction for both APIs may be converted freely by casting. +However the dma_ API uses a strongly typed enumerator for its +direction: + +DMA_NONE no direction (used for debugging) +DMA_TO_DEVICE data is going from the memory to the device +DMA_FROM_DEVICE data is coming from the device to the memory +DMA_BIDIRECTIONAL direction isn't known + +Notes: Not all memory regions in a machine can be mapped by this API. +Further, contiguous 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, memory to be mapped by +this API should be obtained from sources which guarantee it to be +physically contiguous (like kmalloc). + +Further, the DMA address of the memory must be within the +dma_mask of the device (the dma_mask is a bit mask of the +addressable region for the device, i.e., if the DMA address of +the memory ANDed with the dma_mask is still equal to the DMA +address, then the device can perform DMA to the memory). To +ensure that the memory allocated by kmalloc is within the dma_mask, +the driver may specify various platform-dependent flags to restrict +the DMA address range of the allocation (e.g., on x86, GFP_DMA +guarantees to be within the first 16MB of available DMA addresses, +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 +maps an I/O DMA address to a physical memory address). 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 device. 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) + +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) +void +dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size, + enum dma_data_direction 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. + +dma_addr_t +dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size, + enum dma_data_direction dir, unsigned long attrs) + +void +dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size, + enum dma_data_direction dir, unsigned long attrs) + +API for mapping and unmapping for MMIO resources. All the notes and +warnings for the other mapping APIs apply here. The API should only be +used to map device MMIO resources, mapping of RAM is not permitted. + +int +dma_mapping_error(struct device *dev, dma_addr_t dma_addr) + +In some circumstances dma_map_single(), dma_map_page() and dma_map_resource() +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) + +Returns: the number of DMA address 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 nents, enum dma_data_direction 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 +DMA address entries returned. + +void +dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size, + enum dma_data_direction direction) +void +dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size, + enum dma_data_direction direction) +void +dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents, + enum dma_data_direction direction) +void +dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents, + enum dma_data_direction direction) + +Synchronise a single contiguous or scatter/gather mapping for the CPU +and device. With the sync_sg API, all the parameters must be the same +as those passed into the single mapping API. With the sync_single API, +you can use dma_handle and size parameters that aren't identical to +those passed into the single mapping API to do a partial sync. + +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, + unsigned long attrs) + +void +dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr, + size_t size, enum dma_data_direction dir, + unsigned long attrs) + +int +dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl, + int nents, enum dma_data_direction dir, + unsigned long attrs) + +void +dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl, + int nents, enum dma_data_direction dir, + unsigned long attrs) + +The four functions above are just like the counterpart functions +without the _attrs suffixes, except that they pass an optional +dma_attrs. + +The interpretation of DMA attributes is architecture-specific, and +each attribute should be documented in Documentation/DMA-attributes.txt. + +If dma_attrs are 0, 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-mapping.h> +/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and + * documented in Documentation/DMA-attributes.txt */ +... + + unsigned long attr; + attr |= DMA_ATTR_FOO; + .... + 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, + unsigned long attrs) +{ + .... + if (attrs & DMA_ATTR_FOO) + /* twizzle the frobnozzle */ + .... + + +Part II - Advanced dma_ usage +----------------------------- + +Warning: These pieces of the DMA API should 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 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_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_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, phys_addr_t phys_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. + +phys_addr is the CPU physical address to which the memory is currently +assigned (this will be ioremapped so the CPU can access the region). + +device_addr is the DMA address the device needs to be programmed +with to actually 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 ORed 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 has 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. + +void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr); + +dma-debug interface debug_dma_mapping_error() to debug drivers that fail +to check DMA mapping errors on addresses returned by dma_map_single() and +dma_map_page() interfaces. This interface clears a flag set by +debug_dma_map_page() to indicate that dma_mapping_error() has been called by +the driver. When driver does unmap, debug_dma_unmap() checks the flag and if +this flag is still set, prints warning message that includes call trace that +leads up to the unmap. This interface can be called from dma_mapping_error() +routines to enable DMA mapping error check debugging. +
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt new file mode 100644 index 0000000..b1a1983 --- /dev/null +++ b/Documentation/DMA-ISA-LPC.txt
@@ -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 +bus 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 bus address, 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.
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt new file mode 100644 index 0000000..98bf7ac --- /dev/null +++ b/Documentation/DMA-attributes.txt
@@ -0,0 +1,145 @@ + DMA attributes + ============== + +This document describes the semantics of the DMA attributes that are +defined in linux/dma-mapping.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 idiosyncrasies 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. + +DMA_ATTR_WRITE_COMBINE +---------------------- + +DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may be +buffered to improve performance. + +Since it is optional for platforms to implement DMA_ATTR_WRITE_COMBINE, +those that do not will simply ignore the attribute and exhibit default +behavior. + +DMA_ATTR_NON_CONSISTENT +----------------------- + +DMA_ATTR_NON_CONSISTENT lets the platform to 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. + +DMA_ATTR_NO_KERNEL_MAPPING +-------------------------- + +DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernel +virtual mapping for the allocated buffer. On some architectures creating +such mapping is non-trivial task and consumes very limited resources +(like kernel virtual address space or dma consistent address space). +Buffers allocated with this attribute can be only passed to user space +by calling dma_mmap_attrs(). By using this API, you are guaranteeing +that you won't dereference the pointer returned by dma_alloc_attr(). You +can treat it as a cookie that must be passed to dma_mmap_attrs() and +dma_free_attrs(). Make sure that both of these also get this attribute +set on each call. + +Since it is optional for platforms to implement +DMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore the +attribute and exhibit default behavior. + +DMA_ATTR_SKIP_CPU_SYNC +---------------------- + +By default dma_map_{single,page,sg} functions family transfer a given +buffer from CPU domain to device domain. Some advanced use cases might +require sharing a buffer between more than one device. This requires +having a mapping created separately for each device and is usually +performed by calling dma_map_{single,page,sg} function more than once +for the given buffer with device pointer to each device taking part in +the buffer sharing. The first call transfers a buffer from 'CPU' domain +to 'device' domain, what synchronizes CPU caches for the given region +(usually it means that the cache has been flushed or invalidated +depending on the dma direction). However, next calls to +dma_map_{single,page,sg}() for other devices will perform exactly the +same synchronization operation on the CPU cache. CPU cache synchronization +might be a time consuming operation, especially if the buffers are +large, so it is highly recommended to avoid it if possible. +DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization of +the CPU cache for the given buffer assuming that it has been already +transferred to 'device' domain. This attribute can be also used for +dma_unmap_{single,page,sg} functions family to force buffer to stay in +device domain after releasing a mapping for it. Use this attribute with +care! + +DMA_ATTR_FORCE_CONTIGUOUS +------------------------- + +By default DMA-mapping subsystem is allowed to assemble the buffer +allocated by dma_alloc_attrs() function from individual pages if it can +be mapped as contiguous chunk into device dma address space. By +specifying this attribute the allocated buffer is forced to be contiguous +also in physical memory. + +DMA_ATTR_ALLOC_SINGLE_PAGES +--------------------------- + +This is a hint to the DMA-mapping subsystem that it's probably not worth +the time to try to allocate memory to in a way that gives better TLB +efficiency (AKA it's not worth trying to build the mapping out of larger +pages). You might want to specify this if: +- You know that the accesses to this memory won't thrash the TLB. + You might know that the accesses are likely to be sequential or + that they aren't sequential but it's unlikely you'll ping-pong + between many addresses that are likely to be in different physical + pages. +- You know that the penalty of TLB misses while accessing the + memory will be small enough to be inconsequential. If you are + doing a heavy operation like decryption or decompression this + might be the case. +- You know that the DMA mapping is fairly transitory. If you expect + the mapping to have a short lifetime then it may be worth it to + optimize allocation (avoid coming up with large pages) instead of + getting the slight performance win of larger pages. +Setting this hint doesn't guarantee that you won't get huge pages, but it +means that we won't try quite as hard to get them. + +NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM, +though ARM64 patches will likely be posted soon. + +DMA_ATTR_NO_WARN +---------------- + +This tells the DMA-mapping subsystem to suppress allocation failure reports +(similarly to __GFP_NOWARN). + +On some architectures allocation failures are reported with error messages +to the system logs. Although this can help to identify and debug problems, +drivers which handle failures (eg, retry later) have no problems with them, +and can actually flood the system logs with error messages that aren't any +problem at all, depending on the implementation of the retry mechanism. + +So, this provides a way for drivers to avoid those error messages on calls +where allocation failures are not a problem, and shouldn't bother the logs. + +NOTE: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC.
diff --git a/Documentation/DocBook/.gitignore b/Documentation/DocBook/.gitignore new file mode 100644 index 0000000..e05da3f --- /dev/null +++ b/Documentation/DocBook/.gitignore
@@ -0,0 +1,17 @@ +*.xml +*.ps +*.pdf +*.html +*.9.gz +*.9 +*.aux +*.dvi +*.log +*.out +*.png +*.gif +*.svg +*.proc +*.db +media-indices.tmpl +media-entities.tmpl
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile new file mode 100644 index 0000000..fdf8232 --- /dev/null +++ b/Documentation/DocBook/Makefile
@@ -0,0 +1,278 @@ +### +# 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 \ + kernel-hacking.xml kernel-locking.xml deviceiobook.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 \ + debugobjects.xml sh.xml regulator.xml \ + alsa-driver-api.xml writing-an-alsa-driver.xml \ + tracepoint.xml w1.xml \ + writing_musb_glue_layer.xml crypto-API.xml iio.xml + +ifeq ($(DOCBOOKS),) + +# Skip DocBook build if the user explicitly requested no DOCBOOKS. +.DEFAULT: + @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." +else +ifneq ($(SPHINXDIRS),) + +# Skip DocBook build if the user explicitly requested a sphinx dir +.DEFAULT: + @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." +else + + +### +# 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) + + +targets += $(DOCBOOKS) +BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) +xmldocs: $(BOOKS) +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 cmd,build_main_index) + +MAN := $(patsubst %.xml, %.9, $(BOOKS)) +mandocs: $(MAN) + find $(obj)/man -name '*.9' | xargs gzip -nf + +installmandocs: mandocs + mkdir -p /usr/local/man/man9/ + find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ + sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ + xargs install -m 644 -t /usr/local/man/man9/ + +# no-op for the DocBook toolchain +epubdocs: +latexdocs: + +### +#External programs used +KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/docproc +CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype + +# Use a fixed encoding - UTF-8 if the C library has support built-in +# or ASCII if not +LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) +export LC_CTYPE + +XMLTOFLAGS = -m $(srctree)/$(src)/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 $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE + $(call if_changed_rule,docproc) + +# 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 = $(obj)/$(index) +quiet_cmd_build_main_index = HTML $(main_idx) + cmd_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 html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ + echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ + $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ + +### +# Rules to create an aux XML and .db, and use them to re-process the DocBook XML +# to fill internal hyperlinks + gen_aux_xml = : + quiet_gen_aux_xml = echo ' XMLREF $@' +silent_gen_aux_xml = : +%.aux.xml: %.xml + @$($(quiet)gen_aux_xml) + @rm -rf $@ + @(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db) + @$(KERNELDOCXMLREF) -db $<.db $< > $@ +.PRECIOUS: %.aux.xml + +%.html: %.aux.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/$(*F) $< ; fi +%.9 : %.xml + @(which xmlto > /dev/null 2>&1) || \ + (echo "*** You need to install xmlto ***"; \ + exit 1) + $(Q)mkdir -p $(obj)/man/$(*F) + $(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>") > $@ + +endif # DOCBOOKS="" +endif # SPHINDIR=... + +### +# Help targets as used by the top-level makefile +dochelp: + @echo ' Linux kernel internal documentation in different formats (DocBook):' + @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' + @echo + @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' + @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' + @echo + @echo " make DOCBOOKS=\"\" [target] Don't generate docs from Docbook" + @echo ' This is useful to generate only the ReST docs (Sphinx)' + + +### +# 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)) \ + $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ + $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ + $(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)
diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl new file mode 100644 index 0000000..53f439d --- /dev/null +++ b/Documentation/DocBook/alsa-driver-api.tmpl
@@ -0,0 +1,142 @@ +<?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 +!Iinclude/sound/pcm.h + </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> + <sect1><title>PCM DMA Engine API</title> +!Esound/core/pcm_dmaengine.c +!Iinclude/sound/dmaengine_pcm.h + </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>Compress Offload</title> + <sect1><title>Compress Offload API</title> +!Esound/core/compress_offload.c +!Iinclude/uapi/sound/compress_offload.h +!Iinclude/uapi/sound/compress_params.h +!Iinclude/sound/compress_driver.h + </sect1> + </chapter> + <chapter><title>ASoC</title> + <sect1><title>ASoC Core API</title> +!Iinclude/sound/soc.h +!Esound/soc/soc-core.c +<!-- !Esound/soc/soc-cache.c no docbook comments here --> +!Esound/soc/soc-devres.c +!Esound/soc/soc-io.c +!Esound/soc/soc-pcm.c +!Esound/soc/soc-ops.c +!Esound/soc/soc-compress.c + </sect1> + <sect1><title>ASoC DAPM API</title> +!Esound/soc/soc-dapm.c + </sect1> + <sect1><title>ASoC DMA Engine API</title> +!Esound/soc/soc-generic-dmaengine-pcm.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> +!Iinclude/sound/jack.h +!Esound/core/jack.c +!Esound/soc/soc-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>
diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl new file mode 100644 index 0000000..088b79c --- /dev/null +++ b/Documentation/DocBook/crypto-API.tmpl
@@ -0,0 +1,2092 @@ +<?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="KernelCryptoAPI"> + <bookinfo> + <title>Linux Kernel Crypto API</title> + + <authorgroup> + <author> + <firstname>Stephan</firstname> + <surname>Mueller</surname> + <affiliation> + <address> + <email>smueller@chronox.de</email> + </address> + </affiliation> + </author> + <author> + <firstname>Marek</firstname> + <surname>Vasut</surname> + <affiliation> + <address> + <email>marek@denx.de</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Stephan Mueller</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>Kernel Crypto API Interface Specification</title> + + <sect1><title>Introduction</title> + + <para> + The kernel crypto API offers a rich set of cryptographic ciphers as + well as other data transformation mechanisms and methods to invoke + these. This document contains a description of the API and provides + example code. + </para> + + <para> + To understand and properly use the kernel crypto API a brief + explanation of its structure is given. Based on the architecture, + the API can be separated into different components. Following the + architecture specification, hints to developers of ciphers are + provided. Pointers to the API function call documentation are + given at the end. + </para> + + <para> + The kernel crypto API refers to all algorithms as "transformations". + Therefore, a cipher handle variable usually has the name "tfm". + Besides cryptographic operations, the kernel crypto API also knows + compression transformations and handles them the same way as ciphers. + </para> + + <para> + The kernel crypto API serves the following entity types: + + <itemizedlist> + <listitem> + <para>consumers requesting cryptographic services</para> + </listitem> + <listitem> + <para>data transformation implementations (typically ciphers) + that can be called by consumers using the kernel crypto + API</para> + </listitem> + </itemizedlist> + </para> + + <para> + This specification is intended for consumers of the kernel crypto + API as well as for developers implementing ciphers. This API + specification, however, does not discuss all API calls available + to data transformation implementations (i.e. implementations of + ciphers and other transformations (such as CRC or even compression + algorithms) that can register with the kernel crypto API). + </para> + + <para> + Note: The terms "transformation" and cipher algorithm are used + interchangeably. + </para> + </sect1> + + <sect1><title>Terminology</title> + <para> + The transformation implementation is an actual code or interface + to hardware which implements a certain transformation with precisely + defined behavior. + </para> + + <para> + The transformation object (TFM) is an instance of a transformation + implementation. There can be multiple transformation objects + associated with a single transformation implementation. Each of + those transformation objects is held by a crypto API consumer or + another transformation. Transformation object is allocated when a + crypto API consumer requests a transformation implementation. + The consumer is then provided with a structure, which contains + a transformation object (TFM). + </para> + + <para> + The structure that contains transformation objects may also be + referred to as a "cipher handle". Such a cipher handle is always + subject to the following phases that are reflected in the API calls + applicable to such a cipher handle: + </para> + + <orderedlist> + <listitem> + <para>Initialization of a cipher handle.</para> + </listitem> + <listitem> + <para>Execution of all intended cipher operations applicable + for the handle where the cipher handle must be furnished to + every API call.</para> + </listitem> + <listitem> + <para>Destruction of a cipher handle.</para> + </listitem> + </orderedlist> + + <para> + When using the initialization API calls, a cipher handle is + created and returned to the consumer. Therefore, please refer + to all initialization API calls that refer to the data + structure type a consumer is expected to receive and subsequently + to use. The initialization API calls have all the same naming + conventions of crypto_alloc_*. + </para> + + <para> + The transformation context is private data associated with + the transformation object. + </para> + </sect1> + </chapter> + + <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> + <sect1><title>Cipher algorithm types</title> + <para> + The kernel crypto API provides different API calls for the + following cipher types: + + <itemizedlist> + <listitem><para>Symmetric ciphers</para></listitem> + <listitem><para>AEAD ciphers</para></listitem> + <listitem><para>Message digest, including keyed message digest</para></listitem> + <listitem><para>Random number generation</para></listitem> + <listitem><para>User space interface</para></listitem> + </itemizedlist> + </para> + </sect1> + + <sect1><title>Ciphers And Templates</title> + <para> + The kernel crypto API provides implementations of single block + ciphers and message digests. In addition, the kernel crypto API + provides numerous "templates" that can be used in conjunction + with the single block ciphers and message digests. Templates + include all types of block chaining mode, the HMAC mechanism, etc. + </para> + + <para> + Single block ciphers and message digests can either be directly + used by a caller or invoked together with a template to form + multi-block ciphers or keyed message digests. + </para> + + <para> + A single block cipher may even be called with multiple templates. + However, templates cannot be used without a single cipher. + </para> + + <para> + See /proc/crypto and search for "name". For example: + + <itemizedlist> + <listitem><para>aes</para></listitem> + <listitem><para>ecb(aes)</para></listitem> + <listitem><para>cmac(aes)</para></listitem> + <listitem><para>ccm(aes)</para></listitem> + <listitem><para>rfc4106(gcm(aes))</para></listitem> + <listitem><para>sha1</para></listitem> + <listitem><para>hmac(sha1)</para></listitem> + <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> + </itemizedlist> + </para> + + <para> + In these examples, "aes" and "sha1" are the ciphers and all + others are the templates. + </para> + </sect1> + + <sect1><title>Synchronous And Asynchronous Operation</title> + <para> + The kernel crypto API provides synchronous and asynchronous + API operations. + </para> + + <para> + When using the synchronous API operation, the caller invokes + a cipher operation which is performed synchronously by the + kernel crypto API. That means, the caller waits until the + cipher operation completes. Therefore, the kernel crypto API + calls work like regular function calls. For synchronous + operation, the set of API calls is small and conceptually + similar to any other crypto library. + </para> + + <para> + Asynchronous operation is provided by the kernel crypto API + which implies that the invocation of a cipher operation will + complete almost instantly. That invocation triggers the + cipher operation but it does not signal its completion. Before + invoking a cipher operation, the caller must provide a callback + function the kernel crypto API can invoke to signal the + completion of the cipher operation. Furthermore, the caller + must ensure it can handle such asynchronous events by applying + appropriate locking around its data. The kernel crypto API + does not perform any special serialization operation to protect + the caller's data integrity. + </para> + </sect1> + + <sect1><title>Crypto API Cipher References And Priority</title> + <para> + A cipher is referenced by the caller with a string. That string + has the following semantics: + + <programlisting> + template(single block cipher) + </programlisting> + + where "template" and "single block cipher" is the aforementioned + template and single block cipher, respectively. If applicable, + additional templates may enclose other templates, such as + + <programlisting> + template1(template2(single block cipher))) + </programlisting> + </para> + + <para> + The kernel crypto API may provide multiple implementations of a + template or a single block cipher. For example, AES on newer + Intel hardware has the following implementations: AES-NI, + assembler implementation, or straight C. Now, when using the + string "aes" with the kernel crypto API, which cipher + implementation is used? The answer to that question is the + priority number assigned to each cipher implementation by the + kernel crypto API. When a caller uses the string to refer to a + cipher during initialization of a cipher handle, the kernel + crypto API looks up all implementations providing an + implementation with that name and selects the implementation + with the highest priority. + </para> + + <para> + Now, a caller may have the need to refer to a specific cipher + implementation and thus does not want to rely on the + priority-based selection. To accommodate this scenario, the + kernel crypto API allows the cipher implementation to register + a unique name in addition to common names. When using that + unique name, a caller is therefore always sure to refer to + the intended cipher implementation. + </para> + + <para> + The list of available ciphers is given in /proc/crypto. However, + that list does not specify all possible permutations of + templates and ciphers. Each block listed in /proc/crypto may + contain the following information -- if one of the components + listed as follows are not applicable to a cipher, it is not + displayed: + </para> + + <itemizedlist> + <listitem> + <para>name: the generic name of the cipher that is subject + to the priority-based selection -- this name can be used by + the cipher allocation API calls (all names listed above are + examples for such generic names)</para> + </listitem> + <listitem> + <para>driver: the unique name of the cipher -- this name can + be used by the cipher allocation API calls</para> + </listitem> + <listitem> + <para>module: the kernel module providing the cipher + implementation (or "kernel" for statically linked ciphers)</para> + </listitem> + <listitem> + <para>priority: the priority value of the cipher implementation</para> + </listitem> + <listitem> + <para>refcnt: the reference count of the respective cipher + (i.e. the number of current consumers of this cipher)</para> + </listitem> + <listitem> + <para>selftest: specification whether the self test for the + cipher passed</para> + </listitem> + <listitem> + <para>type: + <itemizedlist> + <listitem> + <para>skcipher for symmetric key ciphers</para> + </listitem> + <listitem> + <para>cipher for single block ciphers that may be used with + an additional template</para> + </listitem> + <listitem> + <para>shash for synchronous message digest</para> + </listitem> + <listitem> + <para>ahash for asynchronous message digest</para> + </listitem> + <listitem> + <para>aead for AEAD cipher type</para> + </listitem> + <listitem> + <para>compression for compression type transformations</para> + </listitem> + <listitem> + <para>rng for random number generator</para> + </listitem> + <listitem> + <para>givcipher for cipher with associated IV generator + (see the geniv entry below for the specification of the + IV generator type used by the cipher implementation)</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>blocksize: blocksize of cipher in bytes</para> + </listitem> + <listitem> + <para>keysize: key size in bytes</para> + </listitem> + <listitem> + <para>ivsize: IV size in bytes</para> + </listitem> + <listitem> + <para>seedsize: required size of seed data for random number + generator</para> + </listitem> + <listitem> + <para>digestsize: output size of the message digest</para> + </listitem> + <listitem> + <para>geniv: IV generation type: + <itemizedlist> + <listitem> + <para>eseqiv for encrypted sequence number based IV + generation</para> + </listitem> + <listitem> + <para>seqiv for sequence number based IV generation</para> + </listitem> + <listitem> + <para>chainiv for chain iv generation</para> + </listitem> + <listitem> + <para><builtin> is a marker that the cipher implements + IV generation and handling as it is specific to the given + cipher</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1><title>Key Sizes</title> + <para> + When allocating a cipher handle, the caller only specifies the + cipher type. Symmetric ciphers, however, typically support + multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). + These key sizes are determined with the length of the provided + key. Thus, the kernel crypto API does not provide a separate + way to select the particular symmetric cipher key size. + </para> + </sect1> + + <sect1><title>Cipher Allocation Type And Masks</title> + <para> + The different cipher handle allocation functions allow the + specification of a type and mask flag. Both parameters have + the following meaning (and are therefore not covered in the + subsequent sections). + </para> + + <para> + The type flag specifies the type of the cipher algorithm. + The caller usually provides a 0 when the caller wants the + default handling. Otherwise, the caller may provide the + following selections which match the aforementioned cipher + types: + </para> + + <itemizedlist> + <listitem> + <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with + Associated Data (MAC)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block + cipher packed together with an IV generator (see geniv field + in the /proc/crypto listing for the known IV generators)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of + CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / + decompression instead of performing the operation on one + segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace + CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> + </listitem> + </itemizedlist> + + <para> + The mask flag restricts the type of cipher. The only allowed + flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function + to asynchronous ciphers. Usually, a caller provides a 0 for the + mask flag. + </para> + + <para> + When the caller provides a mask and type specification, the + caller limits the search the kernel crypto API can perform for + a suitable cipher implementation for the given cipher name. + That means, even when a caller uses a cipher name that exists + during its initialization call, the kernel crypto API may not + select it due to the used type and mask field. + </para> + </sect1> + + <sect1><title>Internal Structure of Kernel Crypto API</title> + + <para> + The kernel crypto API has an internal structure where a cipher + implementation may use many layers and indirections. This section + shall help to clarify how the kernel crypto API uses + various components to implement the complete cipher. + </para> + + <para> + The following subsections explain the internal structure based + on existing cipher implementations. The first section addresses + the most complex scenario where all other scenarios form a logical + subset. + </para> + + <sect2><title>Generic AEAD Cipher Structure</title> + + <para> + The following ASCII art decomposes the kernel crypto API layers + when using the AEAD cipher with the automated IV generation. The + shown example is used by the IPSEC layer. + </para> + + <para> + For other use cases of AEAD ciphers, the ASCII art applies as + well, but the caller may not use the AEAD cipher with a separate + IV generator. In this case, the caller must generate the IV. + </para> + + <para> + The depicted example decomposes the AEAD cipher of GCM(AES) based + on the generic C implementations (gcm.c, aes-generic.c, ctr.c, + ghash-generic.c, seqiv.c). The generic implementation serves as an + example showing the complete logic of the kernel crypto API. + </para> + + <para> + It is possible that some streamlined cipher implementations (like + AES-NI) provide implementations merging aspects which in the view + of the kernel crypto API cannot be decomposed into layers any more. + In case of the AES-NI implementation, the CTR mode, the GHASH + implementation and the AES cipher are all merged into one cipher + implementation registered with the kernel crypto API. In this case, + the concept described by the following ASCII art applies too. However, + the decomposition of GCM into the individual sub-components + by the kernel crypto API is not done any more. + </para> + + <para> + Each block in the following ASCII art is an independent cipher + instance obtained from the kernel crypto API. Each block + is accessed by the caller or by other blocks using the API functions + defined by the kernel crypto API for the cipher implementation type. + </para> + + <para> + The blocks below indicate the cipher type as well as the specific + logic implemented in the cipher. + </para> + + <para> + The ASCII art picture also indicates the call structure, i.e. who + calls which component. The arrows point to the invoked block + where the caller uses the API applicable to the cipher type + specified for the block. + </para> + + <programlisting> +<![CDATA[ +kernel crypto API | IPSEC Layer + | ++-----------+ | +| | (1) +| aead | <----------------------------------- esp_output +| (seqiv) | ---+ ++-----------+ | + | (2) ++-----------+ | +| | <--+ (2) +| aead | <----------------------------------- esp_input +| (gcm) | ------------+ ++-----------+ | + | (3) | (5) + v v ++-----------+ +-----------+ +| | | | +| skcipher | | ahash | +| (ctr) | ---+ | (ghash) | ++-----------+ | +-----------+ + | ++-----------+ | (4) +| | <--+ +| cipher | +| (aes) | ++-----------+ +]]> + </programlisting> + + <para> + The following call sequence is applicable when the IPSEC layer + triggers an encryption operation with the esp_output function. During + configuration, the administrator set up the use of rfc4106(gcm(aes)) as + the cipher for ESP. The following call sequence is now depicted in the + ASCII art above: + </para> + + <orderedlist> + <listitem> + <para> + esp_output() invokes crypto_aead_encrypt() to trigger an encryption + operation of the AEAD cipher with IV generator. + </para> + + <para> + In case of GCM, the SEQIV implementation is registered as GIVCIPHER + in crypto_rfc4106_alloc(). + </para> + + <para> + The SEQIV performs its operation to generate an IV where the core + function is seqiv_geniv(). + </para> + </listitem> + + <listitem> + <para> + Now, SEQIV uses the AEAD API function calls to invoke the associated + AEAD cipher. In our case, during the instantiation of SEQIV, the + cipher handle for GCM is provided to SEQIV. This means that SEQIV + invokes AEAD cipher operations with the GCM cipher handle. + </para> + + <para> + During instantiation of the GCM handle, the CTR(AES) and GHASH + ciphers are instantiated. The cipher handles for CTR(AES) and GHASH + are retained for later use. + </para> + + <para> + The GCM implementation is responsible to invoke the CTR mode AES and + the GHASH cipher in the right manner to implement the GCM + specification. + </para> + </listitem> + + <listitem> + <para> + The GCM AEAD cipher type implementation now invokes the SKCIPHER API + with the instantiated CTR(AES) cipher handle. + </para> + + <para> + During instantiation of the CTR(AES) cipher, the CIPHER type + implementation of AES is instantiated. The cipher handle for AES is + retained. + </para> + + <para> + That means that the SKCIPHER implementation of CTR(AES) only + implements the CTR block chaining mode. After performing the block + chaining operation, the CIPHER implementation of AES is invoked. + </para> + </listitem> + + <listitem> + <para> + The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES + cipher handle to encrypt one block. + </para> + </listitem> + + <listitem> + <para> + The GCM AEAD implementation also invokes the GHASH cipher + implementation via the AHASH API. + </para> + </listitem> + </orderedlist> + + <para> + When the IPSEC layer triggers the esp_input() function, the same call + sequence is followed with the only difference that the operation starts + with step (2). + </para> + </sect2> + + <sect2><title>Generic Block Cipher Structure</title> + <para> + Generic block ciphers follow the same concept as depicted with the ASCII + art picture above. + </para> + + <para> + For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The + ASCII art picture above applies as well with the difference that only + step (4) is used and the SKCIPHER block chaining mode is CBC. + </para> + </sect2> + + <sect2><title>Generic Keyed Message Digest Structure</title> + <para> + Keyed message digest implementations again follow the same concept as + depicted in the ASCII art picture above. + </para> + + <para> + For example, HMAC(SHA256) is implemented with hmac.c and + sha256_generic.c. The following ASCII art illustrates the + implementation: + </para> + + <programlisting> +<![CDATA[ +kernel crypto API | Caller + | ++-----------+ (1) | +| | <------------------ some_function +| ahash | +| (hmac) | ---+ ++-----------+ | + | (2) ++-----------+ | +| | <--+ +| shash | +| (sha256) | ++-----------+ +]]> + </programlisting> + + <para> + The following call sequence is applicable when a caller triggers + an HMAC operation: + </para> + + <orderedlist> + <listitem> + <para> + The AHASH API functions are invoked by the caller. The HMAC + implementation performs its operation as needed. + </para> + + <para> + During initialization of the HMAC cipher, the SHASH cipher type of + SHA256 is instantiated. The cipher handle for the SHA256 instance is + retained. + </para> + + <para> + At one time, the HMAC implementation requires a SHA256 operation + where the SHA256 cipher handle is used. + </para> + </listitem> + + <listitem> + <para> + The HMAC instance now invokes the SHASH API with the SHA256 + cipher handle to calculate the message digest. + </para> + </listitem> + </orderedlist> + </sect2> + </sect1> + </chapter> + + <chapter id="Development"><title>Developing Cipher Algorithms</title> + <sect1><title>Registering And Unregistering Transformation</title> + <para> + There are three distinct types of registration functions in + the Crypto API. One is used to register a generic cryptographic + transformation, while the other two are specific to HASH + transformations and COMPRESSion. We will discuss the latter + two in a separate chapter, here we will only look at the + generic ones. + </para> + + <para> + Before discussing the register functions, the data structure + to be filled with each, struct crypto_alg, must be considered + -- see below for a description of this data structure. + </para> + + <para> + The generic registration functions can be found in + include/linux/crypto.h and their definition can be seen below. + The former function registers a single transformation, while + the latter works on an array of transformation descriptions. + The latter is useful when registering transformations in bulk, + for example when a driver implements multiple transformations. + </para> + + <programlisting> + int crypto_register_alg(struct crypto_alg *alg); + int crypto_register_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + The counterparts to those functions are listed below. + </para> + + <programlisting> + int crypto_unregister_alg(struct crypto_alg *alg); + int crypto_unregister_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + Notice that both registration and unregistration functions + do return a value, so make sure to handle errors. A return + code of zero implies success. Any return code < 0 implies + an error. + </para> + + <para> + The bulk registration/unregistration functions + register/unregister each transformation in the given array of + length count. They handle errors as follows: + </para> + <itemizedlist> + <listitem> + <para> + crypto_register_algs() succeeds if and only if it + successfully registers all the given transformations. If an + error occurs partway through, then it rolls back successful + registrations before returning the error code. Note that if + a driver needs to handle registration errors for individual + transformations, then it will need to use the non-bulk + function crypto_register_alg() instead. + </para> + </listitem> + <listitem> + <para> + crypto_unregister_algs() tries to unregister all the given + transformations, continuing on error. It logs errors and + always returns zero. + </para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> + <para> + Example of transformations: aes, arc4, ... + </para> + + <para> + This section describes the simplest of all transformation + implementations, that being the CIPHER type used for symmetric + ciphers. The CIPHER type is used for transformations which + operate on exactly one block at a time and there are no + dependencies between blocks at all. + </para> + + <sect2><title>Registration specifics</title> + <para> + The registration of [CIPHER] algorithm is specific in that + struct crypto_alg field .cra_type is empty. The .cra_u.cipher + has to be filled in with proper callbacks to implement this + transformation. + </para> + + <para> + See struct cipher_alg below. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct cipher_alg</title> + <para> + Struct cipher_alg defines a single block cipher. + </para> + + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the + .cia_setkey() call might happen before or after any of these + schematics happen, but must not happen during any of these + are in-flight. + </para> + + <para> + <programlisting> + KEY ---. PLAINTEXT ---. + v v + .cia_setkey() -> .cia_encrypt() + | + '-----> CIPHERTEXT + </programlisting> + </para> + + <para> + Please note that a pattern where .cia_setkey() is called + multiple times is also valid: + </para> + + <para> + <programlisting> + + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. + v v v v + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() + | | + '---> CIPHERTEXT1 '---> CIPHERTEXT2 + </programlisting> + </para> + + </sect2> + </sect1> + + <sect1><title>Multi-Block Ciphers</title> + <para> + Example of transformations: cbc(aes), ecb(arc4), ... + </para> + + <para> + This section describes the multi-block cipher transformation + implementations. The multi-block ciphers are + used for transformations which operate on scatterlists of + data supplied to the transformation functions. They output + the result into a scatterlist of data as well. + </para> + + <sect2><title>Registration Specifics</title> + + <para> + The registration of multi-block cipher algorithms + is one of the most standard procedures throughout the crypto API. + </para> + + <para> + Note, if a cipher implementation requires a proper alignment + of data, the caller should use the functions of + crypto_skcipher_alignmask() to identify a memory alignment mask. + The kernel crypto API is able to process requests that are unaligned. + This implies, however, additional overhead as the kernel + crypto API needs to perform the realignment of the data which + may imply moving of data. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> + <para> + Struct blkcipher_alg defines a synchronous block cipher whereas + struct ablkcipher_alg defines an asynchronous block cipher. + </para> + + <para> + Please refer to the single block cipher description for schematics + of the block cipher usage. + </para> + </sect2> + + <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> + <para> + There are a couple of specifics to the asynchronous interface. + </para> + + <para> + First of all, some of the drivers will want to use the + Generic ScatterWalk in case the hardware needs to be fed + separate chunks of the scatterlist which contains the + plaintext and will contain the ciphertext. Please refer + to the ScatterWalk interface offered by the Linux kernel + scatter / gather list implementation. + </para> + </sect2> + </sect1> + + <sect1><title>Hashing [HASH]</title> + + <para> + Example of transformations: crc32, md5, sha1, sha256,... + </para> + + <sect2><title>Registering And Unregistering The Transformation</title> + + <para> + There are multiple ways to register a HASH transformation, + depending on whether the transformation is synchronous [SHASH] + or asynchronous [AHASH] and the amount of HASH transformations + we are registering. You can find the prototypes defined in + include/crypto/internal/hash.h: + </para> + + <programlisting> + int crypto_register_ahash(struct ahash_alg *alg); + + int crypto_register_shash(struct shash_alg *alg); + int crypto_register_shashes(struct shash_alg *algs, int count); + </programlisting> + + <para> + The respective counterparts for unregistering the HASH + transformation are as follows: + </para> + + <programlisting> + int crypto_unregister_ahash(struct ahash_alg *alg); + + int crypto_unregister_shash(struct shash_alg *alg); + int crypto_unregister_shashes(struct shash_alg *algs, int count); + </programlisting> + </sect2> + + <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the .setkey() + call might happen before or after any of these schematics happen, + but must not happen during any of these are in-flight. Please note + that calling .init() followed immediately by .finish() is also a + perfectly valid transformation. + </para> + + <programlisting> + I) DATA -----------. + v + .init() -> .update() -> .final() ! .update() might not be called + ^ | | at all in this scenario. + '----' '---> HASH + + II) DATA -----------.-----------. + v v + .init() -> .update() -> .finup() ! .update() may not be called + ^ | | at all in this scenario. + '----' '---> HASH + + III) DATA -----------. + v + .digest() ! The entire process is handled + | by the .digest() call. + '---------------> HASH + </programlisting> + + <para> + Here is a schematic of how the .export()/.import() functions are + called when used from another part of the kernel. + </para> + + <programlisting> + KEY--. DATA--. + v v ! .update() may not be called + .setkey() -> .init() -> .update() -> .export() at all in this scenario. + ^ | | + '-----' '--> PARTIAL_HASH + + ----------- other transformations happen here ----------- + + PARTIAL_HASH--. DATA1--. + v v + .import -> .update() -> .final() ! .update() may not be called + ^ | | at all in this scenario. + '----' '--> HASH1 + + PARTIAL_HASH--. DATA2-. + v v + .import -> .finup() + | + '---------------> HASH2 + </programlisting> + </sect2> + + <sect2><title>Specifics Of Asynchronous HASH Transformation</title> + <para> + Some of the drivers will want to use the Generic ScatterWalk + in case the implementation needs to be fed separate chunks of the + scatterlist which contains the input data. The buffer containing + the resulting hash will always be properly aligned to + .cra_alignmask so there is no need to worry about this. + </para> + </sect2> + </sect1> + </chapter> + + <chapter id="User"><title>User Space Interface</title> + <sect1><title>Introduction</title> + <para> + The concepts of the kernel crypto API visible to kernel space is fully + applicable to the user space interface as well. Therefore, the kernel + crypto API high level discussion for the in-kernel use cases applies + here as well. + </para> + + <para> + The major difference, however, is that user space can only act as a + consumer and never as a provider of a transformation or cipher algorithm. + </para> + + <para> + The following covers the user space interface exported by the kernel + crypto API. A working example of this description is libkcapi that + can be obtained from [1]. That library can be used by user space + applications that require cryptographic services from the kernel. + </para> + + <para> + Some details of the in-kernel kernel crypto API aspects do not + apply to user space, however. This includes the difference between + synchronous and asynchronous invocations. The user space API call + is fully synchronous. + </para> + + <para> + [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> + </para> + + </sect1> + + <sect1><title>User Space API General Remarks</title> + <para> + The kernel crypto API is accessible from user space. Currently, + the following ciphers are accessible: + </para> + + <itemizedlist> + <listitem> + <para>Message digest including keyed message digest (HMAC, CMAC)</para> + </listitem> + + <listitem> + <para>Symmetric ciphers</para> + </listitem> + + <listitem> + <para>AEAD ciphers</para> + </listitem> + + <listitem> + <para>Random Number Generators</para> + </listitem> + </itemizedlist> + + <para> + The interface is provided via socket type using the type AF_ALG. + In addition, the setsockopt option type is SOL_ALG. In case the + user space header files do not export these flags yet, use the + following macros: + </para> + + <programlisting> +#ifndef AF_ALG +#define AF_ALG 38 +#endif +#ifndef SOL_ALG +#define SOL_ALG 279 +#endif + </programlisting> + + <para> + A cipher is accessed with the same name as done for the in-kernel + API calls. This includes the generic vs. unique naming schema for + ciphers as well as the enforcement of priorities for generic names. + </para> + + <para> + To interact with the kernel crypto API, a socket must be + created by the user space application. User space invokes the cipher + operation with the send()/write() system call family. The result of the + cipher operation is obtained with the read()/recv() system call family. + </para> + + <para> + The following API calls assume that the socket descriptor + is already opened by the user space application and discusses only + the kernel crypto API specific invocations. + </para> + + <para> + To initialize the socket interface, the following sequence has to + be performed by the consumer: + </para> + + <orderedlist> + <listitem> + <para> + Create a socket of type AF_ALG with the struct sockaddr_alg + parameter specified below for the different cipher types. + </para> + </listitem> + + <listitem> + <para> + Invoke bind with the socket descriptor + </para> + </listitem> + + <listitem> + <para> + Invoke accept with the socket descriptor. The accept system call + returns a new file descriptor that is to be used to interact with + the particular cipher instance. When invoking send/write or recv/read + system calls to send data to the kernel or obtain data from the + kernel, the file descriptor returned by accept must be used. + </para> + </listitem> + </orderedlist> + </sect1> + + <sect1><title>In-place Cipher operation</title> + <para> + Just like the in-kernel operation of the kernel crypto API, the user + space interface allows the cipher operation in-place. That means that + the input buffer used for the send/write system call and the output + buffer used by the read/recv system call may be one and the same. + This is of particular interest for symmetric cipher operations where a + copying of the output data to its final destination can be avoided. + </para> + + <para> + If a consumer on the other hand wants to maintain the plaintext and + the ciphertext in different memory locations, all a consumer needs + to do is to provide different memory pointers for the encryption and + decryption operation. + </para> + </sect1> + + <sect1><title>Message Digest API</title> + <para> + The message digest type to be used for the cipher operation is + selected when invoking the bind syscall. bind requires the caller + to provide a filled struct sockaddr data structure. This data + structure must be filled as follows: + </para> + + <programlisting> +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "hash", /* this selects the hash logic in the kernel */ + .salg_name = "sha1" /* this is the cipher name */ +}; + </programlisting> + + <para> + The salg_type value "hash" applies to message digests and keyed + message digests. Though, a keyed message digest is referenced by + the appropriate salg_name. Please see below for the setsockopt + interface that explains how the key can be set for a keyed message + digest. + </para> + + <para> + Using the send() system call, the application provides the data that + should be processed with the message digest. The send system call + allows the following flags to be specified: + </para> + + <itemizedlist> + <listitem> + <para> + MSG_MORE: If this flag is set, the send system call acts like a + message digest update function where the final hash is not + yet calculated. If the flag is not set, the send system call + calculates the final message digest immediately. + </para> + </listitem> + </itemizedlist> + + <para> + With the recv() system call, the application can read the message + digest from the kernel crypto API. If the buffer is too small for the + message digest, the flag MSG_TRUNC is set by the kernel. + </para> + + <para> + In order to set a message digest key, the calling application must use + the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC + operation is performed without the initial HMAC state change caused by + the key. + </para> + </sect1> + + <sect1><title>Symmetric Cipher API</title> + <para> + The operation is very similar to the message digest discussion. + During initialization, the struct sockaddr data structure must be + filled as follows: + </para> + + <programlisting> +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "skcipher", /* this selects the symmetric cipher */ + .salg_name = "cbc(aes)" /* this is the cipher name */ +}; + </programlisting> + + <para> + Before data can be sent to the kernel using the write/send system + call family, the consumer must set the key. The key setting is + described with the setsockopt invocation below. + </para> + + <para> + Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is + specified with the data structure provided by the sendmsg() system call. + </para> + + <para> + The sendmsg system call parameter of struct msghdr is embedded into the + struct cmsghdr data structure. See recv(2) and cmsg(3) for more + information on how the cmsghdr data structure is used together with the + send/recv system call family. That cmsghdr data structure holds the + following information specified with a separate header instances: + </para> + + <itemizedlist> + <listitem> + <para> + specification of the cipher operation type with one of these flags: + </para> + <itemizedlist> + <listitem> + <para>ALG_OP_ENCRYPT - encryption of data</para> + </listitem> + <listitem> + <para>ALG_OP_DECRYPT - decryption of data</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para> + specification of the IV information marked with the flag ALG_SET_IV + </para> + </listitem> + </itemizedlist> + + <para> + The send system call family allows the following flag to be specified: + </para> + + <itemizedlist> + <listitem> + <para> + MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected + with a subsequent invocation of the send system call. + </para> + </listitem> + </itemizedlist> + + <para> + Note: The kernel reports -EINVAL for any unexpected data. The caller + must make sure that all data matches the constraints given in + /proc/crypto for the selected cipher. + </para> + + <para> + With the recv() system call, the application can read the result of + the cipher operation from the kernel crypto API. The output buffer + must be at least as large as to hold all blocks of the encrypted or + decrypted data. If the output data size is smaller, only as many + blocks are returned that fit into that output buffer size. + </para> + </sect1> + + <sect1><title>AEAD Cipher API</title> + <para> + The operation is very similar to the symmetric cipher discussion. + During initialization, the struct sockaddr data structure must be + filled as follows: + </para> + + <programlisting> +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "aead", /* this selects the symmetric cipher */ + .salg_name = "gcm(aes)" /* this is the cipher name */ +}; + </programlisting> + + <para> + Before data can be sent to the kernel using the write/send system + call family, the consumer must set the key. The key setting is + described with the setsockopt invocation below. + </para> + + <para> + In addition, before data can be sent to the kernel using the + write/send system call family, the consumer must set the authentication + tag size. To set the authentication tag size, the caller must use the + setsockopt invocation described below. + </para> + + <para> + Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is + specified with the data structure provided by the sendmsg() system call. + </para> + + <para> + The sendmsg system call parameter of struct msghdr is embedded into the + struct cmsghdr data structure. See recv(2) and cmsg(3) for more + information on how the cmsghdr data structure is used together with the + send/recv system call family. That cmsghdr data structure holds the + following information specified with a separate header instances: + </para> + + <itemizedlist> + <listitem> + <para> + specification of the cipher operation type with one of these flags: + </para> + <itemizedlist> + <listitem> + <para>ALG_OP_ENCRYPT - encryption of data</para> + </listitem> + <listitem> + <para>ALG_OP_DECRYPT - decryption of data</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para> + specification of the IV information marked with the flag ALG_SET_IV + </para> + </listitem> + + <listitem> + <para> + specification of the associated authentication data (AAD) with the + flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together + with the plaintext / ciphertext. See below for the memory structure. + </para> + </listitem> + </itemizedlist> + + <para> + The send system call family allows the following flag to be specified: + </para> + + <itemizedlist> + <listitem> + <para> + MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected + with a subsequent invocation of the send system call. + </para> + </listitem> + </itemizedlist> + + <para> + Note: The kernel reports -EINVAL for any unexpected data. The caller + must make sure that all data matches the constraints given in + /proc/crypto for the selected cipher. + </para> + + <para> + With the recv() system call, the application can read the result of + the cipher operation from the kernel crypto API. The output buffer + must be at least as large as defined with the memory structure below. + If the output data size is smaller, the cipher operation is not performed. + </para> + + <para> + The authenticated decryption operation may indicate an integrity error. + Such breach in integrity is marked with the -EBADMSG error code. + </para> + + <sect2><title>AEAD Memory Structure</title> + <para> + The AEAD cipher operates with the following information that + is communicated between user and kernel space as one data stream: + </para> + + <itemizedlist> + <listitem> + <para>plaintext or ciphertext</para> + </listitem> + + <listitem> + <para>associated authentication data (AAD)</para> + </listitem> + + <listitem> + <para>authentication tag</para> + </listitem> + </itemizedlist> + + <para> + The sizes of the AAD and the authentication tag are provided with + the sendmsg and setsockopt calls (see there). As the kernel knows + the size of the entire data stream, the kernel is now able to + calculate the right offsets of the data components in the data + stream. + </para> + + <para> + The user space caller must arrange the aforementioned information + in the following order: + </para> + + <itemizedlist> + <listitem> + <para> + AEAD encryption input: AAD || plaintext + </para> + </listitem> + + <listitem> + <para> + AEAD decryption input: AAD || ciphertext || authentication tag + </para> + </listitem> + </itemizedlist> + + <para> + The output buffer the user space caller provides must be at least as + large to hold the following data: + </para> + + <itemizedlist> + <listitem> + <para> + AEAD encryption output: ciphertext || authentication tag + </para> + </listitem> + + <listitem> + <para> + AEAD decryption output: plaintext + </para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1><title>Random Number Generator API</title> + <para> + Again, the operation is very similar to the other APIs. + During initialization, the struct sockaddr data structure must be + filled as follows: + </para> + + <programlisting> +struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "rng", /* this selects the symmetric cipher */ + .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ +}; + </programlisting> + + <para> + Depending on the RNG type, the RNG must be seeded. The seed is provided + using the setsockopt interface to set the key. For example, the + ansi_cprng requires a seed. The DRBGs do not require a seed, but + may be seeded. + </para> + + <para> + Using the read()/recvmsg() system calls, random numbers can be obtained. + The kernel generates at most 128 bytes in one call. If user space + requires more data, multiple calls to read()/recvmsg() must be made. + </para> + + <para> + WARNING: The user space caller may invoke the initially mentioned + accept system call multiple times. In this case, the returned file + descriptors have the same state. + </para> + + </sect1> + + <sect1><title>Zero-Copy Interface</title> + <para> + In addition to the send/write/read/recv system call family, the AF_ALG + interface can be accessed with the zero-copy interface of splice/vmsplice. + As the name indicates, the kernel tries to avoid a copy operation into + kernel space. + </para> + + <para> + The zero-copy operation requires data to be aligned at the page boundary. + Non-aligned data can be used as well, but may require more operations of + the kernel which would defeat the speed gains obtained from the zero-copy + interface. + </para> + + <para> + The system-interent limit for the size of one zero-copy operation is + 16 pages. If more data is to be sent to AF_ALG, user space must slice + the input into segments with a maximum size of 16 pages. + </para> + + <para> + Zero-copy can be used with the following code example (a complete working + example is provided with libkcapi): + </para> + + <programlisting> +int pipes[2]; + +pipe(pipes); +/* input data in iov */ +vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); +/* opfd is the file descriptor returned from accept() system call */ +splice(pipes[0], NULL, opfd, NULL, ret, 0); +read(opfd, out, outlen); + </programlisting> + + </sect1> + + <sect1><title>Setsockopt Interface</title> + <para> + In addition to the read/recv and send/write system call handling + to send and retrieve data subject to the cipher operation, a consumer + also needs to set the additional information for the cipher operation. + This additional information is set using the setsockopt system call + that must be invoked with the file descriptor of the open cipher + (i.e. the file descriptor returned by the accept system call). + </para> + + <para> + Each setsockopt invocation must use the level SOL_ALG. + </para> + + <para> + The setsockopt interface allows setting the following data using + the mentioned optname: + </para> + + <itemizedlist> + <listitem> + <para> + ALG_SET_KEY -- Setting the key. Key setting is applicable to: + </para> + <itemizedlist> + <listitem> + <para>the skcipher cipher type (symmetric ciphers)</para> + </listitem> + <listitem> + <para>the hash cipher type (keyed message digests)</para> + </listitem> + <listitem> + <para>the AEAD cipher type</para> + </listitem> + <listitem> + <para>the RNG cipher type to provide the seed</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para> + ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size + for AEAD ciphers. For a encryption operation, the authentication + tag of the given size will be generated. For a decryption operation, + the provided ciphertext is assumed to contain an authentication tag + of the given size (see section about AEAD memory layout below). + </para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1><title>User space API example</title> + <para> + Please see [1] for libkcapi which provides an easy-to-use wrapper + around the aforementioned Netlink kernel interface. [1] also contains + a test application that invokes all libkcapi API calls. + </para> + + <para> + [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> + </para> + + </sect1> + + </chapter> + + <chapter id="API"><title>Programming Interface</title> + <para> + Please note that the kernel crypto API contains the AEAD givcrypt + API (crypto_aead_giv* and aead_givcrypt_* function calls in + include/crypto/aead.h). This API is obsolete and will be removed + in the future. To obtain the functionality of an AEAD cipher with + internal IV generation, use the IV generator as a regular cipher. + For example, rfc4106(gcm(aes)) is the AEAD cipher with external + IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel + crypto API generates the IV. Different IV generators are available. + </para> + <sect1><title>Block Cipher Context Data Structures</title> +!Pinclude/linux/crypto.h Block Cipher Context Data Structures +!Finclude/crypto/aead.h aead_request + </sect1> + <sect1><title>Block Cipher Algorithm Definitions</title> +!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions +!Finclude/linux/crypto.h crypto_alg +!Finclude/linux/crypto.h ablkcipher_alg +!Finclude/crypto/aead.h aead_alg +!Finclude/linux/crypto.h blkcipher_alg +!Finclude/linux/crypto.h cipher_alg +!Finclude/crypto/rng.h rng_alg + </sect1> + <sect1><title>Symmetric Key Cipher API</title> +!Pinclude/crypto/skcipher.h Symmetric Key Cipher API +!Finclude/crypto/skcipher.h crypto_alloc_skcipher +!Finclude/crypto/skcipher.h crypto_free_skcipher +!Finclude/crypto/skcipher.h crypto_has_skcipher +!Finclude/crypto/skcipher.h crypto_skcipher_ivsize +!Finclude/crypto/skcipher.h crypto_skcipher_blocksize +!Finclude/crypto/skcipher.h crypto_skcipher_setkey +!Finclude/crypto/skcipher.h crypto_skcipher_reqtfm +!Finclude/crypto/skcipher.h crypto_skcipher_encrypt +!Finclude/crypto/skcipher.h crypto_skcipher_decrypt + </sect1> + <sect1><title>Symmetric Key Cipher Request Handle</title> +!Pinclude/crypto/skcipher.h Symmetric Key Cipher Request Handle +!Finclude/crypto/skcipher.h crypto_skcipher_reqsize +!Finclude/crypto/skcipher.h skcipher_request_set_tfm +!Finclude/crypto/skcipher.h skcipher_request_alloc +!Finclude/crypto/skcipher.h skcipher_request_free +!Finclude/crypto/skcipher.h skcipher_request_set_callback +!Finclude/crypto/skcipher.h skcipher_request_set_crypt + </sect1> + <sect1><title>Asynchronous Block Cipher API - Deprecated</title> +!Pinclude/linux/crypto.h Asynchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_ablkcipher +!Finclude/linux/crypto.h crypto_free_ablkcipher +!Finclude/linux/crypto.h crypto_has_ablkcipher +!Finclude/linux/crypto.h crypto_ablkcipher_ivsize +!Finclude/linux/crypto.h crypto_ablkcipher_blocksize +!Finclude/linux/crypto.h crypto_ablkcipher_setkey +!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm +!Finclude/linux/crypto.h crypto_ablkcipher_encrypt +!Finclude/linux/crypto.h crypto_ablkcipher_decrypt + </sect1> + <sect1><title>Asynchronous Cipher Request Handle - Deprecated</title> +!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle +!Finclude/linux/crypto.h crypto_ablkcipher_reqsize +!Finclude/linux/crypto.h ablkcipher_request_set_tfm +!Finclude/linux/crypto.h ablkcipher_request_alloc +!Finclude/linux/crypto.h ablkcipher_request_free +!Finclude/linux/crypto.h ablkcipher_request_set_callback +!Finclude/linux/crypto.h ablkcipher_request_set_crypt + </sect1> + <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> +!Pinclude/crypto/aead.h Authenticated Encryption With Associated Data (AEAD) Cipher API +!Finclude/crypto/aead.h crypto_alloc_aead +!Finclude/crypto/aead.h crypto_free_aead +!Finclude/crypto/aead.h crypto_aead_ivsize +!Finclude/crypto/aead.h crypto_aead_authsize +!Finclude/crypto/aead.h crypto_aead_blocksize +!Finclude/crypto/aead.h crypto_aead_setkey +!Finclude/crypto/aead.h crypto_aead_setauthsize +!Finclude/crypto/aead.h crypto_aead_encrypt +!Finclude/crypto/aead.h crypto_aead_decrypt + </sect1> + <sect1><title>Asynchronous AEAD Request Handle</title> +!Pinclude/crypto/aead.h Asynchronous AEAD Request Handle +!Finclude/crypto/aead.h crypto_aead_reqsize +!Finclude/crypto/aead.h aead_request_set_tfm +!Finclude/crypto/aead.h aead_request_alloc +!Finclude/crypto/aead.h aead_request_free +!Finclude/crypto/aead.h aead_request_set_callback +!Finclude/crypto/aead.h aead_request_set_crypt +!Finclude/crypto/aead.h aead_request_set_ad + </sect1> + <sect1><title>Synchronous Block Cipher API - Deprecated</title> +!Pinclude/linux/crypto.h Synchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_blkcipher +!Finclude/linux/crypto.h crypto_free_blkcipher +!Finclude/linux/crypto.h crypto_has_blkcipher +!Finclude/linux/crypto.h crypto_blkcipher_name +!Finclude/linux/crypto.h crypto_blkcipher_ivsize +!Finclude/linux/crypto.h crypto_blkcipher_blocksize +!Finclude/linux/crypto.h crypto_blkcipher_setkey +!Finclude/linux/crypto.h crypto_blkcipher_encrypt +!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_decrypt +!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_set_iv +!Finclude/linux/crypto.h crypto_blkcipher_get_iv + </sect1> + <sect1><title>Single Block Cipher API</title> +!Pinclude/linux/crypto.h Single Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_cipher +!Finclude/linux/crypto.h crypto_free_cipher +!Finclude/linux/crypto.h crypto_has_cipher +!Finclude/linux/crypto.h crypto_cipher_blocksize +!Finclude/linux/crypto.h crypto_cipher_setkey +!Finclude/linux/crypto.h crypto_cipher_encrypt_one +!Finclude/linux/crypto.h crypto_cipher_decrypt_one + </sect1> + <sect1><title>Message Digest Algorithm Definitions</title> +!Pinclude/crypto/hash.h Message Digest Algorithm Definitions +!Finclude/crypto/hash.h hash_alg_common +!Finclude/crypto/hash.h ahash_alg +!Finclude/crypto/hash.h shash_alg + </sect1> + <sect1><title>Asynchronous Message Digest API</title> +!Pinclude/crypto/hash.h Asynchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_ahash +!Finclude/crypto/hash.h crypto_free_ahash +!Finclude/crypto/hash.h crypto_ahash_init +!Finclude/crypto/hash.h crypto_ahash_digestsize +!Finclude/crypto/hash.h crypto_ahash_reqtfm +!Finclude/crypto/hash.h crypto_ahash_reqsize +!Finclude/crypto/hash.h crypto_ahash_setkey +!Finclude/crypto/hash.h crypto_ahash_finup +!Finclude/crypto/hash.h crypto_ahash_final +!Finclude/crypto/hash.h crypto_ahash_digest +!Finclude/crypto/hash.h crypto_ahash_export +!Finclude/crypto/hash.h crypto_ahash_import + </sect1> + <sect1><title>Asynchronous Hash Request Handle</title> +!Pinclude/crypto/hash.h Asynchronous Hash Request Handle +!Finclude/crypto/hash.h ahash_request_set_tfm +!Finclude/crypto/hash.h ahash_request_alloc +!Finclude/crypto/hash.h ahash_request_free +!Finclude/crypto/hash.h ahash_request_set_callback +!Finclude/crypto/hash.h ahash_request_set_crypt + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/crypto/hash.h Synchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_shash +!Finclude/crypto/hash.h crypto_free_shash +!Finclude/crypto/hash.h crypto_shash_blocksize +!Finclude/crypto/hash.h crypto_shash_digestsize +!Finclude/crypto/hash.h crypto_shash_descsize +!Finclude/crypto/hash.h crypto_shash_setkey +!Finclude/crypto/hash.h crypto_shash_digest +!Finclude/crypto/hash.h crypto_shash_export +!Finclude/crypto/hash.h crypto_shash_import +!Finclude/crypto/hash.h crypto_shash_init +!Finclude/crypto/hash.h crypto_shash_update +!Finclude/crypto/hash.h crypto_shash_final +!Finclude/crypto/hash.h crypto_shash_finup + </sect1> + <sect1><title>Crypto API Random Number API</title> +!Pinclude/crypto/rng.h Random number generator API +!Finclude/crypto/rng.h crypto_alloc_rng +!Finclude/crypto/rng.h crypto_rng_alg +!Finclude/crypto/rng.h crypto_free_rng +!Finclude/crypto/rng.h crypto_rng_generate +!Finclude/crypto/rng.h crypto_rng_get_bytes +!Finclude/crypto/rng.h crypto_rng_reset +!Finclude/crypto/rng.h crypto_rng_seedsize +!Cinclude/crypto/rng.h + </sect1> + <sect1><title>Asymmetric Cipher API</title> +!Pinclude/crypto/akcipher.h Generic Public Key API +!Finclude/crypto/akcipher.h akcipher_alg +!Finclude/crypto/akcipher.h akcipher_request +!Finclude/crypto/akcipher.h crypto_alloc_akcipher +!Finclude/crypto/akcipher.h crypto_free_akcipher +!Finclude/crypto/akcipher.h crypto_akcipher_set_pub_key +!Finclude/crypto/akcipher.h crypto_akcipher_set_priv_key + </sect1> + <sect1><title>Asymmetric Cipher Request Handle</title> +!Finclude/crypto/akcipher.h akcipher_request_alloc +!Finclude/crypto/akcipher.h akcipher_request_free +!Finclude/crypto/akcipher.h akcipher_request_set_callback +!Finclude/crypto/akcipher.h akcipher_request_set_crypt +!Finclude/crypto/akcipher.h crypto_akcipher_maxsize +!Finclude/crypto/akcipher.h crypto_akcipher_encrypt +!Finclude/crypto/akcipher.h crypto_akcipher_decrypt +!Finclude/crypto/akcipher.h crypto_akcipher_sign +!Finclude/crypto/akcipher.h crypto_akcipher_verify + </sect1> + </chapter> + + <chapter id="Code"><title>Code Examples</title> + <sect1><title>Code Example For Symmetric Key Cipher Operation</title> + <programlisting> + +struct tcrypt_result { + struct completion completion; + int err; +}; + +/* tie all data structures together */ +struct skcipher_def { + struct scatterlist sg; + struct crypto_skcipher *tfm; + struct skcipher_request *req; + struct tcrypt_result result; +}; + +/* Callback function */ +static void test_skcipher_cb(struct crypto_async_request *req, int error) +{ + struct tcrypt_result *result = req->data; + + if (error == -EINPROGRESS) + return; + result->err = error; + complete(&result->completion); + pr_info("Encryption finished successfully\n"); +} + +/* Perform cipher operation */ +static unsigned int test_skcipher_encdec(struct skcipher_def *sk, + int enc) +{ + int rc = 0; + + if (enc) + rc = crypto_skcipher_encrypt(sk->req); + else + rc = crypto_skcipher_decrypt(sk->req); + + switch (rc) { + case 0: + break; + case -EINPROGRESS: + case -EBUSY: + rc = wait_for_completion_interruptible( + &sk->result.completion); + if (!rc && !sk->result.err) { + reinit_completion(&sk->result.completion); + break; + } + default: + pr_info("skcipher encrypt returned with %d result %d\n", + rc, sk->result.err); + break; + } + init_completion(&sk->result.completion); + + return rc; +} + +/* Initialize and trigger cipher operation */ +static int test_skcipher(void) +{ + struct skcipher_def sk; + struct crypto_skcipher *skcipher = NULL; + struct skcipher_request *req = NULL; + char *scratchpad = NULL; + char *ivdata = NULL; + unsigned char key[32]; + int ret = -EFAULT; + + skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0); + if (IS_ERR(skcipher)) { + pr_info("could not allocate skcipher handle\n"); + return PTR_ERR(skcipher); + } + + req = skcipher_request_alloc(skcipher, GFP_KERNEL); + if (!req) { + pr_info("could not allocate skcipher request\n"); + ret = -ENOMEM; + goto out; + } + + skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, + test_skcipher_cb, + &sk.result); + + /* AES 256 with random key */ + get_random_bytes(&key, 32); + if (crypto_skcipher_setkey(skcipher, key, 32)) { + pr_info("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + /* IV will be random */ + ivdata = kmalloc(16, GFP_KERNEL); + if (!ivdata) { + pr_info("could not allocate ivdata\n"); + goto out; + } + get_random_bytes(ivdata, 16); + + /* Input data will be random */ + scratchpad = kmalloc(16, GFP_KERNEL); + if (!scratchpad) { + pr_info("could not allocate scratchpad\n"); + goto out; + } + get_random_bytes(scratchpad, 16); + + sk.tfm = skcipher; + sk.req = req; + + /* We encrypt one block */ + sg_init_one(&sk.sg, scratchpad, 16); + skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata); + init_completion(&sk.result.completion); + + /* encrypt data */ + ret = test_skcipher_encdec(&sk, 1); + if (ret) + goto out; + + pr_info("Encryption triggered successfully\n"); + +out: + if (skcipher) + crypto_free_skcipher(skcipher); + if (req) + skcipher_request_free(req); + if (ivdata) + kfree(ivdata); + if (scratchpad) + kfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> + <programlisting> + +struct sdesc { + struct shash_desc shash; + char ctx[]; +}; + +static struct sdescinit_sdesc(struct crypto_shash *alg) +{ + struct sdescsdesc; + int size; + + size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); + sdesc = kmalloc(size, GFP_KERNEL); + if (!sdesc) + return ERR_PTR(-ENOMEM); + sdesc->shash.tfm = alg; + sdesc->shash.flags = 0x0; + return sdesc; +} + +static int calc_hash(struct crypto_shashalg, + const unsigned chardata, unsigned int datalen, + unsigned chardigest) { + struct sdescsdesc; + int ret; + + sdesc = init_sdesc(alg); + if (IS_ERR(sdesc)) { + pr_info("trusted_key: can't alloc %s\n", hash_alg); + return PTR_ERR(sdesc); + } + + ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); + kfree(sdesc); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Random Number Generator Usage</title> + <programlisting> + +static int get_random_numbers(u8 *buf, unsigned int len) +{ + struct crypto_rngrng = NULL; + chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ + int ret; + + if (!buf || !len) { + pr_debug("No output buffer provided\n"); + return -EINVAL; + } + + rng = crypto_alloc_rng(drbg, 0, 0); + if (IS_ERR(rng)) { + pr_debug("could not allocate RNG handle for %s\n", drbg); + return -PTR_ERR(rng); + } + + ret = crypto_rng_get_bytes(rng, buf, len); + if (ret < 0) + pr_debug("generation of random numbers failed\n"); + else if (ret == 0) + pr_debug("RNG returned no data"); + else + pr_debug("RNG returned %d bytes of data\n", ret); + +out: + crypto_free_rng(rng); + return ret; +} + </programlisting> + </sect1> + </chapter> + </book>
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl new file mode 100644 index 0000000..7e4f34f --- /dev/null +++ b/Documentation/DocBook/debugobjects.tmpl
@@ -0,0 +1,443 @@ +<?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> + <listitem><para>debug_object_assert_init</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> + + <sect1 id="debug_object_assert_init"> + <title>debug_object_assert_init</title> + <para> + This function is called to assert that an object has been + initialized. + </para> + <para> + When the real object is not tracked by debugobjects, it calls + fixup_assert_init of the object type description structure + provided by the caller, with the hardcoded object state + ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem + by calling debug_object_init and other specific initializing + functions. + </para> + <para> + When the real object is already tracked by debugobjects it is + ignored. + </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 true when the fixup was successful, + otherwise false. 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 true when the fixup was successful, + otherwise false. 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 false 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 true when the fixup was successful, + otherwise false. 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 true when the fixup was successful, + otherwise false. The return value is used to update the + statistics. + </para> + </sect1> + <sect1 id="fixup_assert_init"> + <title>fixup_assert_init</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_assert_init is detected. + </para> + <para> + Called from debug_object_assert_init() with a hardcoded state + ODEBUG_STATE_NOTAVAILABLE when the object is not found in the + debug bucket. + </para> + <para> + The function returns true when the fixup was successful, + otherwise false. The return value is used to update the + statistics. + </para> + <para> + Note, this function should make sure debug_object_init() is + called before returning. + </para> + <para> + The handling of statically initialized objects is a special + case. The fixup function should check if this is a legitimate + case of a statically initialized object or not. In this case only + debug_object_init() should be called to make the object known to + the tracker. Then the function should return false because this + is not + a real fixup. + </para> + </sect1> + </chapter> + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + None (knock on wood). + </para> + </chapter> +</book>
diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl new file mode 100644 index 0000000..54199a0 --- /dev/null +++ b/Documentation/DocBook/deviceiobook.tmpl
@@ -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.h +!Elib/pci_iomap.c + </chapter> + +</book>
diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl new file mode 100644 index 0000000..6006b63 --- /dev/null +++ b/Documentation/DocBook/filesystems.tmpl
@@ -0,0 +1,381 @@ +<?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 +!Eblock/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="fs_events"> + <title>Events based on file descriptors</title> +!Efs/eventfd.c + </chapter> + + <chapter id="sysfs"> + <title>The Filesystem for Exporting Kernel Objects</title> +!Efs/sysfs/file.c +!Efs/sysfs/symlink.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 jbd2_journal_init_inode() call +is for journals stored in filesystem inodes, or the jbd2_journal_init_dev() +call can be used 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 jbd2_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. The journalling layer expects the space for the journal was already +allocated and initialized properly by the userspace tools. When loading the +journal you must call jbd2_journal_load() to process journal contents. If the +client file system detects the journal contents does not need to be processed +(or even need not have valid contents), it may call jbd2_journal_wipe() to +clear the journal contents before calling jbd2_journal_load(). +</para> + +<para> +Note that jbd2_journal_wipe(..,0) calls jbd2_journal_skip_recovery() for you if +it detects any outstanding transactions in the journal and similarly +jbd2_journal_load() will call jbd2_journal_recover() if necessary. I would +advise reading ext4_load_journal() in fs/ext4/super.c for examples on this +stage. +</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 jbd2_journal_start() which +returns a transaction handle. +</para> + +<para> +jbd2_journal_start() +and its counterpart jbd2_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 jbd2_journal_stop() the same number of times as +jbd2_journal_start() before the transaction is completed (or more accurately +leaves the update phase). Ext4/VFS makes use of this feature to simplify +handling of inode dirtying, quota support, etc. +</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 jbd2_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 jbd2_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 jbd2_journal_forget() +in much the same way as you might have used bforget() in the past. +</para> + +<para> +A jbd2_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() you can then call jbd2_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 jbd2_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 ext4) may be modified in a later syscall. +</para> + +<para> +The second case to bear in mind is that jbd2_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 jbd2_journal_stop(). So to avoid +deadlocks you must treat jbd2_journal_start/stop() as if they +were semaphores and include them in your semaphore ordering rules to prevent +deadlocks. Note that jbd2_journal_extend() has similar blocking behaviour to +jbd2_journal_start() so you can deadlock here just as easily as on +jbd2_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 ext4_jbd.h to see the basis on which +ext4 uses to make these decisions. +</para> + +<para> +Another wriggle to watch out for is your on-disk block allocation strategy. +Why? Because, if you do a delete, you need to ensure you haven't reused any +of the freed blocks until the transaction freeing these blocks commits. If you +reused these blocks and crash happens, there is no way to restore the contents +of the reallocated blocks at the end of the last fully committed transaction. + +One simple way of doing this is to mark blocks as free in internal in-memory +block allocation structures only after the transaction freeing them commits. +Ext4 uses journal commit callback for this purpose. +</para> + +<para> +With journal commit callbacks you can ask the journalling layer to call a +callback function when the transaction is finally committed to disk, so that +you can do some of your own management. You ask the journalling layer for +calling the callback by simply setting journal->j_commit_callback function +pointer and that function is called after each transaction commit. You can also +use transaction->t_private_list for attaching entries to a transaction that +need processing when the transaction commits. +</para> + +<para> +JBD2 also provides a way to block all transaction updates via +jbd2_journal_{un,}lock_updates(). Ext4 uses this when it wants a window with a +clean and stable fs for a moment. E.g. +</para> + +<programlisting> + + jbd2_journal_lock_updates() //stop new stuff happening.. + jbd2_journal_flush() // checkpoint everything. + ..do stuff on stable fs + jbd2_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> + + </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> + + </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 JBD2 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/jbd2.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/jbd2/journal.c +!Ifs/jbd2/recovery.c + </sect2> + <sect2 id="transaction_level"><title>Transasction Level</title> +!Efs/jbd2/transaction.c + </sect2> + </sect1> + <sect1 id="see_also"> + <title>See also</title> + <para> + <citation> + <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/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>
diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl new file mode 100644 index 0000000..6416292 --- /dev/null +++ b/Documentation/DocBook/gadget.tmpl
@@ -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/function/f_acm.c +!Edrivers/usb/gadget/function/f_ecm.c +!Edrivers/usb/gadget/function/f_subset.c +!Edrivers/usb/gadget/function/f_obex.c +!Edrivers/usb/gadget/function/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>Mass 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 transceiver 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 +-->
diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl new file mode 100644 index 0000000..59fb5c0 --- /dev/null +++ b/Documentation/DocBook/genericirq.tmpl
@@ -0,0 +1,520 @@ +<?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-2010</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 uses + 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> + During the implementation we identified another type: + <itemizedlist> + <listitem><para>Fast EOI 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 high-level IRQ handlers allows us to + optimize the flow of the interrupt handling for each specific + interrupt type. This reduces complexity in that particular code path + 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 low-level hardware logic, and it also leads + to unnecessary code duplication: for example in i386, there is an + ioapic_level_irq and an ioapic_edge_irq IRQ-type which share many + of the low-level 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 high-level flow + handler, which is normally one of the generic + implementations. (This high-level 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. + It's deprecated for three years now and about to be removed. + </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>High-level driver API</para></listitem> + <listitem><para>High-level IRQ flow handlers</para></listitem> + <listitem><para>Chip-level 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 description 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 low-level architecture code calls + into the generic interrupt code by calling desc->handle_irq(). + This high-level IRQ handling function only uses desc->irq_data.chip + primitives referenced by the assigned chip descriptor structure. + </para> + </sect1> + <sect1 id="Highlevel_Driver_API"> + <title>High-level Driver API</title> + <para> + The high-level 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>irq_set_irq_type()</para></listitem> + <listitem><para>irq_set_irq_wake()</para></listitem> + <listitem><para>irq_set_handler_data()</para></listitem> + <listitem><para>irq_set_chip()</para></listitem> + <listitem><para>irq_set_chip_data()</para></listitem> + </itemizedlist> + See the autogenerated function documentation for details. + </para> + </sect1> + <sect1 id="Highlevel_IRQ_flow_handlers"> + <title>High-level 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_fasteoi_irq</para></listitem> + <listitem><para>handle_simple_irq</para></listitem> + <listitem><para>handle_percpu_irq</para></listitem> + <listitem><para>handle_edge_eoi_irq</para></listitem> + <listitem><para>handle_bad_irq</para></listitem> + </itemizedlist> + The interrupt flow handlers (either pre-defined 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(struct irq_data *data) +{ + desc->irq_data.chip->irq_unmask(data); +} + +default_disable(struct irq_data *data) +{ + if (!delay_disable(data)) + desc->irq_data.chip->irq_mask(data); +} + +default_ack(struct irq_data *data) +{ + chip->irq_ack(data); +} + +default_mask_ack(struct irq_data *data) +{ + if (chip->irq_mask_ack) { + chip->irq_mask_ack(data); + } else { + chip->irq_mask(data); + chip->irq_ack(data); + } +} + +noop(struct irq_data *data)) +{ +} + + </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->irq_data.chip->irq_mask_ack(); +handle_irq_event(desc->action); +desc->irq_data.chip->irq_unmask(); + </programlisting> + </para> + </sect3> + <sect3 id="Default_FASTEOI_IRQ_flow_handler"> + <title>Default Fast EOI IRQ flow handler</title> + <para> + handle_fasteoi_irq provides a generic implementation + for interrupts, which only need an EOI at the end of + the handler. + </para> + <para> + The following control flow is implemented (simplified excerpt): + <programlisting> +handle_irq_event(desc->action); +desc->irq_data.chip->irq_eoi(); + </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->irq_data.chip->irq_mask_ack(); + desc->status |= pending | masked; + return; +} +desc->irq_data.chip->irq_ack(); +desc->status |= running; +do { + if (desc->status & masked) + desc->irq_data.chip->irq_unmask(); + desc->status &= ~pending; + handle_irq_event(desc->action); +} while (status & pending); +desc->status &= ~running; + </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> +if (desc->irq_data.chip->irq_ack) + desc->irq_data.chip->irq_ack(); +handle_irq_event(desc->action); +if (desc->irq_data.chip->irq_eoi) + desc->irq_data.chip->irq_eoi(); + </programlisting> + </para> + </sect3> + <sect3 id="EOI_Edge_IRQ_flow_handler"> + <title>EOI Edge IRQ flow handler</title> + <para> + handle_edge_eoi_irq provides an abnomination of the edge + handler which is solely used to tame a badly wreckaged + irq controller on powerpc/cell. + </para> + </sect3> + <sect3 id="BAD_IRQ_flow_handler"> + <title>Bad IRQ flow handler</title> + <para> + handle_bad_irq is used for spurious interrupts which + have no real handler assigned.. + </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 high-level 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 is not configurable. + </para> + </sect2> + </sect1> + <sect1 id="Chiplevel_hardware_encapsulation"> + <title>Chip-level 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>irq_ack()</para></listitem> + <listitem><para>irq_mask_ack() - Optional, recommended for performance</para></listitem> + <listitem><para>irq_mask()</para></listitem> + <listitem><para>irq_unmask()</para></listitem> + <listitem><para>irq_eoi() - Optional, required for EOI flow handlers</para></listitem> + <listitem><para>irq_retrigger() - Optional</para></listitem> + <listitem><para>irq_set_type() - Optional</para></listitem> + <listitem><para>irq_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 low-level functionality. + </para> + </sect1> + </chapter> + + <chapter id="doirq"> + <title>__do_IRQ entry point</title> + <para> + The original implementation __do_IRQ() was an alternative entry + point for all types of interrupts. It no longer exists. + </para> + <para> + This handler turned out to be not suitable for all + interrupt hardware and was therefore reimplemented with split + functionality for edge/level/simple/percpu interrupts. This is not + only a functional optimization. It also shortens code paths for + interrupts. + </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. The per-irq structure is + protected via desc->lock, by the generic layer. + </para> + </chapter> + + <chapter id="genericchip"> + <title>Generic interrupt chip</title> + <para> + To avoid copies of identical implementations of IRQ chips the + core provides a configurable generic interrupt chip + implementation. Developers should check carefully whether the + generic chip fits their needs before implementing the same + functionality slightly differently themselves. + </para> +!Ekernel/irq/generic-chip.c + </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/irqdesc.c +!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>
diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl new file mode 100644 index 0000000..e2ab6a1 --- /dev/null +++ b/Documentation/DocBook/iio.tmpl
@@ -0,0 +1,697 @@ +<?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="iioid"> + <bookinfo> + <title>Industrial I/O driver developer's guide </title> + + <authorgroup> + <author> + <firstname>Daniel</firstname> + <surname>Baluta</surname> + <affiliation> + <address> + <email>daniel.baluta@intel.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2015</year> + <holder>Intel Corporation</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. + </para> + </legalnotice> + </bookinfo> + + <toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + The main purpose of the Industrial I/O subsystem (IIO) is to provide + support for devices that in some sense perform either analog-to-digital + conversion (ADC) or digital-to-analog conversion (DAC) or both. The aim + is to fill the gap between the somewhat similar hwmon and input + subsystems. + Hwmon is directed at low sample rate sensors used to monitor and + control the system itself, like fan speed control or temperature + measurement. Input is, as its name suggests, focused on human interaction + input devices (keyboard, mouse, touchscreen). In some cases there is + considerable overlap between these and IIO. + </para> + <para> + Devices that fall into this category include: + <itemizedlist> + <listitem> + analog to digital converters (ADCs) + </listitem> + <listitem> + accelerometers + </listitem> + <listitem> + capacitance to digital converters (CDCs) + </listitem> + <listitem> + digital to analog converters (DACs) + </listitem> + <listitem> + gyroscopes + </listitem> + <listitem> + inertial measurement units (IMUs) + </listitem> + <listitem> + color and light sensors + </listitem> + <listitem> + magnetometers + </listitem> + <listitem> + pressure sensors + </listitem> + <listitem> + proximity sensors + </listitem> + <listitem> + temperature sensors + </listitem> + </itemizedlist> + Usually these sensors are connected via SPI or I2C. A common use case of the + sensors devices is to have combined functionality (e.g. light plus proximity + sensor). + </para> + </chapter> + <chapter id='iiosubsys'> + <title>Industrial I/O core</title> + <para> + The Industrial I/O core offers: + <itemizedlist> + <listitem> + a unified framework for writing drivers for many different types of + embedded sensors. + </listitem> + <listitem> + a standard interface to user space applications manipulating sensors. + </listitem> + </itemizedlist> + The implementation can be found under <filename> + drivers/iio/industrialio-*</filename> + </para> + <sect1 id="iiodevice"> + <title> Industrial I/O devices </title> + +!Finclude/linux/iio/iio.h iio_dev +!Fdrivers/iio/industrialio-core.c iio_device_alloc +!Fdrivers/iio/industrialio-core.c iio_device_free +!Fdrivers/iio/industrialio-core.c iio_device_register +!Fdrivers/iio/industrialio-core.c iio_device_unregister + + <para> + An IIO device usually corresponds to a single hardware sensor and it + provides all the information needed by a driver handling a device. + Let's first have a look at the functionality embedded in an IIO + device then we will show how a device driver makes use of an IIO + device. + </para> + <para> + There are two ways for a user space application to interact + with an IIO driver. + <itemizedlist> + <listitem> + <filename>/sys/bus/iio/iio:deviceX/</filename>, this + represents a hardware sensor and groups together the data + channels of the same chip. + </listitem> + <listitem> + <filename>/dev/iio:deviceX</filename>, character device node + interface used for buffered data transfer and for events information + retrieval. + </listitem> + </itemizedlist> + </para> + A typical IIO driver will register itself as an I2C or SPI driver and will + create two routines, <function> probe </function> and <function> remove + </function>. At <function>probe</function>: + <itemizedlist> + <listitem>call <function>iio_device_alloc</function>, which allocates memory + for an IIO device. + </listitem> + <listitem> initialize IIO device fields with driver specific information + (e.g. device name, device channels). + </listitem> + <listitem>call <function> iio_device_register</function>, this registers the + device with the IIO core. After this call the device is ready to accept + requests from user space applications. + </listitem> + </itemizedlist> + At <function>remove</function>, we free the resources allocated in + <function>probe</function> in reverse order: + <itemizedlist> + <listitem><function>iio_device_unregister</function>, unregister the device + from the IIO core. + </listitem> + <listitem><function>iio_device_free</function>, free the memory allocated + for the IIO device. + </listitem> + </itemizedlist> + + <sect2 id="iioattr"> <title> IIO device sysfs interface </title> + <para> + Attributes are sysfs files used to expose chip info and also allowing + applications to set various configuration parameters. For device + with index X, attributes can be found under + <filename>/sys/bus/iio/iio:deviceX/ </filename> directory. + Common attributes are: + <itemizedlist> + <listitem><filename>name</filename>, description of the physical + chip. + </listitem> + <listitem><filename>dev</filename>, shows the major:minor pair + associated with <filename>/dev/iio:deviceX</filename> node. + </listitem> + <listitem><filename>sampling_frequency_available</filename>, + available discrete set of sampling frequency values for + device. + </listitem> + </itemizedlist> + Available standard attributes for IIO devices are described in the + <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file + in the Linux kernel sources. + </para> + </sect2> + <sect2 id="iiochannel"> <title> IIO device channels </title> +!Finclude/linux/iio/iio.h iio_chan_spec structure. + <para> + An IIO device channel is a representation of a data channel. An + IIO device can have one or multiple channels. For example: + <itemizedlist> + <listitem> + a thermometer sensor has one channel representing the + temperature measurement. + </listitem> + <listitem> + a light sensor with two channels indicating the measurements in + the visible and infrared spectrum. + </listitem> + <listitem> + an accelerometer can have up to 3 channels representing + acceleration on X, Y and Z axes. + </listitem> + </itemizedlist> + An IIO channel is described by the <type> struct iio_chan_spec + </type>. A thermometer driver for the temperature sensor in the + example above would have to describe its channel as follows: + <programlisting> + static const struct iio_chan_spec temp_channel[] = { + { + .type = IIO_TEMP, + .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), + }, + }; + + </programlisting> + Channel sysfs attributes exposed to userspace are specified in + the form of <emphasis>bitmasks</emphasis>. Depending on their + shared info, attributes can be set in one of the following masks: + <itemizedlist> + <listitem><emphasis>info_mask_separate</emphasis>, attributes will + be specific to this channel</listitem> + <listitem><emphasis>info_mask_shared_by_type</emphasis>, + attributes are shared by all channels of the same type</listitem> + <listitem><emphasis>info_mask_shared_by_dir</emphasis>, attributes + are shared by all channels of the same direction </listitem> + <listitem><emphasis>info_mask_shared_by_all</emphasis>, + attributes are shared by all channels</listitem> + </itemizedlist> + When there are multiple data channels per channel type we have two + ways to distinguish between them: + <itemizedlist> + <listitem> set <emphasis> .modified</emphasis> field of <type> + iio_chan_spec</type> to 1. Modifiers are specified using + <emphasis>.channel2</emphasis> field of the same + <type>iio_chan_spec</type> structure and are used to indicate a + physically unique characteristic of the channel such as its direction + or spectral response. For example, a light sensor can have two channels, + one for infrared light and one for both infrared and visible light. + </listitem> + <listitem> set <emphasis>.indexed </emphasis> field of + <type>iio_chan_spec</type> to 1. In this case the channel is + simply another instance with an index specified by the + <emphasis>.channel</emphasis> field. + </listitem> + </itemizedlist> + Here is how we can make use of the channel's modifiers: + <programlisting> + static const struct iio_chan_spec light_channels[] = { + { + .type = IIO_INTENSITY, + .modified = 1, + .channel2 = IIO_MOD_LIGHT_IR, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + { + .type = IIO_INTENSITY, + .modified = 1, + .channel2 = IIO_MOD_LIGHT_BOTH, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + { + .type = IIO_LIGHT, + .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + + } + </programlisting> + This channel's definition will generate two separate sysfs files + for raw data retrieval: + <itemizedlist> + <listitem> + <filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename> + </listitem> + <listitem> + <filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename> + </listitem> + </itemizedlist> + one file for processed data: + <itemizedlist> + <listitem> + <filename>/sys/bus/iio/iio:deviceX/in_illuminance_input + </filename> + </listitem> + </itemizedlist> + and one shared sysfs file for sampling frequency: + <itemizedlist> + <listitem> + <filename>/sys/bus/iio/iio:deviceX/sampling_frequency. + </filename> + </listitem> + </itemizedlist> + </para> + <para> + Here is how we can make use of the channel's indexing: + <programlisting> + static const struct iio_chan_spec light_channels[] = { + { + .type = IIO_VOLTAGE, + .indexed = 1, + .channel = 0, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + }, + { + .type = IIO_VOLTAGE, + .indexed = 1, + .channel = 1, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + }, + } + </programlisting> + This will generate two separate attributes files for raw data + retrieval: + <itemizedlist> + <listitem> + <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage0_raw</filename>, + representing voltage measurement for channel 0. + </listitem> + <listitem> + <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage1_raw</filename>, + representing voltage measurement for channel 1. + </listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + + <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title> +!Finclude/linux/iio/buffer.h iio_buffer +!Edrivers/iio/industrialio-buffer.c + + <para> + The Industrial I/O core offers a way for continuous data capture + based on a trigger source. Multiple data channels can be read at once + from <filename>/dev/iio:deviceX</filename> character device node, + thus reducing the CPU load. + </para> + + <sect2 id="iiobuffersysfs"> + <title>IIO buffer sysfs interface </title> + <para> + An IIO buffer has an associated attributes directory under <filename> + /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the existing + attributes: + <itemizedlist> + <listitem> + <emphasis>length</emphasis>, the total number of data samples + (capacity) that can be stored by the buffer. + </listitem> + <listitem> + <emphasis>enable</emphasis>, activate buffer capture. + </listitem> + </itemizedlist> + + </para> + </sect2> + <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title> + <para>The meta information associated with a channel reading + placed in a buffer is called a <emphasis> scan element </emphasis>. + The important bits configuring scan elements are exposed to + userspace applications via the <filename> + /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This + file contains attributes of the following form: + <itemizedlist> + <listitem><emphasis>enable</emphasis>, used for enabling a channel. + If and only if its attribute is non zero, then a triggered capture + will contain data samples for this channel. + </listitem> + <listitem><emphasis>type</emphasis>, description of the scan element + data storage within the buffer and hence the form in which it is + read from user space. Format is <emphasis> + [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </emphasis>. + <itemizedlist> + <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis>, specifies + big or little endian. + </listitem> + <listitem> + <emphasis>s </emphasis>or <emphasis>u</emphasis>, specifies if + signed (2's complement) or unsigned. + </listitem> + <listitem><emphasis>bits</emphasis>, is the number of valid data + bits. + </listitem> + <listitem><emphasis>storagebits</emphasis>, is the number of bits + (after padding) that it occupies in the buffer. + </listitem> + <listitem> + <emphasis>shift</emphasis>, if specified, is the shift that needs + to be applied prior to masking out unused bits. + </listitem> + <listitem> + <emphasis>repeat</emphasis>, specifies the number of bits/storagebits + repetitions. When the repeat element is 0 or 1, then the repeat + value is omitted. + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + For example, a driver for a 3-axis accelerometer with 12 bit + resolution where data is stored in two 8-bits registers as + follows: + <programlisting> + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) + +---+---+---+---+---+---+---+---+ + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) + +---+---+---+---+---+---+---+---+ + </programlisting> + + will have the following scan element type for each axis: + <programlisting> + $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type + le:s12/16>>4 + </programlisting> + A user space application will interpret data samples read from the + buffer as two byte little endian signed data, that needs a 4 bits + right shift before masking out the 12 valid bits of data. + </para> + <para> + For implementing buffer support a driver should initialize the following + fields in <type>iio_chan_spec</type> definition: + <programlisting> + struct iio_chan_spec { + /* other members */ + int scan_index + struct { + char sign; + u8 realbits; + u8 storagebits; + u8 shift; + u8 repeat; + enum iio_endian endianness; + } scan_type; + }; + </programlisting> + The driver implementing the accelerometer described above will + have the following channel definition: + <programlisting> + struct struct iio_chan_spec accel_channels[] = { + { + .type = IIO_ACCEL, + .modified = 1, + .channel2 = IIO_MOD_X, + /* other stuff here */ + .scan_index = 0, + .scan_type = { + .sign = 's', + .realbits = 12, + .storagebits = 16, + .shift = 4, + .endianness = IIO_LE, + }, + } + /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) + * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis + */ + } + </programlisting> + </para> + <para> + Here <emphasis> scan_index </emphasis> defines the order in which + the enabled channels are placed inside the buffer. Channels with a lower + scan_index will be placed before channels with a higher index. Each + channel needs to have a unique scan_index. + </para> + <para> + Setting scan_index to -1 can be used to indicate that the specific + channel does not support buffered capture. In this case no entries will + be created for the channel in the scan_elements directory. + </para> + </sect2> + </sect1> + + <sect1 id="iiotrigger"> <title> Industrial I/O triggers </title> +!Finclude/linux/iio/trigger.h iio_trigger +!Edrivers/iio/industrialio-trigger.c + <para> + In many situations it is useful for a driver to be able to + capture data based on some external event (trigger) as opposed + to periodically polling for data. An IIO trigger can be provided + by a device driver that also has an IIO device based on hardware + generated events (e.g. data ready or threshold exceeded) or + provided by a separate driver from an independent interrupt + source (e.g. GPIO line connected to some external system, timer + interrupt or user space writing a specific file in sysfs). A + trigger may initiate data capture for a number of sensors and + also it may be completely unrelated to the sensor itself. + </para> + + <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface </title> + There are two locations in sysfs related to triggers: + <itemizedlist> + <listitem><filename>/sys/bus/iio/devices/triggerY</filename>, + this file is created once an IIO trigger is registered with + the IIO core and corresponds to trigger with index Y. Because + triggers can be very different depending on type there are few + standard attributes that we can describe here: + <itemizedlist> + <listitem> + <emphasis>name</emphasis>, trigger name that can be later + used for association with a device. + </listitem> + <listitem> + <emphasis>sampling_frequency</emphasis>, some timer based + triggers use this attribute to specify the frequency for + trigger calls. + </listitem> + </itemizedlist> + </listitem> + <listitem> + <filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this + directory is created once the device supports a triggered + buffer. We can associate a trigger with our device by writing + the trigger's name in the <filename>current_trigger</filename> file. + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="iiotrigattr"> <title> IIO trigger setup</title> + + <para> + Let's see a simple example of how to setup a trigger to be used + by a driver. + + <programlisting> + struct iio_trigger_ops trigger_ops = { + .set_trigger_state = sample_trigger_state, + .validate_device = sample_validate_device, + } + + struct iio_trigger *trig; + + /* first, allocate memory for our trigger */ + trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx); + + /* setup trigger operations field */ + trig->ops = &trigger_ops; + + /* now register the trigger with the IIO core */ + iio_trigger_register(trig); + </programlisting> + </para> + </sect2> + + <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title> +!Finclude/linux/iio/trigger.h iio_trigger_ops + <para> + Notice that a trigger has a set of operations attached: + <itemizedlist> + <listitem> + <function>set_trigger_state</function>, switch the trigger on/off + on demand. + </listitem> + <listitem> + <function>validate_device</function>, function to validate the + device when the current trigger gets changed. + </listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + <sect1 id="iiotriggered_buffer"> + <title> Industrial I/O triggered buffers </title> + <para> + Now that we know what buffers and triggers are let's see how they + work together. + </para> + <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title> +!Edrivers/iio/buffer/industrialio-triggered-buffer.c +!Finclude/linux/iio/iio.h iio_buffer_setup_ops + + + <para> + A typical triggered buffer setup looks like this: + <programlisting> + const struct iio_buffer_setup_ops sensor_buffer_setup_ops = { + .preenable = sensor_buffer_preenable, + .postenable = sensor_buffer_postenable, + .postdisable = sensor_buffer_postdisable, + .predisable = sensor_buffer_predisable, + }; + + irqreturn_t sensor_iio_pollfunc(int irq, void *p) + { + pf->timestamp = iio_get_time_ns((struct indio_dev *)p); + return IRQ_WAKE_THREAD; + } + + irqreturn_t sensor_trigger_handler(int irq, void *p) + { + u16 buf[8]; + int i = 0; + + /* read data for each active channel */ + for_each_set_bit(bit, active_scan_mask, masklength) + buf[i++] = sensor_get_data(bit) + + iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp); + + iio_trigger_notify_done(trigger); + return IRQ_HANDLED; + } + + /* setup triggered buffer, usually in probe function */ + iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc, + sensor_trigger_handler, + sensor_buffer_setup_ops); + </programlisting> + </para> + The important things to notice here are: + <itemizedlist> + <listitem><function> iio_buffer_setup_ops</function>, the buffer setup + functions to be called at predefined points in the buffer configuration + sequence (e.g. before enable, after disable). If not specified, the + IIO core uses the default <type>iio_triggered_buffer_setup_ops</type>. + </listitem> + <listitem><function>sensor_iio_pollfunc</function>, the function that + will be used as top half of poll function. It should do as little + processing as possible, because it runs in interrupt context. The most + common operation is recording of the current timestamp and for this reason + one can use the IIO core defined <function>iio_pollfunc_store_time + </function> function. + </listitem> + <listitem><function>sensor_trigger_handler</function>, the function that + will be used as bottom half of the poll function. This runs in the + context of a kernel thread and all the processing takes place here. + It usually reads data from the device and stores it in the internal + buffer together with the timestamp recorded in the top half. + </listitem> + </itemizedlist> + </sect2> + </sect1> + </chapter> + <chapter id='iioresources'> + <title> Resources </title> + IIO core may change during time so the best documentation to read is the + source code. There are several locations where you should look: + <itemizedlist> + <listitem> + <filename>drivers/iio/</filename>, contains the IIO core plus + and directories for each sensor type (e.g. accel, magnetometer, + etc.) + </listitem> + <listitem> + <filename>include/linux/iio/</filename>, contains the header + files, nice to read for the internal kernel interfaces. + </listitem> + <listitem> + <filename>include/uapi/linux/iio/</filename>, contains files to be + used by user space applications. + </listitem> + <listitem> + <filename>tools/iio/</filename>, contains tools for rapidly + testing buffers, events and device creation. + </listitem> + <listitem> + <filename>drivers/staging/iio/</filename>, contains code for some + drivers or experimental features that are not yet mature enough + to be moved out. + </listitem> + </itemizedlist> + <para> + Besides the code, there are some good online documentation sources: + <itemizedlist> + <listitem> + <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O mailing + list </ulink> + </listitem> + <listitem> + <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio"> + Analog Device IIO wiki page </ulink> + </listitem> + <listitem> + <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/"> + Using the Linux IIO framework for SDR, Lars-Peter Clausen's + presentation at FOSDEM </ulink> + </listitem> + </itemizedlist> + </para> + </chapter> +</book> + +<!-- +vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 +-->
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl new file mode 100644 index 0000000..ecfd0ea --- /dev/null +++ b/Documentation/DocBook/kernel-api.tmpl
@@ -0,0 +1,331 @@ +<?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> +!Elib/vsprintf.c +!Finclude/linux/kernel.h kstrtol +!Finclude/linux/kernel.h kstrtoul +!Elib/kstrtox.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> + + <sect1 id="idr"><title>idr/ida Functions</title> +!Pinclude/linux/idr.h idr sync +!Plib/idr.c IDA description +!Elib/idr.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 +!Emm/util.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 + </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> + </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-flush.c +!Eblock/blk-lib.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>
diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl new file mode 100644 index 0000000..2a27227 --- /dev/null +++ b/Documentation/DocBook/kernel-hacking.tmpl
@@ -0,0 +1,1312 @@ +<?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="lk-hacking-guide"> + <bookinfo> + <title>Unreliable Guide To Hacking The Linux Kernel</title> + + <authorgroup> + <author> + <firstname>Rusty</firstname> + <surname>Russell</surname> + <affiliation> + <address> + <email>rusty@rustcorp.com.au</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2005</year> + <holder>Rusty Russell</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> + + <releaseinfo> + This is the first release of this document as part of the kernel tarball. + </releaseinfo> + + </bookinfo> + + <toc></toc> + + <chapter id="introduction"> + <title>Introduction</title> + <para> + Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux + Kernel Hacking. This document describes the common routines and + general requirements for kernel code: its goal is to serve as a + primer for Linux kernel development for experienced C + programmers. I avoid implementation details: that's what the + code is for, and I ignore whole tracts of useful routines. + </para> + <para> + Before you read this, please understand that I never wanted to + write this document, being grossly under-qualified, but I always + wanted to read it, and this was the only way. I hope it will + grow into a compendium of best practice, common starting points + and random information. + </para> + </chapter> + + <chapter id="basic-players"> + <title>The Players</title> + + <para> + At any time each of the CPUs in a system can be: + </para> + + <itemizedlist> + <listitem> + <para> + not associated with any process, serving a hardware interrupt; + </para> + </listitem> + + <listitem> + <para> + not associated with any process, serving a softirq or tasklet; + </para> + </listitem> + + <listitem> + <para> + running in kernel space, associated with a process (user context); + </para> + </listitem> + + <listitem> + <para> + running a process in user space. + </para> + </listitem> + </itemizedlist> + + <para> + There is an ordering between these. The bottom two can preempt + each other, but above that is a strict hierarchy: each can only be + preempted by the ones above it. For example, while a softirq is + running on a CPU, no other softirq will preempt it, but a hardware + interrupt can. However, any other CPUs in the system execute + independently. + </para> + + <para> + We'll see a number of ways that the user context can block + interrupts, to become truly non-preemptable. + </para> + + <sect1 id="basics-usercontext"> + <title>User Context</title> + + <para> + User context is when you are coming in from a system call or other + trap: like userspace, you can be preempted by more important tasks + and by interrupts. You can sleep, by calling + <function>schedule()</function>. + </para> + + <note> + <para> + You are always in user context on module load and unload, + and on operations on the block device layer. + </para> + </note> + + <para> + In user context, the <varname>current</varname> pointer (indicating + the task we are currently executing) is valid, and + <function>in_interrupt()</function> + (<filename>include/linux/interrupt.h</filename>) is <returnvalue>false + </returnvalue>. + </para> + + <caution> + <para> + Beware that if you have preemption or softirqs disabled + (see below), <function>in_interrupt()</function> will return a + false positive. + </para> + </caution> + </sect1> + + <sect1 id="basics-hardirqs"> + <title>Hardware Interrupts (Hard IRQs)</title> + + <para> + Timer ticks, <hardware>network cards</hardware> and + <hardware>keyboard</hardware> are examples of real + hardware which produce interrupts at any time. The kernel runs + interrupt handlers, which services the hardware. The kernel + guarantees that this handler is never re-entered: if the same + interrupt arrives, it is queued (or dropped). Because it + disables interrupts, this handler has to be fast: frequently it + simply acknowledges the interrupt, marks a 'software interrupt' + for execution and exits. + </para> + + <para> + You can tell you are in a hardware interrupt, because + <function>in_irq()</function> returns <returnvalue>true</returnvalue>. + </para> + <caution> + <para> + Beware that this will return a false positive if interrupts are disabled + (see below). + </para> + </caution> + </sect1> + + <sect1 id="basics-softirqs"> + <title>Software Interrupt Context: Softirqs and Tasklets</title> + + <para> + Whenever a system call is about to return to userspace, or a + hardware interrupt handler exits, any 'software interrupts' + which are marked pending (usually by hardware interrupts) are + run (<filename>kernel/softirq.c</filename>). + </para> + + <para> + Much of the real interrupt handling work is done here. Early in + the transition to <acronym>SMP</acronym>, there were only 'bottom + halves' (BHs), which didn't take advantage of multiple CPUs. Shortly + after we switched from wind-up computers made of match-sticks and snot, + we abandoned this limitation and switched to 'softirqs'. + </para> + + <para> + <filename class="headerfile">include/linux/interrupt.h</filename> lists the + different softirqs. A very important softirq is the + timer softirq (<filename + class="headerfile">include/linux/timer.h</filename>): you can + register to have it call functions for you in a given length of + time. + </para> + + <para> + Softirqs are often a pain to deal with, since the same softirq + will run simultaneously on more than one CPU. For this reason, + tasklets (<filename + class="headerfile">include/linux/interrupt.h</filename>) are more + often used: they are dynamically-registrable (meaning you can have + as many as you want), and they also guarantee that any tasklet + will only run on one CPU at any time, although different tasklets + can run simultaneously. + </para> + <caution> + <para> + The name 'tasklet' is misleading: they have nothing to do with 'tasks', + and probably more to do with some bad vodka Alexey Kuznetsov had at the + time. + </para> + </caution> + + <para> + You can tell you are in a softirq (or tasklet) + using the <function>in_softirq()</function> macro + (<filename class="headerfile">include/linux/interrupt.h</filename>). + </para> + <caution> + <para> + Beware that this will return a false positive if a bh lock (see below) + is held. + </para> + </caution> + </sect1> + </chapter> + + <chapter id="basic-rules"> + <title>Some Basic Rules</title> + + <variablelist> + <varlistentry> + <term>No memory protection</term> + <listitem> + <para> + If you corrupt memory, whether in user context or + interrupt context, the whole machine will crash. Are you + sure you can't do what you want in userspace? + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>No floating point or <acronym>MMX</acronym></term> + <listitem> + <para> + The <acronym>FPU</acronym> context is not saved; even in user + context the <acronym>FPU</acronym> state probably won't + correspond with the current process: you would mess with some + user process' <acronym>FPU</acronym> state. If you really want + to do this, you would have to explicitly save/restore the full + <acronym>FPU</acronym> state (and avoid context switches). It + is generally a bad idea; use fixed point arithmetic first. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>A rigid stack limit</term> + <listitem> + <para> + Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's + about 14K on most 64-bit archs, and often shared with interrupts + so you can't use it all. Avoid deep recursion and huge local + arrays on the stack (allocate them dynamically instead). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>The Linux kernel is portable</term> + <listitem> + <para> + Let's keep it that way. Your code should be 64-bit clean, + and endian-independent. You should also minimize CPU + specific stuff, e.g. inline assembly should be cleanly + encapsulated and minimized to ease porting. Generally it + should be restricted to the architecture-dependent part of + the kernel tree. + </para> + </listitem> + </varlistentry> + </variablelist> + </chapter> + + <chapter id="ioctls"> + <title>ioctls: Not writing a new system call</title> + + <para> + A system call generally looks like this + </para> + + <programlisting> +asmlinkage long sys_mycall(int arg) +{ + return 0; +} + </programlisting> + + <para> + First, in most cases you don't want to create a new system call. + You create a character device and implement an appropriate ioctl + for it. This is much more flexible than system calls, doesn't have + to be entered in every architecture's + <filename class="headerfile">include/asm/unistd.h</filename> and + <filename>arch/kernel/entry.S</filename> file, and is much more + likely to be accepted by Linus. + </para> + + <para> + If all your routine does is read or write some parameter, consider + implementing a <function>sysfs</function> interface instead. + </para> + + <para> + Inside the ioctl you're in user context to a process. When a + error occurs you return a negated errno (see + <filename class="headerfile">include/linux/errno.h</filename>), + otherwise you return <returnvalue>0</returnvalue>. + </para> + + <para> + After you slept you should check if a signal occurred: the + Unix/Linux way of handling signals is to temporarily exit the + system call with the <constant>-ERESTARTSYS</constant> error. The + system call entry code will switch back to user context, process + the signal handler and then your system call will be restarted + (unless the user disabled that). So you should be prepared to + process the restart, e.g. if you're in the middle of manipulating + some data structure. + </para> + + <programlisting> +if (signal_pending(current)) + return -ERESTARTSYS; + </programlisting> + + <para> + If you're doing longer computations: first think userspace. If you + <emphasis>really</emphasis> want to do it in kernel you should + regularly check if you need to give up the CPU (remember there is + cooperative multitasking per CPU). Idiom: + </para> + + <programlisting> +cond_resched(); /* Will sleep */ + </programlisting> + + <para> + A short note on interface design: the UNIX system call motto is + "Provide mechanism not policy". + </para> + </chapter> + + <chapter id="deadlock-recipes"> + <title>Recipes for Deadlock</title> + + <para> + You cannot call any routines which may sleep, unless: + </para> + <itemizedlist> + <listitem> + <para> + You are in user context. + </para> + </listitem> + + <listitem> + <para> + You do not own any spinlocks. + </para> + </listitem> + + <listitem> + <para> + You have interrupts enabled (actually, Andi Kleen says + that the scheduling code will enable them for you, but + that's probably not what you wanted). + </para> + </listitem> + </itemizedlist> + + <para> + Note that some functions may sleep implicitly: common ones are + the user space access functions (*_user) and memory allocation + functions without <symbol>GFP_ATOMIC</symbol>. + </para> + + <para> + You should always compile your kernel + <symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn + you if you break these rules. If you <emphasis>do</emphasis> break + the rules, you will eventually lock up your box. + </para> + + <para> + Really. + </para> + </chapter> + + <chapter id="common-routines"> + <title>Common Routines</title> + + <sect1 id="routines-printk"> + <title> + <function>printk()</function> + <filename class="headerfile">include/linux/kernel.h</filename> + </title> + + <para> + <function>printk()</function> feeds kernel messages to the + console, dmesg, and the syslog daemon. It is useful for debugging + and reporting errors, and can be used inside interrupt context, + but use with caution: a machine which has its console flooded with + printk messages is unusable. It uses a format string mostly + compatible with ANSI C printf, and C string concatenation to give + it a first "priority" argument: + </para> + + <programlisting> +printk(KERN_INFO "i = %u\n", i); + </programlisting> + + <para> + See <filename class="headerfile">include/linux/kernel.h</filename>; + for other KERN_ values; these are interpreted by syslog as the + level. Special case: for printing an IP address use + </para> + + <programlisting> +__be32 ipaddress; +printk(KERN_INFO "my ip: %pI4\n", &ipaddress); + </programlisting> + + <para> + <function>printk()</function> internally uses a 1K buffer and does + not catch overruns. Make sure that will be enough. + </para> + + <note> + <para> + You will know when you are a real kernel hacker + when you start typoing printf as printk in your user programs :) + </para> + </note> + + <!--- From the Lions book reader department --> + + <note> + <para> + Another sidenote: the original Unix Version 6 sources had a + comment on top of its printf function: "Printf should not be + used for chit-chat". You should follow that advice. + </para> + </note> + </sect1> + + <sect1 id="routines-copy"> + <title> + <function>copy_[to/from]_user()</function> + / + <function>get_user()</function> + / + <function>put_user()</function> + <filename class="headerfile">include/linux/uaccess.h</filename> + </title> + + <para> + <emphasis>[SLEEPS]</emphasis> + </para> + + <para> + <function>put_user()</function> and <function>get_user()</function> + are used to get and put single values (such as an int, char, or + long) from and to userspace. A pointer into userspace should + never be simply dereferenced: data should be copied using these + routines. Both return <constant>-EFAULT</constant> or 0. + </para> + <para> + <function>copy_to_user()</function> and + <function>copy_from_user()</function> are more general: they copy + an arbitrary amount of data to and from userspace. + <caution> + <para> + Unlike <function>put_user()</function> and + <function>get_user()</function>, they return the amount of + uncopied data (ie. <returnvalue>0</returnvalue> still means + success). + </para> + </caution> + [Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.] + </para> + <para> + The functions may sleep implicitly. This should never be called + outside user context (it makes no sense), with interrupts + disabled, or a spinlock held. + </para> + </sect1> + + <sect1 id="routines-kmalloc"> + <title><function>kmalloc()</function>/<function>kfree()</function> + <filename class="headerfile">include/linux/slab.h</filename></title> + + <para> + <emphasis>[MAY SLEEP: SEE BELOW]</emphasis> + </para> + + <para> + These routines are used to dynamically request pointer-aligned + chunks of memory, like malloc and free do in userspace, but + <function>kmalloc()</function> takes an extra flag word. + Important values: + </para> + + <variablelist> + <varlistentry> + <term> + <constant> + GFP_KERNEL + </constant> + </term> + <listitem> + <para> + May sleep and swap to free memory. Only allowed in user + context, but is the most reliable way to allocate memory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant> + GFP_ATOMIC + </constant> + </term> + <listitem> + <para> + Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>, + but may be called from interrupt context. You should + <emphasis>really</emphasis> have a good out-of-memory + error-handling strategy. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <constant> + GFP_DMA + </constant> + </term> + <listitem> + <para> + Allocate ISA DMA lower than 16MB. If you don't know what that + is you don't need it. Very unreliable. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + If you see a <errorname>sleeping function called from invalid + context</errorname> warning message, then maybe you called a + sleeping allocation function from interrupt context without + <constant>GFP_ATOMIC</constant>. You should really fix that. + Run, don't walk. + </para> + + <para> + If you are allocating at least <constant>PAGE_SIZE</constant> + (<filename class="headerfile">include/asm/page.h</filename>) bytes, + consider using <function>__get_free_pages()</function> + + (<filename class="headerfile">include/linux/mm.h</filename>). It + takes an order argument (0 for page sized, 1 for double page, 2 + for four pages etc.) and the same memory priority flag word as + above. + </para> + + <para> + If you are allocating more than a page worth of bytes you can use + <function>vmalloc()</function>. It'll allocate virtual memory in + the kernel map. This block is not contiguous in physical memory, + but the <acronym>MMU</acronym> makes it look like it is for you + (so it'll only look contiguous to the CPUs, not to external device + drivers). If you really need large physically contiguous memory + for some weird device, you have a problem: it is poorly supported + in Linux because after some time memory fragmentation in a running + kernel makes it hard. The best way is to allocate the block early + in the boot process via the <function>alloc_bootmem()</function> + routine. + </para> + + <para> + Before inventing your own cache of often-used objects consider + using a slab cache in + <filename class="headerfile">include/linux/slab.h</filename> + </para> + </sect1> + + <sect1 id="routines-current"> + <title><function>current</function> + <filename class="headerfile">include/asm/current.h</filename></title> + + <para> + This global variable (really a macro) contains a pointer to + the current task structure, so is only valid in user context. + For example, when a process makes a system call, this will + point to the task structure of the calling process. It is + <emphasis>not NULL</emphasis> in interrupt context. + </para> + </sect1> + + <sect1 id="routines-udelay"> + <title><function>mdelay()</function>/<function>udelay()</function> + <filename class="headerfile">include/asm/delay.h</filename> + <filename class="headerfile">include/linux/delay.h</filename> + </title> + + <para> + The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses. + Do not use large values with them as you risk + overflow - the helper function <function>mdelay()</function> is useful + here, or consider <function>msleep()</function>. + </para> + </sect1> + + <sect1 id="routines-endian"> + <title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function> + <filename class="headerfile">include/asm/byteorder.h</filename> + </title> + + <para> + The <function>cpu_to_be32()</function> family (where the "32" can + be replaced by 64 or 16, and the "be" can be replaced by "le") are + the general way to do endian conversions in the kernel: they + return the converted value. All variations supply the reverse as + well: <function>be32_to_cpu()</function>, etc. + </para> + + <para> + There are two major variations of these functions: the pointer + variation, such as <function>cpu_to_be32p()</function>, which take + a pointer to the given type, and return the converted value. The + other variation is the "in-situ" family, such as + <function>cpu_to_be32s()</function>, which convert value referred + to by the pointer, and return void. + </para> + </sect1> + + <sect1 id="routines-local-irqs"> + <title><function>local_irq_save()</function>/<function>local_irq_restore()</function> + <filename class="headerfile">include/linux/irqflags.h</filename> + </title> + + <para> + These routines disable hard interrupts on the local CPU, and + restore them. They are reentrant; saving the previous state in + their one <varname>unsigned long flags</varname> argument. If you + know that interrupts are enabled, you can simply use + <function>local_irq_disable()</function> and + <function>local_irq_enable()</function>. + </para> + </sect1> + + <sect1 id="routines-softirqs"> + <title><function>local_bh_disable()</function>/<function>local_bh_enable()</function> + <filename class="headerfile">include/linux/interrupt.h</filename></title> + + <para> + These routines disable soft interrupts on the local CPU, and + restore them. They are reentrant; if soft interrupts were + disabled before, they will still be disabled after this pair + of functions has been called. They prevent softirqs and tasklets + from running on the current CPU. + </para> + </sect1> + + <sect1 id="routines-processorids"> + <title><function>smp_processor_id</function>() + <filename class="headerfile">include/asm/smp.h</filename></title> + + <para> + <function>get_cpu()</function> disables preemption (so you won't + suddenly get moved to another CPU) and returns the current + processor number, between 0 and <symbol>NR_CPUS</symbol>. Note + that the CPU numbers are not necessarily continuous. You return + it again with <function>put_cpu()</function> when you are done. + </para> + <para> + If you know you cannot be preempted by another task (ie. you are + in interrupt context, or have preemption disabled) you can use + smp_processor_id(). + </para> + </sect1> + + <sect1 id="routines-init"> + <title><type>__init</type>/<type>__exit</type>/<type>__initdata</type> + <filename class="headerfile">include/linux/init.h</filename></title> + + <para> + After boot, the kernel frees up a special section; functions + marked with <type>__init</type> and data structures marked with + <type>__initdata</type> are dropped after boot is complete: similarly + modules discard this memory after initialization. <type>__exit</type> + is used to declare a function which is only required on exit: the + function will be dropped if this file is not compiled as a module. + See the header file for use. Note that it makes no sense for a function + marked with <type>__init</type> to be exported to modules with + <function>EXPORT_SYMBOL()</function> - this will break. + </para> + + </sect1> + + <sect1 id="routines-init-again"> + <title><function>__initcall()</function>/<function>module_init()</function> + <filename class="headerfile">include/linux/init.h</filename></title> + <para> + Many parts of the kernel are well served as a module + (dynamically-loadable parts of the kernel). Using the + <function>module_init()</function> and + <function>module_exit()</function> macros it is easy to write code + without #ifdefs which can operate both as a module or built into + the kernel. + </para> + + <para> + The <function>module_init()</function> macro defines which + function is to be called at module insertion time (if the file is + compiled as a module), or at boot time: if the file is not + compiled as a module the <function>module_init()</function> macro + becomes equivalent to <function>__initcall()</function>, which + through linker magic ensures that the function is called on boot. + </para> + + <para> + The function can return a negative error number to cause + module loading to fail (unfortunately, this has no effect if + the module is compiled into the kernel). This function is + called in user context with interrupts enabled, so it can sleep. + </para> + </sect1> + + <sect1 id="routines-moduleexit"> + <title> <function>module_exit()</function> + <filename class="headerfile">include/linux/init.h</filename> </title> + + <para> + This macro defines the function to be called at module removal + time (or never, in the case of the file compiled into the + kernel). It will only be called if the module usage count has + reached zero. This function can also sleep, but cannot fail: + everything must be cleaned up by the time it returns. + </para> + + <para> + Note that this macro is optional: if it is not present, your + module will not be removable (except for 'rmmod -f'). + </para> + </sect1> + + <sect1 id="routines-module-use-counters"> + <title> <function>try_module_get()</function>/<function>module_put()</function> + <filename class="headerfile">include/linux/module.h</filename></title> + + <para> + These manipulate the module usage count, to protect against + removal (a module also can't be removed if another module uses one + of its exported symbols: see below). Before calling into module + code, you should call <function>try_module_get()</function> on + that module: if it fails, then the module is being removed and you + should act as if it wasn't there. Otherwise, you can safely enter + the module, and call <function>module_put()</function> when you're + finished. + </para> + + <para> + Most registerable structures have an + <structfield>owner</structfield> field, such as in the + <structname>file_operations</structname> structure. Set this field + to the macro <symbol>THIS_MODULE</symbol>. + </para> + </sect1> + + <!-- add info on new-style module refcounting here --> + </chapter> + + <chapter id="queues"> + <title>Wait Queues + <filename class="headerfile">include/linux/wait.h</filename> + </title> + <para> + <emphasis>[SLEEPS]</emphasis> + </para> + + <para> + A wait queue is used to wait for someone to wake you up when a + certain condition is true. They must be used carefully to ensure + there is no race condition. You declare a + <type>wait_queue_head_t</type>, and then processes which want to + wait for that condition declare a <type>wait_queue_t</type> + referring to themselves, and place that in the queue. + </para> + + <sect1 id="queue-declaring"> + <title>Declaring</title> + + <para> + You declare a <type>wait_queue_head_t</type> using the + <function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the + <function>init_waitqueue_head()</function> routine in your + initialization code. + </para> + </sect1> + + <sect1 id="queue-waitqueue"> + <title>Queuing</title> + + <para> + Placing yourself in the waitqueue is fairly complex, because you + must put yourself in the queue before checking the condition. + There is a macro to do this: + <function>wait_event_interruptible()</function> + + <filename class="headerfile">include/linux/wait.h</filename> The + first argument is the wait queue head, and the second is an + expression which is evaluated; the macro returns + <returnvalue>0</returnvalue> when this expression is true, or + <returnvalue>-ERESTARTSYS</returnvalue> if a signal is received. + The <function>wait_event()</function> version ignores signals. + </para> + + </sect1> + + <sect1 id="queue-waking"> + <title>Waking Up Queued Tasks</title> + + <para> + Call <function>wake_up()</function> + + <filename class="headerfile">include/linux/wait.h</filename>;, + which will wake up every process in the queue. The exception is + if one has <constant>TASK_EXCLUSIVE</constant> set, in which case + the remainder of the queue will not be woken. There are other variants + of this basic function available in the same header. + </para> + </sect1> + </chapter> + + <chapter id="atomic-ops"> + <title>Atomic Operations</title> + + <para> + Certain operations are guaranteed atomic on all platforms. The + first class of operations work on <type>atomic_t</type> + + <filename class="headerfile">include/asm/atomic.h</filename>; this + contains a signed integer (at least 32 bits long), and you must use + these functions to manipulate or read atomic_t variables. + <function>atomic_read()</function> and + <function>atomic_set()</function> get and set the counter, + <function>atomic_add()</function>, + <function>atomic_sub()</function>, + <function>atomic_inc()</function>, + <function>atomic_dec()</function>, and + <function>atomic_dec_and_test()</function> (returns + <returnvalue>true</returnvalue> if it was decremented to zero). + </para> + + <para> + Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the + atomic variable is zero. + </para> + + <para> + Note that these functions are slower than normal arithmetic, and + so should not be used unnecessarily. + </para> + + <para> + The second class of atomic operations is atomic bit operations on an + <type>unsigned long</type>, defined in + + <filename class="headerfile">include/linux/bitops.h</filename>. These + operations generally take a pointer to the bit pattern, and a bit + number: 0 is the least significant bit. + <function>set_bit()</function>, <function>clear_bit()</function> + and <function>change_bit()</function> set, clear, and flip the + given bit. <function>test_and_set_bit()</function>, + <function>test_and_clear_bit()</function> and + <function>test_and_change_bit()</function> do the same thing, + except return true if the bit was previously set; these are + particularly useful for atomically setting flags. + </para> + + <para> + It is possible to call these operations with bit indices greater + than BITS_PER_LONG. The resulting behavior is strange on big-endian + platforms though so it is a good idea not to do this. + </para> + </chapter> + + <chapter id="symbols"> + <title>Symbols</title> + + <para> + Within the kernel proper, the normal linking rules apply + (ie. unless a symbol is declared to be file scope with the + <type>static</type> keyword, it can be used anywhere in the + kernel). However, for modules, a special exported symbol table is + kept which limits the entry points to the kernel proper. Modules + can also export symbols. + </para> + + <sect1 id="sym-exportsymbols"> + <title><function>EXPORT_SYMBOL()</function> + <filename class="headerfile">include/linux/export.h</filename></title> + + <para> + This is the classic method of exporting a symbol: dynamically + loaded modules will be able to use the symbol as normal. + </para> + </sect1> + + <sect1 id="sym-exportsymbols-gpl"> + <title><function>EXPORT_SYMBOL_GPL()</function> + <filename class="headerfile">include/linux/export.h</filename></title> + + <para> + Similar to <function>EXPORT_SYMBOL()</function> except that the + symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can + only be seen by modules with a + <function>MODULE_LICENSE()</function> that specifies a GPL + compatible license. It implies that the function is considered + an internal implementation issue, and not really an interface. + Some maintainers and developers may however + require EXPORT_SYMBOL_GPL() when adding any new APIs or functionality. + </para> + </sect1> + </chapter> + + <chapter id="conventions"> + <title>Routines and Conventions</title> + + <sect1 id="conventions-doublelinkedlist"> + <title>Double-linked lists + <filename class="headerfile">include/linux/list.h</filename></title> + + <para> + There used to be three sets of linked-list routines in the kernel + headers, but this one is the winner. If you don't have some + particular pressing need for a single list, it's a good choice. + </para> + + <para> + In particular, <function>list_for_each_entry</function> is useful. + </para> + </sect1> + + <sect1 id="convention-returns"> + <title>Return Conventions</title> + + <para> + For code called in user context, it's very common to defy C + convention, and return <returnvalue>0</returnvalue> for success, + and a negative error number + (eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be + unintuitive at first, but it's fairly widespread in the kernel. + </para> + + <para> + Using <function>ERR_PTR()</function> + + <filename class="headerfile">include/linux/err.h</filename>; to + encode a negative error number into a pointer, and + <function>IS_ERR()</function> and <function>PTR_ERR()</function> + to get it back out again: avoids a separate pointer parameter for + the error number. Icky, but in a good way. + </para> + </sect1> + + <sect1 id="conventions-borkedcompile"> + <title>Breaking Compilation</title> + + <para> + Linus and the other developers sometimes change function or + structure names in development kernels; this is not done just to + keep everyone on their toes: it reflects a fundamental change + (eg. can no longer be called with interrupts on, or does extra + checks, or doesn't do checks which were caught before). Usually + this is accompanied by a fairly complete note to the linux-kernel + mailing list; search the archive. Simply doing a global replace + on the file usually makes things <emphasis>worse</emphasis>. + </para> + </sect1> + + <sect1 id="conventions-initialising"> + <title>Initializing structure members</title> + + <para> + The preferred method of initializing structures is to use + designated initialisers, as defined by ISO C99, eg: + </para> + <programlisting> +static struct block_device_operations opt_fops = { + .open = opt_open, + .release = opt_release, + .ioctl = opt_ioctl, + .check_media_change = opt_media_change, +}; + </programlisting> + <para> + This makes it easy to grep for, and makes it clear which + structure fields are set. You should do this because it looks + cool. + </para> + </sect1> + + <sect1 id="conventions-gnu-extns"> + <title>GNU Extensions</title> + + <para> + GNU Extensions are explicitly allowed in the Linux kernel. + Note that some of the more complex ones are not very well + supported, due to lack of general use, but the following are + considered standard (see the GCC info page section "C + Extensions" for more details - Yes, really the info page, the + man page is only a short summary of the stuff in info). + </para> + <itemizedlist> + <listitem> + <para> + Inline functions + </para> + </listitem> + <listitem> + <para> + Statement expressions (ie. the ({ and }) constructs). + </para> + </listitem> + <listitem> + <para> + Declaring attributes of a function / variable / type + (__attribute__) + </para> + </listitem> + <listitem> + <para> + typeof + </para> + </listitem> + <listitem> + <para> + Zero length arrays + </para> + </listitem> + <listitem> + <para> + Macro varargs + </para> + </listitem> + <listitem> + <para> + Arithmetic on void pointers + </para> + </listitem> + <listitem> + <para> + Non-Constant initializers + </para> + </listitem> + <listitem> + <para> + Assembler Instructions (not outside arch/ and include/asm/) + </para> + </listitem> + <listitem> + <para> + Function names as strings (__func__). + </para> + </listitem> + <listitem> + <para> + __builtin_constant_p() + </para> + </listitem> + </itemizedlist> + + <para> + Be wary when using long long in the kernel, the code gcc generates for + it is horrible and worse: division and multiplication does not work + on i386 because the GCC runtime functions for it are missing from + the kernel environment. + </para> + + <!-- FIXME: add a note about ANSI aliasing cleanness --> + </sect1> + + <sect1 id="conventions-cplusplus"> + <title>C++</title> + + <para> + Using C++ in the kernel is usually a bad idea, because the + kernel does not provide the necessary runtime environment + and the include files are not tested for it. It is still + possible, but not recommended. If you really want to do + this, forget about exceptions at least. + </para> + </sect1> + + <sect1 id="conventions-ifdef"> + <title>#if</title> + + <para> + It is generally considered cleaner to use macros in header files + (or at the top of .c files) to abstract away functions rather than + using `#if' pre-processor statements throughout the source code. + </para> + </sect1> + </chapter> + + <chapter id="submitting"> + <title>Putting Your Stuff in the Kernel</title> + + <para> + In order to get your stuff into shape for official inclusion, or + even to make a neat patch, there's administrative work to be + done: + </para> + <itemizedlist> + <listitem> + <para> + Figure out whose pond you've been pissing in. Look at the top of + the source files, inside the <filename>MAINTAINERS</filename> + file, and last of all in the <filename>CREDITS</filename> file. + You should coordinate with this person to make sure you're not + duplicating effort, or trying something that's already been + rejected. + </para> + + <para> + Make sure you put your name and EMail address at the top of + any files you create or mangle significantly. This is the + first place people will look when they find a bug, or when + <emphasis>they</emphasis> want to make a change. + </para> + </listitem> + + <listitem> + <para> + Usually you want a configuration option for your kernel hack. + Edit <filename>Kconfig</filename> in the appropriate directory. + The Config language is simple to use by cut and paste, and there's + complete documentation in + <filename>Documentation/kbuild/kconfig-language.txt</filename>. + </para> + + <para> + In your description of the option, make sure you address both the + expert user and the user who knows nothing about your feature. Mention + incompatibilities and issues here. <emphasis> Definitely + </emphasis> end your description with <quote> if in doubt, say N + </quote> (or, occasionally, `Y'); this is for people who have no + idea what you are talking about. + </para> + </listitem> + + <listitem> + <para> + Edit the <filename>Makefile</filename>: the CONFIG variables are + exported here so you can usually just add a "obj-$(CONFIG_xxx) += + xxx.o" line. The syntax is documented in + <filename>Documentation/kbuild/makefiles.txt</filename>. + </para> + </listitem> + + <listitem> + <para> + Put yourself in <filename>CREDITS</filename> if you've done + something noteworthy, usually beyond a single file (your name + should be at the top of the source files anyway). + <filename>MAINTAINERS</filename> means you want to be consulted + when changes are made to a subsystem, and hear about bugs; it + implies a more-than-passing commitment to some part of the code. + </para> + </listitem> + + <listitem> + <para> + Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename> + and possibly <filename>Documentation/SubmittingDrivers</filename>. + </para> + </listitem> + </itemizedlist> + </chapter> + + <chapter id="cantrips"> + <title>Kernel Cantrips</title> + + <para> + Some favorites from browsing the source. Feel free to add to this + list. + </para> + + <para> + <filename>arch/x86/include/asm/delay.h:</filename> + </para> + <programlisting> +#define ndelay(n) (__builtin_constant_p(n) ? \ + ((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \ + __ndelay(n)) + </programlisting> + + <para> + <filename>include/linux/fs.h</filename>: + </para> + <programlisting> +/* + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a dentry + * pointer with the same return value. + * + * This should be a per-architecture thing, to allow different + * error and pointer decisions. + */ + #define ERR_PTR(err) ((void *)((long)(err))) + #define PTR_ERR(ptr) ((long)(ptr)) + #define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000)) +</programlisting> + + <para> + <filename>arch/x86/include/asm/uaccess_32.h:</filename> + </para> + + <programlisting> +#define copy_to_user(to,from,n) \ + (__builtin_constant_p(n) ? \ + __constant_copy_to_user((to),(from),(n)) : \ + __generic_copy_to_user((to),(from),(n))) + </programlisting> + + <para> + <filename>arch/sparc/kernel/head.S:</filename> + </para> + + <programlisting> +/* + * Sun people can't spell worth damn. "compatability" indeed. + * At least we *know* we can't spell, and use a spell-checker. + */ + +/* Uh, actually Linus it is I who cannot spell. Too much murky + * Sparc assembly will do this to ya. + */ +C_LABEL(cputypvar): + .asciz "compatibility" + +/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ + .align 4 +C_LABEL(cputypvar_sun4m): + .asciz "compatible" + </programlisting> + + <para> + <filename>arch/sparc/lib/checksum.S:</filename> + </para> + + <programlisting> + /* Sun, you just can't beat me, you just can't. Stop trying, + * give up. I'm serious, I am going to kick the living shit + * out of you, game over, lights out. + */ + </programlisting> + </chapter> + + <chapter id="credits"> + <title>Thanks</title> + + <para> + Thanks to Andi Kleen for the idea, answering my questions, fixing + my mistakes, filling content, etc. Philipp Rumpf for more spelling + and clarity fixes, and some excellent non-obvious points. Werner + Almesberger for giving me a great summary of + <function>disable_irq()</function>, and Jes Sorensen and Andrea + Arcangeli added caveats. Michael Elizabeth Chastain for checking + and adding to the Configure section. <!-- Rusty insisted on this + bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook. + </para> + </chapter> +</book> +
diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl new file mode 100644 index 0000000..7c9cc48 --- /dev/null +++ b/Documentation/DocBook/kernel-locking.tmpl
@@ -0,0 +1,2151 @@ +<?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="LKLockingGuide"> + <bookinfo> + <title>Unreliable Guide To Locking</title> + + <authorgroup> + <author> + <firstname>Rusty</firstname> + <surname>Russell</surname> + <affiliation> + <address> + <email>rusty@rustcorp.com.au</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2003</year> + <holder>Rusty Russell</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> + Welcome, to Rusty's Remarkably Unreliable Guide to Kernel + Locking issues. This document describes the locking systems in + the Linux Kernel in 2.6. + </para> + <para> + With the wide availability of HyperThreading, and <firstterm + linkend="gloss-preemption">preemption </firstterm> in the Linux + Kernel, everyone hacking on the kernel needs to know the + fundamentals of concurrency and locking for + <firstterm linkend="gloss-smp"><acronym>SMP</acronym></firstterm>. + </para> + </chapter> + + <chapter id="races"> + <title>The Problem With Concurrency</title> + <para> + (Skip this if you know what a Race Condition is). + </para> + <para> + In a normal program, you can increment a counter like so: + </para> + <programlisting> + very_important_count++; + </programlisting> + + <para> + This is what they would expect to happen: + </para> + + <table> + <title>Expected Results</title> + + <tgroup cols="2" align="left"> + + <thead> + <row> + <entry>Instance 1</entry> + <entry>Instance 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>read very_important_count (5)</entry> + <entry></entry> + </row> + <row> + <entry>add 1 (6)</entry> + <entry></entry> + </row> + <row> + <entry>write very_important_count (6)</entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>read very_important_count (6)</entry> + </row> + <row> + <entry></entry> + <entry>add 1 (7)</entry> + </row> + <row> + <entry></entry> + <entry>write very_important_count (7)</entry> + </row> + </tbody> + + </tgroup> + </table> + + <para> + This is what might happen: + </para> + + <table> + <title>Possible Results</title> + + <tgroup cols="2" align="left"> + <thead> + <row> + <entry>Instance 1</entry> + <entry>Instance 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>read very_important_count (5)</entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>read very_important_count (5)</entry> + </row> + <row> + <entry>add 1 (6)</entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>add 1 (6)</entry> + </row> + <row> + <entry>write very_important_count (6)</entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>write very_important_count (6)</entry> + </row> + </tbody> + </tgroup> + </table> + + <sect1 id="race-condition"> + <title>Race Conditions and Critical Regions</title> + <para> + This overlap, where the result depends on the + relative timing of multiple tasks, is called a <firstterm>race condition</firstterm>. + The piece of code containing the concurrency issue is called a + <firstterm>critical region</firstterm>. And especially since Linux starting running + on SMP machines, they became one of the major issues in kernel + design and implementation. + </para> + <para> + Preemption can have the same effect, even if there is only one + CPU: by preempting one task during the critical region, we have + exactly the same race condition. In this case the thread which + preempts might run the critical region itself. + </para> + <para> + The solution is to recognize when these simultaneous accesses + occur, and use locks to make sure that only one instance can + enter the critical region at any time. There are many + friendly primitives in the Linux kernel to help you do this. + And then there are the unfriendly primitives, but I'll pretend + they don't exist. + </para> + </sect1> + </chapter> + + <chapter id="locks"> + <title>Locking in the Linux Kernel</title> + + <para> + If I could give you one piece of advice: never sleep with anyone + crazier than yourself. But if I had to give you advice on + locking: <emphasis>keep it simple</emphasis>. + </para> + + <para> + Be reluctant to introduce new locks. + </para> + + <para> + Strangely enough, this last one is the exact reverse of my advice when + you <emphasis>have</emphasis> slept with someone crazier than yourself. + And you should think about getting a big dog. + </para> + + <sect1 id="lock-intro"> + <title>Two Main Types of Kernel Locks: Spinlocks and Mutexes</title> + + <para> + There are two main types of kernel locks. The fundamental type + is the spinlock + (<filename class="headerfile">include/asm/spinlock.h</filename>), + which is a very simple single-holder lock: if you can't get the + spinlock, you keep trying (spinning) until you can. Spinlocks are + very small and fast, and can be used anywhere. + </para> + <para> + The second type is a mutex + (<filename class="headerfile">include/linux/mutex.h</filename>): it + is like a spinlock, but you may block holding a mutex. + If you can't lock a mutex, your task will suspend itself, and be woken + up when the mutex is released. This means the CPU can do something + else while you are waiting. There are many cases when you simply + can't sleep (see <xref linkend="sleeping-things"/>), and so have to + use a spinlock instead. + </para> + <para> + Neither type of lock is recursive: see + <xref linkend="deadlock"/>. + </para> + </sect1> + + <sect1 id="uniprocessor"> + <title>Locks and Uniprocessor Kernels</title> + + <para> + For kernels compiled without <symbol>CONFIG_SMP</symbol>, and + without <symbol>CONFIG_PREEMPT</symbol> spinlocks do not exist at + all. This is an excellent design decision: when no-one else can + run at the same time, there is no reason to have a lock. + </para> + + <para> + If the kernel is compiled without <symbol>CONFIG_SMP</symbol>, + but <symbol>CONFIG_PREEMPT</symbol> is set, then spinlocks + simply disable preemption, which is sufficient to prevent any + races. For most purposes, we can think of preemption as + equivalent to SMP, and not worry about it separately. + </para> + + <para> + You should always test your locking code with <symbol>CONFIG_SMP</symbol> + and <symbol>CONFIG_PREEMPT</symbol> enabled, even if you don't have an SMP test box, because it + will still catch some kinds of locking bugs. + </para> + + <para> + Mutexes still exist, because they are required for + synchronization between <firstterm linkend="gloss-usercontext">user + contexts</firstterm>, as we will see below. + </para> + </sect1> + + <sect1 id="usercontextlocking"> + <title>Locking Only In User Context</title> + + <para> + If you have a data structure which is only ever accessed from + user context, then you can use a simple mutex + (<filename>include/linux/mutex.h</filename>) to protect it. This + is the most trivial case: you initialize the mutex. Then you can + call <function>mutex_lock_interruptible()</function> to grab the mutex, + and <function>mutex_unlock()</function> to release it. There is also a + <function>mutex_lock()</function>, which should be avoided, because it + will not return if a signal is received. + </para> + + <para> + Example: <filename>net/netfilter/nf_sockopt.c</filename> allows + registration of new <function>setsockopt()</function> and + <function>getsockopt()</function> calls, with + <function>nf_register_sockopt()</function>. Registration and + de-registration are only done on module load and unload (and boot + time, where there is no concurrency), and the list of registrations + is only consulted for an unknown <function>setsockopt()</function> + or <function>getsockopt()</function> system call. The + <varname>nf_sockopt_mutex</varname> is perfect to protect this, + especially since the setsockopt and getsockopt calls may well + sleep. + </para> + </sect1> + + <sect1 id="lock-user-bh"> + <title>Locking Between User Context and Softirqs</title> + + <para> + If a <firstterm linkend="gloss-softirq">softirq</firstterm> shares + data with user context, you have two problems. Firstly, the current + user context can be interrupted by a softirq, and secondly, the + critical region could be entered from another CPU. This is where + <function>spin_lock_bh()</function> + (<filename class="headerfile">include/linux/spinlock.h</filename>) is + used. It disables softirqs on that CPU, then grabs the lock. + <function>spin_unlock_bh()</function> does the reverse. (The + '_bh' suffix is a historical reference to "Bottom Halves", the + old name for software interrupts. It should really be + called spin_lock_softirq()' in a perfect world). + </para> + + <para> + Note that you can also use <function>spin_lock_irq()</function> + or <function>spin_lock_irqsave()</function> here, which stop + hardware interrupts as well: see <xref linkend="hardirq-context"/>. + </para> + + <para> + This works perfectly for <firstterm linkend="gloss-up"><acronym>UP + </acronym></firstterm> as well: the spin lock vanishes, and this macro + simply becomes <function>local_bh_disable()</function> + (<filename class="headerfile">include/linux/interrupt.h</filename>), which + protects you from the softirq being run. + </para> + </sect1> + + <sect1 id="lock-user-tasklet"> + <title>Locking Between User Context and Tasklets</title> + + <para> + This is exactly the same as above, because <firstterm + linkend="gloss-tasklet">tasklets</firstterm> are actually run + from a softirq. + </para> + </sect1> + + <sect1 id="lock-user-timers"> + <title>Locking Between User Context and Timers</title> + + <para> + This, too, is exactly the same as above, because <firstterm + linkend="gloss-timers">timers</firstterm> are actually run from + a softirq. From a locking point of view, tasklets and timers + are identical. + </para> + </sect1> + + <sect1 id="lock-tasklets"> + <title>Locking Between Tasklets/Timers</title> + + <para> + Sometimes a tasklet or timer might want to share data with + another tasklet or timer. + </para> + + <sect2 id="lock-tasklets-same"> + <title>The Same Tasklet/Timer</title> + <para> + Since a tasklet is never run on two CPUs at once, you don't + need to worry about your tasklet being reentrant (running + twice at once), even on SMP. + </para> + </sect2> + + <sect2 id="lock-tasklets-different"> + <title>Different Tasklets/Timers</title> + <para> + If another tasklet/timer wants + to share data with your tasklet or timer , you will both need to use + <function>spin_lock()</function> and + <function>spin_unlock()</function> calls. + <function>spin_lock_bh()</function> is + unnecessary here, as you are already in a tasklet, and + none will be run on the same CPU. + </para> + </sect2> + </sect1> + + <sect1 id="lock-softirqs"> + <title>Locking Between Softirqs</title> + + <para> + Often a softirq might + want to share data with itself or a tasklet/timer. + </para> + + <sect2 id="lock-softirqs-same"> + <title>The Same Softirq</title> + + <para> + The same softirq can run on the other CPUs: you can use a + per-CPU array (see <xref linkend="per-cpu"/>) for better + performance. If you're going so far as to use a softirq, + you probably care about scalable performance enough + to justify the extra complexity. + </para> + + <para> + You'll need to use <function>spin_lock()</function> and + <function>spin_unlock()</function> for shared data. + </para> + </sect2> + + <sect2 id="lock-softirqs-different"> + <title>Different Softirqs</title> + + <para> + You'll need to use <function>spin_lock()</function> and + <function>spin_unlock()</function> for shared data, whether it + be a timer, tasklet, different softirq or the same or another + softirq: any of them could be running on a different CPU. + </para> + </sect2> + </sect1> + </chapter> + + <chapter id="hardirq-context"> + <title>Hard IRQ Context</title> + + <para> + Hardware interrupts usually communicate with a + tasklet or softirq. Frequently this involves putting work in a + queue, which the softirq will take out. + </para> + + <sect1 id="hardirq-softirq"> + <title>Locking Between Hard IRQ and Softirqs/Tasklets</title> + + <para> + If a hardware irq handler shares data with a softirq, you have + two concerns. Firstly, the softirq processing can be + interrupted by a hardware interrupt, and secondly, the + critical region could be entered by a hardware interrupt on + another CPU. This is where <function>spin_lock_irq()</function> is + used. It is defined to disable interrupts on that cpu, then grab + the lock. <function>spin_unlock_irq()</function> does the reverse. + </para> + + <para> + The irq handler does not to use + <function>spin_lock_irq()</function>, because the softirq cannot + run while the irq handler is running: it can use + <function>spin_lock()</function>, which is slightly faster. The + only exception would be if a different hardware irq handler uses + the same lock: <function>spin_lock_irq()</function> will stop + that from interrupting us. + </para> + + <para> + This works perfectly for UP as well: the spin lock vanishes, + and this macro simply becomes <function>local_irq_disable()</function> + (<filename class="headerfile">include/asm/smp.h</filename>), which + protects you from the softirq/tasklet/BH being run. + </para> + + <para> + <function>spin_lock_irqsave()</function> + (<filename>include/linux/spinlock.h</filename>) is a variant + which saves whether interrupts were on or off in a flags word, + which is passed to <function>spin_unlock_irqrestore()</function>. This + means that the same code can be used inside an hard irq handler (where + interrupts are already off) and in softirqs (where the irq + disabling is required). + </para> + + <para> + Note that softirqs (and hence tasklets and timers) are run on + return from hardware interrupts, so + <function>spin_lock_irq()</function> also stops these. In that + sense, <function>spin_lock_irqsave()</function> is the most + general and powerful locking function. + </para> + + </sect1> + <sect1 id="hardirq-hardirq"> + <title>Locking Between Two Hard IRQ Handlers</title> + <para> + It is rare to have to share data between two IRQ handlers, but + if you do, <function>spin_lock_irqsave()</function> should be + used: it is architecture-specific whether all interrupts are + disabled inside irq handlers themselves. + </para> + </sect1> + + </chapter> + + <chapter id="cheatsheet"> + <title>Cheat Sheet For Locking</title> + <para> + Pete Zaitcev gives the following summary: + </para> + <itemizedlist> + <listitem> + <para> + If you are in a process context (any syscall) and want to + lock other process out, use a mutex. You can take a mutex + and sleep (<function>copy_from_user*(</function> or + <function>kmalloc(x,GFP_KERNEL)</function>). + </para> + </listitem> + <listitem> + <para> + Otherwise (== data can be touched in an interrupt), use + <function>spin_lock_irqsave()</function> and + <function>spin_unlock_irqrestore()</function>. + </para> + </listitem> + <listitem> + <para> + Avoid holding spinlock for more than 5 lines of code and + across any function call (except accessors like + <function>readb</function>). + </para> + </listitem> + </itemizedlist> + + <sect1 id="minimum-lock-reqirements"> + <title>Table of Minimum Requirements</title> + + <para> The following table lists the <emphasis>minimum</emphasis> + locking requirements between various contexts. In some cases, + the same context can only be running on one CPU at a time, so + no locking is required for that context (eg. a particular + thread can only run on one CPU at a time, but if it needs + shares data with another thread, locking is required). + </para> + <para> + Remember the advice above: you can always use + <function>spin_lock_irqsave()</function>, which is a superset + of all other spinlock primitives. + </para> + + <table> +<title>Table of Locking Requirements</title> +<tgroup cols="11"> +<tbody> + +<row> +<entry></entry> +<entry>IRQ Handler A</entry> +<entry>IRQ Handler B</entry> +<entry>Softirq A</entry> +<entry>Softirq B</entry> +<entry>Tasklet A</entry> +<entry>Tasklet B</entry> +<entry>Timer A</entry> +<entry>Timer B</entry> +<entry>User Context A</entry> +<entry>User Context B</entry> +</row> + +<row> +<entry>IRQ Handler A</entry> +<entry>None</entry> +</row> + +<row> +<entry>IRQ Handler B</entry> +<entry>SLIS</entry> +<entry>None</entry> +</row> + +<row> +<entry>Softirq A</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +</row> + +<row> +<entry>Softirq B</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +</row> + +<row> +<entry>Tasklet A</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>None</entry> +</row> + +<row> +<entry>Tasklet B</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>None</entry> +</row> + +<row> +<entry>Timer A</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>None</entry> +</row> + +<row> +<entry>Timer B</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>SL</entry> +<entry>None</entry> +</row> + +<row> +<entry>User Context A</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>None</entry> +</row> + +<row> +<entry>User Context B</entry> +<entry>SLI</entry> +<entry>SLI</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>SLBH</entry> +<entry>MLI</entry> +<entry>None</entry> +</row> + +</tbody> +</tgroup> +</table> + + <table> +<title>Legend for Locking Requirements Table</title> +<tgroup cols="2"> +<tbody> + +<row> +<entry>SLIS</entry> +<entry>spin_lock_irqsave</entry> +</row> +<row> +<entry>SLI</entry> +<entry>spin_lock_irq</entry> +</row> +<row> +<entry>SL</entry> +<entry>spin_lock</entry> +</row> +<row> +<entry>SLBH</entry> +<entry>spin_lock_bh</entry> +</row> +<row> +<entry>MLI</entry> +<entry>mutex_lock_interruptible</entry> +</row> + +</tbody> +</tgroup> +</table> + +</sect1> +</chapter> + +<chapter id="trylock-functions"> + <title>The trylock Functions</title> + <para> + There are functions that try to acquire a lock only once and immediately + return a value telling about success or failure to acquire the lock. + They can be used if you need no access to the data protected with the lock + when some other thread is holding the lock. You should acquire the lock + later if you then need access to the data protected with the lock. + </para> + + <para> + <function>spin_trylock()</function> does not spin but returns non-zero if + it acquires the spinlock on the first try or 0 if not. This function can + be used in all contexts like <function>spin_lock</function>: you must have + disabled the contexts that might interrupt you and acquire the spin lock. + </para> + + <para> + <function>mutex_trylock()</function> does not suspend your task + but returns non-zero if it could lock the mutex on the first try + or 0 if not. This function cannot be safely used in hardware or software + interrupt contexts despite not sleeping. + </para> +</chapter> + + <chapter id="Examples"> + <title>Common Examples</title> + <para> +Let's step through a simple example: a cache of number to name +mappings. The cache keeps a count of how often each of the objects is +used, and when it gets full, throws out the least used one. + + </para> + + <sect1 id="examples-usercontext"> + <title>All In User Context</title> + <para> +For our first example, we assume that all operations are in user +context (ie. from system calls), so we can sleep. This means we can +use a mutex to protect the cache and all the objects within +it. Here's the code: + </para> + + <programlisting> +#include <linux/list.h> +#include <linux/slab.h> +#include <linux/string.h> +#include <linux/mutex.h> +#include <asm/errno.h> + +struct object +{ + struct list_head list; + int id; + char name[32]; + int popularity; +}; + +/* Protects the cache, cache_num, and the objects within it */ +static DEFINE_MUTEX(cache_lock); +static LIST_HEAD(cache); +static unsigned int cache_num = 0; +#define MAX_CACHE_SIZE 10 + +/* Must be holding cache_lock */ +static struct object *__cache_find(int id) +{ + struct object *i; + + list_for_each_entry(i, &cache, list) + if (i->id == id) { + i->popularity++; + return i; + } + return NULL; +} + +/* Must be holding cache_lock */ +static void __cache_delete(struct object *obj) +{ + BUG_ON(!obj); + list_del(&obj->list); + kfree(obj); + cache_num--; +} + +/* Must be holding cache_lock */ +static void __cache_add(struct object *obj) +{ + list_add(&obj->list, &cache); + if (++cache_num > MAX_CACHE_SIZE) { + struct object *i, *outcast = NULL; + list_for_each_entry(i, &cache, list) { + if (!outcast || i->popularity < outcast->popularity) + outcast = i; + } + __cache_delete(outcast); + } +} + +int cache_add(int id, const char *name) +{ + struct object *obj; + + if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + return -ENOMEM; + + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; + + mutex_lock(&cache_lock); + __cache_add(obj); + mutex_unlock(&cache_lock); + return 0; +} + +void cache_delete(int id) +{ + mutex_lock(&cache_lock); + __cache_delete(__cache_find(id)); + mutex_unlock(&cache_lock); +} + +int cache_find(int id, char *name) +{ + struct object *obj; + int ret = -ENOENT; + + mutex_lock(&cache_lock); + obj = __cache_find(id); + if (obj) { + ret = 0; + strcpy(name, obj->name); + } + mutex_unlock(&cache_lock); + return ret; +} +</programlisting> + + <para> +Note that we always make sure we have the cache_lock when we add, +delete, or look up the cache: both the cache infrastructure itself and +the contents of the objects are protected by the lock. In this case +it's easy, since we copy the data for the user, and never let them +access the objects directly. + </para> + <para> +There is a slight (and common) optimization here: in +<function>cache_add</function> we set up the fields of the object +before grabbing the lock. This is safe, as no-one else can access it +until we put it in cache. + </para> + </sect1> + + <sect1 id="examples-interrupt"> + <title>Accessing From Interrupt Context</title> + <para> +Now consider the case where <function>cache_find</function> can be +called from interrupt context: either a hardware interrupt or a +softirq. An example would be a timer which deletes object from the +cache. + </para> + <para> +The change is shown below, in standard patch format: the +<symbol>-</symbol> are lines which are taken away, and the +<symbol>+</symbol> are lines which are added. + </para> +<programlisting> +--- cache.c.usercontext 2003-12-09 13:58:54.000000000 +1100 ++++ cache.c.interrupt 2003-12-09 14:07:49.000000000 +1100 +@@ -12,7 +12,7 @@ + int popularity; + }; + +-static DEFINE_MUTEX(cache_lock); ++static DEFINE_SPINLOCK(cache_lock); + static LIST_HEAD(cache); + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 +@@ -55,6 +55,7 @@ + int cache_add(int id, const char *name) + { + struct object *obj; ++ unsigned long flags; + + if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL) + return -ENOMEM; +@@ -63,30 +64,33 @@ + obj->id = id; + obj->popularity = 0; + +- mutex_lock(&cache_lock); ++ spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); +- mutex_unlock(&cache_lock); ++ spin_unlock_irqrestore(&cache_lock, flags); + return 0; + } + + void cache_delete(int id) + { +- mutex_lock(&cache_lock); ++ unsigned long flags; ++ ++ spin_lock_irqsave(&cache_lock, flags); + __cache_delete(__cache_find(id)); +- mutex_unlock(&cache_lock); ++ spin_unlock_irqrestore(&cache_lock, flags); + } + + int cache_find(int id, char *name) + { + struct object *obj; + int ret = -ENOENT; ++ unsigned long flags; + +- mutex_lock(&cache_lock); ++ spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); + if (obj) { + ret = 0; + strcpy(name, obj->name); + } +- mutex_unlock(&cache_lock); ++ spin_unlock_irqrestore(&cache_lock, flags); + return ret; + } +</programlisting> + + <para> +Note that the <function>spin_lock_irqsave</function> will turn off +interrupts if they are on, otherwise does nothing (if we are already +in an interrupt handler), hence these functions are safe to call from +any context. + </para> + <para> +Unfortunately, <function>cache_add</function> calls +<function>kmalloc</function> with the <symbol>GFP_KERNEL</symbol> +flag, which is only legal in user context. I have assumed that +<function>cache_add</function> is still only called in user context, +otherwise this should become a parameter to +<function>cache_add</function>. + </para> + </sect1> + <sect1 id="examples-refcnt"> + <title>Exposing Objects Outside This File</title> + <para> +If our objects contained more information, it might not be sufficient +to copy the information in and out: other parts of the code might want +to keep pointers to these objects, for example, rather than looking up +the id every time. This produces two problems. + </para> + <para> +The first problem is that we use the <symbol>cache_lock</symbol> to +protect objects: we'd need to make this non-static so the rest of the +code can use it. This makes locking trickier, as it is no longer all +in one place. + </para> + <para> +The second problem is the lifetime problem: if another structure keeps +a pointer to an object, it presumably expects that pointer to remain +valid. Unfortunately, this is only guaranteed while you hold the +lock, otherwise someone might call <function>cache_delete</function> +and even worse, add another object, re-using the same address. + </para> + <para> +As there is only one lock, you can't hold it forever: no-one else would +get any work done. + </para> + <para> +The solution to this problem is to use a reference count: everyone who +has a pointer to the object increases it when they first get the +object, and drops the reference count when they're finished with it. +Whoever drops it to zero knows it is unused, and can actually delete it. + </para> + <para> +Here is the code: + </para> + +<programlisting> +--- cache.c.interrupt 2003-12-09 14:25:43.000000000 +1100 ++++ cache.c.refcnt 2003-12-09 14:33:05.000000000 +1100 +@@ -7,6 +7,7 @@ + struct object + { + struct list_head list; ++ unsigned int refcnt; + int id; + char name[32]; + int popularity; +@@ -17,6 +18,35 @@ + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + ++static void __object_put(struct object *obj) ++{ ++ if (--obj->refcnt == 0) ++ kfree(obj); ++} ++ ++static void __object_get(struct object *obj) ++{ ++ obj->refcnt++; ++} ++ ++void object_put(struct object *obj) ++{ ++ unsigned long flags; ++ ++ spin_lock_irqsave(&cache_lock, flags); ++ __object_put(obj); ++ spin_unlock_irqrestore(&cache_lock, flags); ++} ++ ++void object_get(struct object *obj) ++{ ++ unsigned long flags; ++ ++ spin_lock_irqsave(&cache_lock, flags); ++ __object_get(obj); ++ spin_unlock_irqrestore(&cache_lock, flags); ++} ++ + /* Must be holding cache_lock */ + static struct object *__cache_find(int id) + { +@@ -35,6 +65,7 @@ + { + BUG_ON(!obj); + list_del(&obj->list); ++ __object_put(obj); + cache_num--; + } + +@@ -63,6 +94,7 @@ + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; ++ obj->refcnt = 1; /* The cache holds a reference */ + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); +@@ -79,18 +111,15 @@ + spin_unlock_irqrestore(&cache_lock, flags); + } + +-int cache_find(int id, char *name) ++struct object *cache_find(int id) + { + struct object *obj; +- int ret = -ENOENT; + unsigned long flags; + + spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); +- if (obj) { +- ret = 0; +- strcpy(name, obj->name); +- } ++ if (obj) ++ __object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); +- return ret; ++ return obj; + } +</programlisting> + +<para> +We encapsulate the reference counting in the standard 'get' and 'put' +functions. Now we can return the object itself from +<function>cache_find</function> which has the advantage that the user +can now sleep holding the object (eg. to +<function>copy_to_user</function> to name to userspace). +</para> +<para> +The other point to note is that I said a reference should be held for +every pointer to the object: thus the reference count is 1 when first +inserted into the cache. In some versions the framework does not hold +a reference count, but they are more complicated. +</para> + + <sect2 id="examples-refcnt-atomic"> + <title>Using Atomic Operations For The Reference Count</title> +<para> +In practice, <type>atomic_t</type> would usually be used for +<structfield>refcnt</structfield>. There are a number of atomic +operations defined in + +<filename class="headerfile">include/asm/atomic.h</filename>: these are +guaranteed to be seen atomically from all CPUs in the system, so no +lock is required. In this case, it is simpler than using spinlocks, +although for anything non-trivial using spinlocks is clearer. The +<function>atomic_inc</function> and +<function>atomic_dec_and_test</function> are used instead of the +standard increment and decrement operators, and the lock is no longer +used to protect the reference count itself. +</para> + +<programlisting> +--- cache.c.refcnt 2003-12-09 15:00:35.000000000 +1100 ++++ cache.c.refcnt-atomic 2003-12-11 15:49:42.000000000 +1100 +@@ -7,7 +7,7 @@ + struct object + { + struct list_head list; +- unsigned int refcnt; ++ atomic_t refcnt; + int id; + char name[32]; + int popularity; +@@ -18,33 +18,15 @@ + static unsigned int cache_num = 0; + #define MAX_CACHE_SIZE 10 + +-static void __object_put(struct object *obj) +-{ +- if (--obj->refcnt == 0) +- kfree(obj); +-} +- +-static void __object_get(struct object *obj) +-{ +- obj->refcnt++; +-} +- + void object_put(struct object *obj) + { +- unsigned long flags; +- +- spin_lock_irqsave(&cache_lock, flags); +- __object_put(obj); +- spin_unlock_irqrestore(&cache_lock, flags); ++ if (atomic_dec_and_test(&obj->refcnt)) ++ kfree(obj); + } + + void object_get(struct object *obj) + { +- unsigned long flags; +- +- spin_lock_irqsave(&cache_lock, flags); +- __object_get(obj); +- spin_unlock_irqrestore(&cache_lock, flags); ++ atomic_inc(&obj->refcnt); + } + + /* Must be holding cache_lock */ +@@ -65,7 +47,7 @@ + { + BUG_ON(!obj); + list_del(&obj->list); +- __object_put(obj); ++ object_put(obj); + cache_num--; + } + +@@ -94,7 +76,7 @@ + strlcpy(obj->name, name, sizeof(obj->name)); + obj->id = id; + obj->popularity = 0; +- obj->refcnt = 1; /* The cache holds a reference */ ++ atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); +@@ -119,7 +101,7 @@ + spin_lock_irqsave(&cache_lock, flags); + obj = __cache_find(id); + if (obj) +- __object_get(obj); ++ object_get(obj); + spin_unlock_irqrestore(&cache_lock, flags); + return obj; + } +</programlisting> +</sect2> +</sect1> + + <sect1 id="examples-lock-per-obj"> + <title>Protecting The Objects Themselves</title> + <para> +In these examples, we assumed that the objects (except the reference +counts) never changed once they are created. If we wanted to allow +the name to change, there are three possibilities: + </para> + <itemizedlist> + <listitem> + <para> +You can make <symbol>cache_lock</symbol> non-static, and tell people +to grab that lock before changing the name in any object. + </para> + </listitem> + <listitem> + <para> +You can provide a <function>cache_obj_rename</function> which grabs +this lock and changes the name for the caller, and tell everyone to +use that function. + </para> + </listitem> + <listitem> + <para> +You can make the <symbol>cache_lock</symbol> protect only the cache +itself, and use another lock to protect the name. + </para> + </listitem> + </itemizedlist> + + <para> +Theoretically, you can make the locks as fine-grained as one lock for +every field, for every object. In practice, the most common variants +are: +</para> + <itemizedlist> + <listitem> + <para> +One lock which protects the infrastructure (the <symbol>cache</symbol> +list in this example) and all the objects. This is what we have done +so far. + </para> + </listitem> + <listitem> + <para> +One lock which protects the infrastructure (including the list +pointers inside the objects), and one lock inside the object which +protects the rest of that object. + </para> + </listitem> + <listitem> + <para> +Multiple locks to protect the infrastructure (eg. one lock per hash +chain), possibly with a separate per-object lock. + </para> + </listitem> + </itemizedlist> + +<para> +Here is the "lock-per-object" implementation: +</para> +<programlisting> +--- cache.c.refcnt-atomic 2003-12-11 15:50:54.000000000 +1100 ++++ cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 +@@ -6,11 +6,17 @@ + + struct object + { ++ /* These two protected by cache_lock. */ + struct list_head list; ++ int popularity; ++ + atomic_t refcnt; ++ ++ /* Doesn't change once created. */ + int id; ++ ++ spinlock_t lock; /* Protects the name */ + char name[32]; +- int popularity; + }; + + static DEFINE_SPINLOCK(cache_lock); +@@ -77,6 +84,7 @@ + obj->id = id; + obj->popularity = 0; + atomic_set(&obj->refcnt, 1); /* The cache holds a reference */ ++ spin_lock_init(&obj->lock); + + spin_lock_irqsave(&cache_lock, flags); + __cache_add(obj); +</programlisting> + +<para> +Note that I decide that the <structfield>popularity</structfield> +count should be protected by the <symbol>cache_lock</symbol> rather +than the per-object lock: this is because it (like the +<structname>struct list_head</structname> inside the object) is +logically part of the infrastructure. This way, I don't need to grab +the lock of every object in <function>__cache_add</function> when +seeking the least popular. +</para> + +<para> +I also decided that the <structfield>id</structfield> member is +unchangeable, so I don't need to grab each object lock in +<function>__cache_find()</function> to examine the +<structfield>id</structfield>: the object lock is only used by a +caller who wants to read or write the <structfield>name</structfield> +field. +</para> + +<para> +Note also that I added a comment describing what data was protected by +which locks. This is extremely important, as it describes the runtime +behavior of the code, and can be hard to gain from just reading. And +as Alan Cox says, <quote>Lock data, not code</quote>. +</para> +</sect1> +</chapter> + + <chapter id="common-problems"> + <title>Common Problems</title> + <sect1 id="deadlock"> + <title>Deadlock: Simple and Advanced</title> + + <para> + There is a coding bug where a piece of code tries to grab a + spinlock twice: it will spin forever, waiting for the lock to + be released (spinlocks, rwlocks and mutexes are not + recursive in Linux). This is trivial to diagnose: not a + stay-up-five-nights-talk-to-fluffy-code-bunnies kind of + problem. + </para> + + <para> + For a slightly more complex case, imagine you have a region + shared by a softirq and user context. If you use a + <function>spin_lock()</function> call to protect it, it is + possible that the user context will be interrupted by the softirq + while it holds the lock, and the softirq will then spin + forever trying to get the same lock. + </para> + + <para> + Both of these are called deadlock, and as shown above, it can + occur even with a single CPU (although not on UP compiles, + since spinlocks vanish on kernel compiles with + <symbol>CONFIG_SMP</symbol>=n. You'll still get data corruption + in the second example). + </para> + + <para> + This complete lockup is easy to diagnose: on SMP boxes the + watchdog timer or compiling with <symbol>DEBUG_SPINLOCK</symbol> set + (<filename>include/linux/spinlock.h</filename>) will show this up + immediately when it happens. + </para> + + <para> + A more complex problem is the so-called 'deadly embrace', + involving two or more locks. Say you have a hash table: each + entry in the table is a spinlock, and a chain of hashed + objects. Inside a softirq handler, you sometimes want to + alter an object from one place in the hash to another: you + grab the spinlock of the old hash chain and the spinlock of + the new hash chain, and delete the object from the old one, + and insert it in the new one. + </para> + + <para> + There are two problems here. First, if your code ever + tries to move the object to the same chain, it will deadlock + with itself as it tries to lock it twice. Secondly, if the + same softirq on another CPU is trying to move another object + in the reverse direction, the following could happen: + </para> + + <table> + <title>Consequences</title> + + <tgroup cols="2" align="left"> + + <thead> + <row> + <entry>CPU 1</entry> + <entry>CPU 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Grab lock A -> OK</entry> + <entry>Grab lock B -> OK</entry> + </row> + <row> + <entry>Grab lock B -> spin</entry> + <entry>Grab lock A -> spin</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + The two CPUs will spin forever, waiting for the other to give up + their lock. It will look, smell, and feel like a crash. + </para> + </sect1> + + <sect1 id="techs-deadlock-prevent"> + <title>Preventing Deadlock</title> + + <para> + Textbooks will tell you that if you always lock in the same + order, you will never get this kind of deadlock. Practice + will tell you that this approach doesn't scale: when I + create a new lock, I don't understand enough of the kernel + to figure out where in the 5000 lock hierarchy it will fit. + </para> + + <para> + The best locks are encapsulated: they never get exposed in + headers, and are never held around calls to non-trivial + functions outside the same file. You can read through this + code and see that it will never deadlock, because it never + tries to grab another lock while it has that one. People + using your code don't even need to know you are using a + lock. + </para> + + <para> + A classic problem here is when you provide callbacks or + hooks: if you call these with the lock held, you risk simple + deadlock, or a deadly embrace (who knows what the callback + will do?). Remember, the other programmers are out to get + you, so don't do this. + </para> + + <sect2 id="techs-deadlock-overprevent"> + <title>Overzealous Prevention Of Deadlocks</title> + + <para> + Deadlocks are problematic, but not as bad as data + corruption. Code which grabs a read lock, searches a list, + fails to find what it wants, drops the read lock, grabs a + write lock and inserts the object has a race condition. + </para> + + <para> + If you don't see why, please stay the fuck away from my code. + </para> + </sect2> + </sect1> + + <sect1 id="racing-timers"> + <title>Racing Timers: A Kernel Pastime</title> + + <para> + Timers can produce their own special problems with races. + Consider a collection of objects (list, hash, etc) where each + object has a timer which is due to destroy it. + </para> + + <para> + If you want to destroy the entire collection (say on module + removal), you might do the following: + </para> + + <programlisting> + /* THIS CODE BAD BAD BAD BAD: IF IT WAS ANY WORSE IT WOULD USE + HUNGARIAN NOTATION */ + spin_lock_bh(&list_lock); + + while (list) { + struct foo *next = list->next; + del_timer(&list->timer); + kfree(list); + list = next; + } + + spin_unlock_bh(&list_lock); + </programlisting> + + <para> + Sooner or later, this will crash on SMP, because a timer can + have just gone off before the <function>spin_lock_bh()</function>, + and it will only get the lock after we + <function>spin_unlock_bh()</function>, and then try to free + the element (which has already been freed!). + </para> + + <para> + This can be avoided by checking the result of + <function>del_timer()</function>: if it returns + <returnvalue>1</returnvalue>, the timer has been deleted. + If <returnvalue>0</returnvalue>, it means (in this + case) that it is currently running, so we can do: + </para> + + <programlisting> + retry: + spin_lock_bh(&list_lock); + + while (list) { + struct foo *next = list->next; + if (!del_timer(&list->timer)) { + /* Give timer a chance to delete this */ + spin_unlock_bh(&list_lock); + goto retry; + } + kfree(list); + list = next; + } + + spin_unlock_bh(&list_lock); + </programlisting> + + <para> + Another common problem is deleting timers which restart + themselves (by calling <function>add_timer()</function> at the end + of their timer function). Because this is a fairly common case + which is prone to races, you should use <function>del_timer_sync()</function> + (<filename class="headerfile">include/linux/timer.h</filename>) + to handle this case. It returns the number of times the timer + had to be deleted before we finally stopped it from adding itself back + in. + </para> + </sect1> + + </chapter> + + <chapter id="Efficiency"> + <title>Locking Speed</title> + + <para> +There are three main things to worry about when considering speed of +some code which does locking. First is concurrency: how many things +are going to be waiting while someone else is holding a lock. Second +is the time taken to actually acquire and release an uncontended lock. +Third is using fewer, or smarter locks. I'm assuming that the lock is +used fairly often: otherwise, you wouldn't be concerned about +efficiency. +</para> + <para> +Concurrency depends on how long the lock is usually held: you should +hold the lock for as long as needed, but no longer. In the cache +example, we always create the object without the lock held, and then +grab the lock only when we are ready to insert it in the list. +</para> + <para> +Acquisition times depend on how much damage the lock operations do to +the pipeline (pipeline stalls) and how likely it is that this CPU was +the last one to grab the lock (ie. is the lock cache-hot for this +CPU): on a machine with more CPUs, this likelihood drops fast. +Consider a 700MHz Intel Pentium III: an instruction takes about 0.7ns, +an atomic increment takes about 58ns, a lock which is cache-hot on +this CPU takes 160ns, and a cacheline transfer from another CPU takes +an additional 170 to 360ns. (These figures from Paul McKenney's +<ulink url="http://www.linuxjournal.com/article.php?sid=6993"> Linux +Journal RCU article</ulink>). +</para> + <para> +These two aims conflict: holding a lock for a short time might be done +by splitting locks into parts (such as in our final per-object-lock +example), but this increases the number of lock acquisitions, and the +results are often slower than having a single lock. This is another +reason to advocate locking simplicity. +</para> + <para> +The third concern is addressed below: there are some methods to reduce +the amount of locking which needs to be done. +</para> + + <sect1 id="efficiency-rwlocks"> + <title>Read/Write Lock Variants</title> + + <para> + Both spinlocks and mutexes have read/write variants: + <type>rwlock_t</type> and <structname>struct rw_semaphore</structname>. + These divide users into two classes: the readers and the writers. If + you are only reading the data, you can get a read lock, but to write to + the data you need the write lock. Many people can hold a read lock, + but a writer must be sole holder. + </para> + + <para> + If your code divides neatly along reader/writer lines (as our + cache code does), and the lock is held by readers for + significant lengths of time, using these locks can help. They + are slightly slower than the normal locks though, so in practice + <type>rwlock_t</type> is not usually worthwhile. + </para> + </sect1> + + <sect1 id="efficiency-read-copy-update"> + <title>Avoiding Locks: Read Copy Update</title> + + <para> + There is a special method of read/write locking called Read Copy + Update. Using RCU, the readers can avoid taking a lock + altogether: as we expect our cache to be read more often than + updated (otherwise the cache is a waste of time), it is a + candidate for this optimization. + </para> + + <para> + How do we get rid of read locks? Getting rid of read locks + means that writers may be changing the list underneath the + readers. That is actually quite simple: we can read a linked + list while an element is being added if the writer adds the + element very carefully. For example, adding + <symbol>new</symbol> to a single linked list called + <symbol>list</symbol>: + </para> + + <programlisting> + new->next = list->next; + wmb(); + list->next = new; + </programlisting> + + <para> + The <function>wmb()</function> is a write memory barrier. It + ensures that the first operation (setting the new element's + <symbol>next</symbol> pointer) is complete and will be seen by + all CPUs, before the second operation is (putting the new + element into the list). This is important, since modern + compilers and modern CPUs can both reorder instructions unless + told otherwise: we want a reader to either not see the new + element at all, or see the new element with the + <symbol>next</symbol> pointer correctly pointing at the rest of + the list. + </para> + <para> + Fortunately, there is a function to do this for standard + <structname>struct list_head</structname> lists: + <function>list_add_rcu()</function> + (<filename>include/linux/list.h</filename>). + </para> + <para> + Removing an element from the list is even simpler: we replace + the pointer to the old element with a pointer to its successor, + and readers will either see it, or skip over it. + </para> + <programlisting> + list->next = old->next; + </programlisting> + <para> + There is <function>list_del_rcu()</function> + (<filename>include/linux/list.h</filename>) which does this (the + normal version poisons the old object, which we don't want). + </para> + <para> + The reader must also be careful: some CPUs can look through the + <symbol>next</symbol> pointer to start reading the contents of + the next element early, but don't realize that the pre-fetched + contents is wrong when the <symbol>next</symbol> pointer changes + underneath them. Once again, there is a + <function>list_for_each_entry_rcu()</function> + (<filename>include/linux/list.h</filename>) to help you. Of + course, writers can just use + <function>list_for_each_entry()</function>, since there cannot + be two simultaneous writers. + </para> + <para> + Our final dilemma is this: when can we actually destroy the + removed element? Remember, a reader might be stepping through + this element in the list right now: if we free this element and + the <symbol>next</symbol> pointer changes, the reader will jump + off into garbage and crash. We need to wait until we know that + all the readers who were traversing the list when we deleted the + element are finished. We use <function>call_rcu()</function> to + register a callback which will actually destroy the object once + all pre-existing readers are finished. Alternatively, + <function>synchronize_rcu()</function> may be used to block until + all pre-existing are finished. + </para> + <para> + But how does Read Copy Update know when the readers are + finished? The method is this: firstly, the readers always + traverse the list inside + <function>rcu_read_lock()</function>/<function>rcu_read_unlock()</function> + pairs: these simply disable preemption so the reader won't go to + sleep while reading the list. + </para> + <para> + RCU then waits until every other CPU has slept at least once: + since readers cannot sleep, we know that any readers which were + traversing the list during the deletion are finished, and the + callback is triggered. The real Read Copy Update code is a + little more optimized than this, but this is the fundamental + idea. + </para> + +<programlisting> +--- cache.c.perobjectlock 2003-12-11 17:15:03.000000000 +1100 ++++ cache.c.rcupdate 2003-12-11 17:55:14.000000000 +1100 +@@ -1,15 +1,18 @@ + #include <linux/list.h> + #include <linux/slab.h> + #include <linux/string.h> ++#include <linux/rcupdate.h> + #include <linux/mutex.h> + #include <asm/errno.h> + + struct object + { +- /* These two protected by cache_lock. */ ++ /* This is protected by RCU */ + struct list_head list; + int popularity; + ++ struct rcu_head rcu; ++ + atomic_t refcnt; + + /* Doesn't change once created. */ +@@ -40,7 +43,7 @@ + { + struct object *i; + +- list_for_each_entry(i, &cache, list) { ++ list_for_each_entry_rcu(i, &cache, list) { + if (i->id == id) { + i->popularity++; + return i; +@@ -49,19 +52,25 @@ + return NULL; + } + ++/* Final discard done once we know no readers are looking. */ ++static void cache_delete_rcu(void *arg) ++{ ++ object_put(arg); ++} ++ + /* Must be holding cache_lock */ + static void __cache_delete(struct object *obj) + { + BUG_ON(!obj); +- list_del(&obj->list); +- object_put(obj); ++ list_del_rcu(&obj->list); + cache_num--; ++ call_rcu(&obj->rcu, cache_delete_rcu); + } + + /* Must be holding cache_lock */ + static void __cache_add(struct object *obj) + { +- list_add(&obj->list, &cache); ++ list_add_rcu(&obj->list, &cache); + if (++cache_num > MAX_CACHE_SIZE) { + struct object *i, *outcast = NULL; + list_for_each_entry(i, &cache, list) { +@@ -104,12 +114,11 @@ + struct object *cache_find(int id) + { + struct object *obj; +- unsigned long flags; + +- spin_lock_irqsave(&cache_lock, flags); ++ rcu_read_lock(); + obj = __cache_find(id); + if (obj) + object_get(obj); +- spin_unlock_irqrestore(&cache_lock, flags); ++ rcu_read_unlock(); + return obj; + } +</programlisting> + +<para> +Note that the reader will alter the +<structfield>popularity</structfield> member in +<function>__cache_find()</function>, and now it doesn't hold a lock. +One solution would be to make it an <type>atomic_t</type>, but for +this usage, we don't really care about races: an approximate result is +good enough, so I didn't change it. +</para> + +<para> +The result is that <function>cache_find()</function> requires no +synchronization with any other functions, so is almost as fast on SMP +as it would be on UP. +</para> + +<para> +There is a further optimization possible here: remember our original +cache code, where there were no reference counts and the caller simply +held the lock whenever using the object? This is still possible: if +you hold the lock, no one can delete the object, so you don't need to +get and put the reference count. +</para> + +<para> +Now, because the 'read lock' in RCU is simply disabling preemption, a +caller which always has preemption disabled between calling +<function>cache_find()</function> and +<function>object_put()</function> does not need to actually get and +put the reference count: we could expose +<function>__cache_find()</function> by making it non-static, and +such callers could simply call that. +</para> +<para> +The benefit here is that the reference count is not written to: the +object is not altered in any way, which is much faster on SMP +machines due to caching. +</para> + </sect1> + + <sect1 id="per-cpu"> + <title>Per-CPU Data</title> + + <para> + Another technique for avoiding locking which is used fairly + widely is to duplicate information for each CPU. For example, + if you wanted to keep a count of a common condition, you could + use a spin lock and a single counter. Nice and simple. + </para> + + <para> + If that was too slow (it's usually not, but if you've got a + really big machine to test on and can show that it is), you + could instead use a counter for each CPU, then none of them need + an exclusive lock. See <function>DEFINE_PER_CPU()</function>, + <function>get_cpu_var()</function> and + <function>put_cpu_var()</function> + (<filename class="headerfile">include/linux/percpu.h</filename>). + </para> + + <para> + Of particular use for simple per-cpu counters is the + <type>local_t</type> type, and the + <function>cpu_local_inc()</function> and related functions, + which are more efficient than simple code on some architectures + (<filename class="headerfile">include/asm/local.h</filename>). + </para> + + <para> + Note that there is no simple, reliable way of getting an exact + value of such a counter, without introducing more locks. This + is not a problem for some uses. + </para> + </sect1> + + <sect1 id="mostly-hardirq"> + <title>Data Which Mostly Used By An IRQ Handler</title> + + <para> + If data is always accessed from within the same IRQ handler, you + don't need a lock at all: the kernel already guarantees that the + irq handler will not run simultaneously on multiple CPUs. + </para> + <para> + Manfred Spraul points out that you can still do this, even if + the data is very occasionally accessed in user context or + softirqs/tasklets. The irq handler doesn't use a lock, and + all other accesses are done as so: + </para> + +<programlisting> + spin_lock(&lock); + disable_irq(irq); + ... + enable_irq(irq); + spin_unlock(&lock); +</programlisting> + <para> + The <function>disable_irq()</function> prevents the irq handler + from running (and waits for it to finish if it's currently + running on other CPUs). The spinlock prevents any other + accesses happening at the same time. Naturally, this is slower + than just a <function>spin_lock_irq()</function> call, so it + only makes sense if this type of access happens extremely + rarely. + </para> + </sect1> + </chapter> + + <chapter id="sleeping-things"> + <title>What Functions Are Safe To Call From Interrupts?</title> + + <para> + Many functions in the kernel sleep (ie. call schedule()) + directly or indirectly: you can never call them while holding a + spinlock, or with preemption disabled. This also means you need + to be in user context: calling them from an interrupt is illegal. + </para> + + <sect1 id="sleeping"> + <title>Some Functions Which Sleep</title> + + <para> + The most common ones are listed below, but you usually have to + read the code to find out if other calls are safe. If everyone + else who calls it can sleep, you probably need to be able to + sleep, too. In particular, registration and deregistration + functions usually expect to be called from user context, and can + sleep. + </para> + + <itemizedlist> + <listitem> + <para> + Accesses to + <firstterm linkend="gloss-userspace">userspace</firstterm>: + </para> + <itemizedlist> + <listitem> + <para> + <function>copy_from_user()</function> + </para> + </listitem> + <listitem> + <para> + <function>copy_to_user()</function> + </para> + </listitem> + <listitem> + <para> + <function>get_user()</function> + </para> + </listitem> + <listitem> + <para> + <function>put_user()</function> + </para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para> + <function>kmalloc(GFP_KERNEL)</function> + </para> + </listitem> + + <listitem> + <para> + <function>mutex_lock_interruptible()</function> and + <function>mutex_lock()</function> + </para> + <para> + There is a <function>mutex_trylock()</function> which does not + sleep. Still, it must not be used inside interrupt context since + its implementation is not safe for that. + <function>mutex_unlock()</function> will also never sleep. + It cannot be used in interrupt context either since a mutex + must be released by the same task that acquired it. + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="dont-sleep"> + <title>Some Functions Which Don't Sleep</title> + + <para> + Some functions are safe to call from any context, or holding + almost any lock. + </para> + + <itemizedlist> + <listitem> + <para> + <function>printk()</function> + </para> + </listitem> + <listitem> + <para> + <function>kfree()</function> + </para> + </listitem> + <listitem> + <para> + <function>add_timer()</function> and <function>del_timer()</function> + </para> + </listitem> + </itemizedlist> + </sect1> + </chapter> + + <chapter id="apiref-mutex"> + <title>Mutex API reference</title> +!Iinclude/linux/mutex.h +!Ekernel/locking/mutex.c + </chapter> + + <chapter id="apiref-futex"> + <title>Futex API reference</title> +!Ikernel/futex.c + </chapter> + + <chapter id="references"> + <title>Further reading</title> + + <itemizedlist> + <listitem> + <para> + <filename>Documentation/locking/spinlocks.txt</filename>: + Linus Torvalds' spinlocking tutorial in the kernel sources. + </para> + </listitem> + + <listitem> + <para> + Unix Systems for Modern Architectures: Symmetric + Multiprocessing and Caching for Kernel Programmers: + </para> + + <para> + Curt Schimmel's very good introduction to kernel level + locking (not written for Linux, but nearly everything + applies). The book is expensive, but really worth every + penny to understand SMP locking. [ISBN: 0201633388] + </para> + </listitem> + </itemizedlist> + </chapter> + + <chapter id="thanks"> + <title>Thanks</title> + + <para> + Thanks to Telsa Gwynne for DocBooking, neatening and adding + style. + </para> + + <para> + Thanks to Martin Pool, Philipp Rumpf, Stephen Rothwell, Paul + Mackerras, Ruedi Aschwanden, Alan Cox, Manfred Spraul, Tim + Waugh, Pete Zaitcev, James Morris, Robert Love, Paul McKenney, + John Ashby for proofreading, correcting, flaming, commenting. + </para> + + <para> + Thanks to the cabal for having no influence on this document. + </para> + </chapter> + + <glossary id="glossary"> + <title>Glossary</title> + + <glossentry id="gloss-preemption"> + <glossterm>preemption</glossterm> + <glossdef> + <para> + Prior to 2.5, or when <symbol>CONFIG_PREEMPT</symbol> is + unset, processes in user context inside the kernel would not + preempt each other (ie. you had that CPU until you gave it up, + except for interrupts). With the addition of + <symbol>CONFIG_PREEMPT</symbol> in 2.5.4, this changed: when + in user context, higher priority tasks can "cut in": spinlocks + were changed to disable preemption, even on UP. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-bh"> + <glossterm>bh</glossterm> + <glossdef> + <para> + Bottom Half: for historical reasons, functions with + '_bh' in them often now refer to any software interrupt, e.g. + <function>spin_lock_bh()</function> blocks any software interrupt + on the current CPU. Bottom halves are deprecated, and will + eventually be replaced by tasklets. Only one bottom half will be + running at any time. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-hwinterrupt"> + <glossterm>Hardware Interrupt / Hardware IRQ</glossterm> + <glossdef> + <para> + Hardware interrupt request. <function>in_irq()</function> returns + <returnvalue>true</returnvalue> in a hardware interrupt handler. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-interruptcontext"> + <glossterm>Interrupt Context</glossterm> + <glossdef> + <para> + Not user context: processing a hardware irq or software irq. + Indicated by the <function>in_interrupt()</function> macro + returning <returnvalue>true</returnvalue>. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-smp"> + <glossterm><acronym>SMP</acronym></glossterm> + <glossdef> + <para> + Symmetric Multi-Processor: kernels compiled for multiple-CPU + machines. (CONFIG_SMP=y). + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-softirq"> + <glossterm>Software Interrupt / softirq</glossterm> + <glossdef> + <para> + Software interrupt handler. <function>in_irq()</function> returns + <returnvalue>false</returnvalue>; <function>in_softirq()</function> + returns <returnvalue>true</returnvalue>. Tasklets and softirqs + both fall into the category of 'software interrupts'. + </para> + <para> + Strictly speaking a softirq is one of up to 32 enumerated software + interrupts which can run on multiple CPUs at once. + Sometimes used to refer to tasklets as + well (ie. all software interrupts). + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-tasklet"> + <glossterm>tasklet</glossterm> + <glossdef> + <para> + A dynamically-registrable software interrupt, + which is guaranteed to only run on one CPU at a time. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-timers"> + <glossterm>timer</glossterm> + <glossdef> + <para> + A dynamically-registrable software interrupt, which is run at + (or close to) a given time. When running, it is just like a + tasklet (in fact, they are called from the TIMER_SOFTIRQ). + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-up"> + <glossterm><acronym>UP</acronym></glossterm> + <glossdef> + <para> + Uni-Processor: Non-SMP. (CONFIG_SMP=n). + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-usercontext"> + <glossterm>User Context</glossterm> + <glossdef> + <para> + The kernel executing on behalf of a particular process (ie. a + system call or trap) or kernel thread. You can tell which + process with the <symbol>current</symbol> macro.) Not to + be confused with userspace. Can be interrupted by software or + hardware interrupts. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-userspace"> + <glossterm>Userspace</glossterm> + <glossdef> + <para> + A process executing its own code outside the kernel. + </para> + </glossdef> + </glossentry> + + </glossary> +</book> +
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl new file mode 100644 index 0000000..f3abca7 --- /dev/null +++ b/Documentation/DocBook/kgdb.tmpl
@@ -0,0 +1,918 @@ +<?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, kdb and the kernel debugger internals</title> + + <authorgroup> + <author> + <firstname>Jason</firstname> + <surname>Wessel</surname> + <affiliation> + <address> + <email>jason.wessel@windriver.com</email> + </address> + </affiliation> + </author> + </authorgroup> + <copyright> + <year>2008,2010</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> + The kernel has two different debugger front ends (kdb and kgdb) + which interface to the debug core. It is possible to use either + of the debugger front ends and dynamically transition between them + if you configure the kernel properly at compile and runtime. + </para> + <para> + Kdb is simplistic shell-style interface which you can use on a + system console with a keyboard or serial console. You can use it + to inspect memory, registers, process lists, dmesg, and even set + breakpoints to stop in a certain location. Kdb is not a source + level debugger, although you can set breakpoints and execute some + basic kernel run control. Kdb is mainly aimed at doing some + analysis to aid in development or diagnosing kernel problems. You + can access some symbols by name in kernel built-ins or in kernel + modules if the code was built + with <symbol>CONFIG_KALLSYMS</symbol>. + </para> + <para> + Kgdb is intended to be used as a source level debugger for the + 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 the way an application developer would use + gdb to debug an application. 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 the target machine. The + kernel to be debugged runs on the target machine. The development + machine runs an instance of gdb against the vmlinux file which + contains the symbols (not a 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 built-ins or loadable kernel modules in the test + machine's kernel. + </para> + </chapter> + <chapter id="CompilingAKernel"> + <title>Compiling a kernel</title> + <para> + <itemizedlist> + <listitem><para>In order to enable compilation of kdb, you must first enable kgdb.</para></listitem> + <listitem><para>The kgdb test compile options are described in the kgdb test suite chapter.</para></listitem> + </itemizedlist> + </para> + <sect1 id="CompileKGDB"> + <title>Kernel config options for kgdb</title> + <para> + To enable <symbol>CONFIG_KGDB</symbol> you should look under + "Kernel hacking" / "Kernel debugging" and select "KGDB: kernel debugger". + </para> + <para> + While it is not a hard requirement that you have symbols in your + vmlinux file, gdb tends not to be very useful without the symbolic + data, so you will want to turn + on <symbol>CONFIG_DEBUG_INFO</symbol> which is called "Compile the + kernel with debug info" in the config menu. + </para> + <para> + It is advised, but not required, that you turn on the + <symbol>CONFIG_FRAME_POINTER</symbol> kernel option which is called "Compile the + kernel with frame pointers" in the config menu. This option + inserts code to into the compiled executable which saves the frame + information in registers or on the stack at different points which + allows 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 which + you can learn more about in the in the section that describes the + parameter "kgdboc". + </para> + <para>Here is an example set of .config symbols to enable or + disable for kgdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + </itemizedlist> + </para> + </sect1> + <sect1 id="CompileKDB"> + <title>Kernel config options for kdb</title> + <para>Kdb is quite a bit more complex than the simple gdbstub + sitting on top of the kernel's debug core. Kdb must implement a + shell, and also adds some helper functions in other parts of the + kernel, responsible for printing out interesting data such as what + you would see if you ran "lsmod", or "ps". In order to build kdb + into the kernel you follow the same steps as you would for kgdb. + </para> + <para>The main config option for kdb + is <symbol>CONFIG_KGDB_KDB</symbol> which is called "KGDB_KDB: + include kdb frontend for kgdb" in the config menu. In theory you + would have already also selected an I/O driver such as the + CONFIG_KGDB_SERIAL_CONSOLE interface if you plan on using kdb on a + serial port, when you were configuring kgdb. + </para> + <para>If you want to use a PS/2-style keyboard with kdb, you would + select CONFIG_KDB_KEYBOARD which is called "KGDB_KDB: keyboard as + input device" in the config menu. The CONFIG_KDB_KEYBOARD option + is not used for anything in the gdb interface to kgdb. The + CONFIG_KDB_KEYBOARD option only works with kdb. + </para> + <para>Here is an example set of .config symbols to enable/disable kdb: + <itemizedlist> + <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> + <listitem><para>CONFIG_KGDB=y</para></listitem> + <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> + <listitem><para>CONFIG_KGDB_KDB=y</para></listitem> + <listitem><para>CONFIG_KDB_KEYBOARD=y</para></listitem> + </itemizedlist> + </para> + </sect1> + </chapter> + <chapter id="kgdbKernelArgs"> + <title>Kernel Debugger Boot Arguments</title> + <para>This section describes the various runtime kernel + parameters that affect the configuration of the kernel debugger. + The following chapter covers using kdb and kgdb as well as + providing some examples of the configuration parameters.</para> + <sect1 id="kgdboc"> + <title>Kernel parameter: kgdboc</title> + <para>The kgdboc driver was originally an abbreviation meant to + stand for "kgdb over console". Today it is the primary mechanism + to configure how to communicate from gdb to kgdb as well as the + devices you want to use to interact with the kdb shell. + </para> + <para>For kgdb/gdb, kgdboc is designed to work with a single serial + port. It is intended to cover the circumstance where you want to + use a serial console as your primary console as well as using it to + perform kernel debugging. It is also possible to use kgdb on a + serial port which is not designated as a system console. Kgdboc + may be configured as a kernel built-in or a kernel loadable module. + You can only make use of <constant>kgdbwait</constant> and early + debugging if you build kgdboc into the kernel as a built-in. + </para> + <para>Optionally you can elect to activate kms (Kernel Mode + Setting) integration. When you use kms with kgdboc and you have a + video driver that has atomic mode setting hooks, it is possible to + enter the debugger on the graphics console. When the kernel + execution is resumed, the previous graphics mode will be restored. + This integration can serve as a useful tool to aid in diagnosing + crashes or doing analysis of memory with kdb while allowing the + full graphics console applications to run. + </para> + <sect2 id="kgdbocArgs"> + <title>kgdboc arguments</title> + <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para> + <para>The order listed above must be observed if you use any of the + optional configurations together. + </para> + <para>Abbreviations: + <itemizedlist> + <listitem><para>kms = Kernel Mode Setting</para></listitem> + <listitem><para>kbd = Keyboard</para></listitem> + </itemizedlist> + </para> + <para>You can configure kgdboc to use the keyboard, and/or a serial + device depending on if you are using kdb and/or kgdb, in one of the + following scenarios. The order listed above must be observed if + you use any of the optional configurations together. Using kms + + only gdb is generally not a useful combination.</para> + <sect3 id="kgdbocArgs1"> + <title>Using loadable module or built-in</title> + <para> + <orderedlist> + <listitem><para>As a kernel built-in:</para> + <para>Use the kernel boot argument: <constant>kgdboc=<tty-device>,[baud]</constant></para></listitem> + <listitem> + <para>As a kernel loadable module:</para> + <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> + <para>Here are two examples of how you might format the kgdboc + string. The first is for an x86 target using the first serial port. + The second example is for the ARM Versatile AB using the second + serial port. + <orderedlist> + <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> + <listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem> + </orderedlist> + </para> + </listitem> + </orderedlist></para> + </sect3> + <sect3 id="kgdbocArgs2"> + <title>Configure kgdboc at runtime with sysfs</title> + <para>At run time you can enable or disable kgdboc by echoing a + parameters into the sysfs. Here are two examples:</para> + <orderedlist> + <listitem><para>Enable kgdboc on ttyS0</para> + <para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + <listitem><para>Disable kgdboc</para> + <para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </orderedlist> + <para>NOTE: You do not need to specify the baud if you are + configuring the console on tty which is already configured or + open.</para> + </sect3> + <sect3 id="kgdbocArgs3"> + <title>More examples</title> + <para>You can configure kgdboc to use the keyboard, and/or a serial device + depending on if you are using kdb and/or kgdb, in one of the + following scenarios. + <orderedlist> + <listitem><para>kdb and kgdb over only a serial port</para> + <para><constant>kgdboc=<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb and kgdb with keyboard and a serial port</para> + <para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para> + <para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para> + </listitem> + <listitem><para>kdb with a keyboard</para> + <para><constant>kgdboc=kbd</constant></para> + </listitem> + <listitem><para>kdb with kernel mode setting</para> + <para><constant>kgdboc=kms,kbd</constant></para> + </listitem> + <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para> + <para><constant>kgdboc=kms,kbd,ttyS0,115200</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 program. + A console proxy has a separate TCP port for the debugger and a separate + TCP port for the "human" console. The proxy can take care of sending + the sysrq-g for you. + </para> + <para>When using kgdboc with no debugger proxy, you can end up + connecting the debugger at 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 + this 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> + </sect3> + </sect2> + </sect1> + <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 if 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 allows when you use this option. If you build the + kgdb I/O driver as a loadable kernel module kgdbwait will not do + anything. + </para> + </sect1> + <sect1 id="kgdbcon"> + <title>Kernel parameter: kgdbcon</title> + <para> The kgdbcon feature allows you to see printk() messages + inside gdb while gdb is connected to the kernel. Kdb does not make + use of the kgdbcon feature. + </para> + <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 I/O 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: You cannot use kgdboc + kgdbcon on a tty that is an + active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant> + </para> + <para>It is possible to use this option with kgdboc on a tty that is not a system console. + </para> + </sect1> + <sect1 id="kgdbreboot"> + <title>Run time parameter: kgdbreboot</title> + <para> The kgdbreboot feature allows you to change how the debugger + deals with the reboot notification. You have 3 choices for the + behavior. The default behavior is always set to 0.</para> + <orderedlist> + <listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Ignore the reboot notification entirely.</para> + </listitem> + <listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Send the detach message to any attached debugger client.</para> + </listitem> + <listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Enter the debugger on reboot notify.</para> + </listitem> + </orderedlist> + </sect1> + </chapter> + <chapter id="usingKDB"> + <title>Using kdb</title> + <para> + </para> + <sect1 id="quickKDBserial"> + <title>Quick start for kdb on a serial port</title> + <para>This is a quick example of how to use kdb.</para> + <para><orderedlist> + <listitem><para>Configure kgdboc at boot using kernel parameters: + <itemizedlist> + <listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console: + <itemizedlist> + <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using minicom 2.2</para> + <para>Press: <constant>Control-a</constant></para> + <para>Press: <constant>f</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> + <para>Press: <constant>Control-]</constant></para> + <para>Type in:<constant>send break</constant></para> + <para>Press: <constant>Enter</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + </itemizedlist> + </listitem> + <listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para> + <para>Some useful commands in kdb include: + <itemizedlist> + <listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem> + <listitem><para>ps -- Displays only the active processes</para></listitem> + <listitem><para>ps A -- Shows all the processes</para></listitem> + <listitem><para>summary -- Shows kernel version info and memory usage</para></listitem> + <listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem> + <listitem><para>dmesg -- View the kernel syslog buffer</para></listitem> + <listitem><para>go -- Continue the system</para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>When you are done using kdb you need to consider rebooting the + system or using the "go" command to resuming normal kernel + execution. If you have paused the kernel for a lengthy period of + time, applications that rely on timely networking or anything to do + with real wall clock time could be adversely affected, so you + should take this into consideration when using the kernel + debugger.</para> + </listitem> + </orderedlist></para> + </sect1> + <sect1 id="quickKDBkeyboard"> + <title>Quick start for kdb using a keyboard connected console</title> + <para>This is a quick example of how to use kdb with a keyboard.</para> + <para><orderedlist> + <listitem><para>Configure kgdboc at boot using kernel parameters: + <itemizedlist> + <listitem><para><constant>kgdboc=kbd</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel has booted: + <itemizedlist> + <listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para> + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using a laptop keyboard</para> + <para>Press and hold down: <constant>Alt</constant></para> + <para>Press and hold down: <constant>Fn</constant></para> + <para>Press and release the key with the label: <constant>SysRq</constant></para> + <para>Release: <constant>Fn</constant></para> + <para>Press and release: <constant>g</constant></para> + <para>Release: <constant>Alt</constant></para> + </listitem> + <listitem><para>Example using a PS/2 101-key keyboard</para> + <para>Press and hold down: <constant>Alt</constant></para> + <para>Press and release the key with the label: <constant>SysRq</constant></para> + <para>Press and release: <constant>g</constant></para> + <para>Release: <constant>Alt</constant></para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para> + </listitem> + </orderedlist></para> + </sect1> + </chapter> + <chapter id="EnableKGDB"> + <title>Using kgdb / gdb</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 kgdb I/O 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 to unconfigure a kgdb I/O driver. + </para> + <sect1 id="ConnectingGDB"> + <title>Connecting with gdb to a serial port</title> + <orderedlist> + <listitem><para>Configure kgdboc</para> + <para>Configure kgdboc at boot using kernel parameters: + <itemizedlist> + <listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem> + </itemizedlist></para> + <para>OR</para> + <para>Configure kgdboc after the kernel has booted: + <itemizedlist> + <listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem> + </itemizedlist></para> + </listitem> + <listitem> + <para>Stop kernel execution (break into the debugger)</para> + <para>In order to connect to gdb via kgdboc, the kernel must + first be stopped. There are several ways to stop the kernel which + include using kgdbwait as a boot argument, via a sysrq-g, or running + the kernel until it takes an exception where it waits for the + debugger to attach. + <itemizedlist> + <listitem><para>When logged in as root or with a super user session you can run:</para> + <para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem> + <listitem><para>Example using minicom 2.2</para> + <para>Press: <constant>Control-a</constant></para> + <para>Press: <constant>f</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + <listitem><para>When you have telneted to a terminal server that supports sending a remote break</para> + <para>Press: <constant>Control-]</constant></para> + <para>Type in:<constant>send break</constant></para> + <para>Press: <constant>Enter</constant></para> + <para>Press: <constant>g</constant></para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>Connect from gdb</para> + <para> + Example (using a directly connected 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> + </listitem> + </orderedlist> + <para>Remember if you continue in gdb, and need to "break in" again, + you need to issue an other sysrq-g. It is easy to create a simple + entry point by putting a breakpoint at <constant>sys_sync</constant> + and then you can run "sync" from a shell or script to break into the + debugger.</para> + </sect1> + </chapter> + <chapter id="switchKdbKgdb"> + <title>kgdb and kdb interoperability</title> + <para>It is possible to transition between kdb and kgdb dynamically. + The debug core will remember which you used the last time and + automatically start in the same mode.</para> + <sect1> + <title>Switching between kdb and kgdb</title> + <sect2> + <title>Switching from kgdb to kdb</title> + <para> + There are two ways to switch from kgdb to kdb: you can use gdb to + issue a maintenance packet, or you can blindly type the command $3#33. + Whenever the kernel debugger stops in kgdb mode it will print the + message <constant>KGDB or $3#33 for KDB</constant>. It is important + to note that you have to type the sequence correctly in one pass. + You cannot type a backspace or delete because kgdb will interpret + that as part of the debug stream. + <orderedlist> + <listitem><para>Change from kgdb to kdb by blindly typing:</para> + <para><constant>$3#33</constant></para></listitem> + <listitem><para>Change from kgdb to kdb with gdb</para> + <para><constant>maintenance packet 3</constant></para> + <para>NOTE: Now you must kill gdb. Typically you press control-z and + issue the command: kill -9 %</para></listitem> + </orderedlist> + </para> + </sect2> + <sect2> + <title>Change from kdb to kgdb</title> + <para>There are two ways you can change from kdb to kgdb. You can + manually enter kgdb mode by issuing the kgdb command from the kdb + shell prompt, or you can connect gdb while the kdb shell prompt is + active. The kdb shell looks for the typical first commands that gdb + would issue with the gdb remote protocol and if it sees one of those + commands it automatically changes into kgdb mode.</para> + <orderedlist> + <listitem><para>From kdb issue the command:</para> + <para><constant>kgdb</constant></para> + <para>Now disconnect your terminal program and connect gdb in its place</para></listitem> + <listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem> + </orderedlist> + </sect2> + </sect1> + <sect1> + <title>Running kdb commands from gdb</title> + <para>It is possible to run a limited set of kdb commands from gdb, + using the gdb monitor command. You don't want to execute any of the + run control or breakpoint operations, because it can disrupt the + state of the kernel debugger. You should be using gdb for + breakpoints and run control operations if you have gdb connected. + The more useful commands to run are things like lsmod, dmesg, ps or + possibly some of the memory information commands. To see all the kdb + commands you can run <constant>monitor help</constant>.</para> + <para>Example: + <informalexample><programlisting> +(gdb) monitor ps +1 idle process (state I) and +27 sleeping system daemon (state M) processes suppressed, +use 'ps A' to see all. +Task Addr Pid Parent [*] cpu State Thread Command + +0xc78291d0 1 0 0 0 S 0xc7829404 init +0xc7954150 942 1 0 0 S 0xc7954384 dropbear +0xc78789c0 944 1 0 0 S 0xc7878bf4 sh +(gdb) + </programlisting></informalexample> + </para> + </sect1> + </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>Kernel Debugger Internals</title> + <sect1 id="kgdbArchitecture"> + <title>Architecture Specifics</title> + <para> + The kernel debugger is organized into a number of components: + <orderedlist> + <listitem><para>The debug core</para> + <para> + The debug core is found in kernel/debugger/debug_core.c. It contains: + <itemizedlist> + <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> + <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> + <listitem><para>The structures and callback API for atomic kernel mode setting.</para> + <para>NOTE: kgdboc is where the kms callbacks are invoked.</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>gdbstub frontend (aka kgdb)</para> + <para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para> + <itemizedlist> + <listitem><para>All the logic to implement the gdb serial protocol</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>kdb frontend</para> + <para>The kdb debugger shell is broken down into a number of + components. The kdb core is located in kernel/debug/kdb. There + are a number of helper functions in some of the other kernel + components to make it possible for kdb to examine and report + information about the kernel without taking locks that could + cause a kernel deadlock. The kdb core contains implements the following functionality.</para> + <itemizedlist> + <listitem><para>A simple shell</para></listitem> + <listitem><para>The kdb core command set</para></listitem> + <listitem><para>A registration API to register additional kdb shell commands.</para> + <itemizedlist> + <listitem><para>A good example of a self-contained kdb module + is the "ftdump" command for dumping the ftrace buffer. See: + kernel/trace/trace_kdb.c</para></listitem> + <listitem><para>For an example of how to dynamically register + a new kdb command you can build the kdb_hello.ko kernel module + from samples/kdb/kdb_hello.c. To build this example you can + set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel + config. Later run "modprobe kdb_hello" and the next time you + enter the kdb shell, you can run the "hello" + command.</para></listitem> + </itemizedlist></listitem> + <listitem><para>The implementation for kdb_printf() which + emits messages directly to I/O drivers, bypassing the kernel + log.</para></listitem> + <listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>kgdb I/O driver</para> + <para> + Each kgdb I/O driver has to provide an implementation for the following: + <itemizedlist> + <listitem><para>configuration via built-in 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 + watchdog 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> + </listitem> + <listitem> + <para> + BUFMAX: The size in bytes of the buffer GDB will read into. + This must be larger than NUMREGBYTES. + </para> + </listitem> + <listitem> + <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> + <sect2> + <title>kgdboc and uarts</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" + to which the tty driver is attached. In the initial + implementation of kgdboc 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 callback in the serial + core which in turn uses the callback in the UART driver.</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 likely + going to mean pressing the reset button. + </para> + </sect2> + <sect2 id="kgdbocKbd"> + <title>kgdboc and keyboards</title> + <para>The kgdboc driver contains logic to configure communications + with an attached keyboard. The keyboard infrastructure is only + compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the + kernel configuration.</para> + <para>The core polled keyboard driver driver for PS/2 type keyboards + is in drivers/char/kdb_keyboard.c. This driver is hooked into the + debug core when kgdboc populates the callback in the array + called <constant>kdb_poll_funcs[]</constant>. The + kdb_get_kbd_char() is the top-level function which polls hardware + for single character input. + </para> + </sect2> + <sect2 id="kgdbocKms"> + <title>kgdboc and kms</title> + <para>The kgdboc driver contains logic to request the graphics + display to switch to a text context when you are using + "kgdboc=kms,kbd", provided that you have a video driver which has a + frame buffer console and atomic kernel mode setting support.</para> + <para> + Every time the kernel + debugger is entered it calls kgdboc_pre_exp_handler() which in turn + calls con_debug_enter() in the virtual console layer. On resuming kernel + execution, the kernel debugger calls kgdboc_post_exp_handler() which + in turn calls con_debug_leave().</para> + <para>Any video driver that wants to be compatible with the kernel + debugger and the atomic kms callbacks must implement the + mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations. + For the fb_debug_enter and fb_debug_leave the option exists to use + the generic drm fb helper functions or implement something custom for + the hardware. The following example shows the initialization of the + .mode_set_base_atomic operation in + drivers/gpu/drm/i915/intel_display.c: + <informalexample> + <programlisting> +static const struct drm_crtc_helper_funcs intel_helper_funcs = { +[...] + .mode_set_base_atomic = intel_pipe_set_base_atomic, +[...] +}; + </programlisting> + </informalexample> + </para> + <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in + drivers/gpu/drm/i915/intel_fb.c: + <informalexample> + <programlisting> +static struct fb_ops intelfb_ops = { +[...] + .fb_debug_enter = drm_fb_helper_debug_enter, + .fb_debug_leave = drm_fb_helper_debug_leave, +[...] +}; + </programlisting> + </informalexample> + </para> + </sect2> + </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> + In Jan 2010 this document was updated to include kdb. + <itemizedlist> + <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem> + </itemizedlist> + </para> + </chapter> +</book> +
diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl new file mode 100644 index 0000000..d7fcdc5 --- /dev/null +++ b/Documentation/DocBook/libata.tmpl
@@ -0,0 +1,1625 @@ +<?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="libataDevGuide"> + <bookinfo> + <title>libATA Developer's Guide</title> + + <authorgroup> + <author> + <firstname>Jeff</firstname> + <surname>Garzik</surname> + </author> + </authorgroup> + + <copyright> + <year>2003-2006</year> + <holder>Jeff Garzik</holder> + </copyright> + + <legalnotice> + <para> + The contents of this file are subject to the Open + Software License version 1.1 that can be found at + <ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink> + and is included herein by reference. + </para> + + <para> + Alternatively, the contents of this file may be used under the terms + of the GNU General Public License version 2 (the "GPL") as distributed + in the kernel source COPYING file, in which case the provisions of + the GPL are applicable instead of the above. If you wish to allow + the use of your version of this file only under the terms of the + GPL and not to allow others to use your version of this file under + the OSL, indicate your decision by deleting the provisions above and + replace them with the notice and other provisions required by the GPL. + If you do not delete the provisions above, a recipient may use your + version of this file under either the OSL or the GPL. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="libataIntroduction"> + <title>Introduction</title> + <para> + libATA is a library used inside the Linux kernel to support ATA host + controllers and devices. libATA provides an ATA driver API, class + transports for ATA and ATAPI devices, and SCSI<->ATA translation + for ATA devices according to the T10 SAT specification. + </para> + <para> + This Guide documents the libATA driver API, library functions, library + internals, and a couple sample ATA low-level drivers. + </para> + </chapter> + + <chapter id="libataDriverApi"> + <title>libata Driver API</title> + <para> + struct ata_port_operations is defined for every low-level libata + hardware driver, and it controls how the low-level driver + interfaces with the ATA and SCSI layers. + </para> + <para> + FIS-based drivers will hook into the system with ->qc_prep() and + ->qc_issue() high-level hooks. Hardware which behaves in a manner + similar to PCI IDE hardware may utilize several generic helpers, + defining at a bare minimum the bus I/O addresses of the ATA shadow + register blocks. + </para> + <sect1> + <title>struct ata_port_operations</title> + + <sect2><title>Disable ATA port</title> + <programlisting> +void (*port_disable) (struct ata_port *); + </programlisting> + + <para> + Called from ata_bus_probe() error path, as well as when + unregistering from the SCSI module (rmmod, hot unplug). + This function should do whatever needs to be done to take the + port out of use. In most cases, ata_port_disable() can be used + as this hook. + </para> + <para> + Called from ata_bus_probe() on a failed probe. + Called from ata_scsi_release(). + </para> + + </sect2> + + <sect2><title>Post-IDENTIFY device configuration</title> + <programlisting> +void (*dev_config) (struct ata_port *, struct ata_device *); + </programlisting> + + <para> + Called after IDENTIFY [PACKET] DEVICE is issued to each device + found. Typically used to apply device-specific fixups prior to + issue of SET FEATURES - XFER MODE, and prior to operation. + </para> + <para> + This entry may be specified as NULL in ata_port_operations. + </para> + + </sect2> + + <sect2><title>Set PIO/DMA mode</title> + <programlisting> +void (*set_piomode) (struct ata_port *, struct ata_device *); +void (*set_dmamode) (struct ata_port *, struct ata_device *); +void (*post_set_mode) (struct ata_port *); +unsigned int (*mode_filter) (struct ata_port *, struct ata_device *, unsigned int); + </programlisting> + + <para> + Hooks called prior to the issue of SET FEATURES - XFER MODE + command. The optional ->mode_filter() hook is called when libata + has built a mask of the possible modes. This is passed to the + ->mode_filter() function which should return a mask of valid modes + after filtering those unsuitable due to hardware limits. It is not + valid to use this interface to add modes. + </para> + <para> + dev->pio_mode and dev->dma_mode are guaranteed to be valid when + ->set_piomode() and when ->set_dmamode() is called. The timings for + any other drive sharing the cable will also be valid at this point. + That is the library records the decisions for the modes of each + drive on a channel before it attempts to set any of them. + </para> + <para> + ->post_set_mode() is + called unconditionally, after the SET FEATURES - XFER MODE + command completes successfully. + </para> + + <para> + ->set_piomode() is always called (if present), but + ->set_dma_mode() is only called if DMA is possible. + </para> + + </sect2> + + <sect2><title>Taskfile read/write</title> + <programlisting> +void (*sff_tf_load) (struct ata_port *ap, struct ata_taskfile *tf); +void (*sff_tf_read) (struct ata_port *ap, struct ata_taskfile *tf); + </programlisting> + + <para> + ->tf_load() is called to load the given taskfile into hardware + registers / DMA buffers. ->tf_read() is called to read the + hardware registers / DMA buffers, to obtain the current set of + taskfile register values. + Most drivers for taskfile-based hardware (PIO or MMIO) use + ata_sff_tf_load() and ata_sff_tf_read() for these hooks. + </para> + + </sect2> + + <sect2><title>PIO data read/write</title> + <programlisting> +void (*sff_data_xfer) (struct ata_device *, unsigned char *, unsigned int, int); + </programlisting> + + <para> +All bmdma-style drivers must implement this hook. This is the low-level +operation that actually copies the data bytes during a PIO data +transfer. +Typically the driver will choose one of ata_sff_data_xfer_noirq(), +ata_sff_data_xfer(), or ata_sff_data_xfer32(). + </para> + + </sect2> + + <sect2><title>ATA command execute</title> + <programlisting> +void (*sff_exec_command)(struct ata_port *ap, struct ata_taskfile *tf); + </programlisting> + + <para> + causes an ATA command, previously loaded with + ->tf_load(), to be initiated in hardware. + Most drivers for taskfile-based hardware use ata_sff_exec_command() + for this hook. + </para> + + </sect2> + + <sect2><title>Per-cmd ATAPI DMA capabilities filter</title> + <programlisting> +int (*check_atapi_dma) (struct ata_queued_cmd *qc); + </programlisting> + + <para> +Allow low-level driver to filter ATA PACKET commands, returning a status +indicating whether or not it is OK to use DMA for the supplied PACKET +command. + </para> + <para> + This hook may be specified as NULL, in which case libata will + assume that atapi dma can be supported. + </para> + + </sect2> + + <sect2><title>Read specific ATA shadow registers</title> + <programlisting> +u8 (*sff_check_status)(struct ata_port *ap); +u8 (*sff_check_altstatus)(struct ata_port *ap); + </programlisting> + + <para> + Reads the Status/AltStatus ATA shadow register from + hardware. On some hardware, reading the Status register has + the side effect of clearing the interrupt condition. + Most drivers for taskfile-based hardware use + ata_sff_check_status() for this hook. + </para> + + </sect2> + + <sect2><title>Write specific ATA shadow register</title> + <programlisting> +void (*sff_set_devctl)(struct ata_port *ap, u8 ctl); + </programlisting> + + <para> + Write the device control ATA shadow register to the hardware. + Most drivers don't need to define this. + </para> + + </sect2> + + <sect2><title>Select ATA device on bus</title> + <programlisting> +void (*sff_dev_select)(struct ata_port *ap, unsigned int device); + </programlisting> + + <para> + Issues the low-level hardware command(s) that causes one of N + hardware devices to be considered 'selected' (active and + available for use) on the ATA bus. This generally has no + meaning on FIS-based devices. + </para> + <para> + Most drivers for taskfile-based hardware use + ata_sff_dev_select() for this hook. + </para> + + </sect2> + + <sect2><title>Private tuning method</title> + <programlisting> +void (*set_mode) (struct ata_port *ap); + </programlisting> + + <para> + By default libata performs drive and controller tuning in + accordance with the ATA timing rules and also applies blacklists + and cable limits. Some controllers need special handling and have + custom tuning rules, typically raid controllers that use ATA + commands but do not actually do drive timing. + </para> + + <warning> + <para> + This hook should not be used to replace the standard controller + tuning logic when a controller has quirks. Replacing the default + tuning logic in that case would bypass handling for drive and + bridge quirks that may be important to data reliability. If a + controller needs to filter the mode selection it should use the + mode_filter hook instead. + </para> + </warning> + + </sect2> + + <sect2><title>Control PCI IDE BMDMA engine</title> + <programlisting> +void (*bmdma_setup) (struct ata_queued_cmd *qc); +void (*bmdma_start) (struct ata_queued_cmd *qc); +void (*bmdma_stop) (struct ata_port *ap); +u8 (*bmdma_status) (struct ata_port *ap); + </programlisting> + + <para> +When setting up an IDE BMDMA transaction, these hooks arm +(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop) +the hardware's DMA engine. ->bmdma_status is used to read the standard +PCI IDE DMA Status register. + </para> + + <para> +These hooks are typically either no-ops, or simply not implemented, in +FIS-based drivers. + </para> + <para> +Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup() +hook. ata_bmdma_setup() will write the pointer to the PRD table to +the IDE PRD Table Address register, enable DMA in the DMA Command +register, and call exec_command() to begin the transfer. + </para> + <para> +Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start() +hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA +Command register. + </para> + <para> +Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop() +hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA +command register. + </para> + <para> +Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook. + </para> + + </sect2> + + <sect2><title>High-level taskfile hooks</title> + <programlisting> +void (*qc_prep) (struct ata_queued_cmd *qc); +int (*qc_issue) (struct ata_queued_cmd *qc); + </programlisting> + + <para> + Higher-level hooks, these two hooks can potentially supercede + several of the above taskfile/DMA engine hooks. ->qc_prep is + called after the buffers have been DMA-mapped, and is typically + used to populate the hardware's DMA scatter-gather table. + Most drivers use the standard ata_qc_prep() helper function, but + more advanced drivers roll their own. + </para> + <para> + ->qc_issue is used to make a command active, once the hardware + and S/G tables have been prepared. IDE BMDMA drivers use the + helper function ata_qc_issue_prot() for taskfile protocol-based + dispatch. More advanced drivers implement their own ->qc_issue. + </para> + <para> + ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and + ->bmdma_start() as necessary to initiate a transfer. + </para> + + </sect2> + + <sect2><title>Exception and probe handling (EH)</title> + <programlisting> +void (*eng_timeout) (struct ata_port *ap); +void (*phy_reset) (struct ata_port *ap); + </programlisting> + + <para> +Deprecated. Use ->error_handler() instead. + </para> + + <programlisting> +void (*freeze) (struct ata_port *ap); +void (*thaw) (struct ata_port *ap); + </programlisting> + + <para> +ata_port_freeze() is called when HSM violations or some other +condition disrupts normal operation of the port. A frozen port +is not allowed to perform any operation until the port is +thawed, which usually follows a successful reset. + </para> + + <para> +The optional ->freeze() callback can be used for freezing the port +hardware-wise (e.g. mask interrupt and stop DMA engine). If a +port cannot be frozen hardware-wise, the interrupt handler +must ack and clear interrupts unconditionally while the port +is frozen. + </para> + <para> +The optional ->thaw() callback is called to perform the opposite of ->freeze(): +prepare the port for normal operation once again. Unmask interrupts, +start DMA engine, etc. + </para> + + <programlisting> +void (*error_handler) (struct ata_port *ap); + </programlisting> + + <para> +->error_handler() is a driver's hook into probe, hotplug, and recovery +and other exceptional conditions. The primary responsibility of an +implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set +of EH hooks as arguments: + </para> + + <para> +'prereset' hook (may be NULL) is called during an EH reset, before any other actions +are taken. + </para> + + <para> +'postreset' hook (may be NULL) is called after the EH reset is performed. Based on +existing conditions, severity of the problem, and hardware capabilities, + </para> + + <para> +Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be +called to perform the low-level EH reset. + </para> + + <programlisting> +void (*post_internal_cmd) (struct ata_queued_cmd *qc); + </programlisting> + + <para> +Perform any hardware-specific actions necessary to finish processing +after executing a probe-time or EH-time command via ata_exec_internal(). + </para> + + </sect2> + + <sect2><title>Hardware interrupt handling</title> + <programlisting> +irqreturn_t (*irq_handler)(int, void *, struct pt_regs *); +void (*irq_clear) (struct ata_port *); + </programlisting> + + <para> + ->irq_handler is the interrupt handling routine registered with + the system, by libata. ->irq_clear is called during probe just + before the interrupt handler is registered, to be sure hardware + is quiet. + </para> + <para> + The second argument, dev_instance, should be cast to a pointer + to struct ata_host_set. + </para> + <para> + Most legacy IDE drivers use ata_sff_interrupt() for the + irq_handler hook, which scans all ports in the host_set, + determines which queued command was active (if any), and calls + ata_sff_host_intr(ap,qc). + </para> + <para> + Most legacy IDE drivers use ata_sff_irq_clear() for the + irq_clear() hook, which simply clears the interrupt and error + flags in the DMA status register. + </para> + + </sect2> + + <sect2><title>SATA phy read/write</title> + <programlisting> +int (*scr_read) (struct ata_port *ap, unsigned int sc_reg, + u32 *val); +int (*scr_write) (struct ata_port *ap, unsigned int sc_reg, + u32 val); + </programlisting> + + <para> + Read and write standard SATA phy registers. Currently only used + if ->phy_reset hook called the sata_phy_reset() helper function. + sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE. + </para> + + </sect2> + + <sect2><title>Init and shutdown</title> + <programlisting> +int (*port_start) (struct ata_port *ap); +void (*port_stop) (struct ata_port *ap); +void (*host_stop) (struct ata_host_set *host_set); + </programlisting> + + <para> + ->port_start() is called just after the data structures for each + port are initialized. Typically this is used to alloc per-port + DMA buffers / tables / rings, enable DMA engines, and similar + tasks. Some drivers also use this entry point as a chance to + allocate driver-private memory for ap->private_data. + </para> + <para> + Many drivers use ata_port_start() as this hook or call + it from their own port_start() hooks. ata_port_start() + allocates space for a legacy IDE PRD table and returns. + </para> + <para> + ->port_stop() is called after ->host_stop(). Its sole function + is to release DMA/memory resources, now that they are no longer + actively being used. Many drivers also free driver-private + data from port at this time. + </para> + <para> + ->host_stop() is called after all ->port_stop() calls +have completed. The hook must finalize hardware shutdown, release DMA +and other resources, etc. + This hook may be specified as NULL, in which case it is not called. + </para> + + </sect2> + + </sect1> + </chapter> + + <chapter id="libataEH"> + <title>Error handling</title> + + <para> + This chapter describes how errors are handled under libata. + Readers are advised to read SCSI EH + (Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first. + </para> + + <sect1><title>Origins of commands</title> + <para> + In libata, a command is represented with struct ata_queued_cmd + or qc. qc's are preallocated during port initialization and + repetitively used for command executions. Currently only one + qc is allocated per port but yet-to-be-merged NCQ branch + allocates one for each tag and maps each qc to NCQ tag 1-to-1. + </para> + <para> + libata commands can originate from two sources - libata itself + and SCSI midlayer. libata internal commands are used for + initialization and error handling. All normal blk requests + and commands for SCSI emulation are passed as SCSI commands + through queuecommand callback of SCSI host template. + </para> + </sect1> + + <sect1><title>How commands are issued</title> + + <variablelist> + + <varlistentry><term>Internal commands</term> + <listitem> + <para> + First, qc is allocated and initialized using + ata_qc_new_init(). Although ata_qc_new_init() doesn't + implement any wait or retry mechanism when qc is not + available, internal commands are currently issued only during + initialization and error recovery, so no other command is + active and allocation is guaranteed to succeed. + </para> + <para> + Once allocated qc's taskfile is initialized for the command to + be executed. qc currently has two mechanisms to notify + completion. One is via qc->complete_fn() callback and the + other is completion qc->waiting. qc->complete_fn() callback + is the asynchronous path used by normal SCSI translated + commands and qc->waiting is the synchronous (issuer sleeps in + process context) path used by internal commands. + </para> + <para> + Once initialization is complete, host_set lock is acquired + and the qc is issued. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>SCSI commands</term> + <listitem> + <para> + All libata drivers use ata_scsi_queuecmd() as + hostt->queuecommand callback. scmds can either be simulated + or translated. No qc is involved in processing a simulated + scmd. The result is computed right away and the scmd is + completed. + </para> + <para> + For a translated scmd, ata_qc_new_init() is invoked to + allocate a qc and the scmd is translated into the qc. SCSI + midlayer's completion notification function pointer is stored + into qc->scsidone. + </para> + <para> + qc->complete_fn() callback is used for completion + notification. ATA commands use ata_scsi_qc_complete() while + ATAPI commands use atapi_qc_complete(). Both functions end up + calling qc->scsidone to notify upper layer when the qc is + finished. After translation is completed, the qc is issued + with ata_qc_issue(). + </para> + <para> + Note that SCSI midlayer invokes hostt->queuecommand while + holding host_set lock, so all above occur while holding + host_set lock. + </para> + </listitem> + </varlistentry> + + </variablelist> + </sect1> + + <sect1><title>How commands are processed</title> + <para> + Depending on which protocol and which controller are used, + commands are processed differently. For the purpose of + discussion, a controller which uses taskfile interface and all + standard callbacks is assumed. + </para> + <para> + Currently 6 ATA command protocols are used. They can be + sorted into the following four categories according to how + they are processed. + </para> + + <variablelist> + <varlistentry><term>ATA NO DATA or DMA</term> + <listitem> + <para> + ATA_PROT_NODATA and ATA_PROT_DMA fall into this category. + These types of commands don't require any software + intervention once issued. Device will raise interrupt on + completion. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>ATA PIO</term> + <listitem> + <para> + ATA_PROT_PIO is in this category. libata currently + implements PIO with polling. ATA_NIEN bit is set to turn + off interrupt and pio_task on ata_wq performs polling and + IO. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>ATAPI NODATA or DMA</term> + <listitem> + <para> + ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this + category. packet_task is used to poll BSY bit after + issuing PACKET command. Once BSY is turned off by the + device, packet_task transfers CDB and hands off processing + to interrupt handler. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>ATAPI PIO</term> + <listitem> + <para> + ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set + and, as in ATAPI NODATA or DMA, packet_task submits cdb. + However, after submitting cdb, further processing (data + transfer) is handed off to pio_task. + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1><title>How commands are completed</title> + <para> + Once issued, all qc's are either completed with + ata_qc_complete() or time out. For commands which are handled + by interrupts, ata_host_intr() invokes ata_qc_complete(), and, + for PIO tasks, pio_task invokes ata_qc_complete(). In error + cases, packet_task may also complete commands. + </para> + <para> + ata_qc_complete() does the following. + </para> + + <orderedlist> + + <listitem> + <para> + DMA memory is unmapped. + </para> + </listitem> + + <listitem> + <para> + ATA_QCFLAG_ACTIVE is cleared from qc->flags. + </para> + </listitem> + + <listitem> + <para> + qc->complete_fn() callback is invoked. If the return value of + the callback is not zero. Completion is short circuited and + ata_qc_complete() returns. + </para> + </listitem> + + <listitem> + <para> + __ata_qc_complete() is called, which does + <orderedlist> + + <listitem> + <para> + qc->flags is cleared to zero. + </para> + </listitem> + + <listitem> + <para> + ap->active_tag and qc->tag are poisoned. + </para> + </listitem> + + <listitem> + <para> + qc->waiting is cleared & completed (in that order). + </para> + </listitem> + + <listitem> + <para> + qc is deallocated by clearing appropriate bit in ap->qactive. + </para> + </listitem> + + </orderedlist> + </para> + </listitem> + + </orderedlist> + + <para> + So, it basically notifies upper layer and deallocates qc. One + exception is short-circuit path in #3 which is used by + atapi_qc_complete(). + </para> + <para> + For all non-ATAPI commands, whether it fails or not, almost + the same code path is taken and very little error handling + takes place. A qc is completed with success status if it + succeeded, with failed status otherwise. + </para> + <para> + However, failed ATAPI commands require more handling as + REQUEST SENSE is needed to acquire sense data. If an ATAPI + command fails, ata_qc_complete() is invoked with error status, + which in turn invokes atapi_qc_complete() via + qc->complete_fn() callback. + </para> + <para> + This makes atapi_qc_complete() set scmd->result to + SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As + the sense data is empty but scmd->result is CHECK CONDITION, + SCSI midlayer will invoke EH for the scmd, and returning 1 + makes ata_qc_complete() to return without deallocating the qc. + This leads us to ata_scsi_error() with partially completed qc. + </para> + + </sect1> + + <sect1><title>ata_scsi_error()</title> + <para> + ata_scsi_error() is the current transportt->eh_strategy_handler() + for libata. As discussed above, this will be entered in two + cases - timeout and ATAPI error completion. This function + calls low level libata driver's eng_timeout() callback, the + standard callback for which is ata_eng_timeout(). It checks + if a qc is active and calls ata_qc_timeout() on the qc if so. + Actual error handling occurs in ata_qc_timeout(). + </para> + <para> + If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and + completes the qc. Note that as we're currently in EH, we + cannot call scsi_done. As described in SCSI EH doc, a + recovered scmd should be either retried with + scsi_queue_insert() or finished with scsi_finish_command(). + Here, we override qc->scsidone with scsi_finish_command() and + calls ata_qc_complete(). + </para> + <para> + If EH is invoked due to a failed ATAPI qc, the qc here is + completed but not deallocated. The purpose of this + half-completion is to use the qc as place holder to make EH + code reach this place. This is a bit hackish, but it works. + </para> + <para> + Once control reaches here, the qc is deallocated by invoking + __ata_qc_complete() explicitly. Then, internal qc for REQUEST + SENSE is issued. Once sense data is acquired, scmd is + finished by directly invoking scsi_finish_command() on the + scmd. Note that as we already have completed and deallocated + the qc which was associated with the scmd, we don't need + to/cannot call ata_qc_complete() again. + </para> + + </sect1> + + <sect1><title>Problems with the current EH</title> + + <itemizedlist> + + <listitem> + <para> + Error representation is too crude. Currently any and all + error conditions are represented with ATA STATUS and ERROR + registers. Errors which aren't ATA device errors are treated + as ATA device errors by setting ATA_ERR bit. Better error + descriptor which can properly represent ATA and other + errors/exceptions is needed. + </para> + </listitem> + + <listitem> + <para> + When handling timeouts, no action is taken to make device + forget about the timed out command and ready for new commands. + </para> + </listitem> + + <listitem> + <para> + EH handling via ata_scsi_error() is not properly protected + from usual command processing. On EH entrance, the device is + not in quiescent state. Timed out commands may succeed or + fail any time. pio_task and atapi_task may still be running. + </para> + </listitem> + + <listitem> + <para> + Too weak error recovery. Devices / controllers causing HSM + mismatch errors and other errors quite often require reset to + return to known state. Also, advanced error handling is + necessary to support features like NCQ and hotplug. + </para> + </listitem> + + <listitem> + <para> + ATA errors are directly handled in the interrupt handler and + PIO errors in pio_task. This is problematic for advanced + error handling for the following reasons. + </para> + <para> + First, advanced error handling often requires context and + internal qc execution. + </para> + <para> + Second, even a simple failure (say, CRC error) needs + information gathering and could trigger complex error handling + (say, resetting & reconfiguring). Having multiple code + paths to gather information, enter EH and trigger actions + makes life painful. + </para> + <para> + Third, scattered EH code makes implementing low level drivers + difficult. Low level drivers override libata callbacks. If + EH is scattered over several places, each affected callbacks + should perform its part of error handling. This can be error + prone and painful. + </para> + </listitem> + + </itemizedlist> + </sect1> + </chapter> + + <chapter id="libataExt"> + <title>libata Library</title> +!Edrivers/ata/libata-core.c + </chapter> + + <chapter id="libataInt"> + <title>libata Core Internals</title> +!Idrivers/ata/libata-core.c + </chapter> + + <chapter id="libataScsiInt"> + <title>libata SCSI translation/emulation</title> +!Edrivers/ata/libata-scsi.c +!Idrivers/ata/libata-scsi.c + </chapter> + + <chapter id="ataExceptions"> + <title>ATA errors and exceptions</title> + + <para> + This chapter tries to identify what error/exception conditions exist + for ATA/ATAPI devices and describe how they should be handled in + implementation-neutral way. + </para> + + <para> + The term 'error' is used to describe conditions where either an + explicit error condition is reported from device or a command has + timed out. + </para> + + <para> + The term 'exception' is either used to describe exceptional + conditions which are not errors (say, power or hotplug events), or + to describe both errors and non-error exceptional conditions. Where + explicit distinction between error and exception is necessary, the + term 'non-error exception' is used. + </para> + + <sect1 id="excat"> + <title>Exception categories</title> + <para> + Exceptions are described primarily with respect to legacy + taskfile + bus master IDE interface. If a controller provides + other better mechanism for error reporting, mapping those into + categories described below shouldn't be difficult. + </para> + + <para> + In the following sections, two recovery actions - reset and + reconfiguring transport - are mentioned. These are described + further in <xref linkend="exrec"/>. + </para> + + <sect2 id="excatHSMviolation"> + <title>HSM violation</title> + <para> + This error is indicated when STATUS value doesn't match HSM + requirement during issuing or execution any ATA/ATAPI command. + </para> + + <itemizedlist> + <title>Examples</title> + + <listitem> + <para> + ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying + to issue a command. + </para> + </listitem> + + <listitem> + <para> + !BSY && !DRQ during PIO data transfer. + </para> + </listitem> + + <listitem> + <para> + DRQ on command completion. + </para> + </listitem> + + <listitem> + <para> + !BSY && ERR after CDB transfer starts but before the + last byte of CDB is transferred. ATA/ATAPI standard states + that "The device shall not terminate the PACKET command + with an error before the last byte of the command packet has + been written" in the error outputs description of PACKET + command and the state diagram doesn't include such + transitions. + </para> + </listitem> + + </itemizedlist> + + <para> + In these cases, HSM is violated and not much information + regarding the error can be acquired from STATUS or ERROR + register. IOW, this error can be anything - driver bug, + faulty device, controller and/or cable. + </para> + + <para> + As HSM is violated, reset is necessary to restore known state. + Reconfiguring transport for lower speed might be helpful too + as transmission errors sometimes cause this kind of errors. + </para> + </sect2> + + <sect2 id="excatDevErr"> + <title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title> + + <para> + These are errors detected and reported by ATA/ATAPI devices + indicating device problems. For this type of errors, STATUS + and ERROR register values are valid and describe error + condition. Note that some of ATA bus errors are detected by + ATA/ATAPI devices and reported using the same mechanism as + device errors. Those cases are described later in this + section. + </para> + + <para> + For ATA commands, this type of errors are indicated by !BSY + && ERR during command execution and on completion. + </para> + + <para>For ATAPI commands,</para> + + <itemizedlist> + + <listitem> + <para> + !BSY && ERR && ABRT right after issuing PACKET + indicates that PACKET command is not supported and falls in + this category. + </para> + </listitem> + + <listitem> + <para> + !BSY && ERR(==CHK) && !ABRT after the last + byte of CDB is transferred indicates CHECK CONDITION and + doesn't fall in this category. + </para> + </listitem> + + <listitem> + <para> + !BSY && ERR(==CHK) && ABRT after the last byte + of CDB is transferred *probably* indicates CHECK CONDITION and + doesn't fall in this category. + </para> + </listitem> + + </itemizedlist> + + <para> + Of errors detected as above, the followings are not ATA/ATAPI + device errors but ATA bus errors and should be handled + according to <xref linkend="excatATAbusErr"/>. + </para> + + <variablelist> + + <varlistentry> + <term>CRC error during data transfer</term> + <listitem> + <para> + This is indicated by ICRC bit in the ERROR register and + means that corruption occurred during data transfer. Up to + ATA/ATAPI-7, the standard specifies that this bit is only + applicable to UDMA transfers but ATA/ATAPI-8 draft revision + 1f says that the bit may be applicable to multiword DMA and + PIO. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ABRT error during data transfer or on completion</term> + <listitem> + <para> + Up to ATA/ATAPI-7, the standard specifies that ABRT could be + set on ICRC errors and on cases where a device is not able + to complete a command. Combined with the fact that MWDMA + and PIO transfer errors aren't allowed to use ICRC bit up to + ATA/ATAPI-7, it seems to imply that ABRT bit alone could + indicate transfer errors. + </para> + <para> + However, ATA/ATAPI-8 draft revision 1f removes the part + that ICRC errors can turn on ABRT. So, this is kind of + gray area. Some heuristics are needed here. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + ATA/ATAPI device errors can be further categorized as follows. + </para> + + <variablelist> + + <varlistentry> + <term>Media errors</term> + <listitem> + <para> + This is indicated by UNC bit in the ERROR register. ATA + devices reports UNC error only after certain number of + retries cannot recover the data, so there's nothing much + else to do other than notifying upper layer. + </para> + <para> + READ and WRITE commands report CHS or LBA of the first + failed sector but ATA/ATAPI standard specifies that the + amount of transferred data on error completion is + indeterminate, so we cannot assume that sectors preceding + the failed sector have been transferred and thus cannot + complete those sectors successfully as SCSI does. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Media changed / media change requested error</term> + <listitem> + <para> + <<TODO: fill here>> + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Address error</term> + <listitem> + <para> + This is indicated by IDNF bit in the ERROR register. + Report to upper layer. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Other errors</term> + <listitem> + <para> + This can be invalid command or parameter indicated by ABRT + ERROR bit or some other error condition. Note that ABRT + bit can indicate a lot of things including ICRC and Address + errors. Heuristics needed. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + Depending on commands, not all STATUS/ERROR bits are + applicable. These non-applicable bits are marked with + "na" in the output descriptions but up to ATA/ATAPI-7 + no definition of "na" can be found. However, + ATA/ATAPI-8 draft revision 1f describes "N/A" as + follows. + </para> + + <blockquote> + <variablelist> + <varlistentry><term>3.2.3.3a N/A</term> + <listitem> + <para> + A keyword the indicates a field has no defined value in + this standard and should not be checked by the host or + device. N/A fields should be cleared to zero. + </para> + </listitem> + </varlistentry> + </variablelist> + </blockquote> + + <para> + So, it seems reasonable to assume that "na" bits are + cleared to zero by devices and thus need no explicit masking. + </para> + + </sect2> + + <sect2 id="excatATAPIcc"> + <title>ATAPI device CHECK CONDITION</title> + + <para> + ATAPI device CHECK CONDITION error is indicated by set CHK bit + (ERR bit) in the STATUS register after the last byte of CDB is + transferred for a PACKET command. For this kind of errors, + sense data should be acquired to gather information regarding + the errors. REQUEST SENSE packet command should be used to + acquire sense data. + </para> + + <para> + Once sense data is acquired, this type of errors can be + handled similarly to other SCSI errors. Note that sense data + may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR + && ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such + cases, the error should be considered as an ATA bus error and + handled according to <xref linkend="excatATAbusErr"/>. + </para> + + </sect2> + + <sect2 id="excatNCQerr"> + <title>ATA device error (NCQ)</title> + + <para> + NCQ command error is indicated by cleared BSY and set ERR bit + during NCQ command phase (one or more NCQ commands + outstanding). Although STATUS and ERROR registers will + contain valid values describing the error, READ LOG EXT is + required to clear the error condition, determine which command + has failed and acquire more information. + </para> + + <para> + READ LOG EXT Log Page 10h reports which tag has failed and + taskfile register values describing the error. With this + information the failed command can be handled as a normal ATA + command error as in <xref linkend="excatDevErr"/> and all + other in-flight commands must be retried. Note that this + retry should not be counted - it's likely that commands + retried this way would have completed normally if it were not + for the failed command. + </para> + + <para> + Note that ATA bus errors can be reported as ATA device NCQ + errors. This should be handled as described in <xref + linkend="excatATAbusErr"/>. + </para> + + <para> + If READ LOG EXT Log Page 10h fails or reports NQ, we're + thoroughly screwed. This condition should be treated + according to <xref linkend="excatHSMviolation"/>. + </para> + + </sect2> + + <sect2 id="excatATAbusErr"> + <title>ATA bus error</title> + + <para> + ATA bus error means that data corruption occurred during + transmission over ATA bus (SATA or PATA). This type of errors + can be indicated by + </para> + + <itemizedlist> + + <listitem> + <para> + ICRC or ABRT error as described in <xref linkend="excatDevErr"/>. + </para> + </listitem> + + <listitem> + <para> + Controller-specific error completion with error information + indicating transmission error. + </para> + </listitem> + + <listitem> + <para> + On some controllers, command timeout. In this case, there may + be a mechanism to determine that the timeout is due to + transmission error. + </para> + </listitem> + + <listitem> + <para> + Unknown/random errors, timeouts and all sorts of weirdities. + </para> + </listitem> + + </itemizedlist> + + <para> + As described above, transmission errors can cause wide variety + of symptoms ranging from device ICRC error to random device + lockup, and, for many cases, there is no way to tell if an + error condition is due to transmission error or not; + therefore, it's necessary to employ some kind of heuristic + when dealing with errors and timeouts. For example, + encountering repetitive ABRT errors for known supported + command is likely to indicate ATA bus error. + </para> + + <para> + Once it's determined that ATA bus errors have possibly + occurred, lowering ATA bus transmission speed is one of + actions which may alleviate the problem. See <xref + linkend="exrecReconf"/> for more information. + </para> + + </sect2> + + <sect2 id="excatPCIbusErr"> + <title>PCI bus error</title> + + <para> + Data corruption or other failures during transmission over PCI + (or other system bus). For standard BMDMA, this is indicated + by Error bit in the BMDMA Status register. This type of + errors must be logged as it indicates something is very wrong + with the system. Resetting host controller is recommended. + </para> + + </sect2> + + <sect2 id="excatLateCompletion"> + <title>Late completion</title> + + <para> + This occurs when timeout occurs and the timeout handler finds + out that the timed out command has completed successfully or + with error. This is usually caused by lost interrupts. This + type of errors must be logged. Resetting host controller is + recommended. + </para> + + </sect2> + + <sect2 id="excatUnknown"> + <title>Unknown error (timeout)</title> + + <para> + This is when timeout occurs and the command is still + processing or the host and device are in unknown state. When + this occurs, HSM could be in any valid or invalid state. To + bring the device to known state and make it forget about the + timed out command, resetting is necessary. The timed out + command may be retried. + </para> + + <para> + Timeouts can also be caused by transmission errors. Refer to + <xref linkend="excatATAbusErr"/> for more details. + </para> + + </sect2> + + <sect2 id="excatHoplugPM"> + <title>Hotplug and power management exceptions</title> + + <para> + <<TODO: fill here>> + </para> + + </sect2> + + </sect1> + + <sect1 id="exrec"> + <title>EH recovery actions</title> + + <para> + This section discusses several important recovery actions. + </para> + + <sect2 id="exrecClr"> + <title>Clearing error condition</title> + + <para> + Many controllers require its error registers to be cleared by + error handler. Different controllers may have different + requirements. + </para> + + <para> + For SATA, it's strongly recommended to clear at least SError + register during error handling. + </para> + </sect2> + + <sect2 id="exrecRst"> + <title>Reset</title> + + <para> + During EH, resetting is necessary in the following cases. + </para> + + <itemizedlist> + + <listitem> + <para> + HSM is in unknown or invalid state + </para> + </listitem> + + <listitem> + <para> + HBA is in unknown or invalid state + </para> + </listitem> + + <listitem> + <para> + EH needs to make HBA/device forget about in-flight commands + </para> + </listitem> + + <listitem> + <para> + HBA/device behaves weirdly + </para> + </listitem> + + </itemizedlist> + + <para> + Resetting during EH might be a good idea regardless of error + condition to improve EH robustness. Whether to reset both or + either one of HBA and device depends on situation but the + following scheme is recommended. + </para> + + <itemizedlist> + + <listitem> + <para> + When it's known that HBA is in ready state but ATA/ATAPI + device is in unknown state, reset only device. + </para> + </listitem> + + <listitem> + <para> + If HBA is in unknown state, reset both HBA and device. + </para> + </listitem> + + </itemizedlist> + + <para> + HBA resetting is implementation specific. For a controller + complying to taskfile/BMDMA PCI IDE, stopping active DMA + transaction may be sufficient iff BMDMA state is the only HBA + context. But even mostly taskfile/BMDMA PCI IDE complying + controllers may have implementation specific requirements and + mechanism to reset themselves. This must be addressed by + specific drivers. + </para> + + <para> + OTOH, ATA/ATAPI standard describes in detail ways to reset + ATA/ATAPI devices. + </para> + + <variablelist> + + <varlistentry><term>PATA hardware reset</term> + <listitem> + <para> + This is hardware initiated device reset signalled with + asserted PATA RESET- signal. There is no standard way to + initiate hardware reset from software although some + hardware provides registers that allow driver to directly + tweak the RESET- signal. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>Software reset</term> + <listitem> + <para> + This is achieved by turning CONTROL SRST bit on for at + least 5us. Both PATA and SATA support it but, in case of + SATA, this may require controller-specific support as the + second Register FIS to clear SRST should be transmitted + while BSY bit is still set. Note that on PATA, this resets + both master and slave devices on a channel. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term> + <listitem> + <para> + Although ATA/ATAPI standard doesn't describe exactly, EDD + implies some level of resetting, possibly similar level + with software reset. Host-side EDD protocol can be handled + with normal command processing and most SATA controllers + should be able to handle EDD's just like other commands. + As in software reset, EDD affects both devices on a PATA + bus. + </para> + <para> + Although EDD does reset devices, this doesn't suit error + handling as EDD cannot be issued while BSY is set and it's + unclear how it will act when device is in unknown/weird + state. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>ATAPI DEVICE RESET command</term> + <listitem> + <para> + This is very similar to software reset except that reset + can be restricted to the selected device without affecting + the other device sharing the cable. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>SATA phy reset</term> + <listitem> + <para> + This is the preferred way of resetting a SATA device. In + effect, it's identical to PATA hardware reset. Note that + this can be done with the standard SCR Control register. + As such, it's usually easier to implement than software + reset. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + One more thing to consider when resetting devices is that + resetting clears certain configuration parameters and they + need to be set to their previous or newly adjusted values + after reset. + </para> + + <para> + Parameters affected are. + </para> + + <itemizedlist> + + <listitem> + <para> + CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used) + </para> + </listitem> + + <listitem> + <para> + Parameters set with SET FEATURES including transfer mode setting + </para> + </listitem> + + <listitem> + <para> + Block count set with SET MULTIPLE MODE + </para> + </listitem> + + <listitem> + <para> + Other parameters (SET MAX, MEDIA LOCK...) + </para> + </listitem> + + </itemizedlist> + + <para> + ATA/ATAPI standard specifies that some parameters must be + maintained across hardware or software reset, but doesn't + strictly specify all of them. Always reconfiguring needed + parameters after reset is required for robustness. Note that + this also applies when resuming from deep sleep (power-off). + </para> + + <para> + Also, ATA/ATAPI standard requires that IDENTIFY DEVICE / + IDENTIFY PACKET DEVICE is issued after any configuration + parameter is updated or a hardware reset and the result used + for further operation. OS driver is required to implement + revalidation mechanism to support this. + </para> + + </sect2> + + <sect2 id="exrecReconf"> + <title>Reconfigure transport</title> + + <para> + For both PATA and SATA, a lot of corners are cut for cheap + connectors, cables or controllers and it's quite common to see + high transmission error rate. This can be mitigated by + lowering transmission speed. + </para> + + <para> + The following is a possible scheme Jeff Garzik suggested. + </para> + + <blockquote> + <para> + If more than $N (3?) transmission errors happen in 15 minutes, + </para> + <itemizedlist> + <listitem> + <para> + if SATA, decrease SATA PHY speed. if speed cannot be decreased, + </para> + </listitem> + <listitem> + <para> + decrease UDMA xfer speed. if at UDMA0, switch to PIO4, + </para> + </listitem> + <listitem> + <para> + decrease PIO xfer speed. if at PIO3, complain, but continue + </para> + </listitem> + </itemizedlist> + </blockquote> + + </sect2> + + </sect1> + + </chapter> + + <chapter id="PiixInt"> + <title>ata_piix Internals</title> +!Idrivers/ata/ata_piix.c + </chapter> + + <chapter id="SILInt"> + <title>sata_sil Internals</title> +!Idrivers/ata/sata_sil.c + </chapter> + + <chapter id="libataThanks"> + <title>Thanks</title> + <para> + The bulk of the ATA knowledge comes thanks to long conversations with + Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA + and SCSI specifications. + </para> + <para> + Thanks to Alan Cox for pointing out similarities + between SATA and SCSI, and in general for motivation to hack on + libata. + </para> + <para> + libata's device detection + method, ata_pio_devchk, and in general all the early probing was + based on extensive study of Hale Landis's probe/reset code in his + ATADRVR driver (www.ata-atapi.com). + </para> + </chapter> + +</book>
diff --git a/Documentation/DocBook/librs.tmpl b/Documentation/DocBook/librs.tmpl new file mode 100644 index 0000000..94f2136 --- /dev/null +++ b/Documentation/DocBook/librs.tmpl
@@ -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>
diff --git a/Documentation/DocBook/lsm.tmpl b/Documentation/DocBook/lsm.tmpl new file mode 100644 index 0000000..fe7664c --- /dev/null +++ b/Documentation/DocBook/lsm.tmpl
@@ -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>
diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl new file mode 100644 index 0000000..b442921 --- /dev/null +++ b/Documentation/DocBook/mtdnand.tmpl
@@ -0,0 +1,1291 @@ +<?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="MTD-NAND-Guide"> + <bookinfo> + <title>MTD NAND Driver 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 NAND driver supports almost all NAND and AG-AND based + chips and connects them to the Memory Technology Devices (MTD) + subsystem of the Linux Kernel. + </para> + <para> + This documentation is provided for developers who want to implement + board drivers or filesystem drivers suitable for NAND devices. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + None. + </para> + </chapter> + + <chapter id="dochints"> + <title>Documentation hints</title> + <para> + The function and structure docs are autogenerated. Each function and + struct member has a short description which is marked with an [XXX] identifier. + The following chapters explain the meaning of those identifiers. + </para> + <sect1 id="Function_identifiers_XXX"> + <title>Function identifiers [XXX]</title> + <para> + The functions are marked with [XXX] identifiers in the short + comment. The identifiers explain the usage and scope of the + functions. Following identifiers are used: + </para> + <itemizedlist> + <listitem><para> + [MTD Interface]</para><para> + These functions provide the interface to the MTD kernel API. + They are not replaceable and provide functionality + which is complete hardware independent. + </para></listitem> + <listitem><para> + [NAND Interface]</para><para> + These functions are exported and provide the interface to the NAND kernel API. + </para></listitem> + <listitem><para> + [GENERIC]</para><para> + Generic functions are not replaceable and provide functionality + which is complete hardware independent. + </para></listitem> + <listitem><para> + [DEFAULT]</para><para> + Default functions provide hardware related functionality which is suitable + for most of the implementations. These functions can be replaced by the + board driver if necessary. Those functions are called via pointers in the + NAND chip description structure. The board driver can set the functions which + should be replaced by board dependent functions before calling nand_scan(). + If the function pointer is NULL on entry to nand_scan() then the pointer + is set to the default function which is suitable for the detected chip type. + </para></listitem> + </itemizedlist> + </sect1> + <sect1 id="Struct_member_identifiers_XXX"> + <title>Struct member identifiers [XXX]</title> + <para> + The struct members are marked with [XXX] identifiers in the + comment. The identifiers explain the usage and scope of the + members. Following identifiers are used: + </para> + <itemizedlist> + <listitem><para> + [INTERN]</para><para> + These members are for NAND driver internal use only and must not be + modified. Most of these values are calculated from the chip geometry + information which is evaluated during nand_scan(). + </para></listitem> + <listitem><para> + [REPLACEABLE]</para><para> + Replaceable members hold hardware related functions which can be + provided by the board driver. The board driver can set the functions which + should be replaced by board dependent functions before calling nand_scan(). + If the function pointer is NULL on entry to nand_scan() then the pointer + is set to the default function which is suitable for the detected chip type. + </para></listitem> + <listitem><para> + [BOARDSPECIFIC]</para><para> + Board specific members hold hardware related information which must + be provided by the board driver. The board driver must set the function + pointers and datafields before calling nand_scan(). + </para></listitem> + <listitem><para> + [OPTIONAL]</para><para> + Optional members can hold information relevant for the board driver. The + generic NAND driver code does not use this information. + </para></listitem> + </itemizedlist> + </sect1> + </chapter> + + <chapter id="basicboarddriver"> + <title>Basic board driver</title> + <para> + For most boards it will be sufficient to provide just the + basic functions and fill out some really board dependent + members in the nand chip description structure. + </para> + <sect1 id="Basic_defines"> + <title>Basic defines</title> + <para> + At least you have to provide a nand_chip structure + and a storage for the ioremap'ed chip address. + You can allocate the nand_chip structure using + kmalloc or you can allocate it statically. + The NAND chip structure embeds an mtd structure + which will be registered to the MTD subsystem. + You can extract a pointer to the mtd structure + from a nand_chip pointer using the nand_to_mtd() + helper. + </para> + <para> + Kmalloc based example + </para> + <programlisting> +static struct mtd_info *board_mtd; +static void __iomem *baseaddr; + </programlisting> + <para> + Static example + </para> + <programlisting> +static struct nand_chip board_chip; +static void __iomem *baseaddr; + </programlisting> + </sect1> + <sect1 id="Partition_defines"> + <title>Partition defines</title> + <para> + If you want to divide your device into partitions, then + define a partitioning scheme suitable to your board. + </para> + <programlisting> +#define NUM_PARTITIONS 2 +static struct mtd_partition partition_info[] = { + { .name = "Flash partition 1", + .offset = 0, + .size = 8 * 1024 * 1024 }, + { .name = "Flash partition 2", + .offset = MTDPART_OFS_NEXT, + .size = MTDPART_SIZ_FULL }, +}; + </programlisting> + </sect1> + <sect1 id="Hardware_control_functions"> + <title>Hardware control function</title> + <para> + The hardware control function provides access to the + control pins of the NAND chip(s). + The access can be done by GPIO pins or by address lines. + If you use address lines, make sure that the timing + requirements are met. + </para> + <para> + <emphasis>GPIO based example</emphasis> + </para> + <programlisting> +static void board_hwcontrol(struct mtd_info *mtd, int cmd) +{ + switch(cmd){ + case NAND_CTL_SETCLE: /* Set CLE pin high */ break; + case NAND_CTL_CLRCLE: /* Set CLE pin low */ break; + case NAND_CTL_SETALE: /* Set ALE pin high */ break; + case NAND_CTL_CLRALE: /* Set ALE pin low */ break; + case NAND_CTL_SETNCE: /* Set nCE pin low */ break; + case NAND_CTL_CLRNCE: /* Set nCE pin high */ break; + } +} + </programlisting> + <para> + <emphasis>Address lines based example.</emphasis> It's assumed that the + nCE pin is driven by a chip select decoder. + </para> + <programlisting> +static void board_hwcontrol(struct mtd_info *mtd, int cmd) +{ + struct nand_chip *this = mtd_to_nand(mtd); + switch(cmd){ + case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; + case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; + case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break; + case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break; + } +} + </programlisting> + </sect1> + <sect1 id="Device_ready_function"> + <title>Device ready function</title> + <para> + If the hardware interface has the ready busy pin of the NAND chip connected to a + GPIO or other accessible I/O pin, this function is used to read back the state of the + pin. The function has no arguments and should return 0, if the device is busy (R/B pin + is low) and 1, if the device is ready (R/B pin is high). + If the hardware interface does not give access to the ready busy pin, then + the function must not be defined and the function pointer this->dev_ready is set to NULL. + </para> + </sect1> + <sect1 id="Init_function"> + <title>Init function</title> + <para> + The init function allocates memory and sets up all the board + specific parameters and function pointers. When everything + is set up nand_scan() is called. This function tries to + detect and identify then chip. If a chip is found all the + internal data fields are initialized accordingly. + The structure(s) have to be zeroed out first and then filled with the necessary + information about the device. + </para> + <programlisting> +static int __init board_init (void) +{ + struct nand_chip *this; + int err = 0; + + /* Allocate memory for MTD device structure and private data */ + this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); + if (!this) { + printk ("Unable to allocate NAND MTD device structure.\n"); + err = -ENOMEM; + goto out; + } + + board_mtd = nand_to_mtd(this); + + /* map physical address */ + baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); + if (!baseaddr) { + printk("Ioremap to access NAND chip failed\n"); + err = -EIO; + goto out_mtd; + } + + /* Set address of NAND IO lines */ + this->IO_ADDR_R = baseaddr; + this->IO_ADDR_W = baseaddr; + /* Reference hardware control function */ + this->hwcontrol = board_hwcontrol; + /* Set command delay time, see datasheet for correct value */ + this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; + /* Assign the device ready function, if available */ + this->dev_ready = board_dev_ready; + this->eccmode = NAND_ECC_SOFT; + + /* Scan to find existence of the device */ + if (nand_scan (board_mtd, 1)) { + err = -ENXIO; + goto out_ior; + } + + add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); + goto out; + +out_ior: + iounmap(baseaddr); +out_mtd: + kfree (this); +out: + return err; +} +module_init(board_init); + </programlisting> + </sect1> + <sect1 id="Exit_function"> + <title>Exit function</title> + <para> + The exit function is only necessary if the driver is + compiled as a module. It releases all resources which + are held by the chip driver and unregisters the partitions + in the MTD layer. + </para> + <programlisting> +#ifdef MODULE +static void __exit board_cleanup (void) +{ + /* Release resources, unregister device */ + nand_release (board_mtd); + + /* unmap physical address */ + iounmap(baseaddr); + + /* Free the MTD device structure */ + kfree (mtd_to_nand(board_mtd)); +} +module_exit(board_cleanup); +#endif + </programlisting> + </sect1> + </chapter> + + <chapter id="boarddriversadvanced"> + <title>Advanced board driver functions</title> + <para> + This chapter describes the advanced functionality of the NAND + driver. For a list of functions which can be overridden by the board + driver see the documentation of the nand_chip structure. + </para> + <sect1 id="Multiple_chip_control"> + <title>Multiple chip control</title> + <para> + The nand driver can control chip arrays. Therefore the + board driver must provide an own select_chip function. This + function must (de)select the requested chip. + The function pointer in the nand_chip structure must + be set before calling nand_scan(). The maxchip parameter + of nand_scan() defines the maximum number of chips to + scan for. Make sure that the select_chip function can + handle the requested number of chips. + </para> + <para> + The nand driver concatenates the chips to one virtual + chip and provides this virtual chip to the MTD layer. + </para> + <para> + <emphasis>Note: The driver can only handle linear chip arrays + of equally sized chips. There is no support for + parallel arrays which extend the buswidth.</emphasis> + </para> + <para> + <emphasis>GPIO based example</emphasis> + </para> + <programlisting> +static void board_select_chip (struct mtd_info *mtd, int chip) +{ + /* Deselect all chips, set all nCE pins high */ + GPIO(BOARD_NAND_NCE) |= 0xff; + if (chip >= 0) + GPIO(BOARD_NAND_NCE) &= ~ (1 << chip); +} + </programlisting> + <para> + <emphasis>Address lines based example.</emphasis> + Its assumed that the nCE pins are connected to an + address decoder. + </para> + <programlisting> +static void board_select_chip (struct mtd_info *mtd, int chip) +{ + struct nand_chip *this = mtd_to_nand(mtd); + + /* Deselect all chips */ + this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; + this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; + switch (chip) { + case 0: + this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; + this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; + break; + .... + case n: + this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; + this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; + break; + } +} + </programlisting> + </sect1> + <sect1 id="Hardware_ECC_support"> + <title>Hardware ECC support</title> + <sect2 id="Functions_and_constants"> + <title>Functions and constants</title> + <para> + The nand driver supports three different types of + hardware ECC. + <itemizedlist> + <listitem><para>NAND_ECC_HW3_256</para><para> + Hardware ECC generator providing 3 bytes ECC per + 256 byte. + </para> </listitem> + <listitem><para>NAND_ECC_HW3_512</para><para> + Hardware ECC generator providing 3 bytes ECC per + 512 byte. + </para> </listitem> + <listitem><para>NAND_ECC_HW6_512</para><para> + Hardware ECC generator providing 6 bytes ECC per + 512 byte. + </para> </listitem> + <listitem><para>NAND_ECC_HW8_512</para><para> + Hardware ECC generator providing 6 bytes ECC per + 512 byte. + </para> </listitem> + </itemizedlist> + If your hardware generator has a different functionality + add it at the appropriate place in nand_base.c + </para> + <para> + The board driver must provide following functions: + <itemizedlist> + <listitem><para>enable_hwecc</para><para> + This function is called before reading / writing to + the chip. Reset or initialize the hardware generator + in this function. The function is called with an + argument which let you distinguish between read + and write operations. + </para> </listitem> + <listitem><para>calculate_ecc</para><para> + This function is called after read / write from / to + the chip. Transfer the ECC from the hardware to + the buffer. If the option NAND_HWECC_SYNDROME is set + then the function is only called on write. See below. + </para> </listitem> + <listitem><para>correct_data</para><para> + In case of an ECC error this function is called for + error detection and correction. Return 1 respectively 2 + in case the error can be corrected. If the error is + not correctable return -1. If your hardware generator + matches the default algorithm of the nand_ecc software + generator then use the correction function provided + by nand_ecc instead of implementing duplicated code. + </para> </listitem> + </itemizedlist> + </para> + </sect2> + <sect2 id="Hardware_ECC_with_syndrome_calculation"> + <title>Hardware ECC with syndrome calculation</title> + <para> + Many hardware ECC implementations provide Reed-Solomon + codes and calculate an error syndrome on read. The syndrome + must be converted to a standard Reed-Solomon syndrome + before calling the error correction code in the generic + Reed-Solomon library. + </para> + <para> + The ECC bytes must be placed immediately after the data + bytes in order to make the syndrome generator work. This + is contrary to the usual layout used by software ECC. The + separation of data and out of band area is not longer + possible. The nand driver code handles this layout and + the remaining free bytes in the oob area are managed by + the autoplacement code. Provide a matching oob-layout + in this case. See rts_from4.c and diskonchip.c for + implementation reference. In those cases we must also + use bad block tables on FLASH, because the ECC layout is + interfering with the bad block marker positions. + See bad block table support for details. + </para> + </sect2> + </sect1> + <sect1 id="Bad_Block_table_support"> + <title>Bad block table support</title> + <para> + Most NAND chips mark the bad blocks at a defined + position in the spare area. Those blocks must + not be erased under any circumstances as the bad + block information would be lost. + It is possible to check the bad block mark each + time when the blocks are accessed by reading the + spare area of the first page in the block. This + is time consuming so a bad block table is used. + </para> + <para> + The nand driver supports various types of bad block + tables. + <itemizedlist> + <listitem><para>Per device</para><para> + The bad block table contains all bad block information + of the device which can consist of multiple chips. + </para> </listitem> + <listitem><para>Per chip</para><para> + A bad block table is used per chip and contains the + bad block information for this particular chip. + </para> </listitem> + <listitem><para>Fixed offset</para><para> + The bad block table is located at a fixed offset + in the chip (device). This applies to various + DiskOnChip devices. + </para> </listitem> + <listitem><para>Automatic placed</para><para> + The bad block table is automatically placed and + detected either at the end or at the beginning + of a chip (device) + </para> </listitem> + <listitem><para>Mirrored tables</para><para> + The bad block table is mirrored on the chip (device) to + allow updates of the bad block table without data loss. + </para> </listitem> + </itemizedlist> + </para> + <para> + nand_scan() calls the function nand_default_bbt(). + nand_default_bbt() selects appropriate default + bad block table descriptors depending on the chip information + which was retrieved by nand_scan(). + </para> + <para> + The standard policy is scanning the device for bad + blocks and build a ram based bad block table which + allows faster access than always checking the + bad block information on the flash chip itself. + </para> + <sect2 id="Flash_based_tables"> + <title>Flash based tables</title> + <para> + It may be desired or necessary to keep a bad block table in FLASH. + For AG-AND chips this is mandatory, as they have no factory marked + bad blocks. They have factory marked good blocks. The marker pattern + is erased when the block is erased to be reused. So in case of + powerloss before writing the pattern back to the chip this block + would be lost and added to the bad blocks. Therefore we scan the + chip(s) when we detect them the first time for good blocks and + store this information in a bad block table before erasing any + of the blocks. + </para> + <para> + The blocks in which the tables are stored are protected against + accidental access by marking them bad in the memory bad block + table. The bad block table management functions are allowed + to circumvent this protection. + </para> + <para> + The simplest way to activate the FLASH based bad block table support + is to set the option NAND_BBT_USE_FLASH in the bbt_option field of + the nand chip structure before calling nand_scan(). For AG-AND + chips is this done by default. + This activates the default FLASH based bad block table functionality + of the NAND driver. The default bad block table options are + <itemizedlist> + <listitem><para>Store bad block table per chip</para></listitem> + <listitem><para>Use 2 bits per block</para></listitem> + <listitem><para>Automatic placement at the end of the chip</para></listitem> + <listitem><para>Use mirrored tables with version numbers</para></listitem> + <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem> + </itemizedlist> + </para> + </sect2> + <sect2 id="User_defined_tables"> + <title>User defined tables</title> + <para> + User defined tables are created by filling out a + nand_bbt_descr structure and storing the pointer in the + nand_chip structure member bbt_td before calling nand_scan(). + If a mirror table is necessary a second structure must be + created and a pointer to this structure must be stored + in bbt_md inside the nand_chip structure. If the bbt_md + member is set to NULL then only the main table is used + and no scan for the mirrored table is performed. + </para> + <para> + The most important field in the nand_bbt_descr structure + is the options field. The options define most of the + table properties. Use the predefined constants from + nand.h to define the options. + <itemizedlist> + <listitem><para>Number of bits per block</para> + <para>The supported number of bits is 1, 2, 4, 8.</para></listitem> + <listitem><para>Table per chip</para> + <para>Setting the constant NAND_BBT_PERCHIP selects that + a bad block table is managed for each chip in a chip array. + If this option is not set then a per device bad block table + is used.</para></listitem> + <listitem><para>Table location is absolute</para> + <para>Use the option constant NAND_BBT_ABSPAGE and + define the absolute page number where the bad block + table starts in the field pages. If you have selected bad block + tables per chip and you have a multi chip array then the start page + must be given for each chip in the chip array. Note: there is no scan + for a table ident pattern performed, so the fields + pattern, veroffs, offs, len can be left uninitialized</para></listitem> + <listitem><para>Table location is automatically detected</para> + <para>The table can either be located in the first or the last good + blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place + the bad block table at the end of the chip (device). The + bad block tables are marked and identified by a pattern which + is stored in the spare area of the first page in the block which + holds the bad block table. Store a pointer to the pattern + in the pattern field. Further the length of the pattern has to be + stored in len and the offset in the spare area must be given + in the offs member of the nand_bbt_descr structure. For mirrored + bad block tables different patterns are mandatory.</para></listitem> + <listitem><para>Table creation</para> + <para>Set the option NAND_BBT_CREATE to enable the table creation + if no table can be found during the scan. Usually this is done only + once if a new chip is found. </para></listitem> + <listitem><para>Table write support</para> + <para>Set the option NAND_BBT_WRITE to enable the table write support. + This allows the update of the bad block table(s) in case a block has + to be marked bad due to wear. The MTD interface function block_markbad + is calling the update function of the bad block table. If the write + support is enabled then the table is updated on FLASH.</para> + <para> + Note: Write support should only be enabled for mirrored tables with + version control. + </para></listitem> + <listitem><para>Table version control</para> + <para>Set the option NAND_BBT_VERSION to enable the table version control. + It's highly recommended to enable this for mirrored tables with write + support. It makes sure that the risk of losing the bad block + table information is reduced to the loss of the information about the + one worn out block which should be marked bad. The version is stored in + 4 consecutive bytes in the spare area of the device. The position of + the version number is defined by the member veroffs in the bad block table + descriptor.</para></listitem> + <listitem><para>Save block contents on write</para> + <para> + In case that the block which holds the bad block table does contain + other useful information, set the option NAND_BBT_SAVECONTENT. When + the bad block table is written then the whole block is read the bad + block table is updated and the block is erased and everything is + written back. If this option is not set only the bad block table + is written and everything else in the block is ignored and erased. + </para></listitem> + <listitem><para>Number of reserved blocks</para> + <para> + For automatic placement some blocks must be reserved for + bad block table storage. The number of reserved blocks is defined + in the maxblocks member of the bad block table description structure. + Reserving 4 blocks for mirrored tables should be a reasonable number. + This also limits the number of blocks which are scanned for the bad + block table ident pattern. + </para></listitem> + </itemizedlist> + </para> + </sect2> + </sect1> + <sect1 id="Spare_area_placement"> + <title>Spare area (auto)placement</title> + <para> + The nand driver implements different possibilities for + placement of filesystem data in the spare area, + <itemizedlist> + <listitem><para>Placement defined by fs driver</para></listitem> + <listitem><para>Automatic placement</para></listitem> + </itemizedlist> + The default placement function is automatic placement. The + nand driver has built in default placement schemes for the + various chiptypes. If due to hardware ECC functionality the + default placement does not fit then the board driver can + provide a own placement scheme. + </para> + <para> + File system drivers can provide a own placement scheme which + is used instead of the default placement scheme. + </para> + <para> + Placement schemes are defined by a nand_oobinfo structure + <programlisting> +struct nand_oobinfo { + int useecc; + int eccbytes; + int eccpos[24]; + int oobfree[8][2]; +}; + </programlisting> + <itemizedlist> + <listitem><para>useecc</para><para> + The useecc member controls the ecc and placement function. The header + file include/mtd/mtd-abi.h contains constants to select ecc and + placement. MTD_NANDECC_OFF switches off the ecc complete. This is + not recommended and available for testing and diagnosis only. + MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE + selects automatic placement. + </para></listitem> + <listitem><para>eccbytes</para><para> + The eccbytes member defines the number of ecc bytes per page. + </para></listitem> + <listitem><para>eccpos</para><para> + The eccpos array holds the byte offsets in the spare area where + the ecc codes are placed. + </para></listitem> + <listitem><para>oobfree</para><para> + The oobfree array defines the areas in the spare area which can be + used for automatic placement. The information is given in the format + {offset, size}. offset defines the start of the usable area, size the + length in bytes. More than one area can be defined. The list is terminated + by an {0, 0} entry. + </para></listitem> + </itemizedlist> + </para> + <sect2 id="Placement_defined_by_fs_driver"> + <title>Placement defined by fs driver</title> + <para> + The calling function provides a pointer to a nand_oobinfo + structure which defines the ecc placement. For writes the + caller must provide a spare area buffer along with the + data buffer. The spare area buffer size is (number of pages) * + (size of spare area). For reads the buffer size is + (number of pages) * ((size of spare area) + (number of ecc + steps per page) * sizeof (int)). The driver stores the + result of the ecc check for each tuple in the spare buffer. + The storage sequence is + </para> + <para> + <spare data page 0><ecc result 0>...<ecc result n> + </para> + <para> + ... + </para> + <para> + <spare data page n><ecc result 0>...<ecc result n> + </para> + <para> + This is a legacy mode used by YAFFS1. + </para> + <para> + If the spare area buffer is NULL then only the ECC placement is + done according to the given scheme in the nand_oobinfo structure. + </para> + </sect2> + <sect2 id="Automatic_placement"> + <title>Automatic placement</title> + <para> + Automatic placement uses the built in defaults to place the + ecc bytes in the spare area. If filesystem data have to be stored / + read into the spare area then the calling function must provide a + buffer. The buffer size per page is determined by the oobfree array in + the nand_oobinfo structure. + </para> + <para> + If the spare area buffer is NULL then only the ECC placement is + done according to the default builtin scheme. + </para> + </sect2> + </sect1> + <sect1 id="Spare_area_autoplacement_default"> + <title>Spare area autoplacement default schemes</title> + <sect2 id="pagesize_256"> + <title>256 byte pagesize</title> +<informaltable><tgroup cols="3"><tbody> +<row> +<entry>Offset</entry> +<entry>Content</entry> +<entry>Comment</entry> +</row> +<row> +<entry>0x00</entry> +<entry>ECC byte 0</entry> +<entry>Error correction code byte 0</entry> +</row> +<row> +<entry>0x01</entry> +<entry>ECC byte 1</entry> +<entry>Error correction code byte 1</entry> +</row> +<row> +<entry>0x02</entry> +<entry>ECC byte 2</entry> +<entry>Error correction code byte 2</entry> +</row> +<row> +<entry>0x03</entry> +<entry>Autoplace 0</entry> +<entry></entry> +</row> +<row> +<entry>0x04</entry> +<entry>Autoplace 1</entry> +<entry></entry> +</row> +<row> +<entry>0x05</entry> +<entry>Bad block marker</entry> +<entry>If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved</entry> +</row> +<row> +<entry>0x06</entry> +<entry>Autoplace 2</entry> +<entry></entry> +</row> +<row> +<entry>0x07</entry> +<entry>Autoplace 3</entry> +<entry></entry> +</row> +</tbody></tgroup></informaltable> + </sect2> + <sect2 id="pagesize_512"> + <title>512 byte pagesize</title> +<informaltable><tgroup cols="3"><tbody> +<row> +<entry>Offset</entry> +<entry>Content</entry> +<entry>Comment</entry> +</row> +<row> +<entry>0x00</entry> +<entry>ECC byte 0</entry> +<entry>Error correction code byte 0 of the lower 256 Byte data in +this page</entry> +</row> +<row> +<entry>0x01</entry> +<entry>ECC byte 1</entry> +<entry>Error correction code byte 1 of the lower 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x02</entry> +<entry>ECC byte 2</entry> +<entry>Error correction code byte 2 of the lower 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x03</entry> +<entry>ECC byte 3</entry> +<entry>Error correction code byte 0 of the upper 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x04</entry> +<entry>reserved</entry> +<entry>reserved</entry> +</row> +<row> +<entry>0x05</entry> +<entry>Bad block marker</entry> +<entry>If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved</entry> +</row> +<row> +<entry>0x06</entry> +<entry>ECC byte 4</entry> +<entry>Error correction code byte 1 of the upper 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x07</entry> +<entry>ECC byte 5</entry> +<entry>Error correction code byte 2 of the upper 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x08 - 0x0F</entry> +<entry>Autoplace 0 - 7</entry> +<entry></entry> +</row> +</tbody></tgroup></informaltable> + </sect2> + <sect2 id="pagesize_2048"> + <title>2048 byte pagesize</title> +<informaltable><tgroup cols="3"><tbody> +<row> +<entry>Offset</entry> +<entry>Content</entry> +<entry>Comment</entry> +</row> +<row> +<entry>0x00</entry> +<entry>Bad block marker</entry> +<entry>If any bit in this byte is zero, then this block is bad. +This applies only to the first page in a block. In the remaining +pages this byte is reserved</entry> +</row> +<row> +<entry>0x01</entry> +<entry>Reserved</entry> +<entry>Reserved</entry> +</row> +<row> +<entry>0x02-0x27</entry> +<entry>Autoplace 0 - 37</entry> +<entry></entry> +</row> +<row> +<entry>0x28</entry> +<entry>ECC byte 0</entry> +<entry>Error correction code byte 0 of the first 256 Byte data in +this page</entry> +</row> +<row> +<entry>0x29</entry> +<entry>ECC byte 1</entry> +<entry>Error correction code byte 1 of the first 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x2A</entry> +<entry>ECC byte 2</entry> +<entry>Error correction code byte 2 of the first 256 Bytes data in +this page</entry> +</row> +<row> +<entry>0x2B</entry> +<entry>ECC byte 3</entry> +<entry>Error correction code byte 0 of the second 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x2C</entry> +<entry>ECC byte 4</entry> +<entry>Error correction code byte 1 of the second 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x2D</entry> +<entry>ECC byte 5</entry> +<entry>Error correction code byte 2 of the second 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x2E</entry> +<entry>ECC byte 6</entry> +<entry>Error correction code byte 0 of the third 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x2F</entry> +<entry>ECC byte 7</entry> +<entry>Error correction code byte 1 of the third 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x30</entry> +<entry>ECC byte 8</entry> +<entry>Error correction code byte 2 of the third 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x31</entry> +<entry>ECC byte 9</entry> +<entry>Error correction code byte 0 of the fourth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x32</entry> +<entry>ECC byte 10</entry> +<entry>Error correction code byte 1 of the fourth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x33</entry> +<entry>ECC byte 11</entry> +<entry>Error correction code byte 2 of the fourth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x34</entry> +<entry>ECC byte 12</entry> +<entry>Error correction code byte 0 of the fifth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x35</entry> +<entry>ECC byte 13</entry> +<entry>Error correction code byte 1 of the fifth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x36</entry> +<entry>ECC byte 14</entry> +<entry>Error correction code byte 2 of the fifth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x37</entry> +<entry>ECC byte 15</entry> +<entry>Error correction code byte 0 of the sixt 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x38</entry> +<entry>ECC byte 16</entry> +<entry>Error correction code byte 1 of the sixt 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x39</entry> +<entry>ECC byte 17</entry> +<entry>Error correction code byte 2 of the sixt 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x3A</entry> +<entry>ECC byte 18</entry> +<entry>Error correction code byte 0 of the seventh 256 Bytes of +data in this page</entry> +</row> +<row> +<entry>0x3B</entry> +<entry>ECC byte 19</entry> +<entry>Error correction code byte 1 of the seventh 256 Bytes of +data in this page</entry> +</row> +<row> +<entry>0x3C</entry> +<entry>ECC byte 20</entry> +<entry>Error correction code byte 2 of the seventh 256 Bytes of +data in this page</entry> +</row> +<row> +<entry>0x3D</entry> +<entry>ECC byte 21</entry> +<entry>Error correction code byte 0 of the eighth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x3E</entry> +<entry>ECC byte 22</entry> +<entry>Error correction code byte 1 of the eighth 256 Bytes of data +in this page</entry> +</row> +<row> +<entry>0x3F</entry> +<entry>ECC byte 23</entry> +<entry>Error correction code byte 2 of the eighth 256 Bytes of data +in this page</entry> +</row> +</tbody></tgroup></informaltable> + </sect2> + </sect1> + </chapter> + + <chapter id="filesystems"> + <title>Filesystem support</title> + <para> + The NAND driver provides all necessary functions for a + filesystem via the MTD interface. + </para> + <para> + Filesystems must be aware of the NAND peculiarities and + restrictions. One major restrictions of NAND Flash is, that you cannot + write as often as you want to a page. The consecutive writes to a page, + before erasing it again, are restricted to 1-3 writes, depending on the + manufacturers specifications. This applies similar to the spare area. + </para> + <para> + Therefore NAND aware filesystems must either write in page size chunks + or hold a writebuffer to collect smaller writes until they sum up to + pagesize. Available NAND aware filesystems: JFFS2, YAFFS. + </para> + <para> + The spare area usage to store filesystem data is controlled by + the spare area placement functionality which is described in one + of the earlier chapters. + </para> + </chapter> + <chapter id="tools"> + <title>Tools</title> + <para> + The MTD project provides a couple of helpful tools to handle NAND Flash. + <itemizedlist> + <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem> + <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem> + <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem> + </itemizedlist> + </para> + <para> + These tools are aware of the NAND restrictions. Please use those tools + instead of complaining about errors which are caused by non NAND aware + access methods. + </para> + </chapter> + + <chapter id="defines"> + <title>Constants</title> + <para> + This chapter describes the constants which might be relevant for a driver developer. + </para> + <sect1 id="Chip_option_constants"> + <title>Chip option constants</title> + <sect2 id="Constants_for_chip_id_table"> + <title>Constants for chip id table</title> + <para> + These constants are defined in nand.h. They are ored together to describe + the chip functionality. + <programlisting> +/* Buswitdh is 16 bit */ +#define NAND_BUSWIDTH_16 0x00000002 +/* Device supports partial programming without padding */ +#define NAND_NO_PADDING 0x00000004 +/* Chip has cache program function */ +#define NAND_CACHEPRG 0x00000008 +/* Chip has copy back function */ +#define NAND_COPYBACK 0x00000010 +/* AND Chip which has 4 banks and a confusing page / block + * assignment. See Renesas datasheet for further information */ +#define NAND_IS_AND 0x00000020 +/* Chip has a array of 4 pages which can be read without + * additional ready /busy waits */ +#define NAND_4PAGE_ARRAY 0x00000040 + </programlisting> + </para> + </sect2> + <sect2 id="Constants_for_runtime_options"> + <title>Constants for runtime options</title> + <para> + These constants are defined in nand.h. They are ored together to describe + the functionality. + <programlisting> +/* The hw ecc generator provides a syndrome instead a ecc value on read + * This can only work if we have the ecc bytes directly behind the + * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ +#define NAND_HWECC_SYNDROME 0x00020000 + </programlisting> + </para> + </sect2> + </sect1> + + <sect1 id="EEC_selection_constants"> + <title>ECC selection constants</title> + <para> + Use these constants to select the ECC algorithm. + <programlisting> +/* No ECC. Usage is not recommended ! */ +#define NAND_ECC_NONE 0 +/* Software ECC 3 byte ECC per 256 Byte data */ +#define NAND_ECC_SOFT 1 +/* Hardware ECC 3 byte ECC per 256 Byte data */ +#define NAND_ECC_HW3_256 2 +/* Hardware ECC 3 byte ECC per 512 Byte data */ +#define NAND_ECC_HW3_512 3 +/* Hardware ECC 6 byte ECC per 512 Byte data */ +#define NAND_ECC_HW6_512 4 +/* Hardware ECC 6 byte ECC per 512 Byte data */ +#define NAND_ECC_HW8_512 6 + </programlisting> + </para> + </sect1> + + <sect1 id="Hardware_control_related_constants"> + <title>Hardware control related constants</title> + <para> + These constants describe the requested hardware access function when + the boardspecific hardware control function is called + <programlisting> +/* Select the chip by setting nCE to low */ +#define NAND_CTL_SETNCE 1 +/* Deselect the chip by setting nCE to high */ +#define NAND_CTL_CLRNCE 2 +/* Select the command latch by setting CLE to high */ +#define NAND_CTL_SETCLE 3 +/* Deselect the command latch by setting CLE to low */ +#define NAND_CTL_CLRCLE 4 +/* Select the address latch by setting ALE to high */ +#define NAND_CTL_SETALE 5 +/* Deselect the address latch by setting ALE to low */ +#define NAND_CTL_CLRALE 6 +/* Set write protection by setting WP to high. Not used! */ +#define NAND_CTL_SETWP 7 +/* Clear write protection by setting WP to low. Not used! */ +#define NAND_CTL_CLRWP 8 + </programlisting> + </para> + </sect1> + + <sect1 id="Bad_block_table_constants"> + <title>Bad block table related constants</title> + <para> + These constants describe the options used for bad block + table descriptors. + <programlisting> +/* Options for the bad block table descriptors */ + +/* The number of bits used per block in the bbt on the device */ +#define NAND_BBT_NRBITS_MSK 0x0000000F +#define NAND_BBT_1BIT 0x00000001 +#define NAND_BBT_2BIT 0x00000002 +#define NAND_BBT_4BIT 0x00000004 +#define NAND_BBT_8BIT 0x00000008 +/* The bad block table is in the last good block of the device */ +#define NAND_BBT_LASTBLOCK 0x00000010 +/* The bbt is at the given page, else we must scan for the bbt */ +#define NAND_BBT_ABSPAGE 0x00000020 +/* bbt is stored per chip on multichip devices */ +#define NAND_BBT_PERCHIP 0x00000080 +/* bbt has a version counter at offset veroffs */ +#define NAND_BBT_VERSION 0x00000100 +/* Create a bbt if none axists */ +#define NAND_BBT_CREATE 0x00000200 +/* Write bbt if necessary */ +#define NAND_BBT_WRITE 0x00001000 +/* Read and write back block contents when writing bbt */ +#define NAND_BBT_SAVECONTENT 0x00002000 + </programlisting> + </para> + </sect1> + + </chapter> + + <chapter id="structs"> + <title>Structures</title> + <para> + This chapter contains the autogenerated documentation of the structures which are + used in the NAND driver and might be relevant for a driver developer. Each + struct member has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + </para> +!Iinclude/linux/mtd/nand.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the NAND kernel API functions + which are exported. Each function has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + </para> +!Edrivers/mtd/nand/nand_base.c +!Edrivers/mtd/nand/nand_bbt.c +!Edrivers/mtd/nand/nand_ecc.c + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the NAND driver internal functions. + Each function has a short description which is marked with an [XXX] identifier. + See the chapter "Documentation hints" for an explanation. + The functions marked with [DEFAULT] might be relevant for a board driver developer. + </para> +!Idrivers/mtd/nand/nand_base.c +!Idrivers/mtd/nand/nand_bbt.c +<!-- No internal functions for kernel-doc: +X!Idrivers/mtd/nand/nand_ecc.c +--> + </chapter> + + <chapter id="credits"> + <title>Credits</title> + <para> + The following people have contributed to the NAND driver: + <orderedlist> + <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem> + <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem> + <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> + </orderedlist> + A lot of users have provided bugfixes, improvements and helping hands for testing. + Thanks a lot. + </para> + <para> + The following people have contributed to this document: + <orderedlist> + <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> + </orderedlist> + </para> + </chapter> +</book>
diff --git a/Documentation/DocBook/networking.tmpl b/Documentation/DocBook/networking.tmpl new file mode 100644 index 0000000..29df250 --- /dev/null +++ b/Documentation/DocBook/networking.tmpl
@@ -0,0 +1,111 @@ +<?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="LinuxNetworking"> + <bookinfo> + <title>Linux Networking and Network Devices APIs</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="netcore"> + <title>Linux Networking</title> + <sect1><title>Networking Base Types</title> +!Iinclude/linux/net.h + </sect1> + <sect1><title>Socket Buffer Functions</title> +!Iinclude/linux/skbuff.h +!Iinclude/net/sock.h +!Enet/socket.c +!Enet/core/skbuff.c +!Enet/core/sock.c +!Enet/core/datagram.c +!Enet/core/stream.c + </sect1> + <sect1><title>Socket Filter</title> +!Enet/core/filter.c + </sect1> + <sect1><title>Generic Network Statistics</title> +!Iinclude/uapi/linux/gen_stats.h +!Enet/core/gen_stats.c +!Enet/core/gen_estimator.c + </sect1> + <sect1><title>SUN RPC subsystem</title> +<!-- The !D functionality is not perfect, garbage has to be protected by comments +!Dnet/sunrpc/sunrpc_syms.c +--> +!Enet/sunrpc/xdr.c +!Enet/sunrpc/svc_xprt.c +!Enet/sunrpc/xprt.c +!Enet/sunrpc/sched.c +!Enet/sunrpc/socklib.c +!Enet/sunrpc/stats.c +!Enet/sunrpc/rpc_pipe.c +!Enet/sunrpc/rpcb_clnt.c +!Enet/sunrpc/clnt.c + </sect1> + <sect1><title>WiMAX</title> +!Enet/wimax/op-msg.c +!Enet/wimax/op-reset.c +!Enet/wimax/op-rfkill.c +!Enet/wimax/stack.c +!Iinclude/net/wimax.h +!Iinclude/uapi/linux/wimax.h + </sect1> + </chapter> + + <chapter id="netdev"> + <title>Network device support</title> + <sect1><title>Driver Support</title> +!Enet/core/dev.c +!Enet/ethernet/eth.c +!Enet/sched/sch_generic.c +!Iinclude/linux/etherdevice.h +!Iinclude/linux/netdevice.h + </sect1> + <sect1><title>PHY Support</title> +!Edrivers/net/phy/phy.c +!Idrivers/net/phy/phy.c +!Edrivers/net/phy/phy_device.c +!Idrivers/net/phy/phy_device.c +!Edrivers/net/phy/mdio_bus.c +!Idrivers/net/phy/mdio_bus.c + </sect1> +<!-- FIXME: Removed for now since no structured comments in source + <sect1><title>Wireless</title> +X!Enet/core/wireless.c + </sect1> +--> + </chapter> + +</book>
diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl new file mode 100644 index 0000000..5047936 --- /dev/null +++ b/Documentation/DocBook/rapidio.tmpl
@@ -0,0 +1,158 @@ +<?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" [ + <!ENTITY rapidio SYSTEM "rapidio.xml"> + ]> + +<book id="RapidIO-Guide"> + <bookinfo> + <title>RapidIO Subsystem Guide</title> + + <authorgroup> + <author> + <firstname>Matt</firstname> + <surname>Porter</surname> + <affiliation> + <address> + <email>mporter@kernel.crashing.org</email> + <email>mporter@mvista.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2005</year> + <holder>MontaVista Software, Inc.</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> + RapidIO is a high speed switched fabric interconnect with + features aimed at the embedded market. RapidIO provides + support for memory-mapped I/O as well as message-based + transactions over the switched fabric network. RapidIO has + a standardized discovery mechanism not unlike the PCI bus + standard that allows simple detection of devices in a + network. + </para> + <para> + This documentation is provided for developers intending + to support RapidIO on new architectures, write new drivers, + or to understand the subsystem internals. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs and Limitations</title> + + <sect1 id="known_bugs"> + <title>Bugs</title> + <para>None. ;)</para> + </sect1> + <sect1 id="Limitations"> + <title>Limitations</title> + <para> + <orderedlist> + <listitem><para>Access/management of RapidIO memory regions is not supported</para></listitem> + <listitem><para>Multiple host enumeration is not supported</para></listitem> + </orderedlist> + </para> + </sect1> + </chapter> + + <chapter id="drivers"> + <title>RapidIO driver interface</title> + <para> + Drivers are provided a set of calls in order + to interface with the subsystem to gather info + on devices, request/map memory region resources, + and manage mailboxes/doorbells. + </para> + <sect1 id="Functions"> + <title>Functions</title> +!Iinclude/linux/rio_drv.h +!Edrivers/rapidio/rio-driver.c +!Edrivers/rapidio/rio.c + </sect1> + </chapter> + + <chapter id="internals"> + <title>Internals</title> + + <para> + This chapter contains the autogenerated documentation of the RapidIO + subsystem. + </para> + + <sect1 id="Structures"><title>Structures</title> +!Iinclude/linux/rio.h + </sect1> + <sect1 id="Enumeration_and_Discovery"><title>Enumeration and Discovery</title> +!Idrivers/rapidio/rio-scan.c + </sect1> + <sect1 id="Driver_functionality"><title>Driver functionality</title> +!Idrivers/rapidio/rio.c +!Idrivers/rapidio/rio-access.c + </sect1> + <sect1 id="Device_model_support"><title>Device model support</title> +!Idrivers/rapidio/rio-driver.c + </sect1> + <sect1 id="Sysfs_support"><title>Sysfs support</title> +!Idrivers/rapidio/rio-sysfs.c + </sect1> + <sect1 id="PPC32_support"><title>PPC32 support</title> +!Iarch/powerpc/sysdev/fsl_rio.c + </sect1> + </chapter> + + <chapter id="credits"> + <title>Credits</title> + <para> + The following people have contributed to the RapidIO + subsystem directly or indirectly: + <orderedlist> + <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem> + <listitem><para>Randy Vinson<email>rvinson@mvista.com</email></para></listitem> + <listitem><para>Dan Malek<email>dan@embeddedalley.com</email></para></listitem> + </orderedlist> + </para> + <para> + The following people have contributed to this document: + <orderedlist> + <listitem><para>Matt Porter<email>mporter@kernel.crashing.org</email></para></listitem> + </orderedlist> + </para> + </chapter> +</book>
diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl new file mode 100644 index 0000000..3b08a08 --- /dev/null +++ b/Documentation/DocBook/regulator.tmpl
@@ -0,0 +1,304 @@ +<?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="regulator-api"> + <bookinfo> + <title>Voltage and current regulator API</title> + + <authorgroup> + <author> + <firstname>Liam</firstname> + <surname>Girdwood</surname> + <affiliation> + <address> + <email>lrg@slimlogic.co.uk</email> + </address> + </affiliation> + </author> + <author> + <firstname>Mark</firstname> + <surname>Brown</surname> + <affiliation> + <orgname>Wolfson Microelectronics</orgname> + <address> + <email>broonie@opensource.wolfsonmicro.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2007-2008</year> + <holder>Wolfson Microelectronics</holder> + </copyright> + <copyright> + <year>2008</year> + <holder>Liam Girdwood</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> + This framework is designed to provide a standard kernel + interface to control voltage and current regulators. + </para> + <para> + The intention is to allow systems to dynamically control + regulator power output in order to save power and prolong + battery life. This applies to both voltage regulators (where + voltage output is controllable) and current sinks (where current + limit is controllable). + </para> + <para> + Note that additional (and currently more complete) documentation + is available in the Linux kernel source under + <filename>Documentation/power/regulator</filename>. + </para> + + <sect1 id="glossary"> + <title>Glossary</title> + <para> + The regulator API uses a number of terms which may not be + familiar: + </para> + <glossary> + + <glossentry> + <glossterm>Regulator</glossterm> + <glossdef> + <para> + Electronic device that supplies power to other devices. Most + regulators can enable and disable their output and some can also + control their output voltage or current. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Consumer</glossterm> + <glossdef> + <para> + Electronic device which consumes power provided by a regulator. + These may either be static, requiring only a fixed supply, or + dynamic, requiring active management of the regulator at + runtime. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Power Domain</glossterm> + <glossdef> + <para> + The electronic circuit supplied by a given regulator, including + the regulator and all consumer devices. The configuration of + the regulator is shared between all the components in the + circuit. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Power Management Integrated Circuit</glossterm> + <acronym>PMIC</acronym> + <glossdef> + <para> + An IC which contains numerous regulators and often also other + subsystems. In an embedded system the primary PMIC is often + equivalent to a combination of the PSU and southbridge in a + desktop system. + </para> + </glossdef> + </glossentry> + </glossary> + </sect1> + </chapter> + + <chapter id="consumer"> + <title>Consumer driver interface</title> + <para> + This offers a similar API to the kernel clock framework. + Consumer drivers use <link + linkend='API-regulator-get'>get</link> and <link + linkend='API-regulator-put'>put</link> operations to acquire and + release regulators. Functions are + provided to <link linkend='API-regulator-enable'>enable</link> + and <link linkend='API-regulator-disable'>disable</link> the + regulator and to get and set the runtime parameters of the + regulator. + </para> + <para> + When requesting regulators consumers use symbolic names for their + supplies, such as "Vcc", which are mapped into actual regulator + devices by the machine interface. + </para> + <para> + A stub version of this API is provided when the regulator + framework is not in use in order to minimise the need to use + ifdefs. + </para> + + <sect1 id="consumer-enable"> + <title>Enabling and disabling</title> + <para> + The regulator API provides reference counted enabling and + disabling of regulators. Consumer devices use the <function><link + linkend='API-regulator-enable'>regulator_enable</link></function> + and <function><link + linkend='API-regulator-disable'>regulator_disable</link> + </function> functions to enable and disable regulators. Calls + to the two functions must be balanced. + </para> + <para> + Note that since multiple consumers may be using a regulator and + machine constraints may not allow the regulator to be disabled + there is no guarantee that calling + <function>regulator_disable</function> will actually cause the + supply provided by the regulator to be disabled. Consumer + drivers should assume that the regulator may be enabled at all + times. + </para> + </sect1> + + <sect1 id="consumer-config"> + <title>Configuration</title> + <para> + Some consumer devices may need to be able to dynamically + configure their supplies. For example, MMC drivers may need to + select the correct operating voltage for their cards. This may + be done while the regulator is enabled or disabled. + </para> + <para> + The <function><link + linkend='API-regulator-set-voltage'>regulator_set_voltage</link> + </function> and <function><link + linkend='API-regulator-set-current-limit' + >regulator_set_current_limit</link> + </function> functions provide the primary interface for this. + Both take ranges of voltages and currents, supporting drivers + that do not require a specific value (eg, CPU frequency scaling + normally permits the CPU to use a wider range of supply + voltages at lower frequencies but does not require that the + supply voltage be lowered). Where an exact value is required + both minimum and maximum values should be identical. + </para> + </sect1> + + <sect1 id="consumer-callback"> + <title>Callbacks</title> + <para> + Callbacks may also be <link + linkend='API-regulator-register-notifier'>registered</link> + for events such as regulation failures. + </para> + </sect1> + </chapter> + + <chapter id="driver"> + <title>Regulator driver interface</title> + <para> + Drivers for regulator chips <link + linkend='API-regulator-register'>register</link> the regulators + with the regulator core, providing operations structures to the + core. A <link + linkend='API-regulator-notifier-call-chain'>notifier</link> interface + allows error conditions to be reported to the core. + </para> + <para> + Registration should be triggered by explicit setup done by the + platform, supplying a <link + linkend='API-struct-regulator-init-data'>struct + regulator_init_data</link> for the regulator containing + <link linkend='machine-constraint'>constraint</link> and + <link linkend='machine-supply'>supply</link> information. + </para> + </chapter> + + <chapter id="machine"> + <title>Machine interface</title> + <para> + This interface provides a way to define how regulators are + connected to consumers on a given system and what the valid + operating parameters are for the system. + </para> + + <sect1 id="machine-supply"> + <title>Supplies</title> + <para> + Regulator supplies are specified using <link + linkend='API-struct-regulator-consumer-supply'>struct + regulator_consumer_supply</link>. This is done at + <link linkend='driver'>driver registration + time</link> as part of the machine constraints. + </para> + </sect1> + + <sect1 id="machine-constraint"> + <title>Constraints</title> + <para> + As well as defining the connections the machine interface + also provides constraints defining the operations that + clients are allowed to perform and the parameters that may be + set. This is required since generally regulator devices will + offer more flexibility than it is safe to use on a given + system, for example supporting higher supply voltages than the + consumers are rated for. + </para> + <para> + This is done at <link linkend='driver'>driver + registration time</link> by providing a <link + linkend='API-struct-regulation-constraints'>struct + regulation_constraints</link>. + </para> + <para> + The constraints may also specify an initial configuration for the + regulator in the constraints, which is particularly useful for + use with static consumers. + </para> + </sect1> + </chapter> + + <chapter id="api"> + <title>API reference</title> + <para> + Due to limitations of the kernel documentation framework and the + existing layout of the source code the entire regulator API is + documented here. + </para> +!Iinclude/linux/regulator/consumer.h +!Iinclude/linux/regulator/machine.h +!Iinclude/linux/regulator/driver.h +!Edrivers/regulator/core.c + </chapter> +</book>
diff --git a/Documentation/DocBook/s390-drivers.tmpl b/Documentation/DocBook/s390-drivers.tmpl new file mode 100644 index 0000000..95bfc12 --- /dev/null +++ b/Documentation/DocBook/s390-drivers.tmpl
@@ -0,0 +1,161 @@ +<?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="s390drivers"> + <bookinfo> + <title>Writing s390 channel device drivers</title> + + <authorgroup> + <author> + <firstname>Cornelia</firstname> + <surname>Huck</surname> + <affiliation> + <address> + <email>cornelia.huck@de.ibm.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2007</year> + <holder>IBM Corp.</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> + This document describes the interfaces available for device drivers that + drive s390 based channel attached I/O devices. This includes interfaces for + interaction with the hardware and interfaces for interacting with the + common driver core. Those interfaces are provided by the s390 common I/O + layer. + </para> + <para> + The document assumes a familarity with the technical terms associated + with the s390 channel I/O architecture. For a description of this + architecture, please refer to the "z/Architecture: Principles of + Operation", IBM publication no. SA22-7832. + </para> + <para> + While most I/O devices on a s390 system are typically driven through the + channel I/O mechanism described here, there are various other methods + (like the diag interface). These are out of the scope of this document. + </para> + <para> + Some additional information can also be found in the kernel source + under Documentation/s390/driver-model.txt. + </para> + </chapter> + <chapter id="ccw"> + <title>The ccw bus</title> + <para> + The ccw bus typically contains the majority of devices available to + a s390 system. Named after the channel command word (ccw), the basic + command structure used to address its devices, the ccw bus contains + so-called channel attached devices. They are addressed via I/O + subchannels, visible on the css bus. A device driver for + channel-attached devices, however, will never interact with the + subchannel directly, but only via the I/O device on the ccw bus, + the ccw device. + </para> + <sect1 id="channelIO"> + <title>I/O functions for channel-attached devices</title> + <para> + Some hardware structures have been translated into C structures for use + by the common I/O layer and device drivers. For more information on + the hardware structures represented here, please consult the Principles + of Operation. + </para> +!Iarch/s390/include/asm/cio.h + </sect1> + <sect1 id="ccwdev"> + <title>ccw devices</title> + <para> + Devices that want to initiate channel I/O need to attach to the ccw bus. + Interaction with the driver core is done via the common I/O layer, which + provides the abstractions of ccw devices and ccw device drivers. + </para> + <para> + The functions that initiate or terminate channel I/O all act upon a + ccw device structure. Device drivers must not bypass those functions + or strange side effects may happen. + </para> +!Iarch/s390/include/asm/ccwdev.h +!Edrivers/s390/cio/device.c +!Edrivers/s390/cio/device_ops.c + </sect1> + <sect1 id="cmf"> + <title>The channel-measurement facility</title> + <para> + The channel-measurement facility provides a means to collect + measurement data which is made available by the channel subsystem + for each channel attached device. + </para> +!Iarch/s390/include/asm/cmb.h +!Edrivers/s390/cio/cmf.c + </sect1> + </chapter> + + <chapter id="ccwgroup"> + <title>The ccwgroup bus</title> + <para> + The ccwgroup bus only contains artificial devices, created by the user. + Many networking devices (e.g. qeth) are in fact composed of several + ccw devices (like read, write and data channel for qeth). The + ccwgroup bus provides a mechanism to create a meta-device which + contains those ccw devices as slave devices and can be associated + with the netdevice. + </para> + <sect1 id="ccwgroupdevices"> + <title>ccw group devices</title> +!Iarch/s390/include/asm/ccwgroup.h +!Edrivers/s390/cio/ccwgroup.c + </sect1> + </chapter> + + <chapter id="genericinterfaces"> + <title>Generic interfaces</title> + <para> + Some interfaces are available to other drivers that do not necessarily + have anything to do with the busses described above, but still are + indirectly using basic infrastructure in the common I/O layer. + One example is the support for adapter interrupts. + </para> +!Edrivers/s390/cio/airq.c + </chapter> + +</book>
diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl new file mode 100644 index 0000000..4b9b9b2 --- /dev/null +++ b/Documentation/DocBook/scsi.tmpl
@@ -0,0 +1,409 @@ +<?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="scsimid"> + <bookinfo> + <title>SCSI Interfaces Guide</title> + + <authorgroup> + <author> + <firstname>James</firstname> + <surname>Bottomley</surname> + <affiliation> + <address> + <email>James.Bottomley@hansenpartnership.com</email> + </address> + </affiliation> + </author> + + <author> + <firstname>Rob</firstname> + <surname>Landley</surname> + <affiliation> + <address> + <email>rob@landley.net</email> + </address> + </affiliation> + </author> + + </authorgroup> + + <copyright> + <year>2007</year> + <holder>Linux Foundation</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. + </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. + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + + <toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <sect1 id="protocol_vs_bus"> + <title>Protocol vs bus</title> + <para> + Once upon a time, the Small Computer Systems Interface defined both + a parallel I/O bus and a data protocol to connect a wide variety of + peripherals (disk drives, tape drives, modems, printers, scanners, + optical drives, test equipment, and medical devices) to a host + computer. + </para> + <para> + Although the old parallel (fast/wide/ultra) SCSI bus has largely + fallen out of use, the SCSI command set is more widely used than ever + to communicate with devices over a number of different busses. + </para> + <para> + The <ulink url='http://www.t10.org/scsi-3.htm'>SCSI protocol</ulink> + is a big-endian peer-to-peer packet based protocol. SCSI commands + are 6, 10, 12, or 16 bytes long, often followed by an associated data + payload. + </para> + <para> + SCSI commands can be transported over just about any kind of bus, and + are the default protocol for storage devices attached to USB, SATA, + SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are + also commonly exchanged over Infiniband, + <ulink url='http://i2o.shadowconnect.com/faq.php'>I20</ulink>, TCP/IP + (<ulink url='https://en.wikipedia.org/wiki/ISCSI'>iSCSI</ulink>), even + <ulink url='http://cyberelk.net/tim/parport/parscsi.html'>Parallel + ports</ulink>. + </para> + </sect1> + <sect1 id="subsystem_design"> + <title>Design of the Linux SCSI subsystem</title> + <para> + The SCSI subsystem uses a three layer design, with upper, mid, and low + layers. Every operation involving the SCSI subsystem (such as reading + a sector from a disk) uses one driver at each of the 3 levels: one + upper layer driver, one lower layer driver, and the SCSI midlayer. + </para> + <para> + The SCSI upper layer provides the interface between userspace and the + kernel, in the form of block and char device nodes for I/O and + ioctl(). The SCSI lower layer contains drivers for specific hardware + devices. + </para> + <para> + In between is the SCSI mid-layer, analogous to a network routing + layer such as the IPv4 stack. The SCSI mid-layer routes a packet + based data protocol between the upper layer's /dev nodes and the + corresponding devices in the lower layer. It manages command queues, + provides error handling and power management functions, and responds + to ioctl() requests. + </para> + </sect1> + </chapter> + + <chapter id="upper_layer"> + <title>SCSI upper layer</title> + <para> + The upper layer supports the user-kernel interface by providing + device nodes. + </para> + <sect1 id="sd"> + <title>sd (SCSI Disk)</title> + <para>sd (sd_mod.o)</para> +<!-- !Idrivers/scsi/sd.c --> + </sect1> + <sect1 id="sr"> + <title>sr (SCSI CD-ROM)</title> + <para>sr (sr_mod.o)</para> + </sect1> + <sect1 id="st"> + <title>st (SCSI Tape)</title> + <para>st (st.o)</para> + </sect1> + <sect1 id="sg"> + <title>sg (SCSI Generic)</title> + <para>sg (sg.o)</para> + </sect1> + <sect1 id="ch"> + <title>ch (SCSI Media Changer)</title> + <para>ch (ch.c)</para> + </sect1> + </chapter> + + <chapter id="mid_layer"> + <title>SCSI mid layer</title> + + <sect1 id="midlayer_implementation"> + <title>SCSI midlayer implementation</title> + <sect2 id="scsi_device.h"> + <title>include/scsi/scsi_device.h</title> + <para> + </para> +!Iinclude/scsi/scsi_device.h + </sect2> + + <sect2 id="scsi.c"> + <title>drivers/scsi/scsi.c</title> + <para>Main file for the SCSI midlayer.</para> +!Edrivers/scsi/scsi.c + </sect2> + <sect2 id="scsicam.c"> + <title>drivers/scsi/scsicam.c</title> + <para> + <ulink url='http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf'>SCSI + Common Access Method</ulink> support functions, for use with + HDIO_GETGEO, etc. + </para> +!Edrivers/scsi/scsicam.c + </sect2> + <sect2 id="scsi_error.c"> + <title>drivers/scsi/scsi_error.c</title> + <para>Common SCSI error/timeout handling routines.</para> +!Edrivers/scsi/scsi_error.c + </sect2> + <sect2 id="scsi_devinfo.c"> + <title>drivers/scsi/scsi_devinfo.c</title> + <para> + Manage scsi_dev_info_list, which tracks blacklisted and whitelisted + devices. + </para> +!Idrivers/scsi/scsi_devinfo.c + </sect2> + <sect2 id="scsi_ioctl.c"> + <title>drivers/scsi/scsi_ioctl.c</title> + <para> + Handle ioctl() calls for SCSI devices. + </para> +!Edrivers/scsi/scsi_ioctl.c + </sect2> + <sect2 id="scsi_lib.c"> + <title>drivers/scsi/scsi_lib.c</title> + <para> + SCSI queuing library. + </para> +!Edrivers/scsi/scsi_lib.c + </sect2> + <sect2 id="scsi_lib_dma.c"> + <title>drivers/scsi/scsi_lib_dma.c</title> + <para> + SCSI library functions depending on DMA + (map and unmap scatter-gather lists). + </para> +!Edrivers/scsi/scsi_lib_dma.c + </sect2> + <sect2 id="scsi_module.c"> + <title>drivers/scsi/scsi_module.c</title> + <para> + The file drivers/scsi/scsi_module.c contains legacy support for + old-style host templates. It should never be used by any new driver. + </para> + </sect2> + <sect2 id="scsi_proc.c"> + <title>drivers/scsi/scsi_proc.c</title> + <para> + The functions in this file provide an interface between + the PROC file system and the SCSI device drivers + It is mainly used for debugging, statistics and to pass + information directly to the lowlevel driver. + + I.E. plumbing to manage /proc/scsi/* + </para> +!Idrivers/scsi/scsi_proc.c + </sect2> + <sect2 id="scsi_netlink.c"> + <title>drivers/scsi/scsi_netlink.c</title> + <para> + Infrastructure to provide async events from transports to userspace + via netlink, using a single NETLINK_SCSITRANSPORT protocol for all + transports. + + See <ulink url='http://marc.info/?l=linux-scsi&m=115507374832500&w=2'>the + original patch submission</ulink> for more details. + </para> +!Idrivers/scsi/scsi_netlink.c + </sect2> + <sect2 id="scsi_scan.c"> + <title>drivers/scsi/scsi_scan.c</title> + <para> + Scan a host to determine which (if any) devices are attached. + + The general scanning/probing algorithm is as follows, exceptions are + made to it depending on device specific flags, compilation options, + and global variable (boot or module load time) settings. + + A specific LUN is scanned via an INQUIRY command; if the LUN has a + device attached, a scsi_device is allocated and setup for it. + + For every id of every channel on the given host, start by scanning + LUN 0. Skip hosts that don't respond at all to a scan of LUN 0. + Otherwise, if LUN 0 has a device attached, allocate and setup a + scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN, + and scan all of the LUNs returned by the REPORT LUN; else, + sequentially scan LUNs up until some maximum is reached, or a LUN is + seen that cannot have a device attached to it. + </para> +!Idrivers/scsi/scsi_scan.c + </sect2> + <sect2 id="scsi_sysctl.c"> + <title>drivers/scsi/scsi_sysctl.c</title> + <para> + Set up the sysctl entry: "/dev/scsi/logging_level" + (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level. + </para> + </sect2> + <sect2 id="scsi_sysfs.c"> + <title>drivers/scsi/scsi_sysfs.c</title> + <para> + SCSI sysfs interface routines. + </para> +!Edrivers/scsi/scsi_sysfs.c + </sect2> + <sect2 id="hosts.c"> + <title>drivers/scsi/hosts.c</title> + <para> + mid to lowlevel SCSI driver interface + </para> +!Edrivers/scsi/hosts.c + </sect2> + <sect2 id="constants.c"> + <title>drivers/scsi/constants.c</title> + <para> + mid to lowlevel SCSI driver interface + </para> +!Edrivers/scsi/constants.c + </sect2> + </sect1> + + <sect1 id="Transport_classes"> + <title>Transport classes</title> + <para> + Transport classes are service libraries for drivers in the SCSI + lower layer, which expose transport attributes in sysfs. + </para> + <sect2 id="Fibre_Channel_transport"> + <title>Fibre Channel transport</title> + <para> + The file drivers/scsi/scsi_transport_fc.c defines transport attributes + for Fibre Channel. + </para> +!Edrivers/scsi/scsi_transport_fc.c + </sect2> + <sect2 id="iSCSI_transport"> + <title>iSCSI transport class</title> + <para> + The file drivers/scsi/scsi_transport_iscsi.c defines transport + attributes for the iSCSI class, which sends SCSI packets over TCP/IP + connections. + </para> +!Edrivers/scsi/scsi_transport_iscsi.c + </sect2> + <sect2 id="SAS_transport"> + <title>Serial Attached SCSI (SAS) transport class</title> + <para> + The file drivers/scsi/scsi_transport_sas.c defines transport + attributes for Serial Attached SCSI, a variant of SATA aimed at + large high-end systems. + </para> + <para> + The SAS transport class contains common code to deal with SAS HBAs, + an aproximated representation of SAS topologies in the driver model, + and various sysfs attributes to expose these topologies and management + interfaces to userspace. + </para> + <para> + In addition to the basic SCSI core objects this transport class + introduces two additional intermediate objects: The SAS PHY + as represented by struct sas_phy defines an "outgoing" PHY on + a SAS HBA or Expander, and the SAS remote PHY represented by + struct sas_rphy defines an "incoming" PHY on a SAS Expander or + end device. Note that this is purely a software concept, the + underlying hardware for a PHY and a remote PHY is the exactly + the same. + </para> + <para> + There is no concept of a SAS port in this code, users can see + what PHYs form a wide port based on the port_identifier attribute, + which is the same for all PHYs in a port. + </para> +!Edrivers/scsi/scsi_transport_sas.c + </sect2> + <sect2 id="SATA_transport"> + <title>SATA transport class</title> + <para> + The SATA transport is handled by libata, which has its own book of + documentation in this directory. + </para> + </sect2> + <sect2 id="SPI_transport"> + <title>Parallel SCSI (SPI) transport class</title> + <para> + The file drivers/scsi/scsi_transport_spi.c defines transport + attributes for traditional (fast/wide/ultra) SCSI busses. + </para> +!Edrivers/scsi/scsi_transport_spi.c + </sect2> + <sect2 id="SRP_transport"> + <title>SCSI RDMA (SRP) transport class</title> + <para> + The file drivers/scsi/scsi_transport_srp.c defines transport + attributes for SCSI over Remote Direct Memory Access. + </para> +!Edrivers/scsi/scsi_transport_srp.c + </sect2> + </sect1> + + </chapter> + + <chapter id="lower_layer"> + <title>SCSI lower layer</title> + <sect1 id="hba_drivers"> + <title>Host Bus Adapter transport types</title> + <para> + Many modern device controllers use the SCSI command set as a protocol to + communicate with their devices through many different types of physical + connections. + </para> + <para> + In SCSI language a bus capable of carrying SCSI commands is + called a "transport", and a controller connecting to such a bus is + called a "host bus adapter" (HBA). + </para> + <sect2 id="scsi_debug.c"> + <title>Debug transport</title> + <para> + The file drivers/scsi/scsi_debug.c simulates a host adapter with a + variable number of disks (or disk like devices) attached, sharing a + common amount of RAM. Does a lot of checking to make sure that we are + not getting blocks mixed up, and panics the kernel if anything out of + the ordinary is seen. + </para> + <para> + To be more realistic, the simulated devices have the transport + attributes of SAS disks. + </para> + <para> + For documentation see + <ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink> + </para> +<!-- !Edrivers/scsi/scsi_debug.c --> + </sect2> + <sect2 id="todo"> + <title>todo</title> + <para>Parallel (fast/wide/ultra) SCSI, USB, SATA, + SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband, + I20, iSCSI, Parallel ports, netlink... + </para> + </sect2> + </sect1> + </chapter> +</book>
diff --git a/Documentation/DocBook/sh.tmpl b/Documentation/DocBook/sh.tmpl new file mode 100644 index 0000000..4a38f60 --- /dev/null +++ b/Documentation/DocBook/sh.tmpl
@@ -0,0 +1,105 @@ +<?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="sh-drivers"> + <bookinfo> + <title>SuperH Interfaces Guide</title> + + <authorgroup> + <author> + <firstname>Paul</firstname> + <surname>Mundt</surname> + <affiliation> + <address> + <email>lethal@linux-sh.org</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008-2010</year> + <holder>Paul Mundt</holder> + </copyright> + <copyright> + <year>2008-2010</year> + <holder>Renesas Technology Corp.</holder> + </copyright> + <copyright> + <year>2010</year> + <holder>Renesas Electronics Corp.</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="mm"> + <title>Memory Management</title> + <sect1 id="sh4"> + <title>SH-4</title> + <sect2 id="sq"> + <title>Store Queue API</title> +!Earch/sh/kernel/cpu/sh4/sq.c + </sect2> + </sect1> + <sect1 id="sh5"> + <title>SH-5</title> + <sect2 id="tlb"> + <title>TLB Interfaces</title> +!Iarch/sh/mm/tlb-sh5.c +!Iarch/sh/include/asm/tlb_64.h + </sect2> + </sect1> + </chapter> + <chapter id="mach"> + <title>Machine Specific Interfaces</title> + <sect1 id="dreamcast"> + <title>mach-dreamcast</title> +!Iarch/sh/boards/mach-dreamcast/rtc.c + </sect1> + <sect1 id="x3proto"> + <title>mach-x3proto</title> +!Earch/sh/boards/mach-x3proto/ilsel.c + </sect1> + </chapter> + <chapter id="busses"> + <title>Busses</title> + <sect1 id="superhyway"> + <title>SuperHyway</title> +!Edrivers/sh/superhyway/superhyway.c + </sect1> + + <sect1 id="maple"> + <title>Maple</title> +!Edrivers/sh/maple/maple.c + </sect1> + </chapter> +</book>
diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl new file mode 100644 index 0000000..3bf4ecf --- /dev/null +++ b/Documentation/DocBook/stylesheet.xsl
@@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> +<param name="chunk.quietly">1</param> +<param name="funcsynopsis.style">ansi</param> +<param name="funcsynopsis.tabular.threshold">80</param> +<param name="callout.graphics">0</param> +<!-- <param name="paper.type">A4</param> --> +<param name="generate.consistent.ids">1</param> +<param name="generate.section.toc.level">2</param> +<param name="use.id.as.filename">1</param> +</stylesheet>
diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl new file mode 100644 index 0000000..b57a9ed --- /dev/null +++ b/Documentation/DocBook/tracepoint.tmpl
@@ -0,0 +1,112 @@ +<?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="Tracepoints"> + <bookinfo> + <title>The Linux Kernel Tracepoint API</title> + + <authorgroup> + <author> + <firstname>Jason</firstname> + <surname>Baron</surname> + <affiliation> + <address> + <email>jbaron@redhat.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>William</firstname> + <surname>Cohen</surname> + <affiliation> + <address> + <email>wcohen@redhat.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <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> + Tracepoints are static probe points that are located in strategic points + throughout the kernel. 'Probes' register/unregister with tracepoints + via a callback mechanism. The 'probes' are strictly typed functions that + are passed a unique set of parameters defined by each tracepoint. + </para> + + <para> + From this simple callback mechanism, 'probes' can be used to profile, debug, + and understand kernel behavior. There are a number of tools that provide a + framework for using 'probes'. These tools include Systemtap, ftrace, and + LTTng. + </para> + + <para> + Tracepoints are defined in a number of header files via various macros. Thus, + the purpose of this document is to provide a clear accounting of the available + tracepoints. The intention is to understand not only what tracepoints are + available but also to understand where future tracepoints might be added. + </para> + + <para> + The API presented has functions of the form: + <function>trace_tracepointname(function parameters)</function>. These are the + tracepoints callbacks that are found throughout the code. Registering and + unregistering probes with these callback sites is covered in the + <filename>Documentation/trace/*</filename> directory. + </para> + </chapter> + + <chapter id="irq"> + <title>IRQ</title> +!Iinclude/trace/events/irq.h + </chapter> + + <chapter id="signal"> + <title>SIGNAL</title> +!Iinclude/trace/events/signal.h + </chapter> + + <chapter id="block"> + <title>Block IO</title> +!Iinclude/trace/events/block.h + </chapter> + + <chapter id="workqueue"> + <title>Workqueue</title> +!Iinclude/trace/events/workqueue.h + </chapter> +</book>
diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl new file mode 100644 index 0000000..cd0e452 --- /dev/null +++ b/Documentation/DocBook/uio-howto.tmpl
@@ -0,0 +1,1050 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []> + +<book id="index"> +<bookinfo> +<title>The Userspace I/O HOWTO</title> + +<author> + <firstname>Hans-Jürgen</firstname> + <surname>Koch</surname> + <authorblurb><para>Linux developer, Linutronix</para></authorblurb> + <affiliation> + <orgname> + <ulink url="http://www.linutronix.de">Linutronix</ulink> + </orgname> + + <address> + <email>hjk@hansjkoch.de</email> + </address> + </affiliation> +</author> + +<copyright> + <year>2006-2008</year> + <holder>Hans-Jürgen Koch.</holder> +</copyright> +<copyright> + <year>2009</year> + <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> +</copyright> + +<legalnotice> +<para> +This documentation is Free Software licensed under the terms of the +GPL version 2. +</para> +</legalnotice> + +<pubdate>2006-12-11</pubdate> + +<abstract> + <para>This HOWTO describes concept and usage of Linux kernel's + Userspace I/O system.</para> +</abstract> + +<revhistory> + <revision> + <revnumber>0.9</revnumber> + <date>2009-07-16</date> + <authorinitials>mst</authorinitials> + <revremark>Added generic pci driver + </revremark> + </revision> + <revision> + <revnumber>0.8</revnumber> + <date>2008-12-24</date> + <authorinitials>hjk</authorinitials> + <revremark>Added name attributes in mem and portio sysfs directories. + </revremark> + </revision> + <revision> + <revnumber>0.7</revnumber> + <date>2008-12-23</date> + <authorinitials>hjk</authorinitials> + <revremark>Added generic platform drivers and offset attribute.</revremark> + </revision> + <revision> + <revnumber>0.6</revnumber> + <date>2008-12-05</date> + <authorinitials>hjk</authorinitials> + <revremark>Added description of portio sysfs attributes.</revremark> + </revision> + <revision> + <revnumber>0.5</revnumber> + <date>2008-05-22</date> + <authorinitials>hjk</authorinitials> + <revremark>Added description of write() function.</revremark> + </revision> + <revision> + <revnumber>0.4</revnumber> + <date>2007-11-26</date> + <authorinitials>hjk</authorinitials> + <revremark>Removed section about uio_dummy.</revremark> + </revision> + <revision> + <revnumber>0.3</revnumber> + <date>2007-04-29</date> + <authorinitials>hjk</authorinitials> + <revremark>Added section about userspace drivers.</revremark> + </revision> + <revision> + <revnumber>0.2</revnumber> + <date>2007-02-13</date> + <authorinitials>hjk</authorinitials> + <revremark>Update after multiple mappings were added.</revremark> + </revision> + <revision> + <revnumber>0.1</revnumber> + <date>2006-12-11</date> + <authorinitials>hjk</authorinitials> + <revremark>First draft.</revremark> + </revision> +</revhistory> +</bookinfo> + +<chapter id="aboutthisdoc"> +<?dbhtml filename="aboutthis.html"?> +<title>About this document</title> + +<sect1 id="translations"> +<?dbhtml filename="translations.html"?> +<title>Translations</title> + +<para>If you know of any translations for this document, or you are +interested in translating it, please email me +<email>hjk@hansjkoch.de</email>. +</para> +</sect1> + +<sect1 id="preface"> +<title>Preface</title> + <para> + For many types of devices, creating a Linux kernel driver is + overkill. All that is really needed is some way to handle an + interrupt and provide access to the memory space of the + device. The logic of controlling the device does not + necessarily have to be within the kernel, as the device does + not need to take advantage of any of other resources that the + kernel provides. One such common class of devices that are + like this are for industrial I/O cards. + </para> + <para> + To address this situation, the userspace I/O system (UIO) was + designed. For typical industrial I/O cards, only a very small + kernel module is needed. The main part of the driver will run in + user space. This simplifies development and reduces the risk of + serious bugs within a kernel module. + </para> + <para> + Please note that UIO is not an universal driver interface. Devices + that are already handled well by other kernel subsystems (like + networking or serial or USB) are no candidates for an UIO driver. + Hardware that is ideally suited for an UIO driver fulfills all of + the following: + </para> +<itemizedlist> +<listitem> + <para>The device has memory that can be mapped. The device can be + controlled completely by writing to this memory.</para> +</listitem> +<listitem> + <para>The device usually generates interrupts.</para> +</listitem> +<listitem> + <para>The device does not fit into one of the standard kernel + subsystems.</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="thanks"> +<title>Acknowledgments</title> + <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of + Linutronix, who have not only written most of the UIO code, but also + helped greatly writing this HOWTO by giving me all kinds of background + information.</para> +</sect1> + +<sect1 id="feedback"> +<title>Feedback</title> + <para>Find something wrong with this document? (Or perhaps something + right?) I would love to hear from you. Please email me at + <email>hjk@hansjkoch.de</email>.</para> +</sect1> +</chapter> + +<chapter id="about"> +<?dbhtml filename="about.html"?> +<title>About UIO</title> + +<para>If you use UIO for your card's driver, here's what you get:</para> + +<itemizedlist> +<listitem> + <para>only one small kernel module to write and maintain.</para> +</listitem> +<listitem> + <para>develop the main part of your driver in user space, + with all the tools and libraries you're used to.</para> +</listitem> +<listitem> + <para>bugs in your driver won't crash the kernel.</para> +</listitem> +<listitem> + <para>updates of your driver can take place without recompiling + the kernel.</para> +</listitem> +</itemizedlist> + +<sect1 id="how_uio_works"> +<title>How UIO works</title> + <para> + Each UIO device is accessed through a device file and several + sysfs attribute files. The device file will be called + <filename>/dev/uio0</filename> for the first device, and + <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> + and so on for subsequent devices. + </para> + + <para><filename>/dev/uioX</filename> is used to access the + address space of the card. Just use + <function>mmap()</function> to access registers or RAM + locations of your card. + </para> + + <para> + Interrupts are handled by reading from + <filename>/dev/uioX</filename>. A blocking + <function>read()</function> from + <filename>/dev/uioX</filename> will return as soon as an + interrupt occurs. You can also use + <function>select()</function> on + <filename>/dev/uioX</filename> to wait for an interrupt. The + integer value read from <filename>/dev/uioX</filename> + represents the total interrupt count. You can use this number + to figure out if you missed some interrupts. + </para> + <para> + For some hardware that has more than one interrupt source internally, + but not separate IRQ mask and status registers, there might be + situations where userspace cannot determine what the interrupt source + was if the kernel handler disables them by writing to the chip's IRQ + register. In such a case, the kernel has to disable the IRQ completely + to leave the chip's register untouched. Now the userspace part can + determine the cause of the interrupt, but it cannot re-enable + interrupts. Another cornercase is chips where re-enabling interrupts + is a read-modify-write operation to a combined IRQ status/acknowledge + register. This would be racy if a new interrupt occurred + simultaneously. + </para> + <para> + To address these problems, UIO also implements a write() function. It + is normally not used and can be ignored for hardware that has only a + single interrupt source or has separate IRQ mask and status registers. + If you need it, however, a write to <filename>/dev/uioX</filename> + will call the <function>irqcontrol()</function> function implemented + by the driver. You have to write a 32-bit value that is usually either + 0 or 1 to disable or enable interrupts. If a driver does not implement + <function>irqcontrol()</function>, <function>write()</function> will + return with <varname>-ENOSYS</varname>. + </para> + + <para> + To handle interrupts properly, your custom kernel module can + provide its own interrupt handler. It will automatically be + called by the built-in handler. + </para> + + <para> + For cards that don't generate interrupts but need to be + polled, there is the possibility to set up a timer that + triggers the interrupt handler at configurable time intervals. + This interrupt simulation is done by calling + <function>uio_event_notify()</function> + from the timer's event handler. + </para> + + <para> + Each driver provides attributes that are used to read or write + variables. These attributes are accessible through sysfs + files. A custom kernel driver module can add its own + attributes to the device owned by the uio driver, but not added + to the UIO device itself at this time. This might change in the + future if it would be found to be useful. + </para> + + <para> + The following standard attributes are provided by the UIO + framework: + </para> +<itemizedlist> +<listitem> + <para> + <filename>name</filename>: The name of your device. It is + recommended to use the name of your kernel module for this. + </para> +</listitem> +<listitem> + <para> + <filename>version</filename>: A version string defined by your + driver. This allows the user space part of your driver to deal + with different versions of the kernel module. + </para> +</listitem> +<listitem> + <para> + <filename>event</filename>: The total number of interrupts + handled by the driver since the last time the device node was + read. + </para> +</listitem> +</itemizedlist> +<para> + These attributes appear under the + <filename>/sys/class/uio/uioX</filename> directory. Please + note that this directory might be a symlink, and not a real + directory. Any userspace code that accesses it must be able + to handle this. +</para> +<para> + Each UIO device can make one or more memory regions available for + memory mapping. This is necessary because some industrial I/O cards + require access to more than one PCI memory region in a driver. +</para> +<para> + Each mapping has its own directory in sysfs, the first mapping + appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. + Subsequent mappings create directories <filename>map1/</filename>, + <filename>map2/</filename>, and so on. These directories will only + appear if the size of the mapping is not 0. +</para> +<para> + Each <filename>mapX/</filename> directory contains four read-only files + that show attributes of the memory: +</para> +<itemizedlist> +<listitem> + <para> + <filename>name</filename>: A string identifier for this mapping. This + is optional, the string can be empty. Drivers can set this to make it + easier for userspace to find the correct mapping. + </para> +</listitem> +<listitem> + <para> + <filename>addr</filename>: The address of memory that can be mapped. + </para> +</listitem> +<listitem> + <para> + <filename>size</filename>: The size, in bytes, of the memory + pointed to by addr. + </para> +</listitem> +<listitem> + <para> + <filename>offset</filename>: The offset, in bytes, that has to be + added to the pointer returned by <function>mmap()</function> to get + to the actual device memory. This is important if the device's memory + is not page aligned. Remember that pointers returned by + <function>mmap()</function> are always page aligned, so it is good + style to always add this offset. + </para> +</listitem> +</itemizedlist> + +<para> + From userspace, the different mappings are distinguished by adjusting + the <varname>offset</varname> parameter of the + <function>mmap()</function> call. To map the memory of mapping N, you + have to use N times the page size as your offset: +</para> +<programlisting format="linespecific"> +offset = N * getpagesize(); +</programlisting> + +<para> + Sometimes there is hardware with memory-like regions that can not be + mapped with the technique described here, but there are still ways to + access them from userspace. The most common example are x86 ioports. + On x86 systems, userspace can access these ioports using + <function>ioperm()</function>, <function>iopl()</function>, + <function>inb()</function>, <function>outb()</function>, and similar + functions. +</para> +<para> + Since these ioport regions can not be mapped, they will not appear under + <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory + described above. Without information about the port regions a hardware + has to offer, it becomes difficult for the userspace part of the + driver to find out which ports belong to which UIO device. +</para> +<para> + To address this situation, the new directory + <filename>/sys/class/uio/uioX/portio/</filename> was added. It only + exists if the driver wants to pass information about one or more port + regions to userspace. If that is the case, subdirectories named + <filename>port0</filename>, <filename>port1</filename>, and so on, + will appear underneath + <filename>/sys/class/uio/uioX/portio/</filename>. +</para> +<para> + Each <filename>portX/</filename> directory contains four read-only + files that show name, start, size, and type of the port region: +</para> +<itemizedlist> +<listitem> + <para> + <filename>name</filename>: A string identifier for this port region. + The string is optional and can be empty. Drivers can set it to make it + easier for userspace to find a certain port region. + </para> +</listitem> +<listitem> + <para> + <filename>start</filename>: The first port of this region. + </para> +</listitem> +<listitem> + <para> + <filename>size</filename>: The number of ports in this region. + </para> +</listitem> +<listitem> + <para> + <filename>porttype</filename>: A string describing the type of port. + </para> +</listitem> +</itemizedlist> + + +</sect1> +</chapter> + +<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> +<?dbhtml filename="custom_kernel_module.html"?> +<title>Writing your own kernel module</title> + <para> + Please have a look at <filename>uio_cif.c</filename> as an + example. The following paragraphs explain the different + sections of this file. + </para> + +<sect1 id="uio_info"> +<title>struct uio_info</title> + <para> + This structure tells the framework the details of your driver, + Some of the members are required, others are optional. + </para> + +<itemizedlist> +<listitem><para> +<varname>const char *name</varname>: Required. The name of your driver as +it will appear in sysfs. I recommend using the name of your module for this. +</para></listitem> + +<listitem><para> +<varname>const char *version</varname>: Required. This string appears in +<filename>/sys/class/uio/uioX/version</filename>. +</para></listitem> + +<listitem><para> +<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you +have memory that can be mapped with <function>mmap()</function>. For each +mapping you need to fill one of the <varname>uio_mem</varname> structures. +See the description below for details. +</para></listitem> + +<listitem><para> +<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required +if you want to pass information about ioports to userspace. For each port +region you need to fill one of the <varname>uio_port</varname> structures. +See the description below for details. +</para></listitem> + +<listitem><para> +<varname>long irq</varname>: Required. If your hardware generates an +interrupt, it's your modules task to determine the irq number during +initialization. If you don't have a hardware generated interrupt but +want to trigger the interrupt handler in some other way, set +<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. +If you had no interrupt at all, you could set +<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this +rarely makes sense. +</para></listitem> + +<listitem><para> +<varname>unsigned long irq_flags</varname>: Required if you've set +<varname>irq</varname> to a hardware interrupt number. The flags given +here will be used in the call to <function>request_irq()</function>. +</para></listitem> + +<listitem><para> +<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct +*vma)</varname>: Optional. If you need a special +<function>mmap()</function> function, you can set it here. If this +pointer is not NULL, your <function>mmap()</function> will be called +instead of the built-in one. +</para></listitem> + +<listitem><para> +<varname>int (*open)(struct uio_info *info, struct inode *inode) +</varname>: Optional. You might want to have your own +<function>open()</function>, e.g. to enable interrupts only when your +device is actually used. +</para></listitem> + +<listitem><para> +<varname>int (*release)(struct uio_info *info, struct inode *inode) +</varname>: Optional. If you define your own +<function>open()</function>, you will probably also want a custom +<function>release()</function> function. +</para></listitem> + +<listitem><para> +<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) +</varname>: Optional. If you need to be able to enable or disable +interrupts from userspace by writing to <filename>/dev/uioX</filename>, +you can implement this function. The parameter <varname>irq_on</varname> +will be 0 to disable interrupts and 1 to enable them. +</para></listitem> +</itemizedlist> + +<para> +Usually, your device will have one or more memory regions that can be mapped +to user space. For each region, you have to set up a +<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. +Here's a description of the fields of <varname>struct uio_mem</varname>: +</para> + +<itemizedlist> +<listitem><para> +<varname>const char *name</varname>: Optional. Set this to help identify +the memory region, it will show up in the corresponding sysfs node. +</para></listitem> + +<listitem><para> +<varname>int memtype</varname>: Required if the mapping is used. Set this to +<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your +card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical +memory (e.g. allocated with <function>kmalloc()</function>). There's also +<varname>UIO_MEM_VIRTUAL</varname> for virtual memory. +</para></listitem> + +<listitem><para> +<varname>phys_addr_t addr</varname>: Required if the mapping is used. +Fill in the address of your memory block. This address is the one that +appears in sysfs. +</para></listitem> + +<listitem><para> +<varname>resource_size_t size</varname>: Fill in the size of the +memory block that <varname>addr</varname> points to. If <varname>size</varname> +is zero, the mapping is considered unused. Note that you +<emphasis>must</emphasis> initialize <varname>size</varname> with zero for +all unused mappings. +</para></listitem> + +<listitem><para> +<varname>void *internal_addr</varname>: If you have to access this memory +region from within your kernel module, you will want to map it internally by +using something like <function>ioremap()</function>. Addresses +returned by this function cannot be mapped to user space, so you must not +store it in <varname>addr</varname>. Use <varname>internal_addr</varname> +instead to remember such an address. +</para></listitem> +</itemizedlist> + +<para> +Please do not touch the <varname>map</varname> element of +<varname>struct uio_mem</varname>! It is used by the UIO framework +to set up sysfs files for this mapping. Simply leave it alone. +</para> + +<para> +Sometimes, your device can have one or more port regions which can not be +mapped to userspace. But if there are other possibilities for userspace to +access these ports, it makes sense to make information about the ports +available in sysfs. For each region, you have to set up a +<varname>struct uio_port</varname> in the <varname>port[]</varname> array. +Here's a description of the fields of <varname>struct uio_port</varname>: +</para> + +<itemizedlist> +<listitem><para> +<varname>char *porttype</varname>: Required. Set this to one of the predefined +constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 +architectures. +</para></listitem> + +<listitem><para> +<varname>unsigned long start</varname>: Required if the port region is used. +Fill in the number of the first port of this region. +</para></listitem> + +<listitem><para> +<varname>unsigned long size</varname>: Fill in the number of ports in this +region. If <varname>size</varname> is zero, the region is considered unused. +Note that you <emphasis>must</emphasis> initialize <varname>size</varname> +with zero for all unused regions. +</para></listitem> +</itemizedlist> + +<para> +Please do not touch the <varname>portio</varname> element of +<varname>struct uio_port</varname>! It is used internally by the UIO +framework to set up sysfs files for this region. Simply leave it alone. +</para> + +</sect1> + +<sect1 id="adding_irq_handler"> +<title>Adding an interrupt handler</title> + <para> + What you need to do in your interrupt handler depends on your + hardware and on how you want to handle it. You should try to + keep the amount of code in your kernel interrupt handler low. + If your hardware requires no action that you + <emphasis>have</emphasis> to perform after each interrupt, + then your handler can be empty.</para> <para>If, on the other + hand, your hardware <emphasis>needs</emphasis> some action to + be performed after each interrupt, then you + <emphasis>must</emphasis> do it in your kernel module. Note + that you cannot rely on the userspace part of your driver. Your + userspace program can terminate at any time, possibly leaving + your hardware in a state where proper interrupt handling is + still required. + </para> + + <para> + There might also be applications where you want to read data + from your hardware at each interrupt and buffer it in a piece + of kernel memory you've allocated for that purpose. With this + technique you could avoid loss of data if your userspace + program misses an interrupt. + </para> + + <para> + A note on shared interrupts: Your driver should support + interrupt sharing whenever this is possible. It is possible if + and only if your driver can detect whether your hardware has + triggered the interrupt or not. This is usually done by looking + at an interrupt status register. If your driver sees that the + IRQ bit is actually set, it will perform its actions, and the + handler returns IRQ_HANDLED. If the driver detects that it was + not your hardware that caused the interrupt, it will do nothing + and return IRQ_NONE, allowing the kernel to call the next + possible interrupt handler. + </para> + + <para> + If you decide not to support shared interrupts, your card + won't work in computers with no free interrupts. As this + frequently happens on the PC platform, you can save yourself a + lot of trouble by supporting interrupt sharing. + </para> +</sect1> + +<sect1 id="using_uio_pdrv"> +<title>Using uio_pdrv for platform devices</title> + <para> + In many cases, UIO drivers for platform devices can be handled in a + generic way. In the same place where you define your + <varname>struct platform_device</varname>, you simply also implement + your interrupt handler and fill your + <varname>struct uio_info</varname>. A pointer to this + <varname>struct uio_info</varname> is then used as + <varname>platform_data</varname> for your platform device. + </para> + <para> + You also need to set up an array of <varname>struct resource</varname> + containing addresses and sizes of your memory mappings. This + information is passed to the driver using the + <varname>.resource</varname> and <varname>.num_resources</varname> + elements of <varname>struct platform_device</varname>. + </para> + <para> + You now have to set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_pdrv"</varname> to use the generic UIO platform device + driver. This driver will fill the <varname>mem[]</varname> array + according to the resources given, and register the device. + </para> + <para> + The advantage of this approach is that you only have to edit a file + you need to edit anyway. You do not have to create an extra driver. + </para> +</sect1> + +<sect1 id="using_uio_pdrv_genirq"> +<title>Using uio_pdrv_genirq for platform devices</title> + <para> + Especially in embedded devices, you frequently find chips where the + irq pin is tied to its own dedicated interrupt line. In such cases, + where you can be really sure the interrupt is not shared, we can take + the concept of <varname>uio_pdrv</varname> one step further and use a + generic interrupt handler. That's what + <varname>uio_pdrv_genirq</varname> does. + </para> + <para> + The setup for this driver is the same as described above for + <varname>uio_pdrv</varname>, except that you do not implement an + interrupt handler. The <varname>.handler</varname> element of + <varname>struct uio_info</varname> must remain + <varname>NULL</varname>. The <varname>.irq_flags</varname> element + must not contain <varname>IRQF_SHARED</varname>. + </para> + <para> + You will set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_pdrv_genirq"</varname> to use this driver. + </para> + <para> + The generic interrupt handler of <varname>uio_pdrv_genirq</varname> + will simply disable the interrupt line using + <function>disable_irq_nosync()</function>. After doing its work, + userspace can reenable the interrupt by writing 0x00000001 to the UIO + device file. The driver already implements an + <function>irq_control()</function> to make this possible, you must not + implement your own. + </para> + <para> + Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of + interrupt handler code. You also do not need to know anything about + the chip's internal registers to create the kernel part of the driver. + All you need to know is the irq number of the pin the chip is + connected to. + </para> +</sect1> + +<sect1 id="using-uio_dmem_genirq"> +<title>Using uio_dmem_genirq for platform devices</title> + <para> + In addition to statically allocated memory ranges, they may also be + a desire to use dynamically allocated regions in a user space driver. + In particular, being able to access memory made available through the + dma-mapping API, may be particularly useful. The + <varname>uio_dmem_genirq</varname> driver provides a way to accomplish + this. + </para> + <para> + This driver is used in a similar manner to the + <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt + configuration and handling. + </para> + <para> + Set the <varname>.name</varname> element of + <varname>struct platform_device</varname> to + <varname>"uio_dmem_genirq"</varname> to use this driver. + </para> + <para> + When using this driver, fill in the <varname>.platform_data</varname> + element of <varname>struct platform_device</varname>, which is of type + <varname>struct uio_dmem_genirq_pdata</varname> and which contains the + following elements: + </para> + <itemizedlist> + <listitem><para><varname>struct uio_info uioinfo</varname>: The same + structure used as the <varname>uio_pdrv_genirq</varname> platform + data</para></listitem> + <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: + Pointer to list of sizes of dynamic memory regions to be mapped into + user space. + </para></listitem> + <listitem><para><varname>unsigned int num_dynamic_regions</varname>: + Number of elements in <varname>dynamic_region_sizes</varname> array. + </para></listitem> + </itemizedlist> + <para> + The dynamic regions defined in the platform data will be appended to + the <varname> mem[] </varname> array after the platform device + resources, which implies that the total number of static and dynamic + memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. + </para> + <para> + The dynamic memory regions will be allocated when the UIO device file, + <varname>/dev/uioX</varname> is opened. + Similar to static memory resources, the memory region information for + dynamic regions is then visible via sysfs at + <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. + The dynamic memory regions will be freed when the UIO device file is + closed. When no processes are holding the device file open, the address + returned to userspace is ~0. + </para> +</sect1> + +</chapter> + +<chapter id="userspace_driver" xreflabel="Writing a driver in user space"> +<?dbhtml filename="userspace_driver.html"?> +<title>Writing a driver in userspace</title> + <para> + Once you have a working kernel module for your hardware, you can + write the userspace part of your driver. You don't need any special + libraries, your driver can be written in any reasonable language, + you can use floating point numbers and so on. In short, you can + use all the tools and libraries you'd normally use for writing a + userspace application. + </para> + +<sect1 id="getting_uio_information"> +<title>Getting information about your UIO device</title> + <para> + Information about all UIO devices is available in sysfs. The + first thing you should do in your driver is check + <varname>name</varname> and <varname>version</varname> to + make sure your talking to the right device and that its kernel + driver has the version you expect. + </para> + <para> + You should also make sure that the memory mapping you need + exists and has the size you expect. + </para> + <para> + There is a tool called <varname>lsuio</varname> that lists + UIO devices and their attributes. It is available here: + </para> + <para> + <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> + http://www.osadl.org/projects/downloads/UIO/user/</ulink> + </para> + <para> + With <varname>lsuio</varname> you can quickly check if your + kernel module is loaded and which attributes it exports. + Have a look at the manpage for details. + </para> + <para> + The source code of <varname>lsuio</varname> can serve as an + example for getting information about an UIO device. + The file <filename>uio_helper.c</filename> contains a lot of + functions you could use in your userspace driver code. + </para> +</sect1> + +<sect1 id="mmap_device_memory"> +<title>mmap() device memory</title> + <para> + After you made sure you've got the right device with the + memory mappings you need, all you have to do is to call + <function>mmap()</function> to map the device's memory + to userspace. + </para> + <para> + The parameter <varname>offset</varname> of the + <function>mmap()</function> call has a special meaning + for UIO devices: It is used to select which mapping of + your device you want to map. To map the memory of + mapping N, you have to use N times the page size as + your offset: + </para> +<programlisting format="linespecific"> + offset = N * getpagesize(); +</programlisting> + <para> + N starts from zero, so if you've got only one memory + range to map, set <varname>offset = 0</varname>. + A drawback of this technique is that memory is always + mapped beginning with its start address. + </para> +</sect1> + +<sect1 id="wait_for_interrupts"> +<title>Waiting for interrupts</title> + <para> + After you successfully mapped your devices memory, you + can access it like an ordinary array. Usually, you will + perform some initialization. After that, your hardware + starts working and will generate an interrupt as soon + as it's finished, has some data available, or needs your + attention because an error occurred. + </para> + <para> + <filename>/dev/uioX</filename> is a read-only file. A + <function>read()</function> will always block until an + interrupt occurs. There is only one legal value for the + <varname>count</varname> parameter of + <function>read()</function>, and that is the size of a + signed 32 bit integer (4). Any other value for + <varname>count</varname> causes <function>read()</function> + to fail. The signed 32 bit integer read is the interrupt + count of your device. If the value is one more than the value + you read the last time, everything is OK. If the difference + is greater than one, you missed interrupts. + </para> + <para> + You can also use <function>select()</function> on + <filename>/dev/uioX</filename>. + </para> +</sect1> + +</chapter> + +<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> +<?dbhtml filename="uio_pci_generic.html"?> +<title>Generic PCI UIO driver</title> + <para> + The generic driver is a kernel module named uio_pci_generic. + It can work with any device compliant to PCI 2.3 (circa 2002) and + any compliant PCI Express device. Using this, you only need to + write the userspace driver, removing the need to write + a hardware-specific kernel module. + </para> + +<sect1 id="uio_pci_generic_binding"> +<title>Making the driver recognize the device</title> + <para> +Since the driver does not declare any device ids, it will not get loaded +automatically and will not automatically bind to any devices, you must load it +and allocate id to the driver yourself. For example: + <programlisting> + modprobe uio_pci_generic + echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id + </programlisting> + </para> + <para> +If there already is a hardware specific kernel driver for your device, the +generic driver still won't bind to it, in this case if you want to use the +generic driver (why would you?) you'll have to manually unbind the hardware +specific driver and bind the generic driver, like this: + <programlisting> + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind + </programlisting> + </para> + <para> +You can verify that the device has been bound to the driver +by looking for it in sysfs, for example like the following: + <programlisting> + ls -l /sys/bus/pci/devices/0000:00:19.0/driver + </programlisting> +Which if successful should print + <programlisting> + .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic + </programlisting> +Note that the generic driver will not bind to old PCI 2.2 devices. +If binding the device failed, run the following command: + <programlisting> + dmesg + </programlisting> +and look in the output for failure reasons + </para> +</sect1> + +<sect1 id="uio_pci_generic_internals"> +<title>Things to know about uio_pci_generic</title> + <para> +Interrupts are handled using the Interrupt Disable bit in the PCI command +register and Interrupt Status bit in the PCI status register. All devices +compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should +support these bits. uio_pci_generic detects this support, and won't bind to +devices which do not support the Interrupt Disable Bit in the command register. + </para> + <para> +On each interrupt, uio_pci_generic sets the Interrupt Disable bit. +This prevents the device from generating further interrupts +until the bit is cleared. The userspace driver should clear this +bit before blocking and waiting for more interrupts. + </para> +</sect1> +<sect1 id="uio_pci_generic_userspace"> +<title>Writing userspace driver using uio_pci_generic</title> + <para> +Userspace driver can use pci sysfs interface, or the +libpci libray that wraps it, to talk to the device and to +re-enable interrupts by writing to the command register. + </para> +</sect1> +<sect1 id="uio_pci_generic_example"> +<title>Example code using uio_pci_generic</title> + <para> +Here is some sample userspace driver code using uio_pci_generic: +<programlisting> +#include <stdlib.h> +#include <stdio.h> +#include <unistd.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> +#include <errno.h> + +int main() +{ + int uiofd; + int configfd; + int err; + int i; + unsigned icount; + unsigned char command_high; + + uiofd = open("/dev/uio0", O_RDONLY); + if (uiofd < 0) { + perror("uio open:"); + return errno; + } + configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); + if (configfd < 0) { + perror("config open:"); + return errno; + } + + /* Read and cache command value */ + err = pread(configfd, &command_high, 1, 5); + if (err != 1) { + perror("command config read:"); + return errno; + } + command_high &= ~0x4; + + for(i = 0;; ++i) { + /* Print out a message, for debugging. */ + if (i == 0) + fprintf(stderr, "Started uio test driver.\n"); + else + fprintf(stderr, "Interrupts: %d\n", icount); + + /****************************************/ + /* Here we got an interrupt from the + device. Do something to it. */ + /****************************************/ + + /* Re-enable interrupts. */ + err = pwrite(configfd, &command_high, 1, 5); + if (err != 1) { + perror("config write:"); + break; + } + + /* Wait for next interrupt. */ + err = read(uiofd, &icount, 4); + if (err != 4) { + perror("uio read:"); + break; + } + + } + return errno; +} + +</programlisting> + </para> +</sect1> + +</chapter> + +<appendix id="app1"> +<title>Further information</title> +<itemizedlist> + <listitem><para> + <ulink url="http://www.osadl.org"> + OSADL homepage.</ulink> + </para></listitem> + <listitem><para> + <ulink url="http://www.linutronix.de"> + Linutronix homepage.</ulink> + </para></listitem> +</itemizedlist> +</appendix> + +</book>
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl new file mode 100644 index 0000000..bc776be --- /dev/null +++ b/Documentation/DocBook/usb.tmpl
@@ -0,0 +1,992 @@ +<?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-USB-API"> + <bookinfo> + <title>The Linux-USB Host Side 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="intro"> + <title>Introduction to USB on Linux</title> + + <para>A Universal Serial Bus (USB) is used to connect a host, + such as a PC or workstation, to a number of peripheral + devices. USB uses a tree structure, with the host as the + root (the system's master), hubs as interior nodes, and + peripherals as leaves (and slaves). + Modern PCs support several such trees of USB devices, usually + one USB 2.0 tree (480 Mbit/sec each) with + a few USB 1.1 trees (12 Mbit/sec each) that are used when you + connect a USB 1.1 device directly to the machine's "root hub". + </para> + + <para>That master/slave asymmetry was designed-in for a number of + reasons, one being ease of use. It is not physically possible to + assemble (legal) USB cables incorrectly: all upstream "to the host" + connectors are the rectangular type (matching the sockets on + root hubs), and all downstream connectors are the squarish type + (or they are built into the peripheral). + Also, the host software doesn't need to deal with distributed + auto-configuration since the pre-designated master node manages all that. + And finally, at the electrical level, bus protocol overhead is reduced by + eliminating arbitration and moving scheduling into the host software. + </para> + + <para>USB 1.0 was announced in January 1996 and was revised + as USB 1.1 (with improvements in hub specification and + support for interrupt-out transfers) in September 1998. + USB 2.0 was released in April 2000, adding high-speed + transfers and transaction-translating hubs (used for USB 1.1 + and 1.0 backward compatibility). + </para> + + <para>Kernel developers added USB support to Linux early in the 2.2 kernel + series, shortly before 2.3 development forked. Updates from 2.3 were + regularly folded back into 2.2 releases, which improved reliability and + brought <filename>/sbin/hotplug</filename> support as well more drivers. + Such improvements were continued in the 2.5 kernel series, where they added + USB 2.0 support, improved performance, and made the host controller drivers + (HCDs) more consistent. They also simplified the API (to make bugs less + likely) and added internal "kerneldoc" documentation. + </para> + + <para>Linux can run inside USB devices as well as on + the hosts that control the devices. + But USB device drivers running inside those peripherals + don't do the same things as the ones running inside hosts, + so they've been given a different name: + <emphasis>gadget drivers</emphasis>. + This document does not cover gadget drivers. + </para> + + </chapter> + +<chapter id="host"> + <title>USB Host-Side API Model</title> + + <para>Host-side drivers for USB devices talk to the "usbcore" APIs. + There are two. One is intended for + <emphasis>general-purpose</emphasis> drivers (exposed through + driver frameworks), and the other is for drivers that are + <emphasis>part of the core</emphasis>. + Such core drivers include the <emphasis>hub</emphasis> driver + (which manages trees of USB devices) and several different kinds + of <emphasis>host controller drivers</emphasis>, + which control individual busses. + </para> + + <para>The device model seen by USB drivers is relatively complex. + </para> + + <itemizedlist> + + <listitem><para>USB supports four kinds of data transfers + (control, bulk, interrupt, and isochronous). Two of them (control + and bulk) use bandwidth as it's available, + while the other two (interrupt and isochronous) + are scheduled to provide guaranteed bandwidth. + </para></listitem> + + <listitem><para>The device description model includes one or more + "configurations" per device, only one of which is active at a time. + Devices that are capable of high-speed operation must also support + full-speed configurations, along with a way to ask about the + "other speed" configurations which might be used. + </para></listitem> + + <listitem><para>Configurations have one or more "interfaces", each + of which may have "alternate settings". Interfaces may be + standardized by USB "Class" specifications, or may be specific to + a vendor or device.</para> + + <para>USB device drivers actually bind to interfaces, not devices. + Think of them as "interface drivers", though you + may not see many devices where the distinction is important. + <emphasis>Most USB devices are simple, with only one configuration, + one interface, and one alternate setting.</emphasis> + </para></listitem> + + <listitem><para>Interfaces have one or more "endpoints", each of + which supports one type and direction of data transfer such as + "bulk out" or "interrupt in". The entire configuration may have + up to sixteen endpoints in each direction, allocated as needed + among all the interfaces. + </para></listitem> + + <listitem><para>Data transfer on USB is packetized; each endpoint + has a maximum packet size. + Drivers must often be aware of conventions such as flagging the end + of bulk transfers using "short" (including zero length) packets. + </para></listitem> + + <listitem><para>The Linux USB API supports synchronous calls for + control and bulk messages. + It also supports asynchronous calls for all kinds of data transfer, + using request structures called "URBs" (USB Request Blocks). + </para></listitem> + + </itemizedlist> + + <para>Accordingly, the USB Core API exposed to device drivers + covers quite a lot of territory. You'll probably need to consult + the USB 2.0 specification, available online from www.usb.org at + no cost, as well as class or device specifications. + </para> + + <para>The only host-side drivers that actually touch hardware + (reading/writing registers, handling IRQs, and so on) are the HCDs. + In theory, all HCDs provide the same functionality through the same + API. In practice, that's becoming more true on the 2.5 kernels, + but there are still differences that crop up especially with + fault handling. Different controllers don't necessarily report + the same aspects of failures, and recovery from faults (including + software-induced ones like unlinking an URB) isn't yet fully + consistent. + Device driver authors should make a point of doing disconnect + testing (while the device is active) with each different host + controller driver, to make sure drivers don't have bugs of + their own as well as to make sure they aren't relying on some + HCD-specific behavior. + (You will need external USB 1.1 and/or + USB 2.0 hubs to perform all those tests.) + </para> + + </chapter> + +<chapter id="types"><title>USB-Standard Types</title> + + <para>In <filename><linux/usb/ch9.h></filename> you will find + the USB data types defined in chapter 9 of the USB specification. + These data types are used throughout USB, and in APIs including + this host side API, gadget APIs, and usbfs. + </para> + +!Iinclude/linux/usb/ch9.h + + </chapter> + +<chapter id="hostside"><title>Host-Side Data Types and Macros</title> + + <para>The host side API exposes several layers to drivers, some of + which are more necessary than others. + These support lifecycle models for host side drivers + and devices, and support passing buffers through usbcore to + some HCD that performs the I/O for the device driver. + </para> + + +!Iinclude/linux/usb.h + + </chapter> + + <chapter id="usbcore"><title>USB Core APIs</title> + + <para>There are two basic I/O models in the USB API. + The most elemental one is asynchronous: drivers submit requests + in the form of an URB, and the URB's completion callback + handle the next step. + All USB transfer types support that model, although there + are special cases for control URBs (which always have setup + and status stages, but may not have a data stage) and + isochronous URBs (which allow large packets and include + per-packet fault reports). + Built on top of that is synchronous API support, where a + driver calls a routine that allocates one or more URBs, + submits them, and waits until they complete. + There are synchronous wrappers for single-buffer control + and bulk transfers (which are awkward to use in some + driver disconnect scenarios), and for scatterlist based + streaming i/o (bulk or interrupt). + </para> + + <para>USB drivers need to provide buffers that can be + used for DMA, although they don't necessarily need to + provide the DMA mapping themselves. + There are APIs to use used when allocating DMA buffers, + which can prevent use of bounce buffers on some systems. + In some cases, drivers may be able to rely on 64bit DMA + to eliminate another kind of bounce buffer. + </para> + +!Edrivers/usb/core/urb.c +!Edrivers/usb/core/message.c +!Edrivers/usb/core/file.c +!Edrivers/usb/core/driver.c +!Edrivers/usb/core/usb.c +!Edrivers/usb/core/hub.c + </chapter> + + <chapter id="hcd"><title>Host Controller APIs</title> + + <para>These APIs are only for use by host controller drivers, + most of which implement standard register interfaces such as + EHCI, OHCI, or UHCI. + UHCI was one of the first interfaces, designed by Intel and + also used by VIA; it doesn't do much in hardware. + OHCI was designed later, to have the hardware do more work + (bigger transfers, tracking protocol state, and so on). + EHCI was designed with USB 2.0; its design has features that + resemble OHCI (hardware does much more work) as well as + UHCI (some parts of ISO support, TD list processing). + </para> + + <para>There are host controllers other than the "big three", + although most PCI based controllers (and a few non-PCI based + ones) use one of those interfaces. + Not all host controllers use DMA; some use PIO, and there + is also a simulator. + </para> + + <para>The same basic APIs are available to drivers for all + those controllers. + For historical reasons they are in two layers: + <structname>struct usb_bus</structname> is a rather thin + layer that became available in the 2.2 kernels, while + <structname>struct usb_hcd</structname> is a more featureful + layer (available in later 2.4 kernels and in 2.5) that + lets HCDs share common code, to shrink driver size + and significantly reduce hcd-specific behaviors. + </para> + +!Edrivers/usb/core/hcd.c +!Edrivers/usb/core/hcd-pci.c +!Idrivers/usb/core/buffer.c + </chapter> + + <chapter id="usbfs"> + <title>The USB Filesystem (usbfs)</title> + + <para>This chapter presents the Linux <emphasis>usbfs</emphasis>. + You may prefer to avoid writing new kernel code for your + USB driver; that's the problem that usbfs set out to solve. + User mode device drivers are usually packaged as applications + or libraries, and may use usbfs through some programming library + that wraps it. Such libraries include + <ulink url="http://libusb.sourceforge.net">libusb</ulink> + for C/C++, and + <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java. + </para> + + <note><title>Unfinished</title> + <para>This particular documentation is incomplete, + especially with respect to the asynchronous mode. + As of kernel 2.5.66 the code and this (new) documentation + need to be cross-reviewed. + </para> + </note> + + <para>Configure usbfs into Linux kernels by enabling the + <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS), + and you get basic support for user mode USB device drivers. + Until relatively recently it was often (confusingly) called + <emphasis>usbdevfs</emphasis> although it wasn't solving what + <emphasis>devfs</emphasis> was. + Every USB device will appear in usbfs, regardless of whether or + not it has a kernel driver. + </para> + + <sect1 id="usbfs-files"> + <title>What files are in "usbfs"?</title> + + <para>Conventionally mounted at + <filename>/proc/bus/usb</filename>, usbfs + features include: + <itemizedlist> + <listitem><para><filename>/proc/bus/usb/devices</filename> + ... a text file + showing each of the USB devices on known to the kernel, + and their configuration descriptors. + You can also poll() this to learn about new devices. + </para></listitem> + <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename> + ... magic files + exposing the each device's configuration descriptors, and + supporting a series of ioctls for making device requests, + including I/O to devices. (Purely for access by programs.) + </para></listitem> + </itemizedlist> + </para> + + <para> Each bus is given a number (BBB) based on when it was + enumerated; within each bus, each device is given a similar + number (DDD). + Those BBB/DDD paths are not "stable" identifiers; + expect them to change even if you always leave the devices + plugged in to the same hub port. + <emphasis>Don't even think of saving these in application + configuration files.</emphasis> + Stable identifiers are available, for user mode applications + that want to use them. HID and networking devices expose + these stable IDs, so that for example you can be sure that + you told the right UPS to power down its second server. + "usbfs" doesn't (yet) expose those IDs. + </para> + + </sect1> + + <sect1 id="usbfs-fstab"> + <title>Mounting and Access Control</title> + + <para>There are a number of mount options for usbfs, which will + be of most interest to you if you need to override the default + access control policy. + That policy is that only root may read or write device files + (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read + the <filename>devices</filename> + or <filename>drivers</filename> files. + I/O requests to the device also need the CAP_SYS_RAWIO capability, + </para> + + <para>The significance of that is that by default, all user mode + device drivers need super-user privileges. + You can change modes or ownership in a driver setup + when the device hotplugs, or maye just start the + driver right then, as a privileged server (or some activity + within one). + That's the most secure approach for multi-user systems, + but for single user systems ("trusted" by that user) + it's more convenient just to grant everyone all access + (using the <emphasis>devmode=0666</emphasis> option) + so the driver can start whenever it's needed. + </para> + + <para>The mount options for usbfs, usable in /etc/fstab or + in command line invocations of <emphasis>mount</emphasis>, are: + + <variablelist> + <varlistentry> + <term><emphasis>busgid</emphasis>=NNNNN</term> + <listitem><para>Controls the GID used for the + /proc/bus/usb/BBB + directories. (Default: 0)</para></listitem></varlistentry> + <varlistentry><term><emphasis>busmode</emphasis>=MMM</term> + <listitem><para>Controls the file mode used for the + /proc/bus/usb/BBB + directories. (Default: 0555) + </para></listitem></varlistentry> + <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term> + <listitem><para>Controls the UID used for the + /proc/bus/usb/BBB + directories. (Default: 0)</para></listitem></varlistentry> + + <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term> + <listitem><para>Controls the GID used for the + /proc/bus/usb/BBB/DDD + files. (Default: 0)</para></listitem></varlistentry> + <varlistentry><term><emphasis>devmode</emphasis>=MMM</term> + <listitem><para>Controls the file mode used for the + /proc/bus/usb/BBB/DDD + files. (Default: 0644)</para></listitem></varlistentry> + <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term> + <listitem><para>Controls the UID used for the + /proc/bus/usb/BBB/DDD + files. (Default: 0)</para></listitem></varlistentry> + + <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term> + <listitem><para>Controls the GID used for the + /proc/bus/usb/devices and drivers files. + (Default: 0)</para></listitem></varlistentry> + <varlistentry><term><emphasis>listmode</emphasis>=MMM</term> + <listitem><para>Controls the file mode used for the + /proc/bus/usb/devices and drivers files. + (Default: 0444)</para></listitem></varlistentry> + <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term> + <listitem><para>Controls the UID used for the + /proc/bus/usb/devices and drivers files. + (Default: 0)</para></listitem></varlistentry> + </variablelist> + + </para> + + <para>Note that many Linux distributions hard-wire the mount options + for usbfs in their init scripts, such as + <filename>/etc/rc.d/rc.sysinit</filename>, + rather than making it easy to set this per-system + policy in <filename>/etc/fstab</filename>. + </para> + + </sect1> + + <sect1 id="usbfs-devices"> + <title>/proc/bus/usb/devices</title> + + <para>This file is handy for status viewing tools in user + mode, which can scan the text format and ignore most of it. + More detailed device status (including class and vendor + status) is available from device-specific files. + For information about the current format of this file, + see the + <filename>Documentation/usb/proc_usb_info.txt</filename> + file in your Linux kernel sources. + </para> + + <para>This file, in combination with the poll() system call, can + also be used to detect when devices are added or removed: +<programlisting>int fd; +struct pollfd pfd; + +fd = open("/proc/bus/usb/devices", O_RDONLY); +pfd = { fd, POLLIN, 0 }; +for (;;) { + /* The first time through, this call will return immediately. */ + poll(&pfd, 1, -1); + + /* To see what's changed, compare the file's previous and current + contents or scan the filesystem. (Scanning is more precise.) */ +}</programlisting> + Note that this behavior is intended to be used for informational + and debug purposes. It would be more appropriate to use programs + such as udev or HAL to initialize a device or start a user-mode + helper program, for instance. + </para> + </sect1> + + <sect1 id="usbfs-bbbddd"> + <title>/proc/bus/usb/BBB/DDD</title> + + <para>Use these files in one of these basic ways: + </para> + + <para><emphasis>They can be read,</emphasis> + producing first the device descriptor + (18 bytes) and then the descriptors for the current configuration. + See the USB 2.0 spec for details about those binary data formats. + You'll need to convert most multibyte values from little endian + format to your native host byte order, although a few of the + fields in the device descriptor (both of the BCD-encoded fields, + and the vendor and product IDs) will be byteswapped for you. + Note that configuration descriptors include descriptors for + interfaces, altsettings, endpoints, and maybe additional + class descriptors. + </para> + + <para><emphasis>Perform USB operations</emphasis> using + <emphasis>ioctl()</emphasis> requests to make endpoint I/O + requests (synchronously or asynchronously) or manage + the device. + These requests need the CAP_SYS_RAWIO capability, + as well as filesystem access permissions. + Only one ioctl request can be made on one of these + device files at a time. + This means that if you are synchronously reading an endpoint + from one thread, you won't be able to write to a different + endpoint from another thread until the read completes. + This works for <emphasis>half duplex</emphasis> protocols, + but otherwise you'd use asynchronous i/o requests. + </para> + + </sect1> + + + <sect1 id="usbfs-lifecycle"> + <title>Life Cycle of User Mode Drivers</title> + + <para>Such a driver first needs to find a device file + for a device it knows how to handle. + Maybe it was told about it because a + <filename>/sbin/hotplug</filename> event handling agent + chose that driver to handle the new device. + Or maybe it's an application that scans all the + /proc/bus/usb device files, and ignores most devices. + In either case, it should <function>read()</function> all + the descriptors from the device file, + and check them against what it knows how to handle. + It might just reject everything except a particular + vendor and product ID, or need a more complex policy. + </para> + + <para>Never assume there will only be one such device + on the system at a time! + If your code can't handle more than one device at + a time, at least detect when there's more than one, and + have your users choose which device to use. + </para> + + <para>Once your user mode driver knows what device to use, + it interacts with it in either of two styles. + The simple style is to make only control requests; some + devices don't need more complex interactions than those. + (An example might be software using vendor-specific control + requests for some initialization or configuration tasks, + with a kernel driver for the rest.) + </para> + + <para>More likely, you need a more complex style driver: + one using non-control endpoints, reading or writing data + and claiming exclusive use of an interface. + <emphasis>Bulk</emphasis> transfers are easiest to use, + but only their sibling <emphasis>interrupt</emphasis> transfers + work with low speed devices. + Both interrupt and <emphasis>isochronous</emphasis> transfers + offer service guarantees because their bandwidth is reserved. + Such "periodic" transfers are awkward to use through usbfs, + unless you're using the asynchronous calls. However, interrupt + transfers can also be used in a synchronous "one shot" style. + </para> + + <para>Your user-mode driver should never need to worry + about cleaning up request state when the device is + disconnected, although it should close its open file + descriptors as soon as it starts seeing the ENODEV + errors. + </para> + + </sect1> + + <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title> + + <para>To use these ioctls, you need to include the following + headers in your userspace program: +<programlisting>#include <linux/usb.h> +#include <linux/usbdevice_fs.h> +#include <asm/byteorder.h></programlisting> + The standard USB device model requests, from "Chapter 9" of + the USB 2.0 specification, are automatically included from + the <filename><linux/usb/ch9.h></filename> header. + </para> + + <para>Unless noted otherwise, the ioctl requests + described here will + update the modification time on the usbfs file to which + they are applied (unless they fail). + A return of zero indicates success; otherwise, a + standard USB error code is returned. (These are + documented in + <filename>Documentation/usb/error-codes.txt</filename> + in your kernel sources.) + </para> + + <para>Each of these files multiplexes access to several + I/O streams, one per endpoint. + Each device has one control endpoint (endpoint zero) + which supports a limited RPC style RPC access. + Devices are configured + by hub_wq (in the kernel) setting a device-wide + <emphasis>configuration</emphasis> that affects things + like power consumption and basic functionality. + The endpoints are part of USB <emphasis>interfaces</emphasis>, + which may have <emphasis>altsettings</emphasis> + affecting things like which endpoints are available. + Many devices only have a single configuration and interface, + so drivers for them will ignore configurations and altsettings. + </para> + + + <sect2 id="usbfs-mgmt"> + <title>Management/Status Requests</title> + + <para>A number of usbfs requests don't deal very directly + with device I/O. + They mostly relate to device management and status. + These are all synchronous requests. + </para> + + <variablelist> + + <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term> + <listitem><para>This is used to force usbfs to + claim a specific interface, + which has not previously been claimed by usbfs or any other + kernel driver. + The ioctl parameter is an integer holding the number of + the interface (bInterfaceNumber from descriptor). + </para><para> + Note that if your driver doesn't claim an interface + before trying to use one of its endpoints, and no + other driver has bound to it, then the interface is + automatically claimed by usbfs. + </para><para> + This claim will be released by a RELEASEINTERFACE ioctl, + or by closing the file descriptor. + File modification time is not updated by this request. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_CONNECTINFO</term> + <listitem><para>Says whether the device is lowspeed. + The ioctl parameter points to a structure like this: +<programlisting>struct usbdevfs_connectinfo { + unsigned int devnum; + unsigned char slow; +}; </programlisting> + File modification time is not updated by this request. + </para><para> + <emphasis>You can't tell whether a "not slow" + device is connected at high speed (480 MBit/sec) + or just full speed (12 MBit/sec).</emphasis> + You should know the devnum value already, + it's the DDD value of the device file name. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_GETDRIVER</term> + <listitem><para>Returns the name of the kernel driver + bound to a given interface (a string). Parameter + is a pointer to this structure, which is modified: +<programlisting>struct usbdevfs_getdriver { + unsigned int interface; + char driver[USBDEVFS_MAXDRIVERNAME + 1]; +};</programlisting> + File modification time is not updated by this request. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_IOCTL</term> + <listitem><para>Passes a request from userspace through + to a kernel driver that has an ioctl entry in the + <emphasis>struct usb_driver</emphasis> it registered. +<programlisting>struct usbdevfs_ioctl { + int ifno; + int ioctl_code; + void *data; +}; + +/* user mode call looks like this. + * 'request' becomes the driver->ioctl() 'code' parameter. + * the size of 'param' is encoded in 'request', and that data + * is copied to or from the driver->ioctl() 'buf' parameter. + */ +static int +usbdev_ioctl (int fd, int ifno, unsigned request, void *param) +{ + struct usbdevfs_ioctl wrapper; + + wrapper.ifno = ifno; + wrapper.ioctl_code = request; + wrapper.data = param; + + return ioctl (fd, USBDEVFS_IOCTL, &wrapper); +} </programlisting> + File modification time is not updated by this request. + </para><para> + This request lets kernel drivers talk to user mode code + through filesystem operations even when they don't create + a character or block special device. + It's also been used to do things like ask devices what + device special file should be used. + Two pre-defined ioctls are used + to disconnect and reconnect kernel drivers, so + that user mode code can completely manage binding + and configuration of devices. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term> + <listitem><para>This is used to release the claim usbfs + made on interface, either implicitly or because of a + USBDEVFS_CLAIMINTERFACE call, before the file + descriptor is closed. + The ioctl parameter is an integer holding the number of + the interface (bInterfaceNumber from descriptor); + File modification time is not updated by this request. + </para><warning><para> + <emphasis>No security check is made to ensure + that the task which made the claim is the one + which is releasing it. + This means that user mode driver may interfere + other ones. </emphasis> + </para></warning></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_RESETEP</term> + <listitem><para>Resets the data toggle value for an endpoint + (bulk or interrupt) to DATA0. + The ioctl parameter is an integer endpoint number + (1 to 15, as identified in the endpoint descriptor), + with USB_DIR_IN added if the device's endpoint sends + data to the host. + </para><warning><para> + <emphasis>Avoid using this request. + It should probably be removed.</emphasis> + Using it typically means the device and driver will lose + toggle synchronization. If you really lost synchronization, + you likely need to completely handshake with the device, + using a request like CLEAR_HALT + or SET_INTERFACE. + </para></warning></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_DROP_PRIVILEGES</term> + <listitem><para>This is used to relinquish the ability + to do certain operations which are considered to be + privileged on a usbfs file descriptor. + This includes claiming arbitrary interfaces, resetting + a device on which there are currently claimed interfaces + from other users, and issuing USBDEVFS_IOCTL calls. + The ioctl parameter is a 32 bit mask of interfaces + the user is allowed to claim on this file descriptor. + You may issue this ioctl more than one time to narrow + said mask. + </para></listitem></varlistentry> + </variablelist> + + </sect2> + + <sect2 id="usbfs-sync"> + <title>Synchronous I/O Support</title> + + <para>Synchronous requests involve the kernel blocking + until the user mode request completes, either by + finishing successfully or by reporting an error. + In most cases this is the simplest way to use usbfs, + although as noted above it does prevent performing I/O + to more than one endpoint at a time. + </para> + + <variablelist> + + <varlistentry><term>USBDEVFS_BULK</term> + <listitem><para>Issues a bulk read or write request to the + device. + The ioctl parameter is a pointer to this structure: +<programlisting>struct usbdevfs_bulktransfer { + unsigned int ep; + unsigned int len; + unsigned int timeout; /* in milliseconds */ + void *data; +};</programlisting> + </para><para>The "ep" value identifies a + bulk endpoint number (1 to 15, as identified in an endpoint + descriptor), + masked with USB_DIR_IN when referring to an endpoint which + sends data to the host from the device. + The length of the data buffer is identified by "len"; + Recent kernels support requests up to about 128KBytes. + <emphasis>FIXME say how read length is returned, + and how short reads are handled.</emphasis>. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_CLEAR_HALT</term> + <listitem><para>Clears endpoint halt (stall) and + resets the endpoint toggle. This is only + meaningful for bulk or interrupt endpoints. + The ioctl parameter is an integer endpoint number + (1 to 15, as identified in an endpoint descriptor), + masked with USB_DIR_IN when referring to an endpoint which + sends data to the host from the device. + </para><para> + Use this on bulk or interrupt endpoints which have + stalled, returning <emphasis>-EPIPE</emphasis> status + to a data transfer request. + Do not issue the control request directly, since + that could invalidate the host's record of the + data toggle. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_CONTROL</term> + <listitem><para>Issues a control request to the device. + The ioctl parameter points to a structure like this: +<programlisting>struct usbdevfs_ctrltransfer { + __u8 bRequestType; + __u8 bRequest; + __u16 wValue; + __u16 wIndex; + __u16 wLength; + __u32 timeout; /* in milliseconds */ + void *data; +};</programlisting> + </para><para> + The first eight bytes of this structure are the contents + of the SETUP packet to be sent to the device; see the + USB 2.0 specification for details. + The bRequestType value is composed by combining a + USB_TYPE_* value, a USB_DIR_* value, and a + USB_RECIP_* value (from + <emphasis><linux/usb.h></emphasis>). + If wLength is nonzero, it describes the length of the data + buffer, which is either written to the device + (USB_DIR_OUT) or read from the device (USB_DIR_IN). + </para><para> + At this writing, you can't transfer more than 4 KBytes + of data to or from a device; usbfs has a limit, and + some host controller drivers have a limit. + (That's not usually a problem.) + <emphasis>Also</emphasis> there's no way to say it's + not OK to get a short read back from the device. + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_RESET</term> + <listitem><para>Does a USB level device reset. + The ioctl parameter is ignored. + After the reset, this rebinds all device interfaces. + File modification time is not updated by this request. + </para><warning><para> + <emphasis>Avoid using this call</emphasis> + until some usbcore bugs get fixed, + since it does not fully synchronize device, interface, + and driver (not just usbfs) state. + </para></warning></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_SETINTERFACE</term> + <listitem><para>Sets the alternate setting for an + interface. The ioctl parameter is a pointer to a + structure like this: +<programlisting>struct usbdevfs_setinterface { + unsigned int interface; + unsigned int altsetting; +}; </programlisting> + File modification time is not updated by this request. + </para><para> + Those struct members are from some interface descriptor + applying to the current configuration. + The interface number is the bInterfaceNumber value, and + the altsetting number is the bAlternateSetting value. + (This resets each endpoint in the interface.) + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_SETCONFIGURATION</term> + <listitem><para>Issues the + <function>usb_set_configuration</function> call + for the device. + The parameter is an integer holding the number of + a configuration (bConfigurationValue from descriptor). + File modification time is not updated by this request. + </para><warning><para> + <emphasis>Avoid using this call</emphasis> + until some usbcore bugs get fixed, + since it does not fully synchronize device, interface, + and driver (not just usbfs) state. + </para></warning></listitem></varlistentry> + + </variablelist> + </sect2> + + <sect2 id="usbfs-async"> + <title>Asynchronous I/O Support</title> + + <para>As mentioned above, there are situations where it may be + important to initiate concurrent operations from user mode code. + This is particularly important for periodic transfers + (interrupt and isochronous), but it can be used for other + kinds of USB requests too. + In such cases, the asynchronous requests described here + are essential. Rather than submitting one request and having + the kernel block until it completes, the blocking is separate. + </para> + + <para>These requests are packaged into a structure that + resembles the URB used by kernel device drivers. + (No POSIX Async I/O support here, sorry.) + It identifies the endpoint type (USBDEVFS_URB_TYPE_*), + endpoint (number, masked with USB_DIR_IN as appropriate), + buffer and length, and a user "context" value serving to + uniquely identify each request. + (It's usually a pointer to per-request data.) + Flags can modify requests (not as many as supported for + kernel drivers). + </para> + + <para>Each request can specify a realtime signal number + (between SIGRTMIN and SIGRTMAX, inclusive) to request a + signal be sent when the request completes. + </para> + + <para>When usbfs returns these urbs, the status value + is updated, and the buffer may have been modified. + Except for isochronous transfers, the actual_length is + updated to say how many bytes were transferred; if the + USBDEVFS_URB_DISABLE_SPD flag is set + ("short packets are not OK"), if fewer bytes were read + than were requested then you get an error report. + </para> + +<programlisting>struct usbdevfs_iso_packet_desc { + unsigned int length; + unsigned int actual_length; + unsigned int status; +}; + +struct usbdevfs_urb { + unsigned char type; + unsigned char endpoint; + int status; + unsigned int flags; + void *buffer; + int buffer_length; + int actual_length; + int start_frame; + int number_of_packets; + int error_count; + unsigned int signr; + void *usercontext; + struct usbdevfs_iso_packet_desc iso_frame_desc[]; +};</programlisting> + + <para> For these asynchronous requests, the file modification + time reflects when the request was initiated. + This contrasts with their use with the synchronous requests, + where it reflects when requests complete. + </para> + + <variablelist> + + <varlistentry><term>USBDEVFS_DISCARDURB</term> + <listitem><para> + <emphasis>TBS</emphasis> + File modification time is not updated by this request. + </para><para> + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_DISCSIGNAL</term> + <listitem><para> + <emphasis>TBS</emphasis> + File modification time is not updated by this request. + </para><para> + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_REAPURB</term> + <listitem><para> + <emphasis>TBS</emphasis> + File modification time is not updated by this request. + </para><para> + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_REAPURBNDELAY</term> + <listitem><para> + <emphasis>TBS</emphasis> + File modification time is not updated by this request. + </para><para> + </para></listitem></varlistentry> + + <varlistentry><term>USBDEVFS_SUBMITURB</term> + <listitem><para> + <emphasis>TBS</emphasis> + </para><para> + </para></listitem></varlistentry> + + </variablelist> + </sect2> + + </sect1> + + </chapter> + +</book> +<!-- vim:syntax=sgml:sw=4 +-->
diff --git a/Documentation/DocBook/w1.tmpl b/Documentation/DocBook/w1.tmpl new file mode 100644 index 0000000..b0228d4 --- /dev/null +++ b/Documentation/DocBook/w1.tmpl
@@ -0,0 +1,101 @@ +<?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="w1id"> + <bookinfo> + <title>W1: Dallas' 1-wire bus</title> + + <authorgroup> + <author> + <firstname>David</firstname> + <surname>Fries</surname> + <affiliation> + <address> + <email>David@Fries.net</email> + </address> + </affiliation> + </author> + + </authorgroup> + + <copyright> + <year>2013</year> + <!-- + <holder></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. + </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. + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + + <toc></toc> + + <chapter id="w1_internal"> + <title>W1 API internal to the kernel</title> + + <sect1 id="w1_internal_api"> + <title>W1 API internal to the kernel</title> + <sect2 id="w1.h"> + <title>drivers/w1/w1.h</title> + <para>W1 core functions.</para> +!Idrivers/w1/w1.h + </sect2> + + <sect2 id="w1.c"> + <title>drivers/w1/w1.c</title> + <para>W1 core functions.</para> +!Idrivers/w1/w1.c + </sect2> + + <sect2 id="w1_family.h"> + <title>drivers/w1/w1_family.h</title> + <para>Allows registering device family operations.</para> +!Idrivers/w1/w1_family.h + </sect2> + + <sect2 id="w1_family.c"> + <title>drivers/w1/w1_family.c</title> + <para>Allows registering device family operations.</para> +!Edrivers/w1/w1_family.c + </sect2> + + <sect2 id="w1_int.c"> + <title>drivers/w1/w1_int.c</title> + <para>W1 internal initialization for master devices.</para> +!Edrivers/w1/w1_int.c + </sect2> + + <sect2 id="w1_netlink.h"> + <title>drivers/w1/w1_netlink.h</title> + <para>W1 external netlink API structures and commands.</para> +!Idrivers/w1/w1_netlink.h + </sect2> + + <sect2 id="w1_io.c"> + <title>drivers/w1/w1_io.c</title> + <para>W1 input/output.</para> +!Edrivers/w1/w1_io.c +!Idrivers/w1/w1_io.c + </sect2> + + </sect1> + + + </chapter> + +</book>
diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl new file mode 100644 index 0000000..a27ab9f --- /dev/null +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl
@@ -0,0 +1,6206 @@ +<?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="Writing-an-ALSA-Driver"> + <bookinfo> + <title>Writing an ALSA Driver</title> + <author> + <firstname>Takashi</firstname> + <surname>Iwai</surname> + <affiliation> + <address> + <email>tiwai@suse.de</email> + </address> + </affiliation> + </author> + + <date>Oct 15, 2007</date> + <edition>0.3.7</edition> + + <abstract> + <para> + This document describes how to write an ALSA (Advanced Linux + Sound Architecture) driver. + </para> + </abstract> + + <legalnotice> + <para> + Copyright (c) 2002-2005 Takashi Iwai <email>tiwai@suse.de</email> + </para> + + <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> + +<!-- ****************************************************** --> +<!-- Preface --> +<!-- ****************************************************** --> + <preface id="preface"> + <title>Preface</title> + <para> + This document describes how to write an + <ulink url="http://www.alsa-project.org/"><citetitle> + ALSA (Advanced Linux Sound Architecture)</citetitle></ulink> + driver. The document focuses mainly on PCI soundcards. + In the case of other device types, the API might + be different, too. However, at least the ALSA kernel API is + consistent, and therefore it would be still a bit help for + writing them. + </para> + + <para> + This document targets people who already have enough + C language skills and have basic linux kernel programming + knowledge. This document doesn't explain the general + topic of linux kernel coding and doesn't cover low-level + driver implementation details. It only describes + the standard way to write a PCI sound driver on ALSA. + </para> + + <para> + If you are already familiar with the older ALSA ver.0.5.x API, you + can check the drivers such as <filename>sound/pci/es1938.c</filename> or + <filename>sound/pci/maestro3.c</filename> which have also almost the same + code-base in the ALSA 0.5.x tree, so you can compare the differences. + </para> + + <para> + This document is still a draft version. Any feedback and + corrections, please!! + </para> + </preface> + + +<!-- ****************************************************** --> +<!-- File Tree Structure --> +<!-- ****************************************************** --> + <chapter id="file-tree"> + <title>File Tree Structure</title> + + <section id="file-tree-general"> + <title>General</title> + <para> + The ALSA drivers are provided in two ways. + </para> + + <para> + One is the trees provided as a tarball or via cvs from the + ALSA's ftp site, and another is the 2.6 (or later) Linux kernel + tree. To synchronize both, the ALSA driver tree is split into + two different trees: alsa-kernel and alsa-driver. The former + contains purely the source code for the Linux 2.6 (or later) + tree. This tree is designed only for compilation on 2.6 or + later environment. The latter, alsa-driver, contains many subtle + files for compiling ALSA drivers outside of the Linux kernel tree, + wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API, + and additional drivers which are still in development or in + tests. The drivers in alsa-driver tree will be moved to + alsa-kernel (and eventually to the 2.6 kernel tree) when they are + finished and confirmed to work fine. + </para> + + <para> + The file tree structure of ALSA driver is depicted below. Both + alsa-kernel and alsa-driver have almost the same file + structure, except for <quote>core</quote> directory. It's + named as <quote>acore</quote> in alsa-driver tree. + + <example> + <title>ALSA File Tree Structure</title> + <literallayout> + sound + /core + /oss + /seq + /oss + /instr + /ioctl32 + /include + /drivers + /mpu401 + /opl3 + /i2c + /l3 + /synth + /emux + /pci + /(cards) + /isa + /(cards) + /arm + /ppc + /sparc + /usb + /pcmcia /(cards) + /oss + </literallayout> + </example> + </para> + </section> + + <section id="file-tree-core-directory"> + <title>core directory</title> + <para> + This directory contains the middle layer which is the heart + of ALSA drivers. In this directory, the native ALSA modules are + stored. The sub-directories contain different modules and are + dependent upon the kernel config. + </para> + + <section id="file-tree-core-directory-oss"> + <title>core/oss</title> + + <para> + The codes for PCM and mixer OSS emulation modules are stored + in this directory. The rawmidi OSS emulation is included in + the ALSA rawmidi code since it's quite small. The sequencer + code is stored in <filename>core/seq/oss</filename> directory (see + <link linkend="file-tree-core-directory-seq-oss"><citetitle> + below</citetitle></link>). + </para> + </section> + + <section id="file-tree-core-directory-ioctl32"> + <title>core/ioctl32</title> + + <para> + This directory contains the 32bit-ioctl wrappers for 64bit + architectures such like x86-64, ppc64 and sparc64. For 32bit + and alpha architectures, these are not compiled. + </para> + </section> + + <section id="file-tree-core-directory-seq"> + <title>core/seq</title> + <para> + This directory and its sub-directories are for the ALSA + sequencer. This directory contains the sequencer core and + primary sequencer modules such like snd-seq-midi, + snd-seq-virmidi, etc. They are compiled only when + <constant>CONFIG_SND_SEQUENCER</constant> is set in the kernel + config. + </para> + </section> + + <section id="file-tree-core-directory-seq-oss"> + <title>core/seq/oss</title> + <para> + This contains the OSS sequencer emulation codes. + </para> + </section> + + <section id="file-tree-core-directory-deq-instr"> + <title>core/seq/instr</title> + <para> + This directory contains the modules for the sequencer + instrument layer. + </para> + </section> + </section> + + <section id="file-tree-include-directory"> + <title>include directory</title> + <para> + This is the place for the public header files of ALSA drivers, + which are to be exported to user-space, or included by + several files at different directories. Basically, the private + header files should not be placed in this directory, but you may + still find files there, due to historical reasons :) + </para> + </section> + + <section id="file-tree-drivers-directory"> + <title>drivers directory</title> + <para> + This directory contains code shared among different drivers + on different architectures. They are hence supposed not to be + architecture-specific. + For example, the dummy pcm driver and the serial MIDI + driver are found in this directory. In the sub-directories, + there is code for components which are independent from + bus and cpu architectures. + </para> + + <section id="file-tree-drivers-directory-mpu401"> + <title>drivers/mpu401</title> + <para> + The MPU401 and MPU401-UART modules are stored here. + </para> + </section> + + <section id="file-tree-drivers-directory-opl3"> + <title>drivers/opl3 and opl4</title> + <para> + The OPL3 and OPL4 FM-synth stuff is found here. + </para> + </section> + </section> + + <section id="file-tree-i2c-directory"> + <title>i2c directory</title> + <para> + This contains the ALSA i2c components. + </para> + + <para> + Although there is a standard i2c layer on Linux, ALSA has its + own i2c code for some cards, because the soundcard needs only a + simple operation and the standard i2c API is too complicated for + such a purpose. + </para> + + <section id="file-tree-i2c-directory-l3"> + <title>i2c/l3</title> + <para> + This is a sub-directory for ARM L3 i2c. + </para> + </section> + </section> + + <section id="file-tree-synth-directory"> + <title>synth directory</title> + <para> + This contains the synth middle-level modules. + </para> + + <para> + So far, there is only Emu8000/Emu10k1 synth driver under + the <filename>synth/emux</filename> sub-directory. + </para> + </section> + + <section id="file-tree-pci-directory"> + <title>pci directory</title> + <para> + This directory and its sub-directories hold the top-level card modules + for PCI soundcards and the code specific to the PCI BUS. + </para> + + <para> + The drivers compiled from a single file are stored directly + in the pci directory, while the drivers with several source files are + stored on their own sub-directory (e.g. emu10k1, ice1712). + </para> + </section> + + <section id="file-tree-isa-directory"> + <title>isa directory</title> + <para> + This directory and its sub-directories hold the top-level card modules + for ISA soundcards. + </para> + </section> + + <section id="file-tree-arm-ppc-sparc-directories"> + <title>arm, ppc, and sparc directories</title> + <para> + They are used for top-level card modules which are + specific to one of these architectures. + </para> + </section> + + <section id="file-tree-usb-directory"> + <title>usb directory</title> + <para> + This directory contains the USB-audio driver. In the latest version, the + USB MIDI driver is integrated in the usb-audio driver. + </para> + </section> + + <section id="file-tree-pcmcia-directory"> + <title>pcmcia directory</title> + <para> + The PCMCIA, especially PCCard drivers will go here. CardBus + drivers will be in the pci directory, because their API is identical + to that of standard PCI cards. + </para> + </section> + + <section id="file-tree-oss-directory"> + <title>oss directory</title> + <para> + The OSS/Lite source files are stored here in Linux 2.6 (or + later) tree. In the ALSA driver tarball, this directory is empty, + of course :) + </para> + </section> + </chapter> + + +<!-- ****************************************************** --> +<!-- Basic Flow for PCI Drivers --> +<!-- ****************************************************** --> + <chapter id="basic-flow"> + <title>Basic Flow for PCI Drivers</title> + + <section id="basic-flow-outline"> + <title>Outline</title> + <para> + The minimum flow for PCI soundcards is as follows: + + <itemizedlist> + <listitem><para>define the PCI ID table (see the section + <link linkend="pci-resource-entries"><citetitle>PCI Entries + </citetitle></link>).</para></listitem> + <listitem><para>create <function>probe()</function> callback.</para></listitem> + <listitem><para>create <function>remove()</function> callback.</para></listitem> + <listitem><para>create a <structname>pci_driver</structname> structure + containing the three pointers above.</para></listitem> + <listitem><para>create an <function>init()</function> function just calling + the <function>pci_register_driver()</function> to register the pci_driver table + defined above.</para></listitem> + <listitem><para>create an <function>exit()</function> function to call + the <function>pci_unregister_driver()</function> function.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id="basic-flow-example"> + <title>Full Code Example</title> + <para> + The code example is shown below. Some parts are kept + unimplemented at this moment but will be filled in the + next sections. The numbers in the comment lines of the + <function>snd_mychip_probe()</function> function + refer to details explained in the following section. + + <example> + <title>Basic Flow for PCI Drivers - Example</title> + <programlisting> +<![CDATA[ + #include <linux/init.h> + #include <linux/pci.h> + #include <linux/slab.h> + #include <sound/core.h> + #include <sound/initval.h> + + /* module parameters (see "Module Parameters") */ + /* SNDRV_CARDS: maximum number of cards supported by this module */ + static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; + static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; + static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; + + /* definition of the chip-specific record */ + struct mychip { + struct snd_card *card; + /* the rest of the implementation will be in section + * "PCI Resource Management" + */ + }; + + /* chip-specific destructor + * (see "PCI Resource Management") + */ + static int snd_mychip_free(struct mychip *chip) + { + .... /* will be implemented later... */ + } + + /* component-destructor + * (see "Management of Cards and Components") + */ + static int snd_mychip_dev_free(struct snd_device *device) + { + return snd_mychip_free(device->device_data); + } + + /* chip-specific constructor + * (see "Management of Cards and Components") + */ + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) + { + struct mychip *chip; + int err; + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + + *rchip = NULL; + + /* check PCI availability here + * (see "PCI Resource Management") + */ + .... + + /* allocate a chip-specific data with zero filled */ + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + if (chip == NULL) + return -ENOMEM; + + chip->card = card; + + /* rest of initialization here; will be implemented + * later, see "PCI Resource Management" + */ + .... + + err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); + if (err < 0) { + snd_mychip_free(chip); + return err; + } + + *rchip = chip; + return 0; + } + + /* constructor -- see "Constructor" sub-section */ + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + static int dev; + struct snd_card *card; + struct mychip *chip; + int err; + + /* (1) */ + if (dev >= SNDRV_CARDS) + return -ENODEV; + if (!enable[dev]) { + dev++; + return -ENOENT; + } + + /* (2) */ + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + if (err < 0) + return err; + + /* (3) */ + err = snd_mychip_create(card, pci, &chip); + if (err < 0) { + snd_card_free(card); + return err; + } + + /* (4) */ + strcpy(card->driver, "My Chip"); + strcpy(card->shortname, "My Own Chip 123"); + sprintf(card->longname, "%s at 0x%lx irq %i", + card->shortname, chip->ioport, chip->irq); + + /* (5) */ + .... /* implemented later */ + + /* (6) */ + err = snd_card_register(card); + if (err < 0) { + snd_card_free(card); + return err; + } + + /* (7) */ + pci_set_drvdata(pci, card); + dev++; + return 0; + } + + /* destructor -- see the "Destructor" sub-section */ + static void snd_mychip_remove(struct pci_dev *pci) + { + snd_card_free(pci_get_drvdata(pci)); + pci_set_drvdata(pci, NULL); + } +]]> + </programlisting> + </example> + </para> + </section> + + <section id="basic-flow-constructor"> + <title>Constructor</title> + <para> + The real constructor of PCI drivers is the <function>probe</function> callback. + The <function>probe</function> callback and other component-constructors which are called + from the <function>probe</function> callback cannot be used with + the <parameter>__init</parameter> prefix + because any PCI device could be a hotplug device. + </para> + + <para> + In the <function>probe</function> callback, the following scheme is often used. + </para> + + <section id="basic-flow-constructor-device-index"> + <title>1) Check and increment the device index.</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int dev; + .... + if (dev >= SNDRV_CARDS) + return -ENODEV; + if (!enable[dev]) { + dev++; + return -ENOENT; + } +]]> + </programlisting> + </informalexample> + + where enable[dev] is the module option. + </para> + + <para> + Each time the <function>probe</function> callback is called, check the + availability of the device. If not available, simply increment + the device index and returns. dev will be incremented also + later (<link + linkend="basic-flow-constructor-set-pci"><citetitle>step + 7</citetitle></link>). + </para> + </section> + + <section id="basic-flow-constructor-create-card"> + <title>2) Create a card instance</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + struct snd_card *card; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The details will be explained in the section + <link linkend="card-management-card-instance"><citetitle> + Management of Cards and Components</citetitle></link>. + </para> + </section> + + <section id="basic-flow-constructor-create-main"> + <title>3) Create a main component</title> + <para> + In this part, the PCI resources are allocated. + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip *chip; + .... + err = snd_mychip_create(card, pci, &chip); + if (err < 0) { + snd_card_free(card); + return err; + } +]]> + </programlisting> + </informalexample> + + The details will be explained in the section <link + linkend="pci-resource"><citetitle>PCI Resource + Management</citetitle></link>. + </para> + </section> + + <section id="basic-flow-constructor-main-component"> + <title>4) Set the driver ID and name strings.</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + strcpy(card->driver, "My Chip"); + strcpy(card->shortname, "My Own Chip 123"); + sprintf(card->longname, "%s at 0x%lx irq %i", + card->shortname, chip->ioport, chip->irq); +]]> + </programlisting> + </informalexample> + + The driver field holds the minimal ID string of the + chip. This is used by alsa-lib's configurator, so keep it + simple but unique. + Even the same driver can have different driver IDs to + distinguish the functionality of each chip type. + </para> + + <para> + The shortname field is a string shown as more verbose + name. The longname field contains the information + shown in <filename>/proc/asound/cards</filename>. + </para> + </section> + + <section id="basic-flow-constructor-create-other"> + <title>5) Create other components, such as mixer, MIDI, etc.</title> + <para> + Here you define the basic components such as + <link linkend="pcm-interface"><citetitle>PCM</citetitle></link>, + mixer (e.g. <link linkend="api-ac97"><citetitle>AC97</citetitle></link>), + MIDI (e.g. <link linkend="midi-interface"><citetitle>MPU-401</citetitle></link>), + and other interfaces. + Also, if you want a <link linkend="proc-interface"><citetitle>proc + file</citetitle></link>, define it here, too. + </para> + </section> + + <section id="basic-flow-constructor-register-card"> + <title>6) Register the card instance.</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + err = snd_card_register(card); + if (err < 0) { + snd_card_free(card); + return err; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + Will be explained in the section <link + linkend="card-management-registration"><citetitle>Management + of Cards and Components</citetitle></link>, too. + </para> + </section> + + <section id="basic-flow-constructor-set-pci"> + <title>7) Set the PCI driver data and return zero.</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + pci_set_drvdata(pci, card); + dev++; + return 0; +]]> + </programlisting> + </informalexample> + + In the above, the card record is stored. This pointer is + used in the remove callback and power-management + callbacks, too. + </para> + </section> + </section> + + <section id="basic-flow-destructor"> + <title>Destructor</title> + <para> + The destructor, remove callback, simply releases the card + instance. Then the ALSA middle layer will release all the + attached components automatically. + </para> + + <para> + It would be typically like the following: + + <informalexample> + <programlisting> +<![CDATA[ + static void snd_mychip_remove(struct pci_dev *pci) + { + snd_card_free(pci_get_drvdata(pci)); + pci_set_drvdata(pci, NULL); + } +]]> + </programlisting> + </informalexample> + + The above code assumes that the card pointer is set to the PCI + driver data. + </para> + </section> + + <section id="basic-flow-header-files"> + <title>Header Files</title> + <para> + For the above example, at least the following include files + are necessary. + + <informalexample> + <programlisting> +<![CDATA[ + #include <linux/init.h> + #include <linux/pci.h> + #include <linux/slab.h> + #include <sound/core.h> + #include <sound/initval.h> +]]> + </programlisting> + </informalexample> + + where the last one is necessary only when module options are + defined in the source file. If the code is split into several + files, the files without module options don't need them. + </para> + + <para> + In addition to these headers, you'll need + <filename><linux/interrupt.h></filename> for interrupt + handling, and <filename><asm/io.h></filename> for I/O + access. If you use the <function>mdelay()</function> or + <function>udelay()</function> functions, you'll need to include + <filename><linux/delay.h></filename> too. + </para> + + <para> + The ALSA interfaces like the PCM and control APIs are defined in other + <filename><sound/xxx.h></filename> header files. + They have to be included after + <filename><sound/core.h></filename>. + </para> + + </section> + </chapter> + + +<!-- ****************************************************** --> +<!-- Management of Cards and Components --> +<!-- ****************************************************** --> + <chapter id="card-management"> + <title>Management of Cards and Components</title> + + <section id="card-management-card-instance"> + <title>Card Instance</title> + <para> + For each soundcard, a <quote>card</quote> record must be allocated. + </para> + + <para> + A card record is the headquarters of the soundcard. It manages + the whole list of devices (components) on the soundcard, such as + PCM, mixers, MIDI, synthesizer, and so on. Also, the card + record holds the ID and the name strings of the card, manages + the root of proc files, and controls the power-management states + and hotplug disconnections. The component list on the card + record is used to manage the correct release of resources at + destruction. + </para> + + <para> + As mentioned above, to create a card instance, call + <function>snd_card_new()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_card *card; + int err; + err = snd_card_new(&pci->dev, index, id, module, extra_size, &card); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The function takes six arguments: the parent device pointer, + the card-index number, the id string, the module pointer (usually + <constant>THIS_MODULE</constant>), + the size of extra-data space, and the pointer to return the + card instance. The extra_size argument is used to + allocate card->private_data for the + chip-specific data. Note that these data + are allocated by <function>snd_card_new()</function>. + </para> + + <para> + The first argument, the pointer of struct + <structname>device</structname>, specifies the parent device. + For PCI devices, typically &pci-> is passed there. + </para> + </section> + + <section id="card-management-component"> + <title>Components</title> + <para> + After the card is created, you can attach the components + (devices) to the card instance. In an ALSA driver, a component is + represented as a struct <structname>snd_device</structname> object. + A component can be a PCM instance, a control interface, a raw + MIDI interface, etc. Each such instance has one component + entry. + </para> + + <para> + A component can be created via + <function>snd_device_new()</function> function. + + <informalexample> + <programlisting> +<![CDATA[ + snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); +]]> + </programlisting> + </informalexample> + </para> + + <para> + This takes the card pointer, the device-level + (<constant>SNDRV_DEV_XXX</constant>), the data pointer, and the + callback pointers (<parameter>&ops</parameter>). The + device-level defines the type of components and the order of + registration and de-registration. For most components, the + device-level is already defined. For a user-defined component, + you can use <constant>SNDRV_DEV_LOWLEVEL</constant>. + </para> + + <para> + This function itself doesn't allocate the data space. The data + must be allocated manually beforehand, and its pointer is passed + as the argument. This pointer (<parameter>chip</parameter> in the + above example) is used as the identifier for the instance. + </para> + + <para> + Each pre-defined ALSA component such as ac97 and pcm calls + <function>snd_device_new()</function> inside its + constructor. The destructor for each component is defined in the + callback pointers. Hence, you don't need to take care of + calling a destructor for such a component. + </para> + + <para> + If you wish to create your own component, you need to + set the destructor function to the dev_free callback in + the <parameter>ops</parameter>, so that it can be released + automatically via <function>snd_card_free()</function>. + The next example will show an implementation of chip-specific + data. + </para> + </section> + + <section id="card-management-chip-specific"> + <title>Chip-Specific Data</title> + <para> + Chip-specific information, e.g. the I/O port address, its + resource pointer, or the irq number, is stored in the + chip-specific record. + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip { + .... + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + In general, there are two ways of allocating the chip record. + </para> + + <section id="card-management-chip-specific-snd-card-new"> + <title>1. Allocating via <function>snd_card_new()</function>.</title> + <para> + As mentioned above, you can pass the extra-data-length + to the 5th argument of <function>snd_card_new()</function>, i.e. + + <informalexample> + <programlisting> +<![CDATA[ + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); +]]> + </programlisting> + </informalexample> + + struct <structname>mychip</structname> is the type of the chip record. + </para> + + <para> + In return, the allocated record can be accessed as + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip *chip = card->private_data; +]]> + </programlisting> + </informalexample> + + With this method, you don't have to allocate twice. + The record is released together with the card instance. + </para> + </section> + + <section id="card-management-chip-specific-allocate-extra"> + <title>2. Allocating an extra device.</title> + + <para> + After allocating a card instance via + <function>snd_card_new()</function> (with + <constant>0</constant> on the 4th arg), call + <function>kzalloc()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_card *card; + struct mychip *chip; + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + ..... + chip = kzalloc(sizeof(*chip), GFP_KERNEL); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The chip record should have the field to hold the card + pointer at least, + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip { + struct snd_card *card; + .... + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + Then, set the card pointer in the returned chip instance. + + <informalexample> + <programlisting> +<![CDATA[ + chip->card = card; +]]> + </programlisting> + </informalexample> + </para> + + <para> + Next, initialize the fields, and register this chip + record as a low-level device with a specified + <parameter>ops</parameter>, + + <informalexample> + <programlisting> +<![CDATA[ + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + .... + snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); +]]> + </programlisting> + </informalexample> + + <function>snd_mychip_dev_free()</function> is the + device-destructor function, which will call the real + destructor. + </para> + + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_mychip_dev_free(struct snd_device *device) + { + return snd_mychip_free(device->device_data); + } +]]> + </programlisting> + </informalexample> + + where <function>snd_mychip_free()</function> is the real destructor. + </para> + </section> + </section> + + <section id="card-management-registration"> + <title>Registration and Release</title> + <para> + After all components are assigned, register the card instance + by calling <function>snd_card_register()</function>. Access + to the device files is enabled at this point. That is, before + <function>snd_card_register()</function> is called, the + components are safely inaccessible from external side. If this + call fails, exit the probe function after releasing the card via + <function>snd_card_free()</function>. + </para> + + <para> + For releasing the card instance, you can call simply + <function>snd_card_free()</function>. As mentioned earlier, all + components are released automatically by this call. + </para> + + <para> + For a device which allows hotplugging, you can use + <function>snd_card_free_when_closed</function>. This one will + postpone the destruction until all devices are closed. + </para> + + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- PCI Resource Management --> +<!-- ****************************************************** --> + <chapter id="pci-resource"> + <title>PCI Resource Management</title> + + <section id="pci-resource-example"> + <title>Full Code Example</title> + <para> + In this section, we'll complete the chip-specific constructor, + destructor and PCI entries. Example code is shown first, + below. + + <example> + <title>PCI Resource Management Example</title> + <programlisting> +<![CDATA[ + struct mychip { + struct snd_card *card; + struct pci_dev *pci; + + unsigned long port; + int irq; + }; + + static int snd_mychip_free(struct mychip *chip) + { + /* disable hardware here if any */ + .... /* (not implemented in this document) */ + + /* release the irq */ + if (chip->irq >= 0) + free_irq(chip->irq, chip); + /* release the I/O ports & memory */ + pci_release_regions(chip->pci); + /* disable the PCI entry */ + pci_disable_device(chip->pci); + /* release the data */ + kfree(chip); + return 0; + } + + /* chip-specific constructor */ + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) + { + struct mychip *chip; + int err; + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + + *rchip = NULL; + + /* initialize the PCI entry */ + err = pci_enable_device(pci); + if (err < 0) + return err; + /* check PCI availability (28bit DMA) */ + if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || + pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { + printk(KERN_ERR "error to set 28bit mask DMA\n"); + pci_disable_device(pci); + return -ENXIO; + } + + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + if (chip == NULL) { + pci_disable_device(pci); + return -ENOMEM; + } + + /* initialize the stuff */ + chip->card = card; + chip->pci = pci; + chip->irq = -1; + + /* (1) PCI resource allocation */ + err = pci_request_regions(pci, "My Chip"); + if (err < 0) { + kfree(chip); + pci_disable_device(pci); + return err; + } + chip->port = pci_resource_start(pci, 0); + if (request_irq(pci->irq, snd_mychip_interrupt, + IRQF_SHARED, KBUILD_MODNAME, chip)) { + printk(KERN_ERR "cannot grab irq %d\n", pci->irq); + snd_mychip_free(chip); + return -EBUSY; + } + chip->irq = pci->irq; + + /* (2) initialization of the chip hardware */ + .... /* (not implemented in this document) */ + + err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); + if (err < 0) { + snd_mychip_free(chip); + return err; + } + + *rchip = chip; + return 0; + } + + /* PCI IDs */ + static struct pci_device_id snd_mychip_ids[] = { + { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, + PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, + .... + { 0, } + }; + MODULE_DEVICE_TABLE(pci, snd_mychip_ids); + + /* pci_driver definition */ + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_mychip_ids, + .probe = snd_mychip_probe, + .remove = snd_mychip_remove, + }; + + /* module initialization */ + static int __init alsa_card_mychip_init(void) + { + return pci_register_driver(&driver); + } + + /* module clean up */ + static void __exit alsa_card_mychip_exit(void) + { + pci_unregister_driver(&driver); + } + + module_init(alsa_card_mychip_init) + module_exit(alsa_card_mychip_exit) + + EXPORT_NO_SYMBOLS; /* for old kernels only */ +]]> + </programlisting> + </example> + </para> + </section> + + <section id="pci-resource-some-haftas"> + <title>Some Hafta's</title> + <para> + The allocation of PCI resources is done in the + <function>probe()</function> function, and usually an extra + <function>xxx_create()</function> function is written for this + purpose. + </para> + + <para> + In the case of PCI devices, you first have to call + the <function>pci_enable_device()</function> function before + allocating resources. Also, you need to set the proper PCI DMA + mask to limit the accessed I/O range. In some cases, you might + need to call <function>pci_set_master()</function> function, + too. + </para> + + <para> + Suppose the 28bit mask, and the code to be added would be like: + + <informalexample> + <programlisting> +<![CDATA[ + err = pci_enable_device(pci); + if (err < 0) + return err; + if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || + pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { + printk(KERN_ERR "error to set 28bit mask DMA\n"); + pci_disable_device(pci); + return -ENXIO; + } + +]]> + </programlisting> + </informalexample> + </para> + </section> + + <section id="pci-resource-resource-allocation"> + <title>Resource Allocation</title> + <para> + The allocation of I/O ports and irqs is done via standard kernel + functions. Unlike ALSA ver.0.5.x., there are no helpers for + that. And these resources must be released in the destructor + function (see below). Also, on ALSA 0.9.x, you don't need to + allocate (pseudo-)DMA for PCI like in ALSA 0.5.x. + </para> + + <para> + Now assume that the PCI device has an I/O port with 8 bytes + and an interrupt. Then struct <structname>mychip</structname> will have the + following fields: + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip { + struct snd_card *card; + + unsigned long port; + int irq; + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + For an I/O port (and also a memory region), you need to have + the resource pointer for the standard resource management. For + an irq, you have to keep only the irq number (integer). But you + need to initialize this number as -1 before actual allocation, + since irq 0 is valid. The port address and its resource pointer + can be initialized as null by + <function>kzalloc()</function> automatically, so you + don't have to take care of resetting them. + </para> + + <para> + The allocation of an I/O port is done like this: + + <informalexample> + <programlisting> +<![CDATA[ + err = pci_request_regions(pci, "My Chip"); + if (err < 0) { + kfree(chip); + pci_disable_device(pci); + return err; + } + chip->port = pci_resource_start(pci, 0); +]]> + </programlisting> + </informalexample> + </para> + + <para> + <!-- obsolete --> + It will reserve the I/O port region of 8 bytes of the given + PCI device. The returned value, chip->res_port, is allocated + via <function>kmalloc()</function> by + <function>request_region()</function>. The pointer must be + released via <function>kfree()</function>, but there is a + problem with this. This issue will be explained later. + </para> + + <para> + The allocation of an interrupt source is done like this: + + <informalexample> + <programlisting> +<![CDATA[ + if (request_irq(pci->irq, snd_mychip_interrupt, + IRQF_SHARED, KBUILD_MODNAME, chip)) { + printk(KERN_ERR "cannot grab irq %d\n", pci->irq); + snd_mychip_free(chip); + return -EBUSY; + } + chip->irq = pci->irq; +]]> + </programlisting> + </informalexample> + + where <function>snd_mychip_interrupt()</function> is the + interrupt handler defined <link + linkend="pcm-interface-interrupt-handler"><citetitle>later</citetitle></link>. + Note that chip->irq should be defined + only when <function>request_irq()</function> succeeded. + </para> + + <para> + On the PCI bus, interrupts can be shared. Thus, + <constant>IRQF_SHARED</constant> is used as the interrupt flag of + <function>request_irq()</function>. + </para> + + <para> + The last argument of <function>request_irq()</function> is the + data pointer passed to the interrupt handler. Usually, the + chip-specific record is used for that, but you can use what you + like, too. + </para> + + <para> + I won't give details about the interrupt handler at this + point, but at least its appearance can be explained now. The + interrupt handler looks usually like the following: + + <informalexample> + <programlisting> +<![CDATA[ + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + .... + return IRQ_HANDLED; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + Now let's write the corresponding destructor for the resources + above. The role of destructor is simple: disable the hardware + (if already activated) and release the resources. So far, we + have no hardware part, so the disabling code is not written here. + </para> + + <para> + To release the resources, the <quote>check-and-release</quote> + method is a safer way. For the interrupt, do like this: + + <informalexample> + <programlisting> +<![CDATA[ + if (chip->irq >= 0) + free_irq(chip->irq, chip); +]]> + </programlisting> + </informalexample> + + Since the irq number can start from 0, you should initialize + chip->irq with a negative value (e.g. -1), so that you can + check the validity of the irq number as above. + </para> + + <para> + When you requested I/O ports or memory regions via + <function>pci_request_region()</function> or + <function>pci_request_regions()</function> like in this example, + release the resource(s) using the corresponding function, + <function>pci_release_region()</function> or + <function>pci_release_regions()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + pci_release_regions(chip->pci); +]]> + </programlisting> + </informalexample> + </para> + + <para> + When you requested manually via <function>request_region()</function> + or <function>request_mem_region</function>, you can release it via + <function>release_resource()</function>. Suppose that you keep + the resource pointer returned from <function>request_region()</function> + in chip->res_port, the release procedure looks like: + + <informalexample> + <programlisting> +<![CDATA[ + release_and_free_resource(chip->res_port); +]]> + </programlisting> + </informalexample> + </para> + + <para> + Don't forget to call <function>pci_disable_device()</function> + before the end. + </para> + + <para> + And finally, release the chip-specific record. + + <informalexample> + <programlisting> +<![CDATA[ + kfree(chip); +]]> + </programlisting> + </informalexample> + </para> + + <para> + We didn't implement the hardware disabling part in the above. + If you need to do this, please note that the destructor may be + called even before the initialization of the chip is completed. + It would be better to have a flag to skip hardware disabling + if the hardware was not initialized yet. + </para> + + <para> + When the chip-data is assigned to the card using + <function>snd_device_new()</function> with + <constant>SNDRV_DEV_LOWLELVEL</constant> , its destructor is + called at the last. That is, it is assured that all other + components like PCMs and controls have already been released. + You don't have to stop PCMs, etc. explicitly, but just + call low-level hardware stopping. + </para> + + <para> + The management of a memory-mapped region is almost as same as + the management of an I/O port. You'll need three fields like + the following: + + <informalexample> + <programlisting> +<![CDATA[ + struct mychip { + .... + unsigned long iobase_phys; + void __iomem *iobase_virt; + }; +]]> + </programlisting> + </informalexample> + + and the allocation would be like below: + + <informalexample> + <programlisting> +<![CDATA[ + if ((err = pci_request_regions(pci, "My Chip")) < 0) { + kfree(chip); + return err; + } + chip->iobase_phys = pci_resource_start(pci, 0); + chip->iobase_virt = ioremap_nocache(chip->iobase_phys, + pci_resource_len(pci, 0)); +]]> + </programlisting> + </informalexample> + + and the corresponding destructor would be: + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_mychip_free(struct mychip *chip) + { + .... + if (chip->iobase_virt) + iounmap(chip->iobase_virt); + .... + pci_release_regions(chip->pci); + .... + } +]]> + </programlisting> + </informalexample> + </para> + + </section> + + <section id="pci-resource-entries"> + <title>PCI Entries</title> + <para> + So far, so good. Let's finish the missing PCI + stuff. At first, we need a + <structname>pci_device_id</structname> table for this + chipset. It's a table of PCI vendor/device ID number, and some + masks. + </para> + + <para> + For example, + + <informalexample> + <programlisting> +<![CDATA[ + static struct pci_device_id snd_mychip_ids[] = { + { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, + PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, + .... + { 0, } + }; + MODULE_DEVICE_TABLE(pci, snd_mychip_ids); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The first and second fields of + the <structname>pci_device_id</structname> structure are the vendor and + device IDs. If you have no reason to filter the matching + devices, you can leave the remaining fields as above. The last + field of the <structname>pci_device_id</structname> struct contains + private data for this entry. You can specify any value here, for + example, to define specific operations for supported device IDs. + Such an example is found in the intel8x0 driver. + </para> + + <para> + The last entry of this list is the terminator. You must + specify this all-zero entry. + </para> + + <para> + Then, prepare the <structname>pci_driver</structname> record: + + <informalexample> + <programlisting> +<![CDATA[ + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_mychip_ids, + .probe = snd_mychip_probe, + .remove = snd_mychip_remove, + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + The <structfield>probe</structfield> and + <structfield>remove</structfield> functions have already + been defined in the previous sections. + The <structfield>name</structfield> + field is the name string of this device. Note that you must not + use a slash <quote>/</quote> in this string. + </para> + + <para> + And at last, the module entries: + + <informalexample> + <programlisting> +<![CDATA[ + static int __init alsa_card_mychip_init(void) + { + return pci_register_driver(&driver); + } + + static void __exit alsa_card_mychip_exit(void) + { + pci_unregister_driver(&driver); + } + + module_init(alsa_card_mychip_init) + module_exit(alsa_card_mychip_exit) +]]> + </programlisting> + </informalexample> + </para> + + <para> + Note that these module entries are tagged with + <parameter>__init</parameter> and + <parameter>__exit</parameter> prefixes. + </para> + + <para> + Oh, one thing was forgotten. If you have no exported symbols, + you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). + + <informalexample> + <programlisting> +<![CDATA[ + EXPORT_NO_SYMBOLS; +]]> + </programlisting> + </informalexample> + + That's all! + </para> + </section> + </chapter> + + +<!-- ****************************************************** --> +<!-- PCM Interface --> +<!-- ****************************************************** --> + <chapter id="pcm-interface"> + <title>PCM Interface</title> + + <section id="pcm-interface-general"> + <title>General</title> + <para> + The PCM middle layer of ALSA is quite powerful and it is only + necessary for each driver to implement the low-level functions + to access its hardware. + </para> + + <para> + For accessing to the PCM layer, you need to include + <filename><sound/pcm.h></filename> first. In addition, + <filename><sound/pcm_params.h></filename> might be needed + if you access to some functions related with hw_param. + </para> + + <para> + Each card device can have up to four pcm instances. A pcm + instance corresponds to a pcm device file. The limitation of + number of instances comes only from the available bit size of + the Linux's device numbers. Once when 64bit device number is + used, we'll have more pcm instances available. + </para> + + <para> + A pcm instance consists of pcm playback and capture streams, + and each pcm stream consists of one or more pcm substreams. Some + soundcards support multiple playback functions. For example, + emu10k1 has a PCM playback of 32 stereo substreams. In this case, at + each open, a free substream is (usually) automatically chosen + and opened. Meanwhile, when only one substream exists and it was + already opened, the successful open will either block + or error with <constant>EAGAIN</constant> according to the + file open mode. But you don't have to care about such details in your + driver. The PCM middle layer will take care of such work. + </para> + </section> + + <section id="pcm-interface-example"> + <title>Full Code Example</title> + <para> + The example code below does not include any hardware access + routines but shows only the skeleton, how to build up the PCM + interfaces. + + <example> + <title>PCM Example Code</title> + <programlisting> +<![CDATA[ + #include <sound/pcm.h> + .... + + /* hardware definition */ + static struct snd_pcm_hardware snd_mychip_playback_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; + + /* hardware definition */ + static struct snd_pcm_hardware snd_mychip_capture_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; + + /* open callback */ + static int snd_mychip_playback_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_playback_hw; + /* more hardware-initialization will be done here */ + .... + return 0; + } + + /* close callback */ + static int snd_mychip_playback_close(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + /* the hardware-specific codes will be here */ + .... + return 0; + + } + + /* open callback */ + static int snd_mychip_capture_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_capture_hw; + /* more hardware-initialization will be done here */ + .... + return 0; + } + + /* close callback */ + static int snd_mychip_capture_close(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + /* the hardware-specific codes will be here */ + .... + return 0; + + } + + /* hw_params callback */ + static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params) + { + return snd_pcm_lib_malloc_pages(substream, + params_buffer_bytes(hw_params)); + } + + /* hw_free callback */ + static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) + { + return snd_pcm_lib_free_pages(substream); + } + + /* prepare callback */ + static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + /* set up the hardware with the current configuration + * for example... + */ + mychip_set_sample_format(chip, runtime->format); + mychip_set_sample_rate(chip, runtime->rate); + mychip_set_channels(chip, runtime->channels); + mychip_set_dma_setup(chip, runtime->dma_addr, + chip->buffer_size, + chip->period_size); + return 0; + } + + /* trigger callback */ + static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, + int cmd) + { + switch (cmd) { + case SNDRV_PCM_TRIGGER_START: + /* do something to start the PCM engine */ + .... + break; + case SNDRV_PCM_TRIGGER_STOP: + /* do something to stop the PCM engine */ + .... + break; + default: + return -EINVAL; + } + } + + /* pointer callback */ + static snd_pcm_uframes_t + snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + unsigned int current_ptr; + + /* get the current hardware pointer */ + current_ptr = mychip_get_hw_pointer(chip); + return current_ptr; + } + + /* operators */ + static struct snd_pcm_ops snd_mychip_playback_ops = { + .open = snd_mychip_playback_open, + .close = snd_mychip_playback_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; + + /* operators */ + static struct snd_pcm_ops snd_mychip_capture_ops = { + .open = snd_mychip_capture_open, + .close = snd_mychip_capture_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; + + /* + * definitions of capture are omitted here... + */ + + /* create a pcm device */ + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + int err; + + err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); + if (err < 0) + return err; + pcm->private_data = chip; + strcpy(pcm->name, "My Chip"); + chip->pcm = pcm; + /* set operators */ + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, + &snd_mychip_playback_ops); + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, + &snd_mychip_capture_ops); + /* pre-allocation of buffers */ + /* NOTE: this may fail */ + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(chip->pci), + 64*1024, 64*1024); + return 0; + } +]]> + </programlisting> + </example> + </para> + </section> + + <section id="pcm-interface-constructor"> + <title>Constructor</title> + <para> + A pcm instance is allocated by the <function>snd_pcm_new()</function> + function. It would be better to create a constructor for pcm, + namely, + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + int err; + + err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); + if (err < 0) + return err; + pcm->private_data = chip; + strcpy(pcm->name, "My Chip"); + chip->pcm = pcm; + .... + return 0; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The <function>snd_pcm_new()</function> function takes four + arguments. The first argument is the card pointer to which this + pcm is assigned, and the second is the ID string. + </para> + + <para> + The third argument (<parameter>index</parameter>, 0 in the + above) is the index of this new pcm. It begins from zero. If + you create more than one pcm instances, specify the + different numbers in this argument. For example, + <parameter>index</parameter> = 1 for the second PCM device. + </para> + + <para> + The fourth and fifth arguments are the number of substreams + for playback and capture, respectively. Here 1 is used for + both arguments. When no playback or capture substreams are available, + pass 0 to the corresponding argument. + </para> + + <para> + If a chip supports multiple playbacks or captures, you can + specify more numbers, but they must be handled properly in + open/close, etc. callbacks. When you need to know which + substream you are referring to, then it can be obtained from + struct <structname>snd_pcm_substream</structname> data passed to each callback + as follows: + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_pcm_substream *substream; + int index = substream->number; +]]> + </programlisting> + </informalexample> + </para> + + <para> + After the pcm is created, you need to set operators for each + pcm stream. + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, + &snd_mychip_playback_ops); + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, + &snd_mychip_capture_ops); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The operators are defined typically like this: + + <informalexample> + <programlisting> +<![CDATA[ + static struct snd_pcm_ops snd_mychip_playback_ops = { + .open = snd_mychip_pcm_open, + .close = snd_mychip_pcm_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; +]]> + </programlisting> + </informalexample> + + All the callbacks are described in the + <link linkend="pcm-interface-operators"><citetitle> + Operators</citetitle></link> subsection. + </para> + + <para> + After setting the operators, you probably will want to + pre-allocate the buffer. For the pre-allocation, simply call + the following: + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(chip->pci), + 64*1024, 64*1024); +]]> + </programlisting> + </informalexample> + + It will allocate a buffer up to 64kB as default. + Buffer management details will be described in the later section <link + linkend="buffer-and-memory"><citetitle>Buffer and Memory + Management</citetitle></link>. + </para> + + <para> + Additionally, you can set some extra information for this pcm + in pcm->info_flags. + The available values are defined as + <constant>SNDRV_PCM_INFO_XXX</constant> in + <filename><sound/asound.h></filename>, which is used for + the hardware definition (described later). When your soundchip + supports only half-duplex, specify like this: + + <informalexample> + <programlisting> +<![CDATA[ + pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; +]]> + </programlisting> + </informalexample> + </para> + </section> + + <section id="pcm-interface-destructor"> + <title>... And the Destructor?</title> + <para> + The destructor for a pcm instance is not always + necessary. Since the pcm device will be released by the middle + layer code automatically, you don't have to call the destructor + explicitly. + </para> + + <para> + The destructor would be necessary if you created + special records internally and needed to release them. In such a + case, set the destructor function to + pcm->private_free: + + <example> + <title>PCM Instance with a Destructor</title> + <programlisting> +<![CDATA[ + static void mychip_pcm_free(struct snd_pcm *pcm) + { + struct mychip *chip = snd_pcm_chip(pcm); + /* free your own data */ + kfree(chip->my_private_pcm_data); + /* do what you like else */ + .... + } + + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + .... + /* allocate your own data */ + chip->my_private_pcm_data = kmalloc(...); + /* set the destructor */ + pcm->private_data = chip; + pcm->private_free = mychip_pcm_free; + .... + } +]]> + </programlisting> + </example> + </para> + </section> + + <section id="pcm-interface-runtime"> + <title>Runtime Pointer - The Chest of PCM Information</title> + <para> + When the PCM substream is opened, a PCM runtime instance is + allocated and assigned to the substream. This pointer is + accessible via <constant>substream->runtime</constant>. + This runtime pointer holds most information you need + to control the PCM: the copy of hw_params and sw_params configurations, the buffer + pointers, mmap records, spinlocks, etc. + </para> + + <para> + The definition of runtime instance is found in + <filename><sound/pcm.h></filename>. Here are + the contents of this file: + <informalexample> + <programlisting> +<![CDATA[ +struct _snd_pcm_runtime { + /* -- Status -- */ + struct snd_pcm_substream *trigger_master; + snd_timestamp_t trigger_tstamp; /* trigger timestamp */ + int overrange; + snd_pcm_uframes_t avail_max; + snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ + snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ + + /* -- HW params -- */ + snd_pcm_access_t access; /* access mode */ + snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ + snd_pcm_subformat_t subformat; /* subformat */ + unsigned int rate; /* rate in Hz */ + unsigned int channels; /* channels */ + snd_pcm_uframes_t period_size; /* period size */ + unsigned int periods; /* periods */ + snd_pcm_uframes_t buffer_size; /* buffer size */ + unsigned int tick_time; /* tick time */ + snd_pcm_uframes_t min_align; /* Min alignment for the format */ + size_t byte_align; + unsigned int frame_bits; + unsigned int sample_bits; + unsigned int info; + unsigned int rate_num; + unsigned int rate_den; + + /* -- SW params -- */ + struct timespec tstamp_mode; /* mmap timestamp is updated */ + unsigned int period_step; + unsigned int sleep_min; /* min ticks to sleep */ + snd_pcm_uframes_t start_threshold; + snd_pcm_uframes_t stop_threshold; + snd_pcm_uframes_t silence_threshold; /* Silence filling happens when + noise is nearest than this */ + snd_pcm_uframes_t silence_size; /* Silence filling size */ + snd_pcm_uframes_t boundary; /* pointers wrap point */ + + snd_pcm_uframes_t silenced_start; + snd_pcm_uframes_t silenced_size; + + snd_pcm_sync_id_t sync; /* hardware synchronization ID */ + + /* -- mmap -- */ + volatile struct snd_pcm_mmap_status *status; + volatile struct snd_pcm_mmap_control *control; + atomic_t mmap_count; + + /* -- locking / scheduling -- */ + spinlock_t lock; + wait_queue_head_t sleep; + struct timer_list tick_timer; + struct fasync_struct *fasync; + + /* -- private section -- */ + void *private_data; + void (*private_free)(struct snd_pcm_runtime *runtime); + + /* -- hardware description -- */ + struct snd_pcm_hardware hw; + struct snd_pcm_hw_constraints hw_constraints; + + /* -- timer -- */ + unsigned int timer_resolution; /* timer resolution */ + + /* -- DMA -- */ + unsigned char *dma_area; /* DMA area */ + dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ + size_t dma_bytes; /* size of DMA area */ + + struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ + +#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) + /* -- OSS things -- */ + struct snd_pcm_oss_runtime oss; +#endif +}; +]]> + </programlisting> + </informalexample> + </para> + + <para> + For the operators (callbacks) of each sound driver, most of + these records are supposed to be read-only. Only the PCM + middle-layer changes / updates them. The exceptions are + the hardware description (hw) DMA buffer information and the + private data. Besides, if you use the standard buffer allocation + method via <function>snd_pcm_lib_malloc_pages()</function>, + you don't need to set the DMA buffer information by yourself. + </para> + + <para> + In the sections below, important records are explained. + </para> + + <section id="pcm-interface-runtime-hw"> + <title>Hardware Description</title> + <para> + The hardware descriptor (struct <structname>snd_pcm_hardware</structname>) + contains the definitions of the fundamental hardware + configuration. Above all, you'll need to define this in + <link linkend="pcm-interface-operators-open-callback"><citetitle> + the open callback</citetitle></link>. + Note that the runtime instance holds the copy of the + descriptor, not the pointer to the existing descriptor. That + is, in the open callback, you can modify the copied descriptor + (<constant>runtime->hw</constant>) as you need. For example, if the maximum + number of channels is 1 only on some chip models, you can + still use the same hardware descriptor and change the + channels_max later: + <informalexample> + <programlisting> +<![CDATA[ + struct snd_pcm_runtime *runtime = substream->runtime; + ... + runtime->hw = snd_mychip_playback_hw; /* common definition */ + if (chip->model == VERY_OLD_ONE) + runtime->hw.channels_max = 1; +]]> + </programlisting> + </informalexample> + </para> + + <para> + Typically, you'll have a hardware descriptor as below: + <informalexample> + <programlisting> +<![CDATA[ + static struct snd_pcm_hardware snd_mychip_playback_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + <itemizedlist> + <listitem><para> + The <structfield>info</structfield> field contains the type and + capabilities of this pcm. The bit flags are defined in + <filename><sound/asound.h></filename> as + <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you + have to specify whether the mmap is supported and which + interleaved format is supported. + When the hardware supports mmap, add the + <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the + hardware supports the interleaved or the non-interleaved + formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or + <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must + be set, respectively. If both are supported, you can set both, + too. + </para> + + <para> + In the above example, <constant>MMAP_VALID</constant> and + <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap + mode. Usually both are set. Of course, + <constant>MMAP_VALID</constant> is set only if the mmap is + really supported. + </para> + + <para> + The other possible flags are + <constant>SNDRV_PCM_INFO_PAUSE</constant> and + <constant>SNDRV_PCM_INFO_RESUME</constant>. The + <constant>PAUSE</constant> bit means that the pcm supports the + <quote>pause</quote> operation, while the + <constant>RESUME</constant> bit means that the pcm supports + the full <quote>suspend/resume</quote> operation. + If the <constant>PAUSE</constant> flag is set, + the <structfield>trigger</structfield> callback below + must handle the corresponding (pause push/release) commands. + The suspend/resume trigger commands can be defined even without + the <constant>RESUME</constant> flag. See <link + linkend="power-management"><citetitle> + Power Management</citetitle></link> section for details. + </para> + + <para> + When the PCM substreams can be synchronized (typically, + synchronized start/stop of a playback and a capture streams), + you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, + too. In this case, you'll need to check the linked-list of + PCM substreams in the trigger callback. This will be + described in the later section. + </para> + </listitem> + + <listitem> + <para> + <structfield>formats</structfield> field contains the bit-flags + of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>). + If the hardware supports more than one format, give all or'ed + bits. In the example above, the signed 16bit little-endian + format is specified. + </para> + </listitem> + + <listitem> + <para> + <structfield>rates</structfield> field contains the bit-flags of + supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>). + When the chip supports continuous rates, pass + <constant>CONTINUOUS</constant> bit additionally. + The pre-defined rate bits are provided only for typical + rates. If your chip supports unconventional rates, you need to add + the <constant>KNOT</constant> bit and set up the hardware + constraint manually (explained later). + </para> + </listitem> + + <listitem> + <para> + <structfield>rate_min</structfield> and + <structfield>rate_max</structfield> define the minimum and + maximum sample rate. This should correspond somehow to + <structfield>rates</structfield> bits. + </para> + </listitem> + + <listitem> + <para> + <structfield>channel_min</structfield> and + <structfield>channel_max</structfield> + define, as you might already expected, the minimum and maximum + number of channels. + </para> + </listitem> + + <listitem> + <para> + <structfield>buffer_bytes_max</structfield> defines the + maximum buffer size in bytes. There is no + <structfield>buffer_bytes_min</structfield> field, since + it can be calculated from the minimum period size and the + minimum number of periods. + Meanwhile, <structfield>period_bytes_min</structfield> and + define the minimum and maximum size of the period in bytes. + <structfield>periods_max</structfield> and + <structfield>periods_min</structfield> define the maximum and + minimum number of periods in the buffer. + </para> + + <para> + The <quote>period</quote> is a term that corresponds to + a fragment in the OSS world. The period defines the size at + which a PCM interrupt is generated. This size strongly + depends on the hardware. + Generally, the smaller period size will give you more + interrupts, that is, more controls. + In the case of capture, this size defines the input latency. + On the other hand, the whole buffer size defines the + output latency for the playback direction. + </para> + </listitem> + + <listitem> + <para> + There is also a field <structfield>fifo_size</structfield>. + This specifies the size of the hardware FIFO, but currently it + is neither used in the driver nor in the alsa-lib. So, you + can ignore this field. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="pcm-interface-runtime-config"> + <title>PCM Configurations</title> + <para> + Ok, let's go back again to the PCM runtime records. + The most frequently referred records in the runtime instance are + the PCM configurations. + The PCM configurations are stored in the runtime instance + after the application sends <type>hw_params</type> data via + alsa-lib. There are many fields copied from hw_params and + sw_params structs. For example, + <structfield>format</structfield> holds the format type + chosen by the application. This field contains the enum value + <constant>SNDRV_PCM_FORMAT_XXX</constant>. + </para> + + <para> + One thing to be noted is that the configured buffer and period + sizes are stored in <quote>frames</quote> in the runtime. + In the ALSA world, 1 frame = channels * samples-size. + For conversion between frames and bytes, you can use the + <function>frames_to_bytes()</function> and + <function>bytes_to_frames()</function> helper functions. + <informalexample> + <programlisting> +<![CDATA[ + period_bytes = frames_to_bytes(runtime, runtime->period_size); +]]> + </programlisting> + </informalexample> + </para> + + <para> + Also, many software parameters (sw_params) are + stored in frames, too. Please check the type of the field. + <type>snd_pcm_uframes_t</type> is for the frames as unsigned + integer while <type>snd_pcm_sframes_t</type> is for the frames + as signed integer. + </para> + </section> + + <section id="pcm-interface-runtime-dma"> + <title>DMA Buffer Information</title> + <para> + The DMA buffer is defined by the following four fields, + <structfield>dma_area</structfield>, + <structfield>dma_addr</structfield>, + <structfield>dma_bytes</structfield> and + <structfield>dma_private</structfield>. + The <structfield>dma_area</structfield> holds the buffer + pointer (the logical address). You can call + <function>memcpy</function> from/to + this pointer. Meanwhile, <structfield>dma_addr</structfield> + holds the physical address of the buffer. This field is + specified only when the buffer is a linear buffer. + <structfield>dma_bytes</structfield> holds the size of buffer + in bytes. <structfield>dma_private</structfield> is used for + the ALSA DMA allocator. + </para> + + <para> + If you use a standard ALSA function, + <function>snd_pcm_lib_malloc_pages()</function>, for + allocating the buffer, these fields are set by the ALSA middle + layer, and you should <emphasis>not</emphasis> change them by + yourself. You can read them but not write them. + On the other hand, if you want to allocate the buffer by + yourself, you'll need to manage it in hw_params callback. + At least, <structfield>dma_bytes</structfield> is mandatory. + <structfield>dma_area</structfield> is necessary when the + buffer is mmapped. If your driver doesn't support mmap, this + field is not necessary. <structfield>dma_addr</structfield> + is also optional. You can use + <structfield>dma_private</structfield> as you like, too. + </para> + </section> + + <section id="pcm-interface-runtime-status"> + <title>Running Status</title> + <para> + The running status can be referred via <constant>runtime->status</constant>. + This is the pointer to the struct <structname>snd_pcm_mmap_status</structname> + record. For example, you can get the current DMA hardware + pointer via <constant>runtime->status->hw_ptr</constant>. + </para> + + <para> + The DMA application pointer can be referred via + <constant>runtime->control</constant>, which points to the + struct <structname>snd_pcm_mmap_control</structname> record. + However, accessing directly to this value is not recommended. + </para> + </section> + + <section id="pcm-interface-runtime-private"> + <title>Private Data</title> + <para> + You can allocate a record for the substream and store it in + <constant>runtime->private_data</constant>. Usually, this + is done in + <link linkend="pcm-interface-operators-open-callback"><citetitle> + the open callback</citetitle></link>. + Don't mix this with <constant>pcm->private_data</constant>. + The <constant>pcm->private_data</constant> usually points to the + chip instance assigned statically at the creation of PCM, while the + <constant>runtime->private_data</constant> points to a dynamic + data structure created at the PCM open callback. + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_open(struct snd_pcm_substream *substream) + { + struct my_pcm_data *data; + .... + data = kmalloc(sizeof(*data), GFP_KERNEL); + substream->runtime->private_data = data; + .... + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The allocated object must be released in + <link linkend="pcm-interface-operators-open-callback"><citetitle> + the close callback</citetitle></link>. + </para> + </section> + + </section> + + <section id="pcm-interface-operators"> + <title>Operators</title> + <para> + OK, now let me give details about each pcm callback + (<parameter>ops</parameter>). In general, every callback must + return 0 if successful, or a negative error number + such as <constant>-EINVAL</constant>. To choose an appropriate + error number, it is advised to check what value other parts of + the kernel return when the same kind of request fails. + </para> + + <para> + The callback function takes at least the argument with + <structname>snd_pcm_substream</structname> pointer. To retrieve + the chip record from the given substream instance, you can use the + following macro. + + <informalexample> + <programlisting> +<![CDATA[ + int xxx() { + struct mychip *chip = snd_pcm_substream_chip(substream); + .... + } +]]> + </programlisting> + </informalexample> + + The macro reads <constant>substream->private_data</constant>, + which is a copy of <constant>pcm->private_data</constant>. + You can override the former if you need to assign different data + records per PCM substream. For example, the cmi8330 driver assigns + different private_data for playback and capture directions, + because it uses two different codecs (SB- and AD-compatible) for + different directions. + </para> + + <section id="pcm-interface-operators-open-callback"> + <title>open callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_open(struct snd_pcm_substream *substream); +]]> + </programlisting> + </informalexample> + + This is called when a pcm substream is opened. + </para> + + <para> + At least, here you have to initialize the runtime->hw + record. Typically, this is done by like this: + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_playback_hw; + return 0; + } +]]> + </programlisting> + </informalexample> + + where <parameter>snd_mychip_playback_hw</parameter> is the + pre-defined hardware description. + </para> + + <para> + You can allocate a private data in this callback, as described + in <link linkend="pcm-interface-runtime-private"><citetitle> + Private Data</citetitle></link> section. + </para> + + <para> + If the hardware configuration needs more constraints, set the + hardware constraints here, too. + See <link linkend="pcm-interface-constraints"><citetitle> + Constraints</citetitle></link> for more details. + </para> + </section> + + <section id="pcm-interface-operators-close-callback"> + <title>close callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_close(struct snd_pcm_substream *substream); +]]> + </programlisting> + </informalexample> + + Obviously, this is called when a pcm substream is closed. + </para> + + <para> + Any private instance for a pcm substream allocated in the + open callback will be released here. + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_close(struct snd_pcm_substream *substream) + { + .... + kfree(substream->runtime->private_data); + .... + } +]]> + </programlisting> + </informalexample> + </para> + </section> + + <section id="pcm-interface-operators-ioctl-callback"> + <title>ioctl callback</title> + <para> + This is used for any special call to pcm ioctls. But + usually you can pass a generic ioctl callback, + <function>snd_pcm_lib_ioctl</function>. + </para> + </section> + + <section id="pcm-interface-operators-hw-params-callback"> + <title>hw_params callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params); +]]> + </programlisting> + </informalexample> + </para> + + <para> + This is called when the hardware parameter + (<structfield>hw_params</structfield>) is set + up by the application, + that is, once when the buffer size, the period size, the + format, etc. are defined for the pcm substream. + </para> + + <para> + Many hardware setups should be done in this callback, + including the allocation of buffers. + </para> + + <para> + Parameters to be initialized are retrieved by + <function>params_xxx()</function> macros. To allocate + buffer, you can call a helper function, + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); +]]> + </programlisting> + </informalexample> + + <function>snd_pcm_lib_malloc_pages()</function> is available + only when the DMA buffers have been pre-allocated. + See the section <link + linkend="buffer-and-memory-buffer-types"><citetitle> + Buffer Types</citetitle></link> for more details. + </para> + + <para> + Note that this and <structfield>prepare</structfield> callbacks + may be called multiple times per initialization. + For example, the OSS emulation may + call these callbacks at each change via its ioctl. + </para> + + <para> + Thus, you need to be careful not to allocate the same buffers + many times, which will lead to memory leaks! Calling the + helper function above many times is OK. It will release the + previous buffer automatically when it was already allocated. + </para> + + <para> + Another note is that this callback is non-atomic + (schedulable) as default, i.e. when no + <structfield>nonatomic</structfield> flag set. + This is important, because the + <structfield>trigger</structfield> callback + is atomic (non-schedulable). That is, mutexes or any + schedule-related functions are not available in + <structfield>trigger</structfield> callback. + Please see the subsection + <link linkend="pcm-interface-atomicity"><citetitle> + Atomicity</citetitle></link> for details. + </para> + </section> + + <section id="pcm-interface-operators-hw-free-callback"> + <title>hw_free callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_hw_free(struct snd_pcm_substream *substream); +]]> + </programlisting> + </informalexample> + </para> + + <para> + This is called to release the resources allocated via + <structfield>hw_params</structfield>. For example, releasing the + buffer via + <function>snd_pcm_lib_malloc_pages()</function> is done by + calling the following: + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_lib_free_pages(substream); +]]> + </programlisting> + </informalexample> + </para> + + <para> + This function is always called before the close callback is called. + Also, the callback may be called multiple times, too. + Keep track whether the resource was already released. + </para> + </section> + + <section id="pcm-interface-operators-prepare-callback"> + <title>prepare callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_prepare(struct snd_pcm_substream *substream); +]]> + </programlisting> + </informalexample> + </para> + + <para> + This callback is called when the pcm is + <quote>prepared</quote>. You can set the format type, sample + rate, etc. here. The difference from + <structfield>hw_params</structfield> is that the + <structfield>prepare</structfield> callback will be called each + time + <function>snd_pcm_prepare()</function> is called, i.e. when + recovering after underruns, etc. + </para> + + <para> + Note that this callback is now non-atomic. + You can use schedule-related functions safely in this callback. + </para> + + <para> + In this and the following callbacks, you can refer to the + values via the runtime record, + substream->runtime. + For example, to get the current + rate, format or channels, access to + runtime->rate, + runtime->format or + runtime->channels, respectively. + The physical address of the allocated buffer is set to + runtime->dma_area. The buffer and period sizes are + in runtime->buffer_size and runtime->period_size, + respectively. + </para> + + <para> + Be careful that this callback will be called many times at + each setup, too. + </para> + </section> + + <section id="pcm-interface-operators-trigger-callback"> + <title>trigger callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); +]]> + </programlisting> + </informalexample> + + This is called when the pcm is started, stopped or paused. + </para> + + <para> + Which action is specified in the second argument, + <constant>SNDRV_PCM_TRIGGER_XXX</constant> in + <filename><sound/pcm.h></filename>. At least, + the <constant>START</constant> and <constant>STOP</constant> + commands must be defined in this callback. + + <informalexample> + <programlisting> +<![CDATA[ + switch (cmd) { + case SNDRV_PCM_TRIGGER_START: + /* do something to start the PCM engine */ + break; + case SNDRV_PCM_TRIGGER_STOP: + /* do something to stop the PCM engine */ + break; + default: + return -EINVAL; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + When the pcm supports the pause operation (given in the info + field of the hardware table), the <constant>PAUSE_PUSH</constant> + and <constant>PAUSE_RELEASE</constant> commands must be + handled here, too. The former is the command to pause the pcm, + and the latter to restart the pcm again. + </para> + + <para> + When the pcm supports the suspend/resume operation, + regardless of full or partial suspend/resume support, + the <constant>SUSPEND</constant> and <constant>RESUME</constant> + commands must be handled, too. + These commands are issued when the power-management status is + changed. Obviously, the <constant>SUSPEND</constant> and + <constant>RESUME</constant> commands + suspend and resume the pcm substream, and usually, they + are identical to the <constant>STOP</constant> and + <constant>START</constant> commands, respectively. + See the <link linkend="power-management"><citetitle> + Power Management</citetitle></link> section for details. + </para> + + <para> + As mentioned, this callback is atomic as default unless + <structfield>nonatomic</structfield> flag set, and + you cannot call functions which may sleep. + The trigger callback should be as minimal as possible, + just really triggering the DMA. The other stuff should be + initialized hw_params and prepare callbacks properly + beforehand. + </para> + </section> + + <section id="pcm-interface-operators-pointer-callback"> + <title>pointer callback</title> + <para> + <informalexample> + <programlisting> +<![CDATA[ + static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) +]]> + </programlisting> + </informalexample> + + This callback is called when the PCM middle layer inquires + the current hardware position on the buffer. The position must + be returned in frames, + ranging from 0 to buffer_size - 1. + </para> + + <para> + This is called usually from the buffer-update routine in the + pcm middle layer, which is invoked when + <function>snd_pcm_period_elapsed()</function> is called in the + interrupt routine. Then the pcm middle layer updates the + position and calculates the available space, and wakes up the + sleeping poll threads, etc. + </para> + + <para> + This callback is also atomic as default. + </para> + </section> + + <section id="pcm-interface-operators-copy-silence"> + <title>copy and silence callbacks</title> + <para> + These callbacks are not mandatory, and can be omitted in + most cases. These callbacks are used when the hardware buffer + cannot be in the normal memory space. Some chips have their + own buffer on the hardware which is not mappable. In such a + case, you have to transfer the data manually from the memory + buffer to the hardware buffer. Or, if the buffer is + non-contiguous on both physical and virtual memory spaces, + these callbacks must be defined, too. + </para> + + <para> + If these two callbacks are defined, copy and set-silence + operations are done by them. The detailed will be described in + the later section <link + linkend="buffer-and-memory"><citetitle>Buffer and Memory + Management</citetitle></link>. + </para> + </section> + + <section id="pcm-interface-operators-ack"> + <title>ack callback</title> + <para> + This callback is also not mandatory. This callback is called + when the appl_ptr is updated in read or write operations. + Some drivers like emu10k1-fx and cs46xx need to track the + current appl_ptr for the internal buffer, and this callback + is useful only for such a purpose. + </para> + <para> + This callback is atomic as default. + </para> + </section> + + <section id="pcm-interface-operators-page-callback"> + <title>page callback</title> + + <para> + This callback is optional too. This callback is used + mainly for non-contiguous buffers. The mmap calls this + callback to get the page address. Some examples will be + explained in the later section <link + linkend="buffer-and-memory"><citetitle>Buffer and Memory + Management</citetitle></link>, too. + </para> + </section> + </section> + + <section id="pcm-interface-interrupt-handler"> + <title>Interrupt Handler</title> + <para> + The rest of pcm stuff is the PCM interrupt handler. The + role of PCM interrupt handler in the sound driver is to update + the buffer position and to tell the PCM middle layer when the + buffer position goes across the prescribed period size. To + inform this, call the <function>snd_pcm_period_elapsed()</function> + function. + </para> + + <para> + There are several types of sound chips to generate the interrupts. + </para> + + <section id="pcm-interface-interrupt-handler-boundary"> + <title>Interrupts at the period (fragment) boundary</title> + <para> + This is the most frequently found type: the hardware + generates an interrupt at each period boundary. + In this case, you can call + <function>snd_pcm_period_elapsed()</function> at each + interrupt. + </para> + + <para> + <function>snd_pcm_period_elapsed()</function> takes the + substream pointer as its argument. Thus, you need to keep the + substream pointer accessible from the chip instance. For + example, define substream field in the chip record to hold the + current running substream pointer, and set the pointer value + at open callback (and reset at close callback). + </para> + + <para> + If you acquire a spinlock in the interrupt handler, and the + lock is used in other pcm callbacks, too, then you have to + release the lock before calling + <function>snd_pcm_period_elapsed()</function>, because + <function>snd_pcm_period_elapsed()</function> calls other pcm + callbacks inside. + </para> + + <para> + Typical code would be like: + + <example> + <title>Interrupt Handler Case #1</title> + <programlisting> +<![CDATA[ + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + spin_lock(&chip->lock); + .... + if (pcm_irq_invoked(chip)) { + /* call updater, unlock before it */ + spin_unlock(&chip->lock); + snd_pcm_period_elapsed(chip->substream); + spin_lock(&chip->lock); + /* acknowledge the interrupt if necessary */ + } + .... + spin_unlock(&chip->lock); + return IRQ_HANDLED; + } +]]> + </programlisting> + </example> + </para> + </section> + + <section id="pcm-interface-interrupt-handler-timer"> + <title>High frequency timer interrupts</title> + <para> + This happens when the hardware doesn't generate interrupts + at the period boundary but issues timer interrupts at a fixed + timer rate (e.g. es1968 or ymfpci drivers). + In this case, you need to check the current hardware + position and accumulate the processed sample length at each + interrupt. When the accumulated size exceeds the period + size, call + <function>snd_pcm_period_elapsed()</function> and reset the + accumulator. + </para> + + <para> + Typical code would be like the following. + + <example> + <title>Interrupt Handler Case #2</title> + <programlisting> +<![CDATA[ + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + spin_lock(&chip->lock); + .... + if (pcm_irq_invoked(chip)) { + unsigned int last_ptr, size; + /* get the current hardware pointer (in frames) */ + last_ptr = get_hw_ptr(chip); + /* calculate the processed frames since the + * last update + */ + if (last_ptr < chip->last_ptr) + size = runtime->buffer_size + last_ptr + - chip->last_ptr; + else + size = last_ptr - chip->last_ptr; + /* remember the last updated point */ + chip->last_ptr = last_ptr; + /* accumulate the size */ + chip->size += size; + /* over the period boundary? */ + if (chip->size >= runtime->period_size) { + /* reset the accumulator */ + chip->size %= runtime->period_size; + /* call updater */ + spin_unlock(&chip->lock); + snd_pcm_period_elapsed(substream); + spin_lock(&chip->lock); + } + /* acknowledge the interrupt if necessary */ + } + .... + spin_unlock(&chip->lock); + return IRQ_HANDLED; + } +]]> + </programlisting> + </example> + </para> + </section> + + <section id="pcm-interface-interrupt-handler-both"> + <title>On calling <function>snd_pcm_period_elapsed()</function></title> + <para> + In both cases, even if more than one period are elapsed, you + don't have to call + <function>snd_pcm_period_elapsed()</function> many times. Call + only once. And the pcm layer will check the current hardware + pointer and update to the latest status. + </para> + </section> + </section> + + <section id="pcm-interface-atomicity"> + <title>Atomicity</title> + <para> + One of the most important (and thus difficult to debug) problems + in kernel programming are race conditions. + In the Linux kernel, they are usually avoided via spin-locks, mutexes + or semaphores. In general, if a race condition can happen + in an interrupt handler, it has to be managed atomically, and you + have to use a spinlock to protect the critical session. If the + critical section is not in interrupt handler code and + if taking a relatively long time to execute is acceptable, you + should use mutexes or semaphores instead. + </para> + + <para> + As already seen, some pcm callbacks are atomic and some are + not. For example, the <parameter>hw_params</parameter> callback is + non-atomic, while <parameter>trigger</parameter> callback is + atomic. This means, the latter is called already in a spinlock + held by the PCM middle layer. Please take this atomicity into + account when you choose a locking scheme in the callbacks. + </para> + + <para> + In the atomic callbacks, you cannot use functions which may call + <function>schedule</function> or go to + <function>sleep</function>. Semaphores and mutexes can sleep, + and hence they cannot be used inside the atomic callbacks + (e.g. <parameter>trigger</parameter> callback). + To implement some delay in such a callback, please use + <function>udelay()</function> or <function>mdelay()</function>. + </para> + + <para> + All three atomic callbacks (trigger, pointer, and ack) are + called with local interrupts disabled. + </para> + + <para> + The recent changes in PCM core code, however, allow all PCM + operations to be non-atomic. This assumes that the all caller + sides are in non-atomic contexts. For example, the function + <function>snd_pcm_period_elapsed()</function> is called + typically from the interrupt handler. But, if you set up the + driver to use a threaded interrupt handler, this call can be in + non-atomic context, too. In such a case, you can set + <structfield>nonatomic</structfield> filed of + <structname>snd_pcm</structname> object after creating it. + When this flag is set, mutex and rwsem are used internally in + the PCM core instead of spin and rwlocks, so that you can call + all PCM functions safely in a non-atomic context. + </para> + + </section> + <section id="pcm-interface-constraints"> + <title>Constraints</title> + <para> + If your chip supports unconventional sample rates, or only the + limited samples, you need to set a constraint for the + condition. + </para> + + <para> + For example, in order to restrict the sample rates in the some + supported values, use + <function>snd_pcm_hw_constraint_list()</function>. + You need to call this function in the open callback. + + <example> + <title>Example of Hardware Constraints</title> + <programlisting> +<![CDATA[ + static unsigned int rates[] = + {4000, 10000, 22050, 44100}; + static struct snd_pcm_hw_constraint_list constraints_rates = { + .count = ARRAY_SIZE(rates), + .list = rates, + .mask = 0, + }; + + static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) + { + int err; + .... + err = snd_pcm_hw_constraint_list(substream->runtime, 0, + SNDRV_PCM_HW_PARAM_RATE, + &constraints_rates); + if (err < 0) + return err; + .... + } +]]> + </programlisting> + </example> + </para> + + <para> + There are many different constraints. + Look at <filename>sound/pcm.h</filename> for a complete list. + You can even define your own constraint rules. + For example, let's suppose my_chip can manage a substream of 1 channel + if and only if the format is S16_LE, otherwise it supports any format + specified in the <structname>snd_pcm_hardware</structname> structure (or in any + other constraint_list). You can build a rule like this: + + <example> + <title>Example of Hardware Constraints for Channels</title> + <programlisting> +<![CDATA[ + static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) + { + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_interval ch; + + snd_interval_any(&ch); + if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { + ch.min = ch.max = 1; + ch.integer = 1; + return snd_interval_refine(c, &ch); + } + return 0; + } +]]> + </programlisting> + </example> + </para> + + <para> + Then you need to call this function to add your rule: + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, + hw_rule_channels_by_format, NULL, + SNDRV_PCM_HW_PARAM_FORMAT, -1); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The rule function is called when an application sets the PCM + format, and it refines the number of channels accordingly. + But an application may set the number of channels before + setting the format. Thus you also need to define the inverse rule: + + <example> + <title>Example of Hardware Constraints for Formats</title> + <programlisting> +<![CDATA[ + static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) + { + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_mask fmt; + + snd_mask_any(&fmt); /* Init the struct */ + if (c->min < 2) { + fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; + return snd_mask_refine(f, &fmt); + } + return 0; + } +]]> + </programlisting> + </example> + </para> + + <para> + ...and in the open callback: + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, + hw_rule_format_by_channels, NULL, + SNDRV_PCM_HW_PARAM_CHANNELS, -1); +]]> + </programlisting> + </informalexample> + </para> + + <para> + I won't give more details here, rather I + would like to say, <quote>Luke, use the source.</quote> + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Control Interface --> +<!-- ****************************************************** --> + <chapter id="control-interface"> + <title>Control Interface</title> + + <section id="control-interface-general"> + <title>General</title> + <para> + The control interface is used widely for many switches, + sliders, etc. which are accessed from user-space. Its most + important use is the mixer interface. In other words, since ALSA + 0.9.x, all the mixer stuff is implemented on the control kernel API. + </para> + + <para> + ALSA has a well-defined AC97 control module. If your chip + supports only the AC97 and nothing else, you can skip this + section. + </para> + + <para> + The control API is defined in + <filename><sound/control.h></filename>. + Include this file if you want to add your own controls. + </para> + </section> + + <section id="control-interface-definition"> + <title>Definition of Controls</title> + <para> + To create a new control, you need to define the + following three + callbacks: <structfield>info</structfield>, + <structfield>get</structfield> and + <structfield>put</structfield>. Then, define a + struct <structname>snd_kcontrol_new</structname> record, such as: + + <example> + <title>Definition of a Control</title> + <programlisting> +<![CDATA[ + static struct snd_kcontrol_new my_control = { + .iface = SNDRV_CTL_ELEM_IFACE_MIXER, + .name = "PCM Playback Switch", + .index = 0, + .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, + .private_value = 0xffff, + .info = my_control_info, + .get = my_control_get, + .put = my_control_put + }; +]]> + </programlisting> + </example> + </para> + + <para> + The <structfield>iface</structfield> field specifies the control + type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which + is usually <constant>MIXER</constant>. + Use <constant>CARD</constant> for global controls that are not + logically part of the mixer. + If the control is closely associated with some specific device on + the sound card, use <constant>HWDEP</constant>, + <constant>PCM</constant>, <constant>RAWMIDI</constant>, + <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and + specify the device number with the + <structfield>device</structfield> and + <structfield>subdevice</structfield> fields. + </para> + + <para> + The <structfield>name</structfield> is the name identifier + string. Since ALSA 0.9.x, the control name is very important, + because its role is classified from its name. There are + pre-defined standard control names. The details are described in + the <link linkend="control-interface-control-names"><citetitle> + Control Names</citetitle></link> subsection. + </para> + + <para> + The <structfield>index</structfield> field holds the index number + of this control. If there are several different controls with + the same name, they can be distinguished by the index + number. This is the case when + several codecs exist on the card. If the index is zero, you can + omit the definition above. + </para> + + <para> + The <structfield>access</structfield> field contains the access + type of this control. Give the combination of bit masks, + <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there. + The details will be explained in + the <link linkend="control-interface-access-flags"><citetitle> + Access Flags</citetitle></link> subsection. + </para> + + <para> + The <structfield>private_value</structfield> field contains + an arbitrary long integer value for this record. When using + the generic <structfield>info</structfield>, + <structfield>get</structfield> and + <structfield>put</structfield> callbacks, you can pass a value + through this field. If several small numbers are necessary, you can + combine them in bitwise. Or, it's possible to give a pointer + (casted to unsigned long) of some record to this field, too. + </para> + + <para> + The <structfield>tlv</structfield> field can be used to provide + metadata about the control; see the + <link linkend="control-interface-tlv"> + <citetitle>Metadata</citetitle></link> subsection. + </para> + + <para> + The other three are + <link linkend="control-interface-callbacks"><citetitle> + callback functions</citetitle></link>. + </para> + </section> + + <section id="control-interface-control-names"> + <title>Control Names</title> + <para> + There are some standards to define the control names. A + control is usually defined from the three parts as + <quote>SOURCE DIRECTION FUNCTION</quote>. + </para> + + <para> + The first, <constant>SOURCE</constant>, specifies the source + of the control, and is a string such as <quote>Master</quote>, + <quote>PCM</quote>, <quote>CD</quote> and + <quote>Line</quote>. There are many pre-defined sources. + </para> + + <para> + The second, <constant>DIRECTION</constant>, is one of the + following strings according to the direction of the control: + <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass + Playback</quote> and <quote>Bypass Capture</quote>. Or, it can + be omitted, meaning both playback and capture directions. + </para> + + <para> + The third, <constant>FUNCTION</constant>, is one of the + following strings according to the function of the control: + <quote>Switch</quote>, <quote>Volume</quote> and + <quote>Route</quote>. + </para> + + <para> + The example of control names are, thus, <quote>Master Capture + Switch</quote> or <quote>PCM Playback Volume</quote>. + </para> + + <para> + There are some exceptions: + </para> + + <section id="control-interface-control-names-global"> + <title>Global capture and playback</title> + <para> + <quote>Capture Source</quote>, <quote>Capture Switch</quote> + and <quote>Capture Volume</quote> are used for the global + capture (input) source, switch and volume. Similarly, + <quote>Playback Switch</quote> and <quote>Playback + Volume</quote> are used for the global output gain switch and + volume. + </para> + </section> + + <section id="control-interface-control-names-tone"> + <title>Tone-controls</title> + <para> + tone-control switch and volumes are specified like + <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control - + Switch</quote>, <quote>Tone Control - Bass</quote>, + <quote>Tone Control - Center</quote>. + </para> + </section> + + <section id="control-interface-control-names-3d"> + <title>3D controls</title> + <para> + 3D-control switches and volumes are specified like <quote>3D + Control - XXX</quote>, e.g. <quote>3D Control - + Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D + Control - Space</quote>. + </para> + </section> + + <section id="control-interface-control-names-mic"> + <title>Mic boost</title> + <para> + Mic-boost switch is set as <quote>Mic Boost</quote> or + <quote>Mic Boost (6dB)</quote>. + </para> + + <para> + More precise information can be found in + <filename>Documentation/sound/alsa/ControlNames.txt</filename>. + </para> + </section> + </section> + + <section id="control-interface-access-flags"> + <title>Access Flags</title> + + <para> + The access flag is the bitmask which specifies the access type + of the given control. The default access type is + <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, + which means both read and write are allowed to this control. + When the access flag is omitted (i.e. = 0), it is + considered as <constant>READWRITE</constant> access as default. + </para> + + <para> + When the control is read-only, pass + <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead. + In this case, you don't have to define + the <structfield>put</structfield> callback. + Similarly, when the control is write-only (although it's a rare + case), you can use the <constant>WRITE</constant> flag instead, and + you don't need the <structfield>get</structfield> callback. + </para> + + <para> + If the control value changes frequently (e.g. the VU meter), + <constant>VOLATILE</constant> flag should be given. This means + that the control may be changed without + <link linkend="control-interface-change-notification"><citetitle> + notification</citetitle></link>. Applications should poll such + a control constantly. + </para> + + <para> + When the control is inactive, set + the <constant>INACTIVE</constant> flag, too. + There are <constant>LOCK</constant> and + <constant>OWNER</constant> flags to change the write + permissions. + </para> + + </section> + + <section id="control-interface-callbacks"> + <title>Callbacks</title> + + <section id="control-interface-callbacks-info"> + <title>info callback</title> + <para> + The <structfield>info</structfield> callback is used to get + detailed information on this control. This must store the + values of the given struct <structname>snd_ctl_elem_info</structname> + object. For example, for a boolean control with a single + element: + + <example> + <title>Example of info callback</title> + <programlisting> +<![CDATA[ + static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; + uinfo->count = 1; + uinfo->value.integer.min = 0; + uinfo->value.integer.max = 1; + return 0; + } +]]> + </programlisting> + </example> + </para> + + <para> + The <structfield>type</structfield> field specifies the type + of the control. There are <constant>BOOLEAN</constant>, + <constant>INTEGER</constant>, <constant>ENUMERATED</constant>, + <constant>BYTES</constant>, <constant>IEC958</constant> and + <constant>INTEGER64</constant>. The + <structfield>count</structfield> field specifies the + number of elements in this control. For example, a stereo + volume would have count = 2. The + <structfield>value</structfield> field is a union, and + the values stored are depending on the type. The boolean and + integer types are identical. + </para> + + <para> + The enumerated type is a bit different from others. You'll + need to set the string for the currently given item index. + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; + uinfo->count = 1; + uinfo->value.enumerated.items = 4; + if (uinfo->value.enumerated.item > 3) + uinfo->value.enumerated.item = 3; + strcpy(uinfo->value.enumerated.name, + texts[uinfo->value.enumerated.item]); + return 0; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The above callback can be simplified with a helper function, + <function>snd_ctl_enum_info</function>. The final code + looks like below. + (You can pass ARRAY_SIZE(texts) instead of 4 in the third + argument; it's a matter of taste.) + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + return snd_ctl_enum_info(uinfo, 1, 4, texts); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + Some common info callbacks are available for your convenience: + <function>snd_ctl_boolean_mono_info()</function> and + <function>snd_ctl_boolean_stereo_info()</function>. + Obviously, the former is an info callback for a mono channel + boolean item, just like <function>snd_myctl_mono_info</function> + above, and the latter is for a stereo channel boolean item. + </para> + + </section> + + <section id="control-interface-callbacks-get"> + <title>get callback</title> + + <para> + This callback is used to read the current value of the + control and to return to user-space. + </para> + + <para> + For example, + + <example> + <title>Example of get callback</title> + <programlisting> +<![CDATA[ + static int snd_myctl_get(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + struct mychip *chip = snd_kcontrol_chip(kcontrol); + ucontrol->value.integer.value[0] = get_some_value(chip); + return 0; + } +]]> + </programlisting> + </example> + </para> + + <para> + The <structfield>value</structfield> field depends on + the type of control as well as on the info callback. For example, + the sb driver uses this field to store the register offset, + the bit-shift and the bit-mask. The + <structfield>private_value</structfield> field is set as follows: + <informalexample> + <programlisting> +<![CDATA[ + .private_value = reg | (shift << 16) | (mask << 24) +]]> + </programlisting> + </informalexample> + and is retrieved in callbacks like + <informalexample> + <programlisting> +<![CDATA[ + static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + int reg = kcontrol->private_value & 0xff; + int shift = (kcontrol->private_value >> 16) & 0xff; + int mask = (kcontrol->private_value >> 24) & 0xff; + .... + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + In the <structfield>get</structfield> callback, + you have to fill all the elements if the + control has more than one elements, + i.e. <structfield>count</structfield> > 1. + In the example above, we filled only one element + (<structfield>value.integer.value[0]</structfield>) since it's + assumed as <structfield>count</structfield> = 1. + </para> + </section> + + <section id="control-interface-callbacks-put"> + <title>put callback</title> + + <para> + This callback is used to write a value from user-space. + </para> + + <para> + For example, + + <example> + <title>Example of put callback</title> + <programlisting> +<![CDATA[ + static int snd_myctl_put(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + struct mychip *chip = snd_kcontrol_chip(kcontrol); + int changed = 0; + if (chip->current_value != + ucontrol->value.integer.value[0]) { + change_current_value(chip, + ucontrol->value.integer.value[0]); + changed = 1; + } + return changed; + } +]]> + </programlisting> + </example> + + As seen above, you have to return 1 if the value is + changed. If the value is not changed, return 0 instead. + If any fatal error happens, return a negative error code as + usual. + </para> + + <para> + As in the <structfield>get</structfield> callback, + when the control has more than one elements, + all elements must be evaluated in this callback, too. + </para> + </section> + + <section id="control-interface-callbacks-all"> + <title>Callbacks are not atomic</title> + <para> + All these three callbacks are basically not atomic. + </para> + </section> + </section> + + <section id="control-interface-constructor"> + <title>Constructor</title> + <para> + When everything is ready, finally we can create a new + control. To create a control, there are two functions to be + called, <function>snd_ctl_new1()</function> and + <function>snd_ctl_add()</function>. + </para> + + <para> + In the simplest way, you can do like this: + + <informalexample> + <programlisting> +<![CDATA[ + err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); + if (err < 0) + return err; +]]> + </programlisting> + </informalexample> + + where <parameter>my_control</parameter> is the + struct <structname>snd_kcontrol_new</structname> object defined above, and chip + is the object pointer to be passed to + kcontrol->private_data + which can be referred to in callbacks. + </para> + + <para> + <function>snd_ctl_new1()</function> allocates a new + <structname>snd_kcontrol</structname> instance, + and <function>snd_ctl_add</function> assigns the given + control component to the card. + </para> + </section> + + <section id="control-interface-change-notification"> + <title>Change Notification</title> + <para> + If you need to change and update a control in the interrupt + routine, you can call <function>snd_ctl_notify()</function>. For + example, + + <informalexample> + <programlisting> +<![CDATA[ + snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); +]]> + </programlisting> + </informalexample> + + This function takes the card pointer, the event-mask, and the + control id pointer for the notification. The event-mask + specifies the types of notification, for example, in the above + example, the change of control values is notified. + The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname> + to be notified. + You can find some examples in <filename>es1938.c</filename> or + <filename>es1968.c</filename> for hardware volume interrupts. + </para> + </section> + + <section id="control-interface-tlv"> + <title>Metadata</title> + <para> + To provide information about the dB values of a mixer control, use + on of the <constant>DECLARE_TLV_xxx</constant> macros from + <filename><sound/tlv.h></filename> to define a variable + containing this information, set the<structfield>tlv.p + </structfield> field to point to this variable, and include the + <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the + <structfield>access</structfield> field; like this: + <informalexample> + <programlisting> +<![CDATA[ + static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); + + static struct snd_kcontrol_new my_control = { + ... + .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | + SNDRV_CTL_ELEM_ACCESS_TLV_READ, + ... + .tlv.p = db_scale_my_control, + }; +]]> + </programlisting> + </informalexample> + </para> + + <para> + The <function>DECLARE_TLV_DB_SCALE</function> macro defines + information about a mixer control where each step in the control's + value changes the dB value by a constant dB amount. + The first parameter is the name of the variable to be defined. + The second parameter is the minimum value, in units of 0.01 dB. + The third parameter is the step size, in units of 0.01 dB. + Set the fourth parameter to 1 if the minimum value actually mutes + the control. + </para> + + <para> + The <function>DECLARE_TLV_DB_LINEAR</function> macro defines + information about a mixer control where the control's value affects + the output linearly. + The first parameter is the name of the variable to be defined. + The second parameter is the minimum value, in units of 0.01 dB. + The third parameter is the maximum value, in units of 0.01 dB. + If the minimum value mutes the control, set the second parameter to + <constant>TLV_DB_GAIN_MUTE</constant>. + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- API for AC97 Codec --> +<!-- ****************************************************** --> + <chapter id="api-ac97"> + <title>API for AC97 Codec</title> + + <section> + <title>General</title> + <para> + The ALSA AC97 codec layer is a well-defined one, and you don't + have to write much code to control it. Only low-level control + routines are necessary. The AC97 codec API is defined in + <filename><sound/ac97_codec.h></filename>. + </para> + </section> + + <section id="api-ac97-example"> + <title>Full Code Example</title> + <para> + <example> + <title>Example of AC97 Interface</title> + <programlisting> +<![CDATA[ + struct mychip { + .... + struct snd_ac97 *ac97; + .... + }; + + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, + unsigned short reg) + { + struct mychip *chip = ac97->private_data; + .... + /* read a register value here from the codec */ + return the_register_value; + } + + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, + unsigned short reg, unsigned short val) + { + struct mychip *chip = ac97->private_data; + .... + /* write the given register value to the codec */ + } + + static int snd_mychip_ac97(struct mychip *chip) + { + struct snd_ac97_bus *bus; + struct snd_ac97_template ac97; + int err; + static struct snd_ac97_bus_ops ops = { + .write = snd_mychip_ac97_write, + .read = snd_mychip_ac97_read, + }; + + err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); + if (err < 0) + return err; + memset(&ac97, 0, sizeof(ac97)); + ac97.private_data = chip; + return snd_ac97_mixer(bus, &ac97, &chip->ac97); + } + +]]> + </programlisting> + </example> + </para> + </section> + + <section id="api-ac97-constructor"> + <title>Constructor</title> + <para> + To create an ac97 instance, first call <function>snd_ac97_bus</function> + with an <type>ac97_bus_ops_t</type> record with callback functions. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_ac97_bus *bus; + static struct snd_ac97_bus_ops ops = { + .write = snd_mychip_ac97_write, + .read = snd_mychip_ac97_read, + }; + + snd_ac97_bus(card, 0, &ops, NULL, &pbus); +]]> + </programlisting> + </informalexample> + + The bus record is shared among all belonging ac97 instances. + </para> + + <para> + And then call <function>snd_ac97_mixer()</function> with an + struct <structname>snd_ac97_template</structname> + record together with the bus pointer created above. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_ac97_template ac97; + int err; + + memset(&ac97, 0, sizeof(ac97)); + ac97.private_data = chip; + snd_ac97_mixer(bus, &ac97, &chip->ac97); +]]> + </programlisting> + </informalexample> + + where chip->ac97 is a pointer to a newly created + <type>ac97_t</type> instance. + In this case, the chip pointer is set as the private data, so that + the read/write callback functions can refer to this chip instance. + This instance is not necessarily stored in the chip + record. If you need to change the register values from the + driver, or need the suspend/resume of ac97 codecs, keep this + pointer to pass to the corresponding functions. + </para> + </section> + + <section id="api-ac97-callbacks"> + <title>Callbacks</title> + <para> + The standard callbacks are <structfield>read</structfield> and + <structfield>write</structfield>. Obviously they + correspond to the functions for read and write accesses to the + hardware low-level codes. + </para> + + <para> + The <structfield>read</structfield> callback returns the + register value specified in the argument. + + <informalexample> + <programlisting> +<![CDATA[ + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, + unsigned short reg) + { + struct mychip *chip = ac97->private_data; + .... + return the_register_value; + } +]]> + </programlisting> + </informalexample> + + Here, the chip can be cast from ac97->private_data. + </para> + + <para> + Meanwhile, the <structfield>write</structfield> callback is + used to set the register value. + + <informalexample> + <programlisting> +<![CDATA[ + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, + unsigned short reg, unsigned short val) +]]> + </programlisting> + </informalexample> + </para> + + <para> + These callbacks are non-atomic like the control API callbacks. + </para> + + <para> + There are also other callbacks: + <structfield>reset</structfield>, + <structfield>wait</structfield> and + <structfield>init</structfield>. + </para> + + <para> + The <structfield>reset</structfield> callback is used to reset + the codec. If the chip requires a special kind of reset, you can + define this callback. + </para> + + <para> + The <structfield>wait</structfield> callback is used to + add some waiting time in the standard initialization of the codec. If the + chip requires the extra waiting time, define this callback. + </para> + + <para> + The <structfield>init</structfield> callback is used for + additional initialization of the codec. + </para> + </section> + + <section id="api-ac97-updating-registers"> + <title>Updating Registers in The Driver</title> + <para> + If you need to access to the codec from the driver, you can + call the following functions: + <function>snd_ac97_write()</function>, + <function>snd_ac97_read()</function>, + <function>snd_ac97_update()</function> and + <function>snd_ac97_update_bits()</function>. + </para> + + <para> + Both <function>snd_ac97_write()</function> and + <function>snd_ac97_update()</function> functions are used to + set a value to the given register + (<constant>AC97_XXX</constant>). The difference between them is + that <function>snd_ac97_update()</function> doesn't write a + value if the given value has been already set, while + <function>snd_ac97_write()</function> always rewrites the + value. + + <informalexample> + <programlisting> +<![CDATA[ + snd_ac97_write(ac97, AC97_MASTER, 0x8080); + snd_ac97_update(ac97, AC97_MASTER, 0x8080); +]]> + </programlisting> + </informalexample> + </para> + + <para> + <function>snd_ac97_read()</function> is used to read the value + of the given register. For example, + + <informalexample> + <programlisting> +<![CDATA[ + value = snd_ac97_read(ac97, AC97_MASTER); +]]> + </programlisting> + </informalexample> + </para> + + <para> + <function>snd_ac97_update_bits()</function> is used to update + some bits in the given register. + + <informalexample> + <programlisting> +<![CDATA[ + snd_ac97_update_bits(ac97, reg, mask, value); +]]> + </programlisting> + </informalexample> + </para> + + <para> + Also, there is a function to change the sample rate (of a + given register such as + <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or + DRA is supported by the codec: + <function>snd_ac97_set_rate()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The following registers are available to set the rate: + <constant>AC97_PCM_MIC_ADC_RATE</constant>, + <constant>AC97_PCM_FRONT_DAC_RATE</constant>, + <constant>AC97_PCM_LR_ADC_RATE</constant>, + <constant>AC97_SPDIF</constant>. When + <constant>AC97_SPDIF</constant> is specified, the register is + not really changed but the corresponding IEC958 status bits will + be updated. + </para> + </section> + + <section id="api-ac97-clock-adjustment"> + <title>Clock Adjustment</title> + <para> + In some chips, the clock of the codec isn't 48000 but using a + PCI clock (to save a quartz!). In this case, change the field + bus->clock to the corresponding + value. For example, intel8x0 + and es1968 drivers have their own function to read from the clock. + </para> + </section> + + <section id="api-ac97-proc-files"> + <title>Proc Files</title> + <para> + The ALSA AC97 interface will create a proc file such as + <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and + <filename>ac97#0-0+regs</filename>. You can refer to these files to + see the current status and registers of the codec. + </para> + </section> + + <section id="api-ac97-multiple-codecs"> + <title>Multiple Codecs</title> + <para> + When there are several codecs on the same card, you need to + call <function>snd_ac97_mixer()</function> multiple times with + ac97.num=1 or greater. The <structfield>num</structfield> field + specifies the codec number. + </para> + + <para> + If you set up multiple codecs, you either need to write + different callbacks for each codec or check + ac97->num in the callback routines. + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- MIDI (MPU401-UART) Interface --> +<!-- ****************************************************** --> + <chapter id="midi-interface"> + <title>MIDI (MPU401-UART) Interface</title> + + <section id="midi-interface-general"> + <title>General</title> + <para> + Many soundcards have built-in MIDI (MPU401-UART) + interfaces. When the soundcard supports the standard MPU401-UART + interface, most likely you can use the ALSA MPU401-UART API. The + MPU401-UART API is defined in + <filename><sound/mpu401.h></filename>. + </para> + + <para> + Some soundchips have a similar but slightly different + implementation of mpu401 stuff. For example, emu10k1 has its own + mpu401 routines. + </para> + </section> + + <section id="midi-interface-constructor"> + <title>Constructor</title> + <para> + To create a rawmidi object, call + <function>snd_mpu401_uart_new()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_rawmidi *rmidi; + snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, + irq, &rmidi); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The first argument is the card pointer, and the second is the + index of this component. You can create up to 8 rawmidi + devices. + </para> + + <para> + The third argument is the type of the hardware, + <constant>MPU401_HW_XXX</constant>. If it's not a special one, + you can use <constant>MPU401_HW_MPU401</constant>. + </para> + + <para> + The 4th argument is the I/O port address. Many + backward-compatible MPU401 have an I/O port such as 0x330. Or, it + might be a part of its own PCI I/O region. It depends on the + chip design. + </para> + + <para> + The 5th argument is a bitflag for additional information. + When the I/O port address above is part of the PCI I/O + region, the MPU401 I/O port might have been already allocated + (reserved) by the driver itself. In such a case, pass a bit flag + <constant>MPU401_INFO_INTEGRATED</constant>, + and the mpu401-uart layer will allocate the I/O ports by itself. + </para> + + <para> + When the controller supports only the input or output MIDI stream, + pass the <constant>MPU401_INFO_INPUT</constant> or + <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. + Then the rawmidi instance is created as a single stream. + </para> + + <para> + <constant>MPU401_INFO_MMIO</constant> bitflag is used to change + the access method to MMIO (via readb and writeb) instead of + iob and outb. In this case, you have to pass the iomapped address + to <function>snd_mpu401_uart_new()</function>. + </para> + + <para> + When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output + stream isn't checked in the default interrupt handler. The driver + needs to call <function>snd_mpu401_uart_interrupt_tx()</function> + by itself to start processing the output stream in the irq handler. + </para> + + <para> + If the MPU-401 interface shares its interrupt with the other logical + devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant> + (see <link linkend="midi-interface-interrupt-handler"><citetitle> + below</citetitle></link>). + </para> + + <para> + Usually, the port address corresponds to the command port and + port + 1 corresponds to the data port. If not, you may change + the <structfield>cport</structfield> field of + struct <structname>snd_mpu401</structname> manually + afterward. However, <structname>snd_mpu401</structname> pointer is not + returned explicitly by + <function>snd_mpu401_uart_new()</function>. You need to cast + rmidi->private_data to + <structname>snd_mpu401</structname> explicitly, + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_mpu401 *mpu; + mpu = rmidi->private_data; +]]> + </programlisting> + </informalexample> + + and reset the cport as you like: + + <informalexample> + <programlisting> +<![CDATA[ + mpu->cport = my_own_control_port; +]]> + </programlisting> + </informalexample> + </para> + + <para> + The 6th argument specifies the ISA irq number that will be + allocated. If no interrupt is to be allocated (because your + code is already allocating a shared interrupt, or because the + device does not use interrupts), pass -1 instead. + For a MPU-401 device without an interrupt, a polling timer + will be used instead. + </para> + </section> + + <section id="midi-interface-interrupt-handler"> + <title>Interrupt Handler</title> + <para> + When the interrupt is allocated in + <function>snd_mpu401_uart_new()</function>, an exclusive ISA + interrupt handler is automatically used, hence you don't have + anything else to do than creating the mpu401 stuff. Otherwise, you + have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call + <function>snd_mpu401_uart_interrupt()</function> explicitly from your + own interrupt handler when it has determined that a UART interrupt + has occurred. + </para> + + <para> + In this case, you need to pass the private_data of the + returned rawmidi object from + <function>snd_mpu401_uart_new()</function> as the second + argument of <function>snd_mpu401_uart_interrupt()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); +]]> + </programlisting> + </informalexample> + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- RawMIDI Interface --> +<!-- ****************************************************** --> + <chapter id="rawmidi-interface"> + <title>RawMIDI Interface</title> + + <section id="rawmidi-interface-overview"> + <title>Overview</title> + + <para> + The raw MIDI interface is used for hardware MIDI ports that can + be accessed as a byte stream. It is not used for synthesizer + chips that do not directly understand MIDI. + </para> + + <para> + ALSA handles file and buffer management. All you have to do is + to write some code to move data between the buffer and the + hardware. + </para> + + <para> + The rawmidi API is defined in + <filename><sound/rawmidi.h></filename>. + </para> + </section> + + <section id="rawmidi-interface-constructor"> + <title>Constructor</title> + + <para> + To create a rawmidi device, call the + <function>snd_rawmidi_new</function> function: + <informalexample> + <programlisting> +<![CDATA[ + struct snd_rawmidi *rmidi; + err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); + if (err < 0) + return err; + rmidi->private_data = chip; + strcpy(rmidi->name, "My MIDI"); + rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | + SNDRV_RAWMIDI_INFO_INPUT | + SNDRV_RAWMIDI_INFO_DUPLEX; +]]> + </programlisting> + </informalexample> + </para> + + <para> + The first argument is the card pointer, the second argument is + the ID string. + </para> + + <para> + The third argument is the index of this component. You can + create up to 8 rawmidi devices. + </para> + + <para> + The fourth and fifth arguments are the number of output and + input substreams, respectively, of this device (a substream is + the equivalent of a MIDI port). + </para> + + <para> + Set the <structfield>info_flags</structfield> field to specify + the capabilities of the device. + Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is + at least one output port, + <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at + least one input port, + and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device + can handle output and input at the same time. + </para> + + <para> + After the rawmidi device is created, you need to set the + operators (callbacks) for each substream. There are helper + functions to set the operators for all the substreams of a device: + <informalexample> + <programlisting> +<![CDATA[ + snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); + snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The operators are usually defined like this: + <informalexample> + <programlisting> +<![CDATA[ + static struct snd_rawmidi_ops snd_mymidi_output_ops = { + .open = snd_mymidi_output_open, + .close = snd_mymidi_output_close, + .trigger = snd_mymidi_output_trigger, + }; +]]> + </programlisting> + </informalexample> + These callbacks are explained in the <link + linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link> + section. + </para> + + <para> + If there are more than one substream, you should give a + unique name to each of them: + <informalexample> + <programlisting> +<![CDATA[ + struct snd_rawmidi_substream *substream; + list_for_each_entry(substream, + &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, + list { + sprintf(substream->name, "My MIDI Port %d", substream->number + 1); + } + /* same for SNDRV_RAWMIDI_STREAM_INPUT */ +]]> + </programlisting> + </informalexample> + </para> + </section> + + <section id="rawmidi-interface-callbacks"> + <title>Callbacks</title> + + <para> + In all the callbacks, the private data that you've set for the + rawmidi device can be accessed as + substream->rmidi->private_data. + <!-- <code> isn't available before DocBook 4.3 --> + </para> + + <para> + If there is more than one port, your callbacks can determine the + port index from the struct snd_rawmidi_substream data passed to each + callback: + <informalexample> + <programlisting> +<![CDATA[ + struct snd_rawmidi_substream *substream; + int index = substream->number; +]]> + </programlisting> + </informalexample> + </para> + + <section id="rawmidi-interface-op-open"> + <title><function>open</function> callback</title> + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_open(struct snd_rawmidi_substream *substream); +]]> + </programlisting> + </informalexample> + + <para> + This is called when a substream is opened. + You can initialize the hardware here, but you shouldn't + start transmitting/receiving data yet. + </para> + </section> + + <section id="rawmidi-interface-op-close"> + <title><function>close</function> callback</title> + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_xxx_close(struct snd_rawmidi_substream *substream); +]]> + </programlisting> + </informalexample> + + <para> + Guess what. + </para> + + <para> + The <function>open</function> and <function>close</function> + callbacks of a rawmidi device are serialized with a mutex, + and can sleep. + </para> + </section> + + <section id="rawmidi-interface-op-trigger-out"> + <title><function>trigger</function> callback for output + substreams</title> + + <informalexample> + <programlisting> +<![CDATA[ + static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); +]]> + </programlisting> + </informalexample> + + <para> + This is called with a nonzero <parameter>up</parameter> + parameter when there is some data in the substream buffer that + must be transmitted. + </para> + + <para> + To read data from the buffer, call + <function>snd_rawmidi_transmit_peek</function>. It will + return the number of bytes that have been read; this will be + less than the number of bytes requested when there are no more + data in the buffer. + After the data have been transmitted successfully, call + <function>snd_rawmidi_transmit_ack</function> to remove the + data from the substream buffer: + <informalexample> + <programlisting> +<![CDATA[ + unsigned char data; + while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { + if (snd_mychip_try_to_transmit(data)) + snd_rawmidi_transmit_ack(substream, 1); + else + break; /* hardware FIFO full */ + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + If you know beforehand that the hardware will accept data, you + can use the <function>snd_rawmidi_transmit</function> function + which reads some data and removes them from the buffer at once: + <informalexample> + <programlisting> +<![CDATA[ + while (snd_mychip_transmit_possible()) { + unsigned char data; + if (snd_rawmidi_transmit(substream, &data, 1) != 1) + break; /* no more data */ + snd_mychip_transmit(data); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + If you know beforehand how many bytes you can accept, you can + use a buffer size greater than one with the + <function>snd_rawmidi_transmit*</function> functions. + </para> + + <para> + The <function>trigger</function> callback must not sleep. If + the hardware FIFO is full before the substream buffer has been + emptied, you have to continue transmitting data later, either + in an interrupt handler, or with a timer if the hardware + doesn't have a MIDI transmit interrupt. + </para> + + <para> + The <function>trigger</function> callback is called with a + zero <parameter>up</parameter> parameter when the transmission + of data should be aborted. + </para> + </section> + + <section id="rawmidi-interface-op-trigger-in"> + <title><function>trigger</function> callback for input + substreams</title> + + <informalexample> + <programlisting> +<![CDATA[ + static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); +]]> + </programlisting> + </informalexample> + + <para> + This is called with a nonzero <parameter>up</parameter> + parameter to enable receiving data, or with a zero + <parameter>up</parameter> parameter do disable receiving data. + </para> + + <para> + The <function>trigger</function> callback must not sleep; the + actual reading of data from the device is usually done in an + interrupt handler. + </para> + + <para> + When data reception is enabled, your interrupt handler should + call <function>snd_rawmidi_receive</function> for all received + data: + <informalexample> + <programlisting> +<![CDATA[ + void snd_mychip_midi_interrupt(...) + { + while (mychip_midi_available()) { + unsigned char data; + data = mychip_midi_read(); + snd_rawmidi_receive(substream, &data, 1); + } + } +]]> + </programlisting> + </informalexample> + </para> + </section> + + <section id="rawmidi-interface-op-drain"> + <title><function>drain</function> callback</title> + + <informalexample> + <programlisting> +<![CDATA[ + static void snd_xxx_drain(struct snd_rawmidi_substream *substream); +]]> + </programlisting> + </informalexample> + + <para> + This is only used with output substreams. This function should wait + until all data read from the substream buffer have been transmitted. + This ensures that the device can be closed and the driver unloaded + without losing data. + </para> + + <para> + This callback is optional. If you do not set + <structfield>drain</structfield> in the struct snd_rawmidi_ops + structure, ALSA will simply wait for 50 milliseconds + instead. + </para> + </section> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Miscellaneous Devices --> +<!-- ****************************************************** --> + <chapter id="misc-devices"> + <title>Miscellaneous Devices</title> + + <section id="misc-devices-opl3"> + <title>FM OPL3</title> + <para> + The FM OPL3 is still used in many chips (mainly for backward + compatibility). ALSA has a nice OPL3 FM control layer, too. The + OPL3 API is defined in + <filename><sound/opl3.h></filename>. + </para> + + <para> + FM registers can be directly accessed through the direct-FM API, + defined in <filename><sound/asound_fm.h></filename>. In + ALSA native mode, FM registers are accessed through + the Hardware-Dependent Device direct-FM extension API, whereas in + OSS compatible mode, FM registers can be accessed with the OSS + direct-FM compatible API in <filename>/dev/dmfmX</filename> device. + </para> + + <para> + To create the OPL3 component, you have two functions to + call. The first one is a constructor for the <type>opl3_t</type> + instance. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_opl3 *opl3; + snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, + integrated, &opl3); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The first argument is the card pointer, the second one is the + left port address, and the third is the right port address. In + most cases, the right port is placed at the left port + 2. + </para> + + <para> + The fourth argument is the hardware type. + </para> + + <para> + When the left and right ports have been already allocated by + the card driver, pass non-zero to the fifth argument + (<parameter>integrated</parameter>). Otherwise, the opl3 module will + allocate the specified ports by itself. + </para> + + <para> + When the accessing the hardware requires special method + instead of the standard I/O access, you can create opl3 instance + separately with <function>snd_opl3_new()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_opl3 *opl3; + snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); +]]> + </programlisting> + </informalexample> + </para> + + <para> + Then set <structfield>command</structfield>, + <structfield>private_data</structfield> and + <structfield>private_free</structfield> for the private + access function, the private data and the destructor. + The l_port and r_port are not necessarily set. Only the + command must be set properly. You can retrieve the data + from the opl3->private_data field. + </para> + + <para> + After creating the opl3 instance via <function>snd_opl3_new()</function>, + call <function>snd_opl3_init()</function> to initialize the chip to the + proper state. Note that <function>snd_opl3_create()</function> always + calls it internally. + </para> + + <para> + If the opl3 instance is created successfully, then create a + hwdep device for this opl3. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_hwdep *opl3hwdep; + snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The first argument is the <type>opl3_t</type> instance you + created, and the second is the index number, usually 0. + </para> + + <para> + The third argument is the index-offset for the sequencer + client assigned to the OPL3 port. When there is an MPU401-UART, + give 1 for here (UART always takes 0). + </para> + </section> + + <section id="misc-devices-hardware-dependent"> + <title>Hardware-Dependent Devices</title> + <para> + Some chips need user-space access for special + controls or for loading the micro code. In such a case, you can + create a hwdep (hardware-dependent) device. The hwdep API is + defined in <filename><sound/hwdep.h></filename>. You can + find examples in opl3 driver or + <filename>isa/sb/sb16_csp.c</filename>. + </para> + + <para> + The creation of the <type>hwdep</type> instance is done via + <function>snd_hwdep_new()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_hwdep *hw; + snd_hwdep_new(card, "My HWDEP", 0, &hw); +]]> + </programlisting> + </informalexample> + + where the third argument is the index number. + </para> + + <para> + You can then pass any pointer value to the + <parameter>private_data</parameter>. + If you assign a private data, you should define the + destructor, too. The destructor function is set in + the <structfield>private_free</structfield> field. + + <informalexample> + <programlisting> +<![CDATA[ + struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); + hw->private_data = p; + hw->private_free = mydata_free; +]]> + </programlisting> + </informalexample> + + and the implementation of the destructor would be: + + <informalexample> + <programlisting> +<![CDATA[ + static void mydata_free(struct snd_hwdep *hw) + { + struct mydata *p = hw->private_data; + kfree(p); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The arbitrary file operations can be defined for this + instance. The file operators are defined in + the <parameter>ops</parameter> table. For example, assume that + this chip needs an ioctl. + + <informalexample> + <programlisting> +<![CDATA[ + hw->ops.open = mydata_open; + hw->ops.ioctl = mydata_ioctl; + hw->ops.release = mydata_release; +]]> + </programlisting> + </informalexample> + + And implement the callback functions as you like. + </para> + </section> + + <section id="misc-devices-IEC958"> + <title>IEC958 (S/PDIF)</title> + <para> + Usually the controls for IEC958 devices are implemented via + the control interface. There is a macro to compose a name string for + IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function> + defined in <filename><include/asound.h></filename>. + </para> + + <para> + There are some standard controls for IEC958 status bits. These + controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>, + and the size of element is fixed as 4 bytes array + (value.iec958.status[x]). For the <structfield>info</structfield> + callback, you don't specify + the value field for this type (the count field must be set, + though). + </para> + + <para> + <quote>IEC958 Playback Con Mask</quote> is used to return the + bit-mask for the IEC958 status bits of consumer mode. Similarly, + <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for + professional mode. They are read-only controls, and are defined + as MIXER controls (iface = + <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>). + </para> + + <para> + Meanwhile, <quote>IEC958 Playback Default</quote> control is + defined for getting and setting the current default IEC958 + bits. Note that this one is usually defined as a PCM control + (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>), + although in some places it's defined as a MIXER control. + </para> + + <para> + In addition, you can define the control switches to + enable/disable or to set the raw bit mode. The implementation + will depend on the chip, but the control should be named as + <quote>IEC958 xxx</quote>, preferably using + the <function>SNDRV_CTL_NAME_IEC958()</function> macro. + </para> + + <para> + You can find several cases, for example, + <filename>pci/emu10k1</filename>, + <filename>pci/ice1712</filename>, or + <filename>pci/cmipci.c</filename>. + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Buffer and Memory Management --> +<!-- ****************************************************** --> + <chapter id="buffer-and-memory"> + <title>Buffer and Memory Management</title> + + <section id="buffer-and-memory-buffer-types"> + <title>Buffer Types</title> + <para> + ALSA provides several different buffer allocation functions + depending on the bus and the architecture. All these have a + consistent API. The allocation of physically-contiguous pages is + done via + <function>snd_malloc_xxx_pages()</function> function, where xxx + is the bus type. + </para> + + <para> + The allocation of pages with fallback is + <function>snd_malloc_xxx_pages_fallback()</function>. This + function tries to allocate the specified pages but if the pages + are not available, it tries to reduce the page sizes until + enough space is found. + </para> + + <para> + The release the pages, call + <function>snd_free_xxx_pages()</function> function. + </para> + + <para> + Usually, ALSA drivers try to allocate and reserve + a large contiguous physical space + at the time the module is loaded for the later use. + This is called <quote>pre-allocation</quote>. + As already written, you can call the following function at + pcm instance construction time (in the case of PCI bus). + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(pci), size, max); +]]> + </programlisting> + </informalexample> + + where <parameter>size</parameter> is the byte size to be + pre-allocated and the <parameter>max</parameter> is the maximum + size to be changed via the <filename>prealloc</filename> proc file. + The allocator will try to get an area as large as possible + within the given size. + </para> + + <para> + The second argument (type) and the third argument (device pointer) + are dependent on the bus. + In the case of the ISA bus, pass <function>snd_dma_isa_data()</function> + as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type. + For the continuous buffer unrelated to the bus can be pre-allocated + with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the + <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, + where <constant>GFP_KERNEL</constant> is the kernel allocation flag to + use. + For the PCI scatter-gather buffers, use + <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with + <function>snd_dma_pci_data(pci)</function> + (see the + <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers + </citetitle></link> section). + </para> + + <para> + Once the buffer is pre-allocated, you can use the + allocator in the <structfield>hw_params</structfield> callback: + + <informalexample> + <programlisting> +<![CDATA[ + snd_pcm_lib_malloc_pages(substream, size); +]]> + </programlisting> + </informalexample> + + Note that you have to pre-allocate to use this function. + </para> + </section> + + <section id="buffer-and-memory-external-hardware"> + <title>External Hardware Buffers</title> + <para> + Some chips have their own hardware buffers and the DMA + transfer from the host memory is not available. In such a case, + you need to either 1) copy/set the audio data directly to the + external hardware buffer, or 2) make an intermediate buffer and + copy/set the data from it to the external hardware buffer in + interrupts (or in tasklets, preferably). + </para> + + <para> + The first case works fine if the external hardware buffer is large + enough. This method doesn't need any extra buffers and thus is + more effective. You need to define the + <structfield>copy</structfield> and + <structfield>silence</structfield> callbacks for + the data transfer. However, there is a drawback: it cannot + be mmapped. The examples are GUS's GF1 PCM or emu8000's + wavetable PCM. + </para> + + <para> + The second case allows for mmap on the buffer, although you have + to handle an interrupt or a tasklet to transfer the data + from the intermediate buffer to the hardware buffer. You can find an + example in the vxpocket driver. + </para> + + <para> + Another case is when the chip uses a PCI memory-map + region for the buffer instead of the host memory. In this case, + mmap is available only on certain architectures like the Intel one. + In non-mmap mode, the data cannot be transferred as in the normal + way. Thus you need to define the <structfield>copy</structfield> and + <structfield>silence</structfield> callbacks as well, + as in the cases above. The examples are found in + <filename>rme32.c</filename> and <filename>rme96.c</filename>. + </para> + + <para> + The implementation of the <structfield>copy</structfield> and + <structfield>silence</structfield> callbacks depends upon + whether the hardware supports interleaved or non-interleaved + samples. The <structfield>copy</structfield> callback is + defined like below, a bit + differently depending whether the direction is playback or + capture: + + <informalexample> + <programlisting> +<![CDATA[ + static int playback_copy(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); + static int capture_copy(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); +]]> + </programlisting> + </informalexample> + </para> + + <para> + In the case of interleaved samples, the second argument + (<parameter>channel</parameter>) is not used. The third argument + (<parameter>pos</parameter>) points the + current position offset in frames. + </para> + + <para> + The meaning of the fourth argument is different between + playback and capture. For playback, it holds the source data + pointer, and for capture, it's the destination data pointer. + </para> + + <para> + The last argument is the number of frames to be copied. + </para> + + <para> + What you have to do in this callback is again different + between playback and capture directions. In the + playback case, you copy the given amount of data + (<parameter>count</parameter>) at the specified pointer + (<parameter>src</parameter>) to the specified offset + (<parameter>pos</parameter>) on the hardware buffer. When + coded like memcpy-like way, the copy would be like: + + <informalexample> + <programlisting> +<![CDATA[ + my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, + frames_to_bytes(runtime, count)); +]]> + </programlisting> + </informalexample> + </para> + + <para> + For the capture direction, you copy the given amount of + data (<parameter>count</parameter>) at the specified offset + (<parameter>pos</parameter>) on the hardware buffer to the + specified pointer (<parameter>dst</parameter>). + + <informalexample> + <programlisting> +<![CDATA[ + my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), + frames_to_bytes(runtime, count)); +]]> + </programlisting> + </informalexample> + + Note that both the position and the amount of data are given + in frames. + </para> + + <para> + In the case of non-interleaved samples, the implementation + will be a bit more complicated. + </para> + + <para> + You need to check the channel argument, and if it's -1, copy + the whole channels. Otherwise, you have to copy only the + specified channel. Please check + <filename>isa/gus/gus_pcm.c</filename> as an example. + </para> + + <para> + The <structfield>silence</structfield> callback is also + implemented in a similar way. + + <informalexample> + <programlisting> +<![CDATA[ + static int silence(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, snd_pcm_uframes_t count); +]]> + </programlisting> + </informalexample> + </para> + + <para> + The meanings of arguments are the same as in the + <structfield>copy</structfield> + callback, although there is no <parameter>src/dst</parameter> + argument. In the case of interleaved samples, the channel + argument has no meaning, as well as on + <structfield>copy</structfield> callback. + </para> + + <para> + The role of <structfield>silence</structfield> callback is to + set the given amount + (<parameter>count</parameter>) of silence data at the + specified offset (<parameter>pos</parameter>) on the hardware + buffer. Suppose that the data format is signed (that is, the + silent-data is 0), and the implementation using a memset-like + function would be like: + + <informalexample> + <programlisting> +<![CDATA[ + my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, + frames_to_bytes(runtime, count)); +]]> + </programlisting> + </informalexample> + </para> + + <para> + In the case of non-interleaved samples, again, the + implementation becomes a bit more complicated. See, for example, + <filename>isa/gus/gus_pcm.c</filename>. + </para> + </section> + + <section id="buffer-and-memory-non-contiguous"> + <title>Non-Contiguous Buffers</title> + <para> + If your hardware supports the page table as in emu10k1 or the + buffer descriptors as in via82xx, you can use the scatter-gather + (SG) DMA. ALSA provides an interface for handling SG-buffers. + The API is provided in <filename><sound/pcm.h></filename>. + </para> + + <para> + For creating the SG-buffer handler, call + <function>snd_pcm_lib_preallocate_pages()</function> or + <function>snd_pcm_lib_preallocate_pages_for_all()</function> + with <constant>SNDRV_DMA_TYPE_DEV_SG</constant> + in the PCM constructor like other PCI pre-allocator. + You need to pass <function>snd_dma_pci_data(pci)</function>, + where pci is the struct <structname>pci_dev</structname> pointer + of the chip as well. + The <type>struct snd_sg_buf</type> instance is created as + substream->dma_private. You can cast + the pointer like: + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; +]]> + </programlisting> + </informalexample> + </para> + + <para> + Then call <function>snd_pcm_lib_malloc_pages()</function> + in the <structfield>hw_params</structfield> callback + as well as in the case of normal PCI buffer. + The SG-buffer handler will allocate the non-contiguous kernel + pages of the given size and map them onto the virtually contiguous + memory. The virtual pointer is addressed in runtime->dma_area. + The physical address (runtime->dma_addr) is set to zero, + because the buffer is physically non-contiguous. + The physical address table is set up in sgbuf->table. + You can get the physical address at a certain offset via + <function>snd_pcm_sgbuf_get_addr()</function>. + </para> + + <para> + When a SG-handler is used, you need to set + <function>snd_pcm_sgbuf_ops_page</function> as + the <structfield>page</structfield> callback. + (See <link linkend="pcm-interface-operators-page-callback"> + <citetitle>page callback section</citetitle></link>.) + </para> + + <para> + To release the data, call + <function>snd_pcm_lib_free_pages()</function> in the + <structfield>hw_free</structfield> callback as usual. + </para> + </section> + + <section id="buffer-and-memory-vmalloced"> + <title>Vmalloc'ed Buffers</title> + <para> + It's possible to use a buffer allocated via + <function>vmalloc</function>, for example, for an intermediate + buffer. Since the allocated pages are not contiguous, you need + to set the <structfield>page</structfield> callback to obtain + the physical address at every offset. + </para> + + <para> + The implementation of <structfield>page</structfield> callback + would be like this: + + <informalexample> + <programlisting> +<![CDATA[ + #include <linux/vmalloc.h> + + /* get the physical page pointer on the given offset */ + static struct page *mychip_page(struct snd_pcm_substream *substream, + unsigned long offset) + { + void *pageptr = substream->runtime->dma_area + offset; + return vmalloc_to_page(pageptr); + } +]]> + </programlisting> + </informalexample> + </para> + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Proc Interface --> +<!-- ****************************************************** --> + <chapter id="proc-interface"> + <title>Proc Interface</title> + <para> + ALSA provides an easy interface for procfs. The proc files are + very useful for debugging. I recommend you set up proc files if + you write a driver and want to get a running status or register + dumps. The API is found in + <filename><sound/info.h></filename>. + </para> + + <para> + To create a proc file, call + <function>snd_card_proc_new()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + struct snd_info_entry *entry; + int err = snd_card_proc_new(card, "my-file", &entry); +]]> + </programlisting> + </informalexample> + + where the second argument specifies the name of the proc file to be + created. The above example will create a file + <filename>my-file</filename> under the card directory, + e.g. <filename>/proc/asound/card0/my-file</filename>. + </para> + + <para> + Like other components, the proc entry created via + <function>snd_card_proc_new()</function> will be registered and + released automatically in the card registration and release + functions. + </para> + + <para> + When the creation is successful, the function stores a new + instance in the pointer given in the third argument. + It is initialized as a text proc file for read only. To use + this proc file as a read-only text file as it is, set the read + callback with a private data via + <function>snd_info_set_text_ops()</function>. + + <informalexample> + <programlisting> +<![CDATA[ + snd_info_set_text_ops(entry, chip, my_proc_read); +]]> + </programlisting> + </informalexample> + + where the second argument (<parameter>chip</parameter>) is the + private data to be used in the callbacks. The third parameter + specifies the read buffer size and the fourth + (<parameter>my_proc_read</parameter>) is the callback function, which + is defined like + + <informalexample> + <programlisting> +<![CDATA[ + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer); +]]> + </programlisting> + </informalexample> + + </para> + + <para> + In the read callback, use <function>snd_iprintf()</function> for + output strings, which works just like normal + <function>printf()</function>. For example, + + <informalexample> + <programlisting> +<![CDATA[ + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer) + { + struct my_chip *chip = entry->private_data; + + snd_iprintf(buffer, "This is my chip!\n"); + snd_iprintf(buffer, "Port = %ld\n", chip->port); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The file permissions can be changed afterwards. As default, it's + set as read only for all users. If you want to add write + permission for the user (root as default), do as follows: + + <informalexample> + <programlisting> +<![CDATA[ + entry->mode = S_IFREG | S_IRUGO | S_IWUSR; +]]> + </programlisting> + </informalexample> + + and set the write buffer size and the callback + + <informalexample> + <programlisting> +<![CDATA[ + entry->c.text.write = my_proc_write; +]]> + </programlisting> + </informalexample> + </para> + + <para> + For the write callback, you can use + <function>snd_info_get_line()</function> to get a text line, and + <function>snd_info_get_str()</function> to retrieve a string from + the line. Some examples are found in + <filename>core/oss/mixer_oss.c</filename>, core/oss/and + <filename>pcm_oss.c</filename>. + </para> + + <para> + For a raw-data proc-file, set the attributes as follows: + + <informalexample> + <programlisting> +<![CDATA[ + static struct snd_info_entry_ops my_file_io_ops = { + .read = my_file_io_read, + }; + + entry->content = SNDRV_INFO_CONTENT_DATA; + entry->private_data = chip; + entry->c.ops = &my_file_io_ops; + entry->size = 4096; + entry->mode = S_IFREG | S_IRUGO; +]]> + </programlisting> + </informalexample> + + For the raw data, <structfield>size</structfield> field must be + set properly. This specifies the maximum size of the proc file access. + </para> + + <para> + The read/write callbacks of raw mode are more direct than the text mode. + You need to use a low-level I/O functions such as + <function>copy_from/to_user()</function> to transfer the + data. + + <informalexample> + <programlisting> +<![CDATA[ + static ssize_t my_file_io_read(struct snd_info_entry *entry, + void *file_private_data, + struct file *file, + char *buf, + size_t count, + loff_t pos) + { + if (copy_to_user(buf, local_data + pos, count)) + return -EFAULT; + return count; + } +]]> + </programlisting> + </informalexample> + + If the size of the info entry has been set up properly, + <structfield>count</structfield> and <structfield>pos</structfield> are + guaranteed to fit within 0 and the given size. + You don't have to check the range in the callbacks unless any + other condition is required. + + </para> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Power Management --> +<!-- ****************************************************** --> + <chapter id="power-management"> + <title>Power Management</title> + <para> + If the chip is supposed to work with suspend/resume + functions, you need to add power-management code to the + driver. The additional code for power-management should be + <function>ifdef</function>'ed with + <constant>CONFIG_PM</constant>. + </para> + + <para> + If the driver <emphasis>fully</emphasis> supports suspend/resume + that is, the device can be + properly resumed to its state when suspend was called, + you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag + in the pcm info field. Usually, this is possible when the + registers of the chip can be safely saved and restored to + RAM. If this is set, the trigger callback is called with + <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume + callback completes. + </para> + + <para> + Even if the driver doesn't support PM fully but + partial suspend/resume is still possible, it's still worthy to + implement suspend/resume callbacks. In such a case, applications + would reset the status by calling + <function>snd_pcm_prepare()</function> and restart the stream + appropriately. Hence, you can define suspend/resume callbacks + below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant> + info flag to the PCM. + </para> + + <para> + Note that the trigger with SUSPEND can always be called when + <function>snd_pcm_suspend_all</function> is called, + regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag. + The <constant>RESUME</constant> flag affects only the behavior + of <function>snd_pcm_resume()</function>. + (Thus, in theory, + <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed + to be handled in the trigger callback when no + <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, + it's better to keep it for compatibility reasons.) + </para> + <para> + In the earlier version of ALSA drivers, a common + power-management layer was provided, but it has been removed. + The driver needs to define the suspend/resume hooks according to + the bus the device is connected to. In the case of PCI drivers, the + callbacks look like below: + + <informalexample> + <programlisting> +<![CDATA[ + #ifdef CONFIG_PM + static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) + { + .... /* do things for suspend */ + return 0; + } + static int snd_my_resume(struct pci_dev *pci) + { + .... /* do things for suspend */ + return 0; + } + #endif +]]> + </programlisting> + </informalexample> + </para> + + <para> + The scheme of the real suspend job is as follows. + + <orderedlist> + <listitem><para>Retrieve the card and the chip data.</para></listitem> + <listitem><para>Call <function>snd_power_change_state()</function> with + <constant>SNDRV_CTL_POWER_D3hot</constant> to change the + power status.</para></listitem> + <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> + <listitem><para>If AC97 codecs are used, call + <function>snd_ac97_suspend()</function> for each codec.</para></listitem> + <listitem><para>Save the register values if necessary.</para></listitem> + <listitem><para>Stop the hardware if necessary.</para></listitem> + <listitem><para>Disable the PCI device by calling + <function>pci_disable_device()</function>. Then, call + <function>pci_save_state()</function> at last.</para></listitem> + </orderedlist> + </para> + + <para> + A typical code would be like: + + <informalexample> + <programlisting> +<![CDATA[ + static int mychip_suspend(struct pci_dev *pci, pm_message_t state) + { + /* (1) */ + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; + /* (2) */ + snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); + /* (3) */ + snd_pcm_suspend_all(chip->pcm); + /* (4) */ + snd_ac97_suspend(chip->ac97); + /* (5) */ + snd_mychip_save_registers(chip); + /* (6) */ + snd_mychip_stop_hardware(chip); + /* (7) */ + pci_disable_device(pci); + pci_save_state(pci); + return 0; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + The scheme of the real resume job is as follows. + + <orderedlist> + <listitem><para>Retrieve the card and the chip data.</para></listitem> + <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. + Then enable the pci device again by calling <function>pci_enable_device()</function>. + Call <function>pci_set_master()</function> if necessary, too.</para></listitem> + <listitem><para>Re-initialize the chip.</para></listitem> + <listitem><para>Restore the saved registers if necessary.</para></listitem> + <listitem><para>Resume the mixer, e.g. calling + <function>snd_ac97_resume()</function>.</para></listitem> + <listitem><para>Restart the hardware (if any).</para></listitem> + <listitem><para>Call <function>snd_power_change_state()</function> with + <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem> + </orderedlist> + </para> + + <para> + A typical code would be like: + + <informalexample> + <programlisting> +<![CDATA[ + static int mychip_resume(struct pci_dev *pci) + { + /* (1) */ + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; + /* (2) */ + pci_restore_state(pci); + pci_enable_device(pci); + pci_set_master(pci); + /* (3) */ + snd_mychip_reinit_chip(chip); + /* (4) */ + snd_mychip_restore_registers(chip); + /* (5) */ + snd_ac97_resume(chip->ac97); + /* (6) */ + snd_mychip_restart_chip(chip); + /* (7) */ + snd_power_change_state(card, SNDRV_CTL_POWER_D0); + return 0; + } +]]> + </programlisting> + </informalexample> + </para> + + <para> + As shown in the above, it's better to save registers after + suspending the PCM operations via + <function>snd_pcm_suspend_all()</function> or + <function>snd_pcm_suspend()</function>. It means that the PCM + streams are already stopped when the register snapshot is + taken. But, remember that you don't have to restart the PCM + stream in the resume callback. It'll be restarted via + trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> + when necessary. + </para> + + <para> + OK, we have all callbacks now. Let's set them up. In the + initialization of the card, make sure that you can get the chip + data from the card instance, typically via + <structfield>private_data</structfield> field, in case you + created the chip data individually. + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + .... + struct snd_card *card; + struct mychip *chip; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + .... + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + .... + card->private_data = chip; + .... + } +]]> + </programlisting> + </informalexample> + + When you created the chip data with + <function>snd_card_new()</function>, it's anyway accessible + via <structfield>private_data</structfield> field. + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + .... + struct snd_card *card; + struct mychip *chip; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); + .... + chip = card->private_data; + .... + } +]]> + </programlisting> + </informalexample> + + </para> + + <para> + If you need a space to save the registers, allocate the + buffer for it here, too, since it would be fatal + if you cannot allocate a memory in the suspend phase. + The allocated buffer should be released in the corresponding + destructor. + </para> + + <para> + And next, set suspend/resume callbacks to the pci_driver. + + <informalexample> + <programlisting> +<![CDATA[ + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_my_ids, + .probe = snd_my_probe, + .remove = snd_my_remove, + #ifdef CONFIG_PM + .suspend = snd_my_suspend, + .resume = snd_my_resume, + #endif + }; +]]> + </programlisting> + </informalexample> + </para> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Module Parameters --> +<!-- ****************************************************** --> + <chapter id="module-parameters"> + <title>Module Parameters</title> + <para> + There are standard module options for ALSA. At least, each + module should have the <parameter>index</parameter>, + <parameter>id</parameter> and <parameter>enable</parameter> + options. + </para> + + <para> + If the module supports multiple cards (usually up to + 8 = <constant>SNDRV_CARDS</constant> cards), they should be + arrays. The default initial values are defined already as + constants for easier programming: + + <informalexample> + <programlisting> +<![CDATA[ + static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; + static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; + static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; +]]> + </programlisting> + </informalexample> + </para> + + <para> + If the module supports only a single card, they could be single + variables, instead. <parameter>enable</parameter> option is not + always necessary in this case, but it would be better to have a + dummy option for compatibility. + </para> + + <para> + The module parameters must be declared with the standard + <function>module_param()()</function>, + <function>module_param_array()()</function> and + <function>MODULE_PARM_DESC()</function> macros. + </para> + + <para> + The typical coding would be like below: + + <informalexample> + <programlisting> +<![CDATA[ + #define CARD_NAME "My Chip" + + module_param_array(index, int, NULL, 0444); + MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); + module_param_array(id, charp, NULL, 0444); + MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); + module_param_array(enable, bool, NULL, 0444); + MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); +]]> + </programlisting> + </informalexample> + </para> + + <para> + Also, don't forget to define the module description, classes, + license and devices. Especially, the recent modprobe requires to + define the module license as GPL, etc., otherwise the system is + shown as <quote>tainted</quote>. + + <informalexample> + <programlisting> +<![CDATA[ + MODULE_DESCRIPTION("My Chip"); + MODULE_LICENSE("GPL"); + MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}"); +]]> + </programlisting> + </informalexample> + </para> + + </chapter> + + +<!-- ****************************************************** --> +<!-- How To Put Your Driver --> +<!-- ****************************************************** --> + <chapter id="how-to-put-your-driver"> + <title>How To Put Your Driver Into ALSA Tree</title> + <section> + <title>General</title> + <para> + So far, you've learned how to write the driver codes. + And you might have a question now: how to put my own + driver into the ALSA driver tree? + Here (finally :) the standard procedure is described briefly. + </para> + + <para> + Suppose that you create a new PCI driver for the card + <quote>xyz</quote>. The card module name would be + snd-xyz. The new driver is usually put into the alsa-driver + tree, <filename>alsa-driver/pci</filename> directory in + the case of PCI cards. + Then the driver is evaluated, audited and tested + by developers and users. After a certain time, the driver + will go to the alsa-kernel tree (to the corresponding directory, + such as <filename>alsa-kernel/pci</filename>) and eventually + will be integrated into the Linux 2.6 tree (the directory would be + <filename>linux/sound/pci</filename>). + </para> + + <para> + In the following sections, the driver code is supposed + to be put into alsa-driver tree. The two cases are covered: + a driver consisting of a single source file and one consisting + of several source files. + </para> + </section> + + <section> + <title>Driver with A Single Source File</title> + <para> + <orderedlist> + <listitem> + <para> + Modify alsa-driver/pci/Makefile + </para> + + <para> + Suppose you have a file xyz.c. Add the following + two lines + <informalexample> + <programlisting> +<![CDATA[ + snd-xyz-objs := xyz.o + obj-$(CONFIG_SND_XYZ) += snd-xyz.o +]]> + </programlisting> + </informalexample> + </para> + </listitem> + + <listitem> + <para> + Create the Kconfig entry + </para> + + <para> + Add the new entry of Kconfig for your xyz driver. + <informalexample> + <programlisting> +<![CDATA[ + config SND_XYZ + tristate "Foobar XYZ" + depends on SND + select SND_PCM + help + Say Y here to include support for Foobar XYZ soundcard. + + To compile this driver as a module, choose M here: the module + will be called snd-xyz. +]]> + </programlisting> + </informalexample> + + the line, select SND_PCM, specifies that the driver xyz supports + PCM. In addition to SND_PCM, the following components are + supported for select command: + SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, + SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. + Add the select command for each supported component. + </para> + + <para> + Note that some selections imply the lowlevel selections. + For example, PCM includes TIMER, MPU401_UART includes RAWMIDI, + AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP. + You don't need to give the lowlevel selections again. + </para> + + <para> + For the details of Kconfig script, refer to the kbuild + documentation. + </para> + + </listitem> + + <listitem> + <para> + Run cvscompile script to re-generate the configure script and + build the whole stuff again. + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section> + <title>Drivers with Several Source Files</title> + <para> + Suppose that the driver snd-xyz have several source files. + They are located in the new subdirectory, + pci/xyz. + + <orderedlist> + <listitem> + <para> + Add a new directory (<filename>xyz</filename>) in + <filename>alsa-driver/pci/Makefile</filename> as below + + <informalexample> + <programlisting> +<![CDATA[ + obj-$(CONFIG_SND) += xyz/ +]]> + </programlisting> + </informalexample> + </para> + </listitem> + + <listitem> + <para> + Under the directory <filename>xyz</filename>, create a Makefile + + <example> + <title>Sample Makefile for a driver xyz</title> + <programlisting> +<![CDATA[ + ifndef SND_TOPDIR + SND_TOPDIR=../.. + endif + + include $(SND_TOPDIR)/toplevel.config + include $(SND_TOPDIR)/Makefile.conf + + snd-xyz-objs := xyz.o abc.o def.o + + obj-$(CONFIG_SND_XYZ) += snd-xyz.o + + include $(SND_TOPDIR)/Rules.make +]]> + </programlisting> + </example> + </para> + </listitem> + + <listitem> + <para> + Create the Kconfig entry + </para> + + <para> + This procedure is as same as in the last section. + </para> + </listitem> + + <listitem> + <para> + Run cvscompile script to re-generate the configure script and + build the whole stuff again. + </para> + </listitem> + </orderedlist> + </para> + </section> + + </chapter> + +<!-- ****************************************************** --> +<!-- Useful Functions --> +<!-- ****************************************************** --> + <chapter id="useful-functions"> + <title>Useful Functions</title> + + <section id="useful-functions-snd-printk"> + <title><function>snd_printk()</function> and friends</title> + <para> + ALSA provides a verbose version of the + <function>printk()</function> function. If a kernel config + <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this + function prints the given message together with the file name + and the line of the caller. The <constant>KERN_XXX</constant> + prefix is processed as + well as the original <function>printk()</function> does, so it's + recommended to add this prefix, e.g. + + <informalexample> + <programlisting> +<![CDATA[ + snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n"); +]]> + </programlisting> + </informalexample> + </para> + + <para> + There are also <function>printk()</function>'s for + debugging. <function>snd_printd()</function> can be used for + general debugging purposes. If + <constant>CONFIG_SND_DEBUG</constant> is set, this function is + compiled, and works just like + <function>snd_printk()</function>. If the ALSA is compiled + without the debugging flag, it's ignored. + </para> + + <para> + <function>snd_printdd()</function> is compiled in only when + <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note + that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default + even if you configure the alsa-driver with + <option>--with-debug=full</option> option. You need to give + explicitly <option>--with-debug=detect</option> option instead. + </para> + </section> + + <section id="useful-functions-snd-bug"> + <title><function>snd_BUG()</function></title> + <para> + It shows the <computeroutput>BUG?</computeroutput> message and + stack trace as well as <function>snd_BUG_ON</function> at the point. + It's useful to show that a fatal error happens there. + </para> + <para> + When no debug flag is set, this macro is ignored. + </para> + </section> + + <section id="useful-functions-snd-bug-on"> + <title><function>snd_BUG_ON()</function></title> + <para> + <function>snd_BUG_ON()</function> macro is similar with + <function>WARN_ON()</function> macro. For example, + + <informalexample> + <programlisting> +<![CDATA[ + snd_BUG_ON(!pointer); +]]> + </programlisting> + </informalexample> + + or it can be used as the condition, + <informalexample> + <programlisting> +<![CDATA[ + if (snd_BUG_ON(non_zero_is_bug)) + return -EINVAL; +]]> + </programlisting> + </informalexample> + + </para> + + <para> + The macro takes an conditional expression to evaluate. + When <constant>CONFIG_SND_DEBUG</constant>, is set, if the + expression is non-zero, it shows the warning message such as + <computeroutput>BUG? (xxx)</computeroutput> + normally followed by stack trace. + + In both cases it returns the evaluated value. + </para> + + </section> + + </chapter> + + +<!-- ****************************************************** --> +<!-- Acknowledgments --> +<!-- ****************************************************** --> + <chapter id="acknowledgments"> + <title>Acknowledgments</title> + <para> + I would like to thank Phil Kerr for his help for improvement and + corrections of this document. + </para> + <para> + Kevin Conder reformatted the original plain-text to the + DocBook format. + </para> + <para> + Giuliano Pochini corrected typos and contributed the example codes + in the hardware constraints section. + </para> + </chapter> +</book>
diff --git a/Documentation/DocBook/writing_musb_glue_layer.tmpl b/Documentation/DocBook/writing_musb_glue_layer.tmpl new file mode 100644 index 0000000..837eca7 --- /dev/null +++ b/Documentation/DocBook/writing_musb_glue_layer.tmpl
@@ -0,0 +1,873 @@ +<?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="Writing-MUSB-Glue-Layer"> + <bookinfo> + <title>Writing an MUSB Glue Layer</title> + + <authorgroup> + <author> + <firstname>Apelete</firstname> + <surname>Seketeli</surname> + <affiliation> + <address> + <email>apelete at seketeli.net</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Apelete Seketeli</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 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 Linux kernel source + tree. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="introduction"> + <title>Introduction</title> + <para> + The Linux MUSB subsystem is part of the larger Linux USB + subsystem. It provides support for embedded USB Device Controllers + (UDC) that do not use Universal Host Controller Interface (UHCI) + or Open Host Controller Interface (OHCI). + </para> + <para> + Instead, these embedded UDC rely on the USB On-the-Go (OTG) + specification which they implement at least partially. The silicon + reference design used in most cases is the Multipoint USB + Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor + Graphics Inventra™ design. + </para> + <para> + As a self-taught exercise I have written an MUSB glue layer for + the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers + in the kernel source tree. This layer can be found at + drivers/usb/musb/jz4740.c. In this documentation I will walk + through the basics of the jz4740.c glue layer, explaining the + different pieces and what needs to be done in order to write your + own device glue layer. + </para> + </chapter> + + <chapter id="linux-musb-basics"> + <title>Linux MUSB Basics</title> + <para> + To get started on the topic, please read USB On-the-Go Basics (see + Resources) which provides an introduction of USB OTG operation at + the hardware level. A couple of wiki pages by Texas Instruments + and Analog Devices also provide an overview of the Linux kernel + MUSB configuration, albeit focused on some specific devices + provided by these companies. Finally, getting acquainted with the + USB specification at USB home page may come in handy, with + practical instance provided through the Writing USB Device Drivers + documentation (again, see Resources). + </para> + <para> + Linux USB stack is a layered architecture in which the MUSB + controller hardware sits at the lowest. The MUSB controller driver + abstract the MUSB controller hardware to the Linux USB stack. + </para> + <programlisting> + ------------------------ + | | <------- drivers/usb/gadget + | Linux USB Core Stack | <------- drivers/usb/host + | | <------- drivers/usb/core + ------------------------ + ⬍ + -------------------------- + | | <------ drivers/usb/musb/musb_gadget.c + | MUSB Controller driver | <------ drivers/usb/musb/musb_host.c + | | <------ drivers/usb/musb/musb_core.c + -------------------------- + ⬍ + --------------------------------- + | MUSB Platform Specific Driver | + | | <-- drivers/usb/musb/jz4740.c + | aka "Glue Layer" | + --------------------------------- + ⬍ + --------------------------------- + | MUSB Controller Hardware | + --------------------------------- + </programlisting> + <para> + As outlined above, the glue layer is actually the platform + specific code sitting in between the controller driver and the + controller hardware. + </para> + <para> + Just like a Linux USB driver needs to register itself with the + Linux USB subsystem, the MUSB glue layer needs first to register + itself with the MUSB controller driver. This will allow the + controller driver to know about which device the glue layer + supports and which functions to call when a supported device is + detected or released; remember we are talking about an embedded + controller chip here, so no insertion or removal at run-time. + </para> + <para> + All of this information is passed to the MUSB controller driver + through a platform_driver structure defined in the glue layer as: + </para> + <programlisting linenumbering="numbered"> +static struct platform_driver jz4740_driver = { + .probe = jz4740_probe, + .remove = jz4740_remove, + .driver = { + .name = "musb-jz4740", + }, +}; + </programlisting> + <para> + The probe and remove function pointers are called when a matching + device is detected and, respectively, released. The name string + describes the device supported by this glue layer. In the current + case it matches a platform_device structure declared in + arch/mips/jz4740/platform.c. Note that we are not using device + tree bindings here. + </para> + <para> + In order to register itself to the controller driver, the glue + layer goes through a few steps, basically allocating the + controller hardware resources and initialising a couple of + circuits. To do so, it needs to keep track of the information used + throughout these steps. This is done by defining a private + jz4740_glue structure: + </para> + <programlisting linenumbering="numbered"> +struct jz4740_glue { + struct device *dev; + struct platform_device *musb; + struct clk *clk; +}; + </programlisting> + <para> + The dev and musb members are both device structure variables. The + first one holds generic information about the device, since it's + the basic device structure, and the latter holds information more + closely related to the subsystem the device is registered to. The + clk variable keeps information related to the device clock + operation. + </para> + <para> + Let's go through the steps of the probe function that leads the + glue layer to register itself to the controller driver. + </para> + <para> + N.B.: For the sake of readability each function will be split in + logical parts, each part being shown as if it was independent from + the others. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + struct platform_device *musb; + struct jz4740_glue *glue; + struct clk *clk; + int ret; + + glue = devm_kzalloc(&pdev->dev, sizeof(*glue), GFP_KERNEL); + if (!glue) + return -ENOMEM; + + musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO); + if (!musb) { + dev_err(&pdev->dev, "failed to allocate musb device\n"); + return -ENOMEM; + } + + clk = devm_clk_get(&pdev->dev, "udc"); + if (IS_ERR(clk)) { + dev_err(&pdev->dev, "failed to get clock\n"); + ret = PTR_ERR(clk); + goto err_platform_device_put; + } + + ret = clk_prepare_enable(clk); + if (ret) { + dev_err(&pdev->dev, "failed to enable clock\n"); + goto err_platform_device_put; + } + + musb->dev.parent = &pdev->dev; + + glue->dev = &pdev->dev; + glue->musb = musb; + glue->clk = clk; + + return 0; + +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + The first few lines of the probe function allocate and assign the + glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows + the allocation process to sleep and wait for memory, thus being + usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line + 12) allows automatic allocation and management of device IDs in + order to avoid device namespace collisions with explicit IDs. With + devm_clk_get() (line 18) the glue layer allocates the clock -- the + <literal>devm_</literal> prefix indicates that clk_get() is + managed: it automatically frees the allocated clock resource data + when the device is released -- and enable it. + </para> + <para> + Then comes the registration steps: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + struct musb_hdrc_platform_data *pdata = &jz4740_musb_platform_data; + + pdata->platform_ops = &jz4740_musb_ops; + + platform_set_drvdata(pdev, glue); + + ret = platform_device_add_resources(musb, pdev->resource, + pdev->num_resources); + if (ret) { + dev_err(&pdev->dev, "failed to add resources\n"); + goto err_clk_disable; + } + + ret = platform_device_add_data(musb, pdata, sizeof(*pdata)); + if (ret) { + dev_err(&pdev->dev, "failed to add platform_data\n"); + goto err_clk_disable; + } + + return 0; + +err_clk_disable: + clk_disable_unprepare(clk); +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + The first step is to pass the device data privately held by the + glue layer on to the controller driver through + platform_set_drvdata() (line 7). Next is passing on the device + resources information, also privately held at that point, through + platform_device_add_resources() (line 9). + </para> + <para> + Finally comes passing on the platform specific data to the + controller driver (line 16). Platform data will be discussed in + <link linkend="device-platform-data">Chapter 4</link>, but here + we are looking at the platform_ops function pointer (line 5) in + musb_hdrc_platform_data structure (line 3). This function + pointer allows the MUSB controller driver to know which function + to call for device operation: + </para> + <programlisting linenumbering="numbered"> +static const struct musb_platform_ops jz4740_musb_ops = { + .init = jz4740_musb_init, + .exit = jz4740_musb_exit, +}; + </programlisting> + <para> + Here we have the minimal case where only init and exit functions + are called by the controller driver when needed. Fact is the + JZ4740 MUSB controller is a basic controller, lacking some + features found in other controllers, otherwise we may also have + pointers to a few other functions like a power management function + or a function to switch between OTG and non-OTG modes, for + instance. + </para> + <para> + At that point of the registration process, the controller driver + actually calls the init function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + The goal of jz4740_musb_init() is to get hold of the transceiver + driver data of the MUSB controller hardware and pass it on to the + MUSB controller driver, as usual. The transceiver is the circuitry + inside the controller hardware responsible for sending/receiving + the USB data. Since it is an implementation of the physical layer + of the OSI model, the transceiver is also referred to as PHY. + </para> + <para> + Getting hold of the MUSB PHY driver data is done with + usb_get_phy() which returns a pointer to the structure + containing the driver instance data. The next couple of + instructions (line 12 and 14) are used as a quirk and to setup + IRQ handling respectively. Quirks and IRQ handling will be + discussed later in <link linkend="device-quirks">Chapter + 5</link> and <link linkend="handling-irqs">Chapter 3</link>. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_exit(struct musb *musb) +{ + usb_put_phy(musb->xceiv); + + return 0; +} + </programlisting> + <para> + Acting as the counterpart of init, the exit function releases the + MUSB PHY driver when the controller hardware itself is about to be + released. + </para> + <para> + Again, note that init and exit are fairly simple in this case due + to the basic set of features of the JZ4740 controller hardware. + When writing an musb glue layer for a more complex controller + hardware, you might need to take care of more processing in those + two functions. + </para> + <para> + Returning from the init function, the MUSB controller driver jumps + back into the probe function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_probe(struct platform_device *pdev) +{ + ret = platform_device_add(musb); + if (ret) { + dev_err(&pdev->dev, "failed to register musb device\n"); + goto err_clk_disable; + } + + return 0; + +err_clk_disable: + clk_disable_unprepare(clk); +err_platform_device_put: + platform_device_put(musb); + return ret; +} + </programlisting> + <para> + This is the last part of the device registration process where the + glue layer adds the controller hardware device to Linux kernel + device hierarchy: at this stage, all known information about the + device is passed on to the Linux USB core stack. + </para> + <programlisting linenumbering="numbered"> +static int jz4740_remove(struct platform_device *pdev) +{ + struct jz4740_glue *glue = platform_get_drvdata(pdev); + + platform_device_unregister(glue->musb); + clk_disable_unprepare(glue->clk); + + return 0; +} + </programlisting> + <para> + Acting as the counterpart of probe, the remove function unregister + the MUSB controller hardware (line 5) and disable the clock (line + 6), allowing it to be gated. + </para> + </chapter> + + <chapter id="handling-irqs"> + <title>Handling IRQs</title> + <para> + Additionally to the MUSB controller hardware basic setup and + registration, the glue layer is also responsible for handling the + IRQs: + </para> + <programlisting linenumbering="numbered"> +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) +{ + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; +} + </programlisting> + <para> + Here the glue layer mostly has to read the relevant hardware + registers and pass their values on to the controller driver which + will handle the actual event that triggered the IRQ. + </para> + <para> + The interrupt handler critical section is protected by the + spin_lock_irqsave() and counterpart spin_unlock_irqrestore() + functions (line 7 and 24 respectively), which prevent the + interrupt handler code to be run by two different threads at the + same time. + </para> + <para> + Then the relevant interrupt registers are read (line 9 to 11): + </para> + <itemizedlist> + <listitem> + <para> + MUSB_INTRUSB: indicates which USB interrupts are currently + active, + </para> + </listitem> + <listitem> + <para> + MUSB_INTRTX: indicates which of the interrupts for TX + endpoints are currently active, + </para> + </listitem> + <listitem> + <para> + MUSB_INTRRX: indicates which of the interrupts for TX + endpoints are currently active. + </para> + </listitem> + </itemizedlist> + <para> + Note that musb_readb() is used to read 8-bit registers at most, + while musb_readw() allows us to read at most 16-bit registers. + There are other functions that can be used depending on the size + of your device registers. See musb_io.h for more information. + </para> + <para> + Instruction on line 18 is another quirk specific to the JZ4740 + USB device controller, which will be discussed later in <link + linkend="device-quirks">Chapter 5</link>. + </para> + <para> + The glue layer still needs to register the IRQ handler though. + Remember the instruction on line 14 of the init function: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + This instruction sets a pointer to the glue layer IRQ handler + function, in order for the controller hardware to call the handler + back when an IRQ comes from the controller hardware. The interrupt + handler is now implemented and registered. + </para> + </chapter> + + <chapter id="device-platform-data"> + <title>Device Platform Data</title> + <para> + In order to write an MUSB glue layer, you need to have some data + describing the hardware capabilities of your controller hardware, + which is called the platform data. + </para> + <para> + Platform data is specific to your hardware, though it may cover a + broad range of devices, and is generally found somewhere in the + arch/ directory, depending on your device architecture. + </para> + <para> + For instance, platform data for the JZ4740 SoC is found in + arch/mips/jz4740/platform.c. In the platform.c file each device of + the JZ4740 SoC is described through a set of structures. + </para> + <para> + Here is the part of arch/mips/jz4740/platform.c that covers the + USB Device Controller (UDC): + </para> + <programlisting linenumbering="numbered"> +/* USB Device Controller */ +struct platform_device jz4740_udc_xceiv_device = { + .name = "usb_phy_gen_xceiv", + .id = 0, +}; + +static struct resource jz4740_udc_resources[] = { + [0] = { + .start = JZ4740_UDC_BASE_ADDR, + .end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1, + .flags = IORESOURCE_MEM, + }, + [1] = { + .start = JZ4740_IRQ_UDC, + .end = JZ4740_IRQ_UDC, + .flags = IORESOURCE_IRQ, + .name = "mc", + }, +}; + +struct platform_device jz4740_udc_device = { + .name = "musb-jz4740", + .id = -1, + .dev = { + .dma_mask = &jz4740_udc_device.dev.coherent_dma_mask, + .coherent_dma_mask = DMA_BIT_MASK(32), + }, + .num_resources = ARRAY_SIZE(jz4740_udc_resources), + .resource = jz4740_udc_resources, +}; + </programlisting> + <para> + The jz4740_udc_xceiv_device platform device structure (line 2) + describes the UDC transceiver with a name and id number. + </para> + <para> + At the time of this writing, note that + "usb_phy_gen_xceiv" is the specific name to be used for + all transceivers that are either built-in with reference USB IP or + autonomous and doesn't require any PHY programming. You will need + to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make + use of the corresponding transceiver driver. The id field could be + set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to + PLATFORM_DEVID_AUTO) or start with 0 for the first device of this + kind if we want a specific id number. + </para> + <para> + The jz4740_udc_resources resource structure (line 7) defines the + UDC registers base addresses. + </para> + <para> + The first array (line 9 to 11) defines the UDC registers base + memory addresses: start points to the first register memory + address, end points to the last register memory address and the + flags member defines the type of resource we are dealing with. So + IORESOURCE_MEM is used to define the registers memory addresses. + The second array (line 14 to 17) defines the UDC IRQ registers + addresses. Since there is only one IRQ register available for the + JZ4740 UDC, start and end point at the same address. The + IORESOURCE_IRQ flag tells that we are dealing with IRQ resources, + and the name "mc" is in fact hard-coded in the MUSB core + in order for the controller driver to retrieve this IRQ resource + by querying it by its name. + </para> + <para> + Finally, the jz4740_udc_device platform device structure (line 21) + describes the UDC itself. + </para> + <para> + The "musb-jz4740" name (line 22) defines the MUSB + driver that is used for this device; remember this is in fact + the name that we used in the jz4740_driver platform driver + structure in <link linkend="linux-musb-basics">Chapter + 2</link>. The id field (line 23) is set to -1 (equivalent to + PLATFORM_DEVID_NONE) since we do not need an id for the device: + the MUSB controller driver was already set to allocate an + automatic id in <link linkend="linux-musb-basics">Chapter + 2</link>. In the dev field we care for DMA related information + here. The dma_mask field (line 25) defines the width of the DMA + mask that is going to be used, and coherent_dma_mask (line 26) + has the same purpose but for the alloc_coherent DMA mappings: in + both cases we are using a 32 bits mask. Then the resource field + (line 29) is simply a pointer to the resource structure defined + before, while the num_resources field (line 28) keeps track of + the number of arrays defined in the resource structure (in this + case there were two resource arrays defined before). + </para> + <para> + With this quick overview of the UDC platform data at the arch/ + level now done, let's get back to the MUSB glue layer specific + platform data in drivers/usb/musb/jz4740.c: + </para> + <programlisting linenumbering="numbered"> +static struct musb_hdrc_config jz4740_musb_config = { + /* Silicon does not implement USB OTG. */ + .multipoint = 0, + /* Max EPs scanned, driver will decide which EP can be used. */ + .num_eps = 4, + /* RAMbits needed to configure EPs from table */ + .ram_bits = 9, + .fifo_cfg = jz4740_musb_fifo_cfg, + .fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg), +}; + +static struct musb_hdrc_platform_data jz4740_musb_platform_data = { + .mode = MUSB_PERIPHERAL, + .config = &jz4740_musb_config, +}; + </programlisting> + <para> + First the glue layer configures some aspects of the controller + driver operation related to the controller hardware specifics. + This is done through the jz4740_musb_config musb_hdrc_config + structure. + </para> + <para> + Defining the OTG capability of the controller hardware, the + multipoint member (line 3) is set to 0 (equivalent to false) + since the JZ4740 UDC is not OTG compatible. Then num_eps (line + 5) defines the number of USB endpoints of the controller + hardware, including endpoint 0: here we have 3 endpoints + + endpoint 0. Next is ram_bits (line 7) which is the width of the + RAM address bus for the MUSB controller hardware. This + information is needed when the controller driver cannot + automatically configure endpoints by reading the relevant + controller hardware registers. This issue will be discussed when + we get to device quirks in <link linkend="device-quirks">Chapter + 5</link>. Last two fields (line 8 and 9) are also about device + quirks: fifo_cfg points to the USB endpoints configuration table + and fifo_cfg_size keeps track of the size of the number of + entries in that configuration table. More on that later in <link + linkend="device-quirks">Chapter 5</link>. + </para> + <para> + Then this configuration is embedded inside + jz4740_musb_platform_data musb_hdrc_platform_data structure (line + 11): config is a pointer to the configuration structure itself, + and mode tells the controller driver if the controller hardware + may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG + which is a dual mode. + </para> + <para> + Remember that jz4740_musb_platform_data is then used to convey + platform data information as we have seen in the probe function + in <link linkend="linux-musb-basics">Chapter 2</link> + </para> + </chapter> + + <chapter id="device-quirks"> + <title>Device Quirks</title> + <para> + Completing the platform data specific to your device, you may also + need to write some code in the glue layer to work around some + device specific limitations. These quirks may be due to some + hardware bugs, or simply be the result of an incomplete + implementation of the USB On-the-Go specification. + </para> + <para> + The JZ4740 UDC exhibits such quirks, some of which we will discuss + here for the sake of insight even though these might not be found + in the controller hardware you are working on. + </para> + <para> + Let's get back to the init function first: + </para> + <programlisting linenumbering="numbered"> +static int jz4740_musb_init(struct musb *musb) +{ + musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2); + if (!musb->xceiv) { + pr_err("HS UDC: no transceiver configured\n"); + return -ENODEV; + } + + /* Silicon does not implement ConfigData register. + * Set dyn_fifo to avoid reading EP config from hardware. + */ + musb->dyn_fifo = true; + + musb->isr = jz4740_musb_interrupt; + + return 0; +} + </programlisting> + <para> + Instruction on line 12 helps the MUSB controller driver to work + around the fact that the controller hardware is missing registers + that are used for USB endpoints configuration. + </para> + <para> + Without these registers, the controller driver is unable to read + the endpoints configuration from the hardware, so we use line 12 + instruction to bypass reading the configuration from silicon, and + rely on a hard-coded table that describes the endpoints + configuration instead: + </para> + <programlisting linenumbering="numbered"> +static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = { +{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, }, +{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, }, +{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, }, +}; + </programlisting> + <para> + Looking at the configuration table above, we see that each + endpoints is described by three fields: hw_ep_num is the endpoint + number, style is its direction (either FIFO_TX for the controller + driver to send packets in the controller hardware, or FIFO_RX to + receive packets from hardware), and maxpacket defines the maximum + size of each data packet that can be transmitted over that + endpoint. Reading from the table, the controller driver knows that + endpoint 1 can be used to send and receive USB data packets of 512 + bytes at once (this is in fact a bulk in/out endpoint), and + endpoint 2 can be used to send data packets of 64 bytes at once + (this is in fact an interrupt endpoint). + </para> + <para> + Note that there is no information about endpoint 0 here: that one + is implemented by default in every silicon design, with a + predefined configuration according to the USB specification. For + more examples of endpoint configuration tables, see musb_core.c. + </para> + <para> + Let's now get back to the interrupt handler function: + </para> + <programlisting linenumbering="numbered"> +static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci) +{ + unsigned long flags; + irqreturn_t retval = IRQ_NONE; + struct musb *musb = __hci; + + spin_lock_irqsave(&musb->lock, flags); + + musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB); + musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX); + musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX); + + /* + * The controller is gadget only, the state of the host mode IRQ bits is + * undefined. Mask them to make sure that the musb driver core will + * never see them set + */ + musb->int_usb &= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME | + MUSB_INTR_RESET | MUSB_INTR_SOF; + + if (musb->int_usb || musb->int_tx || musb->int_rx) + retval = musb_interrupt(musb); + + spin_unlock_irqrestore(&musb->lock, flags); + + return retval; +} + </programlisting> + <para> + Instruction on line 18 above is a way for the controller driver to + work around the fact that some interrupt bits used for USB host + mode operation are missing in the MUSB_INTRUSB register, thus left + in an undefined hardware state, since this MUSB controller + hardware is used in peripheral mode only. As a consequence, the + glue layer masks these missing bits out to avoid parasite + interrupts by doing a logical AND operation between the value read + from MUSB_INTRUSB and the bits that are actually implemented in + the register. + </para> + <para> + These are only a couple of the quirks found in the JZ4740 USB + device controller. Some others were directly addressed in the MUSB + core since the fixes were generic enough to provide a better + handling of the issues for others controller hardware eventually. + </para> + </chapter> + + <chapter id="conclusion"> + <title>Conclusion</title> + <para> + Writing a Linux MUSB glue layer should be a more accessible task, + as this documentation tries to show the ins and outs of this + exercise. + </para> + <para> + The JZ4740 USB device controller being fairly simple, I hope its + glue layer serves as a good example for the curious mind. Used + with the current MUSB glue layers, this documentation should + provide enough guidance to get started; should anything gets out + of hand, the linux-usb mailing list archive is another helpful + resource to browse through. + </para> + </chapter> + + <chapter id="acknowledgements"> + <title>Acknowledgements</title> + <para> + Many thanks to Lars-Peter Clausen and Maarten ter Huurne for + answering my questions while I was writing the JZ4740 glue layer + and for helping me out getting the code in good shape. + </para> + <para> + I would also like to thank the Qi-Hardware community at large for + its cheerful guidance and support. + </para> + </chapter> + + <chapter id="resources"> + <title>Resources</title> + <para> + USB Home Page: + <ulink url="http://www.usb.org">http://www.usb.org</ulink> + </para> + <para> + linux-usb Mailing List Archives: + <ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink> + </para> + <para> + USB On-the-Go Basics: + <ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink> + </para> + <para> + Writing USB Device Drivers: + <ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink> + </para> + <para> + Texas Instruments USB Configuration Wiki Page: + <ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink> + </para> + <para> + Analog Devices Blackfin MUSB Configuration: + <ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink> + </para> + </chapter> + +</book>
diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl new file mode 100644 index 0000000..3210dcf --- /dev/null +++ b/Documentation/DocBook/writing_usb_driver.tmpl
@@ -0,0 +1,412 @@ +<?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="USBDeviceDriver"> + <bookinfo> + <title>Writing USB Device Drivers</title> + + <authorgroup> + <author> + <firstname>Greg</firstname> + <surname>Kroah-Hartman</surname> + <affiliation> + <address> + <email>greg@kroah.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2001-2002</year> + <holder>Greg Kroah-Hartman</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> + + <para> + This documentation is based on an article published in + Linux Journal Magazine, October 2001, Issue 90. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + The Linux USB subsystem has grown from supporting only two different + types of devices in the 2.2.7 kernel (mice and keyboards), to over 20 + different types of devices in the 2.4 kernel. Linux currently supports + almost all USB class devices (standard types of devices like keyboards, + mice, modems, printers and speakers) and an ever-growing number of + vendor-specific devices (such as USB to serial converters, digital + cameras, Ethernet devices and MP3 players). For a full list of the + different USB devices currently supported, see Resources. + </para> + <para> + The remaining kinds of USB devices that do not have support on Linux are + almost all vendor-specific devices. Each vendor decides to implement a + custom protocol to talk to their device, so a custom driver usually needs + to be created. Some vendors are open with their USB protocols and help + with the creation of Linux drivers, while others do not publish them, and + developers are forced to reverse-engineer. See Resources for some links + to handy reverse-engineering tools. + </para> + <para> + Because each different protocol causes a new driver to be created, I have + written a generic USB driver skeleton, modelled after the pci-skeleton.c + file in the kernel source tree upon which many PCI network drivers have + been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c + in the kernel source tree. In this article I will walk through the basics + of the skeleton driver, explaining the different pieces and what needs to + be done to customize it to your specific device. + </para> + </chapter> + + <chapter id="basics"> + <title>Linux USB Basics</title> + <para> + If you are going to write a Linux USB driver, please become familiar with + the USB protocol specification. It can be found, along with many other + useful documents, at the USB home page (see Resources). An excellent + introduction to the Linux USB subsystem can be found at the USB Working + Devices List (see Resources). It explains how the Linux USB subsystem is + structured and introduces the reader to the concept of USB urbs + (USB Request Blocks), which are essential to USB drivers. + </para> + <para> + The first thing a Linux USB driver needs to do is register itself with + the Linux USB subsystem, giving it some information about which devices + the driver supports and which functions to call when a device supported + by the driver is inserted or removed from the system. All of this + information is passed to the USB subsystem in the usb_driver structure. + The skeleton driver declares a usb_driver as: + </para> + <programlisting> +static struct usb_driver skel_driver = { + .name = "skeleton", + .probe = skel_probe, + .disconnect = skel_disconnect, + .fops = &skel_fops, + .minor = USB_SKEL_MINOR_BASE, + .id_table = skel_table, +}; + </programlisting> + <para> + The variable name is a string that describes the driver. It is used in + informational messages printed to the system log. The probe and + disconnect function pointers are called when a device that matches the + information provided in the id_table variable is either seen or removed. + </para> + <para> + The fops and minor variables are optional. Most USB drivers hook into + another kernel subsystem, such as the SCSI, network or TTY subsystem. + These types of drivers register themselves with the other kernel + subsystem, and any user-space interactions are provided through that + interface. But for drivers that do not have a matching kernel subsystem, + such as MP3 players or scanners, a method of interacting with user space + is needed. The USB subsystem provides a way to register a minor device + number and a set of file_operations function pointers that enable this + user-space interaction. The skeleton driver needs this kind of interface, + so it provides a minor starting number and a pointer to its + file_operations functions. + </para> + <para> + The USB driver is then registered with a call to usb_register, usually in + the driver's init function, as shown here: + </para> + <programlisting> +static int __init usb_skel_init(void) +{ + int result; + + /* register this driver with the USB subsystem */ + result = usb_register(&skel_driver); + if (result < 0) { + err("usb_register failed for the "__FILE__ "driver." + "Error number %d", result); + return -1; + } + + return 0; +} +module_init(usb_skel_init); + </programlisting> + <para> + When the driver is unloaded from the system, it needs to deregister + itself with the USB subsystem. This is done with the usb_deregister + function: + </para> + <programlisting> +static void __exit usb_skel_exit(void) +{ + /* deregister this driver with the USB subsystem */ + usb_deregister(&skel_driver); +} +module_exit(usb_skel_exit); + </programlisting> + <para> + To enable the linux-hotplug system to load the driver automatically when + the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The + following code tells the hotplug scripts that this module supports a + single device with a specific vendor and product ID: + </para> + <programlisting> +/* table of devices that work with this driver */ +static struct usb_device_id skel_table [] = { + { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) }, + { } /* Terminating entry */ +}; +MODULE_DEVICE_TABLE (usb, skel_table); + </programlisting> + <para> + There are other macros that can be used in describing a usb_device_id for + drivers that support a whole class of USB drivers. See usb.h for more + information on this. + </para> + </chapter> + + <chapter id="device"> + <title>Device operation</title> + <para> + When a device is plugged into the USB bus that matches the device ID + pattern that your driver registered with the USB core, the probe function + is called. The usb_device structure, interface number and the interface ID + are passed to the function: + </para> + <programlisting> +static int skel_probe(struct usb_interface *interface, + const struct usb_device_id *id) + </programlisting> + <para> + The driver now needs to verify that this device is actually one that it + can accept. If so, it returns 0. + If not, or if any error occurs during initialization, an errorcode + (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>) + is returned from the probe function. + </para> + <para> + In the skeleton driver, we determine what end points are marked as bulk-in + and bulk-out. We create buffers to hold the data that will be sent and + received from the device, and a USB urb to write data to the device is + initialized. + </para> + <para> + Conversely, when the device is removed from the USB bus, the disconnect + function is called with the device pointer. The driver needs to clean any + private data that has been allocated at this time and to shut down any + pending urbs that are in the USB system. + </para> + <para> + Now that the device is plugged into the system and the driver is bound to + the device, any of the functions in the file_operations structure that + were passed to the USB subsystem will be called from a user program trying + to talk to the device. The first function called will be open, as the + program tries to open the device for I/O. We increment our private usage + count and save a pointer to our internal structure in the file + structure. This is done so that future calls to file operations will + enable the driver to determine which device the user is addressing. All + of this is done with the following code: + </para> + <programlisting> +/* increment our usage count for the module */ +++skel->open_count; + +/* save our object in the file's private structure */ +file->private_data = dev; + </programlisting> + <para> + After the open function is called, the read and write functions are called + to receive and send data to the device. In the skel_write function, we + receive a pointer to some data that the user wants to send to the device + and the size of the data. The function determines how much data it can + send to the device based on the size of the write urb it has created (this + size depends on the size of the bulk out end point that the device has). + Then it copies the data from user space to kernel space, points the urb to + the data and submits the urb to the USB subsystem. This can be seen in + the following code: + </para> + <programlisting> +/* we can only write as much as 1 urb will hold */ +bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; + +/* copy the data from user space into our urb */ +copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); + +/* set up our urb */ +usb_fill_bulk_urb(skel->write_urb, + skel->dev, + usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), + skel->write_urb->transfer_buffer, + bytes_written, + skel_write_bulk_callback, + skel); + +/* send the data out the bulk port */ +result = usb_submit_urb(skel->write_urb); +if (result) { + err("Failed submitting write urb, error %d", result); +} + </programlisting> + <para> + When the write urb is filled up with the proper information using the + usb_fill_bulk_urb function, we point the urb's completion callback to call our + own skel_write_bulk_callback function. This function is called when the + urb is finished by the USB subsystem. The callback function is called in + interrupt context, so caution must be taken not to do very much processing + at that time. Our implementation of skel_write_bulk_callback merely + reports if the urb was completed successfully or not and then returns. + </para> + <para> + The read function works a bit differently from the write function in that + we do not use an urb to transfer data from the device to the driver. + Instead we call the usb_bulk_msg function, which can be used to send or + receive data from a device without having to create urbs and handle + urb completion callback functions. We call the usb_bulk_msg function, + giving it a buffer into which to place any data received from the device + and a timeout value. If the timeout period expires without receiving any + data from the device, the function will fail and return an error message. + This can be shown with the following code: + </para> + <programlisting> +/* do an immediate bulk read to get data from the device */ +retval = usb_bulk_msg (skel->dev, + usb_rcvbulkpipe (skel->dev, + skel->bulk_in_endpointAddr), + skel->bulk_in_buffer, + skel->bulk_in_size, + &count, HZ*10); +/* if the read was successful, copy the data to user space */ +if (!retval) { + if (copy_to_user (buffer, skel->bulk_in_buffer, count)) + retval = -EFAULT; + else + retval = count; +} + </programlisting> + <para> + The usb_bulk_msg function can be very useful for doing single reads or + writes to a device; however, if you need to read or write constantly to a + device, it is recommended to set up your own urbs and submit them to the + USB subsystem. + </para> + <para> + When the user program releases the file handle that it has been using to + talk to the device, the release function in the driver is called. In this + function we decrement our private usage count and wait for possible + pending writes: + </para> + <programlisting> +/* decrement our usage count for the device */ +--skel->open_count; + </programlisting> + <para> + One of the more difficult problems that USB drivers must be able to handle + smoothly is the fact that the USB device may be removed from the system at + any point in time, even if a program is currently talking to it. It needs + to be able to shut down any current reads and writes and notify the + user-space programs that the device is no longer there. The following + code (function <function>skel_delete</function>) + is an example of how to do this: </para> + <programlisting> +static inline void skel_delete (struct usb_skel *dev) +{ + kfree (dev->bulk_in_buffer); + if (dev->bulk_out_buffer != NULL) + usb_free_coherent (dev->udev, dev->bulk_out_size, + dev->bulk_out_buffer, + dev->write_urb->transfer_dma); + usb_free_urb (dev->write_urb); + kfree (dev); +} + </programlisting> + <para> + If a program currently has an open handle to the device, we reset the flag + <literal>device_present</literal>. For + every read, write, release and other functions that expect a device to be + present, the driver first checks this flag to see if the device is + still present. If not, it releases that the device has disappeared, and a + -ENODEV error is returned to the user-space program. When the release + function is eventually called, it determines if there is no device + and if not, it does the cleanup that the skel_disconnect + function normally does if there are no open files on the device (see + Listing 5). + </para> + </chapter> + + <chapter id="iso"> + <title>Isochronous Data</title> + <para> + This usb-skeleton driver does not have any examples of interrupt or + isochronous data being sent to or from the device. Interrupt data is sent + almost exactly as bulk data is, with a few minor exceptions. Isochronous + data works differently with continuous streams of data being sent to or + from the device. The audio and video camera drivers are very good examples + of drivers that handle isochronous data and will be useful if you also + need to do this. + </para> + </chapter> + + <chapter id="Conclusion"> + <title>Conclusion</title> + <para> + Writing Linux USB device drivers is not a difficult task as the + usb-skeleton driver shows. This driver, combined with the other current + USB drivers, should provide enough examples to help a beginning author + create a working driver in a minimal amount of time. The linux-usb-devel + mailing list archives also contain a lot of helpful information. + </para> + </chapter> + + <chapter id="resources"> + <title>Resources</title> + <para> + The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink> + </para> + <para> + Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink> + </para> + <para> + Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink> + </para> + <para> + linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink> + </para> + <para> + Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink> + </para> + <para> + USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink> + </para> + </chapter> + +</book>
diff --git a/Documentation/DocBook/z8530book.tmpl b/Documentation/DocBook/z8530book.tmpl new file mode 100644 index 0000000..6f3883b --- /dev/null +++ b/Documentation/DocBook/z8530book.tmpl
@@ -0,0 +1,371 @@ +<?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="Z85230Guide"> + <bookinfo> + <title>Z8530 Programming Guide</title> + + <authorgroup> + <author> + <firstname>Alan</firstname> + <surname>Cox</surname> + <affiliation> + <address> + <email>alan@lxorguk.ukuu.org.uk</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2000</year> + <holder>Alan Cox</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 Z85x30 family synchronous/asynchronous controller chips are + used on a large number of cheap network interface cards. The + kernel provides a core interface layer that is designed to make + it easy to provide WAN services using this chip. + </para> + <para> + The current driver only support synchronous operation. Merging the + asynchronous driver support into this code to allow any Z85x30 + device to be used as both a tty interface and as a synchronous + controller is a project for Linux post the 2.4 release + </para> + </chapter> + + <chapter id="Driver_Modes"> + <title>Driver Modes</title> + <para> + The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices + in three different modes. Each mode can be applied to an individual + channel on the chip (each chip has two channels). + </para> + <para> + The PIO synchronous mode supports the most common Z8530 wiring. Here + the chip is interface to the I/O and interrupt facilities of the + host machine but not to the DMA subsystem. When running PIO the + Z8530 has extremely tight timing requirements. Doing high speeds, + even with a Z85230 will be tricky. Typically you should expect to + achieve at best 9600 baud with a Z8C530 and 64Kbits with a Z85230. + </para> + <para> + The DMA mode supports the chip when it is configured to use dual DMA + channels on an ISA bus. The better cards tend to support this mode + of operation for a single channel. With DMA running the Z85230 tops + out when it starts to hit ISA DMA constraints at about 512Kbits. It + is worth noting here that many PC machines hang or crash when the + chip is driven fast enough to hold the ISA bus solid. + </para> + <para> + Transmit DMA mode uses a single DMA channel. The DMA channel is used + for transmission as the transmit FIFO is smaller than the receive + FIFO. it gives better performance than pure PIO mode but is nowhere + near as ideal as pure DMA mode. + </para> + </chapter> + + <chapter id="Using_the_Z85230_driver"> + <title>Using the Z85230 driver</title> + <para> + The Z85230 driver provides the back end interface to your board. To + configure a Z8530 interface you need to detect the board and to + identify its ports and interrupt resources. It is also your problem + to verify the resources are available. + </para> + <para> + Having identified the chip you need to fill in a struct z8530_dev, + which describes each chip. This object must exist until you finally + shutdown the board. Firstly zero the active field. This ensures + nothing goes off without you intending it. The irq field should + be set to the interrupt number of the chip. (Each chip has a single + interrupt source rather than each channel). You are responsible + for allocating the interrupt line. The interrupt handler should be + set to <function>z8530_interrupt</function>. The device id should + be set to the z8530_dev structure pointer. Whether the interrupt can + be shared or not is board dependent, and up to you to initialise. + </para> + <para> + The structure holds two channel structures. + Initialise chanA.ctrlio and chanA.dataio with the address of the + control and data ports. You can or this with Z8530_PORT_SLEEP to + indicate your interface needs the 5uS delay for chip settling done + in software. The PORT_SLEEP option is architecture specific. Other + flags may become available on future platforms, eg for MMIO. + Initialise the chanA.irqs to &z8530_nop to start the chip up + as disabled and discarding interrupt events. This ensures that + stray interrupts will be mopped up and not hang the bus. Set + chanA.dev to point to the device structure itself. The + private and name field you may use as you wish. The private field + is unused by the Z85230 layer. The name is used for error reporting + and it may thus make sense to make it match the network name. + </para> + <para> + Repeat the same operation with the B channel if your chip has + both channels wired to something useful. This isn't always the + case. If it is not wired then the I/O values do not matter, but + you must initialise chanB.dev. + </para> + <para> + If your board has DMA facilities then initialise the txdma and + rxdma fields for the relevant channels. You must also allocate the + ISA DMA channels and do any necessary board level initialisation + to configure them. The low level driver will do the Z8530 and + DMA controller programming but not board specific magic. + </para> + <para> + Having initialised the device you can then call + <function>z8530_init</function>. This will probe the chip and + reset it into a known state. An identification sequence is then + run to identify the chip type. If the checks fail to pass the + function returns a non zero error code. Typically this indicates + that the port given is not valid. After this call the + type field of the z8530_dev structure is initialised to either + Z8530, Z85C30 or Z85230 according to the chip found. + </para> + <para> + Once you have called z8530_init you can also make use of the utility + function <function>z8530_describe</function>. This provides a + consistent reporting format for the Z8530 devices, and allows all + the drivers to provide consistent reporting. + </para> + </chapter> + + <chapter id="Attaching_Network_Interfaces"> + <title>Attaching Network Interfaces</title> + <para> + If you wish to use the network interface facilities of the driver, + then you need to attach a network device to each channel that is + present and in use. In addition to use the generic HDLC + you need to follow some additional plumbing rules. They may seem + complex but a look at the example hostess_sv11 driver should + reassure you. + </para> + <para> + The network device used for each channel should be pointed to by + the netdevice field of each channel. The hdlc-> priv field of the + network device points to your private data - you will need to be + able to find your private data from this. + </para> + <para> + The way most drivers approach this particular problem is to + create a structure holding the Z8530 device definition and + put that into the private field of the network device. The + network device fields of the channels then point back to the + network devices. + </para> + <para> + If you wish to use the generic HDLC then you need to register + the HDLC device. + </para> + <para> + Before you register your network device you will also need to + provide suitable handlers for most of the network device callbacks. + See the network device documentation for more details on this. + </para> + </chapter> + + <chapter id="Configuring_And_Activating_The_Port"> + <title>Configuring And Activating The Port</title> + <para> + The Z85230 driver provides helper functions and tables to load the + port registers on the Z8530 chips. When programming the register + settings for a channel be aware that the documentation recommends + initialisation orders. Strange things happen when these are not + followed. + </para> + <para> + <function>z8530_channel_load</function> takes an array of + pairs of initialisation values in an array of u8 type. The first + value is the Z8530 register number. Add 16 to indicate the alternate + register bank on the later chips. The array is terminated by a 255. + </para> + <para> + The driver provides a pair of public tables. The + z8530_hdlc_kilostream table is for the UK 'Kilostream' service and + also happens to cover most other end host configurations. The + z8530_hdlc_kilostream_85230 table is the same configuration using + the enhancements of the 85230 chip. The configuration loaded is + standard NRZ encoded synchronous data with HDLC bitstuffing. All + of the timing is taken from the other end of the link. + </para> + <para> + When writing your own tables be aware that the driver internally + tracks register values. It may need to reload values. You should + therefore be sure to set registers 1-7, 9-11, 14 and 15 in all + configurations. Where the register settings depend on DMA selection + the driver will update the bits itself when you open or close. + Loading a new table with the interface open is not recommended. + </para> + <para> + There are three standard configurations supported by the core + code. In PIO mode the interface is programmed up to use + interrupt driven PIO. This places high demands on the host processor + to avoid latency. The driver is written to take account of latency + issues but it cannot avoid latencies caused by other drivers, + notably IDE in PIO mode. Because the drivers allocate buffers you + must also prevent MTU changes while the port is open. + </para> + <para> + Once the port is open it will call the rx_function of each channel + whenever a completed packet arrived. This is invoked from + interrupt context and passes you the channel and a network + buffer (struct sk_buff) holding the data. The data includes + the CRC bytes so most users will want to trim the last two + bytes before processing the data. This function is very timing + critical. When you wish to simply discard data the support + code provides the function <function>z8530_null_rx</function> + to discard the data. + </para> + <para> + To active PIO mode sending and receiving the <function> + z8530_sync_open</function> is called. This expects to be passed + the network device and the channel. Typically this is called from + your network device open callback. On a failure a non zero error + status is returned. The <function>z8530_sync_close</function> + function shuts down a PIO channel. This must be done before the + channel is opened again and before the driver shuts down + and unloads. + </para> + <para> + The ideal mode of operation is dual channel DMA mode. Here the + kernel driver will configure the board for DMA in both directions. + The driver also handles ISA DMA issues such as controller + programming and the memory range limit for you. This mode is + activated by calling the <function>z8530_sync_dma_open</function> + function. On failure a non zero error value is returned. + Once this mode is activated it can be shut down by calling the + <function>z8530_sync_dma_close</function>. You must call the close + function matching the open mode you used. + </para> + <para> + The final supported mode uses a single DMA channel to drive the + transmit side. As the Z85C30 has a larger FIFO on the receive + channel this tends to increase the maximum speed a little. + This is activated by calling the <function>z8530_sync_txdma_open + </function>. This returns a non zero error code on failure. The + <function>z8530_sync_txdma_close</function> function closes down + the Z8530 interface from this mode. + </para> + </chapter> + + <chapter id="Network_Layer_Functions"> + <title>Network Layer Functions</title> + <para> + The Z8530 layer provides functions to queue packets for + transmission. The driver internally buffers the frame currently + being transmitted and one further frame (in order to keep back + to back transmission running). Any further buffering is up to + the caller. + </para> + <para> + The function <function>z8530_queue_xmit</function> takes a network + buffer in sk_buff format and queues it for transmission. The + caller must provide the entire packet with the exception of the + bitstuffing and CRC. This is normally done by the caller via + the generic HDLC interface layer. It returns 0 if the buffer has been + queued and non zero values for queue full. If the function accepts + the buffer it becomes property of the Z8530 layer and the caller + should not free it. + </para> + <para> + The function <function>z8530_get_stats</function> returns a pointer + to an internally maintained per interface statistics block. This + provides most of the interface code needed to implement the network + layer get_stats callback. + </para> + </chapter> + + <chapter id="Porting_The_Z8530_Driver"> + <title>Porting The Z8530 Driver</title> + <para> + The Z8530 driver is written to be portable. In DMA mode it makes + assumptions about the use of ISA DMA. These are probably warranted + in most cases as the Z85230 in particular was designed to glue to PC + type machines. The PIO mode makes no real assumptions. + </para> + <para> + Should you need to retarget the Z8530 driver to another architecture + the only code that should need changing are the port I/O functions. + At the moment these assume PC I/O port accesses. This may not be + appropriate for all platforms. Replacing + <function>z8530_read_port</function> and <function>z8530_write_port + </function> is intended to be all that is required to port this + driver layer. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry><term>Interrupt Locking</term> + <listitem> + <para> + The locking in the driver is done via the global cli/sti lock. This + makes for relatively poor SMP performance. Switching this to use a + per device spin lock would probably materially improve performance. + </para> + </listitem></varlistentry> + + <varlistentry><term>Occasional Failures</term> + <listitem> + <para> + We have reports of occasional failures when run for very long + periods of time and the driver starts to receive junk frames. At + the moment the cause of this is not clear. + </para> + </listitem></varlistentry> + </variablelist> + + </para> + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> +!Edrivers/net/wan/z85230.c + </chapter> + + <chapter id="intfunctions"> + <title>Internal Functions</title> +!Idrivers/net/wan/z85230.c + </chapter> + +</book>
diff --git a/Documentation/EDID/1024x768.S b/Documentation/EDID/1024x768.S new file mode 100644 index 0000000..6f3e4b7 --- /dev/null +++ b/Documentation/EDID/1024x768.S
@@ -0,0 +1,44 @@ +/* + 1024x768.S: EDID data set for standard 1024x768 60 Hz monitor + + Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 65000 /* kHz */ +#define XPIX 1024 +#define YPIX 768 +#define XY_RATIO XY_RATIO_4_3 +#define XBLANK 320 +#define YBLANK 38 +#define XOFFSET 8 +#define XPULSE 144 +#define YOFFSET (63+3) +#define YPULSE (63+6) +#define DPI 72 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux XGA" +#define ESTABLISHED_TIMING2_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */ +#define HSYNC_POL 0 +#define VSYNC_POL 0 +#define CRC 0x55 + +#include "edid.S"
diff --git a/Documentation/EDID/1280x1024.S b/Documentation/EDID/1280x1024.S new file mode 100644 index 0000000..bd9bef2 --- /dev/null +++ b/Documentation/EDID/1280x1024.S
@@ -0,0 +1,44 @@ +/* + 1280x1024.S: EDID data set for standard 1280x1024 60 Hz monitor + + Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 108000 /* kHz */ +#define XPIX 1280 +#define YPIX 1024 +#define XY_RATIO XY_RATIO_5_4 +#define XBLANK 408 +#define YBLANK 42 +#define XOFFSET 48 +#define XPULSE 112 +#define YOFFSET (63+1) +#define YPULSE (63+3) +#define DPI 72 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux SXGA" +/* No ESTABLISHED_TIMINGx_BITS */ +#define HSYNC_POL 1 +#define VSYNC_POL 1 +#define CRC 0xa0 + +#include "edid.S"
diff --git a/Documentation/EDID/1600x1200.S b/Documentation/EDID/1600x1200.S new file mode 100644 index 0000000..a45101c --- /dev/null +++ b/Documentation/EDID/1600x1200.S
@@ -0,0 +1,44 @@ +/* + 1600x1200.S: EDID data set for standard 1600x1200 60 Hz monitor + + Copyright (C) 2013 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 162000 /* kHz */ +#define XPIX 1600 +#define YPIX 1200 +#define XY_RATIO XY_RATIO_4_3 +#define XBLANK 560 +#define YBLANK 50 +#define XOFFSET 64 +#define XPULSE 192 +#define YOFFSET (63+1) +#define YPULSE (63+3) +#define DPI 72 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux UXGA" +/* No ESTABLISHED_TIMINGx_BITS */ +#define HSYNC_POL 1 +#define VSYNC_POL 1 +#define CRC 0x9d + +#include "edid.S"
diff --git a/Documentation/EDID/1680x1050.S b/Documentation/EDID/1680x1050.S new file mode 100644 index 0000000..b0d7c69 --- /dev/null +++ b/Documentation/EDID/1680x1050.S
@@ -0,0 +1,44 @@ +/* + 1680x1050.S: EDID data set for standard 1680x1050 60 Hz monitor + + Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 146250 /* kHz */ +#define XPIX 1680 +#define YPIX 1050 +#define XY_RATIO XY_RATIO_16_10 +#define XBLANK 560 +#define YBLANK 39 +#define XOFFSET 104 +#define XPULSE 176 +#define YOFFSET (63+3) +#define YPULSE (63+6) +#define DPI 96 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux WSXGA" +/* No ESTABLISHED_TIMINGx_BITS */ +#define HSYNC_POL 1 +#define VSYNC_POL 1 +#define CRC 0x26 + +#include "edid.S"
diff --git a/Documentation/EDID/1920x1080.S b/Documentation/EDID/1920x1080.S new file mode 100644 index 0000000..3084355 --- /dev/null +++ b/Documentation/EDID/1920x1080.S
@@ -0,0 +1,44 @@ +/* + 1920x1080.S: EDID data set for standard 1920x1080 60 Hz monitor + + Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 148500 /* kHz */ +#define XPIX 1920 +#define YPIX 1080 +#define XY_RATIO XY_RATIO_16_9 +#define XBLANK 280 +#define YBLANK 45 +#define XOFFSET 88 +#define XPULSE 44 +#define YOFFSET (63+4) +#define YPULSE (63+5) +#define DPI 96 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux FHD" +/* No ESTABLISHED_TIMINGx_BITS */ +#define HSYNC_POL 1 +#define VSYNC_POL 1 +#define CRC 0x05 + +#include "edid.S"
diff --git a/Documentation/EDID/800x600.S b/Documentation/EDID/800x600.S new file mode 100644 index 0000000..6644e26 --- /dev/null +++ b/Documentation/EDID/800x600.S
@@ -0,0 +1,41 @@ +/* + 800x600.S: EDID data set for standard 800x600 60 Hz monitor + + Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org> + Copyright (C) 2014 Linaro Limited + + 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. +*/ + +/* EDID */ +#define VERSION 1 +#define REVISION 3 + +/* Display */ +#define CLOCK 40000 /* kHz */ +#define XPIX 800 +#define YPIX 600 +#define XY_RATIO XY_RATIO_4_3 +#define XBLANK 256 +#define YBLANK 28 +#define XOFFSET 40 +#define XPULSE 128 +#define YOFFSET (63+1) +#define YPULSE (63+4) +#define DPI 72 +#define VFREQ 60 /* Hz */ +#define TIMING_NAME "Linux SVGA" +#define ESTABLISHED_TIMING1_BITS 0x01 /* Bit 0: 800x600 @ 60Hz */ +#define HSYNC_POL 1 +#define VSYNC_POL 1 +#define CRC 0xc2 + +#include "edid.S"
diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/HOWTO.txt new file mode 100644 index 0000000..835db33 --- /dev/null +++ b/Documentation/EDID/HOWTO.txt
@@ -0,0 +1,58 @@ +In the good old days when graphics parameters were configured explicitly +in a file called xorg.conf, even broken hardware could be managed. + +Today, with the advent of Kernel Mode Setting, a graphics board is +either correctly working because all components follow the standards - +or the computer is unusable, because the screen remains dark after +booting or it displays the wrong area. Cases when this happens are: +- The graphics board does not recognize the monitor. +- The graphics board is unable to detect any EDID data. +- The graphics board incorrectly forwards EDID data to the driver. +- The monitor sends no or bogus EDID data. +- A KVM sends its own EDID data instead of querying the connected monitor. +Adding the kernel parameter "nomodeset" helps in most cases, but causes +restrictions later on. + +As a remedy for such situations, the kernel configuration item +CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an +individually prepared or corrected EDID data set in the /lib/firmware +directory from where it is loaded via the firmware interface. The code +(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for +commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200, +1680x1050, 1920x1080) as binary blobs, but the kernel source tree does +not contain code to create these data. In order to elucidate the origin +of the built-in binary EDID blobs and to facilitate the creation of +individual data for a specific misbehaving monitor, commented sources +and a Makefile environment are given here. + +To create binary EDID and C source code files from the existing data +material, simply type "make". + +If you want to create your own EDID file, copy the file 1024x768.S, +replace the settings with your own data and add a new target to the +Makefile. Please note that the EDID data structure expects the timing +values in a different way as compared to the standard X11 format. + +X11: +HTimings: hdisp hsyncstart hsyncend htotal +VTimings: vdisp vsyncstart vsyncend vtotal + +EDID: +#define XPIX hdisp +#define XBLANK htotal-hdisp +#define XOFFSET hsyncstart-hdisp +#define XPULSE hsyncend-hsyncstart + +#define YPIX vdisp +#define YBLANK vtotal-vdisp +#define YOFFSET (63+(vsyncstart-vdisp)) +#define YPULSE (63+(vsyncend-vsyncstart)) + +The CRC value in the last line + #define CRC 0x55 +also is a bit tricky. After a first version of the binary data set is +created, it must be checked with the "edid-decode" utility which will +most probably complain about a wrong CRC. Fortunately, the utility also +displays the correct CRC which must then be inserted into the source +file. After the make procedure is repeated, the EDID data set is ready +to be used.
diff --git a/Documentation/EDID/Makefile b/Documentation/EDID/Makefile new file mode 100644 index 0000000..17763ca --- /dev/null +++ b/Documentation/EDID/Makefile
@@ -0,0 +1,26 @@ + +SOURCES := $(wildcard [0-9]*x[0-9]*.S) + +BIN := $(patsubst %.S, %.bin, $(SOURCES)) + +IHEX := $(patsubst %.S, %.bin.ihex, $(SOURCES)) + +CODE := $(patsubst %.S, %.c, $(SOURCES)) + +all: $(BIN) $(IHEX) $(CODE) + +clean: + @rm -f *.o *.bin.ihex *.bin *.c + +%.o: %.S + @cc -c $^ + +%.bin: %.o + @objcopy -Obinary $^ $@ + +%.bin.ihex: %.o + @objcopy -Oihex $^ $@ + @dos2unix $@ 2>/dev/null + +%.c: %.bin + @echo "{" >$@; hexdump -f hex $^ >>$@; echo "};" >>$@
diff --git a/Documentation/EDID/edid.S b/Documentation/EDID/edid.S new file mode 100644 index 0000000..7ac0327 --- /dev/null +++ b/Documentation/EDID/edid.S
@@ -0,0 +1,272 @@ +/* + edid.S: EDID data template + + Copyright (C) 2012 Carsten Emde <C.Emde@osadl.org> + + 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. +*/ + + +/* Manufacturer */ +#define MFG_LNX1 'L' +#define MFG_LNX2 'N' +#define MFG_LNX3 'X' +#define SERIAL 0 +#define YEAR 2012 +#define WEEK 5 + +/* EDID 1.3 standard definitions */ +#define XY_RATIO_16_10 0b00 +#define XY_RATIO_4_3 0b01 +#define XY_RATIO_5_4 0b10 +#define XY_RATIO_16_9 0b11 + +/* Provide defaults for the timing bits */ +#ifndef ESTABLISHED_TIMING1_BITS +#define ESTABLISHED_TIMING1_BITS 0x00 +#endif +#ifndef ESTABLISHED_TIMING2_BITS +#define ESTABLISHED_TIMING2_BITS 0x00 +#endif +#ifndef ESTABLISHED_TIMING3_BITS +#define ESTABLISHED_TIMING3_BITS 0x00 +#endif + +#define mfgname2id(v1,v2,v3) \ + ((((v1-'@')&0x1f)<<10)+(((v2-'@')&0x1f)<<5)+((v3-'@')&0x1f)) +#define swap16(v1) ((v1>>8)+((v1&0xff)<<8)) +#define msbs2(v1,v2) ((((v1>>8)&0x0f)<<4)+((v2>>8)&0x0f)) +#define msbs4(v1,v2,v3,v4) \ + (((v1&0x03)>>2)+((v2&0x03)>>4)+((v3&0x03)>>6)+((v4&0x03)>>8)) +#define pixdpi2mm(pix,dpi) ((pix*25)/dpi) +#define xsize pixdpi2mm(XPIX,DPI) +#define ysize pixdpi2mm(YPIX,DPI) + + .data + +/* Fixed header pattern */ +header: .byte 0x00,0xff,0xff,0xff,0xff,0xff,0xff,0x00 + +mfg_id: .word swap16(mfgname2id(MFG_LNX1, MFG_LNX2, MFG_LNX3)) + +prod_code: .word 0 + +/* Serial number. 32 bits, little endian. */ +serial_number: .long SERIAL + +/* Week of manufacture */ +week: .byte WEEK + +/* Year of manufacture, less 1990. (1990-2245) + If week=255, it is the model year instead */ +year: .byte YEAR-1990 + +version: .byte VERSION /* EDID version, usually 1 (for 1.3) */ +revision: .byte REVISION /* EDID revision, usually 3 (for 1.3) */ + +/* If Bit 7=1 Digital input. If set, the following bit definitions apply: + Bits 6-1 Reserved, must be 0 + Bit 0 Signal is compatible with VESA DFP 1.x TMDS CRGB, + 1 pixel per clock, up to 8 bits per color, MSB aligned, + If Bit 7=0 Analog input. If clear, the following bit definitions apply: + Bits 6-5 Video white and sync levels, relative to blank + 00=+0.7/-0.3 V; 01=+0.714/-0.286 V; + 10=+1.0/-0.4 V; 11=+0.7/0 V + Bit 4 Blank-to-black setup (pedestal) expected + Bit 3 Separate sync supported + Bit 2 Composite sync (on HSync) supported + Bit 1 Sync on green supported + Bit 0 VSync pulse must be serrated when somposite or + sync-on-green is used. */ +video_parms: .byte 0x6d + +/* Maximum horizontal image size, in centimetres + (max 292 cm/115 in at 16:9 aspect ratio) */ +max_hor_size: .byte xsize/10 + +/* Maximum vertical image size, in centimetres. + If either byte is 0, undefined (e.g. projector) */ +max_vert_size: .byte ysize/10 + +/* Display gamma, minus 1, times 100 (range 1.00-3.5 */ +gamma: .byte 120 + +/* Bit 7 DPMS standby supported + Bit 6 DPMS suspend supported + Bit 5 DPMS active-off supported + Bits 4-3 Display type: 00=monochrome; 01=RGB colour; + 10=non-RGB multicolour; 11=undefined + Bit 2 Standard sRGB colour space. Bytes 25-34 must contain + sRGB standard values. + Bit 1 Preferred timing mode specified in descriptor block 1. + Bit 0 GTF supported with default parameter values. */ +dsp_features: .byte 0xea + +/* Chromaticity coordinates. */ +/* Red and green least-significant bits + Bits 7-6 Red x value least-significant 2 bits + Bits 5-4 Red y value least-significant 2 bits + Bits 3-2 Green x value lst-significant 2 bits + Bits 1-0 Green y value least-significant 2 bits */ +red_green_lsb: .byte 0x5e + +/* Blue and white least-significant 2 bits */ +blue_white_lsb: .byte 0xc0 + +/* Red x value most significant 8 bits. + 0-255 encodes 0-0.996 (255/256); 0-0.999 (1023/1024) with lsbits */ +red_x_msb: .byte 0xa4 + +/* Red y value most significant 8 bits */ +red_y_msb: .byte 0x59 + +/* Green x and y value most significant 8 bits */ +green_x_y_msb: .byte 0x4a,0x98 + +/* Blue x and y value most significant 8 bits */ +blue_x_y_msb: .byte 0x25,0x20 + +/* Default white point x and y value most significant 8 bits */ +white_x_y_msb: .byte 0x50,0x54 + +/* Established timings */ +/* Bit 7 720x400 @ 70 Hz + Bit 6 720x400 @ 88 Hz + Bit 5 640x480 @ 60 Hz + Bit 4 640x480 @ 67 Hz + Bit 3 640x480 @ 72 Hz + Bit 2 640x480 @ 75 Hz + Bit 1 800x600 @ 56 Hz + Bit 0 800x600 @ 60 Hz */ +estbl_timing1: .byte ESTABLISHED_TIMING1_BITS + +/* Bit 7 800x600 @ 72 Hz + Bit 6 800x600 @ 75 Hz + Bit 5 832x624 @ 75 Hz + Bit 4 1024x768 @ 87 Hz, interlaced (1024x768) + Bit 3 1024x768 @ 60 Hz + Bit 2 1024x768 @ 72 Hz + Bit 1 1024x768 @ 75 Hz + Bit 0 1280x1024 @ 75 Hz */ +estbl_timing2: .byte ESTABLISHED_TIMING2_BITS + +/* Bit 7 1152x870 @ 75 Hz (Apple Macintosh II) + Bits 6-0 Other manufacturer-specific display mod */ +estbl_timing3: .byte ESTABLISHED_TIMING3_BITS + +/* Standard timing */ +/* X resolution, less 31, divided by 8 (256-2288 pixels) */ +std_xres: .byte (XPIX/8)-31 +/* Y resolution, X:Y pixel ratio + Bits 7-6 X:Y pixel ratio: 00=16:10; 01=4:3; 10=5:4; 11=16:9. + Bits 5-0 Vertical frequency, less 60 (60-123 Hz) */ +std_vres: .byte (XY_RATIO<<6)+VFREQ-60 + .fill 7,2,0x0101 /* Unused */ + +descriptor1: +/* Pixel clock in 10 kHz units. (0.-655.35 MHz, little-endian) */ +clock: .word CLOCK/10 + +/* Horizontal active pixels 8 lsbits (0-4095) */ +x_act_lsb: .byte XPIX&0xff +/* Horizontal blanking pixels 8 lsbits (0-4095) + End of active to start of next active. */ +x_blk_lsb: .byte XBLANK&0xff +/* Bits 7-4 Horizontal active pixels 4 msbits + Bits 3-0 Horizontal blanking pixels 4 msbits */ +x_msbs: .byte msbs2(XPIX,XBLANK) + +/* Vertical active lines 8 lsbits (0-4095) */ +y_act_lsb: .byte YPIX&0xff +/* Vertical blanking lines 8 lsbits (0-4095) */ +y_blk_lsb: .byte YBLANK&0xff +/* Bits 7-4 Vertical active lines 4 msbits + Bits 3-0 Vertical blanking lines 4 msbits */ +y_msbs: .byte msbs2(YPIX,YBLANK) + +/* Horizontal sync offset pixels 8 lsbits (0-1023) From blanking start */ +x_snc_off_lsb: .byte XOFFSET&0xff +/* Horizontal sync pulse width pixels 8 lsbits (0-1023) */ +x_snc_pls_lsb: .byte XPULSE&0xff +/* Bits 7-4 Vertical sync offset lines 4 lsbits -63) + Bits 3-0 Vertical sync pulse width lines 4 lsbits -63) */ +y_snc_lsb: .byte ((YOFFSET-63)<<4)+(YPULSE-63) +/* Bits 7-6 Horizontal sync offset pixels 2 msbits + Bits 5-4 Horizontal sync pulse width pixels 2 msbits + Bits 3-2 Vertical sync offset lines 2 msbits + Bits 1-0 Vertical sync pulse width lines 2 msbits */ +xy_snc_msbs: .byte msbs4(XOFFSET,XPULSE,YOFFSET,YPULSE) + +/* Horizontal display size, mm, 8 lsbits (0-4095 mm, 161 in) */ +x_dsp_size: .byte xsize&0xff + +/* Vertical display size, mm, 8 lsbits (0-4095 mm, 161 in) */ +y_dsp_size: .byte ysize&0xff + +/* Bits 7-4 Horizontal display size, mm, 4 msbits + Bits 3-0 Vertical display size, mm, 4 msbits */ +dsp_size_mbsb: .byte msbs2(xsize,ysize) + +/* Horizontal border pixels (each side; total is twice this) */ +x_border: .byte 0 +/* Vertical border lines (each side; total is twice this) */ +y_border: .byte 0 + +/* Bit 7 Interlaced + Bits 6-5 Stereo mode: 00=No stereo; other values depend on bit 0: + Bit 0=0: 01=Field sequential, sync=1 during right; 10=similar, + sync=1 during left; 11=4-way interleaved stereo + Bit 0=1 2-way interleaved stereo: 01=Right image on even lines; + 10=Left image on even lines; 11=side-by-side + Bits 4-3 Sync type: 00=Analog composite; 01=Bipolar analog composite; + 10=Digital composite (on HSync); 11=Digital separate + Bit 2 If digital separate: Vertical sync polarity (1=positive) + Other types: VSync serrated (HSync during VSync) + Bit 1 If analog sync: Sync on all 3 RGB lines (else green only) + Digital: HSync polarity (1=positive) + Bit 0 2-way line-interleaved stereo, if bits 4-3 are not 00. */ +features: .byte 0x18+(VSYNC_POL<<2)+(HSYNC_POL<<1) + +descriptor2: .byte 0,0 /* Not a detailed timing descriptor */ + .byte 0 /* Must be zero */ + .byte 0xff /* Descriptor is monitor serial number (text) */ + .byte 0 /* Must be zero */ +start1: .ascii "Linux #0" +end1: .byte 0x0a /* End marker */ + .fill 12-(end1-start1), 1, 0x20 /* Padded spaces */ +descriptor3: .byte 0,0 /* Not a detailed timing descriptor */ + .byte 0 /* Must be zero */ + .byte 0xfd /* Descriptor is monitor range limits */ + .byte 0 /* Must be zero */ +start2: .byte VFREQ-1 /* Minimum vertical field rate (1-255 Hz) */ + .byte VFREQ+1 /* Maximum vertical field rate (1-255 Hz) */ + .byte (CLOCK/(XPIX+XBLANK))-1 /* Minimum horizontal line rate + (1-255 kHz) */ + .byte (CLOCK/(XPIX+XBLANK))+1 /* Maximum horizontal line rate + (1-255 kHz) */ + .byte (CLOCK/10000)+1 /* Maximum pixel clock rate, rounded up + to 10 MHz multiple (10-2550 MHz) */ + .byte 0 /* No extended timing information type */ +end2: .byte 0x0a /* End marker */ + .fill 12-(end2-start2), 1, 0x20 /* Padded spaces */ +descriptor4: .byte 0,0 /* Not a detailed timing descriptor */ + .byte 0 /* Must be zero */ + .byte 0xfc /* Descriptor is text */ + .byte 0 /* Must be zero */ +start3: .ascii TIMING_NAME +end3: .byte 0x0a /* End marker */ + .fill 12-(end3-start3), 1, 0x20 /* Padded spaces */ +extensions: .byte 0 /* Number of extensions to follow */ +checksum: .byte CRC /* Sum of all bytes must be 0 */
diff --git a/Documentation/EDID/hex b/Documentation/EDID/hex new file mode 100644 index 0000000..8873ebb --- /dev/null +++ b/Documentation/EDID/hex
@@ -0,0 +1 @@ +"\t" 8/1 "0x%02x, " "\n"
diff --git a/Documentation/HOWTO b/Documentation/HOWTO new file mode 100644 index 0000000..5f04234 --- /dev/null +++ b/Documentation/HOWTO
@@ -0,0 +1,652 @@ +HOWTO do Linux kernel development +================================= + +This is the be-all, end-all document on this topic. It contains +instructions on how to become a Linux kernel developer and how to learn +to work with the Linux kernel development community. It tries to not +contain anything related to the technical aspects of kernel programming, +but will help point you in the right direction for that. + +If anything in this document becomes out of date, please send in patches +to the maintainer of this file, who is listed at the bottom of the +document. + + +Introduction +------------ + +So, you want to learn how to become a Linux kernel developer? Or you +have been told by your manager, "Go write a Linux driver for this +device." This document's goal is to teach you everything you need to +know to achieve this by describing the process you need to go through, +and hints on how to work with the community. It will also try to +explain some of the reasons why the community works like it does. + +The kernel is written mostly in C, with some architecture-dependent +parts written in assembly. A good understanding of C is required for +kernel development. Assembly (any architecture) is not required unless +you plan to do low-level development for that architecture. Though they +are not a good substitute for a solid C education and/or years of +experience, the following books are good for, if anything, reference: + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + +The kernel is written using GNU C and the GNU toolchain. While it +adheres to the ISO C89 standard, it uses a number of extensions that are +not featured in the standard. The kernel is a freestanding C +environment, with no reliance on the standard C library, so some +portions of the C standard are not supported. Arbitrary long long +divisions and floating point are not allowed. It can sometimes be +difficult to understand the assumptions the kernel has on the toolchain +and the extensions that it uses, and unfortunately there is no +definitive reference for them. Please check the gcc info pages (`info +gcc`) for some information on them. + +Please remember that you are trying to learn how to work with the +existing development community. It is a diverse group of people, with +high standards for coding, style and procedure. These standards have +been created over time based on what they have found to work best for +such a large and geographically dispersed team. Try to learn as much as +possible about these standards ahead of time, as they are well +documented; do not expect people to adapt to you or your company's way +of doing things. + + +Legal Issues +------------ + +The Linux kernel source code is released under the GPL. Please see the +file, COPYING, in the main directory of the source tree, for details on +the license. If you have further questions about the license, please +contact a lawyer, and do not ask on the Linux kernel mailing list. The +people on the mailing lists are not lawyers, and you should not rely on +their statements on legal matters. + +For common questions and answers about the GPL, please see: + + https://www.gnu.org/licenses/gpl-faq.html + + +Documentation +------------- + +The Linux kernel source tree has a large range of documents that are +invaluable for learning how to interact with the kernel community. When +new features are added to the kernel, it is recommended that new +documentation files are also added which explain how to use the feature. +When a kernel change causes the interface that the kernel exposes to +userspace to change, it is recommended that you send the information or +a patch to the manual pages explaining the change to the manual pages +maintainer at mtk.manpages@gmail.com, and CC the list +linux-api@vger.kernel.org. + +Here is a list of files that are in the kernel source tree that are +required reading: + + README + This file gives a short background on the Linux kernel and describes + what is necessary to do to configure and build the kernel. People + who are new to the kernel should start here. + + :ref:`Documentation/Changes <changes>` + This file gives a list of the minimum levels of various software + packages that are necessary to build and run the kernel + successfully. + + :ref:`Documentation/CodingStyle <codingstyle>` + This describes the Linux kernel coding style, and some of the + rationale behind it. All new code is expected to follow the + guidelines in this document. Most maintainers will only accept + patches if these rules are followed, and many people will only + review code if it is in the proper style. + + :ref:`Documentation/SubmittingPatches <submittingpatches>` and :ref:`Documentation/SubmittingDrivers <submittingdrivers>` + These files describe in explicit detail how to successfully create + and send a patch, including (but not limited to): + + - Email contents + - Email format + - Who to send it to + + Following these rules will not guarantee success (as all patches are + subject to scrutiny for content and style), but not following them + will almost always prevent it. + + Other excellent descriptions of how to create patches properly are: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>` + This file describes the rationale behind the conscious decision to + not have a stable API within the kernel, including things like: + + - Subsystem shim-layers (for compatibility?) + - Driver portability between Operating Systems. + - Mitigating rapid change within the kernel source tree (or + preventing rapid change) + + This document is crucial for understanding the Linux development + philosophy and is very important for people moving to Linux from + development on other Operating Systems. + + :ref:`Documentation/SecurityBugs <securitybugs>` + If you feel you have found a security problem in the Linux kernel, + please follow the steps in this document to help notify the kernel + developers, and help solve the issue. + + :ref:`Documentation/ManagementStyle <managementstyle>` + This document describes how Linux kernel maintainers operate and the + shared ethos behind their methodologies. This is important reading + for anyone new to kernel development (or anyone simply curious about + it), as it resolves a lot of common misconceptions and confusion + about the unique behavior of kernel maintainers. + + :ref:`Documentation/stable_kernel_rules.txt <stable_kernel_rules>` + This file describes the rules on how the stable kernel releases + happen, and what to do if you want to get a change into one of these + releases. + + :ref:`Documentation/kernel-docs.txt <kernel_docs>` + A list of external documentation that pertains to kernel + development. Please consult this list if you do not find what you + are looking for within the in-kernel documentation. + + :ref:`Documentation/applying-patches.txt <applying_patches>` + A good introduction describing exactly what a patch is and how to + apply it to the different development branches of the kernel. + +The kernel also has a large number of documents that can be +automatically generated from the source code itself or from +ReStructuredText markups (ReST), like this one. This includes a +full description of the in-kernel API, and rules on how to handle +locking properly. + +All such documents can be generated as PDF or HTML by running:: + + make pdfdocs + make htmldocs + +respectively from the main kernel source directory. + +The documents that uses ReST markup will be generated at Documentation/output. +They can also be generated on LaTeX and ePub formats with:: + + make latexdocs + make epubdocs + +Currently, there are some documents written on DocBook that are in +the process of conversion to ReST. Such documents will be created in the +Documentation/DocBook/ directory and can be generated also as +Postscript or man pages by running:: + + make psdocs + make mandocs + +Becoming A Kernel Developer +--------------------------- + +If you do not know anything about Linux kernel development, you should +look at the Linux KernelNewbies project: + + https://kernelnewbies.org + +It consists of a helpful mailing list where you can ask almost any type +of basic kernel development question (make sure to search the archives +first, before asking something that has already been answered in the +past.) It also has an IRC channel that you can use to ask questions in +real-time, and a lot of helpful documentation that is useful for +learning about Linux kernel development. + +The website has basic information about code organization, subsystems, +and current projects (both in-tree and out-of-tree). It also describes +some basic logistical information, like how to compile a kernel and +apply a patch. + +If you do not know where you want to start, but you want to look for +some task to start doing to join into the kernel development community, +go to the Linux Kernel Janitor's project: + + https://kernelnewbies.org/KernelJanitors + +It is a great place to start. It describes a list of relatively simple +problems that need to be cleaned up and fixed within the Linux kernel +source tree. Working with the developers in charge of this project, you +will learn the basics of getting your patch into the Linux kernel tree, +and possibly be pointed in the direction of what to go work on next, if +you do not already have an idea. + +If you already have a chunk of code that you want to put into the kernel +tree, but need some help getting it in the proper form, the +kernel-mentors project was created to help you out with this. It is a +mailing list, and can be found at: + + https://selenic.com/mailman/listinfo/kernel-mentors + +Before making any actual modifications to the Linux kernel code, it is +imperative to understand how the code in question works. For this +purpose, nothing is better than reading through it directly (most tricky +bits are commented well), perhaps even with the help of specialized +tools. One such tool that is particularly recommended is the Linux +Cross-Reference project, which is able to present source code in a +self-referential, indexed webpage format. An excellent up-to-date +repository of the kernel code may be found at: + + http://lxr.free-electrons.com/ + + +The development process +----------------------- + +Linux kernel development process currently consists of a few different +main kernel "branches" and lots of different subsystem-specific kernel +branches. These different branches are: + + - main 4.x kernel tree + - 4.x.y -stable kernel tree + - 4.x -git kernel patches + - subsystem specific kernel trees and patches + - the 4.x -next kernel tree for integration tests + +4.x kernel tree +----------------- +4.x kernels are maintained by Linus Torvalds, and can be found on +https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development +process is as follows: + + - As soon as a new kernel is released a two weeks window is open, + during this period of time maintainers can submit big diffs to + Linus, usually the patches that have already been included in the + -next kernel for a few weeks. The preferred way to submit big changes + is using git (the kernel's source management tool, more information + can be found at https://git-scm.com/) but plain patches are also just + fine. + - After two weeks a -rc1 kernel is released it is now possible to push + only patches that do not include new features that could affect the + stability of the whole kernel. Please note that a whole new driver + (or filesystem) might be accepted after -rc1 because there is no + risk of causing regressions with such a change as long as the change + is self-contained and does not affect areas outside of the code that + is being added. git can be used to send patches to Linus after -rc1 + is released, but the patches need to also be sent to a public + mailing list for review. + - A new -rc is released whenever Linus deems the current git tree to + be in a reasonably sane state adequate for testing. The goal is to + release a new -rc kernel every week. + - Process continues until the kernel is considered "ready", the + process should last around 6 weeks. + +It is worth mentioning what Andrew Morton wrote on the linux-kernel +mailing list about kernel releases: + + *"Nobody knows when a kernel will be released, because it's + released according to perceived bug status, not according to a + preconceived timeline."* + +4.x.y -stable kernel tree +------------------------- +Kernels with 3-part versions are -stable kernels. They contain +relatively small and critical fixes for security problems or significant +regressions discovered in a given 4.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 4.x.y kernel is available, then the highest numbered 4.x +kernel is the current stable kernel. + +4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and +are released as needs dictate. The normal release period is approximately +two weeks, but it can be longer if there are no pressing problems. A +security-related problem, instead, can cause a release to happen almost +instantly. + +The file Documentation/stable_kernel_rules.txt in the kernel tree +documents what kinds of changes are acceptable for the -stable tree, and +how the release process works. + +4.x -git patches +---------------- +These are daily snapshots of Linus' kernel tree which are managed in a +git repository (hence the name.) These patches are usually released +daily and represent the current state of Linus' tree. They are more +experimental than -rc kernels since they are generated automatically +without even a cursory glance to see if they are sane. + +Subsystem Specific kernel trees and patches +------------------------------------------- +The maintainers of the various kernel subsystems --- and also many +kernel subsystem developers --- expose their current state of +development in source repositories. That way, others can see what is +happening in the different areas of the kernel. In areas where +development is rapid, a developer may be asked to base his submissions +onto such a subsystem kernel tree so that conflicts between the +submission and other already ongoing work are avoided. + +Most of these repositories are git trees, but there are also other SCMs +in use, or patch queues being published as quilt series. Addresses of +these subsystem repositories are listed in the MAINTAINERS file. Many +of them can be browsed at https://git.kernel.org/. + +Before a proposed patch is committed to such a subsystem tree, it is +subject to review which primarily happens on mailing lists (see the +respective section below). For several kernel subsystems, this review +process is tracked with the tool patchwork. Patchwork offers a web +interface which shows patch postings, any comments on a patch or +revisions to it, and maintainers can mark patches as under review, +accepted, or rejected. Most of these patchwork sites are listed at +https://patchwork.kernel.org/. + +4.x -next kernel tree for integration tests +------------------------------------------- +Before updates from subsystem trees are merged into the mainline 4.x +tree, they need to be integration-tested. For this purpose, a special +testing repository exists into which virtually all subsystem trees are +pulled on an almost daily basis: + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +This way, the -next kernel gives a summary outlook onto what will be +expected to go into the mainline kernel at the next merge period. +Adventurous testers are very welcome to runtime-test the -next kernel. + + +Bug Reporting +------------- + +https://bugzilla.kernel.org is where the Linux kernel developers track kernel +bugs. Users are encouraged to report all bugs that they find in this +tool. For details on how to use the kernel bugzilla, please see: + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +The file REPORTING-BUGS in the main kernel source directory has a good +template for how to report a possible kernel bug, and details what kind +of information is needed by the kernel developers to help track down the +problem. + + +Managing bug reports +-------------------- + +One of the best ways to put into practice your hacking skills is by fixing +bugs reported by other people. Not only you will help to make the kernel +more stable, you'll learn to fix real world problems and you will improve +your skills, and other developers will be aware of your presence. Fixing +bugs is one of the best ways to get merits among other developers, because +not many people like wasting time fixing other people's bugs. + +To work in the already reported bug reports, go to https://bugzilla.kernel.org. +If you want to be advised of the future bug reports, you can subscribe to the +bugme-new mailing list (only new bug reports are mailed here) or to the +bugme-janitor mailing list (every change in the bugzilla is mailed here) + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + + + +Mailing lists +------------- + +As some of the above documents describe, the majority of the core kernel +developers participate on the Linux Kernel Mailing list. Details on how +to subscribe and unsubscribe from the list can be found at: + + http://vger.kernel.org/vger-lists.html#linux-kernel + +There are archives of the mailing list on the web in many different +places. Use a search engine to find these archives. For example: + + http://dir.gmane.org/gmane.linux.kernel + +It is highly recommended that you search the archives about the topic +you want to bring up, before you post it to the list. A lot of things +already discussed in detail are only recorded at the mailing list +archives. + +Most of the individual kernel subsystems also have their own separate +mailing list where they do their development efforts. See the +MAINTAINERS file for a list of what these lists are for the different +groups. + +Many of the lists are hosted on kernel.org. Information on them can be +found at: + + http://vger.kernel.org/vger-lists.html + +Please remember to follow good behavioral habits when using the lists. +Though a bit cheesy, the following URL has some simple guidelines for +interacting with the list (or any list): + + http://www.albion.com/netiquette/ + +If multiple people respond to your mail, the CC: list of recipients may +get pretty large. Don't remove anybody from the CC: list without a good +reason, or don't reply only to the list address. Get used to receiving the +mail twice, one from the sender and the one from the list, and don't try +to tune that by adding fancy mail-headers, people will not like it. + +Remember to keep the context and the attribution of your replies intact, +keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and +add your statements between the individual quoted sections instead of +writing at the top of the mail. + +If you add patches to your mail, make sure they are plain readable text +as stated in Documentation/SubmittingPatches. +Kernel developers don't want to deal with +attachments or compressed patches; they may want to comment on +individual lines of your patch, which works only that way. Make sure you +use a mail program that does not mangle spaces and tab characters. A +good first test is to send the mail to yourself and try to apply your +own patch by yourself. If that doesn't work, get your mail program fixed +or change it until it works. + +Above all, please remember to show respect to other subscribers. + + +Working with the community +-------------------------- + +The goal of the kernel community is to provide the best possible kernel +there is. When you submit a patch for acceptance, it will be reviewed +on its technical merits and those alone. So, what should you be +expecting? + + - criticism + - comments + - requests for change + - requests for justification + - silence + +Remember, this is part of getting your patch into the kernel. You have +to be able to take criticism and comments about your patches, evaluate +them at a technical level and either rework your patches or provide +clear and concise reasoning as to why those changes should not be made. +If there are no responses to your posting, wait a few days and try +again, sometimes things get lost in the huge volume. + +What should you not do? + + - expect your patch to be accepted without question + - become defensive + - ignore comments + - resubmit the patch without making any of the requested changes + +In a community that is looking for the best technical solution possible, +there will always be differing opinions on how beneficial a patch is. +You have to be cooperative, and willing to adapt your idea to fit within +the kernel. Or at least be willing to prove your idea is worth it. +Remember, being wrong is acceptable as long as you are willing to work +toward a solution that is right. + +It is normal that the answers to your first patch might simply be a list +of a dozen things you should correct. This does **not** imply that your +patch will not be accepted, and it is **not** meant against you +personally. Simply correct all issues raised against your patch and +resend it. + + +Differences between the kernel community and corporate structures +----------------------------------------------------------------- + +The kernel community works differently than most traditional corporate +development environments. Here are a list of things that you can try to +do to avoid problems: + + Good things to say regarding your proposed changes: + + - "This solves multiple problems." + - "This deletes 2000 lines of code." + - "Here is a patch that explains what I am trying to describe." + - "I tested it on 5 different architectures..." + - "Here is a series of small patches that..." + - "This increases performance on typical machines..." + + Bad things you should avoid saying: + + - "We did it this way in AIX/ptx/Solaris, so therefore it must be + good..." + - "I've being doing this for 20 years, so..." + - "This is required for my company to make money" + - "This is for our Enterprise product line." + - "Here is my 1000 page design document that describes my idea" + - "I've been working on this for 6 months..." + - "Here's a 5000 line patch that..." + - "I rewrote all of the current mess, and here it is..." + - "I have a deadline, and this patch needs to be applied now." + +Another way the kernel community is different than most traditional +software engineering work environments is the faceless nature of +interaction. One benefit of using email and irc as the primary forms of +communication is the lack of discrimination based on gender or race. +The Linux kernel work environment is accepting of women and minorities +because all you are is an email address. The international aspect also +helps to level the playing field because you can't guess gender based on +a person's name. A man may be named Andrea and a woman may be named Pat. +Most women who have worked in the Linux kernel and have expressed an +opinion have had positive experiences. + +The language barrier can cause problems for some people who are not +comfortable with English. A good grasp of the language can be needed in +order to get ideas across properly on mailing lists, so it is +recommended that you check your emails to make sure they make sense in +English before sending them. + + +Break up your changes +--------------------- + +The Linux kernel community does not gladly accept large chunks of code +dropped on it all at once. The changes need to be properly introduced, +discussed, and broken up into tiny, individual portions. This is almost +the exact opposite of what companies are used to doing. Your proposal +should also be introduced very early in the development process, so that +you can receive feedback on what you are doing. It also lets the +community feel that you are working with them, and not simply using them +as a dumping ground for your feature. However, don't send 50 emails at +one time to a mailing list, your patch series should be smaller than +that almost all of the time. + +The reasons for breaking things up are the following: + +1) Small patches increase the likelihood that your patches will be + applied, since they don't take much time or effort to verify for + correctness. A 5 line patch can be applied by a maintainer with + barely a second glance. However, a 500 line patch may take hours to + review for correctness (the time it takes is exponentially + proportional to the size of the patch, or something). + + Small patches also make it very easy to debug when something goes + wrong. It's much easier to back out patches one by one than it is + to dissect a very large patch after it's been applied (and broken + something). + +2) It's important not only to send small patches, but also to rewrite + and simplify (or simply re-order) patches before submitting them. + +Here is an analogy from kernel developer Al Viro: + + *"Think of a teacher grading homework from a math student. The + teacher does not want to see the student's trials and errors + before they came up with the solution. They want to see the + cleanest, most elegant answer. A good student knows this, and + would never submit her intermediate work before the final + solution.* + + *The same is true of kernel development. The maintainers and + reviewers do not want to see the thought process behind the + solution to the problem one is solving. They want to see a + simple and elegant solution."* + +It may be challenging to keep the balance between presenting an elegant +solution and working together with the community and discussing your +unfinished work. Therefore it is good to get early in the process to +get feedback to improve your work, but also keep your changes in small +chunks that they may get already accepted, even when your whole task is +not ready for inclusion now. + +Also realize that it is not acceptable to send patches for inclusion +that are unfinished and will be "fixed up later." + + +Justify your change +------------------- + +Along with breaking up your patches, it is very important for you to let +the Linux community know why they should add this change. New features +must be justified as being needed and useful. + + +Document your change +-------------------- + +When sending in your patches, pay special attention to what you say in +the text in your email. This information will become the ChangeLog +information for the patch, and will be preserved for everyone to see for +all time. It should describe the patch completely, containing: + + - why the change is necessary + - the overall design approach in the patch + - implementation details + - testing results + +For more details on what this should all look like, please see the +ChangeLog section of the document: + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + + +All of these things are sometimes very hard to do. It can take years to +perfect these practices (if at all). It's a continuous process of +improvement that requires a lot of patience and determination. But +don't give up, it's possible. Many have done it before, and each had to +start exactly where you are now. + + + + +---------- + +Thanks to Paolo Ciarrocchi who allowed the "Development Process" +(https://lwn.net/Articles/94386/) section +to be based on text he had written, and to Randy Dunlap and Gerrit +Huizenga for some of the list of things you should and should not say. +Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi +Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for +their review, comments, and contributions. Without their help, this +document would not have been possible. + + + +Maintainer: Greg Kroah-Hartman <greg@kroah.com>
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt new file mode 100644 index 0000000..c0d8788 --- /dev/null +++ b/Documentation/IPMI.txt
@@ -0,0 +1,725 @@ + + The Linux IPMI Driver + --------------------- + Corey Minyard + <minyard@mvista.com> + <minyard@acm.org> + +The Intelligent Platform Management Interface, or IPMI, is a +standard for controlling intelligent devices that monitor a system. +It provides for dynamic discovery of sensors in the system and the +ability to monitor the sensors and be informed when the sensor's +values change or go outside certain boundaries. It also has a +standardized database for field-replaceable units (FRUs) and a watchdog +timer. + +To use this, you need an interface to an IPMI controller in your +system (called a Baseboard Management Controller, or BMC) and +management software that can use the IPMI system. + +This document describes how to use the IPMI driver for Linux. If you +are not familiar with IPMI itself, see the web site at +http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big +subject and I can't cover it all here! + +Configuration +------------- + +The Linux IPMI driver is modular, which means you have to pick several +things to have it work right depending on your hardware. Most of +these are available in the 'Character Devices' menu then the IPMI +menu. + +No matter what, you must pick 'IPMI top-level message handler' to use +IPMI. What you do beyond that depends on your needs and hardware. + +The message handler does not provide any user-level interfaces. +Kernel code (like the watchdog) can still use it. If you need access +from userland, you need to select 'Device interface for IPMI' if you +want access through a device driver. + +The driver interface depends on your hardware. If your system +properly provides the SMBIOS info for IPMI, the driver will detect it +and just work. If you have a board with a standard interface (These +will generally be either "KCS", "SMIC", or "BT", consult your hardware +manual), choose the 'IPMI SI handler' option. A driver also exists +for direct I2C access to the IPMI management controller. Some boards +support this, but it is unknown if it will work on every board. For +this, choose 'IPMI SMBus handler', but be ready to try to do some +figuring to see if it will work on your system if the SMBIOS/APCI +information is wrong or not present. It is fairly safe to have both +these enabled and let the drivers auto-detect what is present. + +You should generally enable ACPI on your system, as systems with IPMI +can have ACPI tables describing them. + +If you have a standard interface and the board manufacturer has done +their job correctly, the IPMI controller should be automatically +detected (via ACPI or SMBIOS tables) and should just work. Sadly, +many boards do not have this information. The driver attempts +standard defaults, but they may not work. If you fall into this +situation, you need to read the section below named 'The SI Driver' or +"The SMBus Driver" on how to hand-configure your system. + +IPMI defines a standard watchdog timer. You can enable this with the +'IPMI Watchdog Timer' config option. If you compile the driver into +the kernel, then via a kernel command-line option you can have the +watchdog timer start as soon as it initializes. It also have a lot +of other options, see the 'Watchdog' section below for more details. +Note that you can also have the watchdog continue to run if it is +closed (by default it is disabled on close). Go into the 'Watchdog +Cards' menu, enable 'Watchdog Timer Support', and enable the option +'Disable watchdog shutdown on close'. + +IPMI systems can often be powered off using IPMI commands. Select +'IPMI Poweroff' to do this. The driver will auto-detect if the system +can be powered off by IPMI. It is safe to enable this even if your +system doesn't support this option. This works on ATCA systems, the +Radisys CPI1 card, and any IPMI system that supports standard chassis +management commands. + +If you want the driver to put an event into the event log on a panic, +enable the 'Generate a panic event to all BMCs on a panic' option. If +you want the whole panic string put into the event log using OEM +events, enable the 'Generate OEM events containing the panic string' +option. + +Basic Design +------------ + +The Linux IPMI driver is designed to be very modular and flexible, you +only need to take the pieces you need and you can use it in many +different ways. Because of that, it's broken into many chunks of +code. These chunks (by module name) are: + +ipmi_msghandler - This is the central piece of software for the IPMI +system. It handles all messages, message timing, and responses. The +IPMI users tie into this, and the IPMI physical interfaces (called +System Management Interfaces, or SMIs) also tie in here. This +provides the kernelland interface for IPMI, but does not provide an +interface for use by application processes. + +ipmi_devintf - This provides a userland IOCTL interface for the IPMI +driver, each open file for this device ties in to the message handler +as an IPMI user. + +ipmi_si - A driver for various system interfaces. This supports KCS, +SMIC, and BT interfaces. Unless you have an SMBus interface or your +own custom interface, you probably need to use this. + +ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the +I2C kernel driver's SMBus interfaces to send and receive IPMI messages +over the SMBus. + +ipmi_watchdog - IPMI requires systems to have a very capable watchdog +timer. This driver implements the standard Linux watchdog timer +interface on top of the IPMI message handler. + +ipmi_poweroff - Some systems support the ability to be turned off via +IPMI commands. + +These are all individually selectable via configuration options. + +Note that the KCS-only interface has been removed. The af_ipmi driver +is no longer supported and has been removed because it was impossible +to do 32 bit emulation on 64-bit kernels with it. + +Much documentation for the interface is in the include files. The +IPMI include files are: + +net/af_ipmi.h - Contains the socket interface. + +linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI. + +linux/ipmi_smi.h - Contains the interface for system management interfaces +(things that interface to IPMI controllers) to use. + +linux/ipmi_msgdefs.h - General definitions for base IPMI messaging. + + +Addressing +---------- + +The IPMI addressing works much like IP addresses, you have an overlay +to handle the different address types. The overlay is: + + struct ipmi_addr + { + int addr_type; + short channel; + char data[IPMI_MAX_ADDR_SIZE]; + }; + +The addr_type determines what the address really is. The driver +currently understands two different types of addresses. + +"System Interface" addresses are defined as: + + struct ipmi_system_interface_addr + { + int addr_type; + short channel; + }; + +and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking +straight to the BMC on the current card. The channel must be +IPMI_BMC_CHANNEL. + +Messages that are destined to go out on the IPMB bus use the +IPMI_IPMB_ADDR_TYPE address type. The format is + + struct ipmi_ipmb_addr + { + int addr_type; + short channel; + unsigned char slave_addr; + unsigned char lun; + }; + +The "channel" here is generally zero, but some devices support more +than one channel, it corresponds to the channel as defined in the IPMI +spec. + + +Messages +-------- + +Messages are defined as: + +struct ipmi_msg +{ + unsigned char netfn; + unsigned char lun; + unsigned char cmd; + unsigned char *data; + int data_len; +}; + +The driver takes care of adding/stripping the header information. The +data portion is just the data to be send (do NOT put addressing info +here) or the response. Note that the completion code of a response is +the first item in "data", it is not stripped out because that is how +all the messages are defined in the spec (and thus makes counting the +offsets a little easier :-). + +When using the IOCTL interface from userland, you must provide a block +of data for "data", fill it, and set data_len to the length of the +block of data, even when receiving messages. Otherwise the driver +will have no place to put the message. + +Messages coming up from the message handler in kernelland will come in +as: + + struct ipmi_recv_msg + { + struct list_head link; + + /* The type of message as defined in the "Receive Types" + defines above. */ + int recv_type; + + ipmi_user_t *user; + struct ipmi_addr addr; + long msgid; + struct ipmi_msg msg; + + /* Call this when done with the message. It will presumably free + the message and do any other necessary cleanup. */ + void (*done)(struct ipmi_recv_msg *msg); + + /* Place-holder for the data, don't make any assumptions about + the size or existence of this, since it may change. */ + unsigned char msg_data[IPMI_MAX_MSG_LENGTH]; + }; + +You should look at the receive type and handle the message +appropriately. + + +The Upper Layer Interface (Message Handler) +------------------------------------------- + +The upper layer of the interface provides the users with a consistent +view of the IPMI interfaces. It allows multiple SMI interfaces to be +addressed (because some boards actually have multiple BMCs on them) +and the user should not have to care what type of SMI is below them. + + +Creating the User + +To user the message handler, you must first create a user using +ipmi_create_user. The interface number specifies which SMI you want +to connect to, and you must supply callback functions to be called +when data comes in. The callback function can run at interrupt level, +so be careful using the callbacks. This also allows to you pass in a +piece of data, the handler_data, that will be passed back to you on +all calls. + +Once you are done, call ipmi_destroy_user() to get rid of the user. + +From userland, opening the device automatically creates a user, and +closing the device automatically destroys the user. + + +Messaging + +To send a message from kernel-land, the ipmi_request() call does +pretty much all message handling. Most of the parameter are +self-explanatory. However, it takes a "msgid" parameter. This is NOT +the sequence number of messages. It is simply a long value that is +passed back when the response for the message is returned. You may +use it for anything you like. + +Responses come back in the function pointed to by the ipmi_recv_hndl +field of the "handler" that you passed in to ipmi_create_user(). +Remember again, these may be running at interrupt level. Remember to +look at the receive type, too. + +From userland, you fill out an ipmi_req_t structure and use the +IPMICTL_SEND_COMMAND ioctl. For incoming stuff, you can use select() +or poll() to wait for messages to come in. However, you cannot use +read() to get them, you must call the IPMICTL_RECEIVE_MSG with the +ipmi_recv_t structure to actually get the message. Remember that you +must supply a pointer to a block of data in the msg.data field, and +you must fill in the msg.data_len field with the size of the data. +This gives the receiver a place to actually put the message. + +If the message cannot fit into the data you provide, you will get an +EMSGSIZE error and the driver will leave the data in the receive +queue. If you want to get it and have it truncate the message, us +the IPMICTL_RECEIVE_MSG_TRUNC ioctl. + +When you send a command (which is defined by the lowest-order bit of +the netfn per the IPMI spec) on the IPMB bus, the driver will +automatically assign the sequence number to the command and save the +command. If the response is not receive in the IPMI-specified 5 +seconds, it will generate a response automatically saying the command +timed out. If an unsolicited response comes in (if it was after 5 +seconds, for instance), that response will be ignored. + +In kernelland, after you receive a message and are done with it, you +MUST call ipmi_free_recv_msg() on it, or you will leak messages. Note +that you should NEVER mess with the "done" field of a message, that is +required to properly clean up the message. + +Note that when sending, there is an ipmi_request_supply_msgs() call +that lets you supply the smi and receive message. This is useful for +pieces of code that need to work even if the system is out of buffers +(the watchdog timer uses this, for instance). You supply your own +buffer and own free routines. This is not recommended for normal use, +though, since it is tricky to manage your own buffers. + + +Events and Incoming Commands + +The driver takes care of polling for IPMI events and receiving +commands (commands are messages that are not responses, they are +commands that other things on the IPMB bus have sent you). To receive +these, you must register for them, they will not automatically be sent +to you. + +To receive events, you must call ipmi_set_gets_events() and set the +"val" to non-zero. Any events that have been received by the driver +since startup will immediately be delivered to the first user that +registers for events. After that, if multiple users are registered +for events, they will all receive all events that come in. + +For receiving commands, you have to individually register commands you +want to receive. Call ipmi_register_for_cmd() and supply the netfn +and command name for each command you want to receive. You also +specify a bitmask of the channels you want to receive the command from +(or use IPMI_CHAN_ALL for all channels if you don't care). Only one +user may be registered for each netfn/cmd/channel, but different users +may register for different commands, or the same command if the +channel bitmasks do not overlap. + +From userland, equivalent IOCTLs are provided to do these functions. + + +The Lower Layer (SMI) Interface +------------------------------- + +As mentioned before, multiple SMI interfaces may be registered to the +message handler, each of these is assigned an interface number when +they register with the message handler. They are generally assigned +in the order they register, although if an SMI unregisters and then +another one registers, all bets are off. + +The ipmi_smi.h defines the interface for management interfaces, see +that for more details. + + +The SI Driver +------------- + +The SI driver allows up to 4 KCS or SMIC interfaces to be configured +in the system. By default, scan the ACPI tables for interfaces, and +if it doesn't find any the driver will attempt to register one KCS +interface at the spec-specified I/O port 0xca2 without interrupts. +You can change this at module load time (for a module) with: + + modprobe ipmi_si.o type=<type1>,<type2>.... + ports=<port1>,<port2>... addrs=<addr1>,<addr2>... + irqs=<irq1>,<irq2>... + regspacings=<sp1>,<sp2>,... regsizes=<size1>,<size2>,... + regshifts=<shift1>,<shift2>,... + slave_addrs=<addr1>,<addr2>,... + force_kipmid=<enable1>,<enable2>,... + kipmid_max_busy_us=<ustime1>,<ustime2>,... + unload_when_empty=[0|1] + trydefaults=[0|1] trydmi=[0|1] tryacpi=[0|1] + tryplatform=[0|1] trypci=[0|1] + +Each of these except try... items is a list, the first item for the +first interface, second item for the second interface, etc. + +The si_type may be either "kcs", "smic", or "bt". If you leave it blank, it +defaults to "kcs". + +If you specify addrs as non-zero for an interface, the driver will +use the memory address given as the address of the device. This +overrides si_ports. + +If you specify ports as non-zero for an interface, the driver will +use the I/O port given as the device address. + +If you specify irqs as non-zero for an interface, the driver will +attempt to use the given interrupt for the device. + +trydefaults sets whether the standard IPMI interface at 0xca2 and +any interfaces specified by ACPE are tried. By default, the driver +tries it, set this value to zero to turn this off. + +The other try... items disable discovery by their corresponding +names. These are all enabled by default, set them to zero to disable +them. The tryplatform disables openfirmware. + +The next three parameters have to do with register layout. The +registers used by the interfaces may not appear at successive +locations and they may not be in 8-bit registers. These parameters +allow the layout of the data in the registers to be more precisely +specified. + +The regspacings parameter give the number of bytes between successive +register start addresses. For instance, if the regspacing is set to 4 +and the start address is 0xca2, then the address for the second +register would be 0xca6. This defaults to 1. + +The regsizes parameter gives the size of a register, in bytes. The +data used by IPMI is 8-bits wide, but it may be inside a larger +register. This parameter allows the read and write type to specified. +It may be 1, 2, 4, or 8. The default is 1. + +Since the register size may be larger than 32 bits, the IPMI data may not +be in the lower 8 bits. The regshifts parameter give the amount to shift +the data to get to the actual IPMI data. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +The force_ipmid parameter forcefully enables (if set to 1) or disables +(if set to 0) the kernel IPMI daemon. Normally this is auto-detected +by the driver, but systems with broken interrupts might need an enable, +or users that don't want the daemon (don't need the performance, don't +want the CPU hit) can disable it. + +If unload_when_empty is set to 1, the driver will be unloaded if it +doesn't find any interfaces or all the interfaces fail to work. The +default is one. Setting to 0 is useful with the hotmod, but is +obviously only useful for modules. + +When compiled into the kernel, the parameters can be specified on the +kernel command line as: + + ipmi_si.type=<type1>,<type2>... + ipmi_si.ports=<port1>,<port2>... ipmi_si.addrs=<addr1>,<addr2>... + ipmi_si.irqs=<irq1>,<irq2>... ipmi_si.trydefaults=[0|1] + ipmi_si.regspacings=<sp1>,<sp2>,... + ipmi_si.regsizes=<size1>,<size2>,... + ipmi_si.regshifts=<shift1>,<shift2>,... + ipmi_si.slave_addrs=<addr1>,<addr2>,... + ipmi_si.force_kipmid=<enable1>,<enable2>,... + ipmi_si.kipmid_max_busy_us=<ustime1>,<ustime2>,... + +It works the same as the module parameters of the same names. + +By default, the driver will attempt to detect any device specified by +ACPI, and if none of those then a KCS device at the spec-specified +0xca2. If you want to turn this off, set the "trydefaults" option to +false. + +If your IPMI interface does not support interrupts and is a KCS or +SMIC interface, the IPMI driver will start a kernel thread for the +interface to help speed things up. This is a low-priority kernel +thread that constantly polls the IPMI driver while an IPMI operation +is in progress. The force_kipmid module parameter will all the user to +force this thread on or off. If you force it off and don't have +interrupts, the driver will run VERY slowly. Don't blame me, +these interfaces suck. + +Unfortunately, this thread can use a lot of CPU depending on the +interface's performance. This can waste a lot of CPU and cause +various issues with detecting idle CPU and using extra power. To +avoid this, the kipmid_max_busy_us sets the maximum amount of time, in +microseconds, that kipmid will spin before sleeping for a tick. This +value sets a balance between performance and CPU waste and needs to be +tuned to your needs. Maybe, someday, auto-tuning will be added, but +that's not a simple thing and even the auto-tuning would need to be +tuned to the user's desired performance. + +The driver supports a hot add and remove of interfaces. This way, +interfaces can be added or removed after the kernel is up and running. +This is done using /sys/modules/ipmi_si/parameters/hotmod, which is a +write-only parameter. You write a string to this interface. The string +has the format: + <op1>[:op2[:op3...]] +The "op"s are: + add|remove,kcs|bt|smic,mem|i/o,<address>[,<opt1>[,<opt2>[,...]]] +You can specify more than one interface on the line. The "opt"s are: + rsp=<regspacing> + rsi=<regsize> + rsh=<regshift> + irq=<irq> + ipmb=<ipmb slave addr> +and these have the same meanings as discussed above. Note that you +can also use this on the kernel command line for a more compact format +for specifying an interface. Note that when removing an interface, +only the first three parameters (si type, address type, and address) +are used for the comparison. Any options are ignored for removing. + +The SMBus Driver (SSIF) +----------------------- + +The SMBus driver allows up to 4 SMBus devices to be configured in the +system. By default, the driver will only register with something it +finds in DMI or ACPI tables. You can change this +at module load time (for a module) with: + + modprobe ipmi_ssif.o + addr=<i2caddr1>[,<i2caddr2>[,...]] + adapter=<adapter1>[,<adapter2>[...]] + dbg=<flags1>,<flags2>... + slave_addrs=<addr1>,<addr2>,... + [dbg_probe=1] + +The addresses are normal I2C addresses. The adapter is the string +name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name. +It is *NOT* i2c-<n> itself. Also, the comparison is done ignoring +spaces, so if the name is "This is an I2C chip" you can say +adapter_name=ThisisanI2cchip. This is because it's hard to pass in +spaces in kernel parameters. + +The debug flags are bit flags for each BMC found, they are: +IPMI messages: 1, driver state: 2, timing: 4, I2C probe: 8 + +Setting dbg_probe to 1 will enable debugging of the probing and +detection process for BMCs on the SMBusses. + +The slave_addrs specifies the IPMI address of the local BMC. This is +usually 0x20 and the driver defaults to that, but in case it's not, it +can be specified when the driver starts up. + +Discovering the IPMI compliant BMC on the SMBus can cause devices on +the I2C bus to fail. The SMBus driver writes a "Get Device ID" IPMI +message as a block write to the I2C bus and waits for a response. +This action can be detrimental to some I2C devices. It is highly +recommended that the known I2C address be given to the SMBus driver in +the smb_addr parameter unless you have DMI or ACPI data to tell the +driver what to use. + +When compiled into the kernel, the addresses can be specified on the +kernel command line as: + + ipmb_ssif.addr=<i2caddr1>[,<i2caddr2>[...]] + ipmi_ssif.adapter=<adapter1>[,<adapter2>[...]] + ipmi_ssif.dbg=<flags1>[,<flags2>[...]] + ipmi_ssif.dbg_probe=1 + ipmi_ssif.slave_addrs=<addr1>[,<addr2>[...]] + +These are the same options as on the module command line. + +The I2C driver does not support non-blocking access or polling, so +this driver cannod to IPMI panic events, extend the watchdog at panic +time, or other panic-related IPMI functions without special kernel +patches and driver modifications. You can get those at the openipmi +web page. + +The driver supports a hot add and remove of interfaces through the I2C +sysfs interface. + +Other Pieces +------------ + +Get the detailed info related with the IPMI device +-------------------------------------------------- + +Some users need more detailed information about a device, like where +the address came from or the raw base device for the IPMI interface. +You can use the IPMI smi_watcher to catch the IPMI interfaces as they +come or go, and to grab the information, you can use the function +ipmi_get_smi_info(), which returns the following structure: + +struct ipmi_smi_info { + enum ipmi_addr_src addr_src; + struct device *dev; + union { + struct { + void *acpi_handle; + } acpi_info; + } addr_info; +}; + +Currently special info for only for SI_ACPI address sources is +returned. Others may be added as necessary. + +Note that the dev pointer is included in the above structure, and +assuming ipmi_smi_get_info returns success, you must call put_device +on the dev pointer. + + +Watchdog +-------- + +A watchdog timer is provided that implements the Linux-standard +watchdog timer interface. It has three module parameters that can be +used to control it: + + modprobe ipmi_watchdog timeout=<t> pretimeout=<t> action=<action type> + preaction=<preaction type> preop=<preop type> start_now=x + nowayout=x ifnum_to_use=n panic_wdt_timeout=<t> + +ifnum_to_use specifies which interface the watchdog timer should use. +The default is -1, which means to pick the first one registered. + +The timeout is the number of seconds to the action, and the pretimeout +is the amount of seconds before the reset that the pre-timeout panic will +occur (if pretimeout is zero, then pretimeout will not be enabled). Note +that the pretimeout is the time before the final timeout. So if the +timeout is 50 seconds and the pretimeout is 10 seconds, then the pretimeout +will occur in 40 second (10 seconds before the timeout). The panic_wdt_timeout +is the value of timeout which is set on kernel panic, in order to let actions +such as kdump to occur during panic. + +The action may be "reset", "power_cycle", or "power_off", and +specifies what to do when the timer times out, and defaults to +"reset". + +The preaction may be "pre_smi" for an indication through the SMI +interface, "pre_int" for an indication through the SMI with an +interrupts, and "pre_nmi" for a NMI on a preaction. This is how +the driver is informed of the pretimeout. + +The preop may be set to "preop_none" for no operation on a pretimeout, +"preop_panic" to set the preoperation to panic, or "preop_give_data" +to provide data to read from the watchdog device when the pretimeout +occurs. A "pre_nmi" setting CANNOT be used with "preop_give_data" +because you can't do data operations from an NMI. + +When preop is set to "preop_give_data", one byte comes ready to read +on the device when the pretimeout occurs. Select and fasync work on +the device, as well. + +If start_now is set to 1, the watchdog timer will start running as +soon as the driver is loaded. + +If nowayout is set to 1, the watchdog timer will not stop when the +watchdog device is closed. The default value of nowayout is true +if the CONFIG_WATCHDOG_NOWAYOUT option is enabled, or false if not. + +When compiled into the kernel, the kernel command line is available +for configuring the watchdog: + + ipmi_watchdog.timeout=<t> ipmi_watchdog.pretimeout=<t> + ipmi_watchdog.action=<action type> + ipmi_watchdog.preaction=<preaction type> + ipmi_watchdog.preop=<preop type> + ipmi_watchdog.start_now=x + ipmi_watchdog.nowayout=x + ipmi_watchdog.panic_wdt_timeout=<t> + +The options are the same as the module parameter options. + +The watchdog will panic and start a 120 second reset timeout if it +gets a pre-action. During a panic or a reboot, the watchdog will +start a 120 timer if it is running to make sure the reboot occurs. + +Note that if you use the NMI preaction for the watchdog, you MUST NOT +use the nmi watchdog. There is no reasonable way to tell if an NMI +comes from the IPMI controller, so it must assume that if it gets an +otherwise unhandled NMI, it must be from IPMI and it will panic +immediately. + +Once you open the watchdog timer, you must write a 'V' character to the +device to close it, or the timer will not stop. This is a new semantic +for the driver, but makes it consistent with the rest of the watchdog +drivers in Linux. + + +Panic Timeouts +-------------- + +The OpenIPMI driver supports the ability to put semi-custom and custom +events in the system event log if a panic occurs. if you enable the +'Generate a panic event to all BMCs on a panic' option, you will get +one event on a panic in a standard IPMI event format. If you enable +the 'Generate OEM events containing the panic string' option, you will +also get a bunch of OEM events holding the panic string. + + +The field settings of the events are: +* Generator ID: 0x21 (kernel) +* EvM Rev: 0x03 (this event is formatting in IPMI 1.0 format) +* Sensor Type: 0x20 (OS critical stop sensor) +* Sensor #: The first byte of the panic string (0 if no panic string) +* Event Dir | Event Type: 0x6f (Assertion, sensor-specific event info) +* Event Data 1: 0xa1 (Runtime stop in OEM bytes 2 and 3) +* Event data 2: second byte of panic string +* Event data 3: third byte of panic string +See the IPMI spec for the details of the event layout. This event is +always sent to the local management controller. It will handle routing +the message to the right place + +Other OEM events have the following format: +Record ID (bytes 0-1): Set by the SEL. +Record type (byte 2): 0xf0 (OEM non-timestamped) +byte 3: The slave address of the card saving the panic +byte 4: A sequence number (starting at zero) +The rest of the bytes (11 bytes) are the panic string. If the panic string +is longer than 11 bytes, multiple messages will be sent with increasing +sequence numbers. + +Because you cannot send OEM events using the standard interface, this +function will attempt to find an SEL and add the events there. It +will first query the capabilities of the local management controller. +If it has an SEL, then they will be stored in the SEL of the local +management controller. If not, and the local management controller is +an event generator, the event receiver from the local management +controller will be queried and the events sent to the SEL on that +device. Otherwise, the events go nowhere since there is nowhere to +send them. + + +Poweroff +-------- + +If the poweroff capability is selected, the IPMI driver will install +a shutdown function into the standard poweroff function pointer. This +is in the ipmi_poweroff module. When the system requests a powerdown, +it will send the proper IPMI commands to do this. This is supported on +several platforms. + +There is a module parameter named "poweroff_powercycle" that may +either be zero (do a power down) or non-zero (do a power cycle, power +the system off, then power it on in a few seconds). Setting +ipmi_poweroff.poweroff_control=x will do the same thing on the kernel +command line. The parameter is also available via the proc filesystem +in /proc/sys/dev/ipmi/poweroff_powercycle. Note that if the system +does not support power cycling, it will always do the power off. + +The "ifnum_to_use" parameter specifies which interface the poweroff +code should use. The default is -1, which means to pick the first one +registered. + +Note that if you have ACPI enabled, the system will prefer using ACPI to +power off.
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/IRQ-affinity.txt new file mode 100644 index 0000000..01a6751 --- /dev/null +++ b/Documentation/IRQ-affinity.txt
@@ -0,0 +1,65 @@ +ChangeLog: + Started by Ingo Molnar <mingo@redhat.com> + Update by Max Krasnyansky <maxk@qualcomm.com> + +SMP IRQ affinity + +/proc/irq/IRQ#/smp_affinity and /proc/irq/IRQ#/smp_affinity_list specify +which target CPUs are permitted for a given IRQ source. It's a bitmask +(smp_affinity) or cpu list (smp_affinity_list) of allowed CPUs. It's not +allowed to turn off all CPUs, and if an IRQ controller does not support +IRQ affinity then the value will not change from the default of all cpus. + +/proc/irq/default_smp_affinity specifies default affinity mask that applies +to all non-active IRQs. Once IRQ is allocated/activated its affinity bitmask +will be set to the default mask. It can then be changed as described above. +Default mask is 0xffffffff. + +Here is an example of restricting IRQ44 (eth1) to CPU0-3 then restricting +it to CPU4-7 (this is an 8-CPU SMP box): + +[root@moon 44]# cd /proc/irq/44 +[root@moon 44]# cat smp_affinity +ffffffff + +[root@moon 44]# echo 0f > smp_affinity +[root@moon 44]# cat smp_affinity +0000000f +[root@moon 44]# ping -f h +PING hell (195.4.7.3): 56 data bytes +... +--- hell ping statistics --- +6029 packets transmitted, 6027 packets received, 0% packet loss +round-trip min/avg/max = 0.1/0.1/0.4 ms +[root@moon 44]# cat /proc/interrupts | grep 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 0 0 0 0 IO-APIC-level eth1 + +As can be seen from the line above IRQ44 was delivered only to the first four +processors (0-3). +Now lets restrict that IRQ to CPU(4-7). + +[root@moon 44]# echo f0 > smp_affinity +[root@moon 44]# cat smp_affinity +000000f0 +[root@moon 44]# ping -f h +PING hell (195.4.7.3): 56 data bytes +.. +--- hell ping statistics --- +2779 packets transmitted, 2777 packets received, 0% packet loss +round-trip min/avg/max = 0.1/0.5/585.4 ms +[root@moon 44]# cat /proc/interrupts | 'CPU\|44:' + CPU0 CPU1 CPU2 CPU3 CPU4 CPU5 CPU6 CPU7 + 44: 1068 1785 1785 1783 1784 1069 1070 1069 IO-APIC-level eth1 + +This time around IRQ44 was delivered only to the last four processors. +i.e counters for the CPU0-3 did not change. + +Here is an example of limiting that same irq (44) to cpus 1024 to 1031: + +[root@moon 44]# echo 1024-1031 > smp_affinity_list +[root@moon 44]# cat smp_affinity_list +1024-1031 + +Note that to do this with a bitmask would require 32 bitmasks of zero +to follow the pertinent one.
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.txt new file mode 100644 index 0000000..82001a2 --- /dev/null +++ b/Documentation/IRQ-domain.txt
@@ -0,0 +1,235 @@ +irq_domain interrupt number mapping library + +The current design of the Linux kernel uses a single large number +space where each separate IRQ source is assigned a different number. +This is simple when there is only one interrupt controller, but in +systems with multiple interrupt controllers the kernel must ensure +that each one gets assigned non-overlapping allocations of Linux +IRQ numbers. + +The number of interrupt controllers registered as unique irqchips +show a rising tendency: for example subdrivers of different kinds +such as GPIO controllers avoid reimplementing identical callback +mechanisms as the IRQ core system by modelling their interrupt +handlers as irqchips, i.e. in effect cascading interrupt controllers. + +Here the interrupt number loose all kind of correspondence to +hardware interrupt numbers: whereas in the past, IRQ numbers could +be chosen so they matched the hardware IRQ line into the root +interrupt controller (i.e. the component actually fireing the +interrupt line to the CPU) nowadays this number is just a number. + +For this reason we need a mechanism to separate controller-local +interrupt numbers, called hardware irq's, from Linux IRQ numbers. + +The irq_alloc_desc*() and irq_free_desc*() APIs provide allocation of +irq numbers, but they don't provide any support for reverse mapping of +the controller-local IRQ (hwirq) number into the Linux IRQ number +space. + +The irq_domain library adds mapping between hwirq and IRQ numbers on +top of the irq_alloc_desc*() API. An irq_domain to manage mapping is +preferred over interrupt controller drivers open coding their own +reverse mapping scheme. + +irq_domain also implements translation from an abstract irq_fwspec +structure to hwirq numbers (Device Tree and ACPI GSI so far), and can +be easily extended to support other IRQ topology data sources. + +=== irq_domain usage === +An interrupt controller driver creates and registers an irq_domain by +calling one of the irq_domain_add_*() functions (each mapping method +has a different allocator function, more on that later). The function +will return a pointer to the irq_domain on success. The caller must +provide the allocator function with an irq_domain_ops structure. + +In most cases, the irq_domain will begin empty without any mappings +between hwirq and IRQ numbers. Mappings are added to the irq_domain +by calling irq_create_mapping() which accepts the irq_domain and a +hwirq number as arguments. If a mapping for the hwirq doesn't already +exist then it will allocate a new Linux irq_desc, associate it with +the hwirq, and call the .map() callback so the driver can perform any +required hardware setup. + +When an interrupt is received, irq_find_mapping() function should +be used to find the Linux IRQ number from the hwirq number. + +The irq_create_mapping() function must be called *atleast once* +before any call to irq_find_mapping(), lest the descriptor will not +be allocated. + +If the driver has the Linux IRQ number or the irq_data pointer, and +needs to know the associated hwirq number (such as in the irq_chip +callbacks) then it can be directly obtained from irq_data->hwirq. + +=== Types of irq_domain mappings === +There are several mechanisms available for reverse mapping from hwirq +to Linux irq, and each mechanism uses a different allocation function. +Which reverse map type should be used depends on the use case. Each +of the reverse map types are described below: + +==== Linear ==== +irq_domain_add_linear() +irq_domain_create_linear() + +The linear reverse map maintains a fixed size table indexed by the +hwirq number. When a hwirq is mapped, an irq_desc is allocated for +the hwirq, and the IRQ number is stored in the table. + +The Linear map is a good choice when the maximum number of hwirqs is +fixed and a relatively small number (~ < 256). The advantages of this +map are fixed time lookup for IRQ numbers, and irq_descs are only +allocated for in-use IRQs. The disadvantage is that the table must be +as large as the largest possible hwirq number. + +irq_domain_add_linear() and irq_domain_create_linear() are functionally +equivalent, except for the first argument is different - the former +accepts an Open Firmware specific 'struct device_node', while the latter +accepts a more general abstraction 'struct fwnode_handle'. + +The majority of drivers should use the linear map. + +==== Tree ==== +irq_domain_add_tree() +irq_domain_create_tree() + +The irq_domain maintains a radix tree map from hwirq numbers to Linux +IRQs. When an hwirq is mapped, an irq_desc is allocated and the +hwirq is used as the lookup key for the radix tree. + +The tree map is a good choice if the hwirq number can be very large +since it doesn't need to allocate a table as large as the largest +hwirq number. The disadvantage is that hwirq to IRQ number lookup is +dependent on how many entries are in the table. + +irq_domain_add_tree() and irq_domain_create_tree() are functionally +equivalent, except for the first argument is different - the former +accepts an Open Firmware specific 'struct device_node', while the latter +accepts a more general abstraction 'struct fwnode_handle'. + +Very few drivers should need this mapping. + +==== No Map ===- +irq_domain_add_nomap() + +The No Map mapping is to be used when the hwirq number is +programmable in the hardware. In this case it is best to program the +Linux IRQ number into the hardware itself so that no mapping is +required. Calling irq_create_direct_mapping() will allocate a Linux +IRQ number and call the .map() callback so that driver can program the +Linux IRQ number into the hardware. + +Most drivers cannot use this mapping. + +==== Legacy ==== +irq_domain_add_simple() +irq_domain_add_legacy() +irq_domain_add_legacy_isa() + +The Legacy mapping is a special case for drivers that already have a +range of irq_descs allocated for the hwirqs. It is used when the +driver cannot be immediately converted to use the linear mapping. For +example, many embedded system board support files use a set of #defines +for IRQ numbers that are passed to struct device registrations. In that +case the Linux IRQ numbers cannot be dynamically assigned and the legacy +mapping should be used. + +The legacy map assumes a contiguous range of IRQ numbers has already +been allocated for the controller and that the IRQ number can be +calculated by adding a fixed offset to the hwirq number, and +visa-versa. The disadvantage is that it requires the interrupt +controller to manage IRQ allocations and it requires an irq_desc to be +allocated for every hwirq, even if it is unused. + +The legacy map should only be used if fixed IRQ mappings must be +supported. For example, ISA controllers would use the legacy map for +mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ +numbers. + +Most users of legacy mappings should use irq_domain_add_simple() which +will use a legacy domain only if an IRQ range is supplied by the +system and will otherwise use a linear domain mapping. The semantics +of this call are such that if an IRQ range is specified then +descriptors will be allocated on-the-fly for it, and if no range is +specified it will fall through to irq_domain_add_linear() which means +*no* irq descriptors will be allocated. + +A typical use case for simple domains is where an irqchip provider +is supporting both dynamic and static IRQ assignments. + +In order to avoid ending up in a situation where a linear domain is +used and no descriptor gets allocated it is very important to make sure +that the driver using the simple domain call irq_create_mapping() +before any irq_find_mapping() since the latter will actually work +for the static IRQ assignment case. + +==== Hierarchy IRQ domain ==== +On some architectures, there may be multiple interrupt controllers +involved in delivering an interrupt from the device to the target CPU. +Let's look at a typical interrupt delivering path on x86 platforms: + +Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU + +There are three interrupt controllers involved: +1) IOAPIC controller +2) Interrupt remapping controller +3) Local APIC controller + +To support such a hardware topology and make software architecture match +hardware architecture, an irq_domain data structure is built for each +interrupt controller and those irq_domains are organized into hierarchy. +When building irq_domain hierarchy, the irq_domain near to the device is +child and the irq_domain near to CPU is parent. So a hierarchy structure +as below will be built for the example above. + CPU Vector irq_domain (root irq_domain to manage CPU vectors) + ^ + | + Interrupt Remapping irq_domain (manage irq_remapping entries) + ^ + | + IOAPIC irq_domain (manage IOAPIC delivery entries/pins) + +There are four major interfaces to use hierarchy irq_domain: +1) irq_domain_alloc_irqs(): allocate IRQ descriptors and interrupt + controller related resources to deliver these interrupts. +2) irq_domain_free_irqs(): free IRQ descriptors and interrupt controller + related resources associated with these interrupts. +3) irq_domain_activate_irq(): activate interrupt controller hardware to + deliver the interrupt. +4) irq_domain_deactivate_irq(): deactivate interrupt controller hardware + to stop delivering the interrupt. + +Following changes are needed to support hierarchy irq_domain. +1) a new field 'parent' is added to struct irq_domain; it's used to + maintain irq_domain hierarchy information. +2) a new field 'parent_data' is added to struct irq_data; it's used to + build hierarchy irq_data to match hierarchy irq_domains. The irq_data + is used to store irq_domain pointer and hardware irq number. +3) new callbacks are added to struct irq_domain_ops to support hierarchy + irq_domain operations. + +With support of hierarchy irq_domain and hierarchy irq_data ready, an +irq_domain structure is built for each interrupt controller, and an +irq_data structure is allocated for each irq_domain associated with an +IRQ. Now we could go one step further to support stacked(hierarchy) +irq_chip. That is, an irq_chip is associated with each irq_data along +the hierarchy. A child irq_chip may implement a required action by +itself or by cooperating with its parent irq_chip. + +With stacked irq_chip, interrupt controller driver only needs to deal +with the hardware managed by itself and may ask for services from its +parent irq_chip when needed. So we could achieve a much cleaner +software architecture. + +For an interrupt controller driver to support hierarchy irq_domain, it +needs to: +1) Implement irq_domain_ops.alloc and irq_domain_ops.free +2) Optionally implement irq_domain_ops.activate and + irq_domain_ops.deactivate. +3) Optionally implement an irq_chip to manage the interrupt controller + hardware. +4) No need to implement irq_domain_ops.map and irq_domain_ops.unmap, + they are unused with hierarchy irq_domain. + +Hierarchy irq_domain may also be used to support other architectures, +such as ARM, ARM64 etc.
diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.txt new file mode 100644 index 0000000..1011e71 --- /dev/null +++ b/Documentation/IRQ.txt
@@ -0,0 +1,22 @@ +What is an IRQ? + +An IRQ is an interrupt request from a device. +Currently they can come in over a pin, or over a packet. +Several devices may be connected to the same pin thus +sharing an IRQ. + +An IRQ number is a kernel identifier used to talk about a hardware +interrupt source. Typically this is an index into the global irq_desc +array, but except for what linux/interrupt.h implements the details +are architecture specific. + +An IRQ number is an enumeration of the possible interrupt sources on a +machine. Typically what is enumerated is the number of input pins on +all of the interrupt controller in the system. In the case of ISA +what is enumerated are the 16 input pins on the two i8259 interrupt +controllers. + +Architectures can assign additional meaning to the IRQ numbers, and +are encouraged to in the case where there is any manual configuration +of the hardware involved. The ISA IRQs are a classic example of +assigning this kind of additional meaning.
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.txt new file mode 100644 index 0000000..49585b6 --- /dev/null +++ b/Documentation/Intel-IOMMU.txt
@@ -0,0 +1,111 @@ +Linux IOMMU Support +=================== + +The architecture spec can be obtained from the below location. + +http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/vt-directed-io-spec.pdf + +This guide gives a quick cheat sheet for some basic understanding. + +Some Keywords + +DMAR - DMA remapping +DRHD - DMA Remapping Hardware Unit Definition +RMRR - Reserved memory Region Reporting Structure +ZLR - Zero length reads from PCI devices +IOVA - IO Virtual address. + +Basic stuff +----------- + +ACPI enumerates and lists the different DMA engines in the platform, and +device scope relationships between PCI devices and which DMA engine controls +them. + +What is RMRR? +------------- + +There are some devices the BIOS controls, for e.g USB devices to perform +PS2 emulation. The regions of memory used for these devices are marked +reserved in the e820 map. When we turn on DMA translation, DMA to those +regions will fail. Hence BIOS uses RMRR to specify these regions along with +devices that need to access these regions. OS is expected to setup +unity mappings for these regions for these devices to access these regions. + +How is IOVA generated? +--------------------- + +Well behaved drivers call pci_map_*() calls before sending command to device +that needs to perform DMA. Once DMA is completed and mapping is no longer +required, device performs a pci_unmap_*() calls to unmap the region. + +The Intel IOMMU driver allocates a virtual address per domain. Each PCIE +device has its own domain (hence protection). Devices under p2p bridges +share the virtual address with all devices under the p2p bridge due to +transaction id aliasing for p2p bridges. + +IOVA generation is pretty generic. We used the same technique as vmalloc() +but these are not global address spaces, but separate for each domain. +Different DMA engines may support different number of domains. + +We also allocate guard pages with each mapping, so we can attempt to catch +any overflow that might happen. + + +Graphics Problems? +------------------ +If you encounter issues with graphics devices, you can try adding +option intel_iommu=igfx_off to turn off the integrated graphics engine. +If this fixes anything, please ensure you file a bug reporting the problem. + +Some exceptions to IOVA +----------------------- +Interrupt ranges are not address translated, (0xfee00000 - 0xfeefffff). +The same is true for peer to peer transactions. Hence we reserve the +address from PCI MMIO ranges so they are not allocated for IOVA addresses. + + +Fault reporting +--------------- +When errors are reported, the DMA engine signals via an interrupt. The fault +reason and device that caused it with fault reason is printed on console. + +See below for sample. + + +Boot Message Sample +------------------- + +Something like this gets printed indicating presence of DMAR tables +in ACPI. + +ACPI: DMAR (v001 A M I OEMDMAR 0x00000001 MSFT 0x00000097) @ 0x000000007f5b5ef0 + +When DMAR is being processed and initialized by ACPI, prints DMAR locations +and any RMRR's processed. + +ACPI DMAR:Host address width 36 +ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed90000 +ACPI DMAR:DRHD (flags: 0x00000000)base: 0x00000000fed91000 +ACPI DMAR:DRHD (flags: 0x00000001)base: 0x00000000fed93000 +ACPI DMAR:RMRR base: 0x00000000000ed000 end: 0x00000000000effff +ACPI DMAR:RMRR base: 0x000000007f600000 end: 0x000000007fffffff + +When DMAR is enabled for use, you will notice.. + +PCI-DMA: Using DMAR IOMMU + +Fault reporting +--------------- + +DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000 +DMAR:[fault reason 05] PTE Write access is not set +DMAR:[DMA Write] Request device [00:02.0] fault addr 6df084000 +DMAR:[fault reason 05] PTE Write access is not set + +TBD +---- + +- For compatibility testing, could use unity map domain for all devices, just + provide a 1-1 for all useful memory under a single domain for all devices. +- API for paravirt ops for abstracting functionality for VMM folks.
diff --git a/Documentation/Makefile b/Documentation/Makefile new file mode 100644 index 0000000..c2a4691 --- /dev/null +++ b/Documentation/Makefile
@@ -0,0 +1 @@ +subdir-y :=
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx new file mode 100644 index 0000000..92deea3 --- /dev/null +++ b/Documentation/Makefile.sphinx
@@ -0,0 +1,112 @@ +# -*- makefile -*- +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXBUILD = sphinx-build +SPHINXOPTS = +SPHINXDIRS = . +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +SPHINX_CONF = conf.py +PAPER = +BUILDDIR = $(obj)/output + +# User-friendly check for sphinx-build +HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) + +ifeq ($(HAVE_SPHINX),0) + +.DEFAULT: + $(warning The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable.) + @echo " SKIP Sphinx $@ target." + +else ifneq ($(DOCBOOKS),) + +# Skip Sphinx build if the user explicitly requested DOCBOOKS. +.DEFAULT: + @echo " SKIP Sphinx $@ target (DOCBOOKS specified)." + +else # HAVE_SPHINX + +# User-friendly check for pdflatex +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi) + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +KERNELDOC = $(srctree)/scripts/kernel-doc +KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) +ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* +loop_cmd = $(echo-cmd) $(cmd_$(1)) + +# $2 sphinx builder e.g. "html" +# $3 name of the build subfolder / e.g. "media", used as: +# * dest folder relative to $(BUILDDIR) and +# * cache folder relative to $(BUILDDIR)/.doctrees +# $4 dest subfolder e.g. "man" for man pages at media/man +# $5 reST source folder relative to $(srctree)/$(src), +# e.g. "media" for the linux-tv book-set at ./Documentation/media + +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ + BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(SPHINXBUILD) \ + -b $2 \ + -c $(abspath $(srctree)/$(src)) \ + -d $(abspath $(BUILDDIR)/.doctrees/$3) \ + -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ + $(ALLSPHINXOPTS) \ + $(abspath $(srctree)/$(src)/$5) \ + $(abspath $(BUILDDIR)/$3/$4); + +htmldocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) + +latexdocs: +ifeq ($(HAVE_PDFLATEX),0) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + @echo " SKIP Sphinx $@ target." +else # HAVE_PDFLATEX + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) +endif # HAVE_PDFLATEX + +pdfdocs: latexdocs +ifneq ($(HAVE_PDFLATEX),0) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) +endif # HAVE_PDFLATEX + +epubdocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) + +xmldocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) + +# no-ops for the Sphinx toolchain +sgmldocs: +psdocs: +mandocs: +installmandocs: + +cleandocs: + $(Q)rm -rf $(BUILDDIR) + +endif # HAVE_SPHINX + +dochelp: + @echo ' Linux kernel internal documentation in different formats (Sphinx):' + @echo ' htmldocs - HTML' + @echo ' latexdocs - LaTeX' + @echo ' pdfdocs - PDF' + @echo ' epubdocs - EPUB' + @echo ' xmldocs - XML' + @echo ' cleandocs - clean all generated files' + @echo + @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' + @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo + @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' + @echo ' configuration. This is e.g. useful to build with nit-picking config.'
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle new file mode 100644 index 0000000..dea2e66 --- /dev/null +++ b/Documentation/ManagementStyle
@@ -0,0 +1,288 @@ +.. _managementstyle: + +Linux kernel management style +============================= + +This is a short document describing the preferred (or made up, depending +on who you ask) management style for the linux kernel. It's meant to +mirror the CodingStyle document to some degree, and mainly written to +avoid answering [#f1]_ the same (or similar) questions over and over again. + +Management style is very personal and much harder to quantify than +simple coding style rules, so this document may or may not have anything +to do with reality. It started as a lark, but that doesn't mean that it +might not actually be true. You'll have to decide for yourself. + +Btw, when talking about "kernel manager", it's all about the technical +lead persons, not the people who do traditional management inside +companies. If you sign purchase orders or you have any clue about the +budget of your group, you're almost certainly not a kernel manager. +These suggestions may or may not apply to you. + +First off, I'd suggest buying "Seven Habits of Highly Effective +People", and NOT read it. Burn it, it's a great symbolic gesture. + +.. [#f1] This document does so not so much by answering the question, but by + making it painfully obvious to the questioner that we don't have a clue + to what the answer is. + +Anyway, here goes: + +.. _decisions: + +1) Decisions +------------ + +Everybody thinks managers make decisions, and that decision-making is +important. The bigger and more painful the decision, the bigger the +manager must be to make it. That's very deep and obvious, but it's not +actually true. + +The name of the game is to **avoid** having to make a decision. In +particular, if somebody tells you "choose (a) or (b), we really need you +to decide on this", you're in trouble as a manager. The people you +manage had better know the details better than you, so if they come to +you for a technical decision, you're screwed. You're clearly not +competent to make that decision for them. + +(Corollary:if the people you manage don't know the details better than +you, you're also screwed, although for a totally different reason. +Namely that you are in the wrong job, and that **they** should be managing +your brilliance instead). + +So the name of the game is to **avoid** decisions, at least the big and +painful ones. Making small and non-consequential decisions is fine, and +makes you look like you know what you're doing, so what a kernel manager +needs to do is to turn the big and painful ones into small things where +nobody really cares. + +It helps to realize that the key difference between a big decision and a +small one is whether you can fix your decision afterwards. Any decision +can be made small by just always making sure that if you were wrong (and +you **will** be wrong), you can always undo the damage later by +backtracking. Suddenly, you get to be doubly managerial for making +**two** inconsequential decisions - the wrong one **and** the right one. + +And people will even see that as true leadership (*cough* bullshit +*cough*). + +Thus the key to avoiding big decisions becomes to just avoiding to do +things that can't be undone. Don't get ushered into a corner from which +you cannot escape. A cornered rat may be dangerous - a cornered manager +is just pitiful. + +It turns out that since nobody would be stupid enough to ever really let +a kernel manager have huge fiscal responsibility **anyway**, it's usually +fairly easy to backtrack. Since you're not going to be able to waste +huge amounts of money that you might not be able to repay, the only +thing you can backtrack on is a technical decision, and there +back-tracking is very easy: just tell everybody that you were an +incompetent nincompoop, say you're sorry, and undo all the worthless +work you had people work on for the last year. Suddenly the decision +you made a year ago wasn't a big decision after all, since it could be +easily undone. + +It turns out that some people have trouble with this approach, for two +reasons: + + - admitting you were an idiot is harder than it looks. We all like to + maintain appearances, and coming out in public to say that you were + wrong is sometimes very hard indeed. + - having somebody tell you that what you worked on for the last year + wasn't worthwhile after all can be hard on the poor lowly engineers + too, and while the actual **work** was easy enough to undo by just + deleting it, you may have irrevocably lost the trust of that + engineer. And remember: "irrevocable" was what we tried to avoid in + the first place, and your decision ended up being a big one after + all. + +Happily, both of these reasons can be mitigated effectively by just +admitting up-front that you don't have a friggin' clue, and telling +people ahead of the fact that your decision is purely preliminary, and +might be the wrong thing. You should always reserve the right to change +your mind, and make people very **aware** of that. And it's much easier +to admit that you are stupid when you haven't **yet** done the really +stupid thing. + +Then, when it really does turn out to be stupid, people just roll their +eyes and say "Oops, he did it again". + +This preemptive admission of incompetence might also make the people who +actually do the work also think twice about whether it's worth doing or +not. After all, if **they** aren't certain whether it's a good idea, you +sure as hell shouldn't encourage them by promising them that what they +work on will be included. Make them at least think twice before they +embark on a big endeavor. + +Remember: they'd better know more about the details than you do, and +they usually already think they have the answer to everything. The best +thing you can do as a manager is not to instill confidence, but rather a +healthy dose of critical thinking on what they do. + +Btw, another way to avoid a decision is to plaintively just whine "can't +we just do both?" and look pitiful. Trust me, it works. If it's not +clear which approach is better, they'll eventually figure it out. The +answer may end up being that both teams get so frustrated by the +situation that they just give up. + +That may sound like a failure, but it's usually a sign that there was +something wrong with both projects, and the reason the people involved +couldn't decide was that they were both wrong. You end up coming up +smelling like roses, and you avoided yet another decision that you could +have screwed up on. + + +2) People +--------- + +Most people are idiots, and being a manager means you'll have to deal +with it, and perhaps more importantly, that **they** have to deal with +**you**. + +It turns out that while it's easy to undo technical mistakes, it's not +as easy to undo personality disorders. You just have to live with +theirs - and yours. + +However, in order to prepare yourself as a kernel manager, it's best to +remember not to burn any bridges, bomb any innocent villagers, or +alienate too many kernel developers. It turns out that alienating people +is fairly easy, and un-alienating them is hard. Thus "alienating" +immediately falls under the heading of "not reversible", and becomes a +no-no according to :ref:`decisions`. + +There's just a few simple rules here: + + (1) don't call people d*ckheads (at least not in public) + (2) learn how to apologize when you forgot rule (1) + +The problem with #1 is that it's very easy to do, since you can say +"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without +even realizing it, and almost always with a white-hot conviction that +you are right. + +And the more convinced you are that you are right (and let's face it, +you can call just about **anybody** a d*ckhead, and you often **will** be +right), the harder it ends up being to apologize afterwards. + +To solve this problem, you really only have two options: + + - get really good at apologies + - spread the "love" out so evenly that nobody really ends up feeling + like they get unfairly targeted. Make it inventive enough, and they + might even be amused. + +The option of being unfailingly polite really doesn't exist. Nobody will +trust somebody who is so clearly hiding his true character. + +.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite + frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't + scan nearly as well. But I'm sure he thought about it. + + +3) People II - the Good Kind +---------------------------- + +While it turns out that most people are idiots, the corollary to that is +sadly that you are one too, and that while we can all bask in the secure +knowledge that we're better than the average person (let's face it, +nobody ever believes that they're average or below-average), we should +also admit that we're not the sharpest knife around, and there will be +other people that are less of an idiot than you are. + +Some people react badly to smart people. Others take advantage of them. + +Make sure that you, as a kernel maintainer, are in the second group. +Suck up to them, because they are the people who will make your job +easier. In particular, they'll be able to make your decisions for you, +which is what the game is all about. + +So when you find somebody smarter than you are, just coast along. Your +management responsibilities largely become ones of saying "Sounds like a +good idea - go wild", or "That sounds good, but what about xxx?". The +second version in particular is a great way to either learn something +new about "xxx" or seem **extra** managerial by pointing out something the +smarter person hadn't thought about. In either case, you win. + +One thing to look out for is to realize that greatness in one area does +not necessarily translate to other areas. So you might prod people in +specific directions, but let's face it, they might be good at what they +do, and suck at everything else. The good news is that people tend to +naturally gravitate back to what they are good at, so it's not like you +are doing something irreversible when you **do** prod them in some +direction, just don't push too hard. + + +4) Placing blame +---------------- + +Things will go wrong, and people want somebody to blame. Tag, you're it. + +It's not actually that hard to accept the blame, especially if people +kind of realize that it wasn't **all** your fault. Which brings us to the +best way of taking the blame: do it for another guy. You'll feel good +for taking the fall, he'll feel good about not getting blamed, and the +guy who lost his whole 36GB porn-collection because of your incompetence +will grudgingly admit that you at least didn't try to weasel out of it. + +Then make the developer who really screwed up (if you can find him) know +**in_private** that he screwed up. Not just so he can avoid it in the +future, but so that he knows he owes you one. And, perhaps even more +importantly, he's also likely the person who can fix it. Because, let's +face it, it sure ain't you. + +Taking the blame is also why you get to be manager in the first place. +It's part of what makes people trust you, and allow you the potential +glory, because you're the one who gets to say "I screwed up". And if +you've followed the previous rules, you'll be pretty good at saying that +by now. + + +5) Things to avoid +------------------ + +There's one thing people hate even more than being called "d*ckhead", +and that is being called a "d*ckhead" in a sanctimonious voice. The +first you can apologize for, the second one you won't really get the +chance. They likely will no longer be listening even if you otherwise +do a good job. + +We all think we're better than anybody else, which means that when +somebody else puts on airs, it **really** rubs us the wrong way. You may +be morally and intellectually superior to everybody around you, but +don't try to make it too obvious unless you really **intend** to irritate +somebody [#f3]_. + +Similarly, don't be too polite or subtle about things. Politeness easily +ends up going overboard and hiding the problem, and as they say, "On the +internet, nobody can hear you being subtle". Use a big blunt object to +hammer the point in, because you can't really depend on people getting +your point otherwise. + +Some humor can help pad both the bluntness and the moralizing. Going +overboard to the point of being ridiculous can drive a point home +without making it painful to the recipient, who just thinks you're being +silly. It can thus help get through the personal mental block we all +have about criticism. + +.. [#f3] Hint: internet newsgroups that are not directly related to your work + are great ways to take out your frustrations at other people. Write + insulting posts with a sneer just to get into a good flame every once in + a while, and you'll feel cleansed. Just don't crap too close to home. + + +6) Why me? +---------- + +Since your main responsibility seems to be to take the blame for other +peoples mistakes, and make it painfully obvious to everybody else that +you're incompetent, the obvious question becomes one of why do it in the +first place? + +First off, while you may or may not get screaming teenage girls (or +boys, let's not be judgmental or sexist here) knocking on your dressing +room door, you **will** get an immense feeling of personal accomplishment +for being "in charge". Never mind the fact that you're really leading +by trying to keep up with everybody else and running after them as fast +as you can. Everybody will still think you're the person in charge. + +It's a great job if you can hack it.
diff --git a/Documentation/PCI/00-INDEX b/Documentation/PCI/00-INDEX new file mode 100644 index 0000000..147231f --- /dev/null +++ b/Documentation/PCI/00-INDEX
@@ -0,0 +1,14 @@ +00-INDEX + - this file +MSI-HOWTO.txt + - the Message Signaled Interrupts (MSI) Driver Guide HOWTO and FAQ. +PCIEBUS-HOWTO.txt + - a guide describing the PCI Express Port Bus driver +pci-error-recovery.txt + - info on PCI error recovery +pci-iov-howto.txt + - the PCI Express I/O Virtualization HOWTO +pci.txt + - info on the PCI subsystem for device driver authors +pcieaer-howto.txt + - the PCI Express Advanced Error Reporting Driver Guide HOWTO
diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt new file mode 100644 index 0000000..cd9c9f6 --- /dev/null +++ b/Documentation/PCI/MSI-HOWTO.txt
@@ -0,0 +1,272 @@ + The MSI Driver Guide HOWTO + Tom L Nguyen tom.l.nguyen@intel.com + 10/03/2003 + Revised Feb 12, 2004 by Martine Silbermann + email: Martine.Silbermann@hp.com + Revised Jun 25, 2004 by Tom L Nguyen + Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com> + Copyright 2003, 2008 Intel Corporation + +1. About this guide + +This guide describes the basics of Message Signaled Interrupts (MSIs), +the advantages of using MSI over traditional interrupt mechanisms, how +to change your driver to use MSI or MSI-X and some basic diagnostics to +try if a device doesn't support MSIs. + + +2. What are MSIs? + +A Message Signaled Interrupt is a write from the device to a special +address which causes an interrupt to be received by the CPU. + +The MSI capability was first specified in PCI 2.2 and was later enhanced +in PCI 3.0 to allow each interrupt to be masked individually. The MSI-X +capability was also introduced with PCI 3.0. It supports more interrupts +per device than MSI and allows interrupts to be independently configured. + +Devices may support both MSI and MSI-X, but only one can be enabled at +a time. + + +3. Why use MSIs? + +There are three reasons why using MSIs can give an advantage over +traditional pin-based interrupts. + +Pin-based PCI interrupts are often shared amongst several devices. +To support this, the kernel must call each interrupt handler associated +with an interrupt, which leads to reduced performance for the system as +a whole. MSIs are never shared, so this problem cannot arise. + +When a device writes data to memory, then raises a pin-based interrupt, +it is possible that the interrupt may arrive before all the data has +arrived in memory (this becomes more likely with devices behind PCI-PCI +bridges). In order to ensure that all the data has arrived in memory, +the interrupt handler must read a register on the device which raised +the interrupt. PCI transaction ordering rules require that all the data +arrive in memory before the value may be returned from the register. +Using MSIs avoids this problem as the interrupt-generating write cannot +pass the data writes, so by the time the interrupt is raised, the driver +knows that all the data has arrived in memory. + +PCI devices can only support a single pin-based interrupt per function. +Often drivers have to query the device to find out what event has +occurred, slowing down interrupt handling for the common case. With +MSIs, a device can support more interrupts, allowing each interrupt +to be specialised to a different purpose. One possible design gives +infrequent conditions (such as errors) their own interrupt which allows +the driver to handle the normal interrupt handling path more efficiently. +Other possible designs include giving one interrupt to each packet queue +in a network card or each port in a storage controller. + + +4. How to use MSIs + +PCI devices are initialised to use pin-based interrupts. The device +driver has to set up the device to use MSI or MSI-X. Not all machines +support MSIs correctly, and for those machines, the APIs described below +will simply fail and the device will continue to use pin-based interrupts. + +4.1 Include kernel support for MSIs + +To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI +option enabled. This option is only available on some architectures, +and it may depend on some other options also being set. For example, +on x86, you must also enable X86_UP_APIC or SMP in order to see the +CONFIG_PCI_MSI option. + +4.2 Using MSI + +Most of the hard work is done for the driver in the PCI layer. The driver +simply has to request that the PCI layer set up the MSI capability for this +device. + +To automatically use MSI or MSI-X interrupt vectors, use the following +function: + + int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, + unsigned int max_vecs, unsigned int flags); + +which allocates up to max_vecs interrupt vectors for a PCI device. It +returns the number of vectors allocated or a negative error. If the device +has a requirements for a minimum number of vectors the driver can pass a +min_vecs argument set to this limit, and the PCI core will return -ENOSPC +if it can't meet the minimum number of vectors. + +The flags argument is used to specify which type of interrupt can be used +by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX). +A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for +any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set, +pci_alloc_irq_vectors() will spread the interrupts around the available CPUs. + +To get the Linux IRQ numbers passed to request_irq() and free_irq() and the +vectors, use the following function: + + int pci_irq_vector(struct pci_dev *dev, unsigned int nr); + +Any allocated resources should be freed before removing the device using +the following function: + + void pci_free_irq_vectors(struct pci_dev *dev); + +If a device supports both MSI-X and MSI capabilities, this API will use the +MSI-X facilities in preference to the MSI facilities. MSI-X supports any +number of interrupts between 1 and 2048. In contrast, MSI is restricted to +a maximum of 32 interrupts (and must be a power of two). In addition, the +MSI interrupt vectors must be allocated consecutively, so the system might +not be able to allocate as many vectors for MSI as it could for MSI-X. On +some platforms, MSI interrupts must all be targeted at the same set of CPUs +whereas MSI-X interrupts can all be targeted at different CPUs. + +If a device supports neither MSI-X or MSI it will fall back to a single +legacy IRQ vector. + +The typical usage of MSI or MSI-X interrupts is to allocate as many vectors +as possible, likely up to the limit supported by the device. If nvec is +larger than the number supported by the device it will automatically be +capped to the supported limit, so there is no need to query the number of +vectors supported beforehand: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) + if (nvec < 0) + goto out_err; + +If a driver is unable or unwilling to deal with a variable number of MSI +interrupts it can request a particular number of interrupts by passing that +number to pci_alloc_irq_vectors() function as both 'min_vecs' and +'max_vecs' parameters: + + ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +The most notorious example of the request type described above is enabling +the single MSI mode for a device. It could be done by passing two 1s as +'min_vecs' and 'max_vecs': + + ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); + if (ret < 0) + goto out_err; + +Some devices might not support using legacy line interrupts, in which case +the driver can specify that only MSI or MSI-X is acceptable: + + nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); + if (nvec < 0) + goto out_err; + +4.3 Legacy APIs + +The following old APIs to enable and disable MSI or MSI-X interrupts should +not be used in new code: + + pci_enable_msi() /* deprecated */ + pci_enable_msi_range() /* deprecated */ + pci_enable_msi_exact() /* deprecated */ + pci_disable_msi() /* deprecated */ + pci_enable_msix_range() /* deprecated */ + pci_enable_msix_exact() /* deprecated */ + pci_disable_msix() /* deprecated */ + +Additionally there are APIs to provide the number of supported MSI or MSI-X +vectors: pci_msi_vec_count() and pci_msix_vec_count(). In general these +should be avoided in favor of letting pci_alloc_irq_vectors() cap the +number of vectors. If you have a legitimate special use case for the count +of vectors we might have to revisit that decision and add a +pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently. + +4.4 Considerations when using MSIs + +4.4.1 Spinlocks + +Most device drivers have a per-device spinlock which is taken in the +interrupt handler. With pin-based interrupts or a single MSI, it is not +necessary to disable interrupts (Linux guarantees the same interrupt will +not be re-entered). If a device uses multiple interrupts, the driver +must disable interrupts while the lock is held. If the device sends +a different interrupt, the driver will deadlock trying to recursively +acquire the spinlock. Such deadlocks can be avoided by using +spin_lock_irqsave() or spin_lock_irq() which disable local interrupts +and acquire the lock (see Documentation/DocBook/kernel-locking). + +4.5 How to tell whether MSI/MSI-X is enabled on a device + +Using 'lspci -v' (as root) may show some devices with "MSI", "Message +Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities +has an 'Enable' flag which is followed with either "+" (enabled) +or "-" (disabled). + + +5. MSI quirks + +Several PCI chipsets or devices are known not to support MSIs. +The PCI stack provides three ways to disable MSIs: + +1. globally +2. on all devices behind a specific bridge +3. on a single device + +5.1. Disabling MSIs globally + +Some host chipsets simply don't support MSIs properly. If we're +lucky, the manufacturer knows this and has indicated it in the ACPI +FADT table. In this case, Linux automatically disables MSIs. +Some boards don't include this information in the table and so we have +to detect them ourselves. The complete list of these is found near the +quirk_disable_all_msi() function in drivers/pci/quirks.c. + +If you have a board which has problems with MSIs, you can pass pci=nomsi +on the kernel command line to disable MSIs on all devices. It would be +in your best interests to report the problem to linux-pci@vger.kernel.org +including a full 'lspci -v' so we can add the quirks to the kernel. + +5.2. Disabling MSIs below a bridge + +Some PCI bridges are not able to route MSIs between busses properly. +In this case, MSIs must be disabled on all devices behind the bridge. + +Some bridges allow you to enable MSIs by changing some bits in their +PCI configuration space (especially the Hypertransport chipsets such +as the nVidia nForce and Serverworks HT2000). As with host chipsets, +Linux mostly knows about them and automatically enables MSIs if it can. +If you have a bridge unknown to Linux, you can enable +MSIs in configuration space using whatever method you know works, then +enable MSIs on that bridge by doing: + + echo 1 > /sys/bus/pci/devices/$bridge/msi_bus + +where $bridge is the PCI address of the bridge you've enabled (eg +0000:00:0e.0). + +To disable MSIs, echo 0 instead of 1. Changing this value should be +done with caution as it could break interrupt handling for all devices +below this bridge. + +Again, please notify linux-pci@vger.kernel.org of any bridges that need +special handling. + +5.3. Disabling MSIs on a single device + +Some devices are known to have faulty MSI implementations. Usually this +is handled in the individual device driver, but occasionally it's necessary +to handle this with a quirk. Some drivers have an option to disable use +of MSI. While this is a convenient workaround for the driver author, +it is not good practice, and should not be emulated. + +5.4. Finding why MSIs are disabled on a device + +From the above three sections, you can see that there are many reasons +why MSIs may not be enabled for a given device. Your first step should +be to examine your dmesg carefully to determine whether MSIs are enabled +for your machine. You should also check your .config to be sure you +have enabled CONFIG_PCI_MSI. + +Then, 'lspci -t' gives the list of bridges above a device. Reading +/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) +or disabled (0). If 0 is found in any of the msi_bus files belonging +to bridges between the PCI root and the device, MSIs are disabled. + +It is also worth checking the device driver to see whether it supports MSIs. +For example, it may contain calls to pci_enable_msi_range() or +pci_enable_msix_range().
diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.txt new file mode 100644 index 0000000..6bd5f37 --- /dev/null +++ b/Documentation/PCI/PCIEBUS-HOWTO.txt
@@ -0,0 +1,217 @@ + The PCI Express Port Bus Driver Guide HOWTO + Tom L Nguyen tom.l.nguyen@intel.com + 11/03/2004 + +1. About this guide + +This guide describes the basics of the PCI Express Port Bus driver +and provides information on how to enable the service drivers to +register/unregister with the PCI Express Port Bus Driver. + +2. Copyright 2004 Intel Corporation + +3. What is the PCI Express Port Bus Driver + +A PCI Express Port is a logical PCI-PCI Bridge structure. There +are two types of PCI Express Port: the Root Port and the Switch +Port. The Root Port originates a PCI Express link from a PCI Express +Root Complex and the Switch Port connects PCI Express links to +internal logical PCI buses. The Switch Port, which has its secondary +bus representing the switch's internal routing logic, is called the +switch's Upstream Port. The switch's Downstream Port is bridging from +switch's internal routing bus to a bus representing the downstream +PCI Express link from the PCI Express Switch. + +A PCI Express Port can provide up to four distinct functions, +referred to in this document as services, depending on its port type. +PCI Express Port's services include native hotplug support (HP), +power management event support (PME), advanced error reporting +support (AER), and virtual channel support (VC). These services may +be handled by a single complex driver or be individually distributed +and handled by corresponding service drivers. + +4. Why use the PCI Express Port Bus Driver? + +In existing Linux kernels, the Linux Device Driver Model allows a +physical device to be handled by only a single driver. The PCI +Express Port is a PCI-PCI Bridge device with multiple distinct +services. To maintain a clean and simple solution each service +may have its own software service driver. In this case several +service drivers will compete for a single PCI-PCI Bridge device. +For example, if the PCI Express Root Port native hotplug service +driver is loaded first, it claims a PCI-PCI Bridge Root Port. The +kernel therefore does not load other service drivers for that Root +Port. In other words, it is impossible to have multiple service +drivers load and run on a PCI-PCI Bridge device simultaneously +using the current driver model. + +To enable multiple service drivers running simultaneously requires +having a PCI Express Port Bus driver, which manages all populated +PCI Express Ports and distributes all provided service requests +to the corresponding service drivers as required. Some key +advantages of using the PCI Express Port Bus driver are listed below: + + - Allow multiple service drivers to run simultaneously on + a PCI-PCI Bridge Port device. + + - Allow service drivers implemented in an independent + staged approach. + + - Allow one service driver to run on multiple PCI-PCI Bridge + Port devices. + + - Manage and distribute resources of a PCI-PCI Bridge Port + device to requested service drivers. + +5. Configuring the PCI Express Port Bus Driver vs. Service Drivers + +5.1 Including the PCI Express Port Bus Driver Support into the Kernel + +Including the PCI Express Port Bus driver depends on whether the PCI +Express support is included in the kernel config. The kernel will +automatically include the PCI Express Port Bus driver as a kernel +driver when the PCI Express support is enabled in the kernel. + +5.2 Enabling Service Driver Support + +PCI device drivers are implemented based on Linux Device Driver Model. +All service drivers are PCI device drivers. As discussed above, it is +impossible to load any service driver once the kernel has loaded the +PCI Express Port Bus Driver. To meet the PCI Express Port Bus Driver +Model requires some minimal changes on existing service drivers that +imposes no impact on the functionality of existing service drivers. + +A service driver is required to use the two APIs shown below to +register its service with the PCI Express Port Bus driver (see +section 5.2.1 & 5.2.2). It is important that a service driver +initializes the pcie_port_service_driver data structure, included in +header file /include/linux/pcieport_if.h, before calling these APIs. +Failure to do so will result an identity mismatch, which prevents +the PCI Express Port Bus driver from loading a service driver. + +5.2.1 pcie_port_service_register + +int pcie_port_service_register(struct pcie_port_service_driver *new) + +This API replaces the Linux Driver Model's pci_register_driver API. A +service driver should always calls pcie_port_service_register at +module init. Note that after service driver being loaded, calls +such as pci_enable_device(dev) and pci_set_master(dev) are no longer +necessary since these calls are executed by the PCI Port Bus driver. + +5.2.2 pcie_port_service_unregister + +void pcie_port_service_unregister(struct pcie_port_service_driver *new) + +pcie_port_service_unregister replaces the Linux Driver Model's +pci_unregister_driver. It's always called by service driver when a +module exits. + +5.2.3 Sample Code + +Below is sample service driver code to initialize the port service +driver data structure. + +static struct pcie_port_service_id service_id[] = { { + .vendor = PCI_ANY_ID, + .device = PCI_ANY_ID, + .port_type = PCIE_RC_PORT, + .service_type = PCIE_PORT_SERVICE_AER, + }, { /* end: all zeroes */ } +}; + +static struct pcie_port_service_driver root_aerdrv = { + .name = (char *)device_name, + .id_table = &service_id[0], + + .probe = aerdrv_load, + .remove = aerdrv_unload, + + .suspend = aerdrv_suspend, + .resume = aerdrv_resume, +}; + +Below is a sample code for registering/unregistering a service +driver. + +static int __init aerdrv_service_init(void) +{ + int retval = 0; + + retval = pcie_port_service_register(&root_aerdrv); + if (!retval) { + /* + * FIX ME + */ + } + return retval; +} + +static void __exit aerdrv_service_exit(void) +{ + pcie_port_service_unregister(&root_aerdrv); +} + +module_init(aerdrv_service_init); +module_exit(aerdrv_service_exit); + +6. Possible Resource Conflicts + +Since all service drivers of a PCI-PCI Bridge Port device are +allowed to run simultaneously, below lists a few of possible resource +conflicts with proposed solutions. + +6.1 MSI Vector Resource + +The MSI capability structure enables a device software driver to call +pci_enable_msi to request MSI based interrupts. Once MSI interrupts +are enabled on a device, it stays in this mode until a device driver +calls pci_disable_msi to disable MSI interrupts and revert back to +INTx emulation mode. Since service drivers of the same PCI-PCI Bridge +port share the same physical device, if an individual service driver +calls pci_enable_msi/pci_disable_msi it may result unpredictable +behavior. For example, two service drivers run simultaneously on the +same physical Root Port. Both service drivers call pci_enable_msi to +request MSI based interrupts. A service driver may not know whether +any other service drivers have run on this Root Port. If either one +of them calls pci_disable_msi, it puts the other service driver +in a wrong interrupt mode. + +To avoid this situation all service drivers are not permitted to +switch interrupt mode on its device. The PCI Express Port Bus driver +is responsible for determining the interrupt mode and this should be +transparent to service drivers. Service drivers need to know only +the vector IRQ assigned to the field irq of struct pcie_device, which +is passed in when the PCI Express Port Bus driver probes each service +driver. Service drivers should use (struct pcie_device*)dev->irq to +call request_irq/free_irq. In addition, the interrupt mode is stored +in the field interrupt_mode of struct pcie_device. + +6.2 MSI-X Vector Resources + +Similar to the MSI a device driver for an MSI-X capable device can +call pci_enable_msix to request MSI-X interrupts. All service drivers +are not permitted to switch interrupt mode on its device. The PCI +Express Port Bus driver is responsible for determining the interrupt +mode and this should be transparent to service drivers. Any attempt +by service driver to call pci_enable_msix/pci_disable_msix may +result unpredictable behavior. Service drivers should use +(struct pcie_device*)dev->irq and call request_irq/free_irq. + +6.3 PCI Memory/IO Mapped Regions + +Service drivers for PCI Express Power Management (PME), Advanced +Error Reporting (AER), Hot-Plug (HP) and Virtual Channel (VC) access +PCI configuration space on the PCI Express port. In all cases the +registers accessed are independent of each other. This patch assumes +that all service drivers will be well behaved and not overwrite +other service driver's configuration settings. + +6.4 PCI Config Registers + +Each service driver runs its PCI config operations on its own +capability structure except the PCI Express capability structure, in +which Root Control register and Device Control register are shared +between PME and AER. This patch assumes that all service drivers +will be well behaved and not overwrite other service driver's +configuration settings.
diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt new file mode 100644 index 0000000..ac26869 --- /dev/null +++ b/Documentation/PCI/pci-error-recovery.txt
@@ -0,0 +1,431 @@ + + PCI Error Recovery + ------------------ + February 2, 2006 + + Current document maintainer: + Linas Vepstas <linasvepstas@gmail.com> + updated by Richard Lary <rlary@us.ibm.com> + and Mike Mason <mmlnx@us.ibm.com> on 27-Jul-2009 + + +Many PCI bus controllers are able to detect a variety of hardware +PCI errors on the bus, such as parity errors on the data and address +busses, as well as SERR and PERR errors. Some of the more advanced +chipsets are able to deal with these errors; these include PCI-E chipsets, +and the PCI-host bridges found on IBM Power4, Power5 and Power6-based +pSeries boxes. A typical action taken is to disconnect the affected device, +halting all I/O to it. The goal of a disconnection is to avoid system +corruption; for example, to halt system memory corruption due to DMA's +to "wild" addresses. Typically, a reconnection mechanism is also +offered, so that the affected PCI device(s) are reset and put back +into working condition. The reset phase requires coordination +between the affected device drivers and the PCI controller chip. +This document describes a generic API for notifying device drivers +of a bus disconnection, and then performing error recovery. +This API is currently implemented in the 2.6.16 and later kernels. + +Reporting and recovery is performed in several steps. First, when +a PCI hardware error has resulted in a bus disconnect, that event +is reported as soon as possible to all affected device drivers, +including multiple instances of a device driver on multi-function +cards. This allows device drivers to avoid deadlocking in spinloops, +waiting for some i/o-space register to change, when it never will. +It also gives the drivers a chance to defer incoming I/O as +needed. + +Next, recovery is performed in several stages. Most of the complexity +is forced by the need to handle multi-function devices, that is, +devices that have multiple device drivers associated with them. +In the first stage, each driver is allowed to indicate what type +of reset it desires, the choices being a simple re-enabling of I/O +or requesting a slot reset. + +If any driver requests a slot reset, that is what will be done. + +After a reset and/or a re-enabling of I/O, all drivers are +again notified, so that they may then perform any device setup/config +that may be required. After these have all completed, a final +"resume normal operations" event is sent out. + +The biggest reason for choosing a kernel-based implementation rather +than a user-space implementation was the need to deal with bus +disconnects of PCI devices attached to storage media, and, in particular, +disconnects from devices holding the root file system. If the root +file system is disconnected, a user-space mechanism would have to go +through a large number of contortions to complete recovery. Almost all +of the current Linux file systems are not tolerant of disconnection +from/reconnection to their underlying block device. By contrast, +bus errors are easy to manage in the device driver. Indeed, most +device drivers already handle very similar recovery procedures; +for example, the SCSI-generic layer already provides significant +mechanisms for dealing with SCSI bus errors and SCSI bus resets. + + +Detailed Design +--------------- +Design and implementation details below, based on a chain of +public email discussions with Ben Herrenschmidt, circa 5 April 2005. + +The error recovery API support is exposed to the driver in the form of +a structure of function pointers pointed to by a new field in struct +pci_driver. A driver that fails to provide the structure is "non-aware", +and the actual recovery steps taken are platform dependent. The +arch/powerpc implementation will simulate a PCI hotplug remove/add. + +This structure has the form: +struct pci_error_handlers +{ + int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); + int (*mmio_enabled)(struct pci_dev *dev); + int (*link_reset)(struct pci_dev *dev); + int (*slot_reset)(struct pci_dev *dev); + void (*resume)(struct pci_dev *dev); +}; + +The possible channel states are: +enum pci_channel_state { + pci_channel_io_normal, /* I/O channel is in normal state */ + pci_channel_io_frozen, /* I/O to channel is blocked */ + pci_channel_io_perm_failure, /* PCI card is dead */ +}; + +Possible return values are: +enum pci_ers_result { + PCI_ERS_RESULT_NONE, /* no result/none/not supported in device driver */ + PCI_ERS_RESULT_CAN_RECOVER, /* Device driver can recover without slot reset */ + PCI_ERS_RESULT_NEED_RESET, /* Device driver wants slot to be reset. */ + PCI_ERS_RESULT_DISCONNECT, /* Device has completely failed, is unrecoverable */ + PCI_ERS_RESULT_RECOVERED, /* Device driver is fully recovered and operational */ +}; + +A driver does not have to implement all of these callbacks; however, +if it implements any, it must implement error_detected(). If a callback +is not implemented, the corresponding feature is considered unsupported. +For example, if mmio_enabled() and resume() aren't there, then it +is assumed that the driver is not doing any direct recovery and requires +a slot reset. If link_reset() is not implemented, the card is assumed to +not care about link resets. Typically a driver will want to know about +a slot_reset(). + +The actual steps taken by a platform to recover from a PCI error +event will be platform-dependent, but will follow the general +sequence described below. + +STEP 0: Error Event +------------------- +A PCI bus error is detected by the PCI hardware. On powerpc, the slot +is isolated, in that all I/O is blocked: all reads return 0xffffffff, +all writes are ignored. + + +STEP 1: Notification +-------------------- +Platform calls the error_detected() callback on every instance of +every driver affected by the error. + +At this point, the device might not be accessible anymore, depending on +the platform (the slot will be isolated on powerpc). The driver may +already have "noticed" the error because of a failing I/O, but this +is the proper "synchronization point", that is, it gives the driver +a chance to cleanup, waiting for pending stuff (timers, whatever, etc...) +to complete; it can take semaphores, schedule, etc... everything but +touch the device. Within this function and after it returns, the driver +shouldn't do any new IOs. Called in task context. This is sort of a +"quiesce" point. See note about interrupts at the end of this doc. + +All drivers participating in this system must implement this call. +The driver must return one of the following result codes: + - PCI_ERS_RESULT_CAN_RECOVER: + Driver returns this if it thinks it might be able to recover + the HW by just banging IOs or if it wants to be given + a chance to extract some diagnostic information (see + mmio_enable, below). + - PCI_ERS_RESULT_NEED_RESET: + Driver returns this if it can't recover without a + slot reset. + - PCI_ERS_RESULT_DISCONNECT: + Driver returns this if it doesn't want to recover at all. + +The next step taken will depend on the result codes returned by the +drivers. + +If all drivers on the segment/slot return PCI_ERS_RESULT_CAN_RECOVER, +then the platform should re-enable IOs on the slot (or do nothing in +particular, if the platform doesn't isolate slots), and recovery +proceeds to STEP 2 (MMIO Enable). + +If any driver requested a slot reset (by returning PCI_ERS_RESULT_NEED_RESET), +then recovery proceeds to STEP 4 (Slot Reset). + +If the platform is unable to recover the slot, the next step +is STEP 6 (Permanent Failure). + +>>> The current powerpc implementation assumes that a device driver will +>>> *not* schedule or semaphore in this routine; the current powerpc +>>> implementation uses one kernel thread to notify all devices; +>>> thus, if one device sleeps/schedules, all devices are affected. +>>> Doing better requires complex multi-threaded logic in the error +>>> recovery implementation (e.g. waiting for all notification threads +>>> to "join" before proceeding with recovery.) This seems excessively +>>> complex and not worth implementing. + +>>> The current powerpc implementation doesn't much care if the device +>>> attempts I/O at this point, or not. I/O's will fail, returning +>>> a value of 0xff on read, and writes will be dropped. If more than +>>> EEH_MAX_FAILS I/O's are attempted to a frozen adapter, EEH +>>> assumes that the device driver has gone into an infinite loop +>>> and prints an error to syslog. A reboot is then required to +>>> get the device working again. + +STEP 2: MMIO Enabled +------------------- +The platform re-enables MMIO to the device (but typically not the +DMA), and then calls the mmio_enabled() callback on all affected +device drivers. + +This is the "early recovery" call. IOs are allowed again, but DMA is +not, with some restrictions. This is NOT a callback for the driver to +start operations again, only to peek/poke at the device, extract diagnostic +information, if any, and eventually do things like trigger a device local +reset or some such, but not restart operations. This callback is made if +all drivers on a segment agree that they can try to recover and if no automatic +link reset was performed by the HW. If the platform can't just re-enable IOs +without a slot reset or a link reset, it will not call this callback, and +instead will have gone directly to STEP 3 (Link Reset) or STEP 4 (Slot Reset) + +>>> The following is proposed; no platform implements this yet: +>>> Proposal: All I/O's should be done _synchronously_ from within +>>> this callback, errors triggered by them will be returned via +>>> the normal pci_check_whatever() API, no new error_detected() +>>> callback will be issued due to an error happening here. However, +>>> such an error might cause IOs to be re-blocked for the whole +>>> segment, and thus invalidate the recovery that other devices +>>> on the same segment might have done, forcing the whole segment +>>> into one of the next states, that is, link reset or slot reset. + +The driver should return one of the following result codes: + - PCI_ERS_RESULT_RECOVERED + Driver returns this if it thinks the device is fully + functional and thinks it is ready to start + normal driver operations again. There is no + guarantee that the driver will actually be + allowed to proceed, as another driver on the + same segment might have failed and thus triggered a + slot reset on platforms that support it. + + - PCI_ERS_RESULT_NEED_RESET + Driver returns this if it thinks the device is not + recoverable in its current state and it needs a slot + reset to proceed. + + - PCI_ERS_RESULT_DISCONNECT + Same as above. Total failure, no recovery even after + reset driver dead. (To be defined more precisely) + +The next step taken depends on the results returned by the drivers. +If all drivers returned PCI_ERS_RESULT_RECOVERED, then the platform +proceeds to either STEP3 (Link Reset) or to STEP 5 (Resume Operations). + +If any driver returned PCI_ERS_RESULT_NEED_RESET, then the platform +proceeds to STEP 4 (Slot Reset) + +STEP 3: Link Reset +------------------ +The platform resets the link, and then calls the link_reset() callback +on all affected device drivers. This is a PCI-Express specific state +and is done whenever a non-fatal error has been detected that can be +"solved" by resetting the link. This call informs the driver of the +reset and the driver should check to see if the device appears to be +in working condition. + +The driver is not supposed to restart normal driver I/O operations +at this point. It should limit itself to "probing" the device to +check its recoverability status. If all is right, then the platform +will call resume() once all drivers have ack'd link_reset(). + + Result codes: + (identical to STEP 3 (MMIO Enabled) + +The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5 +(Resume Operations). + +>>> The current powerpc implementation does not implement this callback. + +STEP 4: Slot Reset +------------------ + +In response to a return value of PCI_ERS_RESULT_NEED_RESET, the +the platform will perform a slot reset on the requesting PCI device(s). +The actual steps taken by a platform to perform a slot reset +will be platform-dependent. Upon completion of slot reset, the +platform will call the device slot_reset() callback. + +Powerpc platforms implement two levels of slot reset: +soft reset(default) and fundamental(optional) reset. + +Powerpc soft reset consists of asserting the adapter #RST line and then +restoring the PCI BAR's and PCI configuration header to a state +that is equivalent to what it would be after a fresh system +power-on followed by power-on BIOS/system firmware initialization. +Soft reset is also known as hot-reset. + +Powerpc fundamental reset is supported by PCI Express cards only +and results in device's state machines, hardware logic, port states and +configuration registers to initialize to their default conditions. + +For most PCI devices, a soft reset will be sufficient for recovery. +Optional fundamental reset is provided to support a limited number +of PCI Express PCI devices for which a soft reset is not sufficient +for recovery. + +If the platform supports PCI hotplug, then the reset might be +performed by toggling the slot electrical power off/on. + +It is important for the platform to restore the PCI config space +to the "fresh poweron" state, rather than the "last state". After +a slot reset, the device driver will almost always use its standard +device initialization routines, and an unusual config space setup +may result in hung devices, kernel panics, or silent data corruption. + +This call gives drivers the chance to re-initialize the hardware +(re-download firmware, etc.). At this point, the driver may assume +that the card is in a fresh state and is fully functional. The slot +is unfrozen and the driver has full access to PCI config space, +memory mapped I/O space and DMA. Interrupts (Legacy, MSI, or MSI-X) +will also be available. + +Drivers should not restart normal I/O processing operations +at this point. If all device drivers report success on this +callback, the platform will call resume() to complete the sequence, +and let the driver restart normal I/O processing. + +A driver can still return a critical failure for this function if +it can't get the device operational after reset. If the platform +previously tried a soft reset, it might now try a hard reset (power +cycle) and then call slot_reset() again. It the device still can't +be recovered, there is nothing more that can be done; the platform +will typically report a "permanent failure" in such a case. The +device will be considered "dead" in this case. + +Drivers for multi-function cards will need to coordinate among +themselves as to which driver instance will perform any "one-shot" +or global device initialization. For example, the Symbios sym53cxx2 +driver performs device init only from PCI function 0: + ++ if (PCI_FUNC(pdev->devfn) == 0) ++ sym_reset_scsi_bus(np, 0); + + Result codes: + - PCI_ERS_RESULT_DISCONNECT + Same as above. + +Drivers for PCI Express cards that require a fundamental reset must +set the needs_freset bit in the pci_dev structure in their probe function. +For example, the QLogic qla2xxx driver sets the needs_freset bit for certain +PCI card types: + ++ /* Set EEH reset type to fundamental if required by hba */ ++ if (IS_QLA24XX(ha) || IS_QLA25XX(ha) || IS_QLA81XX(ha)) ++ pdev->needs_freset = 1; ++ + +Platform proceeds either to STEP 5 (Resume Operations) or STEP 6 (Permanent +Failure). + +>>> The current powerpc implementation does not try a power-cycle +>>> reset if the driver returned PCI_ERS_RESULT_DISCONNECT. +>>> However, it probably should. + + +STEP 5: Resume Operations +------------------------- +The platform will call the resume() callback on all affected device +drivers if all drivers on the segment have returned +PCI_ERS_RESULT_RECOVERED from one of the 3 previous callbacks. +The goal of this callback is to tell the driver to restart activity, +that everything is back and running. This callback does not return +a result code. + +At this point, if a new error happens, the platform will restart +a new error recovery sequence. + +STEP 6: Permanent Failure +------------------------- +A "permanent failure" has occurred, and the platform cannot recover +the device. The platform will call error_detected() with a +pci_channel_state value of pci_channel_io_perm_failure. + +The device driver should, at this point, assume the worst. It should +cancel all pending I/O, refuse all new I/O, returning -EIO to +higher layers. The device driver should then clean up all of its +memory and remove itself from kernel operations, much as it would +during system shutdown. + +The platform will typically notify the system operator of the +permanent failure in some way. If the device is hotplug-capable, +the operator will probably want to remove and replace the device. +Note, however, not all failures are truly "permanent". Some are +caused by over-heating, some by a poorly seated card. Many +PCI error events are caused by software bugs, e.g. DMA's to +wild addresses or bogus split transactions due to programming +errors. See the discussion in powerpc/eeh-pci-error-recovery.txt +for additional detail on real-life experience of the causes of +software errors. + + +Conclusion; General Remarks +--------------------------- +The way the callbacks are called is platform policy. A platform with +no slot reset capability may want to just "ignore" drivers that can't +recover (disconnect them) and try to let other cards on the same segment +recover. Keep in mind that in most real life cases, though, there will +be only one driver per segment. + +Now, a note about interrupts. If you get an interrupt and your +device is dead or has been isolated, there is a problem :) +The current policy is to turn this into a platform policy. +That is, the recovery API only requires that: + + - There is no guarantee that interrupt delivery can proceed from any +device on the segment starting from the error detection and until the +slot_reset callback is called, at which point interrupts are expected +to be fully operational. + + - There is no guarantee that interrupt delivery is stopped, that is, +a driver that gets an interrupt after detecting an error, or that detects +an error within the interrupt handler such that it prevents proper +ack'ing of the interrupt (and thus removal of the source) should just +return IRQ_NOTHANDLED. It's up to the platform to deal with that +condition, typically by masking the IRQ source during the duration of +the error handling. It is expected that the platform "knows" which +interrupts are routed to error-management capable slots and can deal +with temporarily disabling that IRQ number during error processing (this +isn't terribly complex). That means some IRQ latency for other devices +sharing the interrupt, but there is simply no other way. High end +platforms aren't supposed to share interrupts between many devices +anyway :) + +>>> Implementation details for the powerpc platform are discussed in +>>> the file Documentation/powerpc/eeh-pci-error-recovery.txt + +>>> As of this writing, there is a growing list of device drivers with +>>> patches implementing error recovery. Not all of these patches are in +>>> mainline yet. These may be used as "examples": +>>> +>>> drivers/scsi/ipr +>>> drivers/scsi/sym53c8xx_2 +>>> drivers/scsi/qla2xxx +>>> drivers/scsi/lpfc +>>> drivers/next/bnx2.c +>>> drivers/next/e100.c +>>> drivers/net/e1000 +>>> drivers/net/e1000e +>>> drivers/net/ixgb +>>> drivers/net/ixgbe +>>> drivers/net/cxgb3 +>>> drivers/net/s2io.c +>>> drivers/net/qlge + +The End +-------
diff --git a/Documentation/PCI/pci-iov-howto.txt b/Documentation/PCI/pci-iov-howto.txt new file mode 100644 index 0000000..2d91ae2 --- /dev/null +++ b/Documentation/PCI/pci-iov-howto.txt
@@ -0,0 +1,135 @@ + PCI Express I/O Virtualization Howto + Copyright (C) 2009 Intel Corporation + Yu Zhao <yu.zhao@intel.com> + + Update: November 2012 + -- sysfs-based SRIOV enable-/disable-ment + Donald Dutile <ddutile@redhat.com> + +1. Overview + +1.1 What is SR-IOV + +Single Root I/O Virtualization (SR-IOV) is a PCI Express Extended +capability which makes one physical device appear as multiple virtual +devices. The physical device is referred to as Physical Function (PF) +while the virtual devices are referred to as Virtual Functions (VF). +Allocation of the VF can be dynamically controlled by the PF via +registers encapsulated in the capability. By default, this feature is +not enabled and the PF behaves as traditional PCIe device. Once it's +turned on, each VF's PCI configuration space can be accessed by its own +Bus, Device and Function Number (Routing ID). And each VF also has PCI +Memory Space, which is used to map its register set. VF device driver +operates on the register set so it can be functional and appear as a +real existing PCI device. + +2. User Guide + +2.1 How can I enable SR-IOV capability + +Multiple methods are available for SR-IOV enablement. +In the first method, the device driver (PF driver) will control the +enabling and disabling of the capability via API provided by SR-IOV core. +If the hardware has SR-IOV capability, loading its PF driver would +enable it and all VFs associated with the PF. Some PF drivers require +a module parameter to be set to determine the number of VFs to enable. +In the second method, a write to the sysfs file sriov_numvfs will +enable and disable the VFs associated with a PCIe PF. This method +enables per-PF, VF enable/disable values versus the first method, +which applies to all PFs of the same device. Additionally, the +PCI SRIOV core support ensures that enable/disable operations are +valid to reduce duplication in multiple drivers for the same +checks, e.g., check numvfs == 0 if enabling VFs, ensure +numvfs <= totalvfs. +The second method is the recommended method for new/future VF devices. + +2.2 How can I use the Virtual Functions + +The VF is treated as hot-plugged PCI devices in the kernel, so they +should be able to work in the same way as real PCI devices. The VF +requires device driver that is same as a normal PCI device's. + +3. Developer Guide + +3.1 SR-IOV API + +To enable SR-IOV capability: +(a) For the first method, in the driver: + int pci_enable_sriov(struct pci_dev *dev, int nr_virtfn); + 'nr_virtfn' is number of VFs to be enabled. +(b) For the second method, from sysfs: + echo 'nr_virtfn' > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +To disable SR-IOV capability: +(a) For the first method, in the driver: + void pci_disable_sriov(struct pci_dev *dev); +(b) For the second method, from sysfs: + echo 0 > \ + /sys/bus/pci/devices/<DOMAIN:BUS:DEVICE.FUNCTION>/sriov_numvfs + +3.2 Usage example + +Following piece of code illustrates the usage of the SR-IOV API. + +static int dev_probe(struct pci_dev *dev, const struct pci_device_id *id) +{ + pci_enable_sriov(dev, NR_VIRTFN); + + ... + + return 0; +} + +static void dev_remove(struct pci_dev *dev) +{ + pci_disable_sriov(dev); + + ... +} + +static int dev_suspend(struct pci_dev *dev, pm_message_t state) +{ + ... + + return 0; +} + +static int dev_resume(struct pci_dev *dev) +{ + ... + + return 0; +} + +static void dev_shutdown(struct pci_dev *dev) +{ + ... +} + +static int dev_sriov_configure(struct pci_dev *dev, int numvfs) +{ + if (numvfs > 0) { + ... + pci_enable_sriov(dev, numvfs); + ... + return numvfs; + } + if (numvfs == 0) { + .... + pci_disable_sriov(dev); + ... + return 0; + } +} + +static struct pci_driver dev_driver = { + .name = "SR-IOV Physical Function driver", + .id_table = dev_id_table, + .probe = dev_probe, + .remove = dev_remove, + .suspend = dev_suspend, + .resume = dev_resume, + .shutdown = dev_shutdown, + .sriov_configure = dev_sriov_configure, +};
diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt new file mode 100644 index 0000000..77f49dc --- /dev/null +++ b/Documentation/PCI/pci.txt
@@ -0,0 +1,634 @@ + + How To Write Linux PCI Drivers + + by Martin Mares <mj@ucw.cz> on 07-Feb-2000 + updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The world of PCI is vast and full of (mostly unpleasant) surprises. +Since each CPU architecture implements different chip-sets and PCI devices +have different requirements (erm, "features"), the result is the PCI support +in the Linux kernel is not as trivial as one would wish. This short paper +tries to introduce all potential driver authors to Linux APIs for +PCI device drivers. + +A more complete resource is the third edition of "Linux Device Drivers" +by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. +LDD3 is available for free (under Creative Commons License) from: + + http://lwn.net/Kernel/LDD3/ + +However, keep in mind that all documents are subject to "bit rot". +Refer to the source code if things are not working as described here. + +Please send questions/comments/patches about Linux PCI API to the +"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. + + + +0. Structure of PCI drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +PCI drivers "discover" PCI devices in a system via pci_register_driver(). +Actually, it's the other way around. When the PCI generic code discovers +a new device, the driver with a matching "description" will be notified. +Details on this below. + +pci_register_driver() leaves most of the probing for devices to +the PCI layer and supports online insertion/removal of devices [thus +supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. +pci_register_driver() call requires passing in a table of function +pointers and thus dictates the high level structure of a driver. + +Once the driver knows about a PCI device and takes ownership, the +driver generally needs to perform the following initialization: + + Enable the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines + +When done using the device, and perhaps the module needs to be unloaded, +the driver needs to take the follow steps: + Disable the device from generating IRQs + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and coherent) + Unregister from other subsystems (e.g. scsi or netdev) + Release MMIO/IOP resources + Disable the device + +Most of these topics are covered in the following sections. +For the rest look at LDD3 or <linux/pci.h> . + +If the PCI subsystem is not configured (CONFIG_PCI is not set), most of +the PCI functions described below are defined as inline functions either +completely empty or just returning an appropriate error codes to avoid +lots of ifdefs in the drivers. + + + +1. pci_register_driver() call +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PCI device drivers call pci_register_driver() during their +initialization with a pointer to a structure describing the driver +(struct pci_driver): + + field name Description + ---------- ------------------------------------------------------ + id_table Pointer to table of device ID's the driver is + interested in. Most drivers should export this + table using MODULE_DEVICE_TABLE(pci,...). + + probe This probing function gets called (during execution + of pci_register_driver() for already existing + devices or later if a new device gets inserted) for + all PCI devices which match the ID table and are not + "owned" by the other drivers yet. This function gets + passed a "struct pci_dev *" for each device whose + entry in the ID table matches the device. The probe + function returns zero when the driver chooses to + take "ownership" of the device or an error code + (negative number) otherwise. + The probe function always gets called from process + context, so it can sleep. + + remove The remove() function gets called whenever a device + being handled by this driver is removed (either during + deregistration of the driver or when it's manually + pulled out of a hot-pluggable slot). + The remove function always gets called from process + context, so it can sleep. + + suspend Put device into low power state. + suspend_late Put device into low power state. + + resume_early Wake device from low power state. + resume Wake device from low power state. + + (Please see Documentation/power/pci.txt for descriptions + of PCI Power Management and the related functions.) + + shutdown Hook into reboot_notifier_list (kernel/sys.c). + Intended to stop any idling DMA operations. + Useful for enabling wake-on-lan (NIC) or changing + the power state of a device before reboot. + e.g. drivers/net/e100.c. + + err_handler See Documentation/PCI/pci-error-recovery.txt + + +The ID table is an array of struct pci_device_id entries ending with an +all-zero entry. Definitions with static const are generally preferred. + +Each entry consists of: + + vendor,device Vendor and device ID to match (or PCI_ANY_ID) + + subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) + subdevice, + + class Device class, subclass, and "interface" to match. + See Appendix D of the PCI Local Bus Spec or + include/linux/pci_ids.h for a full list of classes. + Most drivers do not need to specify class/class_mask + as vendor/device is normally sufficient. + + class_mask limit which sub-fields of the class field are compared. + See drivers/scsi/sym53c8xx_2/ for example of usage. + + driver_data Data private to the driver. + Most drivers don't need to use driver_data field. + Best practice is to use driver_data as an index + into a static list of equivalent device types, + instead of using it as a pointer. + + +Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up +a pci_device_id table. + +New PCI IDs may be added to a device driver pci_ids table at runtime +as shown below: + +echo "vendor device subvendor subdevice class class_mask driver_data" > \ +/sys/bus/pci/drivers/{driver}/new_id + +All fields are passed in as hexadecimal values (no leading 0x). +The vendor and device fields are mandatory, the others are optional. Users +need pass only as many optional fields as necessary: + o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) + o class and classmask fields default to 0 + o driver_data defaults to 0UL. + +Note that driver_data must match the value used by any of the pci_device_id +entries defined in the driver. This makes the driver_data field mandatory +if all the pci_device_id entries have a non-zero driver_data value. + +Once added, the driver probe routine will be invoked for any unclaimed +PCI devices listed in its (newly updated) pci_ids list. + +When the driver exits, it just calls pci_unregister_driver() and the PCI layer +automatically calls the remove hook for all devices handled by the driver. + + +1.1 "Attributes" for driver functions/data + +Please mark the initialization and cleanup functions where appropriate +(the corresponding macros are defined in <linux/init.h>): + + __init Initialization code. Thrown away after the driver + initializes. + __exit Exit code. Ignored for non-modular drivers. + +Tips on when/where to use the above attributes: + o The module_init()/module_exit() functions (and all + initialization functions called _only_ from these) + should be marked __init/__exit. + + o Do not mark the struct pci_driver. + + o Do NOT mark a function if you are not sure which mark to use. + Better to not mark the function than mark the function wrong. + + + +2. How to find PCI devices manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PCI drivers should have a really good reason for not using the +pci_register_driver() interface to search for PCI devices. +The main reason PCI devices are controlled by multiple drivers +is because one PCI device implements several different HW services. +E.g. combined serial/parallel port/floppy controller. + +A manual search may be performed using the following constructs: + +Searching by vendor and device ID: + + struct pci_dev *dev = NULL; + while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) + configure_device(dev); + +Searching by class ID (iterate in a similar way): + + pci_get_class(CLASS_ID, dev) + +Searching by both vendor/device and subsystem vendor/device ID: + + pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). + +You can use the constant PCI_ANY_ID as a wildcard replacement for +VENDOR_ID or DEVICE_ID. This allows searching for any device from a +specific vendor, for example. + +These functions are hotplug-safe. They increment the reference count on +the pci_dev that they return. You must eventually (possibly at module unload) +decrement the reference count on these devices by calling pci_dev_put(). + + + +3. Device Initialization Steps +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As noted in the introduction, most PCI drivers need the following steps +for device initialization: + + Enable the device + Request MMIO/IOP resources + Set the DMA mask size (for both coherent and streaming DMA) + Allocate and initialize shared control data (pci_allocate_coherent()) + Access device configuration space (if needed) + Register IRQ handler (request_irq()) + Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) + Enable DMA/processing engines. + +The driver can access PCI config space registers at any time. +(Well, almost. When running BIST, config space can go away...but +that will just result in a PCI Bus Master Abort and config reads +will return garbage). + + +3.1 Enable the PCI device +~~~~~~~~~~~~~~~~~~~~~~~~~ +Before touching any device registers, the driver needs to enable +the PCI device by calling pci_enable_device(). This will: + o wake up the device if it was in suspended state, + o allocate I/O and memory regions of the device (if BIOS did not), + o allocate an IRQ (if BIOS did not). + +NOTE: pci_enable_device() can fail! Check the return value. + +[ OS BUG: we don't check resource allocations before enabling those + resources. The sequence would make more sense if we called + pci_request_resources() before calling pci_enable_device(). + Currently, the device drivers can't detect the bug when when two + devices have been allocated the same range. This is not a common + problem and unlikely to get fixed soon. + + This has been discussed before but not changed as of 2.6.19: + http://lkml.org/lkml/2006/3/2/194 +] + +pci_set_master() will enable DMA by setting the bus master bit +in the PCI_COMMAND register. It also fixes the latency timer value if +it's set to something bogus by the BIOS. pci_clear_master() will +disable DMA by clearing the bus master bit. + +If the PCI device can use the PCI Memory-Write-Invalidate transaction, +call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval +and also ensures that the cache line size register is set correctly. +Check the return value of pci_set_mwi() as not all architectures +or chip-sets may support Memory-Write-Invalidate. Alternatively, +if Mem-Wr-Inval would be nice to have but is not required, call +pci_try_set_mwi() to have the system do its best effort at enabling +Mem-Wr-Inval. + + +3.2 Request MMIO/IOP resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Memory (MMIO), and I/O port addresses should NOT be read directly +from the PCI device config space. Use the values in the pci_dev structure +as the PCI "bus address" might have been remapped to a "host physical" +address by the arch/chip-set specific kernel support. + +See Documentation/io-mapping.txt for how to access device registers +or device memory. + +The device driver needs to call pci_request_region() to verify +no other device is already using the same address resource. +Conversely, drivers should call pci_release_region() AFTER +calling pci_disable_device(). +The idea is to prevent two devices colliding on the same address range. + +[ See OS BUG comment above. Currently (2.6.19), The driver can only + determine MMIO and IO Port resource availability _after_ calling + pci_enable_device(). ] + +Generic flavors of pci_request_region() are request_mem_region() +(for MMIO ranges) and request_region() (for IO Port ranges). +Use these for address resources that are not described by "normal" PCI +BARs. + +Also see pci_request_selected_regions() below. + + +3.3 Set the DMA mask size +~~~~~~~~~~~~~~~~~~~~~~~~~ +[ If anything below doesn't make sense, please refer to + Documentation/DMA-API.txt. This section is just a reminder that + drivers need to indicate DMA capabilities of the device and is not + an authoritative source for DMA interfaces. ] + +While all drivers should explicitly indicate the DMA capability +(e.g. 32 or 64 bit) of the PCI bus master, devices with more than +32-bit bus master capability for streaming data need the driver +to "register" this capability by calling pci_set_dma_mask() with +appropriate parameters. In general this allows more efficient DMA +on systems where System RAM exists above 4G _physical_ address. + +Drivers for all PCI-X and PCIe compliant devices must call +pci_set_dma_mask() as they are 64-bit DMA devices. + +Similarly, drivers must also "register" this capability if the device +can directly address "consistent memory" in System RAM above 4G physical +address by calling pci_set_consistent_dma_mask(). +Again, this includes drivers for all PCI-X and PCIe compliant devices. +Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are +64-bit DMA capable for payload ("streaming") data but not control +("consistent") data. + + +3.4 Setup shared control data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) +memory. See Documentation/DMA-API.txt for a full description of +the DMA APIs. This section is just a reminder that it needs to be done +before enabling DMA on the device. + + +3.5 Initialize device registers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some drivers will need specific "capability" fields programmed +or other "vendor specific" register initialized or reset. +E.g. clearing pending interrupts. + + +3.6 Register IRQ handler +~~~~~~~~~~~~~~~~~~~~~~~~ +While calling request_irq() is the last step described here, +this is often just another intermediate step to initialize a device. +This step can often be deferred until the device is opened for use. + +All interrupt handlers for IRQ lines should be registered with IRQF_SHARED +and use the devid to map IRQs to devices (remember that all PCI IRQ lines +can be shared). + +request_irq() will associate an interrupt handler and device handle +with an interrupt number. Historically interrupt numbers represent +IRQ lines which run from the PCI device to the Interrupt controller. +With MSI and MSI-X (more below) the interrupt number is a CPU "vector". + +request_irq() also enables the interrupt. Make sure the device is +quiesced and does not have any interrupts pending before registering +the interrupt handler. + +MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" +which deliver interrupts to the CPU via a DMA write to a Local APIC. +The fundamental difference between MSI and MSI-X is how multiple +"vectors" get allocated. MSI requires contiguous blocks of vectors +while MSI-X can allocate several individual ones. + +MSI capability can be enabled by calling pci_enable_msi() or +pci_enable_msix() before calling request_irq(). This causes +the PCI support to program CPU vector data into the PCI device +capability registers. + +If your PCI device supports both, try to enable MSI-X first. +Only one can be enabled at a time. Many architectures, chip-sets, +or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix +will fail. This is important to note since many drivers have +two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs. +They choose which handler to register with request_irq() based on the +return value from pci_enable_msi/msix(). + +There are (at least) two really good reasons for using MSI: +1) MSI is an exclusive interrupt vector by definition. + This means the interrupt handler doesn't have to verify + its device caused the interrupt. + +2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed + to be visible to the host CPU(s) when the MSI is delivered. This + is important for both data coherency and avoiding stale control data. + This guarantee allows the driver to omit MMIO reads to flush + the DMA stream. + +See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples +of MSI/MSI-X usage. + + + +4. PCI device shutdown +~~~~~~~~~~~~~~~~~~~~~~~ + +When a PCI device driver is being unloaded, most of the following +steps need to be performed: + + Disable the device from generating IRQs + Release the IRQ (free_irq()) + Stop all DMA activity + Release DMA buffers (both streaming and consistent) + Unregister from other subsystems (e.g. scsi or netdev) + Disable device from responding to MMIO/IO Port addresses + Release MMIO/IO Port resource(s) + + +4.1 Stop IRQs on the device +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How to do this is chip/device specific. If it's not done, it opens +the possibility of a "screaming interrupt" if (and only if) +the IRQ is shared with another device. + +When the shared IRQ handler is "unhooked", the remaining devices +using the same IRQ line will still need the IRQ enabled. Thus if the +"unhooked" device asserts IRQ line, the system will respond assuming +it was one of the remaining devices asserted the IRQ line. Since none +of the other devices will handle the IRQ, the system will "hang" until +it decides the IRQ isn't going to get handled and masks the IRQ (100,000 +iterations later). Once the shared IRQ is masked, the remaining devices +will stop functioning properly. Not a nice situation. + +This is another reason to use MSI or MSI-X if it's available. +MSI and MSI-X are defined to be exclusive interrupts and thus +are not susceptible to the "screaming interrupt" problem. + + +4.2 Release the IRQ +~~~~~~~~~~~~~~~~~~~ +Once the device is quiesced (no more IRQs), one can call free_irq(). +This function will return control once any pending IRQs are handled, +"unhook" the drivers IRQ handler from that IRQ, and finally release +the IRQ if no one else is using it. + + +4.3 Stop all DMA activity +~~~~~~~~~~~~~~~~~~~~~~~~~ +It's extremely important to stop all DMA operations BEFORE attempting +to deallocate DMA control data. Failure to do so can result in memory +corruption, hangs, and on some chip-sets a hard crash. + +Stopping DMA after stopping the IRQs can avoid races where the +IRQ handler might restart DMA engines. + +While this step sounds obvious and trivial, several "mature" drivers +didn't get this step right in the past. + + +4.4 Release DMA buffers +~~~~~~~~~~~~~~~~~~~~~~~ +Once DMA is stopped, clean up streaming DMA first. +I.e. unmap data buffers and return buffers to "upstream" +owners if there is one. + +Then clean up "consistent" buffers which contain the control data. + +See Documentation/DMA-API.txt for details on unmapping interfaces. + + +4.5 Unregister from other subsystems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Most low level PCI device drivers support some other subsystem +like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your +driver isn't losing resources from that other subsystem. +If this happens, typically the symptom is an Oops (panic) when +the subsystem attempts to call into a driver that has been unloaded. + + +4.6 Disable Device from responding to MMIO/IO Port addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +io_unmap() MMIO or IO Port resources and then call pci_disable_device(). +This is the symmetric opposite of pci_enable_device(). +Do not access device registers after calling pci_disable_device(). + + +4.7 Release MMIO/IO Port Resource(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Call pci_release_region() to mark the MMIO or IO Port range as available. +Failure to do so usually results in the inability to reload the driver. + + + +5. How to access PCI config space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use pci_(read|write)_config_(byte|word|dword) to access the config +space of a device represented by struct pci_dev *. All these functions return 0 +when successful or an error code (PCIBIOS_...) which can be translated to a text +string by pcibios_strerror. Most drivers expect that accesses to valid PCI +devices don't fail. + +If you don't have a struct pci_dev available, you can call +pci_bus_(read|write)_config_(byte|word|dword) to access a given device +and function on that bus. + +If you access fields in the standard portion of the config header, please +use symbolic names of locations and bits declared in <linux/pci.h>. + +If you need to access Extended PCI Capability registers, just call +pci_find_capability() for the particular capability and it will find the +corresponding register block for you. + + + +6. Other interesting functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, + bus and slot and number. If the device is + found, its reference count is increased. +pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) +pci_find_capability() Find specified capability in device's capability + list. +pci_resource_start() Returns bus start address for a given PCI region +pci_resource_end() Returns bus end address for a given PCI region +pci_resource_len() Returns the byte length of a PCI region +pci_set_drvdata() Set private driver data pointer for a pci_dev +pci_get_drvdata() Return private driver data pointer for a pci_dev +pci_set_mwi() Enable Memory-Write-Invalidate transactions. +pci_clear_mwi() Disable Memory-Write-Invalidate transactions. + + + +7. Miscellaneous hints +~~~~~~~~~~~~~~~~~~~~~~ + +When displaying PCI device names to the user (for example when a driver wants +to tell the user what card has it found), please use pci_name(pci_dev). + +Always refer to the PCI devices by a pointer to the pci_dev structure. +All PCI layer functions use this identification and it's the only +reasonable one. Don't use bus/slot/function numbers except for very +special purposes -- on systems with multiple primary buses their semantics +can be pretty complex. + +Don't try to turn on Fast Back to Back writes in your driver. All devices +on the bus need to be capable of doing it, so this is something which needs +to be handled by platform and generic code, not individual drivers. + + + +8. Vendor and device identifications +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Do not add new device or vendor IDs to include/linux/pci_ids.h unless they +are shared across multiple drivers. You can add private definitions in +your driver if they're helpful, or just use plain hex constants. + +The device IDs are arbitrary hex numbers (vendor controlled) and normally used +only in a single location, the pci_device_id table. + +Please DO submit new vendor/device IDs to http://pciids.sourceforge.net/. + + + +9. Obsolete functions +~~~~~~~~~~~~~~~~~~~~~ + +There are several functions which you might come across when trying to +port an old driver to the new PCI interface. They are no longer present +in the kernel as they aren't compatible with hotplug or PCI domains or +having sane locking. + +pci_find_device() Superseded by pci_get_device() +pci_find_subsys() Superseded by pci_get_subsys() +pci_find_slot() Superseded by pci_get_domain_bus_and_slot() +pci_get_slot() Superseded by pci_get_domain_bus_and_slot() + + +The alternative is the traditional PCI device driver that walks PCI +device lists. This is still possible but discouraged. + + + +10. MMIO Space and "Write Posting" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Converting a driver from using I/O Port space to using MMIO space +often requires some additional changes. Specifically, "write posting" +needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) +already do this. I/O Port space guarantees write transactions reach the PCI +device before the CPU can continue. Writes to MMIO space allow the CPU +to continue before the transaction reaches the PCI device. HW weenies +call this "Write Posting" because the write completion is "posted" to +the CPU before the transaction has reached its destination. + +Thus, timing sensitive code should add readl() where the CPU is +expected to wait before doing other work. The classic "bit banging" +sequence works fine for I/O Port space: + + for (i = 8; --i; val >>= 1) { + outb(val & 1, ioport_reg); /* write bit */ + udelay(10); + } + +The same sequence for MMIO space should be: + + for (i = 8; --i; val >>= 1) { + writeb(val & 1, mmio_reg); /* write bit */ + readb(safe_mmio_reg); /* flush posted write */ + udelay(10); + } + +It is important that "safe_mmio_reg" not have any side effects that +interferes with the correct operation of the device. + +Another case to watch out for is when resetting a PCI device. Use PCI +Configuration space reads to flush the writel(). This will gracefully +handle the PCI master abort on all platforms if the PCI device is +expected to not respond to a readl(). Most x86 platforms will allow +MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage +(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). +
diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt new file mode 100644 index 0000000..ea8cafb --- /dev/null +++ b/Documentation/PCI/pcieaer-howto.txt
@@ -0,0 +1,262 @@ + The PCI Express Advanced Error Reporting Driver Guide HOWTO + T. Long Nguyen <tom.l.nguyen@intel.com> + Yanmin Zhang <yanmin.zhang@intel.com> + 07/29/2006 + + +1. Overview + +1.1 About this guide + +This guide describes the basics of the PCI Express Advanced Error +Reporting (AER) driver and provides information on how to use it, as +well as how to enable the drivers of endpoint devices to conform with +PCI Express AER driver. + +1.2 Copyright (C) Intel Corporation 2006. + +1.3 What is the PCI Express AER Driver? + +PCI Express error signaling can occur on the PCI Express link itself +or on behalf of transactions initiated on the link. PCI Express +defines two error reporting paradigms: the baseline capability and +the Advanced Error Reporting capability. The baseline capability is +required of all PCI Express components providing a minimum defined +set of error reporting requirements. Advanced Error Reporting +capability is implemented with a PCI Express advanced error reporting +extended capability structure providing more robust error reporting. + +The PCI Express AER driver provides the infrastructure to support PCI +Express Advanced Error Reporting capability. The PCI Express AER +driver provides three basic functions: + +- Gathers the comprehensive error information if errors occurred. +- Reports error to the users. +- Performs error recovery actions. + +AER driver only attaches root ports which support PCI-Express AER +capability. + + +2. User Guide + +2.1 Include the PCI Express AER Root Driver into the Linux Kernel + +The PCI Express AER Root driver is a Root Port service driver attached +to the PCI Express Port Bus driver. If a user wants to use it, the driver +has to be compiled. Option CONFIG_PCIEAER supports this capability. It +depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and +CONFIG_PCIEAER = y. + +2.2 Load PCI Express AER Root Driver + +Some systems have AER support in firmware. Enabling Linux AER support at +the same time the firmware handles AER may result in unpredictable +behavior. Therefore, Linux does not handle AER events unless the firmware +grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0 +Specification for details regarding _OSC usage. + +2.3 AER error output + +When a PCIe AER error is captured, an error message will be output to +console. If it's a correctable error, it is output as a warning. +Otherwise, it is printed as an error. So users could choose different +log level to filter out correctable error messages. + +Below shows an example: +0000:50:00.0: PCIe Bus Error: severity=Uncorrected (Fatal), type=Transaction Layer, id=0500(Requester ID) +0000:50:00.0: device [8086:0329] error status/mask=00100000/00000000 +0000:50:00.0: [20] Unsupported Request (First) +0000:50:00.0: TLP Header: 04000001 00200a03 05010000 00050100 + +In the example, 'Requester ID' means the ID of the device who sends +the error message to root port. Pls. refer to pci express specs for +other fields. + + +3. Developer Guide + +To enable AER aware support requires a software driver to configure +the AER capability structure within its device and to provide callbacks. + +To support AER better, developers need understand how AER does work +firstly. + +PCI Express errors are classified into two types: correctable errors +and uncorrectable errors. This classification is based on the impacts +of those errors, which may result in degraded performance or function +failure. + +Correctable errors pose no impacts on the functionality of the +interface. The PCI Express protocol can recover without any software +intervention or any loss of data. These errors are detected and +corrected by hardware. Unlike correctable errors, uncorrectable +errors impact functionality of the interface. Uncorrectable errors +can cause a particular transaction or a particular PCI Express link +to be unreliable. Depending on those error conditions, uncorrectable +errors are further classified into non-fatal errors and fatal errors. +Non-fatal errors cause the particular transaction to be unreliable, +but the PCI Express link itself is fully functional. Fatal errors, on +the other hand, cause the link to be unreliable. + +When AER is enabled, a PCI Express device will automatically send an +error message to the PCIe root port above it when the device captures +an error. The Root Port, upon receiving an error reporting message, +internally processes and logs the error message in its PCI Express +capability structure. Error information being logged includes storing +the error reporting agent's requestor ID into the Error Source +Identification Registers and setting the error bits of the Root Error +Status Register accordingly. If AER error reporting is enabled in Root +Error Command Register, the Root Port generates an interrupt if an +error is detected. + +Note that the errors as described above are related to the PCI Express +hierarchy and links. These errors do not include any device specific +errors because device specific errors will still get sent directly to +the device driver. + +3.1 Configure the AER capability structure + +AER aware drivers of PCI Express component need change the device +control registers to enable AER. They also could change AER registers, +including mask and severity registers. Helper function +pci_enable_pcie_error_reporting could be used to enable AER. See +section 3.3. + +3.2. Provide callbacks + +3.2.1 callback reset_link to reset pci express link + +This callback is used to reset the pci express physical link when a +fatal error happens. The root port aer service driver provides a +default reset_link function, but different upstream ports might +have different specifications to reset pci express link, so all +upstream ports should provide their own reset_link functions. + +In struct pcie_port_service_driver, a new pointer, reset_link, is +added. + +pci_ers_result_t (*reset_link) (struct pci_dev *dev); + +Section 3.2.2.2 provides more detailed info on when to call +reset_link. + +3.2.2 PCI error-recovery callbacks + +The PCI Express AER Root driver uses error callbacks to coordinate +with downstream device drivers associated with a hierarchy in question +when performing error recovery actions. + +Data struct pci_driver has a pointer, err_handler, to point to +pci_error_handlers who consists of a couple of callback function +pointers. AER driver follows the rules defined in +pci-error-recovery.txt except pci express specific parts (e.g. +reset_link). Pls. refer to pci-error-recovery.txt for detailed +definitions of the callbacks. + +Below sections specify when to call the error callback functions. + +3.2.2.1 Correctable errors + +Correctable errors pose no impacts on the functionality of +the interface. The PCI Express protocol can recover without any +software intervention or any loss of data. These errors do not +require any recovery actions. The AER driver clears the device's +correctable error status register accordingly and logs these errors. + +3.2.2.2 Non-correctable (non-fatal and fatal) errors + +If an error message indicates a non-fatal error, performing link reset +at upstream is not required. The AER driver calls error_detected(dev, +pci_channel_io_normal) to all drivers associated within a hierarchy in +question. for example, +EndPoint<==>DownstreamPort B<==>UpstreamPort A<==>RootPort. +If Upstream port A captures an AER error, the hierarchy consists of +Downstream port B and EndPoint. + +A driver may return PCI_ERS_RESULT_CAN_RECOVER, +PCI_ERS_RESULT_DISCONNECT, or PCI_ERS_RESULT_NEED_RESET, depending on +whether it can recover or the AER driver calls mmio_enabled as next. + +If an error message indicates a fatal error, kernel will broadcast +error_detected(dev, pci_channel_io_frozen) to all drivers within +a hierarchy in question. Then, performing link reset at upstream is +necessary. As different kinds of devices might use different approaches +to reset link, AER port service driver is required to provide the +function to reset link. Firstly, kernel looks for if the upstream +component has an aer driver. If it has, kernel uses the reset_link +callback of the aer driver. If the upstream component has no aer driver +and the port is downstream port, we will perform a hot reset as the +default by setting the Secondary Bus Reset bit of the Bridge Control +register associated with the downstream port. As for upstream ports, +they should provide their own aer service drivers with reset_link +function. If error_detected returns PCI_ERS_RESULT_CAN_RECOVER and +reset_link returns PCI_ERS_RESULT_RECOVERED, the error handling goes +to mmio_enabled. + +3.3 helper functions + +3.3.1 int pci_enable_pcie_error_reporting(struct pci_dev *dev); +pci_enable_pcie_error_reporting enables the device to send error +messages to root port when an error is detected. Note that devices +don't enable the error reporting by default, so device drivers need +call this function to enable it. + +3.3.2 int pci_disable_pcie_error_reporting(struct pci_dev *dev); +pci_disable_pcie_error_reporting disables the device to send error +messages to root port when an error is detected. + +3.3.3 int pci_cleanup_aer_uncorrect_error_status(struct pci_dev *dev); +pci_cleanup_aer_uncorrect_error_status cleanups the uncorrectable +error status register. + +3.4 Frequent Asked Questions + +Q: What happens if a PCI Express device driver does not provide an +error recovery handler (pci_driver->err_handler is equal to NULL)? + +A: The devices attached with the driver won't be recovered. If the +error is fatal, kernel will print out warning messages. Please refer +to section 3 for more information. + +Q: What happens if an upstream port service driver does not provide +callback reset_link? + +A: Fatal error recovery will fail if the errors are reported by the +upstream ports who are attached by the service driver. + +Q: How does this infrastructure deal with driver that is not PCI +Express aware? + +A: This infrastructure calls the error callback functions of the +driver when an error happens. But if the driver is not aware of +PCI Express, the device might not report its own errors to root +port. + +Q: What modifications will that driver need to make it compatible +with the PCI Express AER Root driver? + +A: It could call the helper functions to enable AER in devices and +cleanup uncorrectable status register. Pls. refer to section 3.3. + + +4. Software error injection + +Debugging PCIe AER error recovery code is quite difficult because it +is hard to trigger real hardware errors. Software based error +injection can be used to fake various kinds of PCIe errors. + +First you should enable PCIe AER software error injection in kernel +configuration, that is, following item should be in your .config. + +CONFIG_PCIEAER_INJECT=y or CONFIG_PCIEAER_INJECT=m + +After reboot with new kernel or insert the module, a device file named +/dev/aer_inject should be created. + +Then, you need a user space tool named aer-inject, which can be gotten +from: + http://www.kernel.org/pub/linux/utils/pci/aer-inject/ + +More information about aer-inject can be found in the document comes +with its source code.
diff --git a/Documentation/RCU/00-INDEX b/Documentation/RCU/00-INDEX new file mode 100644 index 0000000..f773a26 --- /dev/null +++ b/Documentation/RCU/00-INDEX
@@ -0,0 +1,36 @@ +00-INDEX + - This file +arrayRCU.txt + - Using RCU to Protect Read-Mostly Arrays +checklist.txt + - Review Checklist for RCU Patches +listRCU.txt + - Using RCU to Protect Read-Mostly Linked Lists +lockdep.txt + - RCU and lockdep checking +lockdep-splat.txt + - RCU Lockdep splats explained. +NMI-RCU.txt + - Using RCU to Protect Dynamic NMI Handlers +rcu_dereference.txt + - Proper care and feeding of return values from rcu_dereference() +rcubarrier.txt + - RCU and Unloadable Modules +rculist_nulls.txt + - RCU list primitives for use with SLAB_DESTROY_BY_RCU +rcuref.txt + - Reference-count design for elements of lists/arrays protected by RCU +rcu.txt + - RCU Concepts +RTFP.txt + - List of RCU papers (bibliography) going back to 1980. +stallwarn.txt + - RCU CPU stall warnings (module parameter rcu_cpu_stall_suppress) +torture.txt + - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST) +trace.txt + - CONFIG_RCU_TRACE debugfs files and formats +UP.txt + - RCU on Uniprocessor Systems +whatisRCU.txt + - What is RCU?
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg new file mode 100644 index 0000000..727e270 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCU.svg
@@ -0,0 +1,474 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:28:20 2015 --> + +<!-- Magnification: 3.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="9.1in" + height="8.9in" + viewBox="-66 -66 10932 10707" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="BigTreeClassicRCU.fig"> + <metadata + id="metadata106"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs104"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3864" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="973" + inkscape:window-height="1137" + id="namedview102" + showgrid="false" + inkscape:zoom="0.9743589" + inkscape:cx="409.50003" + inkscape:cy="400.49997" + inkscape:window-x="915" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="10800" + height="5625" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect6" /> + <!-- Line: box --> + <rect + x="1125" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect8" /> + <!-- Line: box --> + <rect + x="3825" + y="900" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect10" /> + <!-- Line: box --> + <rect + x="6525" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect12" /> + <!-- Line --> + <polyline + points="3375,6525 3375,5046 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline14" /> + <!-- Arrowhead on XXXpoint 3375 6525 - 3375 4860--> + <!-- Circle --> + <circle + cx="7425" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle18" /> + <!-- Circle --> + <circle + cx="7875" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle20" /> + <!-- Circle --> + <circle + cx="8325" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle22" /> + <!-- Circle --> + <circle + cx="2025" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle24" /> + <!-- Circle --> + <circle + cx="2475" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle26" /> + <!-- Circle --> + <circle + cx="2925" + cy="6075" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle28" /> + <!-- Circle --> + <circle + cx="4725" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle30" /> + <!-- Circle --> + <circle + cx="5175" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle32" /> + <!-- Circle --> + <circle + cx="5625" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle34" /> + <!-- Line: box --> + <rect + x="2025" + y="6525" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect36" /> + <!-- Line --> + <polyline + points="2475,3600 3975,2310 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline38" /> + <!-- Arrowhead on XXXpoint 2475 3600 - 4116 2190--> + <!-- Line --> + <polyline + points="7875,3600 6372,2310 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline42" /> + <!-- Arrowhead on XXXpoint 7875 3600 - 6231 2190--> + <!-- Line --> + <polyline + points="6975,8775 6975,5046 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline46" /> + <!-- Arrowhead on XXXpoint 6975 8775 - 6975 4860--> + <!-- Line --> + <polyline + points="1575,8775 1575,5046 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline50" /> + <!-- Arrowhead on XXXpoint 1575 8775 - 1575 4860--> + <!-- Line --> + <polyline + points="8775,6525 8775,5046 " + style="stroke:#00d1d1;stroke-width:44.9934641;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline54" /> + <!-- Arrowhead on XXXpoint 8775 6525 - 8775 4860--> + <!-- Text --> + <text + xml:space="preserve" + x="1575" + y="9225" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text58">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1575" + y="9675" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text60">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1575" + y="10350" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text62">CPU 0</text> + <!-- Text --> + <text + xml:space="preserve" + x="3375" + y="6975" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text64">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3375" + y="7425" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text66">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="3375" + y="8100" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text68">CPU 15</text> + <!-- Text --> + <text + xml:space="preserve" + x="6975" + y="9225" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text70">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="6975" + y="9675" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text72">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="6975" + y="10350" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text74">CPU 1007</text> + <!-- Text --> + <text + xml:space="preserve" + x="8730" + y="6930" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text76">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8730" + y="7380" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text78">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="8730" + y="8055" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text80">CPU 1023</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="start" + id="text82">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="2475" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text84">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2475" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text86">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="7875" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text88">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="7875" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text90">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5175" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text92">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5175" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text94">rcu_node</text> + <!-- Line: box --> + <rect + x="225" + y="8775" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect96" /> + <!-- Line: box --> + <rect + x="5625" + y="8775" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect98" /> + <!-- Line: box --> + <rect + x="7380" + y="6480" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect100" /> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg new file mode 100644 index 0000000..9bbb194 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg
@@ -0,0 +1,499 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:26:09 2015 --> + +<!-- Magnification: 2.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="5.7in" + height="6.6in" + viewBox="-44 -44 6838 7888" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="BigTreeClassicRCUBH.fig"> + <metadata + id="metadata110"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs108"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3868" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow2Mend" + style="overflow:visible;"> + <path + id="path3886" + style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " + transform="scale(0.6) rotate(180) translate(0,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="878" + inkscape:window-height="1148" + id="namedview106" + showgrid="false" + inkscape:zoom="1.3547758" + inkscape:cx="256.5" + inkscape:cy="297" + inkscape:window-x="45" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="450" + y="0" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="4950" + y="4950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect8" /> + <!-- Line: box --> + <rect + x="750" + y="600" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect10" /> + <!-- Line: box --> + <rect + x="0" + y="450" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect12" /> + <!-- Line: box --> + <rect + x="300" + y="1050" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect14" /> + <!-- Circle --> + <circle + cx="2850" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle16" /> + <!-- Circle --> + <circle + cx="3150" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle18" /> + <!-- Circle --> + <circle + cx="3450" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle20" /> + <!-- Circle --> + <circle + cx="1350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle22" /> + <!-- Circle --> + <circle + cx="1650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle24" /> + <!-- Circle --> + <circle + cx="1950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle26" /> + <!-- Circle --> + <circle + cx="4350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle28" /> + <!-- Circle --> + <circle + cx="4650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle30" /> + <!-- Circle --> + <circle + cx="4950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle32" /> + <!-- Line --> + <polyline + points="1350,3450 2350,2590 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline34" /> + <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> + <!-- Line --> + <polyline + points="4950,3450 3948,2590 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline38" /> + <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> + <!-- Line: box --> + <rect + x="750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect42" /> + <!-- Line --> + <polyline + points="2250,5400 2250,4414 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline44" /> + <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> + <!-- Line: box --> + <rect + x="1500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect48" /> + <!-- Line: box --> + <rect + x="300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect50" /> + <!-- Line: box --> + <rect + x="3750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect52" /> + <!-- Line: box --> + <rect + x="4500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect54" /> + <!-- Line: box --> + <rect + x="3300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect56" /> + <!-- Line: box --> + <rect + x="2250" + y="1650" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect58" /> + <!-- Text --> + <text + xml:space="preserve" + x="6450" + y="300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text60">rcu_bh</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="1950" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text62">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2250" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text64">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text66">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text68">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text70">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text72">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text74">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text76">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text78">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text80">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text82">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text84">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text86">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text88">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text90">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="6000" + y="750" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text92">rcu_sched</text> + <!-- Line --> + <polyline + points="5250,5400 5250,4414 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline94" /> + <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> + <!-- Line --> + <polyline + points="4050,6600 4050,4414 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline98" /> + <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> + <!-- Line --> + <polyline + points="1050,6600 1050,4414 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline102" /> + <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg new file mode 100644 index 0000000..21ba782 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg
@@ -0,0 +1,695 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:20:02 2015 --> + +<!-- Magnification: 2.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="5.7in" + height="8.6in" + viewBox="-44 -44 6838 10288" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="BigTreeClassicRCUBHdyntick.fig"> + <metadata + id="metadata166"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs164"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3924" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow2Lend" + style="overflow:visible;"> + <path + id="path3936" + style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " + transform="scale(1.1) rotate(180) translate(1,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="845" + inkscape:window-height="988" + id="namedview162" + showgrid="false" + inkscape:zoom="1.0452196" + inkscape:cx="256.5" + inkscape:cy="387.00003" + inkscape:window-x="356" + inkscape:window-y="61" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="450" + y="0" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="4950" + y="4950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect8" /> + <!-- Line: box --> + <rect + x="750" + y="600" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect10" /> + <!-- Line --> + <polyline + points="5250,8100 5688,5912 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline12" /> + <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790--> + <polyline + points="5714 6068 5704 5822 5598 6044 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline14" /> + <!-- Line --> + <polyline + points="4050,9300 4486,7262 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline16" /> + <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140--> + <polyline + points="4514 7418 4506 7172 4396 7394 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline18" /> + <!-- Line --> + <polyline + points="1040,9300 1476,7262 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline20" /> + <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140--> + <polyline + points="1504 7418 1496 7172 1386 7394 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline22" /> + <!-- Line --> + <polyline + points="2240,8100 2676,6062 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline24" /> + <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940--> + <polyline + points="2704 6218 2696 5972 2586 6194 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline26" /> + <!-- Line: box --> + <rect + x="0" + y="450" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect28" /> + <!-- Line: box --> + <rect + x="300" + y="1050" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect30" /> + <!-- Line --> + <polyline + points="1350,3450 2350,2590 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> + <!-- Line --> + <polyline + points="4950,3450 3948,2590 " + style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> + <!-- Line --> + <polyline + points="4050,6600 4050,4414 " + style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline40" /> + <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> + <!-- Line --> + <polyline + points="1050,6600 1050,4414 " + style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline44" /> + <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> + <!-- Line --> + <polyline + points="2250,5400 2250,4414 " + style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline48" /> + <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> + <!-- Line --> + <polyline + points="2250,8100 2250,6364 " + style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline52" /> + <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240--> + <!-- Line --> + <polyline + points="1050,9300 1050,7564 " + style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline56" /> + <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440--> + <!-- Line --> + <polyline + points="4050,9300 4050,7564 " + style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline60" /> + <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440--> + <!-- Line --> + <polyline + points="5250,8100 5250,6364 " + style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline64" /> + <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240--> + <!-- Circle --> + <circle + cx="2850" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle68" /> + <!-- Circle --> + <circle + cx="3150" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle70" /> + <!-- Circle --> + <circle + cx="3450" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle72" /> + <!-- Circle --> + <circle + cx="1350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle74" /> + <!-- Circle --> + <circle + cx="1650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle76" /> + <!-- Circle --> + <circle + cx="1950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle78" /> + <!-- Circle --> + <circle + cx="4350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle80" /> + <!-- Circle --> + <circle + cx="4650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle82" /> + <!-- Circle --> + <circle + cx="4950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle84" /> + <!-- Line: box --> + <rect + x="750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect86" /> + <!-- Line: box --> + <rect + x="300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect88" /> + <!-- Line: box --> + <rect + x="3750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect90" /> + <!-- Line: box --> + <rect + x="4500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect92" /> + <!-- Line: box --> + <rect + x="3300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect94" /> + <!-- Line: box --> + <rect + x="2250" + y="1650" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect96" /> + <!-- Line: box --> + <rect + x="0" + y="9300" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect98" /> + <!-- Line: box --> + <rect + x="1350" + y="8100" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect100" /> + <!-- Line: box --> + <rect + x="3000" + y="9300" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect102" /> + <!-- Line: box --> + <rect + x="4350" + y="8100" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect104" /> + <!-- Line: box --> + <rect + x="1500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect106" /> + <!-- Text --> + <text + xml:space="preserve" + x="6450" + y="300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text108">rcu_bh</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="1950" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text110">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2250" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text112">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text114">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text116">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text118">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text120">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text122">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text124">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text126">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text128">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text130">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text132">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text134">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text136">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text138">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="9600" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text140">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="9900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text142">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="9600" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text144">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="9900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text146">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text148">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text150">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text152">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text154">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="6000" + y="750" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text156">rcu_sched</text> + <!-- Line --> + <polyline + points="5250,5400 5250,4414 " + style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline158" /> + <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg new file mode 100644 index 0000000..15adcac --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg
@@ -0,0 +1,741 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:32:59 2015 --> + +<!-- Magnification: 2.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="6.1in" + height="8.9in" + viewBox="-44 -44 7288 10738" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="BigTreePreemptRCUBHdyntick.fig"> + <metadata + id="metadata182"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs180"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3940" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="874" + inkscape:window-height="1148" + id="namedview178" + showgrid="false" + inkscape:zoom="1.2097379" + inkscape:cx="274.5" + inkscape:cy="400.49997" + inkscape:window-x="946" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="900" + y="0" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="1200" + y="600" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect8" /> + <!-- Line: box --> + <rect + x="5400" + y="4950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect10" /> + <!-- Line: box --> + <rect + x="450" + y="450" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect12" /> + <!-- Line: box --> + <rect + x="750" + y="1050" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect14" /> + <!-- Line: box --> + <rect + x="4950" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect16" /> + <!-- Line --> + <polyline + points="5250,8550 5688,6362 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline18" /> + <!-- Arrowhead on XXXpoint 5250 8550 - 5710 6240--> + <polyline + points="5714 6518 5704 6272 5598 6494 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline20" /> + <!-- Line --> + <polyline + points="4050,9750 4486,7712 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline22" /> + <!-- Arrowhead on XXXpoint 4050 9750 - 4512 7590--> + <polyline + points="4514 7868 4506 7622 4396 7844 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline24" /> + <!-- Line --> + <polyline + points="1040,9750 1476,7712 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline26" /> + <!-- Arrowhead on XXXpoint 1040 9750 - 1502 7590--> + <polyline + points="1504 7868 1496 7622 1386 7844 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline28" /> + <!-- Line --> + <polyline + points="2240,8550 2676,6512 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline30" /> + <!-- Arrowhead on XXXpoint 2240 8550 - 2702 6390--> + <polyline + points="2704 6668 2696 6422 2586 6644 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline32" /> + <!-- Line --> + <polyline + points="4050,9750 5682,6360 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline34" /> + <!-- Arrowhead on XXXpoint 4050 9750 - 5736 6246--> + <polyline + points="5672 6518 5722 6276 5562 6466 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline36" /> + <!-- Line --> + <polyline + points="1010,9750 2642,6360 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline38" /> + <!-- Arrowhead on XXXpoint 1010 9750 - 2696 6246--> + <polyline + points="2632 6518 2682 6276 2522 6466 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline40" /> + <!-- Line: box --> + <rect + x="0" + y="900" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect42" /> + <!-- Line: box --> + <rect + x="300" + y="1500" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect44" /> + <!-- Line --> + <polyline + points="1350,3900 2350,3040 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline46" /> + <!-- Arrowhead on XXXpoint 1350 3900 - 2444 2960--> + <!-- Line --> + <polyline + points="4950,3900 3948,3040 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline50" /> + <!-- Arrowhead on XXXpoint 4950 3900 - 3854 2960--> + <!-- Line --> + <polyline + points="4050,7050 4050,4864 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline54" /> + <!-- Arrowhead on XXXpoint 4050 7050 - 4050 4740--> + <!-- Line --> + <polyline + points="1050,7050 1050,4864 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline58" /> + <!-- Arrowhead on XXXpoint 1050 7050 - 1050 4740--> + <!-- Line --> + <polyline + points="2250,5850 2250,4864 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline62" /> + <!-- Arrowhead on XXXpoint 2250 5850 - 2250 4740--> + <!-- Line --> + <polyline + points="2250,8550 2250,6814 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline66" /> + <!-- Arrowhead on XXXpoint 2250 8550 - 2250 6690--> + <!-- Line --> + <polyline + points="1050,9750 1050,8014 " + style="stroke:#00ff00;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline70" /> + <!-- Arrowhead on XXXpoint 1050 9750 - 1050 7890--> + <!-- Line --> + <polyline + points="4050,9750 4050,8014 " + style="stroke:#00ff00;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline74" /> + <!-- Arrowhead on XXXpoint 4050 9750 - 4050 7890--> + <!-- Line --> + <polyline + points="5250,8550 5250,6814 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline78" /> + <!-- Arrowhead on XXXpoint 5250 8550 - 5250 6690--> + <!-- Circle --> + <circle + cx="2850" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle82" /> + <!-- Circle --> + <circle + cx="3150" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle84" /> + <!-- Circle --> + <circle + cx="3450" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle86" /> + <!-- Circle --> + <circle + cx="1350" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle88" /> + <!-- Circle --> + <circle + cx="1650" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle90" /> + <!-- Circle --> + <circle + cx="1950" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle92" /> + <!-- Circle --> + <circle + cx="4350" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle94" /> + <!-- Circle --> + <circle + cx="4650" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle96" /> + <!-- Circle --> + <circle + cx="4950" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle98" /> + <!-- Line: box --> + <rect + x="750" + y="3900" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect100" /> + <!-- Line: box --> + <rect + x="300" + y="7050" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect102" /> + <!-- Line: box --> + <rect + x="3750" + y="3900" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect104" /> + <!-- Line: box --> + <rect + x="4500" + y="5850" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect106" /> + <!-- Line: box --> + <rect + x="3300" + y="7050" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect108" /> + <!-- Line: box --> + <rect + x="2250" + y="2100" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect110" /> + <!-- Line: box --> + <rect + x="0" + y="9750" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect112" /> + <!-- Line: box --> + <rect + x="1350" + y="8550" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect114" /> + <!-- Line: box --> + <rect + x="3000" + y="9750" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect116" /> + <!-- Line: box --> + <rect + x="4350" + y="8550" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect118" /> + <!-- Line: box --> + <rect + x="1500" + y="5850" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect120" /> + <!-- Text --> + <text + xml:space="preserve" + x="6450" + y="750" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text122">rcu_bh</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text124">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text126">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text128">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text130">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text132">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text134">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text136">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text138">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text140">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7650" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text142">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text144">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text146">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text148">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7650" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text150">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text152">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="10050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text154">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="10350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text156">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="10050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text158">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="10350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text160">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8850" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text162">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="9150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text164">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8850" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text166">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="9150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text168">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="6900" + y="300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text170">rcu_preempt</text> + <!-- Text --> + <text + xml:space="preserve" + x="6000" + y="1200" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text172">rcu_sched</text> + <!-- Line --> + <polyline + points="5250,5850 5250,4864 " + style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline174" /> + <!-- Arrowhead on XXXpoint 5250 5850 - 5250 4740--> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg new file mode 100644 index 0000000..bbc3801 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg
@@ -0,0 +1,858 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:29:48 2015 --> + +<!-- Magnification: 2.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="7.4in" + height="9.9in" + viewBox="-44 -44 8938 11938" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="BigTreePreemptRCUBHdyntickCB.svg"> + <metadata + id="metadata212"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs210"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3970" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="881" + inkscape:window-height="1128" + id="namedview208" + showgrid="false" + inkscape:zoom="1.0195195" + inkscape:cx="333" + inkscape:cy="445.49997" + inkscape:window-x="936" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="900" + y="0" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="1200" + y="600" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect8" /> + <!-- Line: box --> + <rect + x="5400" + y="4950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect10" /> + <!-- Line: box --> + <rect + x="450" + y="450" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect12" /> + <!-- Line: box --> + <rect + x="750" + y="1050" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect14" /> + <!-- Line: box --> + <rect + x="4950" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect16" /> + <!-- Line --> + <polyline + points="5250,8550 5688,6362 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline18" /> + <!-- Arrowhead on XXXpoint 5250 8550 - 5710 6240--> + <polyline + points="5714 6518 5704 6272 5598 6494 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline20" /> + <!-- Line --> + <polyline + points="4050,9750 4486,7712 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline22" /> + <!-- Arrowhead on XXXpoint 4050 9750 - 4512 7590--> + <polyline + points="4514 7868 4506 7622 4396 7844 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline24" /> + <!-- Line --> + <polyline + points="1040,9750 1476,7712 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline26" /> + <!-- Arrowhead on XXXpoint 1040 9750 - 1502 7590--> + <polyline + points="1504 7868 1496 7622 1386 7844 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline28" /> + <!-- Line --> + <polyline + points="2240,8550 2676,6512 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline30" /> + <!-- Arrowhead on XXXpoint 2240 8550 - 2702 6390--> + <polyline + points="2704 6668 2696 6422 2586 6644 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline32" /> + <!-- Line --> + <polyline + points="4050,9600 5692,6062 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline34" /> + <!-- Arrowhead on XXXpoint 4050 9600 - 5744 5948--> + <polyline + points="5682 6220 5730 5978 5574 6170 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline36" /> + <!-- Line --> + <polyline + points="1086,9600 2728,6062 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline38" /> + <!-- Arrowhead on XXXpoint 1086 9600 - 2780 5948--> + <polyline + points="2718 6220 2766 5978 2610 6170 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline40" /> + <!-- Line: box --> + <rect + x="0" + y="900" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect42" /> + <!-- Line: box --> + <rect + x="300" + y="1500" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect44" /> + <!-- Line --> + <polyline + points="1350,3900 2350,3040 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline46" /> + <!-- Arrowhead on XXXpoint 1350 3900 - 2444 2960--> + <!-- Line --> + <polyline + points="4950,3900 3948,3040 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline50" /> + <!-- Arrowhead on XXXpoint 4950 3900 - 3854 2960--> + <!-- Line --> + <polyline + points="4050,7050 4050,4864 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline54" /> + <!-- Arrowhead on XXXpoint 4050 7050 - 4050 4740--> + <!-- Line --> + <polyline + points="1050,7050 1050,4864 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline58" /> + <!-- Arrowhead on XXXpoint 1050 7050 - 1050 4740--> + <!-- Line --> + <polyline + points="2250,5850 2250,4864 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline62" /> + <!-- Arrowhead on XXXpoint 2250 5850 - 2250 4740--> + <!-- Line --> + <polyline + points="2250,8550 2250,6814 " + style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline66" /> + <!-- Arrowhead on XXXpoint 2250 8550 - 2250 6690--> + <!-- Line --> + <polyline + points="1050,9750 1050,8014 " + style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline70" /> + <!-- Arrowhead on XXXpoint 1050 9750 - 1050 7890--> + <!-- Line --> + <polyline + points="4050,9750 4050,8014 " + style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline74" /> + <!-- Arrowhead on XXXpoint 4050 9750 - 4050 7890--> + <!-- Line --> + <polyline + points="5250,8550 5250,6814 " + style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline78" /> + <!-- Arrowhead on XXXpoint 5250 8550 - 5250 6690--> + <!-- Line --> + <polyline + points="6000,6300 8048,7910 " + style="stroke:#87cfff;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline82" /> + <!-- Arrowhead on XXXpoint 6000 6300 - 8146 7986--> + <!-- Circle --> + <circle + cx="2850" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle86" /> + <!-- Circle --> + <circle + cx="3150" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle88" /> + <!-- Circle --> + <circle + cx="3450" + cy="4350" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle90" /> + <!-- Circle --> + <circle + cx="1350" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle92" /> + <!-- Circle --> + <circle + cx="1650" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle94" /> + <!-- Circle --> + <circle + cx="1950" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle96" /> + <!-- Circle --> + <circle + cx="4350" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle98" /> + <!-- Circle --> + <circle + cx="4650" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle100" /> + <!-- Circle --> + <circle + cx="4950" + cy="5550" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle102" /> + <!-- Line: box --> + <rect + x="7350" + y="7950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect104" /> + <!-- Line: box --> + <rect + x="7350" + y="9450" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect106" /> + <!-- Line --> + <polyline + points="8100,8850 8100,9384 " + style="stroke:#000000;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline108" /> + <!-- Arrowhead on XXXpoint 8100 8850 - 8100 9510--> + <!-- Line: box --> + <rect + x="7350" + y="10950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect112" /> + <!-- Line --> + <polyline + points="8100,10350 8100,10884 " + style="stroke:#000000;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" + id="polyline114" /> + <!-- Arrowhead on XXXpoint 8100 10350 - 8100 11010--> + <!-- Line: box --> + <rect + x="750" + y="3900" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect118" /> + <!-- Line: box --> + <rect + x="300" + y="7050" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect120" /> + <!-- Line: box --> + <rect + x="3750" + y="3900" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect122" /> + <!-- Line: box --> + <rect + x="4500" + y="5850" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect124" /> + <!-- Line: box --> + <rect + x="3300" + y="7050" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect126" /> + <!-- Line: box --> + <rect + x="2250" + y="2100" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect128" /> + <!-- Line: box --> + <rect + x="0" + y="9750" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect130" /> + <!-- Line: box --> + <rect + x="1350" + y="8550" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect132" /> + <!-- Line: box --> + <rect + x="3000" + y="9750" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect134" /> + <!-- Line: box --> + <rect + x="4350" + y="8550" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect136" /> + <!-- Line: box --> + <rect + x="1500" + y="5850" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect138" /> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="8250" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text140">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="8550" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text142">rcu_head</text> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="9750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text144">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="10050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text146">rcu_head</text> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="11250" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text148">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8100" + y="11550" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text150">rcu_head</text> + <!-- Text --> + <text + xml:space="preserve" + x="6000" + y="1200" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text152">rcu_sched</text> + <!-- Text --> + <text + xml:space="preserve" + x="6450" + y="750" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text154">rcu_bh</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text156">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text158">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text160">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text162">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text164">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text166">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text168">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text170">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text172">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7650" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text174">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text176">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text178">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text180">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7650" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text182">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text184">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="10050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text186">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="10350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text188">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="10050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text190">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="10350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text192">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8850" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text194">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="9150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text196">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8850" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text198">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="9150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text200">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="6900" + y="300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text202">rcu_preempt</text> + <!-- Line --> + <polyline + points="5250,5850 5250,4864 " + style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline204" /> + <!-- Arrowhead on XXXpoint 5250 5850 - 5250 4740--> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.html b/Documentation/RCU/Design/Data-Structures/Data-Structures.html new file mode 100644 index 0000000..7eb47ac --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html
@@ -0,0 +1,1333 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + <html> + <head><title>A Tour Through TREE_RCU's Data Structures [LWN.net]</title> + <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + + <p>January 27, 2016</p> + <p>This article was contributed by Paul E. McKenney</p> + +<h3>Introduction</h3> + +This document describes RCU's major data structures and their relationship +to each other. + +<ol> +<li> <a href="#Data-Structure Relationships"> + Data-Structure Relationships</a> +<li> <a href="#The rcu_state Structure"> + The <tt>rcu_state</tt> Structure</a> +<li> <a href="#The rcu_node Structure"> + The <tt>rcu_node</tt> Structure</a> +<li> <a href="#The rcu_data Structure"> + The <tt>rcu_data</tt> Structure</a> +<li> <a href="#The rcu_dynticks Structure"> + The <tt>rcu_dynticks</tt> Structure</a> +<li> <a href="#The rcu_head Structure"> + The <tt>rcu_head</tt> Structure</a> +<li> <a href="#RCU-Specific Fields in the task_struct Structure"> + RCU-Specific Fields in the <tt>task_struct</tt> Structure</a> +<li> <a href="#Accessor Functions"> + Accessor Functions</a> +</ol> + +At the end we have the +<a href="#Answers to Quick Quizzes">answers to the quick quizzes</a>. + +<h3><a name="Data-Structure Relationships">Data-Structure Relationships</a></h3> + +<p>RCU is for all intents and purposes a large state machine, and its +data structures maintain the state in such a way as to allow RCU readers +to execute extremely quickly, while also processing the RCU grace periods +requested by updaters in an efficient and extremely scalable fashion. +The efficiency and scalability of RCU updaters is provided primarily +by a combining tree, as shown below: + +</p><p><img src="BigTreeClassicRCU.svg" alt="BigTreeClassicRCU.svg" width="30%"> + +</p><p>This diagram shows an enclosing <tt>rcu_state</tt> structure +containing a tree of <tt>rcu_node</tt> structures. +Each leaf node of the <tt>rcu_node</tt> tree has up to 16 +<tt>rcu_data</tt> structures associated with it, so that there +are <tt>NR_CPUS</tt> number of <tt>rcu_data</tt> structures, +one for each possible CPU. +This structure is adjusted at boot time, if needed, to handle the +common case where <tt>nr_cpu_ids</tt> is much less than +<tt>NR_CPUs</tt>. +For example, a number of Linux distributions set <tt>NR_CPUs=4096</tt>, +which results in a three-level <tt>rcu_node</tt> tree. +If the actual hardware has only 16 CPUs, RCU will adjust itself +at boot time, resulting in an <tt>rcu_node</tt> tree with only a single node. + +</p><p>The purpose of this combining tree is to allow per-CPU events +such as quiescent states, dyntick-idle transitions, +and CPU hotplug operations to be processed efficiently +and scalably. +Quiescent states are recorded by the per-CPU <tt>rcu_data</tt> structures, +and other events are recorded by the leaf-level <tt>rcu_node</tt> +structures. +All of these events are combined at each level of the tree until finally +grace periods are completed at the tree's root <tt>rcu_node</tt> +structure. +A grace period can be completed at the root once every CPU +(or, in the case of <tt>CONFIG_PREEMPT_RCU</tt>, task) +has passed through a quiescent state. +Once a grace period has completed, record of that fact is propagated +back down the tree. + +</p><p>As can be seen from the diagram, on a 64-bit system +a two-level tree with 64 leaves can accommodate 1,024 CPUs, with a fanout +of 64 at the root and a fanout of 16 at the leaves. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + Why isn't the fanout at the leaves also 64? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + Because there are more types of events that affect the leaf-level + <tt>rcu_node</tt> structures than further up the tree. + Therefore, if the leaf <tt>rcu_node</tt> structures have fanout of + 64, the contention on these structures' <tt>->structures</tt> + becomes excessive. + Experimentation on a wide variety of systems has shown that a fanout + of 16 works well for the leaves of the <tt>rcu_node</tt> tree. + </font> + + <p><font color="ffffff">Of course, further experience with + systems having hundreds or thousands of CPUs may demonstrate + that the fanout for the non-leaf <tt>rcu_node</tt> structures + must also be reduced. + Such reduction can be easily carried out when and if it proves + necessary. + In the meantime, if you are using such a system and running into + contention problems on the non-leaf <tt>rcu_node</tt> structures, + you may use the <tt>CONFIG_RCU_FANOUT</tt> kernel configuration + parameter to reduce the non-leaf fanout as needed. + </font> + + <p><font color="ffffff">Kernels built for systems with + strong NUMA characteristics might also need to adjust + <tt>CONFIG_RCU_FANOUT</tt> so that the domains of the + <tt>rcu_node</tt> structures align with hardware boundaries. + However, there has thus far been no need for this. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<p>If your system has more than 1,024 CPUs (or more than 512 CPUs on +a 32-bit system), then RCU will automatically add more levels to the +tree. +For example, if you are crazy enough to build a 64-bit system with 65,536 +CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows: + +</p><p><img src="HugeTreeClassicRCU.svg" alt="HugeTreeClassicRCU.svg" width="50%"> + +</p><p>RCU currently permits up to a four-level tree, which on a 64-bit system +accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for +32-bit systems. +On the other hand, you can set <tt>CONFIG_RCU_FANOUT</tt> to be +as small as 2 if you wish, which would permit only 16 CPUs, which +is useful for testing. + +</p><p>This multi-level combining tree allows us to get most of the +performance and scalability +benefits of partitioning, even though RCU grace-period detection is +inherently a global operation. +The trick here is that only the last CPU to report a quiescent state +into a given <tt>rcu_node</tt> structure need advance to the <tt>rcu_node</tt> +structure at the next level up the tree. +This means that at the leaf-level <tt>rcu_node</tt> structure, only +one access out of sixteen will progress up the tree. +For the internal <tt>rcu_node</tt> structures, the situation is even +more extreme: Only one access out of sixty-four will progress up +the tree. +Because the vast majority of the CPUs do not progress up the tree, +the lock contention remains roughly constant up the tree. +No matter how many CPUs there are in the system, at most 64 quiescent-state +reports per grace period will progress all the way to the root +<tt>rcu_node</tt> structure, thus ensuring that the lock contention +on that root <tt>rcu_node</tt> structure remains acceptably low. + +</p><p>In effect, the combining tree acts like a big shock absorber, +keeping lock contention under control at all tree levels regardless +of the level of loading on the system. + +</p><p>The Linux kernel actually supports multiple flavors of RCU +running concurrently, so RCU builds separate data structures for each +flavor. +For example, for <tt>CONFIG_TREE_RCU=y</tt> kernels, RCU provides +rcu_sched and rcu_bh, as shown below: + +</p><p><img src="BigTreeClassicRCUBH.svg" alt="BigTreeClassicRCUBH.svg" width="33%"> + +</p><p>Energy efficiency is increasingly important, and for that +reason the Linux kernel provides <tt>CONFIG_NO_HZ_IDLE</tt>, which +turns off the scheduling-clock interrupts on idle CPUs, which in +turn allows those CPUs to attain deeper sleep states and to consume +less energy. +CPUs whose scheduling-clock interrupts have been turned off are +said to be in <i>dyntick-idle mode</i>. +RCU must handle dyntick-idle CPUs specially +because RCU would otherwise wake up each CPU on every grace period, +which would defeat the whole purpose of <tt>CONFIG_NO_HZ_IDLE</tt>. +RCU uses the <tt>rcu_dynticks</tt> structure to track +which CPUs are in dyntick idle mode, as shown below: + +</p><p><img src="BigTreeClassicRCUBHdyntick.svg" alt="BigTreeClassicRCUBHdyntick.svg" width="33%"> + +</p><p>However, if a CPU is in dyntick-idle mode, it is in that mode +for all flavors of RCU. +Therefore, a single <tt>rcu_dynticks</tt> structure is allocated per +CPU, and all of a given CPU's <tt>rcu_data</tt> structures share +that <tt>rcu_dynticks</tt>, as shown in the figure. + +</p><p>Kernels built with <tt>CONFIG_PREEMPT_RCU</tt> support +rcu_preempt in addition to rcu_sched and rcu_bh, as shown below: + +</p><p><img src="BigTreePreemptRCUBHdyntick.svg" alt="BigTreePreemptRCUBHdyntick.svg" width="35%"> + +</p><p>RCU updaters wait for normal grace periods by registering +RCU callbacks, either directly via <tt>call_rcu()</tt> and +friends (namely <tt>call_rcu_bh()</tt> and <tt>call_rcu_sched()</tt>), +there being a separate interface per flavor of RCU) +or indirectly via <tt>synchronize_rcu()</tt> and friends. +RCU callbacks are represented by <tt>rcu_head</tt> structures, +which are queued on <tt>rcu_data</tt> structures while they are +waiting for a grace period to elapse, as shown in the following figure: + +</p><p><img src="BigTreePreemptRCUBHdyntickCB.svg" alt="BigTreePreemptRCUBHdyntickCB.svg" width="40%"> + +</p><p>This figure shows how <tt>TREE_RCU</tt>'s and +<tt>PREEMPT_RCU</tt>'s major data structures are related. +Lesser data structures will be introduced with the algorithms that +make use of them. + +</p><p>Note that each of the data structures in the above figure has +its own synchronization: + +<p><ol> +<li> Each <tt>rcu_state</tt> structures has a lock and a mutex, + and some fields are protected by the corresponding root + <tt>rcu_node</tt> structure's lock. +<li> Each <tt>rcu_node</tt> structure has a spinlock. +<li> The fields in <tt>rcu_data</tt> are private to the corresponding + CPU, although a few can be read and written by other CPUs. +<li> Similarly, the fields in <tt>rcu_dynticks</tt> are private + to the corresponding CPU, although a few can be read by + other CPUs. +</ol> + +<p>It is important to note that different data structures can have +very different ideas about the state of RCU at any given time. +For but one example, awareness of the start or end of a given RCU +grace period propagates slowly through the data structures. +This slow propagation is absolutely necessary for RCU to have good +read-side performance. +If this balkanized implementation seems foreign to you, one useful +trick is to consider each instance of these data structures to be +a different person, each having the usual slightly different +view of reality. + +</p><p>The general role of each of these data structures is as +follows: + +</p><ol> +<li> <tt>rcu_state</tt>: + This structure forms the interconnection between the + <tt>rcu_node</tt> and <tt>rcu_data</tt> structures, + tracks grace periods, serves as short-term repository + for callbacks orphaned by CPU-hotplug events, + maintains <tt>rcu_barrier()</tt> state, + tracks expedited grace-period state, + and maintains state used to force quiescent states when + grace periods extend too long, +<li> <tt>rcu_node</tt>: This structure forms the combining + tree that propagates quiescent-state + information from the leaves to the root, and also propagates + grace-period information from the root to the leaves. + It provides local copies of the grace-period state in order + to allow this information to be accessed in a synchronized + manner without suffering the scalability limitations that + would otherwise be imposed by global locking. + In <tt>CONFIG_PREEMPT_RCU</tt> kernels, it manages the lists + of tasks that have blocked while in their current + RCU read-side critical section. + In <tt>CONFIG_PREEMPT_RCU</tt> with + <tt>CONFIG_RCU_BOOST</tt>, it manages the + per-<tt>rcu_node</tt> priority-boosting + kernel threads (kthreads) and state. + Finally, it records CPU-hotplug state in order to determine + which CPUs should be ignored during a given grace period. +<li> <tt>rcu_data</tt>: This per-CPU structure is the + focus of quiescent-state detection and RCU callback queuing. + It also tracks its relationship to the corresponding leaf + <tt>rcu_node</tt> structure to allow more-efficient + propagation of quiescent states up the <tt>rcu_node</tt> + combining tree. + Like the <tt>rcu_node</tt> structure, it provides a local + copy of the grace-period information to allow for-free + synchronized + access to this information from the corresponding CPU. + Finally, this structure records past dyntick-idle state + for the corresponding CPU and also tracks statistics. +<li> <tt>rcu_dynticks</tt>: + This per-CPU structure tracks the current dyntick-idle + state for the corresponding CPU. + Unlike the other three structures, the <tt>rcu_dynticks</tt> + structure is not replicated per RCU flavor. +<li> <tt>rcu_head</tt>: + This structure represents RCU callbacks, and is the + only structure allocated and managed by RCU users. + The <tt>rcu_head</tt> structure is normally embedded + within the RCU-protected data structure. +</ol> + +<p>If all you wanted from this article was a general notion of how +RCU's data structures are related, you are done. +Otherwise, each of the following sections give more details on +the <tt>rcu_state</tt>, <tt>rcu_node</tt>, <tt>rcu_data</tt>, +and <tt>rcu_dynticks</tt> data structures. + +<h3><a name="The rcu_state Structure"> +The <tt>rcu_state</tt> Structure</a></h3> + +<p>The <tt>rcu_state</tt> structure is the base structure that +represents a flavor of RCU. +This structure forms the interconnection between the +<tt>rcu_node</tt> and <tt>rcu_data</tt> structures, +tracks grace periods, contains the lock used to +synchronize with CPU-hotplug events, +and maintains state used to force quiescent states when +grace periods extend too long, + +</p><p>A few of the <tt>rcu_state</tt> structure's fields are discussed, +singly and in groups, in the following sections. +The more specialized fields are covered in the discussion of their +use. + +<h5>Relationship to rcu_node and rcu_data Structures</h5> + +This portion of the <tt>rcu_state</tt> structure is declared +as follows: + +<pre> + 1 struct rcu_node node[NUM_RCU_NODES]; + 2 struct rcu_node *level[NUM_RCU_LVLS + 1]; + 3 struct rcu_data __percpu *rda; +</pre> + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + Wait a minute! + You said that the <tt>rcu_node</tt> structures formed a tree, + but they are declared as a flat array! + What gives? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + The tree is laid out in the array. + The first node In the array is the head, the next set of nodes in the + array are children of the head node, and so on until the last set of + nodes in the array are the leaves. + </font> + + <p><font color="ffffff">See the following diagrams to see how + this works. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<p>The <tt>rcu_node</tt> tree is embedded into the +<tt>->node[]</tt> array as shown in the following figure: + +</p><p><img src="TreeMapping.svg" alt="TreeMapping.svg" width="40%"> + +</p><p>One interesting consequence of this mapping is that a +breadth-first traversal of the tree is implemented as a simple +linear scan of the array, which is in fact what the +<tt>rcu_for_each_node_breadth_first()</tt> macro does. +This macro is used at the beginning and ends of grace periods. + +</p><p>Each entry of the <tt>->level</tt> array references +the first <tt>rcu_node</tt> structure on the corresponding level +of the tree, for example, as shown below: + +</p><p><img src="TreeMappingLevel.svg" alt="TreeMappingLevel.svg" width="40%"> + +</p><p>The zero<sup>th</sup> element of the array references the root +<tt>rcu_node</tt> structure, the first element references the +first child of the root <tt>rcu_node</tt>, and finally the second +element references the first leaf <tt>rcu_node</tt> structure. + +</p><p>For whatever it is worth, if you draw the tree to be tree-shaped +rather than array-shaped, it is easy to draw a planar representation: + +</p><p><img src="TreeLevel.svg" alt="TreeLevel.svg" width="60%"> + +</p><p>Finally, the <tt>->rda</tt> field references a per-CPU +pointer to the corresponding CPU's <tt>rcu_data</tt> structure. + +</p><p>All of these fields are constant once initialization is complete, +and therefore need no protection. + +<h5>Grace-Period Tracking</h5> + +<p>This portion of the <tt>rcu_state</tt> structure is declared +as follows: + +<pre> + 1 unsigned long gpnum; + 2 unsigned long completed; +</pre> + +<p>RCU grace periods are numbered, and +the <tt>->gpnum</tt> field contains the number of the grace +period that started most recently. +The <tt>->completed</tt> field contains the number of the +grace period that completed most recently. +If the two fields are equal, the RCU grace period that most recently +started has already completed, and therefore the corresponding +flavor of RCU is idle. +If <tt>->gpnum</tt> is one greater than <tt>->completed</tt>, +then <tt>->gpnum</tt> gives the number of the current RCU +grace period, which has not yet completed. +Any other combination of values indicates that something is broken. +These two fields are protected by the root <tt>rcu_node</tt>'s +<tt>->lock</tt> field. + +</p><p>There are <tt>->gpnum</tt> and <tt>->completed</tt> fields +in the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures +as well. +The fields in the <tt>rcu_state</tt> structure represent the +most current values, and those of the other structures are compared +in order to detect the start of a new grace period in a distributed +fashion. +The values flow from <tt>rcu_state</tt> to <tt>rcu_node</tt> +(down the tree from the root to the leaves) to <tt>rcu_data</tt>. + +<h5>Miscellaneous</h5> + +<p>This portion of the <tt>rcu_state</tt> structure is declared +as follows: + +<pre> + 1 unsigned long gp_max; + 2 char abbr; + 3 char *name; +</pre> + +<p>The <tt>->gp_max</tt> field tracks the duration of the longest +grace period in jiffies. +It is protected by the root <tt>rcu_node</tt>'s <tt>->lock</tt>. + +<p>The <tt>->name</tt> field points to the name of the RCU flavor +(for example, “rcu_sched”), and is constant. +The <tt>->abbr</tt> field contains a one-character abbreviation, +for example, “s” for RCU-sched. + +<h3><a name="The rcu_node Structure"> +The <tt>rcu_node</tt> Structure</a></h3> + +<p>The <tt>rcu_node</tt> structures form the combining +tree that propagates quiescent-state +information from the leaves to the root and also that propagates +grace-period information from the root down to the leaves. +They provides local copies of the grace-period state in order +to allow this information to be accessed in a synchronized +manner without suffering the scalability limitations that +would otherwise be imposed by global locking. +In <tt>CONFIG_PREEMPT_RCU</tt> kernels, they manage the lists +of tasks that have blocked while in their current +RCU read-side critical section. +In <tt>CONFIG_PREEMPT_RCU</tt> with +<tt>CONFIG_RCU_BOOST</tt>, they manage the +per-<tt>rcu_node</tt> priority-boosting +kernel threads (kthreads) and state. +Finally, they record CPU-hotplug state in order to determine +which CPUs should be ignored during a given grace period. + +</p><p>The <tt>rcu_node</tt> structure's fields are discussed, +singly and in groups, in the following sections. + +<h5>Connection to Combining Tree</h5> + +<p>This portion of the <tt>rcu_node</tt> structure is declared +as follows: + +<pre> + 1 struct rcu_node *parent; + 2 u8 level; + 3 u8 grpnum; + 4 unsigned long grpmask; + 5 int grplo; + 6 int grphi; +</pre> + +<p>The <tt>->parent</tt> pointer references the <tt>rcu_node</tt> +one level up in the tree, and is <tt>NULL</tt> for the root +<tt>rcu_node</tt>. +The RCU implementation makes heavy use of this field to push quiescent +states up the tree. +The <tt>->level</tt> field gives the level in the tree, with +the root being at level zero, its children at level one, and so on. +The <tt>->grpnum</tt> field gives this node's position within +the children of its parent, so this number can range between 0 and 31 +on 32-bit systems and between 0 and 63 on 64-bit systems. +The <tt>->level</tt> and <tt>->grpnum</tt> fields are +used only during initialization and for tracing. +The <tt>->grpmask</tt> field is the bitmask counterpart of +<tt>->grpnum</tt>, and therefore always has exactly one bit set. +This mask is used to clear the bit corresponding to this <tt>rcu_node</tt> +structure in its parent's bitmasks, which are described later. +Finally, the <tt>->grplo</tt> and <tt>->grphi</tt> fields +contain the lowest and highest numbered CPU served by this +<tt>rcu_node</tt> structure, respectively. + +</p><p>All of these fields are constant, and thus do not require any +synchronization. + +<h5>Synchronization</h5> + +<p>This field of the <tt>rcu_node</tt> structure is declared +as follows: + +<pre> + 1 raw_spinlock_t lock; +</pre> + +<p>This field is used to protect the remaining fields in this structure, +unless otherwise stated. +That said, all of the fields in this structure can be accessed without +locking for tracing purposes. +Yes, this can result in confusing traces, but better some tracing confusion +than to be heisenbugged out of existence. + +<h5>Grace-Period Tracking</h5> + +<p>This portion of the <tt>rcu_node</tt> structure is declared +as follows: + +<pre> + 1 unsigned long gpnum; + 2 unsigned long completed; +</pre> + +<p>These fields are the counterparts of the fields of the same name in +the <tt>rcu_state</tt> structure. +They each may lag up to one behind their <tt>rcu_state</tt> +counterparts. +If a given <tt>rcu_node</tt> structure's <tt>->gpnum</tt> and +<tt>->complete</tt> fields are equal, then this <tt>rcu_node</tt> +structure believes that RCU is idle. +Otherwise, as with the <tt>rcu_state</tt> structure, +the <tt>->gpnum</tt> field will be one greater than the +<tt>->complete</tt> fields, with <tt>->gpnum</tt> +indicating which grace period this <tt>rcu_node</tt> believes +is still being waited for. + +</p><p>The <tt>>gpnum</tt> field of each <tt>rcu_node</tt> +structure is updated at the beginning +of each grace period, and the <tt>->completed</tt> fields are +updated at the end of each grace period. + +<h5>Quiescent-State Tracking</h5> + +<p>These fields manage the propagation of quiescent states up the +combining tree. + +</p><p>This portion of the <tt>rcu_node</tt> structure has fields +as follows: + +<pre> + 1 unsigned long qsmask; + 2 unsigned long expmask; + 3 unsigned long qsmaskinit; + 4 unsigned long expmaskinit; +</pre> + +<p>The <tt>->qsmask</tt> field tracks which of this +<tt>rcu_node</tt> structure's children still need to report +quiescent states for the current normal grace period. +Such children will have a value of 1 in their corresponding bit. +Note that the leaf <tt>rcu_node</tt> structures should be +thought of as having <tt>rcu_data</tt> structures as their +children. +Similarly, the <tt>->expmask</tt> field tracks which +of this <tt>rcu_node</tt> structure's children still need to report +quiescent states for the current expedited grace period. +An expedited grace period has +the same conceptual properties as a normal grace period, but the +expedited implementation accepts extreme CPU overhead to obtain +much lower grace-period latency, for example, consuming a few +tens of microseconds worth of CPU time to reduce grace-period +duration from milliseconds to tens of microseconds. +The <tt>->qsmaskinit</tt> field tracks which of this +<tt>rcu_node</tt> structure's children cover for at least +one online CPU. +This mask is used to initialize <tt>->qsmask</tt>, +and <tt>->expmaskinit</tt> is used to initialize +<tt>->expmask</tt> and the beginning of the +normal and expedited grace periods, respectively. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + Why are these bitmasks protected by locking? + Come on, haven't you heard of atomic instructions??? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + Lockless grace-period computation! Such a tantalizing possibility! + </font> + + <p><font color="ffffff">But consider the following sequence of events: + </font> + + <ol> + <li> <font color="ffffff">CPU 0 has been in dyntick-idle + mode for quite some time. + When it wakes up, it notices that the current RCU + grace period needs it to report in, so it sets a + flag where the scheduling clock interrupt will find it. + </font><p> + <li> <font color="ffffff">Meanwhile, CPU 1 is running + <tt>force_quiescent_state()</tt>, + and notices that CPU 0 has been in dyntick idle mode, + which qualifies as an extended quiescent state. + </font><p> + <li> <font color="ffffff">CPU 0's scheduling clock + interrupt fires in the + middle of an RCU read-side critical section, and notices + that the RCU core needs something, so commences RCU softirq + processing. + </font> + <p> + <li> <font color="ffffff">CPU 0's softirq handler + executes and is just about ready + to report its quiescent state up the <tt>rcu_node</tt> + tree. + </font><p> + <li> <font color="ffffff">But CPU 1 beats it to the punch, + completing the current + grace period and starting a new one. + </font><p> + <li> <font color="ffffff">CPU 0 now reports its quiescent + state for the wrong + grace period. + That grace period might now end before the RCU read-side + critical section. + If that happens, disaster will ensue. + </font> + </ol> + + <p><font color="ffffff">So the locking is absolutely required in + order to coordinate + clearing of the bits with the grace-period numbers in + <tt>->gpnum</tt> and <tt>->completed</tt>. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<h5>Blocked-Task Management</h5> + +<p><tt>PREEMPT_RCU</tt> allows tasks to be preempted in the +midst of their RCU read-side critical sections, and these tasks +must be tracked explicitly. +The details of exactly why and how they are tracked will be covered +in a separate article on RCU read-side processing. +For now, it is enough to know that the <tt>rcu_node</tt> +structure tracks them. + +<pre> + 1 struct list_head blkd_tasks; + 2 struct list_head *gp_tasks; + 3 struct list_head *exp_tasks; + 4 bool wait_blkd_tasks; +</pre> + +<p>The <tt>->blkd_tasks</tt> field is a list header for +the list of blocked and preempted tasks. +As tasks undergo context switches within RCU read-side critical +sections, their <tt>task_struct</tt> structures are enqueued +(via the <tt>task_struct</tt>'s <tt>->rcu_node_entry</tt> +field) onto the head of the <tt>->blkd_tasks</tt> list for the +leaf <tt>rcu_node</tt> structure corresponding to the CPU +on which the outgoing context switch executed. +As these tasks later exit their RCU read-side critical sections, +they remove themselves from the list. +This list is therefore in reverse time order, so that if one of the tasks +is blocking the current grace period, all subsequent tasks must +also be blocking that same grace period. +Therefore, a single pointer into this list suffices to track +all tasks blocking a given grace period. +That pointer is stored in <tt>->gp_tasks</tt> for normal +grace periods and in <tt>->exp_tasks</tt> for expedited +grace periods. +These last two fields are <tt>NULL</tt> if either there is +no grace period in flight or if there are no blocked tasks +preventing that grace period from completing. +If either of these two pointers is referencing a task that +removes itself from the <tt>->blkd_tasks</tt> list, +then that task must advance the pointer to the next task on +the list, or set the pointer to <tt>NULL</tt> if there +are no subsequent tasks on the list. + +</p><p>For example, suppose that tasks T1, T2, and T3 are +all hard-affinitied to the largest-numbered CPU in the system. +Then if task T1 blocked in an RCU read-side +critical section, then an expedited grace period started, +then task T2 blocked in an RCU read-side critical section, +then a normal grace period started, and finally task 3 blocked +in an RCU read-side critical section, then the state of the +last leaf <tt>rcu_node</tt> structure's blocked-task list +would be as shown below: + +</p><p><img src="blkd_task.svg" alt="blkd_task.svg" width="60%"> + +</p><p>Task T1 is blocking both grace periods, task T2 is +blocking only the normal grace period, and task T3 is blocking +neither grace period. +Note that these tasks will not remove themselves from this list +immediately upon resuming execution. +They will instead remain on the list until they execute the outermost +<tt>rcu_read_unlock()</tt> that ends their RCU read-side critical +section. + +<p> +The <tt>->wait_blkd_tasks</tt> field indicates whether or not +the current grace period is waiting on a blocked task. + +<h5>Sizing the <tt>rcu_node</tt> Array</h5> + +<p>The <tt>rcu_node</tt> array is sized via a series of +C-preprocessor expressions as follows: + +<pre> + 1 #ifdef CONFIG_RCU_FANOUT + 2 #define RCU_FANOUT CONFIG_RCU_FANOUT + 3 #else + 4 # ifdef CONFIG_64BIT + 5 # define RCU_FANOUT 64 + 6 # else + 7 # define RCU_FANOUT 32 + 8 # endif + 9 #endif +10 +11 #ifdef CONFIG_RCU_FANOUT_LEAF +12 #define RCU_FANOUT_LEAF CONFIG_RCU_FANOUT_LEAF +13 #else +14 # ifdef CONFIG_64BIT +15 # define RCU_FANOUT_LEAF 64 +16 # else +17 # define RCU_FANOUT_LEAF 32 +18 # endif +19 #endif +20 +21 #define RCU_FANOUT_1 (RCU_FANOUT_LEAF) +22 #define RCU_FANOUT_2 (RCU_FANOUT_1 * RCU_FANOUT) +23 #define RCU_FANOUT_3 (RCU_FANOUT_2 * RCU_FANOUT) +24 #define RCU_FANOUT_4 (RCU_FANOUT_3 * RCU_FANOUT) +25 +26 #if NR_CPUS <= RCU_FANOUT_1 +27 # define RCU_NUM_LVLS 1 +28 # define NUM_RCU_LVL_0 1 +29 # define NUM_RCU_NODES NUM_RCU_LVL_0 +30 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0 } +31 # define RCU_NODE_NAME_INIT { "rcu_node_0" } +32 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0" } +33 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0" } +34 #elif NR_CPUS <= RCU_FANOUT_2 +35 # define RCU_NUM_LVLS 2 +36 # define NUM_RCU_LVL_0 1 +37 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1) +38 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1) +39 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1 } +40 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1" } +41 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1" } +42 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1" } +43 #elif NR_CPUS <= RCU_FANOUT_3 +44 # define RCU_NUM_LVLS 3 +45 # define NUM_RCU_LVL_0 1 +46 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_2) +47 # define NUM_RCU_LVL_2 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1) +48 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1 + NUM_RCU_LVL_2) +49 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1, NUM_RCU_LVL_2 } +50 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1", "rcu_node_2" } +51 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1", "rcu_node_fqs_2" } +52 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1", "rcu_node_exp_2" } +53 #elif NR_CPUS <= RCU_FANOUT_4 +54 # define RCU_NUM_LVLS 4 +55 # define NUM_RCU_LVL_0 1 +56 # define NUM_RCU_LVL_1 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_3) +57 # define NUM_RCU_LVL_2 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_2) +58 # define NUM_RCU_LVL_3 DIV_ROUND_UP(NR_CPUS, RCU_FANOUT_1) +59 # define NUM_RCU_NODES (NUM_RCU_LVL_0 + NUM_RCU_LVL_1 + NUM_RCU_LVL_2 + NUM_RCU_LVL_3) +60 # define NUM_RCU_LVL_INIT { NUM_RCU_LVL_0, NUM_RCU_LVL_1, NUM_RCU_LVL_2, NUM_RCU_LVL_3 } +61 # define RCU_NODE_NAME_INIT { "rcu_node_0", "rcu_node_1", "rcu_node_2", "rcu_node_3" } +62 # define RCU_FQS_NAME_INIT { "rcu_node_fqs_0", "rcu_node_fqs_1", "rcu_node_fqs_2", "rcu_node_fqs_3" } +63 # define RCU_EXP_NAME_INIT { "rcu_node_exp_0", "rcu_node_exp_1", "rcu_node_exp_2", "rcu_node_exp_3" } +64 #else +65 # error "CONFIG_RCU_FANOUT insufficient for NR_CPUS" +66 #endif +</pre> + +<p>The maximum number of levels in the <tt>rcu_node</tt> structure +is currently limited to four, as specified by lines 21-24 +and the structure of the subsequent “if” statement. +For 32-bit systems, this allows 16*32*32*32=524,288 CPUs, which +should be sufficient for the next few years at least. +For 64-bit systems, 16*64*64*64=4,194,304 CPUs is allowed, which +should see us through the next decade or so. +This four-level tree also allows kernels built with +<tt>CONFIG_RCU_FANOUT=8</tt> to support up to 4096 CPUs, +which might be useful in very large systems having eight CPUs per +socket (but please note that no one has yet shown any measurable +performance degradation due to misaligned socket and <tt>rcu_node</tt> +boundaries). +In addition, building kernels with a full four levels of <tt>rcu_node</tt> +tree permits better testing of RCU's combining-tree code. + +</p><p>The <tt>RCU_FANOUT</tt> symbol controls how many children +are permitted at each non-leaf level of the <tt>rcu_node</tt> tree. +If the <tt>CONFIG_RCU_FANOUT</tt> Kconfig option is not specified, +it is set based on the word size of the system, which is also +the Kconfig default. + +</p><p>The <tt>RCU_FANOUT_LEAF</tt> symbol controls how many CPUs are +handled by each leaf <tt>rcu_node</tt> structure. +Experience has shown that allowing a given leaf <tt>rcu_node</tt> +structure to handle 64 CPUs, as permitted by the number of bits in +the <tt>->qsmask</tt> field on a 64-bit system, results in +excessive contention for the leaf <tt>rcu_node</tt> structures' +<tt>->lock</tt> fields. +The number of CPUs per leaf <tt>rcu_node</tt> structure is therefore +limited to 16 given the default value of <tt>CONFIG_RCU_FANOUT_LEAF</tt>. +If <tt>CONFIG_RCU_FANOUT_LEAF</tt> is unspecified, the value +selected is based on the word size of the system, just as for +<tt>CONFIG_RCU_FANOUT</tt>. +Lines 11-19 perform this computation. + +</p><p>Lines 21-24 compute the maximum number of CPUs supported by +a single-level (which contains a single <tt>rcu_node</tt> structure), +two-level, three-level, and four-level <tt>rcu_node</tt> tree, +respectively, given the fanout specified by <tt>RCU_FANOUT</tt> +and <tt>RCU_FANOUT_LEAF</tt>. +These numbers of CPUs are retained in the +<tt>RCU_FANOUT_1</tt>, +<tt>RCU_FANOUT_2</tt>, +<tt>RCU_FANOUT_3</tt>, and +<tt>RCU_FANOUT_4</tt> +C-preprocessor variables, respectively. + +</p><p>These variables are used to control the C-preprocessor <tt>#if</tt> +statement spanning lines 26-66 that computes the number of +<tt>rcu_node</tt> structures required for each level of the tree, +as well as the number of levels required. +The number of levels is placed in the <tt>NUM_RCU_LVLS</tt> +C-preprocessor variable by lines 27, 35, 44, and 54. +The number of <tt>rcu_node</tt> structures for the topmost level +of the tree is always exactly one, and this value is unconditionally +placed into <tt>NUM_RCU_LVL_0</tt> by lines 28, 36, 45, and 55. +The rest of the levels (if any) of the <tt>rcu_node</tt> tree +are computed by dividing the maximum number of CPUs by the +fanout supported by the number of levels from the current level down, +rounding up. This computation is performed by lines 37, +46-47, and 56-58. +Lines 31-33, 40-42, 50-52, and 62-63 create initializers +for lockdep lock-class names. +Finally, lines 64-66 produce an error if the maximum number of +CPUs is too large for the specified fanout. + +<h3><a name="The rcu_data Structure"> +The <tt>rcu_data</tt> Structure</a></h3> + +<p>The <tt>rcu_data</tt> maintains the per-CPU state for the +corresponding flavor of RCU. +The fields in this structure may be accessed only from the corresponding +CPU (and from tracing) unless otherwise stated. +This structure is the +focus of quiescent-state detection and RCU callback queuing. +It also tracks its relationship to the corresponding leaf +<tt>rcu_node</tt> structure to allow more-efficient +propagation of quiescent states up the <tt>rcu_node</tt> +combining tree. +Like the <tt>rcu_node</tt> structure, it provides a local +copy of the grace-period information to allow for-free +synchronized +access to this information from the corresponding CPU. +Finally, this structure records past dyntick-idle state +for the corresponding CPU and also tracks statistics. + +</p><p>The <tt>rcu_data</tt> structure's fields are discussed, +singly and in groups, in the following sections. + +<h5>Connection to Other Data Structures</h5> + +<p>This portion of the <tt>rcu_data</tt> structure is declared +as follows: + +<pre> + 1 int cpu; + 2 struct rcu_state *rsp; + 3 struct rcu_node *mynode; + 4 struct rcu_dynticks *dynticks; + 5 unsigned long grpmask; + 6 bool beenonline; +</pre> + +<p>The <tt>->cpu</tt> field contains the number of the +corresponding CPU, the <tt>->rsp</tt> pointer references +the corresponding <tt>rcu_state</tt> structure (and is most frequently +used to locate the name of the corresponding flavor of RCU for tracing), +and the <tt>->mynode</tt> field references the corresponding +<tt>rcu_node</tt> structure. +The <tt>->mynode</tt> is used to propagate quiescent states +up the combining tree. +<p>The <tt>->dynticks</tt> pointer references the +<tt>rcu_dynticks</tt> structure corresponding to this +CPU. +Recall that a single per-CPU instance of the <tt>rcu_dynticks</tt> +structure is shared among all flavors of RCU. +These first four fields are constant and therefore require not +synchronization. + +</p><p>The <tt>->grpmask</tt> field indicates the bit in +the <tt>->mynode->qsmask</tt> corresponding to this +<tt>rcu_data</tt> structure, and is also used when propagating +quiescent states. +The <tt>->beenonline</tt> flag is set whenever the corresponding +CPU comes online, which means that the debugfs tracing need not dump +out any <tt>rcu_data</tt> structure for which this flag is not set. + +<h5>Quiescent-State and Grace-Period Tracking</h5> + +<p>This portion of the <tt>rcu_data</tt> structure is declared +as follows: + +<pre> + 1 unsigned long completed; + 2 unsigned long gpnum; + 3 bool cpu_no_qs; + 4 bool core_needs_qs; + 5 bool gpwrap; + 6 unsigned long rcu_qs_ctr_snap; +</pre> + +<p>The <tt>completed</tt> and <tt>gpnum</tt> +fields are the counterparts of the fields of the same name +in the <tt>rcu_state</tt> and <tt>rcu_node</tt> structures. +They may each lag up to one behind their <tt>rcu_node</tt> +counterparts, but in <tt>CONFIG_NO_HZ_IDLE</tt> and +<tt>CONFIG_NO_HZ_FULL</tt> kernels can lag +arbitrarily far behind for CPUs in dyntick-idle mode (but these counters +will catch up upon exit from dyntick-idle mode). +If a given <tt>rcu_data</tt> structure's <tt>->gpnum</tt> and +<tt>->complete</tt> fields are equal, then this <tt>rcu_data</tt> +structure believes that RCU is idle. +Otherwise, as with the <tt>rcu_state</tt> and <tt>rcu_node</tt> +structure, +the <tt>->gpnum</tt> field will be one greater than the +<tt>->complete</tt> fields, with <tt>->gpnum</tt> +indicating which grace period this <tt>rcu_data</tt> believes +is still being waited for. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + All this replication of the grace period numbers can only cause + massive confusion. + Why not just keep a global pair of counters and be done with it??? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + Because if there was only a single global pair of grace-period + numbers, there would need to be a single global lock to allow + safely accessing and updating them. + And if we are not going to have a single global lock, we need + to carefully manage the numbers on a per-node basis. + Recall from the answer to a previous Quick Quiz that the consequences + of applying a previously sampled quiescent state to the wrong + grace period are quite severe. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<p>The <tt>->cpu_no_qs</tt> flag indicates that the +CPU has not yet passed through a quiescent state, +while the <tt>->core_needs_qs</tt> flag indicates that the +RCU core needs a quiescent state from the corresponding CPU. +The <tt>->gpwrap</tt> field indicates that the corresponding +CPU has remained idle for so long that the <tt>completed</tt> +and <tt>gpnum</tt> counters are in danger of overflow, which +will cause the CPU to disregard the values of its counters on +its next exit from idle. +Finally, the <tt>rcu_qs_ctr_snap</tt> field is used to detect +cases where a given operation has resulted in a quiescent state +for all flavors of RCU, for example, <tt>cond_resched_rcu_qs()</tt>. + +<h5>RCU Callback Handling</h5> + +<p>In the absence of CPU-hotplug events, RCU callbacks are invoked by +the same CPU that registered them. +This is strictly a cache-locality optimization: callbacks can and +do get invoked on CPUs other than the one that registered them. +After all, if the CPU that registered a given callback has gone +offline before the callback can be invoked, there really is no other +choice. + +</p><p>This portion of the <tt>rcu_data</tt> structure is declared +as follows: + +<pre> + 1 struct rcu_head *nxtlist; + 2 struct rcu_head **nxttail[RCU_NEXT_SIZE]; + 3 unsigned long nxtcompleted[RCU_NEXT_SIZE]; + 4 long qlen_lazy; + 5 long qlen; + 6 long qlen_last_fqs_check; + 7 unsigned long n_force_qs_snap; + 8 unsigned long n_cbs_invoked; + 9 unsigned long n_cbs_orphaned; +10 unsigned long n_cbs_adopted; +11 long blimit; +</pre> + +<p>The <tt>->nxtlist</tt> pointer and the +<tt>->nxttail[]</tt> array form a four-segment list with +older callbacks near the head and newer ones near the tail. +Each segment contains callbacks with the corresponding relationship +to the current grace period. +The pointer out of the end of each of the four segments is referenced +by the element of the <tt>->nxttail[]</tt> array indexed by +<tt>RCU_DONE_TAIL</tt> (for callbacks handled by a prior grace period), +<tt>RCU_WAIT_TAIL</tt> (for callbacks waiting on the current grace period), +<tt>RCU_NEXT_READY_TAIL</tt> (for callbacks that will wait on the next +grace period), and +<tt>RCU_NEXT_TAIL</tt> (for callbacks that are not yet associated +with a specific grace period) +respectively, as shown in the following figure. + +</p><p><img src="nxtlist.svg" alt="nxtlist.svg" width="40%"> + +</p><p>In this figure, the <tt>->nxtlist</tt> pointer references the +first +RCU callback in the list. +The <tt>->nxttail[RCU_DONE_TAIL]</tt> array element references +the <tt>->nxtlist</tt> pointer itself, indicating that none +of the callbacks is ready to invoke. +The <tt>->nxttail[RCU_WAIT_TAIL]</tt> array element references callback +CB 2's <tt>->next</tt> pointer, which indicates that +CB 1 and CB 2 are both waiting on the current grace period. +The <tt>->nxttail[RCU_NEXT_READY_TAIL]</tt> array element +references the same RCU callback that <tt>->nxttail[RCU_WAIT_TAIL]</tt> +does, which indicates that there are no callbacks waiting on the next +RCU grace period. +The <tt>->nxttail[RCU_NEXT_TAIL]</tt> array element references +CB 4's <tt>->next</tt> pointer, indicating that all the +remaining RCU callbacks have not yet been assigned to an RCU grace +period. +Note that the <tt>->nxttail[RCU_NEXT_TAIL]</tt> array element +always references the last RCU callback's <tt>->next</tt> pointer +unless the callback list is empty, in which case it references +the <tt>->nxtlist</tt> pointer. + +</p><p>CPUs advance their callbacks from the +<tt>RCU_NEXT_TAIL</tt> to the <tt>RCU_NEXT_READY_TAIL</tt> to the +<tt>RCU_WAIT_TAIL</tt> to the <tt>RCU_DONE_TAIL</tt> list segments +as grace periods advance. +The CPU advances the callbacks in its <tt>rcu_data</tt> structure +whenever it notices that another RCU grace period has completed. +The CPU detects the completion of an RCU grace period by noticing +that the value of its <tt>rcu_data</tt> structure's +<tt>->completed</tt> field differs from that of its leaf +<tt>rcu_node</tt> structure. +Recall that each <tt>rcu_node</tt> structure's +<tt>->completed</tt> field is updated at the end of each +grace period. + +</p><p>The <tt>->nxtcompleted[]</tt> array records grace-period +numbers corresponding to the list segments. +This allows CPUs that go idle for extended periods to determine +which of their callbacks are ready to be invoked after reawakening. + +</p><p>The <tt>->qlen</tt> counter contains the number of +callbacks in <tt>->nxtlist</tt>, and the +<tt>->qlen_lazy</tt> contains the number of those callbacks that +are known to only free memory, and whose invocation can therefore +be safely deferred. +The <tt>->qlen_last_fqs_check</tt> and +<tt>->n_force_qs_snap</tt> coordinate the forcing of quiescent +states from <tt>call_rcu()</tt> and friends when callback +lists grow excessively long. + +</p><p>The <tt>->n_cbs_invoked</tt>, +<tt>->n_cbs_orphaned</tt>, and <tt>->n_cbs_adopted</tt> +fields count the number of callbacks invoked, +sent to other CPUs when this CPU goes offline, +and received from other CPUs when those other CPUs go offline. +Finally, the <tt>->blimit</tt> counter is the maximum number of +RCU callbacks that may be invoked at a given time. + +<h5>Dyntick-Idle Handling</h5> + +<p>This portion of the <tt>rcu_data</tt> structure is declared +as follows: + +<pre> + 1 int dynticks_snap; + 2 unsigned long dynticks_fqs; +</pre> + +The <tt>->dynticks_snap</tt> field is used to take a snapshot +of the corresponding CPU's dyntick-idle state when forcing +quiescent states, and is therefore accessed from other CPUs. +Finally, the <tt>->dynticks_fqs</tt> field is used to +count the number of times this CPU is determined to be in +dyntick-idle state, and is used for tracing and debugging purposes. + +<h3><a name="The rcu_dynticks Structure"> +The <tt>rcu_dynticks</tt> Structure</a></h3> + +<p>The <tt>rcu_dynticks</tt> maintains the per-CPU dyntick-idle state +for the corresponding CPU. +Unlike the other structures, <tt>rcu_dynticks</tt> is not +replicated over the different flavors of RCU. +The fields in this structure may be accessed only from the corresponding +CPU (and from tracing) unless otherwise stated. +Its fields are as follows: + +<pre> + 1 int dynticks_nesting; + 2 int dynticks_nmi_nesting; + 3 atomic_t dynticks; +</pre> + +<p>The <tt>->dynticks_nesting</tt> field counts the +nesting depth of normal interrupts. +In addition, this counter is incremented when exiting dyntick-idle +mode and decremented when entering it. +This counter can therefore be thought of as counting the number +of reasons why this CPU cannot be permitted to enter dyntick-idle +mode, aside from non-maskable interrupts (NMIs). +NMIs are counted by the <tt>->dynticks_nmi_nesting</tt> +field, except that NMIs that interrupt non-dyntick-idle execution +are not counted. + +</p><p>Finally, the <tt>->dynticks</tt> field counts the corresponding +CPU's transitions to and from dyntick-idle mode, so that this counter +has an even value when the CPU is in dyntick-idle mode and an odd +value otherwise. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + Why not just count all NMIs? + Wouldn't that be simpler and less error prone? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + It seems simpler only until you think hard about how to go about + updating the <tt>rcu_dynticks</tt> structure's + <tt>->dynticks</tt> field. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<p>Additional fields are present for some special-purpose +builds, and are discussed separately. + +<h3><a name="The rcu_head Structure"> +The <tt>rcu_head</tt> Structure</a></h3> + +<p>Each <tt>rcu_head</tt> structure represents an RCU callback. +These structures are normally embedded within RCU-protected data +structures whose algorithms use asynchronous grace periods. +In contrast, when using algorithms that block waiting for RCU grace periods, +RCU users need not provide <tt>rcu_head</tt> structures. + +</p><p>The <tt>rcu_head</tt> structure has fields as follows: + +<pre> + 1 struct rcu_head *next; + 2 void (*func)(struct rcu_head *head); +</pre> + +<p>The <tt>->next</tt> field is used +to link the <tt>rcu_head</tt> structures together in the +lists within the <tt>rcu_data</tt> structures. +The <tt>->func</tt> field is a pointer to the function +to be called when the callback is ready to be invoked, and +this function is passed a pointer to the <tt>rcu_head</tt> +structure. +However, <tt>kfree_rcu()</tt> uses the <tt>->func</tt> +field to record the offset of the <tt>rcu_head</tt> +structure within the enclosing RCU-protected data structure. + +</p><p>Both of these fields are used internally by RCU. +From the viewpoint of RCU users, this structure is an +opaque “cookie”. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + Given that the callback function <tt>->func</tt> + is passed a pointer to the <tt>rcu_head</tt> structure, + how is that function supposed to find the beginning of the + enclosing RCU-protected data structure? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + In actual practice, there is a separate callback function per + type of RCU-protected data structure. + The callback function can therefore use the <tt>container_of()</tt> + macro in the Linux kernel (or other pointer-manipulation facilities + in other software environments) to find the beginning of the + enclosing structure. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<h3><a name="RCU-Specific Fields in the task_struct Structure"> +RCU-Specific Fields in the <tt>task_struct</tt> Structure</a></h3> + +<p>The <tt>CONFIG_PREEMPT_RCU</tt> implementation uses some +additional fields in the <tt>task_struct</tt> structure: + +<pre> + 1 #ifdef CONFIG_PREEMPT_RCU + 2 int rcu_read_lock_nesting; + 3 union rcu_special rcu_read_unlock_special; + 4 struct list_head rcu_node_entry; + 5 struct rcu_node *rcu_blocked_node; + 6 #endif /* #ifdef CONFIG_PREEMPT_RCU */ + 7 #ifdef CONFIG_TASKS_RCU + 8 unsigned long rcu_tasks_nvcsw; + 9 bool rcu_tasks_holdout; +10 struct list_head rcu_tasks_holdout_list; +11 int rcu_tasks_idle_cpu; +12 #endif /* #ifdef CONFIG_TASKS_RCU */ +</pre> + +<p>The <tt>->rcu_read_lock_nesting</tt> field records the +nesting level for RCU read-side critical sections, and +the <tt>->rcu_read_unlock_special</tt> field is a bitmask +that records special conditions that require <tt>rcu_read_unlock()</tt> +to do additional work. +The <tt>->rcu_node_entry</tt> field is used to form lists of +tasks that have blocked within preemptible-RCU read-side critical +sections and the <tt>->rcu_blocked_node</tt> field references +the <tt>rcu_node</tt> structure whose list this task is a member of, +or <tt>NULL</tt> if it is not blocked within a preemptible-RCU +read-side critical section. + +<p>The <tt>->rcu_tasks_nvcsw</tt> field tracks the number of +voluntary context switches that this task had undergone at the +beginning of the current tasks-RCU grace period, +<tt>->rcu_tasks_holdout</tt> is set if the current tasks-RCU +grace period is waiting on this task, <tt>->rcu_tasks_holdout_list</tt> +is a list element enqueuing this task on the holdout list, +and <tt>->rcu_tasks_idle_cpu</tt> tracks which CPU this +idle task is running, but only if the task is currently running, +that is, if the CPU is currently idle. + +<h3><a name="Accessor Functions"> +Accessor Functions</a></h3> + +<p>The following listing shows the +<tt>rcu_get_root()</tt>, <tt>rcu_for_each_node_breadth_first</tt>, +<tt>rcu_for_each_nonleaf_node_breadth_first()</tt>, and +<tt>rcu_for_each_leaf_node()</tt> function and macros: + +<pre> + 1 static struct rcu_node *rcu_get_root(struct rcu_state *rsp) + 2 { + 3 return &rsp->node[0]; + 4 } + 5 + 6 #define rcu_for_each_node_breadth_first(rsp, rnp) \ + 7 for ((rnp) = &(rsp)->node[0]; \ + 8 (rnp) < &(rsp)->node[NUM_RCU_NODES]; (rnp)++) + 9 + 10 #define rcu_for_each_nonleaf_node_breadth_first(rsp, rnp) \ + 11 for ((rnp) = &(rsp)->node[0]; \ + 12 (rnp) < (rsp)->level[NUM_RCU_LVLS - 1]; (rnp)++) + 13 + 14 #define rcu_for_each_leaf_node(rsp, rnp) \ + 15 for ((rnp) = (rsp)->level[NUM_RCU_LVLS - 1]; \ + 16 (rnp) < &(rsp)->node[NUM_RCU_NODES]; (rnp)++) +</pre> + +<p>The <tt>rcu_get_root()</tt> simply returns a pointer to the +first element of the specified <tt>rcu_state</tt> structure's +<tt>->node[]</tt> array, which is the root <tt>rcu_node</tt> +structure. + +</p><p>As noted earlier, the <tt>rcu_for_each_node_breadth_first()</tt> +macro takes advantage of the layout of the <tt>rcu_node</tt> +structures in the <tt>rcu_state</tt> structure's +<tt>->node[]</tt> array, performing a breadth-first traversal by +simply traversing the array in order. +The <tt>rcu_for_each_nonleaf_node_breadth_first()</tt> macro operates +similarly, but traverses only the first part of the array, thus excluding +the leaf <tt>rcu_node</tt> structures. +Finally, the <tt>rcu_for_each_leaf_node()</tt> macro traverses only +the last part of the array, thus traversing only the leaf +<tt>rcu_node</tt> structures. + +<table> +<tr><th> </th></tr> +<tr><th align="left">Quick Quiz:</th></tr> +<tr><td> + What do <tt>rcu_for_each_nonleaf_node_breadth_first()</tt> and + <tt>rcu_for_each_leaf_node()</tt> do if the <tt>rcu_node</tt> tree + contains only a single node? +</td></tr> +<tr><th align="left">Answer:</th></tr> +<tr><td bgcolor="#ffffff"><font color="ffffff"> + In the single-node case, + <tt>rcu_for_each_nonleaf_node_breadth_first()</tt> is a no-op + and <tt>rcu_for_each_leaf_node()</tt> traverses the single node. +</font></td></tr> +<tr><td> </td></tr> +</table> + +<h3><a name="Summary"> +Summary</a></h3> + +So each flavor of RCU is represented by an <tt>rcu_state</tt> structure, +which contains a combining tree of <tt>rcu_node</tt> and +<tt>rcu_data</tt> structures. +Finally, in <tt>CONFIG_NO_HZ_IDLE</tt> kernels, each CPU's dyntick-idle +state is tracked by an <tt>rcu_dynticks</tt> structure. + +If you made it this far, you are well prepared to read the code +walkthroughs in the other articles in this series. + +<h3><a name="Acknowledgments"> +Acknowledgments</a></h3> + +I owe thanks to Cyrill Gorcunov, Mathieu Desnoyers, Dhaval Giani, Paul +Turner, Abhishek Srivastava, Matt Kowalczyk, and Serge Hallyn +for helping me get this document into a more human-readable state. + +<h3><a name="Legal Statement"> +Legal Statement</a></h3> + +<p>This work represents the view of the author and does not necessarily +represent the view of IBM. + +</p><p>Linux is a registered trademark of Linus Torvalds. + +</p><p>Other company, product, and service names may be trademarks or +service marks of others. + +</body></html>
diff --git a/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg b/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg new file mode 100644 index 0000000..2bf12b4 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/HugeTreeClassicRCU.svg
@@ -0,0 +1,939 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:37:22 2015 --> + +<!-- Magnification: 3.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="15.1in" + height="11.2in" + viewBox="-66 -66 18087 13407" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="HugeTreeClassicRCU.fig"> + <metadata + id="metadata224"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs222"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3982" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1134" + inkscape:window-height="789" + id="namedview220" + showgrid="false" + inkscape:zoom="0.60515873" + inkscape:cx="679.5" + inkscape:cy="504" + inkscape:window-x="786" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="450" + y="0" + width="17100" + height="8325" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect6" /> + <!-- Line: box --> + <rect + x="11025" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect8" /> + <!-- Line: box --> + <rect + x="4275" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect10" /> + <!-- Line: box --> + <rect + x="5400" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect12" /> + <!-- Line: box --> + <rect + x="9900" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect14" /> + <!-- Line: box --> + <rect + x="14400" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect16" /> + <!-- Line: box --> + <rect + x="900" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect18" /> + <!-- Line: box --> + <rect + x="7650" + y="900" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect20" /> + <!-- Line --> + <polyline + points="3150,9225 3150,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline22" /> + <!-- Arrowhead on XXXpoint 3150 9225 - 3150 7560--> + <!-- Circle --> + <circle + cx="8550" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle26" /> + <!-- Circle --> + <circle + cx="9000" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle28" /> + <!-- Circle --> + <circle + cx="9450" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle30" /> + <!-- Line --> + <polyline + points="6750,6300 8250,5010 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 6750 6300 - 8391 4890--> + <!-- Line --> + <polyline + points="11250,6300 9747,5010 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 11250 6300 - 9606 4890--> + <!-- Circle --> + <circle + cx="13950" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle40" /> + <!-- Circle --> + <circle + cx="13500" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle42" /> + <!-- Circle --> + <circle + cx="13050" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle44" /> + <!-- Circle --> + <circle + cx="9450" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle46" /> + <!-- Circle --> + <circle + cx="9000" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle48" /> + <!-- Circle --> + <circle + cx="8550" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle50" /> + <!-- Circle --> + <circle + cx="4950" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle52" /> + <!-- Circle --> + <circle + cx="4500" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle54" /> + <!-- Circle --> + <circle + cx="4050" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle56" /> + <!-- Circle --> + <circle + cx="1800" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle58" /> + <!-- Circle --> + <circle + cx="2250" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle60" /> + <!-- Circle --> + <circle + cx="2700" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle62" /> + <!-- Circle --> + <circle + cx="15300" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle64" /> + <!-- Circle --> + <circle + cx="15750" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle66" /> + <!-- Circle --> + <circle + cx="16200" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle68" /> + <!-- Circle --> + <circle + cx="10800" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle70" /> + <!-- Circle --> + <circle + cx="11250" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle72" /> + <!-- Circle --> + <circle + cx="11700" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle74" /> + <!-- Circle --> + <circle + cx="6300" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle76" /> + <!-- Circle --> + <circle + cx="6750" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle78" /> + <!-- Circle --> + <circle + cx="7200" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle80" /> + <!-- Line: box --> + <rect + x="0" + y="11475" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect82" /> + <!-- Line: box --> + <rect + x="1800" + y="9225" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect84" /> + <!-- Line: box --> + <rect + x="4500" + y="11475" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect86" /> + <!-- Line: box --> + <rect + x="6300" + y="9270" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect88" /> + <!-- Line: box --> + <rect + x="8955" + y="11475" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect90" /> + <!-- Line: box --> + <rect + x="10755" + y="9270" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect92" /> + <!-- Line: box --> + <rect + x="13455" + y="11475" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect94" /> + <!-- Line: box --> + <rect + x="15255" + y="9270" + width="2700" + height="1800" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect96" /> + <!-- Line --> + <polyline + points="11700,3600 10197,2310 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline98" /> + <!-- Arrowhead on XXXpoint 11700 3600 - 10056 2190--> + <!-- Line --> + <polyline + points="6300,3600 7800,2310 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline102" /> + <!-- Arrowhead on XXXpoint 6300 3600 - 7941 2190--> + <!-- Line --> + <polyline + points="3150,6300 4650,5010 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline106" /> + <!-- Arrowhead on XXXpoint 3150 6300 - 4791 4890--> + <!-- Line --> + <polyline + points="14850,6300 13347,5010 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline110" /> + <!-- Arrowhead on XXXpoint 14850 6300 - 13206 4890--> + <!-- Line --> + <polyline + points="1350,11475 1350,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline114" /> + <!-- Arrowhead on XXXpoint 1350 11475 - 1350 7560--> + <!-- Line --> + <polyline + points="16650,9225 16650,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline118" /> + <!-- Arrowhead on XXXpoint 16650 9225 - 16650 7560--> + <!-- Line --> + <polyline + points="14850,11475 14850,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline122" /> + <!-- Arrowhead on XXXpoint 14850 11475 - 14850 7560--> + <!-- Line --> + <polyline + points="12150,9225 12150,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline126" /> + <!-- Arrowhead on XXXpoint 12150 9225 - 12150 7560--> + <!-- Line --> + <polyline + points="10350,11475 10350,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline130" /> + <!-- Arrowhead on XXXpoint 10350 11475 - 10350 7560--> + <!-- Line --> + <polyline + points="7650,9225 7650,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline134" /> + <!-- Arrowhead on XXXpoint 7650 9225 - 7650 7560--> + <!-- Line --> + <polyline + points="5850,11475 5850,7746 " + style="stroke:#00d1d1;stroke-width:44.99790066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline138" /> + <!-- Arrowhead on XXXpoint 5850 11475 - 5850 7560--> + <!-- Text --> + <text + xml:space="preserve" + x="12375" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text142">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="12375" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text144">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5625" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text146">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5625" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text148">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="6750" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text150">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="6750" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text152">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="11250" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text154">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="11250" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text156">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="15750" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text158">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="15750" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text160">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text162">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text164">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1350" + y="13050" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text166">CPU 0</text> + <!-- Text --> + <text + xml:space="preserve" + x="1350" + y="11925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text168">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1350" + y="12375" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text170">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="10800" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text172">CPU 15</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="9675" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text174">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="10125" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text176">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5850" + y="11925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text178">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5850" + y="12375" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text180">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5850" + y="13050" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text182">CPU 21823</text> + <!-- Text --> + <text + xml:space="preserve" + x="7650" + y="10845" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text184">CPU 21839</text> + <!-- Text --> + <text + xml:space="preserve" + x="7650" + y="10170" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text186">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="7650" + y="9720" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text188">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="10305" + y="11925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text190">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="10305" + y="12375" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text192">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="10305" + y="13050" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text194">CPU 43679</text> + <!-- Text --> + <text + xml:space="preserve" + x="12105" + y="10845" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text196">CPU 43695</text> + <!-- Text --> + <text + xml:space="preserve" + x="12105" + y="10170" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text198">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="12105" + y="9720" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text200">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="14805" + y="11925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text202">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="14805" + y="12375" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text204">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="14805" + y="13050" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text206">CPU 65519</text> + <!-- Text --> + <text + xml:space="preserve" + x="16605" + y="10845" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text208">CPU 65535</text> + <!-- Text --> + <text + xml:space="preserve" + x="16605" + y="10170" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text210">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="16605" + y="9720" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text212">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="675" + y="450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="start" + id="text214">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="9000" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text216">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="9000" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text218">rcu_node</text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeLevel.svg b/Documentation/RCU/Design/Data-Structures/TreeLevel.svg new file mode 100644 index 0000000..7a7eb3b --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/TreeLevel.svg
@@ -0,0 +1,828 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:41:29 2015 --> + +<!-- Magnification: 3.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="17.7in" + height="10.4in" + viewBox="-66 -66 21237 12507" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="TreeLevel.fig"> + <metadata + id="metadata216"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs214"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3974" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1023" + inkscape:window-height="1148" + id="namedview212" + showgrid="false" + inkscape:zoom="0.55869424" + inkscape:cx="796.50006" + inkscape:cy="467.99997" + inkscape:window-x="897" + inkscape:window-y="24" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="20655" + height="8325" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect6" /> + <!-- Line: box --> + <rect + x="14130" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect8" /> + <!-- Line: box --> + <rect + x="7380" + y="3600" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect10" /> + <!-- Line: box --> + <rect + x="8505" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect12" /> + <!-- Line: box --> + <rect + x="13005" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect14" /> + <!-- Line: box --> + <rect + x="17505" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect16" /> + <!-- Line: box --> + <rect + x="4005" + y="6300" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect18" /> + <!-- Line: box --> + <rect + x="10755" + y="900" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect20" /> + <!-- Line --> + <polyline + points="6255,9225 6255,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline22" /> + <!-- Arrowhead on XXXpoint 6255 9225 - 6255 7560--> + <!-- Circle --> + <circle + cx="11655" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle26" /> + <!-- Circle --> + <circle + cx="12105" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle28" /> + <!-- Circle --> + <circle + cx="12555" + cy="4275" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle30" /> + <!-- Line --> + <polyline + points="9855,6300 11355,5010 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 9855 6300 - 11496 4890--> + <!-- Line --> + <polyline + points="14355,6300 12852,5010 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 14355 6300 - 12711 4890--> + <!-- Circle --> + <circle + cx="17055" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle40" /> + <!-- Circle --> + <circle + cx="16605" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle42" /> + <!-- Circle --> + <circle + cx="16155" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle44" /> + <!-- Circle --> + <circle + cx="12555" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle46" /> + <!-- Circle --> + <circle + cx="12105" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle48" /> + <!-- Circle --> + <circle + cx="11655" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle50" /> + <!-- Circle --> + <circle + cx="8055" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle52" /> + <!-- Circle --> + <circle + cx="7605" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle54" /> + <!-- Circle --> + <circle + cx="7155" + cy="6975" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle56" /> + <!-- Circle --> + <circle + cx="4905" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle58" /> + <!-- Circle --> + <circle + cx="5355" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle60" /> + <!-- Circle --> + <circle + cx="5805" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle62" /> + <!-- Circle --> + <circle + cx="18405" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle64" /> + <!-- Circle --> + <circle + cx="18855" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle66" /> + <!-- Circle --> + <circle + cx="19305" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle68" /> + <!-- Circle --> + <circle + cx="13905" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle70" /> + <!-- Circle --> + <circle + cx="14355" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle72" /> + <!-- Circle --> + <circle + cx="14805" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle74" /> + <!-- Circle --> + <circle + cx="9405" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle76" /> + <!-- Circle --> + <circle + cx="9855" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle78" /> + <!-- Circle --> + <circle + cx="10305" + cy="8775" + r="114" + style="fill:#000000;stroke:#000000;stroke-width:21;" + id="circle80" /> + <!-- Line: box --> + <rect + x="225" + y="1125" + width="3150" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect82" /> + <!-- Line: box --> + <rect + x="225" + y="2250" + width="3150" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect84" /> + <!-- Line: box --> + <rect + x="225" + y="3375" + width="3150" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:21; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect86" /> + <!-- Line --> + <polyline + points="14805,3600 13302,2310 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline88" /> + <!-- Arrowhead on XXXpoint 14805 3600 - 13161 2190--> + <!-- Line --> + <polyline + points="9405,3600 10905,2310 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline92" /> + <!-- Arrowhead on XXXpoint 9405 3600 - 11046 2190--> + <!-- Line --> + <polyline + points="6255,6300 7755,5010 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline96" /> + <!-- Arrowhead on XXXpoint 6255 6300 - 7896 4890--> + <!-- Line --> + <polyline + points="17955,6300 16452,5010 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline100" /> + <!-- Arrowhead on XXXpoint 17955 6300 - 16311 4890--> + <!-- Line --> + <polyline + points="4455,11025 4455,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline104" /> + <!-- Arrowhead on XXXpoint 4455 11025 - 4455 7560--> + <!-- Line --> + <polyline + points="19755,9225 19755,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline108" /> + <!-- Arrowhead on XXXpoint 19755 9225 - 19755 7560--> + <!-- Line --> + <polyline + points="17955,11025 17955,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline112" /> + <!-- Arrowhead on XXXpoint 17955 11025 - 17955 7560--> + <!-- Line --> + <polyline + points="15255,9225 15255,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline116" /> + <!-- Arrowhead on XXXpoint 15255 9225 - 15255 7560--> + <!-- Line --> + <polyline + points="13455,11025 13455,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline120" /> + <!-- Arrowhead on XXXpoint 13455 11025 - 13455 7560--> + <!-- Line --> + <polyline + points="10755,9225 10755,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline124" /> + <!-- Arrowhead on XXXpoint 10755 9225 - 10755 7560--> + <!-- Line --> + <polyline + points="8955,11025 8955,7746 " + style="stroke:#00d1d1;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline128" /> + <!-- Arrowhead on XXXpoint 8955 11025 - 8955 7560--> + <!-- Line: box --> + <rect + x="12105" + y="11025" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect132" /> + <!-- Line: box --> + <rect + x="13905" + y="9225" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect134" /> + <!-- Line: box --> + <rect + x="16605" + y="11025" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect136" /> + <!-- Line: box --> + <rect + x="18405" + y="9225" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect138" /> + <!-- Line: box --> + <rect + x="9405" + y="9225" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect140" /> + <!-- Line: box --> + <rect + x="7605" + y="11025" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect142" /> + <!-- Line: box --> + <rect + x="4905" + y="9225" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect144" /> + <!-- Line: box --> + <rect + x="3105" + y="11025" + width="2700" + height="1350" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect146" /> + <!-- Line --> + <polyline + points="3375,1575 10701,1575 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline148" /> + <!-- Arrowhead on XXXpoint 3375 1575 - 10890 1575--> + <!-- Line --> + <polyline + points="3375,3825 4050,3825 4050,5400 2700,5400 2700,6975 3951,6975 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline152" /> + <!-- Arrowhead on XXXpoint 2700 6975 - 4140 6975--> + <!-- Line --> + <polyline + points="3375,2700 5175,2700 5175,4275 7326,4275 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline156" /> + <!-- Arrowhead on XXXpoint 5175 4275 - 7515 4275--> + <!-- Text --> + <text + xml:space="preserve" + x="15480" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text160">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="15480" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text162">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8730" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text164">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="8730" + y="4500" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text166">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="9855" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text168">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="9855" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text170">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="14355" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text172">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="14355" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text174">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="18855" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text176">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="18855" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text178">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5355" + y="6750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text180">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5355" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text182">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text184">->level[0]</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="2925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text186">->level[1]</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text188">->level[2]</text> + <!-- Text --> + <text + xml:space="preserve" + x="12105" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text190">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="12105" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="middle" + id="text192">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="6255" + y="10125" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text194">CPU 15</text> + <!-- Text --> + <text + xml:space="preserve" + x="4455" + y="11925" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text196">CPU 0</text> + <!-- Text --> + <text + xml:space="preserve" + x="19755" + y="10125" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text198">CPU 65535</text> + <!-- Text --> + <text + xml:space="preserve" + x="17955" + y="11925" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text200">CPU 65519</text> + <!-- Text --> + <text + xml:space="preserve" + x="15255" + y="10125" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text202">CPU 43695</text> + <!-- Text --> + <text + xml:space="preserve" + x="13455" + y="11925" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text204">CPU 43679</text> + <!-- Text --> + <text + xml:space="preserve" + x="10755" + y="10125" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text206">CPU 21839</text> + <!-- Text --> + <text + xml:space="preserve" + x="8955" + y="11925" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text208">CPU 21823</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="450" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="288" + text-anchor="start" + id="text210">struct rcu_state</text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeMapping.svg b/Documentation/RCU/Design/Data-Structures/TreeMapping.svg new file mode 100644 index 0000000..729cfa9 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/TreeMapping.svg
@@ -0,0 +1,305 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:43:22 2015 --> + +<!-- Magnification: 1.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="3.1in" + height="0.9in" + viewBox="-12 -12 3699 1074" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="TreeMapping.fig"> + <metadata + id="metadata66"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs64"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow2Lend" + style="overflow:visible;"> + <path + id="path3836" + style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " + transform="scale(1.1) rotate(180) translate(1,0)" /> + </marker> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow2Mend" + style="overflow:visible;"> + <path + id="path3842" + style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " + transform="scale(0.6) rotate(180) translate(0,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3824" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="991" + inkscape:window-height="606" + id="namedview62" + showgrid="false" + inkscape:zoom="3.0752688" + inkscape:cx="139.5" + inkscape:cy="40.5" + inkscape:window-x="891" + inkscape:window-y="177" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="3675" + height="1050" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect6" /> + <!-- Line: box --> + <rect + x="75" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect8" /> + <!-- Line: box --> + <rect + x="600" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect10" /> + <!-- Line: box --> + <rect + x="1125" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect12" /> + <!-- Line: box --> + <rect + x="1650" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect14" /> + <!-- Line: box --> + <rect + x="2175" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect16" /> + <!-- Line: box --> + <rect + x="3225" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect18" /> + <!-- Line --> + <polyline + points="675,375 675,150 300,150 300,358 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline20" /> + <!-- Arrowhead on XXXpoint 300 150 - 300 390--> + <!-- Line --> + <polyline + points="1200,675 1200,900 300,900 300,691 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline24" /> + <!-- Arrowhead on XXXpoint 300 900 - 300 660--> + <!-- Line --> + <polyline + points="1725,375 1725,150 900,150 900,358 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline28" /> + <!-- Arrowhead on XXXpoint 900 150 - 900 390--> + <!-- Line --> + <polyline + points="2250,375 2250,75 825,75 825,358 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 825 75 - 825 390--> + <!-- Line --> + <polyline + points="2775,675 2775,900 1425,900 1425,691 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 1425 900 - 1425 660--> + <!-- Line --> + <polyline + points="3300,675 3300,975 1350,975 1350,691 " + style="stroke:#000000;stroke-width:7.00088889;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline40" /> + <!-- Arrowhead on XXXpoint 1350 975 - 1350 660--> + <!-- Line: box --> + <rect + x="2700" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect44" /> + <!-- Text --> + <text + xml:space="preserve" + x="300" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text46">0:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="1350" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text48">4:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="1875" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text50">0:1 </text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text52">2:3 </text> + <!-- Text --> + <text + xml:space="preserve" + x="2925" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text54">4:5 </text> + <!-- Text --> + <text + xml:space="preserve" + x="3450" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text56">6:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="825" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text58">0:3 </text> + <!-- Text --> + <text + xml:space="preserve" + x="3600" + y="150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="end" + id="text60">struct rcu_state</text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg b/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg new file mode 100644 index 0000000..5b416a4 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/TreeMappingLevel.svg
@@ -0,0 +1,380 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:45:19 2015 --> + +<!-- Magnification: 1.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="3.1in" + height="1.8in" + viewBox="-12 -12 3699 2124" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="TreeMappingLevel.svg"> + <metadata + id="metadata98"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs96"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow2Lend" + style="overflow:visible;"> + <path + id="path3868" + style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" + d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " + transform="scale(1.1) rotate(180) translate(1,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1598" + inkscape:window-height="1211" + id="namedview94" + showgrid="false" + inkscape:zoom="5.2508961" + inkscape:cx="139.5" + inkscape:cy="81" + inkscape:window-x="840" + inkscape:window-y="122" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="3675" + height="2100" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect6" /> + <!-- Line: box --> + <rect + x="75" + y="1350" + width="750" + height="225" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect8" /> + <!-- Line: box --> + <rect + x="75" + y="1575" + width="750" + height="225" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect10" /> + <!-- Line: box --> + <rect + x="75" + y="1800" + width="750" + height="225" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect12" /> + <!-- Arc --> + <path + style="stroke:#000000;stroke-width:7;stroke-linecap:butt;" + d="M 1800,900 A 118 118 0 0 0 1800 1125 " + id="path14" /> + <!-- Arc --> + <path + style="stroke:#000000;stroke-width:7;stroke-linecap:butt;" + d="M 750,900 A 75 75 0 0 0 750 1050 " + id="path16" /> + <!-- Line --> + <polyline + points="750,900 750,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline18" /> + <!-- Arrowhead on XXXpoint 750 900 - 750 660--> + <!-- Line: box --> + <rect + x="75" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect22" /> + <!-- Line: box --> + <rect + x="600" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect24" /> + <!-- Line: box --> + <rect + x="1650" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect26" /> + <!-- Line: box --> + <rect + x="2175" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect28" /> + <!-- Line: box --> + <rect + x="3225" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect30" /> + <!-- Line --> + <polyline + points="675,375 675,150 300,150 300,358 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 300 150 - 300 390--> + <!-- Line --> + <polyline + points="1725,375 1725,150 900,150 900,358 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 900 150 - 900 390--> + <!-- Line --> + <polyline + points="2250,375 2250,75 825,75 825,358 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline40" /> + <!-- Arrowhead on XXXpoint 825 75 - 825 390--> + <!-- Line --> + <polyline + points="2775,675 2775,975 1425,975 1425,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline44" /> + <!-- Arrowhead on XXXpoint 1425 975 - 1425 660--> + <!-- Line: box --> + <rect + x="2700" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect48" /> + <!-- Line: box --> + <rect + x="1125" + y="375" + width="375" + height="300" + rx="0" + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect50" /> + <!-- Line --> + <polyline + points="3300,675 3300,1050 1350,1050 1350,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline52" /> + <!-- Arrowhead on XXXpoint 1350 1050 - 1350 660--> + <!-- Line --> + <polyline + points="825,1425 975,1425 975,1200 225,1200 225,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline56" /> + <!-- Arrowhead on XXXpoint 225 1200 - 225 660--> + <!-- Line --> + <polyline + points="1200,675 1200,975 300,975 300,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline60" /> + <!-- Arrowhead on XXXpoint 300 975 - 300 660--> + <!-- Text --> + <text + xml:space="preserve" + x="150" + y="1500" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="108" + text-anchor="start" + id="text64">->level[0]</text> + <!-- Text --> + <text + xml:space="preserve" + x="150" + y="1725" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="108" + text-anchor="start" + id="text66">->level[1]</text> + <!-- Text --> + <text + xml:space="preserve" + x="150" + y="1950" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="108" + text-anchor="start" + id="text68">->level[2]</text> + <!-- Text --> + <text + xml:space="preserve" + x="300" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text70">0:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="1350" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text72">4:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="1875" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text74">0:1 </text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text76">2:3 </text> + <!-- Text --> + <text + xml:space="preserve" + x="2925" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text78">4:5 </text> + <!-- Text --> + <text + xml:space="preserve" + x="3450" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text80">6:7 </text> + <!-- Text --> + <text + xml:space="preserve" + x="825" + y="525" + fill="#000000" + font-family="Times" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="middle" + id="text82">0:3 </text> + <!-- Text --> + <text + xml:space="preserve" + x="3600" + y="150" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="normal" + font-size="96" + text-anchor="end" + id="text84">struct rcu_state</text> + <!-- Line --> + <polyline + points="825,1875 1800,1875 1800,1125 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:none" + id="polyline86" /> + <!-- Line --> + <polyline + points="1800,900 1800,691 " + style="stroke:#000000;stroke-width:7.00025806;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Lend)" + id="polyline88" /> + <!-- Arrowhead on XXXpoint 1800 900 - 1800 660--> + <!-- Line --> + <polyline + points="825,1650 1200,1650 1200,1125 750,1125 750,1050 " + style="stroke:#000000;stroke-width:7; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline92" /> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/blkd_task.svg b/Documentation/RCU/Design/Data-Structures/blkd_task.svg new file mode 100644 index 0000000..00e810b --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/blkd_task.svg
@@ -0,0 +1,843 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:35:03 2015 --> + +<!-- Magnification: 2.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="10.1in" + height="8.6in" + viewBox="-44 -44 12088 10288" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="blkd_task.fig"> + <metadata + id="metadata212"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs210"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3970" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="1087" + inkscape:window-height="1144" + id="namedview208" + showgrid="false" + inkscape:zoom="1.0495049" + inkscape:cx="454.50003" + inkscape:cy="387.00003" + inkscape:window-x="833" + inkscape:window-y="28" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="450" + y="0" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="4950" + y="4950" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect8" /> + <!-- Line: box --> + <rect + x="750" + y="600" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect10" /> + <!-- Line --> + <polyline + points="5250,8100 5688,5912 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline12" /> + <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790--> + <polyline + points="5714 6068 5704 5822 5598 6044 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline14" /> + <!-- Line --> + <polyline + points="4050,9300 4486,7262 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline16" /> + <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140--> + <polyline + points="4514 7418 4506 7172 4396 7394 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline18" /> + <!-- Line --> + <polyline + points="1040,9300 1476,7262 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline20" /> + <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140--> + <polyline + points="1504 7418 1496 7172 1386 7394 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline22" /> + <!-- Line --> + <polyline + points="2240,8100 2676,6062 " + style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="polyline24" /> + <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940--> + <polyline + points="2704 6218 2696 5972 2586 6194 " + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " + id="polyline26" /> + <!-- Line: box --> + <rect + x="0" + y="450" + width="6300" + height="7350" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + id="rect28" /> + <!-- Line: box --> + <rect + x="300" + y="1050" + width="5700" + height="3750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + id="rect30" /> + <!-- Line --> + <polyline + points="1350,3450 2350,2590 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline32" /> + <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> + <!-- Line --> + <polyline + points="4950,3450 3948,2590 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline36" /> + <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> + <!-- Line --> + <polyline + points="4050,6600 4050,4414 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline40" /> + <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> + <!-- Line --> + <polyline + points="1050,6600 1050,4414 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline44" /> + <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> + <!-- Line --> + <polyline + points="2250,5400 2250,4414 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline48" /> + <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> + <!-- Line --> + <polyline + points="2250,8100 2250,6364 " + style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline52" /> + <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240--> + <!-- Line --> + <polyline + points="1050,9300 1050,7564 " + style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline56" /> + <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440--> + <!-- Line --> + <polyline + points="4050,9300 4050,7564 " + style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline60" /> + <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440--> + <!-- Line --> + <polyline + points="5250,8100 5250,6364 " + style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline64" /> + <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240--> + <!-- Circle --> + <circle + cx="2850" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle68" /> + <!-- Circle --> + <circle + cx="3150" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle70" /> + <!-- Circle --> + <circle + cx="3450" + cy="3900" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle72" /> + <!-- Circle --> + <circle + cx="1350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle74" /> + <!-- Circle --> + <circle + cx="1650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle76" /> + <!-- Circle --> + <circle + cx="1950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle78" /> + <!-- Circle --> + <circle + cx="4350" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle80" /> + <!-- Circle --> + <circle + cx="4650" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle82" /> + <!-- Circle --> + <circle + cx="4950" + cy="5100" + r="76" + style="fill:#000000;stroke:#000000;stroke-width:14;" + id="circle84" /> + <!-- Line: box --> + <rect + x="750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect86" /> + <!-- Line: box --> + <rect + x="300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect88" /> + <!-- Line: box --> + <rect + x="4500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect90" /> + <!-- Line: box --> + <rect + x="3300" + y="6600" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect92" /> + <!-- Line: box --> + <rect + x="2250" + y="1650" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect94" /> + <!-- Line: box --> + <rect + x="0" + y="9300" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect96" /> + <!-- Line: box --> + <rect + x="1350" + y="8100" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect98" /> + <!-- Line: box --> + <rect + x="3000" + y="9300" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect100" /> + <!-- Line: box --> + <rect + x="4350" + y="8100" + width="2100" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " + id="rect102" /> + <!-- Line: box --> + <rect + x="1500" + y="5400" + width="1500" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect104" /> + <!-- Line --> + <polygon + points="5550,3450 7350,2850 7350,5100 5550,4350 5550,3450 " + style="stroke:#000000;stroke-width:14; stroke-linejoin:miter; stroke-linecap:butt; stroke-dasharray:120 120;fill:#ffbfbf; " + id="polygon106" /> + <!-- Line --> + <polyline + points="9300,3150 10734,3150 " + style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline108" /> + <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150--> + <!-- Line: box --> + <rect + x="10800" + y="2850" + width="1200" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect112" /> + <!-- Line --> + <polyline + points="11400,3600 11400,4284 " + style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline114" /> + <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410--> + <!-- Line: box --> + <rect + x="10800" + y="4350" + width="1200" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect118" /> + <!-- Line --> + <polyline + points="11400,5100 11400,5784 " + style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline120" /> + <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910--> + <!-- Line: box --> + <rect + x="10800" + y="5850" + width="1200" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect124" /> + <!-- Line --> + <polyline + points="9300,3900 9900,3900 9900,4650 10734,4650 " + style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline126" /> + <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650--> + <!-- Line --> + <polyline + points="9300,4650 9600,4650 9600,6150 10734,6150 " + style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline130" /> + <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150--> + <!-- Text --> + <text + xml:space="preserve" + x="6450" + y="300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text134">rcu_bh</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="1950" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text136">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="3150" + y="2250" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text138">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text140">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text142">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text144">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text146">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text148">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text150">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="5700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text152">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5250" + y="6000" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text154">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="6900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text156">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="7200" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text158">rcu_data</text> + <!-- Text --> + <text + xml:space="preserve" + x="450" + y="1350" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text160">struct rcu_state</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="9600" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text162">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="1050" + y="9900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text164">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="9600" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text166">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="4050" + y="9900" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text168">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text170">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="2400" + y="8700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text172">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8400" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text174">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="5400" + y="8700" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text176">rcu_dynticks</text> + <!-- Text --> + <text + xml:space="preserve" + x="6000" + y="750" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="192" + text-anchor="end" + id="text178">rcu_sched</text> + <!-- Text --> + <text + xml:space="preserve" + x="11400" + y="3300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="216" + text-anchor="middle" + id="text180">T3</text> + <!-- Text --> + <text + xml:space="preserve" + x="11400" + y="4800" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="216" + text-anchor="middle" + id="text182">T2</text> + <!-- Text --> + <text + xml:space="preserve" + x="11400" + y="6300" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="216" + text-anchor="middle" + id="text184">T1</text> + <!-- Line --> + <polyline + points="5250,5400 5250,4414 " + style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline186" /> + <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> + <!-- Line: box --> + <rect + x="3750" + y="3450" + width="1800" + height="900" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect190" /> + <!-- Line: box --> + <rect + x="7350" + y="2850" + width="1950" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect192" /> + <!-- Line: box --> + <rect + x="7350" + y="3600" + width="1950" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect194" /> + <!-- Line: box --> + <rect + x="7350" + y="4350" + width="1950" + height="750" + rx="0" + style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + id="rect196" /> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text198">rcu_node</text> + <!-- Text --> + <text + xml:space="preserve" + x="4650" + y="3750" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="middle" + id="text200">struct</text> + <!-- Text --> + <text + xml:space="preserve" + x="7500" + y="3300" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text202">blkd_tasks</text> + <!-- Text --> + <text + xml:space="preserve" + x="7500" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text204">gp_tasks</text> + <!-- Text --> + <text + xml:space="preserve" + x="7500" + y="4800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="192" + text-anchor="start" + id="text206">exp_tasks</text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Data-Structures/nxtlist.svg b/Documentation/RCU/Design/Data-Structures/nxtlist.svg new file mode 100644 index 0000000..abc4cc7 --- /dev/null +++ b/Documentation/RCU/Design/Data-Structures/nxtlist.svg
@@ -0,0 +1,396 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> + +<!-- CreationDate: Wed Dec 9 17:39:46 2015 --> + +<!-- Magnification: 3.000 --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="10.4in" + height="10.4in" + viewBox="-66 -66 12507 12507" + id="svg2" + version="1.1" + inkscape:version="0.48.4 r9939" + sodipodi:docname="nxtlist.fig"> + <metadata + id="metadata94"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs92"> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Mend" + style="overflow:visible;"> + <path + id="path3852" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" + transform="scale(0.4) rotate(180) translate(10,0)" /> + </marker> + </defs> + <sodipodi:namedview + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1" + objecttolerance="10" + gridtolerance="10" + guidetolerance="10" + inkscape:pageopacity="0" + inkscape:pageshadow="2" + inkscape:window-width="925" + inkscape:window-height="928" + id="namedview90" + showgrid="false" + inkscape:zoom="0.80021373" + inkscape:cx="467.99997" + inkscape:cy="467.99997" + inkscape:window-x="948" + inkscape:window-y="73" + inkscape:window-maximized="0" + inkscape:current-layer="g4" /> + <g + style="stroke-width:.025in; fill:none" + id="g4"> + <!-- Line: box --> + <rect + x="0" + y="0" + width="7875" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect6" /> + <!-- Line: box --> + <rect + x="0" + y="1125" + width="7875" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect8" /> + <!-- Line: box --> + <rect + x="0" + y="2250" + width="7875" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect10" /> + <!-- Line: box --> + <rect + x="0" + y="3375" + width="7875" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect12" /> + <!-- Line: box --> + <rect + x="0" + y="4500" + width="7875" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + id="rect14" /> + <!-- Line: box --> + <rect + x="10575" + y="0" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect16" /> + <!-- Line: box --> + <rect + x="10575" + y="1125" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect18" /> + <!-- Line --> + <polyline + points="11475,2250 11475,3276 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline20" /> + <!-- Arrowhead on XXXpoint 11475 2250 - 11475 3465--> + <!-- Line: box --> + <rect + x="10575" + y="6750" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect24" /> + <!-- Line: box --> + <rect + x="10575" + y="7875" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect26" /> + <!-- Line: box --> + <rect + x="10575" + y="10125" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect28" /> + <!-- Line: box --> + <rect + x="10575" + y="11250" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect30" /> + <!-- Line: box --> + <rect + x="10575" + y="3375" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect32" /> + <!-- Line --> + <polyline + points="11475,5625 11475,6651 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline34" /> + <!-- Arrowhead on XXXpoint 11475 5625 - 11475 6840--> + <!-- Line --> + <polyline + points="7875,225 10476,225 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline38" /> + <!-- Arrowhead on XXXpoint 7875 225 - 10665 225--> + <!-- Line --> + <polyline + points="7875,1350 9675,1350 9675,675 7971,675 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline42" /> + <!-- Arrowhead on XXXpoint 9675 675 - 7785 675--> + <!-- Line --> + <polyline + points="7875,2475 9675,2475 9675,4725 10476,4725 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline46" /> + <!-- Arrowhead on XXXpoint 9675 4725 - 10665 4725--> + <!-- Line --> + <polyline + points="7875,3600 9225,3600 9225,5175 10476,5175 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline50" /> + <!-- Arrowhead on XXXpoint 9225 5175 - 10665 5175--> + <!-- Line --> + <polyline + points="7875,4725 8775,4725 8775,11475 10476,11475 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline54" /> + <!-- Arrowhead on XXXpoint 8775 11475 - 10665 11475--> + <!-- Line: box --> + <rect + x="10575" + y="4500" + width="1800" + height="1125" + rx="0" + style="stroke:#000000;stroke-width:45; stroke-linejoin:miter; stroke-linecap:butt; " + id="rect58" /> + <!-- Line --> + <polyline + points="11475,9000 11475,10026 " + style="stroke:#000000;stroke-width:45.00382345;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline60" /> + <!-- Arrowhead on XXXpoint 11475 9000 - 11475 10215--> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="675" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text64">nxtlist</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="1800" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text66">nxttail[RCU_DONE_TAIL]</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="2925" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text68">nxttail[RCU_WAIT_TAIL]</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="4050" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text70">nxttail[RCU_NEXT_READY_TAIL]</text> + <!-- Text --> + <text + xml:space="preserve" + x="225" + y="5175" + fill="#000000" + font-family="Courier" + font-style="normal" + font-weight="bold" + font-size="324" + text-anchor="start" + id="text72">nxttail[RCU_NEXT_TAIL]</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="675" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text74">CB 1</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="1800" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text76">next</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="7425" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text78">CB 3</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="8550" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text80">next</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="10800" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text82">CB 4</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="11925" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text84">next</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="4050" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text86">CB 2</text> + <!-- Text --> + <text + xml:space="preserve" + x="11475" + y="5175" + fill="#000000" + font-family="Helvetica" + font-style="normal" + font-weight="normal" + font-size="324" + text-anchor="middle" + id="text88">next</text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg new file mode 100644 index 0000000..4b4014f --- /dev/null +++ b/Documentation/RCU/Design/Requirements/GPpartitionReaders1.svg
@@ -0,0 +1,374 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="447.99197" + height="428.19299" + id="svg2" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="GPpartitionReaders1.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3792" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart" + style="overflow:visible"> + <path + id="path3789" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.6184291" + inkscape:cx="223.99599" + inkscape:cy="214.0965" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="979" + inkscape:window-height="836" + inkscape:window-x="571" + inkscape:window-y="335" + inkscape:window-maximized="0" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-28.441125,-185.60612)"> + <flowRoot + xml:space="preserve" + id="flowRoot2985" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + id="flowRegion2987"><rect + id="rect2989" + width="82.85714" + height="11.428572" + x="240" + y="492.36218" /></flowRegion><flowPara + id="flowPara2991"></flowPara></flowRoot> <g + id="g4433" + transform="translate(2,0)"> + <text + sodipodi:linespacing="125%" + id="text2993" + y="-261.66608" + x="412.12299" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + xml:space="preserve" + transform="matrix(0,1,-1,0,0,0)"><tspan + y="-261.66608" + x="412.12299" + id="tspan2995" + sodipodi:role="line">synchronize_rcu()</tspan></text> + <g + id="g4417" + transform="matrix(0,1,-1,0,730.90257,222.4928)"> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)" + d="m 97.580736,477.4048 183.140664,0" + id="path2997" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 96.752718,465.38398 0,22.62742" + id="path4397" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 281.54942,465.38397 0,22.62742" + id="path4397-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="268.18076" + id="text4429" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431" + x="112.04738" + y="268.18076">WRITE_ONCE(a, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="439.13766" + id="text4441" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4443" + x="112.04738" + y="439.13766">WRITE_ONCE(b, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.60869" + y="309.29346" + id="text4445" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4447" + x="255.60869" + y="309.29346">r1 = READ_ONCE(a);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.14423" + y="520.61786" + id="text4449" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4451" + x="255.14423" + y="520.61786">WRITE_ONCE(c, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="384.71124" + id="text4453" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4455" + x="396.10254" + y="384.71124">r2 = READ_ONCE(b);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="582.13617" + id="text4457" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4459" + x="396.10254" + y="582.13617">r3 = READ_ONCE(c);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.08231" + y="213.91006" + id="text4461" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463" + x="112.08231" + y="213.91006">thread0()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="252.34512" + y="213.91006" + id="text4461-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-0" + x="252.34512" + y="213.91006">thread1()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.42557" + y="213.91006" + id="text4461-2" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-2" + x="396.42557" + y="213.91006">thread2()</tspan></text> + <rect + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="rect4495" + width="436.28488" + height="416.4859" + x="34.648232" + y="191.10612" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 183.14066,191.10612 0,417.193 -0.70711,0" + id="path4497" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + d="m 325.13867,191.10612 0,417.193 -0.70711,0" + id="path4497-5" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="251.53981" + id="text4429-8" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9" + x="111.75929" + y="251.53981">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="367.91556" + id="text4429-8-9" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4" + x="396.10254" + y="367.91556">rcu_read_lock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="597.40289" + id="text4429-8-9-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4" + x="396.10254" + y="597.40289">rcu_read_unlock();</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="111.75929" + y="453.15311" + id="text4429-8-9-3-1" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431-9-4-4-6" + x="111.75929" + y="453.15311">rcu_read_unlock();</tspan></text> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 33.941125,227.87568 436.284885,0 0,0.7071" + id="path4608" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="394.94427" + y="345.66351" + id="text4648" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650" + x="394.94427" + y="345.66351">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(36.441125,199.60612)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.11968" + y="475.77856" + id="text4648-4" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4" + x="112.11968" + y="475.77856">QS</tspan></text> + <path + sodipodi:type="arc" + style="fill:none;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-246.38346,329.72117)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <path + sodipodi:type="arc" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0" + id="path4652-7-7" + sodipodi:cx="358.85669" + sodipodi:cy="142.87541" + sodipodi:rx="10.960155" + sodipodi:ry="10.253048" + d="m 358.86939,132.62237 a 10.960155,10.253048 0 1 1 -0.0228,0" + transform="translate(-103.65246,202.90878)" + sodipodi:start="4.7135481" + sodipodi:end="10.994651" + sodipodi:open="true" /> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="254.85066" + y="348.96619" + id="text4648-4-3" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4650-4-5" + x="254.85066" + y="348.96619">QS</tspan></text> + </g> +</svg>
diff --git a/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg new file mode 100644 index 0000000..48cd162 --- /dev/null +++ b/Documentation/RCU/Design/Requirements/ReadersPartitionGP1.svg
@@ -0,0 +1,639 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="735.25" + height="516.21875" + id="svg2" + version="1.1" + inkscape:version="0.48.3.1 r9886" + sodipodi:docname="ReadersPartitionGP1.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible"> + <path + id="path3792" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart" + style="overflow:visible"> + <path + id="path3789" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lstart" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lstart-4" + style="overflow:visible"> + <path + id="path3789-9" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(1.1,0,0,1.1,1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend-4" + style="overflow:visible"> + <path + id="path3792-4" + style="fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.3670394" + inkscape:cx="367.26465" + inkscape:cy="258.46182" + inkscape:document-units="px" + inkscape:current-layer="g4433-6" + showgrid="false" + inkscape:window-width="1351" + inkscape:window-height="836" + inkscape:window-x="438" + inkscape:window-y="335" + inkscape:window-maximized="0" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-29.15625,-185.59375)"> + <flowRoot + xml:space="preserve" + id="flowRoot2985" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol"><flowRegion + id="flowRegion2987"><rect + id="rect2989" + width="82.85714" + height="11.428572" + x="240" + y="492.36218" /></flowRegion><flowPara + id="flowPara2991" /></flowRoot> <g + id="g4433" + transform="translate(2,-12)"> + <text + sodipodi:linespacing="125%" + id="text2993" + y="-261.66608" + x="436.12299" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + xml:space="preserve" + transform="matrix(0,1,-1,0,0,0)"><tspan + y="-261.66608" + x="436.12299" + id="tspan2995" + sodipodi:role="line">synchronize_rcu()</tspan></text> + <g + id="g4417" + transform="matrix(0,1,-1,0,730.90257,222.4928)"> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow2Lstart);marker-end:url(#Arrow2Lend)" + d="M 97.580736,477.4048 327.57913,476.09759" + id="path2997" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 96.752718,465.38398 0,22.62742" + id="path4397" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 328.40703,465.38397 0,22.62742" + id="path4397-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + </g> + </g> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="268.18076" + id="text4429" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4431" + x="112.04738" + y="268.18076">WRITE_ONCE(a, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.04738" + y="487.13766" + id="text4441" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4443" + x="112.04738" + y="487.13766">WRITE_ONCE(b, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.60869" + y="297.29346" + id="text4445" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4447" + x="255.60869" + y="297.29346">r1 = READ_ONCE(a);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="255.14423" + y="554.61786" + id="text4449" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4451" + x="255.14423" + y="554.61786">WRITE_ONCE(c, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="370.71124" + id="text4453" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4455" + x="396.10254" + y="370.71124">WRITE_ONCE(d, 1);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.10254" + y="572.13617" + id="text4457" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4459" + x="396.10254" + y="572.13617">r2 = READ_ONCE(c);</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="112.08231" + y="213.91006" + id="text4461" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463" + x="112.08231" + y="213.91006">thread0()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="252.34512" + y="213.91006" + id="text4461-6" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4463-0" + x="252.34512" + y="213.91006">thread1()</tspan></text> + <text + xml:space="preserve" + style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Symbol;-inkscape-font-specification:Symbol" + x="396.42557&
