android/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'mauro-exp/docbook3' into death-to-docbook

Browse Source 
Mauro says:

This patch series convert the remaining DocBooks to ReST.

The first version was originally
send as 3 patch series:

   [PATCH 00/36] Convert DocBook documents to ReST
   [PATCH 0/5] Convert more books to ReST
   [PATCH 00/13] Get rid of DocBook

The lsm book was added as if it were a text file under
Documentation. The plan is to merge it with another file
under Documentation/security, after both this series and
a security Documentation patch series gets merged.

It also adjusts some Sphinx-pedantic errors/warnings on
some kernel-doc markups.

I also added some patches here to add PDF output for all
existing ReST books.
This commit is contained in:
Jonathan Corbet 2017-05-18 11:03:08 -06:00
commit 6312811be2
124 changed files with 7469 additions and 10511 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Documentation/00-INDEX
View File

@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
- How to do DMA with ISA (and LPC) devices. - How to do DMA with ISA (and LPC) devices.
DMA-attributes.txt DMA-attributes.txt
- listing of the various possible attributes a DMA region can have - listing of the various possible attributes a DMA region can have
DocBook/
- directory with DocBook templates etc. for kernel documentation.
EDID/ EDID/
- directory with info on customizing EDID for broken gfx/displays. - directory with info on customizing EDID for broken gfx/displays.
IPMI.txt IPMI.txt
@ -40,8 +38,6 @@ Intel-IOMMU.txt
- basic info on the Intel IOMMU virtualization support. - basic info on the Intel IOMMU virtualization support.
Makefile Makefile
- It's not of interest for those who aren't touching the build system. - It's not of interest for those who aren't touching the build system.
Makefile.sphinx
- It's not of interest for those who aren't touching the build system.
PCI/ PCI/
- info related to PCI drivers. - info related to PCI drivers.
RCU/ RCU/
@ -264,6 +260,8 @@ logo.gif
- full colour GIF image of Linux logo (penguin - Tux). - full colour GIF image of Linux logo (penguin - Tux).
logo.txt logo.txt
- info on creator of above logo & site to get additional images from. - info on creator of above logo & site to get additional images from.
lsm.txt
- Linux Security Modules: General Security Hooks for Linux
lzo.txt lzo.txt
- kernel LZO decompressor input formats - kernel LZO decompressor input formats
m68k/ m68k/

17
Documentation/DocBook/.gitignore vendored
View File

@ -1,17 +0,0 @@
*.xml
*.ps
*.pdf
*.html
*.9.gz
*.9
*.aux
*.dvi
*.log
*.out
*.png
*.gif
*.svg
*.proc
*.db
media-indices.tmpl
media-entities.tmpl

282
Documentation/DocBook/Makefile
View File

@ -1,282 +0,0 @@
###
# 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 \
networking.xml \
filesystems.xml lsm.xml kgdb.xml \
libata.xml mtdnand.xml librs.xml rapidio.xml \
s390-drivers.xml scsi.xml \
sh.xml w1.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
# Default location for installed man pages
export INSTALL_MAN_PATH = $(objtree)/usr
installmandocs: mandocs
mkdir -p $(INSTALL_MAN_PATH)/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 $(INSTALL_MAN_PATH)/man/man9/
# no-op for the DocBook toolchain
epubdocs:
latexdocs:
linkcheckdocs:
###
#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/&/\\&amp;/g" \
-e "s/</\\&lt;/g" \
-e "s/>/\\&gt;/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 to INSTALL_MAN_PATH'; \
echo ' (default: $(INSTALL_MAN_PATH))'; \
echo ''
@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)) \
$(patsubst %.xml, .%.xml.cmd, $(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 so we can use it in if_changed and friends.
.PHONY: $(PHONY)

381
Documentation/DocBook/filesystems.tmpl
View File

@ -1,381 +0,0 @@
<?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>

1312
Documentation/DocBook/kernel-hacking.tmpl
View File

File diff suppressed because it is too large Load Diff

2151
Documentation/DocBook/kernel-locking.tmpl
View File

File diff suppressed because it is too large Load Diff

918
Documentation/DocBook/kgdb.tmpl
View File

@ -1,918 +0,0 @@
<?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_STRICT_KERNEL_RWX, 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_STRICT_KERNEL_RWX 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_STRICT_KERNEL_RWX 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_STRICT_KERNEL_RWX 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=&lt;tty-device&gt;,[baud]</constant></para></listitem>
<listitem>
<para>As a kernel loadable module:</para>
<para>Use the command: <constant>modprobe kgdboc kgdboc=&lt;tty-device&gt;,[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 &gt; /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
<listitem><para>Disable kgdboc</para>
<para><constant>echo "" &gt; /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=&lt;serial_device&gt;[,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,&lt;serial_device&gt;[,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 &gt; /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 &gt; /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 &gt; /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 &gt; /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 &gt; /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/&lt;driver&gt;/parameter/&lt;option&gt;</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 &gt; /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 &gt; /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 &lt;asm/kgdb.h&gt; 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>

1625
Documentation/DocBook/libata.tmpl
View File

File diff suppressed because it is too large Load Diff

289
Documentation/DocBook/librs.tmpl
View File

@ -1,289 +0,0 @@
<?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 &lt; 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>

265
Documentation/DocBook/lsm.tmpl
View File

@ -1,265 +0,0 @@
<?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>

1291
Documentation/DocBook/mtdnand.tmpl
View File

File diff suppressed because it is too large Load Diff

111
Documentation/DocBook/networking.tmpl
View File

@ -1,111 +0,0 @@
<?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>

155
Documentation/DocBook/rapidio.tmpl
View File

@ -1,155 +0,0 @@
<?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="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>

161
Documentation/DocBook/s390-drivers.tmpl
View File

@ -1,161 +0,0 @@
<?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>

409
Documentation/DocBook/scsi.tmpl
View File

@ -1,409 +0,0 @@
<?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&amp;m=115507374832500&amp;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>

105
Documentation/DocBook/sh.tmpl
View File

@ -1,105 +0,0 @@
<?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>

11
Documentation/DocBook/stylesheet.xsl
View File

@ -1,11 +0,0 @@
<?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>

101
Documentation/DocBook/w1.tmpl
View File

@ -1,101 +0,0 @@
<?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>

371
Documentation/DocBook/z8530book.tmpl
View File

@ -1,371 +0,0 @@
<?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 &amp;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-&gt; 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>

125
Documentation/Makefile
View File

@ -1 +1,126 @@
# -*- makefile -*-
# Makefile for Sphinx documentation
#
subdir-y := subdir-y :=
# 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
PDFLATEX = xelatex
LATEXOPTS = -interaction=batchmode
# 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 # HAVE_SPHINX
# User-friendly check for pdflatex
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/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)) || exit;
# $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 $2 && \
PYTHONDONTWRITEBYTECODE=1 \
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)))
linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
latexdocs:
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
ifeq ($(HAVE_PDFLATEX),0)
pdfdocs:
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_PDFLATEX
pdfdocs: latexdocs
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
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)))
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.
# no-ops for the Sphinx toolchain
sgmldocs:
@:
psdocs:
@:
mandocs:
@:
installmandocs:
@:
cleandocs:
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
dochelp:
@echo ' Linux kernel internal documentation in different formats from ReST:'
@echo ' htmldocs - HTML'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
@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.'

130
Documentation/Makefile.sphinx
View File

@ -1,130 +0,0 @@
# -*- 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
PDFLATEX = xelatex
LATEXOPTS = -interaction=batchmode
# 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 $(PDFLATEX) >/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)) || exit;
# $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 $2 && \
PYTHONDONTWRITEBYTECODE=1 \
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)))
linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
latexdocs:
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
ifeq ($(HAVE_PDFLATEX),0)
pdfdocs:
$(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
@echo " SKIP Sphinx $@ target."
else # HAVE_PDFLATEX
pdfdocs: latexdocs
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
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)))
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.
# no-ops for the Sphinx toolchain
sgmldocs:
@:
psdocs:
@:
mandocs:
@:
installmandocs:
@:
cleandocs:
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
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 ' linkcheckdocs - check for broken external links (will connect to external hosts)'
@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.'

2
Documentation/PCI/MSI-HOWTO.txt
View File

@ -186,7 +186,7 @@ must disable interrupts while the lock is held. If the device sends
a different interrupt, the driver will deadlock trying to recursively a different interrupt, the driver will deadlock trying to recursively
acquire the spinlock. Such deadlocks can be avoided by using acquire the spinlock. Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
and acquire the lock (see Documentation/DocBook/kernel-locking). and acquire the lock (see Documentation/kernel-hacking/locking.rst).
4.5 How to tell whether MSI/MSI-X is enabled on a device 4.5 How to tell whether MSI/MSI-X is enabled on a device

6
Documentation/admin-guide/README.rst
View File

@ -55,12 +55,6 @@ Documentation
contains information about the problems, which may result by upgrading contains information about the problems, which may result by upgrading
your kernel. your kernel.
- The Documentation/DocBook/ subdirectory contains several guides for
kernel developers and users. These guides can be rendered in a
number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others.
After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
or ``make mandocs`` will render the documentation in the requested format.
Installing the kernel source Installing the kernel source
---------------------------- ----------------------------

35
Documentation/conf.py
View File

@ -281,6 +281,7 @@ latex_elements = {
\\definecolor{NoteColor}{RGB}{204,255,255} \\definecolor{NoteColor}{RGB}{204,255,255}
\\definecolor{WarningColor}{RGB}{255,204,204} \\definecolor{WarningColor}{RGB}{255,204,204}
\\definecolor{AttentionColor}{RGB}{255,255,204} \\definecolor{AttentionColor}{RGB}{255,255,204}
\\definecolor{ImportantColor}{RGB}{192,255,204}
\\definecolor{OtherColor}{RGB}{204,204,204} \\definecolor{OtherColor}{RGB}{204,204,204}
\\newlength{\\mynoticelength} \\newlength{\\mynoticelength}
\\makeatletter\\newenvironment{coloredbox}[1]{% \\makeatletter\\newenvironment{coloredbox}[1]{%
@ -301,9 +302,14 @@ latex_elements = {
\\ifthenelse% \\ifthenelse%
{\\equal{\\py@noticetype}{attention}}% {\\equal{\\py@noticetype}{attention}}%
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}% {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
{%
\\ifthenelse%
{\\equal{\\py@noticetype}{important}}%
{\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
}% }%
}% }%
}%
}\\makeatother }\\makeatother
\\makeatletter \\makeatletter
@ -339,27 +345,42 @@ if major == 1 and minor > 3:
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).
# Sorted in alphabetical order
latex_documents = [ latex_documents = [
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
'The kernel development community', 'manual'),
('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation', ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('core-api/index', 'core-api.tex', 'The kernel core API manual', ('core-api/index', 'core-api.tex', 'The kernel core API manual',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
'The kernel development community', 'manual'),
('dev-tools/index', 'dev-tools.tex', 'Development tools for the Kernel',
'The kernel development community', 'manual'),
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
'The kernel development community', 'manual'),
('driver-api/index', 'driver-api.tex', 'The kernel driver API manual', ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('input/index', 'linux-input.tex', 'The Linux input driver subsystem', ('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
'The kernel development community', 'manual'),
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
'The kernel development community', 'manual'),
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
'The kernel development community', 'manual'),
('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To Hacking The Linux Kernel',
'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem Documentation', ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('networking/index', 'networking.tex', 'Linux Networking Documentation',
'The kernel development community', 'manual'),
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
'The kernel development community', 'manual'),
('security/index', 'security.tex', 'The kernel security subsystem manual', ('security/index', 'security.tex', 'The kernel security subsystem manual',
'The kernel development community', 'manual'), 'The kernel development community', 'manual'),
('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
'The kernel development community', 'manual'),
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
'The kernel development community', 'manual'),
('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
'The kernel development community', 'manual'),
] ]
# The name of an image file (relative to this directory) to place at the top of # The name of an image file (relative to this directory) to place at the top of

1
Documentation/core-api/index.rst
View File

@ -19,6 +19,7 @@ Core utilities
workqueue workqueue
genericirq genericirq
flexible-arrays flexible-arrays
librs
Interfaces for kernel debugging Interfaces for kernel debugging
=============================== ===============================

212
Documentation/core-api/librs.rst Normal file
View File

@ -0,0 +1,212 @@
==========================================
Reed-Solomon Library Programming Interface
==========================================
:Author: Thomas Gleixner
Introduction
============
The generic Reed-Solomon Library provides encoding, decoding and error
correction functions.
Reed-Solomon codes are used in communication and storage applications to
ensure data integrity.
This documentation is provided for developers who want to utilize the
functions provided by the library.
Known Bugs And Assumptions
==========================
None.
Usage
=====
This chapter provides examples of how to use the library.
Initializing
------------
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.
::
/* 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);
Encoding
--------
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.
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.
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.
::
/* 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);
Decoding
--------
The decoder calculates the syndrome over the given data length and the
received parity symbols and corrects errors in the data.
If a syndrome is available from a hardware decoder then the syndrome
calculation is skipped.
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.
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.
Decoding with syndrome calculation, direct data correction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
/* 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);
Decoding with syndrome given by hardware decoder, direct data correction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
/* 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);
Decoding with syndrome given by hardware decoder, no direct data correction.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: It's not necessary to give data and received parity to the
decoder.
::
/* 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]);
}
Cleanup
-------
The function free_rs frees the allocated resources, if the caller is
the last user of the decoder.
::
/* Release resources */
free_rs(rs_decoder);
Structures
==========
This chapter contains the autogenerated documentation of the structures
which are used in the Reed-Solomon Library and are relevant for a
developer.
.. kernel-doc:: include/linux/rslib.h
:internal:
Public Functions Provided
=========================
This chapter contains the autogenerated documentation of the
Reed-Solomon functions which are exported.
.. kernel-doc:: lib/reed_solomon/reed_solomon.c
:export:
Credits
=======
The library code for encoding and decoding was written by Phil Karn.
::
Copyright 2002, Phil Karn, KA9Q
May be used under the terms of the GNU General Public License (GPL)
The wrapper functions and interfaces are written by Thomas Gleixner.
Many users have provided bugfixes, improvements and helping hands for
testing. Thanks a lot.
The following people have contributed to this document:
Thomas Gleixner\ tglx@linutronix.de

10
Documentation/crypto/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = 'Linux Kernel Crypto API'
tags.add("subproject")
latex_documents = [
('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
'The kernel development community', 'manual'),
]

1
Documentation/dev-tools/index.rst
View File

@ -23,6 +23,7 @@ whole; patches welcome!
kmemleak kmemleak
kmemcheck kmemcheck
gdb-kernel-debugging gdb-kernel-debugging
kgdb
.. only:: subproject and html .. only:: subproject and html

907
Documentation/dev-tools/kgdb.rst Normal file
View File

@ -0,0 +1,907 @@
=================================================
Using kgdb, kdb and the kernel debugger internals
=================================================
:Author: Jason Wessel
Introduction
============
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.
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
``CONFIG_KALLSYMS``.
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.
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.
Compiling a kernel
==================
- In order to enable compilation of kdb, you must first enable kgdb.
- The kgdb test compile options are described in the kgdb test suite
chapter.
Kernel config options for kgdb
------------------------------
To enable ``CONFIG_KGDB`` you should look under
:menuselection:`Kernel hacking --> Kernel debugging` and select
:menuselection:`KGDB: kernel debugger`.
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 ``CONFIG_DEBUG_INFO`` which is called
:menuselection:`Compile the kernel with debug info` in the config menu.
It is advised, but not required, that you turn on the
``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`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.
If the architecture that you are using supports the kernel option
``CONFIG_STRICT_KERNEL_RWX``, 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_STRICT_KERNEL_RWX``
option turned on, else you need to turn off this option.
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.
Here is an example set of ``.config`` symbols to enable or disable for kgdb::
# CONFIG_STRICT_KERNEL_RWX is not set
CONFIG_FRAME_POINTER=y
CONFIG_KGDB=y
CONFIG_KGDB_SERIAL_CONSOLE=y
Kernel config options for kdb
-----------------------------
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.
The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
:menuselection:`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.
If you want to use a PS/2-style keyboard with kdb, you would select
``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`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.
Here is an example set of ``.config`` symbols to enable/disable kdb::
# CONFIG_STRICT_KERNEL_RWX is not set
CONFIG_FRAME_POINTER=y
CONFIG_KGDB=y
CONFIG_KGDB_SERIAL_CONSOLE=y
CONFIG_KGDB_KDB=y
CONFIG_KDB_KEYBOARD=y
Kernel Debugger Boot Arguments
==============================
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.
Kernel parameter: kgdboc
------------------------
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.
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
``kgdbwait`` and early debugging if you build kgdboc into the kernel as
a built-in.
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.
kgdboc arguments
~~~~~~~~~~~~~~~~
Usage::
kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
The order listed above must be observed if you use any of the optional
configurations together.
Abbreviations:
- kms = Kernel Mode Setting
- kbd = Keyboard
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.
Using loadable module or built-in
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. As a kernel built-in:
Use the kernel boot argument::
kgdboc=<tty-device>,[baud]
2. As a kernel loadable module:
Use the command::
modprobe kgdboc kgdboc=<tty-device>,[baud]
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.
1. ``kgdboc=ttyS0,115200``
2. ``kgdboc=ttyAMA1,115200``
Configure kgdboc at runtime with sysfs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
At run time you can enable or disable kgdboc by echoing a parameters
into the sysfs. Here are two examples:
1. Enable kgdboc on ttyS0::
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
2. Disable kgdboc::
echo "" > /sys/module/kgdboc/parameters/kgdboc
.. note::
You do not need to specify the baud if you are configuring the
console on tty which is already configured or open.
More examples
^^^^^^^^^^^^^
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.
1. kdb and kgdb over only a serial port::
kgdboc=<serial_device>[,baud]
Example::
kgdboc=ttyS0,115200
2. kdb and kgdb with keyboard and a serial port::
kgdboc=kbd,<serial_device>[,baud]
Example::
kgdboc=kbd,ttyS0,115200
3. kdb with a keyboard::
kgdboc=kbd
4. kdb with kernel mode setting::
kgdboc=kms,kbd
5. kdb with kernel mode setting and kgdb over a serial port::
kgdboc=kms,kbd,ttyS0,115200
.. note::
Kgdboc does not support interrupting the target via the gdb remote
protocol. You must manually send a :kbd:`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 :kbd:`SysRq-G`
for you.
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 :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
disconnect the terminal session and connect gdb. Your options if you
don't like this are to hack gdb to send the :kbd:`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.
Kernel parameter: ``kgdbwait``
------------------------------
The Kernel command line option ``kgdbwait`` 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.
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.
Kernel parameter: ``kgdbcon``
-----------------------------
The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
feature.
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.
1. Activate with the kernel command line option::
kgdbcon
2. Use sysfs before configuring an I/O driver::
echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
.. 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.
.. important::
You cannot use kgdboc + kgdbcon on a tty that is an
active system console. An example of incorrect usage is::
console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
It is possible to use this option with kgdboc on a tty that is not a
system console.
Run time parameter: ``kgdbreboot``
----------------------------------
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.
.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
.. flat-table::
:widths: 1 10 8
* - 1
- ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
- Ignore the reboot notification entirely.
* - 2
- ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
- Send the detach message to any attached debugger client.
* - 3
- ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
- Enter the debugger on reboot notify.
Using kdb
=========
Quick start for kdb on a serial port
------------------------------------
This is a quick example of how to use kdb.
1. Configure kgdboc at boot using kernel parameters::
console=ttyS0,115200 kgdboc=ttyS0,115200
OR
Configure kgdboc after the kernel has booted; assuming you are using
a serial port console::
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
2. 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 :kbd:`SysRq-G`, which means you must have
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
- When logged in as root or with a super user session you can run::
echo g > /proc/sysrq-trigger
- Example using minicom 2.2
Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
- When you have telneted to a terminal server that supports sending
a remote break
Press: :kbd:`CTRL-]`
Type in: ``send break``
Press: :kbd:`Enter` :kbd:`g`
3. From the kdb prompt you can run the ``help`` command to see a complete
list of the commands that are available.
Some useful commands in kdb include:
=========== =================================================================
``lsmod`` Shows where kernel modules are loaded
``ps`` Displays only the active processes
``ps A`` Shows all the processes
``summary`` Shows kernel version info and memory usage
``bt`` Get a backtrace of the current process using :c:func:`dump_stack`
``dmesg`` View the kernel syslog buffer
``go`` Continue the system
=========== =================================================================
4. 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.
Quick start for kdb using a keyboard connected console
------------------------------------------------------
This is a quick example of how to use kdb with a keyboard.
1. Configure kgdboc at boot using kernel parameters::
kgdboc=kbd
OR
Configure kgdboc after the kernel has booted::
echo kbd > /sys/module/kgdboc/parameters/kgdboc
2. 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 :kbd:`SysRq-G`, which means you must have
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
- When logged in as root or with a super user session you can run::
echo g > /proc/sysrq-trigger
- Example using a laptop keyboard:
Press and hold down: :kbd:`Alt`
Press and hold down: :kbd:`Fn`
Press and release the key with the label: :kbd:`SysRq`
Release: :kbd:`Fn`
Press and release: :kbd:`g`
Release: :kbd:`Alt`
- Example using a PS/2 101-key keyboard
Press and hold down: :kbd:`Alt`
Press and release the key with the label: :kbd:`SysRq`
Press and release: :kbd:`g`
Release: :kbd:`Alt`
3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
continue kernel execution.
Using kgdb / gdb
================
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.
All kgdb I/O drivers can be reconfigured at run time, if
``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
config string to ``/sys/module/<driver>/parameter/<option>``. 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 ``detach`` command prior to trying to unconfigure a
kgdb I/O driver.
Connecting with gdb to a serial port
------------------------------------
1. Configure kgdboc
Configure kgdboc at boot using kernel parameters::
kgdboc=ttyS0,115200
OR
Configure kgdboc after the kernel has booted::
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
2. Stop kernel execution (break into the debugger)
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 :kbd:`SysRq-G`, or running the
kernel until it takes an exception where it waits for the debugger to
attach.
- When logged in as root or with a super user session you can run::
echo g > /proc/sysrq-trigger
- Example using minicom 2.2
Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
- When you have telneted to a terminal server that supports sending
a remote break
Press: :kbd:`CTRL-]`
Type in: ``send break``
Press: :kbd:`Enter` :kbd:`g`
3. Connect from gdb
Example (using a directly connected port)::
% gdb ./vmlinux
(gdb) set remotebaud 115200
(gdb) target remote /dev/ttyS0
Example (kgdb to a terminal server on TCP port 2012)::
% gdb ./vmlinux
(gdb) target remote 192.168.2.2:2012
Once connected, you can debug a kernel the way you would debug an
application program.
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 ``target remote`` command by typing in::
set debug remote 1
Remember if you continue in gdb, and need to "break in" again, you need
to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
shell or script to break into the debugger.
kgdb and kdb interoperability
=============================
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.
Switching between kdb and kgdb
------------------------------
Switching from kgdb to kdb
~~~~~~~~~~~~~~~~~~~~~~~~~~
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 ``KGDB or $3#33 for KDB``. 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.
1. Change from kgdb to kdb by blindly typing::
$3#33
2. Change from kgdb to kdb with gdb::
maintenance packet 3
.. note::
Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
the command::
kill -9 %
Change from kdb to kgdb
~~~~~~~~~~~~~~~~~~~~~~~
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.
1. From kdb issue the command::
kgdb
Now disconnect your terminal program and connect gdb in its place
2. At the kdb prompt, disconnect the terminal program and connect gdb in
its place.
Running kdb commands from gdb
-----------------------------
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
``monitor help``.
Example::
(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)
kgdb Test Suite
===============
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.
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.
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.
Kernel Debugger Internals
=========================
Architecture Specifics
----------------------
The kernel debugger is organized into a number of components:
1. The debug core
The debug core is found in ``kernel/debugger/debug_core.c``. It
contains:
- A generic OS exception handler which includes sync'ing the
processors into a stopped state on an multi-CPU system.
- The API to talk to the kgdb I/O drivers
- The API to make calls to the arch-specific kgdb implementation
- The logic to perform safe memory reads and writes to memory while
using the debugger
- A full implementation for software breakpoints unless overridden
by the arch
- The API to invoke either the kdb or kgdb frontend to the debug
core.
- The structures and callback API for atomic kernel mode setting.
.. note:: kgdboc is where the kms callbacks are invoked.
2. kgdb arch-specific implementation
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:
- contains an arch-specific trap catcher which invokes
:c:func:`kgdb_handle_exception` to start kgdb about doing its work
- translation to and from gdb specific packet format to :c:type:`pt_regs`
- Registration and unregistration of architecture specific trap
hooks
- Any special exception handling and cleanup
- NMI exception handling and cleanup
- (optional) HW breakpoints
3. gdbstub frontend (aka kgdb)
The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
- All the logic to implement the gdb serial protocol
4. kdb frontend
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.
- A simple shell
- The kdb core command set
- A registration API to register additional kdb shell commands.
- A good example of a self-contained kdb module is the ``ftdump``
command for dumping the ftrace buffer. See:
``kernel/trace/trace_kdb.c``
- 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.
- The implementation for :c:func:`kdb_printf` which emits messages directly
to I/O drivers, bypassing the kernel log.
- SW / HW breakpoint management for the kdb shell
5. kgdb I/O driver
Each kgdb I/O driver has to provide an implementation for the
following:
- configuration via built-in or module
- dynamic configuration and kgdb hook registration calls
- read and write character interface
- A cleanup handler for unconfiguring from the kgdb core
- (optional) Early debug methodology
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.
If you are intent on adding kgdb architecture specific support for a new
architecture, the architecture should define ``HAVE_ARCH_KGDB`` 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.
There are a few flags which must be set on every architecture in their
``asm/kgdb.h`` file. These are:
- ``NUMREGBYTES``:
The size in bytes of all of the registers, so that we
can ensure they will all fit into a packet.
- ``BUFMAX``:
The size in bytes of the buffer GDB will read into. This must
be larger than NUMREGBYTES.
- ``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.
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.
.. kernel-doc:: include/linux/kgdb.h
:internal:
kgdboc internals
----------------
kgdboc and uarts
~~~~~~~~~~~~~~~~
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.
When using kgdboc with a UART, the UART driver must implement two
callbacks in the :c:type:`struct uart_ops <uart_ops>`.
Example from ``drivers/8250.c``::
#ifdef CONFIG_CONSOLE_POLL
.poll_get_char = serial8250_get_poll_char,
.poll_put_char = serial8250_put_poll_char,
#endif
Any implementation specifics around creating a polling driver use the
``#ifdef CONFIG_CONSOLE_POLL``, 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.
kgdboc and keyboards
~~~~~~~~~~~~~~~~~~~~~~~~
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.
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
:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
function which polls hardware for single character input.
kgdboc and kms
~~~~~~~~~~~~~~~~~~
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.
Every time the kernel debugger is entered it calls
:c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
in the virtual console layer. On resuming kernel execution, the kernel
debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
:c:func:`con_debug_leave`.
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::
static const struct drm_crtc_helper_funcs intel_helper_funcs = {
[...]
.mode_set_base_atomic = intel_pipe_set_base_atomic,
[...]
};
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``::
static struct fb_ops intelfb_ops = {
[...]
.fb_debug_enter = drm_fb_helper_debug_enter,
.fb_debug_leave = drm_fb_helper_debug_leave,
[...]
};
Credits
=======
The following people have contributed to this document:
1. Amit Kale <amitkale@linsyssoft.com>
2. Tom Rini <trini@kernel.crashing.org>
In March 2008 this document was completely rewritten by:
- Jason Wessel <jason.wessel@windriver.com>
In Jan 2010 this document was updated to include kdb.
- Jason Wessel <jason.wessel@windriver.com>

90
Documentation/doc-guide/docbook.rst
View File

@ -1,90 +0,0 @@
DocBook XML [DEPRECATED]
========================
.. attention::
This section describes the deprecated DocBook XML toolchain. Please do not
create new DocBook XML template files. Please consider converting existing
DocBook XML templates files to Sphinx/reStructuredText.
Converting DocBook to Sphinx
----------------------------
Over time, we expect all of the documents under ``Documentation/DocBook`` to be
converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,
which uses ``pandoc`` under the hood. For example::
$ cd Documentation/sphinx
$ ./tmplcvt ../DocBook/in.tmpl ../out.rst
Then edit the resulting rst files to fix any remaining issues, and add the
document in the ``toctree`` in ``Documentation/index.rst``.
Components of the kernel-doc system
-----------------------------------
Many places in the source tree have extractable documentation in the form of
block comments above functions. The components of this system are:
- ``scripts/kernel-doc``
This is a perl script that hunts for the block comments and can mark them up
directly into reStructuredText, DocBook, man, text, and HTML. (No, not
texinfo.)
- ``Documentation/DocBook/*.tmpl``
These are XML template files, which are normal XML files with special
place-holders for where the extracted documentation should go.
- ``scripts/docproc.c``
This is a program for converting XML template files into XML files. When a
file is referenced it is searched for symbols exported (EXPORT_SYMBOL), to be
able to distinguish between internal and external functions.
It invokes kernel-doc, giving it the list of functions that are to be
documented.
Additionally it is used to scan the XML template files to locate all the files
referenced herein. This is used to generate dependency information as used by
make.
- ``Makefile``
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used to build
DocBook XML files, PostScript files, PDF files, and html files in
Documentation/DocBook. The older target 'sgmldocs' is equivalent to 'xmldocs'.
- ``Documentation/DocBook/Makefile``
This is where C files are associated with SGML templates.
How to use kernel-doc comments in DocBook XML template files
------------------------------------------------------------
DocBook XML template files (\*.tmpl) are like normal XML files, except that they
can contain escape sequences where extracted documentation should be inserted.
``!E<filename>`` is replaced by the documentation, in ``<filename>``, for
functions that are exported using ``EXPORT_SYMBOL``: the function list is
collected from files listed in ``Documentation/DocBook/Makefile``.
``!I<filename>`` is replaced by the documentation for functions that are **not**
exported using ``EXPORT_SYMBOL``.
``!D<filename>`` is used to name additional files to search for functions
exported using ``EXPORT_SYMBOL``.
``!F<filename> <function [functions...]>`` is replaced by the documentation, in
``<filename>``, for the functions listed.
``!P<filename> <section title>`` is replaced by the contents of the ``DOC:``
section titled ``<section title>`` from ``<filename>``. Spaces are allowed in
``<section title>``; do not quote the ``<section title>``.
``!C<filename>`` is replaced by nothing, but makes the tools check that all DOC:
sections and documented functions, symbols, etc. are used. This makes sense to
use when you use ``!F`` or ``!P`` only and want to verify that all documentation
is included.

1
Documentation/doc-guide/index.rst
View File

@ -10,7 +10,6 @@ How to write kernel documentation
sphinx.rst sphinx.rst
kernel-doc.rst kernel-doc.rst
parse-headers.rst parse-headers.rst
docbook.rst
.. only:: subproject and html .. only:: subproject and html

10
Documentation/doc-guide/kernel-doc.rst
View File

@ -149,6 +149,16 @@ Domain`_ references.
``%CONST`` ``%CONST``
Name of a constant. (No cross-referencing, just formatting.) Name of a constant. (No cross-referencing, just formatting.)
````literal````
A literal block that should be handled as-is. The output will use a
``monospaced font``.
Useful if you need to use special characters that would otherwise have some
meaning either by kernel-doc script of by reStructuredText.
This is particularly useful if you need to use things like ``%ph`` inside
a function description.
``$ENVVAR`` ``$ENVVAR``
Name of an environment variable. (No cross-referencing, just formatting.) Name of an environment variable. (No cross-referencing, just formatting.)

5
Documentation/doc-guide/sphinx.rst
View File

@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The
kernel-doc comments have some special structure and formatting, but beyond that kernel-doc comments have some special structure and formatting, but beyond that
they are also treated as reStructuredText. they are also treated as reStructuredText.
There is also the deprecated DocBook toolchain to generate documentation from
DocBook XML template files under ``Documentation/DocBook``. The DocBook files
are to be converted to reStructuredText, and the toolchain is slated to be
removed.
Finally, there are thousands of plain text documentation files scattered around Finally, there are thousands of plain text documentation files scattered around
``Documentation``. Some of these will likely be converted to reStructuredText ``Documentation``. Some of these will likely be converted to reStructuredText
over time, but the bulk of them will remain in plain text. over time, but the bulk of them will remain in plain text.

6
Documentation/driver-api/index.rst
View File

@ -32,7 +32,13 @@ available subsections can be seen below.
i2c i2c
hsi hsi
edac edac
scsi
libata
mtdnand
miscellaneous miscellaneous
w1
rapidio
s390-drivers
vme vme
80211/index 80211/index
uio-howto uio-howto

1031
Documentation/driver-api/libata.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1007
Documentation/driver-api/mtdnand.rst Normal file
View File

File diff suppressed because it is too large Load Diff

107
Documentation/driver-api/rapidio.rst Normal file
View File

@ -0,0 +1,107 @@
=======================
RapidIO Subsystem Guide
=======================
:Author: Matt Porter
Introduction
============
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.
This documentation is provided for developers intending to support
RapidIO on new architectures, write new drivers, or to understand the
subsystem internals.
Known Bugs and Limitations
==========================
Bugs
----
None. ;)
Limitations
-----------
1. Access/management of RapidIO memory regions is not supported
2. Multiple host enumeration is not supported
RapidIO driver interface
========================
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.
Functions
---------
.. kernel-doc:: include/linux/rio_drv.h
:internal:
.. kernel-doc:: drivers/rapidio/rio-driver.c
:export:
.. kernel-doc:: drivers/rapidio/rio.c
:export:
Internals
=========
This chapter contains the autogenerated documentation of the RapidIO
subsystem.
Structures
----------
.. kernel-doc:: include/linux/rio.h
:internal:
Enumeration and Discovery
-------------------------
.. kernel-doc:: drivers/rapidio/rio-scan.c
:internal:
Driver functionality
--------------------
.. kernel-doc:: drivers/rapidio/rio.c
:internal:
.. kernel-doc:: drivers/rapidio/rio-access.c
:internal:
Device model support
--------------------
.. kernel-doc:: drivers/rapidio/rio-driver.c
:internal:
PPC32 support
-------------
.. kernel-doc:: arch/powerpc/sysdev/fsl_rio.c
:internal:
Credits
=======
The following people have contributed to the RapidIO subsystem directly
or indirectly:
1. Matt Porter\ mporter@kernel.crashing.org
2. Randy Vinson\ rvinson@mvista.com
3. Dan Malek\ dan@embeddedalley.com
The following people have contributed to this document:
1. Matt Porter\ mporter@kernel.crashing.org

111
Documentation/driver-api/s390-drivers.rst Normal file
View File

@ -0,0 +1,111 @@
===================================
Writing s390 channel device drivers
===================================
:Author: Cornelia Huck
Introduction
============
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.
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.
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.
Some additional information can also be found in the kernel source under
Documentation/s390/driver-model.txt.
The ccw bus
===========
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.
I/O functions for channel-attached devices
------------------------------------------
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.
.. kernel-doc:: arch/s390/include/asm/cio.h
:internal:
ccw devices
-----------
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.
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.
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
:internal:
.. kernel-doc:: drivers/s390/cio/device.c
:export:
.. kernel-doc:: drivers/s390/cio/device_ops.c
:export:
The channel-measurement facility
--------------------------------
The channel-measurement facility provides a means to collect measurement
data which is made available by the channel subsystem for each channel
attached device.
.. kernel-doc:: arch/s390/include/asm/cmb.h
:internal:
.. kernel-doc:: drivers/s390/cio/cmf.c
:export:
The ccwgroup bus
================
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.
ccw group devices
-----------------
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
:internal:
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
:export:
Generic interfaces
==================
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.
.. kernel-doc:: drivers/s390/cio/airq.c
:export:

344
Documentation/driver-api/scsi.rst Normal file
View File

@ -0,0 +1,344 @@
=====================
SCSI Interfaces Guide
=====================
:Author: James Bottomley
:Author: Rob Landley
Introduction
============
Protocol vs bus
---------------
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.
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.
The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ 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.
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,
`I20 <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
(`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
Design of the Linux SCSI subsystem
----------------------------------
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.
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.
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.
SCSI upper layer
================
The upper layer supports the user-kernel interface by providing device
nodes.
sd (SCSI Disk)
--------------
sd (sd_mod.o)
sr (SCSI CD-ROM)
----------------
sr (sr_mod.o)
st (SCSI Tape)
--------------
st (st.o)
sg (SCSI Generic)
-----------------
sg (sg.o)
ch (SCSI Media Changer)
-----------------------
ch (ch.c)
SCSI mid layer
==============
SCSI midlayer implementation
----------------------------
include/scsi/scsi_device.h
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/scsi/scsi_device.h
:internal:
drivers/scsi/scsi.c
~~~~~~~~~~~~~~~~~~~
Main file for the SCSI midlayer.
.. kernel-doc:: drivers/scsi/scsi.c
:export:
drivers/scsi/scsicam.c
~~~~~~~~~~~~~~~~~~~~~~
`SCSI Common Access
Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
functions, for use with HDIO_GETGEO, etc.
.. kernel-doc:: drivers/scsi/scsicam.c
:export:
drivers/scsi/scsi_error.c
~~~~~~~~~~~~~~~~~~~~~~~~~~
Common SCSI error/timeout handling routines.
.. kernel-doc:: drivers/scsi/scsi_error.c
:export:
drivers/scsi/scsi_devinfo.c
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
devices.
.. kernel-doc:: drivers/scsi/scsi_devinfo.c
:internal:
drivers/scsi/scsi_ioctl.c
~~~~~~~~~~~~~~~~~~~~~~~~~~
Handle ioctl() calls for SCSI devices.
.. kernel-doc:: drivers/scsi/scsi_ioctl.c
:export:
drivers/scsi/scsi_lib.c
~~~~~~~~~~~~~~~~~~~~~~~~
SCSI queuing library.
.. kernel-doc:: drivers/scsi/scsi_lib.c
:export:
drivers/scsi/scsi_lib_dma.c
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SCSI library functions depending on DMA (map and unmap scatter-gather
lists).
.. kernel-doc:: drivers/scsi/scsi_lib_dma.c
:export:
drivers/scsi/scsi_module.c
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_module.c contains legacy support for
old-style host templates. It should never be used by any new driver.
drivers/scsi/scsi_proc.c
~~~~~~~~~~~~~~~~~~~~~~~~~
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/\*
.. kernel-doc:: drivers/scsi/scsi_proc.c
:internal:
drivers/scsi/scsi_netlink.c
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Infrastructure to provide async events from transports to userspace via
netlink, using a single NETLINK_SCSITRANSPORT protocol for all
transports. See `the original patch
submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
more details.
.. kernel-doc:: drivers/scsi/scsi_netlink.c
:internal:
drivers/scsi/scsi_scan.c
~~~~~~~~~~~~~~~~~~~~~~~~~
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.
.. kernel-doc:: drivers/scsi/scsi_scan.c
:internal:
drivers/scsi/scsi_sysctl.c
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up the sysctl entry: "/dev/scsi/logging_level"
(DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
drivers/scsi/scsi_sysfs.c
~~~~~~~~~~~~~~~~~~~~~~~~~~
SCSI sysfs interface routines.
.. kernel-doc:: drivers/scsi/scsi_sysfs.c
:export:
drivers/scsi/hosts.c
~~~~~~~~~~~~~~~~~~~~
mid to lowlevel SCSI driver interface
.. kernel-doc:: drivers/scsi/hosts.c
:export:
drivers/scsi/constants.c
~~~~~~~~~~~~~~~~~~~~~~~~
mid to lowlevel SCSI driver interface
.. kernel-doc:: drivers/scsi/constants.c
:export:
Transport classes
-----------------
Transport classes are service libraries for drivers in the SCSI lower
layer, which expose transport attributes in sysfs.
Fibre Channel transport
~~~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_transport_fc.c defines transport attributes
for Fibre Channel.
.. kernel-doc:: drivers/scsi/scsi_transport_fc.c
:export:
iSCSI transport class
~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_transport_iscsi.c defines transport
attributes for the iSCSI class, which sends SCSI packets over TCP/IP
connections.
.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
:export:
Serial Attached SCSI (SAS) transport class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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.
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.
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.
.. kernel-doc:: drivers/scsi/scsi_transport_sas.c
:export:
SATA transport class
~~~~~~~~~~~~~~~~~~~~
The SATA transport is handled by libata, which has its own book of
documentation in this directory.
Parallel SCSI (SPI) transport class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_transport_spi.c defines transport
attributes for traditional (fast/wide/ultra) SCSI busses.
.. kernel-doc:: drivers/scsi/scsi_transport_spi.c
:export:
SCSI RDMA (SRP) transport class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_transport_srp.c defines transport
attributes for SCSI over Remote Direct Memory Access.
.. kernel-doc:: drivers/scsi/scsi_transport_srp.c
:export:
SCSI lower layer
================
Host Bus Adapter transport types
--------------------------------
Many modern device controllers use the SCSI command set as a protocol to
communicate with their devices through many different types of physical
connections.
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).
Debug transport
~~~~~~~~~~~~~~~
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.
To be more realistic, the simulated devices have the transport
attributes of SAS disks.
For documentation see http://sg.danny.cz/sg/sdebug26.html
todo
~~~~
Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports,
netlink...

70
Documentation/driver-api/w1.rst Normal file
View File

@ -0,0 +1,70 @@
======================
W1: Dallas' 1-wire bus
======================
:Author: David Fries
W1 API internal to the kernel
=============================
W1 API internal to the kernel
-----------------------------
drivers/w1/w1.h
~~~~~~~~~~~~~~~
W1 core functions.
.. kernel-doc:: drivers/w1/w1.h
:internal:
drivers/w1/w1.c
~~~~~~~~~~~~~~~
W1 core functions.
.. kernel-doc:: drivers/w1/w1.c
:internal:
drivers/w1/w1_family.h
~~~~~~~~~~~~~~~~~~~~~~~
Allows registering device family operations.
.. kernel-doc:: drivers/w1/w1_family.h
:internal:
drivers/w1/w1_family.c
~~~~~~~~~~~~~~~~~~~~~~~
Allows registering device family operations.
.. kernel-doc:: drivers/w1/w1_family.c
:export:
drivers/w1/w1_int.c
~~~~~~~~~~~~~~~~~~~~
W1 internal initialization for master devices.
.. kernel-doc:: drivers/w1/w1_int.c
:export:
drivers/w1/w1_netlink.h
~~~~~~~~~~~~~~~~~~~~~~~~
W1 external netlink API structures and commands.
.. kernel-doc:: drivers/w1/w1_netlink.h
:internal:
drivers/w1/w1_io.c
~~~~~~~~~~~~~~~~~~~
W1 input/output.
.. kernel-doc:: drivers/w1/w1_io.c
:export:
.. kernel-doc:: drivers/w1/w1_io.c
:internal:

4
Documentation/fb/api.txt
View File

@ -289,12 +289,12 @@ the FB_CAP_FOURCC bit in the fb_fix_screeninfo capabilities field.
FOURCC definitions are located in the linux/videodev2.h header. However, and FOURCC definitions are located in the linux/videodev2.h header. However, and
despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2 despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
and don't require usage of the V4L2 subsystem. FOURCC documentation is and don't require usage of the V4L2 subsystem. FOURCC documentation is
available in Documentation/DocBook/v4l/pixfmt.xml. available in Documentation/media/uapi/v4l/pixfmt.rst.
To select a format, applications set the grayscale field to the desired FOURCC. To select a format, applications set the grayscale field to the desired FOURCC.
For YUV formats, they should also select the appropriate colorspace by setting For YUV formats, they should also select the appropriate colorspace by setting
the colorspace field to one of the colorspaces listed in linux/videodev2.h and the colorspace field to one of the colorspaces listed in linux/videodev2.h and
documented in Documentation/DocBook/v4l/colorspaces.xml. documented in Documentation/media/uapi/v4l/colorspaces.rst.
The red, green, blue and transp fields are not used with the FOURCC-based API. The red, green, blue and transp fields are not used with the FOURCC-based API.
For forward compatibility reasons applications must zero those fields, and For forward compatibility reasons applications must zero those fields, and

10
Documentation/filesystems/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "Linux Filesystems API"
tags.add("subproject")
latex_documents = [
('index', 'filesystems.tex', project,
'The kernel development community', 'manual'),
]

317
Documentation/filesystems/index.rst Normal file
View File

@ -0,0 +1,317 @@
=====================
Linux Filesystems API
=====================
The Linux VFS
=============
The Filesystem types
--------------------
.. kernel-doc:: include/linux/fs.h
:internal:
The Directory Cache
-------------------
.. kernel-doc:: fs/dcache.c
:export:
.. kernel-doc:: include/linux/dcache.h
:internal:
Inode Handling
--------------
.. kernel-doc:: fs/inode.c
:export:
.. kernel-doc:: fs/bad_inode.c
:export:
Registration and Superblocks
----------------------------
.. kernel-doc:: fs/super.c
:export:
File Locks
----------
.. kernel-doc:: fs/locks.c
:export:
.. kernel-doc:: fs/locks.c
:internal:
Other Functions
---------------
.. kernel-doc:: fs/mpage.c
:export:
.. kernel-doc:: fs/namei.c
:export:
.. kernel-doc:: fs/buffer.c
:export:
.. kernel-doc:: block/bio.c
:export:
.. kernel-doc:: fs/seq_file.c
:export:
.. kernel-doc:: fs/filesystems.c
:export:
.. kernel-doc:: fs/fs-writeback.c
:export:
.. kernel-doc:: fs/block_dev.c
:export:
The proc filesystem
===================
sysctl interface
----------------
.. kernel-doc:: kernel/sysctl.c
:export:
proc filesystem interface
-------------------------
.. kernel-doc:: fs/proc/base.c
:internal:
Events based on file descriptors
================================
.. kernel-doc:: fs/eventfd.c
:export:
The Filesystem for Exporting Kernel Objects
===========================================
.. kernel-doc:: fs/sysfs/file.c
:export:
.. kernel-doc:: fs/sysfs/symlink.c
:export:
The debugfs filesystem
======================
debugfs interface
-----------------
.. kernel-doc:: fs/debugfs/inode.c
:export:
.. kernel-doc:: fs/debugfs/file.c
:export:
The Linux Journalling API
=========================
Overview
--------
Details
~~~~~~~
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 :c:func:`jbd2_journal_init_inode` call is for journals stored in
filesystem inodes, or the :c:func:`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 :c:func:`jbd2_journal_destroy` on it to free up
any used kernel memory.
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 :c:func:`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 :c:func:`jbd2_journal_wipe` to clear the journal contents before
calling :c:func:`jbd2_journal_load`.
Note that jbd2_journal_wipe(..,0) calls
:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
transactions in the journal and similarly :c:func:`jbd2_journal_load` will
call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
Now you can go ahead and start modifying the underlying filesystem.
Almost.
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 :c:func:`jbd2_journal_start` which returns a transaction handle.
:c:func:`jbd2_journal_start` and its counterpart :c:func:`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
:c:func:`jbd2_journal_stop` the same number of times as
:c:func:`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.
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 :c:func:`jbd2_journal_get_create_access()` /
:c:func:`jbd2_journal_get_write_access()` /
:c:func:`jbd2_journal_get_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
:c:func:`jbd2_journal_dirty_metadata`. 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 :c:func:`jbd2_journal_forget` in much the same way as you
might have used :c:func:`bforget` in the past.
A :c:func:`jbd2_journal_flush` may be called at any time to commit and
checkpoint all your transactions.
Then at umount time , in your :c:func:`put_super` you can then call
:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
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 :c:func:`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.
The second case to bear in mind is that :c:func:`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 :c:func:`jbd2_journal_stop`. So to avoid
deadlocks you must treat :c:func:`jbd2_journal_start` /
:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
your semaphore ordering rules to prevent
deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
easily as on :c:func:`jbd2_journal_start`.
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.
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.
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.
JBD2 also provides a way to block all transaction updates via
:c:func:`jbd2_journal_lock_updates()` /
:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
window with a clean and stable fs for a moment. E.g.
::
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.
The opportunities for abuse and DOS attacks with this should be obvious,
if you allow unprivileged userspace to trigger codepaths containing
these calls.
Summary
~~~~~~~
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.
Data Types
----------
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'.
Structures
~~~~~~~~~~
.. kernel-doc:: include/linux/jbd2.h
:internal:
Functions
---------
The functions here are split into two groups those that affect a journal
as a whole, and those which are used to manage transactions
Journal Level
~~~~~~~~~~~~~
.. kernel-doc:: fs/jbd2/journal.c
:export:
.. kernel-doc:: fs/jbd2/recovery.c
:internal:
Transasction Level
~~~~~~~~~~~~~~~~~~
.. kernel-doc:: fs/jbd2/transaction.c
See also
--------
`Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
`Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
splice API
==========
splice is a method for moving blocks of data around inside the kernel,
without continually transferring them between the kernel and user space.
.. kernel-doc:: fs/splice.c
pipes API
=========
Pipe interfaces are all for in-kernel (builtin image) use. They are not
exported for use by modules.
.. kernel-doc:: include/linux/pipe_fs_i.h
:internal:
.. kernel-doc:: fs/pipe.c

2
Documentation/gpu/todo.rst
View File

@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The
task would be to clean up interfaces like moving functions around between task would be to clean up interfaces like moving functions around between
files to better group them and improving the interfaces like dropping return files to better group them and improving the interfaces like dropping return
values for functions that never fail. Then write kerneldoc for all exported values for functions that never fail. Then write kerneldoc for all exported
functions and an overview section and integrate it all into the drm DocBook. functions and an overview section and integrate it all into the drm book.
See https://dri.freedesktop.org/docs/drm/ for what's there already. See https://dri.freedesktop.org/docs/drm/ for what's there already.

14
Documentation/index.rst
View File

@ -51,6 +51,7 @@ merged much easier.
process/index process/index
dev-tools/index dev-tools/index
doc-guide/index doc-guide/index
kernel-hacking/index
Kernel API documentation Kernel API documentation
------------------------ ------------------------
@ -67,11 +68,24 @@ needed).
driver-api/index driver-api/index
core-api/index core-api/index
media/index media/index
networking/index
input/index input/index
gpu/index gpu/index
security/index security/index
sound/index sound/index
crypto/index crypto/index
filesystems/index
Architecture-specific documentation
-----------------------------------
These books provide programming details about architecture-specific
implementation.
.. toctree::
:maxdepth: 2
sh/index
Korean translations Korean translations
------------------- -------------------

65
Documentation/kernel-doc-nano-HOWTO.txt
View File

@ -17,8 +17,8 @@ The format for this documentation is called the kernel-doc format.
It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file. It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
This style embeds the documentation within the source files, using This style embeds the documentation within the source files, using
a few simple conventions. The scripts/kernel-doc perl script, some a few simple conventions. The scripts/kernel-doc perl script, the
SGML templates in Documentation/DocBook, and other tools understand Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
these conventions, and are used to extract this embedded documentation these conventions, and are used to extract this embedded documentation
into various documents. into various documents.
@ -122,15 +122,9 @@ are:
- scripts/kernel-doc - scripts/kernel-doc
This is a perl script that hunts for the block comments and can mark This is a perl script that hunts for the block comments and can mark
them up directly into DocBook, man, text, and HTML. (No, not them up directly into DocBook, ReST, man, text, and HTML. (No, not
texinfo.) texinfo.)
- Documentation/DocBook/*.tmpl
These are SGML template files, which are normal SGML files with
special place-holders for where the extracted documentation should
go.
- scripts/docproc.c - scripts/docproc.c
This is a program for converting SGML template files into SGML This is a program for converting SGML template files into SGML
@ -145,25 +139,18 @@ are:
- Makefile - Makefile
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
to build XML DocBook files, PostScript files, PDF files, and html files are used to build XML DocBook files, LaTeX files, PDF files,
in Documentation/DocBook. The older target 'sgmldocs' is equivalent ePub files and html files in Documentation/.
to 'xmldocs'.
- Documentation/DocBook/Makefile
This is where C files are associated with SGML templates.
How to extract the documentation How to extract the documentation
-------------------------------- --------------------------------
If you just want to read the ready-made books on the various If you just want to read the ready-made books on the various
subsystems (see Documentation/DocBook/*.tmpl), just type 'make subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your depending on your preference. If you would rather read a different format,
preference. If you would rather read a different format, you can type you can type 'make xmldocs' and then use DocBook tools to convert
'make xmldocs' and then use DocBook tools to convert Documentation/output/*.xml to a format of your choice (for example,
Documentation/DocBook/*.xml to a format of your choice (for example,
'db2html ...' if 'make htmldocs' was not defined). 'db2html ...' if 'make htmldocs' was not defined).
If you want to see man pages instead, you can do this: If you want to see man pages instead, you can do this:
@ -329,37 +316,7 @@ This is done by using a DOC: section keyword with a section title. E.g.:
* hardware, software, or its subject(s). * hardware, software, or its subject(s).
*/ */
DOC: sections are used in SGML templates files as indicated below. DOC: sections are used in ReST files.
How to make new SGML template files
-----------------------------------
SGML template files (*.tmpl) are like normal SGML files, except that
they can contain escape sequences where extracted documentation should
be inserted.
!E<filename> is replaced by the documentation, in <filename>, for
functions that are exported using EXPORT_SYMBOL: the function list is
collected from files listed in Documentation/DocBook/Makefile.
!I<filename> is replaced by the documentation for functions that are
_not_ exported using EXPORT_SYMBOL.
!D<filename> is used to name additional files to search for functions
exported using EXPORT_SYMBOL.
!F<filename> <function [functions...]> is replaced by the
documentation, in <filename>, for the functions listed.
!P<filename> <section title> is replaced by the contents of the DOC:
section titled <section title> from <filename>.
Spaces are allowed in <section title>; do not quote the <section title>.
!C<filename> is replaced by nothing, but makes the tools check that
all DOC: sections and documented functions, symbols, etc. are used.
This makes sense to use when you use !F/!P only and want to verify
that all documentation is included.
Tim. Tim.
*/ <twaugh@redhat.com> */ <twaugh@redhat.com>

10
Documentation/kernel-hacking/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "Kernel Hacking Guides"
tags.add("subproject")
latex_documents = [
('index', 'kernel-hacking.tex', project,
'The kernel development community', 'manual'),
]

811
Documentation/kernel-hacking/hacking.rst Normal file
View File

@ -0,0 +1,811 @@
============================================
Unreliable Guide To Hacking The Linux Kernel
============================================
:Author: Rusty Russell
Introduction
============
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.
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.
The Players
===========
At any time each of the CPUs in a system can be:
- not associated with any process, serving a hardware interrupt;
- not associated with any process, serving a softirq or tasklet;
- running in kernel space, associated with a process (user context);
- running a process in user space.
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.
We'll see a number of ways that the user context can block interrupts,
to become truly non-preemptable.
User Context
------------
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 :c:func:`schedule()`.
.. note::
You are always in user context on module load and unload, and on
operations on the block device layer.
In user context, the ``current`` pointer (indicating the task we are
currently executing) is valid, and :c:func:`in_interrupt()`
(``include/linux/preempt.h``) is false.
.. warning::
Beware that if you have preemption or softirqs disabled (see below),
:c:func:`in_interrupt()` will return a false positive.
Hardware Interrupts (Hard IRQs)
-------------------------------
Timer ticks, network cards and keyboard 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.
You can tell you are in a hardware interrupt, because
:c:func:`in_irq()` returns true.
.. warning::
Beware that this will return a false positive if interrupts are
disabled (see below).
Software Interrupt Context: Softirqs and Tasklets
-------------------------------------------------
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 (``kernel/softirq.c``).
Much of the real interrupt handling work is done here. Early in the
transition to SMP, 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'.
``include/linux/interrupt.h`` lists the different softirqs. A very
important softirq is the timer softirq (``include/linux/timer.h``): you
can register to have it call functions for you in a given length of
time.
Softirqs are often a pain to deal with, since the same softirq will run
simultaneously on more than one CPU. For this reason, tasklets
(``include/linux/interrupt.h``) 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.
.. warning::
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.
You can tell you are in a softirq (or tasklet) using the
:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
.. warning::
Beware that this will return a false positive if a
:ref:`botton half lock <local_bh_disable>` is held.
Some Basic Rules
================
No memory protection
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?
No floating point or MMX
The FPU context is not saved; even in user context the FPU state
probably won't correspond with the current process: you would mess
with some user process' FPU state. If you really want to do this,
you would have to explicitly save/restore the full FPU state (and
avoid context switches). It is generally a bad idea; use fixed point
arithmetic first.
A rigid stack limit
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).
The Linux kernel is portable
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.
ioctls: Not writing a new system call
=====================================
A system call generally looks like this::
asmlinkage long sys_mycall(int arg)
{
return 0;
}
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 ``include/asm/unistd.h`` and
``arch/kernel/entry.S`` file, and is much more likely to be accepted by
Linus.
If all your routine does is read or write some parameter, consider
implementing a :c:func:`sysfs()` interface instead.
Inside the ioctl you're in user context to a process. When a error
occurs you return a negated errno (see
``include/uapi/asm-generic/errno-base.h``,
``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
otherwise you return 0.
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
``-ERESTARTSYS`` 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.
::
if (signal_pending(current))
return -ERESTARTSYS;
If you're doing longer computations: first think userspace. If you
**really** 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::
cond_resched(); /* Will sleep */
A short note on interface design: the UNIX system call motto is "Provide
mechanism not policy".
Recipes for Deadlock
====================
You cannot call any routines which may sleep, unless:
- You are in user context.
- You do not own any spinlocks.
- 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).
Note that some functions may sleep implicitly: common ones are the user
space access functions (\*_user) and memory allocation functions
without ``GFP_ATOMIC``.
You should always compile your kernel ``CONFIG_DEBUG_ATOMIC_SLEEP`` on,
and it will warn you if you break these rules. If you **do** break the
rules, you will eventually lock up your box.
Really.
Common Routines
===============
:c:func:`printk()`
------------------
Defined in ``include/linux/printk.h``
:c:func:`printk()` 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::
printk(KERN_INFO "i = %u\n", i);
See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
interpreted by syslog as the level. Special case: for printing an IP
address use::
__be32 ipaddress;
printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
:c:func:`printk()` internally uses a 1K buffer and does not catch
overruns. Make sure that will be enough.
.. note::
You will know when you are a real kernel hacker when you start
typoing printf as printk in your user programs :)
.. note::
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.
:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
---------------------------------------------------------------------------------------------------
Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
**[SLEEPS]**
:c:func:`put_user()` and :c:func:`get_user()` 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 ``-EFAULT`` or
0.
:c:func:`copy_to_user()` and :c:func:`copy_from_user()` are
more general: they copy an arbitrary amount of data to and from
userspace.
.. warning::
Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
return the amount of uncopied data (ie. 0 still means success).
[Yes, this moronic interface makes me cringe. The flamewar comes up
every year or so. --RR.]
The functions may sleep implicitly. This should never be called outside
user context (it makes no sense), with interrupts disabled, or a
spinlock held.
:c:func:`kmalloc()`/:c:func:`kfree()`
-------------------------------------
Defined in ``include/linux/slab.h``
**[MAY SLEEP: SEE BELOW]**
These routines are used to dynamically request pointer-aligned chunks of
memory, like malloc and free do in userspace, but
:c:func:`kmalloc()` takes an extra flag word. Important values:
``GFP_KERNEL``
May sleep and swap to free memory. Only allowed in user context, but
is the most reliable way to allocate memory.
``GFP_ATOMIC``
Don't sleep. Less reliable than ``GFP_KERNEL``, but may be called
from interrupt context. You should **really** have a good
out-of-memory error-handling strategy.
``GFP_DMA``
Allocate ISA DMA lower than 16MB. If you don't know what that is you
don't need it. Very unreliable.
If you see a sleeping function called from invalid context warning
message, then maybe you called a sleeping allocation function from
interrupt context without ``GFP_ATOMIC``. You should really fix that.
Run, don't walk.
If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
(``include/linux/gfp.h``). 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.
If you are allocating more than a page worth of bytes you can use
:c:func:`vmalloc()`. It'll allocate virtual memory in the kernel
map. This block is not contiguous in physical memory, but the MMU 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 :c:func:`alloc_bootmem()`
routine.
Before inventing your own cache of often-used objects consider using a
slab cache in ``include/linux/slab.h``
:c:func:`current()`
-------------------
Defined in ``include/asm/current.h``
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 **not NULL** in interrupt context.
:c:func:`mdelay()`/:c:func:`udelay()`
-------------------------------------
Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
used for small pauses. Do not use large values with them as you risk
overflow - the helper function :c:func:`mdelay()` is useful here, or
consider :c:func:`msleep()`.
:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
-----------------------------------------------------------------------------------------------
Defined in ``include/asm/byteorder.h``
The :c:func:`cpu_to_be32()` 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:
:c:func:`be32_to_cpu()`, etc.
There are two major variations of these functions: the pointer
variation, such as :c:func:`cpu_to_be32p()`, which take a pointer
to the given type, and return the converted value. The other variation
is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
convert value referred to by the pointer, and return void.
:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
--------------------------------------------------------
Defined in ``include/linux/irqflags.h``
These routines disable hard interrupts on the local CPU, and restore
them. They are reentrant; saving the previous state in their one
``unsigned long flags`` argument. If you know that interrupts are
enabled, you can simply use :c:func:`local_irq_disable()` and
:c:func:`local_irq_enable()`.
.. _local_bh_disable:
:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
--------------------------------------------------------
Defined in ``include/linux/bottom_half.h``
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.
:c:func:`smp_processor_id()`
----------------------------
Defined in ``include/linux/smp.h``
:c:func:`get_cpu()` disables preemption (so you won't suddenly get
moved to another CPU) and returns the current processor number, between
0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily
continuous. You return it again with :c:func:`put_cpu()` when you
are done.
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().
``__init``/``__exit``/``__initdata``
------------------------------------
Defined in ``include/linux/init.h``
After boot, the kernel frees up a special section; functions marked with
``__init`` and data structures marked with ``__initdata`` are dropped
after boot is complete: similarly modules discard this memory after
initialization. ``__exit`` 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 ``__init`` to be exported to modules
with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
will break.
:c:func:`__initcall()`/:c:func:`module_init()`
----------------------------------------------
Defined in ``include/linux/init.h`` / ``include/linux/module.h``
Many parts of the kernel are well served as a module
(dynamically-loadable parts of the kernel). Using the
:c:func:`module_init()` and :c:func:`module_exit()` macros it
is easy to write code without #ifdefs which can operate both as a module
or built into the kernel.
The :c:func:`module_init()` 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
:c:func:`module_init()` macro becomes equivalent to
:c:func:`__initcall()`, which through linker magic ensures that
the function is called on boot.
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.
:c:func:`module_exit()`
-----------------------
Defined in ``include/linux/module.h``
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.
Note that this macro is optional: if it is not present, your module will
not be removable (except for 'rmmod -f').
:c:func:`try_module_get()`/:c:func:`module_put()`
-------------------------------------------------
Defined in ``include/linux/module.h``
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
:c:func:`try_module_get()` 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
:c:func:`module_put()` when you're finished.
Most registerable structures have an owner field, such as in the
:c:type:`struct file_operations <file_operations>` structure.
Set this field to the macro ``THIS_MODULE``.
Wait Queues ``include/linux/wait.h``
====================================
**[SLEEPS]**
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 :c:type:`wait_queue_head_t`, and then processes
which want to wait for that condition declare a :c:type:`wait_queue_t`
referring to themselves, and place that in the queue.
Declaring
---------
You declare a ``wait_queue_head_t`` using the
:c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the
:c:func:`init_waitqueue_head()` routine in your initialization
code.
Queuing
-------
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: :c:func:`wait_event_interruptible()`
(``include/linux/wait.h``) The first argument is the wait queue head, and
the second is an expression which is evaluated; the macro returns 0 when
this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
:c:func:`wait_event()` version ignores signals.
Waking Up Queued Tasks
----------------------
Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake
up every process in the queue. The exception is if one has
``TASK_EXCLUSIVE`` 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.
Atomic Operations
=================
Certain operations are guaranteed atomic on all platforms. The first
class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
this contains a signed integer (at least 32 bits long), and you must use
these functions to manipulate or read :c:type:`atomic_t` variables.
:c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
:c:func:`atomic_dec_and_test()` (returns true if it was
decremented to zero).
Yes. It returns true (i.e. != 0) if the atomic variable is zero.
Note that these functions are slower than normal arithmetic, and so
should not be used unnecessarily.
The second class of atomic operations is atomic bit operations on an
``unsigned long``, defined in ``include/linux/bitops.h``. These
operations generally take a pointer to the bit pattern, and a bit
number: 0 is the least significant bit. :c:func:`set_bit()`,
:c:func:`clear_bit()` and :c:func:`change_bit()` set, clear,
and flip the given bit. :c:func:`test_and_set_bit()`,
:c:func:`test_and_clear_bit()` and
:c:func:`test_and_change_bit()` do the same thing, except return
true if the bit was previously set; these are particularly useful for
atomically setting flags.
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.
Symbols
=======
Within the kernel proper, the normal linking rules apply (ie. unless a
symbol is declared to be file scope with the ``static`` 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.
:c:func:`EXPORT_SYMBOL()`
-------------------------
Defined in ``include/linux/export.h``
This is the classic method of exporting a symbol: dynamically loaded
modules will be able to use the symbol as normal.
:c:func:`EXPORT_SYMBOL_GPL()`
-----------------------------
Defined in ``include/linux/export.h``
Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
modules with a :c:func:`MODULE_LICENSE()` 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.
Routines and Conventions
========================
Double-linked lists ``include/linux/list.h``
--------------------------------------------
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.
In particular, :c:func:`list_for_each_entry()` is useful.
Return Conventions
------------------
For code called in user context, it's very common to defy C convention,
and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
failure. This can be unintuitive at first, but it's fairly widespread in
the kernel.
Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
negative error number into a pointer, and :c:func:`IS_ERR()` and
:c:func:`PTR_ERR()` to get it back out again: avoids a separate
pointer parameter for the error number. Icky, but in a good way.
Breaking Compilation
--------------------
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 **worse**.
Initializing structure members
------------------------------
The preferred method of initializing structures is to use designated
initialisers, as defined by ISO C99, eg::
static struct block_device_operations opt_fops = {
.open = opt_open,
.release = opt_release,
.ioctl = opt_ioctl,
.check_media_change = opt_media_change,
};
This makes it easy to grep for, and makes it clear which structure
fields are set. You should do this because it looks cool.
GNU Extensions
--------------
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).
- Inline functions
- Statement expressions (ie. the ({ and }) constructs).
- Declaring attributes of a function / variable / type
(__attribute__)
- typeof
- Zero length arrays
- Macro varargs
- Arithmetic on void pointers
- Non-Constant initializers
- Assembler Instructions (not outside arch/ and include/asm/)
- Function names as strings (__func__).
- __builtin_constant_p()
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.
C++
---
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.
NUMif
-----
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.
Putting Your Stuff in the Kernel
================================
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:
- Figure out whose pond you've been pissing in. Look at the top of the
source files, inside the ``MAINTAINERS`` file, and last of all in the
``CREDITS`` file. You should coordinate with this person to make sure
you're not duplicating effort, or trying something that's already
been rejected.
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 **they** want to make a change.
- Usually you want a configuration option for your kernel hack. Edit
``Kconfig`` in the appropriate directory. The Config language is
simple to use by cut and paste, and there's complete documentation in
``Documentation/kbuild/kconfig-language.txt``.
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. **Definitely** end your
description with “if in doubt, say N” (or, occasionally, \`Y'); this
is for people who have no idea what you are talking about.
- Edit the ``Makefile``: the CONFIG variables are exported here so you
can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
is documented in ``Documentation/kbuild/makefiles.txt``.
- Put yourself in ``CREDITS`` if you've done something noteworthy,
usually beyond a single file (your name should be at the top of the
source files anyway). ``MAINTAINERS`` 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.
- Finally, don't forget to read
``Documentation/process/submitting-patches.rst`` and possibly
``Documentation/process/submitting-drivers.rst``.
Kernel Cantrips
===============
Some favorites from browsing the source. Feel free to add to this list.
``arch/x86/include/asm/delay.h``::
#define ndelay(n) (__builtin_constant_p(n) ? \
((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
__ndelay(n))
``include/linux/fs.h``::
/*
* 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))
``arch/x86/include/asm/uaccess_32.h:``::
#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)))
``arch/sparc/kernel/head.S:``::
/*
* 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"
``arch/sparc/lib/checksum.S:``::
/* 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.
*/
Thanks
======
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 :c:func:`disable_irq()`, and Jes
Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain
for checking and adding to the Configure section. Telsa Gwynne for
teaching me DocBook.

9
Documentation/kernel-hacking/index.rst Normal file
View File

@ -0,0 +1,9 @@
=====================
Kernel Hacking Guides
=====================
.. toctree::
:maxdepth: 2
hacking
locking

1446
Documentation/kernel-hacking/locking.rst Normal file
View File

File diff suppressed because it is too large Load Diff

201
Documentation/lsm.txt Normal file
View File

@ -0,0 +1,201 @@
========================================================
Linux Security Modules: General Security Hooks for Linux
========================================================
:Author: Stephen Smalley
:Author: Timothy Fraser
:Author: Chris Vance
.. note::
The APIs described in this book are outdated.
Introduction
============
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.
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.
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.
LSM Framework
=============
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
`LSM Capabilities Module <#cap>`__.
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 :c:func:`security()` system call to support new system calls
for security-aware applications.
The LSM security fields are simply ``void*`` pointers. For process and
program execution security information, security fields were added to
:c:type:`struct task_struct <task_struct>` and
:c:type:`struct linux_binprm <linux_binprm>`. For filesystem
security information, a security field was added to :c:type:`struct
super_block <super_block>`. For pipe, file, and socket security
information, security fields were added to :c:type:`struct inode
<inode>` and :c:type:`struct file <file>`. For packet and
network device security information, security fields were added to
:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct
net_device <net_device>`. For System V IPC security information,
security fields were added to :c:type:`struct kern_ipc_perm
<kern_ipc_perm>` and :c:type:`struct msg_msg
<msg_msg>`; additionally, the definitions for :c:type:`struct
msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel
were moved to header files (``include/linux/msg.h`` and
``include/linux/shm.h`` as appropriate) to allow the security modules to
use these definitions.
Each LSM hook is a function pointer in a global table, security_ops.
This table is a :c:type:`struct security_operations
<security_operations>` structure as defined by
``include/linux/security.h``. 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->".
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.
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 :c:func:`register_security()` function (in
``security/security.c``) is provided to allow a security module to set
security_ops to refer to its own hook functions, and an
:c:func:`unregister_security()` 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.
LSM also provides a simple mechanism for stacking additional security
modules with the primary security module. It defines
:c:func:`register_security()` and
:c:func:`unregister_security()` hooks in the :c:type:`struct
security_operations <security_operations>` structure and
provides :c:func:`mod_reg_security()` and
:c:func:`mod_unreg_security()` 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.
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 :c:func:`alloc_security()` and
:c:func:`free_security()` 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 :c:func:`post_lookup()` hook in
:c:type:`struct inode_security_ops <inode_security_ops>`.
This hook is used to set security information for inodes after
successful lookup operations. An example of the second category of hooks
is the :c:func:`permission()` hook in :c:type:`struct
inode_security_ops <inode_security_ops>`. This hook checks
permission when accessing an inode.
LSM Capabilities Module
=======================
The LSM kernel patch moves most of the existing POSIX.1e capabilities
logic into an optional security module stored in the file
``security/capability.c``. 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.
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.
At present, the capabilities logic for computing process capabilities on
:c:func:`execve()` and :c:func:`set\*uid()`, checking
capabilities for a particular process, saving and checking capabilities
for netlink messages, and handling the :c:func:`capget()` and
:c:func:`capset()` 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:
- ``fs/open.c``::c:func:`sys_access()`
- ``fs/lockd/host.c``::c:func:`nlm_bind_host()`
- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()`
- ``fs/proc/array.c``::c:func:`task_cap()`

10
Documentation/networking/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "Linux Networking Documentation"
tags.add("subproject")
latex_documents = [
('index', 'networking.tex', project,
'The kernel development community', 'manual'),
]

18
Documentation/networking/index.rst Normal file
View File

@ -0,0 +1,18 @@
Linux Networking Documentation
==============================
Contents:
.. toctree::
:maxdepth: 2
kapi
z8530book
.. only:: subproject
Indices
=======
* :ref:`genindex`

147
Documentation/networking/kapi.rst Normal file
View File

@ -0,0 +1,147 @@
=========================================
Linux Networking and Network Devices APIs
=========================================
Linux Networking
================
Networking Base Types
---------------------
.. kernel-doc:: include/linux/net.h
:internal:
Socket Buffer Functions
-----------------------
.. kernel-doc:: include/linux/skbuff.h
:internal:
.. kernel-doc:: include/net/sock.h
:internal:
.. kernel-doc:: net/socket.c
:export:
.. kernel-doc:: net/core/skbuff.c
:export:
.. kernel-doc:: net/core/sock.c
:export:
.. kernel-doc:: net/core/datagram.c
:export:
.. kernel-doc:: net/core/stream.c
:export:
Socket Filter
-------------
.. kernel-doc:: net/core/filter.c
:export:
Generic Network Statistics
--------------------------
.. kernel-doc:: include/uapi/linux/gen_stats.h
:internal:
.. kernel-doc:: net/core/gen_stats.c
:export:
.. kernel-doc:: net/core/gen_estimator.c
:export:
SUN RPC subsystem
-----------------
.. kernel-doc:: net/sunrpc/xdr.c
:export:
.. kernel-doc:: net/sunrpc/svc_xprt.c
:export:
.. kernel-doc:: net/sunrpc/xprt.c
:export:
.. kernel-doc:: net/sunrpc/sched.c
:export:
.. kernel-doc:: net/sunrpc/socklib.c
:export:
.. kernel-doc:: net/sunrpc/stats.c
:export:
.. kernel-doc:: net/sunrpc/rpc_pipe.c
:export:
.. kernel-doc:: net/sunrpc/rpcb_clnt.c
:export:
.. kernel-doc:: net/sunrpc/clnt.c
:export:
WiMAX
-----
.. kernel-doc:: net/wimax/op-msg.c
:export:
.. kernel-doc:: net/wimax/op-reset.c
:export:
.. kernel-doc:: net/wimax/op-rfkill.c
:export:
.. kernel-doc:: net/wimax/stack.c
:export:
.. kernel-doc:: include/net/wimax.h
:internal:
.. kernel-doc:: include/uapi/linux/wimax.h
:internal:
Network device support
======================
Driver Support
--------------
.. kernel-doc:: net/core/dev.c
:export:
.. kernel-doc:: net/ethernet/eth.c
:export:
.. kernel-doc:: net/sched/sch_generic.c
:export:
.. kernel-doc:: include/linux/etherdevice.h
:internal:
.. kernel-doc:: include/linux/netdevice.h
:internal:
PHY Support
-----------
.. kernel-doc:: drivers/net/phy/phy.c
:export:
.. kernel-doc:: drivers/net/phy/phy.c
:internal:
.. kernel-doc:: drivers/net/phy/phy_device.c
:export:
.. kernel-doc:: drivers/net/phy/phy_device.c
:internal:
.. kernel-doc:: drivers/net/phy/mdio_bus.c
:export:
.. kernel-doc:: drivers/net/phy/mdio_bus.c
:internal:

256
Documentation/networking/z8530book.rst Normal file
View File

@ -0,0 +1,256 @@
=======================
Z8530 Programming Guide
=======================
:Author: Alan Cox
Introduction
============
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.
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
Driver Modes
============
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).
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.
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.
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.
Using the Z85230 driver
=======================
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.
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
:c:func:`z8530_interrupt()`. 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.
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.
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.
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.
Having initialised the device you can then call
:c:func:`z8530_init()`. 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.
Once you have called z8530_init you can also make use of the utility
function :c:func:`z8530_describe()`. This provides a consistent
reporting format for the Z8530 devices, and allows all the drivers to
provide consistent reporting.
Attaching Network Interfaces
============================
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.
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.
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.
If you wish to use the generic HDLC then you need to register the HDLC
device.
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.
Configuring And Activating The Port
===================================
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.
:c:func:`z8530_channel_load()` 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.
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.
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.
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.
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
:c:func:`z8530_null_rx()` to discard the data.
To active PIO mode sending and receiving the ``z8530_sync_open`` 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 :c:func:`z8530_sync_close()` function shuts down a PIO
channel. This must be done before the channel is opened again and before
the driver shuts down and unloads.
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
:c:func:`z8530_sync_dma_open()` function. On failure a non zero
error value is returned. Once this mode is activated it can be shut down
by calling the :c:func:`z8530_sync_dma_close()`. You must call
the close function matching the open mode you used.
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
``z8530_sync_txdma_open``. This returns a non zero error code on failure. The
:c:func:`z8530_sync_txdma_close()` function closes down the Z8530
interface from this mode.
Network Layer Functions
=======================
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.
The function :c:func:`z8530_queue_xmit()` 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.
The function :c:func:`z8530_get_stats()` 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.
Porting The Z8530 Driver
========================
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.
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 :c:func:`z8530_read_port()` and
``z8530_write_port`` is intended to be all that is required to port
this driver layer.
Known Bugs And Assumptions
==========================
Interrupt Locking
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.
Occasional Failures
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.
Public Functions Provided
=========================
.. kernel-doc:: drivers/net/wan/z85230.c
:export:
Internal Functions
==================
.. kernel-doc:: drivers/net/wan/z85230.c
:internal:

26
Documentation/process/changes.rst
View File

@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
Linux documentation for functions is transitioning to inline Linux documentation for functions is transitioning to inline
documentation via specially-formatted comments near their documentation via specially-formatted comments near their
definitions in the source. These comments can be combined with the definitions in the source. These comments can be combined with ReST
SGML templates in the Documentation/DocBook directory to make DocBook files the Documentation/ directory to make enriched documentation, which can
files, which can then be converted by DocBook stylesheets to PostScript, then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
HTML, PDF files, and several other formats. In order to convert from In order to convert from ReST format to a format of your choice, you'll need
DocBook format to a format of your choice, you'll need to install Jade as Sphinx.
well as the desired DocBook stylesheets.
Util-linux Util-linux
---------- ----------
@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
functionalities required for ``XeLaTex`` to work. For PDF output you'll also functionalities required for ``XeLaTex`` to work. For PDF output you'll also
need ``convert(1)`` from ImageMagick (https://www.imagemagick.org). need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
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 Getting updated software
======================== ========================
@ -409,15 +402,6 @@ Quota-tools
- <http://sourceforge.net/projects/linuxquota/> - <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 Intel P6 microcode
------------------ ------------------

8
Documentation/process/howto.rst
View File

@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
make latexdocs make latexdocs
make epubdocs 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 Becoming A Kernel Developer
--------------------------- ---------------------------

34
Documentation/process/kernel-docs.rst
View File

@ -40,50 +40,18 @@ Enjoy!
Docs at the Linux Kernel tree Docs at the Linux Kernel tree
----------------------------- -----------------------------
The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
* Name: **linux/Documentation** * Name: **linux/Documentation**
:Author: Many. :Author: Many.
:Location: Documentation/ :Location: Documentation/
:Keywords: text files, Sphinx, DocBook. :Keywords: text files, Sphinx.
:Description: Documentation that comes with the kernel sources, :Description: Documentation that comes with the kernel sources,
inside the Documentation directory. Some pages from this document inside the Documentation directory. Some pages from this document
(including this document itself) have been moved there, and might (including this document itself) have been moved there, and might
be more up to date than the web version. be more up to date than the web version.
* Title: **The Kernel Hacking HOWTO**
:Author: Various Talented People, and Rusty.
:Location: Documentation/DocBook/kernel-hacking.tmpl
:Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
symbols, return conventions.
:Description: From the Introduction: "Please understand that I
never wanted to write this document, being grossly underqualified,
but I always wanted to read it, and this was the only way. I
simply explain some best practices, and give reading entry-points
into the kernel sources. I avoid implementation details: that's
what the code is for, and I ignore whole tracts of useful
routines. This document assumes familiarity with C, and an
understanding of what the kernel is, and how it is used. It was
originally written for the 2.3 kernels, but nearly all of it
applies to 2.2 too; 2.0 is slightly different".
* Title: **Linux Kernel Locking HOWTO**
:Author: Various Talented People, and Rusty.
:Location: Documentation/DocBook/kernel-locking.tmpl
:Keywords: locks, locking, spinlock, semaphore, atomic, race
condition, bottom halves, tasklets, softirqs.
:Description: The title says it all: document describing the
locking system in the Linux Kernel either in uniprocessor or SMP
systems.
:Notes: "It was originally written for the later (>2.3.47) 2.3
kernels, but most of it applies to 2.2 too; 2.0 is slightly
different". Freely redistributable under the conditions of the GNU
General Public License.
On-line docs On-line docs
------------ ------------

10
Documentation/sh/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "SuperH architecture implementation manual"
tags.add("subproject")
latex_documents = [
('index', 'sh.tex', project,
'The kernel development community', 'manual'),
]

59
Documentation/sh/index.rst Normal file
View File

@ -0,0 +1,59 @@
=======================
SuperH Interfaces Guide
=======================
:Author: Paul Mundt
Memory Management
=================
SH-4
----
Store Queue API
~~~~~~~~~~~~~~~
.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
:export:
SH-5
----
TLB Interfaces
~~~~~~~~~~~~~~
.. kernel-doc:: arch/sh/mm/tlb-sh5.c
:internal:
.. kernel-doc:: arch/sh/include/asm/tlb_64.h
:internal:
Machine Specific Interfaces
===========================
mach-dreamcast
--------------
.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
:internal:
mach-x3proto
------------
.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
:export:
Busses
======
SuperHyway
----------
.. kernel-doc:: drivers/sh/superhyway/superhyway.c
:export:
Maple
-----
.. kernel-doc:: drivers/sh/maple/maple.c
:export:

10
Documentation/sound/conf.py Normal file
View File

@ -0,0 +1,10 @@
# -*- coding: utf-8; mode: python -*-
project = "Linux Sound Subsystem Documentation"
tags.add("subproject")
latex_documents = [
('index', 'sound.tex', project,
'The kernel development community', 'manual'),
]

28
Documentation/sphinx/tmplcvt
View File

@ -1,28 +0,0 @@
#!/bin/bash
#
# Convert a template file into something like RST
#
# fix <function>
# feed to pandoc
# fix \_
# title line?
#
set -eu
if [ "$#" != "2" ]; then
echo "$0 <docbook file> <rst file>"
exit
fi
DIR=$(dirname $0)
in=$1
rst=$2
tmp=$rst.tmp
cp $in $tmp
sed --in-place -f $DIR/convert_template.sed $tmp
pandoc -s -S -f docbook -t rst -o $rst $tmp
sed --in-place -f $DIR/post_convert.sed $rst
rm $tmp
echo "book writen to $rst"

7
Documentation/translations/ja_JP/howto.rst
View File

@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
make latexdocs make latexdocs
make epubdocs make epubdocs
現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
Postscript または man ページの形式を生成するには以下のようにします - ::
make psdocs
make mandocs
カーネル開発者になるには カーネル開発者になるには
------------------------ ------------------------

7
Documentation/translations/ko_KR/howto.rst
View File

@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
make latexdocs make latexdocs
make epubdocs make epubdocs
현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
Postscript 나 man page 로도 만들어질 수 있다::
make psdocs
make mandocs
커널 개발자가 되는 것 커널 개발자가 되는 것
--------------------- ---------------------

5
MAINTAINERS
View File

@ -3579,7 +3579,6 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6.git
S: Maintained S: Maintained
F: Documentation/crypto/ F: Documentation/crypto/
F: Documentation/devicetree/bindings/crypto/ F: Documentation/devicetree/bindings/crypto/
F: Documentation/DocBook/crypto-API.tmpl
F: arch/*/crypto/ F: arch/*/crypto/
F: crypto/ F: crypto/
F: drivers/crypto/ F: drivers/crypto/
@ -7377,7 +7376,7 @@ W: http://kgdb.wiki.kernel.org/
L: kgdb-bugreport@lists.sourceforge.net L: kgdb-bugreport@lists.sourceforge.net
T: git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git
S: Maintained S: Maintained
F: Documentation/DocBook/kgdb.tmpl F: Documentation/dev-tools/kgdb.rst
F: drivers/misc/kgdbts.c F: drivers/misc/kgdbts.c
F: drivers/tty/serial/kgdboc.c F: drivers/tty/serial/kgdboc.c
F: include/linux/kdb.h F: include/linux/kdb.h
@ -10990,7 +10989,7 @@ S: Supported
F: arch/s390/ F: arch/s390/
F: drivers/s390/ F: drivers/s390/
F: Documentation/s390/ F: Documentation/s390/
F: Documentation/DocBook/s390* F: Documentation/driver-api/s390-drivers.rst
S390 COMMON I/O LAYER S390 COMMON I/O LAYER
M: Sebastian Ott <sebott@linux.vnet.ibm.com> M: Sebastian Ott <sebott@linux.vnet.ibm.com>

11
Makefile
View File

@ -1312,7 +1312,7 @@ clean: archclean vmlinuxclean
# #
mrproper: rm-dirs := $(wildcard $(MRPROPER_DIRS)) mrproper: rm-dirs := $(wildcard $(MRPROPER_DIRS))
mrproper: rm-files := $(wildcard $(MRPROPER_FILES)) mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
mrproper-dirs := $(addprefix _mrproper_,Documentation/DocBook scripts) mrproper-dirs := $(addprefix _mrproper_,scripts)
PHONY += $(mrproper-dirs) mrproper archmrproper PHONY += $(mrproper-dirs) mrproper archmrproper
$(mrproper-dirs): $(mrproper-dirs):
@ -1416,9 +1416,7 @@ help:
@$(MAKE) $(build)=$(package-dir) help @$(MAKE) $(build)=$(package-dir) help
@echo '' @echo ''
@echo 'Documentation targets:' @echo 'Documentation targets:'
@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp @$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
@echo ''
@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
@echo '' @echo ''
@echo 'Architecture specific targets ($(SRCARCH)):' @echo 'Architecture specific targets ($(SRCARCH)):'
@$(if $(archhelp),$(archhelp),\ @$(if $(archhelp),$(archhelp),\
@ -1469,9 +1467,8 @@ $(help-board-dirs): help-%:
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
PHONY += $(DOC_TARGETS) PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE $(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype $(Q)$(MAKE) $(build)=scripts build_docproc
$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@ $(Q)$(MAKE) $(build)=Documentation $@
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
else # KBUILD_EXTMOD else # KBUILD_EXTMOD

2
arch/ia64/include/asm/io.h
View File

@ -117,7 +117,7 @@ extern int valid_mmap_phys_addr_range (unsigned long pfn, size_t count);
* following the barrier will arrive after all previous writes. For most * following the barrier will arrive after all previous writes. For most
* ia64 platforms, this is a simple 'mf.a' instruction. * ia64 platforms, this is a simple 'mf.a' instruction.
* *
* See Documentation/DocBook/deviceiobook.tmpl for more information. * See Documentation/driver-api/device-io.rst for more information.
*/ */
static inline void ___ia64_mmiowb(void) static inline void ___ia64_mmiowb(void)
{ {

2
arch/ia64/sn/kernel/iomv.c
View File

@ -63,7 +63,7 @@ EXPORT_SYMBOL(sn_io_addr);
/** /**
* __sn_mmiowb - I/O space memory barrier * __sn_mmiowb - I/O space memory barrier
* *
* See arch/ia64/include/asm/io.h and Documentation/DocBook/deviceiobook.tmpl * See arch/ia64/include/asm/io.h and Documentation/driver-api/device-io.rst
* for details. * for details.
* *
* On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear. * On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear.

2
drivers/ata/acard-ahci.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* AHCI hardware documentation: * AHCI hardware documentation:
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

2
drivers/ata/ahci.c
View File

@ -24,7 +24,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* AHCI hardware documentation: * AHCI hardware documentation:
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

2
drivers/ata/ahci.h
View File

@ -24,7 +24,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* AHCI hardware documentation: * AHCI hardware documentation:
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

2
drivers/ata/ata_piix.c
View File

@ -33,7 +33,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available at http://developer.intel.com/ * Hardware documentation available at http://developer.intel.com/
* *

2
drivers/ata/libahci.c
View File

@ -24,7 +24,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* AHCI hardware documentation: * AHCI hardware documentation:
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf * http://www.intel.com/technology/serialata/pdf/rev1_0.pdf

2
drivers/ata/libata-core.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available from http://www.t13.org/ and * Hardware documentation available from http://www.t13.org/ and
* http://www.sata-io.org/ * http://www.sata-io.org/

2
drivers/ata/libata-eh.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available from http://www.t13.org/ and * Hardware documentation available from http://www.t13.org/ and
* http://www.sata-io.org/ * http://www.sata-io.org/

9
drivers/ata/libata-scsi.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available from * Hardware documentation available from
* - http://www.t10.org/ * - http://www.t10.org/
@ -3398,9 +3398,10 @@ static size_t ata_format_dsm_trim_descr(struct scsi_cmnd *cmd, u32 trmax,
* *
* Translate a SCSI WRITE SAME command to be either a DSM TRIM command or * Translate a SCSI WRITE SAME command to be either a DSM TRIM command or
* an SCT Write Same command. * an SCT Write Same command.
* Based on WRITE SAME has the UNMAP flag * Based on WRITE SAME has the UNMAP flag:
* When set translate to DSM TRIM *
* When clear translate to SCT Write Same * - When set translate to DSM TRIM
* - When clear translate to SCT Write Same
*/ */
static unsigned int ata_scsi_write_same_xlat(struct ata_queued_cmd *qc) static unsigned int ata_scsi_write_same_xlat(struct ata_queued_cmd *qc)
{ {

2
drivers/ata/libata-sff.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available from http://www.t13.org/ and * Hardware documentation available from http://www.t13.org/ and
* http://www.sata-io.org/ * http://www.sata-io.org/

2
drivers/ata/libata.h
View File

@ -21,7 +21,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
*/ */

2
drivers/ata/pata_pdc2027x.c
View File

@ -17,7 +17,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware information only available under NDA. * Hardware information only available under NDA.
* *

2
drivers/ata/pdc_adma.c
View File

@ -21,7 +21,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* *
* Supports ATA disks in single-packet ADMA mode. * Supports ATA disks in single-packet ADMA mode.

2
drivers/ata/sata_nv.c
View File

@ -21,7 +21,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* No hardware documentation available outside of NVIDIA. * No hardware documentation available outside of NVIDIA.
* This driver programs the NVIDIA SATA controller in a similar * This driver programs the NVIDIA SATA controller in a similar

2
drivers/ata/sata_promise.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware information only available under NDA. * Hardware information only available under NDA.
* *

2
drivers/ata/sata_promise.h
View File

@ -20,7 +20,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
*/ */

2
drivers/ata/sata_qstor.c
View File

@ -23,7 +23,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
*/ */

2
drivers/ata/sata_sil.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Documentation for SiI 3112: * Documentation for SiI 3112:
* http://gkernel.sourceforge.net/specs/sii/3112A_SiI-DS-0095-B2.pdf.bz2 * http://gkernel.sourceforge.net/specs/sii/3112A_SiI-DS-0095-B2.pdf.bz2

2
drivers/ata/sata_sis.c
View File

@ -24,7 +24,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available under NDA. * Hardware documentation available under NDA.
* *

2
drivers/ata/sata_svw.c
View File

@ -30,7 +30,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available under NDA. * Hardware documentation available under NDA.
* *

2
drivers/ata/sata_sx4.c
View File

@ -24,7 +24,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available under NDA. * Hardware documentation available under NDA.
* *

2
drivers/ata/sata_uli.c
View File

@ -18,7 +18,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available under NDA. * Hardware documentation available under NDA.
* *

2
drivers/ata/sata_via.c
View File

@ -25,7 +25,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Hardware documentation available under NDA. * Hardware documentation available under NDA.
* *

2
drivers/ata/sata_vsc.c
View File

@ -26,7 +26,7 @@
* *
* *
* libata documentation is available via 'make {ps|pdf}docs', * libata documentation is available via 'make {ps|pdf}docs',
* as Documentation/DocBook/libata.* * as Documentation/driver-api/libata.rst
* *
* Vitesse hardware documentation presumably available under NDA. * Vitesse hardware documentation presumably available under NDA.
* Intel 31244 (same hardware interface) documentation presumably * Intel 31244 (same hardware interface) documentation presumably

7
drivers/mtd/nand/nand_base.c
View File

@ -502,10 +502,12 @@ static int nand_default_block_markbad(struct mtd_info *mtd, loff_t ofs)
* specify how to write bad block markers to OOB (chip->block_markbad). * specify how to write bad block markers to OOB (chip->block_markbad).
* *
* We try operations in the following order: * We try operations in the following order:
*
* (1) erase the affected block, to allow OOB marker to be written cleanly * (1) erase the affected block, to allow OOB marker to be written cleanly
* (2) write bad block marker to OOB area of affected block (unless flag * (2) write bad block marker to OOB area of affected block (unless flag
* NAND_BBT_NO_OOB_BBM is present) * NAND_BBT_NO_OOB_BBM is present)
* (3) update the BBT * (3) update the BBT
*
* Note that we retain the first error encountered in (2) or (3), finish the * Note that we retain the first error encountered in (2) or (3), finish the
* procedures, and dump the error in the end. * procedures, and dump the error in the end.
*/ */
@ -1219,9 +1221,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
* @mtd: mtd info * @mtd: mtd info
* @ofs: offset to start unlock from * @ofs: offset to start unlock from
* @len: length to unlock * @len: length to unlock
* @invert: when = 0, unlock the range of blocks within the lower and * @invert:
* - when = 0, unlock the range of blocks within the lower and
* upper boundary address * upper boundary address
* when = 1, unlock the range of blocks outside the boundaries * - when = 1, unlock the range of blocks outside the boundaries
* of the lower and upper boundary address * of the lower and upper boundary address
* *
* Returs unlock status. * Returs unlock status.

1
drivers/net/phy/phy.c
View File

@ -377,6 +377,7 @@ static void phy_sanitize_settings(struct phy_device *phydev)
* @cmd: ethtool_cmd * @cmd: ethtool_cmd
* *
* A few notes about parameter checking: * A few notes about parameter checking:
*
* - We don't set port or transceiver, so we don't care what they * - We don't set port or transceiver, so we don't care what they
* were set to. * were set to.
* - phy_start_aneg() will make sure forced settings are sane, and * - phy_start_aneg() will make sure forced settings are sane, and

2
drivers/scsi/qla1280.c
View File

@ -3390,7 +3390,7 @@ qla1280_isp_cmd(struct scsi_qla_host *ha)
* On PCI bus, order reverses and write of 6 posts, then index 5, * On PCI bus, order reverses and write of 6 posts, then index 5,
* causing chip to issue full queue of stale commands * causing chip to issue full queue of stale commands
* The mmiowb() prevents future writes from crossing the barrier. * The mmiowb() prevents future writes from crossing the barrier.
* See Documentation/DocBook/deviceiobook.tmpl for more information. * See Documentation/driver-api/device-io.rst for more information.
*/ */
WRT_REG_WORD(&reg->mailbox4, ha->req_ring_index); WRT_REG_WORD(&reg->mailbox4, ha->req_ring_index);
mmiowb(); mmiowb();

7
drivers/scsi/scsi_scan.c
View File

@ -1051,10 +1051,11 @@ static unsigned char *scsi_inq_str(unsigned char *buf, unsigned char *inq,
* allocate and set it up by calling scsi_add_lun. * allocate and set it up by calling scsi_add_lun.
* *
* Return: * Return:
* SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device *
* SCSI_SCAN_TARGET_PRESENT: target responded, but no device is * - SCSI_SCAN_NO_RESPONSE: could not allocate or setup a scsi_device
* - SCSI_SCAN_TARGET_PRESENT: target responded, but no device is
* attached at the LUN * attached at the LUN
* SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized * - SCSI_SCAN_LUN_PRESENT: a new scsi_device was allocated and initialized
**/ **/
static int scsi_probe_and_add_lun(struct scsi_target *starget, static int scsi_probe_and_add_lun(struct scsi_target *starget,
u64 lun, int *bflagsp, u64 lun, int *bflagsp,

2
drivers/scsi/scsi_transport_fc.c
View File

@ -2914,10 +2914,12 @@ EXPORT_SYMBOL(fc_remote_port_add);
* port is no longer part of the topology. Note: Although a port * port is no longer part of the topology. Note: Although a port
* may no longer be part of the topology, it may persist in the remote * may no longer be part of the topology, it may persist in the remote
* ports displayed by the fc_host. We do this under 2 conditions: * ports displayed by the fc_host. We do this under 2 conditions:
*
* 1) If the port was a scsi target, we delay its deletion by "blocking" it. * 1) If the port was a scsi target, we delay its deletion by "blocking" it.
* This allows the port to temporarily disappear, then reappear without * This allows the port to temporarily disappear, then reappear without
* disrupting the SCSI device tree attached to it. During the "blocked" * disrupting the SCSI device tree attached to it. During the "blocked"
* period the port will still exist. * period the port will still exist.
*
* 2) If the port was a scsi target and disappears for longer than we * 2) If the port was a scsi target and disappears for longer than we
* expect, we'll delete the port and the tear down the SCSI device tree * expect, we'll delete the port and the tear down the SCSI device tree
* attached to it. However, we want to semi-persist the target id assigned * attached to it. However, we want to semi-persist the target id assigned

4
drivers/scsi/scsicam.c
View File

@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param);
* @hds: put heads here * @hds: put heads here
* @secs: put sectors here * @secs: put sectors here
* *
* Description: determine the BIOS mapping/geometry used to create the partition * Determine the BIOS mapping/geometry used to create the partition
* table, storing the results in *cyls, *hds, and *secs * table, storing the results in @cyls, @hds, and @secs
* *
* Returns: -1 on failure, 0 on success. * Returns: -1 on failure, 0 on success.
*/ */

2
drivers/usb/gadget/Kconfig
View File

@ -41,7 +41,7 @@ menuconfig USB_GADGET
don't have this kind of hardware (except maybe inside Linux PDAs). don't have this kind of hardware (except maybe inside Linux PDAs).
For more information, see <http://www.linux-usb.org/gadget> and For more information, see <http://www.linux-usb.org/gadget> and
the kernel DocBook documentation for this API. the kernel documentation for this API.
if USB_GADGET if USB_GADGET

2
fs/debugfs/file.c
View File

@ -9,7 +9,7 @@
* 2 as published by the Free Software Foundation. * 2 as published by the Free Software Foundation.
* *
* debugfs is for people to use instead of /proc or /sys. * debugfs is for people to use instead of /proc or /sys.
* See Documentation/DocBook/filesystems for more details. * See Documentation/filesystems/ for more details.
* *
*/ */

2
fs/debugfs/inode.c
View File

@ -9,7 +9,7 @@
* 2 as published by the Free Software Foundation. * 2 as published by the Free Software Foundation.
* *
* debugfs is for people to use instead of /proc or /sys. * debugfs is for people to use instead of /proc or /sys.
* See Documentation/DocBook/kernel-api for more details. * See ./Documentation/core-api/kernel-api.rst for more details.
* *
*/ */

Some files were not shown because too many files have changed in this diff Show More