Merge remote-tracking branch 'mauro-exp/docbook3' into death-to-docbook
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:
commit
6312811be2
|
@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
|
|||
- How to do DMA with ISA (and LPC) devices.
|
||||
DMA-attributes.txt
|
||||
- listing of the various possible attributes a DMA region can have
|
||||
DocBook/
|
||||
- directory with DocBook templates etc. for kernel documentation.
|
||||
EDID/
|
||||
- directory with info on customizing EDID for broken gfx/displays.
|
||||
IPMI.txt
|
||||
|
@ -40,8 +38,6 @@ Intel-IOMMU.txt
|
|||
- basic info on the Intel IOMMU virtualization support.
|
||||
Makefile
|
||||
- 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/
|
||||
- info related to PCI drivers.
|
||||
RCU/
|
||||
|
@ -264,6 +260,8 @@ logo.gif
|
|||
- full colour GIF image of Linux logo (penguin - Tux).
|
||||
logo.txt
|
||||
- info on creator of above logo & site to get additional images from.
|
||||
lsm.txt
|
||||
- Linux Security Modules: General Security Hooks for Linux
|
||||
lzo.txt
|
||||
- kernel LZO decompressor input formats
|
||||
m68k/
|
||||
|
|
|
@ -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
|
|
@ -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/&/\\&/g" \
|
||||
-e "s/</\\</g" \
|
||||
-e "s/>/\\>/g"; \
|
||||
echo "</programlisting>") > $@
|
||||
|
||||
endif # DOCBOOKS=""
|
||||
endif # SPHINDIR=...
|
||||
|
||||
###
|
||||
# Help targets as used by the top-level makefile
|
||||
dochelp:
|
||||
@echo ' Linux kernel internal documentation in different formats (DocBook):'
|
||||
@echo ' htmldocs - HTML'
|
||||
@echo ' pdfdocs - PDF'
|
||||
@echo ' psdocs - Postscript'
|
||||
@echo ' xmldocs - XML DocBook'
|
||||
@echo ' mandocs - man pages'
|
||||
@echo ' installmandocs - install man pages generated by mandocs 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)
|
|
@ -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>
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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=<tty-device>,[baud]</constant></para></listitem>
|
||||
<listitem>
|
||||
<para>As a kernel loadable module:</para>
|
||||
<para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para>
|
||||
<para>Here are two examples of how you might format the kgdboc
|
||||
string. The first is for an x86 target using the first serial port.
|
||||
The second example is for the ARM Versatile AB using the second
|
||||
serial port.
|
||||
<orderedlist>
|
||||
<listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
|
||||
<listitem><para><constant>kgdboc=ttyAMA1,115200</constant></para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist></para>
|
||||
</sect3>
|
||||
<sect3 id="kgdbocArgs2">
|
||||
<title>Configure kgdboc at runtime with sysfs</title>
|
||||
<para>At run time you can enable or disable kgdboc by echoing a
|
||||
parameters into the sysfs. Here are two examples:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Enable kgdboc on ttyS0</para>
|
||||
<para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||
<listitem><para>Disable kgdboc</para>
|
||||
<para><constant>echo "" > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||
</orderedlist>
|
||||
<para>NOTE: You do not need to specify the baud if you are
|
||||
configuring the console on tty which is already configured or
|
||||
open.</para>
|
||||
</sect3>
|
||||
<sect3 id="kgdbocArgs3">
|
||||
<title>More examples</title>
|
||||
<para>You can configure kgdboc to use the keyboard, and/or a serial device
|
||||
depending on if you are using kdb and/or kgdb, in one of the
|
||||
following scenarios.
|
||||
<orderedlist>
|
||||
<listitem><para>kdb and kgdb over only a serial port</para>
|
||||
<para><constant>kgdboc=<serial_device>[,baud]</constant></para>
|
||||
<para>Example: <constant>kgdboc=ttyS0,115200</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>kdb and kgdb with keyboard and a serial port</para>
|
||||
<para><constant>kgdboc=kbd,<serial_device>[,baud]</constant></para>
|
||||
<para>Example: <constant>kgdboc=kbd,ttyS0,115200</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>kdb with a keyboard</para>
|
||||
<para><constant>kgdboc=kbd</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>kdb with kernel mode setting</para>
|
||||
<para><constant>kgdboc=kms,kbd</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>kdb with kernel mode setting and kgdb over a serial port</para>
|
||||
<para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
<para>NOTE: Kgdboc does not support interrupting the target via the
|
||||
gdb remote protocol. You must manually send a sysrq-g unless you
|
||||
have a proxy that splits console output to a terminal program.
|
||||
A console proxy has a separate TCP port for the debugger and a separate
|
||||
TCP port for the "human" console. The proxy can take care of sending
|
||||
the sysrq-g for you.
|
||||
</para>
|
||||
<para>When using kgdboc with no debugger proxy, you can end up
|
||||
connecting the debugger at one of two entry points. If an
|
||||
exception occurs after you have loaded kgdboc, a message should
|
||||
print on the console stating it is waiting for the debugger. In
|
||||
this case you disconnect your terminal program and then connect the
|
||||
debugger in its place. If you want to interrupt the target system
|
||||
and forcibly enter a debug session you have to issue a Sysrq
|
||||
sequence and then type the letter <constant>g</constant>. Then
|
||||
you disconnect the terminal session and connect gdb. Your options
|
||||
if you don't like this are to hack gdb to send the sysrq-g for you
|
||||
as well as on the initial connect, or to use a debugger proxy that
|
||||
allows an unmodified gdb to do the debugging.
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="kgdbwait">
|
||||
<title>Kernel parameter: kgdbwait</title>
|
||||
<para>
|
||||
The Kernel command line option <constant>kgdbwait</constant> makes
|
||||
kgdb wait for a debugger connection during booting of a kernel. You
|
||||
can only use this option if you compiled a kgdb I/O driver into the
|
||||
kernel and you specified the I/O driver configuration as a kernel
|
||||
command line option. The kgdbwait parameter should always follow the
|
||||
configuration parameter for the kgdb I/O driver in the kernel
|
||||
command line else the I/O driver will not be configured prior to
|
||||
asking the kernel to use it to wait.
|
||||
</para>
|
||||
<para>
|
||||
The kernel will stop and wait as early as the I/O driver and
|
||||
architecture allows when you use this option. If you build the
|
||||
kgdb I/O driver as a loadable kernel module kgdbwait will not do
|
||||
anything.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="kgdbcon">
|
||||
<title>Kernel parameter: kgdbcon</title>
|
||||
<para> The kgdbcon feature allows you to see printk() messages
|
||||
inside gdb while gdb is connected to the kernel. Kdb does not make
|
||||
use of the kgdbcon feature.
|
||||
</para>
|
||||
<para>Kgdb supports using the gdb serial protocol to send console
|
||||
messages to the debugger when the debugger is connected and running.
|
||||
There are two ways to activate this feature.
|
||||
<orderedlist>
|
||||
<listitem><para>Activate with the kernel command line option:</para>
|
||||
<para><constant>kgdbcon</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>Use sysfs before configuring an I/O driver</para>
|
||||
<para>
|
||||
<constant>echo 1 > /sys/module/kgdb/parameters/kgdb_use_con</constant>
|
||||
</para>
|
||||
<para>
|
||||
NOTE: If you do this after you configure the kgdb I/O driver, the
|
||||
setting will not take effect until the next point the I/O is
|
||||
reconfigured.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
<para>IMPORTANT NOTE: You cannot use kgdboc + kgdbcon on a tty that is an
|
||||
active system console. An example of incorrect usage is <constant>console=ttyS0,115200 kgdboc=ttyS0 kgdbcon</constant>
|
||||
</para>
|
||||
<para>It is possible to use this option with kgdboc on a tty that is not a system console.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="kgdbreboot">
|
||||
<title>Run time parameter: kgdbreboot</title>
|
||||
<para> The kgdbreboot feature allows you to change how the debugger
|
||||
deals with the reboot notification. You have 3 choices for the
|
||||
behavior. The default behavior is always set to 0.</para>
|
||||
<orderedlist>
|
||||
<listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para>
|
||||
<para>Ignore the reboot notification entirely.</para>
|
||||
</listitem>
|
||||
<listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para>
|
||||
<para>Send the detach message to any attached debugger client.</para>
|
||||
</listitem>
|
||||
<listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para>
|
||||
<para>Enter the debugger on reboot notify.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</sect1>
|
||||
</chapter>
|
||||
<chapter id="usingKDB">
|
||||
<title>Using kdb</title>
|
||||
<para>
|
||||
</para>
|
||||
<sect1 id="quickKDBserial">
|
||||
<title>Quick start for kdb on a serial port</title>
|
||||
<para>This is a quick example of how to use kdb.</para>
|
||||
<para><orderedlist>
|
||||
<listitem><para>Configure kgdboc at boot using kernel parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>console=ttyS0,115200 kgdboc=ttyS0,115200</constant></para></listitem>
|
||||
</itemizedlist></para>
|
||||
<para>OR</para>
|
||||
<para>Configure kgdboc after the kernel has booted; assuming you are using a serial port console:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>When logged in as root or with a super user session you can run:</para>
|
||||
<para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem>
|
||||
<listitem><para>Example using minicom 2.2</para>
|
||||
<para>Press: <constant>Control-a</constant></para>
|
||||
<para>Press: <constant>f</constant></para>
|
||||
<para>Press: <constant>g</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>When you have telneted to a terminal server that supports sending a remote break</para>
|
||||
<para>Press: <constant>Control-]</constant></para>
|
||||
<para>Type in:<constant>send break</constant></para>
|
||||
<para>Press: <constant>Enter</constant></para>
|
||||
<para>Press: <constant>g</constant></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>From the kdb prompt you can run the "help" command to see a complete list of the commands that are available.</para>
|
||||
<para>Some useful commands in kdb include:
|
||||
<itemizedlist>
|
||||
<listitem><para>lsmod -- Shows where kernel modules are loaded</para></listitem>
|
||||
<listitem><para>ps -- Displays only the active processes</para></listitem>
|
||||
<listitem><para>ps A -- Shows all the processes</para></listitem>
|
||||
<listitem><para>summary -- Shows kernel version info and memory usage</para></listitem>
|
||||
<listitem><para>bt -- Get a backtrace of the current process using dump_stack()</para></listitem>
|
||||
<listitem><para>dmesg -- View the kernel syslog buffer</para></listitem>
|
||||
<listitem><para>go -- Continue the system</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>When you are done using kdb you need to consider rebooting the
|
||||
system or using the "go" command to resuming normal kernel
|
||||
execution. If you have paused the kernel for a lengthy period of
|
||||
time, applications that rely on timely networking or anything to do
|
||||
with real wall clock time could be adversely affected, so you
|
||||
should take this into consideration when using the kernel
|
||||
debugger.</para>
|
||||
</listitem>
|
||||
</orderedlist></para>
|
||||
</sect1>
|
||||
<sect1 id="quickKDBkeyboard">
|
||||
<title>Quick start for kdb using a keyboard connected console</title>
|
||||
<para>This is a quick example of how to use kdb with a keyboard.</para>
|
||||
<para><orderedlist>
|
||||
<listitem><para>Configure kgdboc at boot using kernel parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>kgdboc=kbd</constant></para></listitem>
|
||||
</itemizedlist></para>
|
||||
<para>OR</para>
|
||||
<para>Configure kgdboc after the kernel has booted:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>echo kbd > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>Enter the kernel debugger manually or by waiting for an oops or fault. There are several ways you can enter the kernel debugger manually; all involve using the sysrq-g, which means you must have enabled CONFIG_MAGIC_SYSRQ=y in your kernel config.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>When logged in as root or with a super user session you can run:</para>
|
||||
<para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem>
|
||||
<listitem><para>Example using a laptop keyboard</para>
|
||||
<para>Press and hold down: <constant>Alt</constant></para>
|
||||
<para>Press and hold down: <constant>Fn</constant></para>
|
||||
<para>Press and release the key with the label: <constant>SysRq</constant></para>
|
||||
<para>Release: <constant>Fn</constant></para>
|
||||
<para>Press and release: <constant>g</constant></para>
|
||||
<para>Release: <constant>Alt</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>Example using a PS/2 101-key keyboard</para>
|
||||
<para>Press and hold down: <constant>Alt</constant></para>
|
||||
<para>Press and release the key with the label: <constant>SysRq</constant></para>
|
||||
<para>Press and release: <constant>g</constant></para>
|
||||
<para>Release: <constant>Alt</constant></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Now type in a kdb command such as "help", "dmesg", "bt" or "go" to continue kernel execution.</para>
|
||||
</listitem>
|
||||
</orderedlist></para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
<chapter id="EnableKGDB">
|
||||
<title>Using kgdb / gdb</title>
|
||||
<para>In order to use kgdb you must activate it by passing
|
||||
configuration information to one of the kgdb I/O drivers. If you
|
||||
do not pass any configuration information kgdb will not do anything
|
||||
at all. Kgdb will only actively hook up to the kernel trap hooks
|
||||
if a kgdb I/O driver is loaded and configured. If you unconfigure
|
||||
a kgdb I/O driver, kgdb will unregister all the kernel hook points.
|
||||
</para>
|
||||
<para> All kgdb I/O drivers can be reconfigured at run time, if
|
||||
<symbol>CONFIG_SYSFS</symbol> and <symbol>CONFIG_MODULES</symbol>
|
||||
are enabled, by echo'ing a new config string to
|
||||
<constant>/sys/module/<driver>/parameter/<option></constant>.
|
||||
The driver can be unconfigured by passing an empty string. You cannot
|
||||
change the configuration while the debugger is attached. Make sure
|
||||
to detach the debugger with the <constant>detach</constant> command
|
||||
prior to trying to unconfigure a kgdb I/O driver.
|
||||
</para>
|
||||
<sect1 id="ConnectingGDB">
|
||||
<title>Connecting with gdb to a serial port</title>
|
||||
<orderedlist>
|
||||
<listitem><para>Configure kgdboc</para>
|
||||
<para>Configure kgdboc at boot using kernel parameters:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>kgdboc=ttyS0,115200</constant></para></listitem>
|
||||
</itemizedlist></para>
|
||||
<para>OR</para>
|
||||
<para>Configure kgdboc after the kernel has booted:
|
||||
<itemizedlist>
|
||||
<listitem><para><constant>echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc</constant></para></listitem>
|
||||
</itemizedlist></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Stop kernel execution (break into the debugger)</para>
|
||||
<para>In order to connect to gdb via kgdboc, the kernel must
|
||||
first be stopped. There are several ways to stop the kernel which
|
||||
include using kgdbwait as a boot argument, via a sysrq-g, or running
|
||||
the kernel until it takes an exception where it waits for the
|
||||
debugger to attach.
|
||||
<itemizedlist>
|
||||
<listitem><para>When logged in as root or with a super user session you can run:</para>
|
||||
<para><constant>echo g > /proc/sysrq-trigger</constant></para></listitem>
|
||||
<listitem><para>Example using minicom 2.2</para>
|
||||
<para>Press: <constant>Control-a</constant></para>
|
||||
<para>Press: <constant>f</constant></para>
|
||||
<para>Press: <constant>g</constant></para>
|
||||
</listitem>
|
||||
<listitem><para>When you have telneted to a terminal server that supports sending a remote break</para>
|
||||
<para>Press: <constant>Control-]</constant></para>
|
||||
<para>Type in:<constant>send break</constant></para>
|
||||
<para>Press: <constant>Enter</constant></para>
|
||||
<para>Press: <constant>g</constant></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Connect from gdb</para>
|
||||
<para>
|
||||
Example (using a directly connected port):
|
||||
</para>
|
||||
<programlisting>
|
||||
% gdb ./vmlinux
|
||||
(gdb) set remotebaud 115200
|
||||
(gdb) target remote /dev/ttyS0
|
||||
</programlisting>
|
||||
<para>
|
||||
Example (kgdb to a terminal server on TCP port 2012):
|
||||
</para>
|
||||
<programlisting>
|
||||
% gdb ./vmlinux
|
||||
(gdb) target remote 192.168.2.2:2012
|
||||
</programlisting>
|
||||
<para>
|
||||
Once connected, you can debug a kernel the way you would debug an
|
||||
application program.
|
||||
</para>
|
||||
<para>
|
||||
If you are having problems connecting or something is going
|
||||
seriously wrong while debugging, it will most often be the case
|
||||
that you want to enable gdb to be verbose about its target
|
||||
communications. You do this prior to issuing the <constant>target
|
||||
remote</constant> command by typing in: <constant>set debug remote 1</constant>
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<para>Remember if you continue in gdb, and need to "break in" again,
|
||||
you need to issue an other sysrq-g. It is easy to create a simple
|
||||
entry point by putting a breakpoint at <constant>sys_sync</constant>
|
||||
and then you can run "sync" from a shell or script to break into the
|
||||
debugger.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
<chapter id="switchKdbKgdb">
|
||||
<title>kgdb and kdb interoperability</title>
|
||||
<para>It is possible to transition between kdb and kgdb dynamically.
|
||||
The debug core will remember which you used the last time and
|
||||
automatically start in the same mode.</para>
|
||||
<sect1>
|
||||
<title>Switching between kdb and kgdb</title>
|
||||
<sect2>
|
||||
<title>Switching from kgdb to kdb</title>
|
||||
<para>
|
||||
There are two ways to switch from kgdb to kdb: you can use gdb to
|
||||
issue a maintenance packet, or you can blindly type the command $3#33.
|
||||
Whenever the kernel debugger stops in kgdb mode it will print the
|
||||
message <constant>KGDB or $3#33 for KDB</constant>. It is important
|
||||
to note that you have to type the sequence correctly in one pass.
|
||||
You cannot type a backspace or delete because kgdb will interpret
|
||||
that as part of the debug stream.
|
||||
<orderedlist>
|
||||
<listitem><para>Change from kgdb to kdb by blindly typing:</para>
|
||||
<para><constant>$3#33</constant></para></listitem>
|
||||
<listitem><para>Change from kgdb to kdb with gdb</para>
|
||||
<para><constant>maintenance packet 3</constant></para>
|
||||
<para>NOTE: Now you must kill gdb. Typically you press control-z and
|
||||
issue the command: kill -9 %</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Change from kdb to kgdb</title>
|
||||
<para>There are two ways you can change from kdb to kgdb. You can
|
||||
manually enter kgdb mode by issuing the kgdb command from the kdb
|
||||
shell prompt, or you can connect gdb while the kdb shell prompt is
|
||||
active. The kdb shell looks for the typical first commands that gdb
|
||||
would issue with the gdb remote protocol and if it sees one of those
|
||||
commands it automatically changes into kgdb mode.</para>
|
||||
<orderedlist>
|
||||
<listitem><para>From kdb issue the command:</para>
|
||||
<para><constant>kgdb</constant></para>
|
||||
<para>Now disconnect your terminal program and connect gdb in its place</para></listitem>
|
||||
<listitem><para>At the kdb prompt, disconnect the terminal program and connect gdb in its place.</para></listitem>
|
||||
</orderedlist>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1>
|
||||
<title>Running kdb commands from gdb</title>
|
||||
<para>It is possible to run a limited set of kdb commands from gdb,
|
||||
using the gdb monitor command. You don't want to execute any of the
|
||||
run control or breakpoint operations, because it can disrupt the
|
||||
state of the kernel debugger. You should be using gdb for
|
||||
breakpoints and run control operations if you have gdb connected.
|
||||
The more useful commands to run are things like lsmod, dmesg, ps or
|
||||
possibly some of the memory information commands. To see all the kdb
|
||||
commands you can run <constant>monitor help</constant>.</para>
|
||||
<para>Example:
|
||||
<informalexample><programlisting>
|
||||
(gdb) monitor ps
|
||||
1 idle process (state I) and
|
||||
27 sleeping system daemon (state M) processes suppressed,
|
||||
use 'ps A' to see all.
|
||||
Task Addr Pid Parent [*] cpu State Thread Command
|
||||
|
||||
0xc78291d0 1 0 0 0 S 0xc7829404 init
|
||||
0xc7954150 942 1 0 0 S 0xc7954384 dropbear
|
||||
0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
|
||||
(gdb)
|
||||
</programlisting></informalexample>
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
<chapter id="KGDBTestSuite">
|
||||
<title>kgdb Test Suite</title>
|
||||
<para>
|
||||
When kgdb is enabled in the kernel config you can also elect to
|
||||
enable the config parameter KGDB_TESTS. Turning this on will
|
||||
enable a special kgdb I/O module which is designed to test the
|
||||
kgdb internal functions.
|
||||
</para>
|
||||
<para>
|
||||
The kgdb tests are mainly intended for developers to test the kgdb
|
||||
internals as well as a tool for developing a new kgdb architecture
|
||||
specific implementation. These tests are not really for end users
|
||||
of the Linux kernel. The primary source of documentation would be
|
||||
to look in the drivers/misc/kgdbts.c file.
|
||||
</para>
|
||||
<para>
|
||||
The kgdb test suite can also be configured at compile time to run
|
||||
the core set of tests by setting the kernel config parameter
|
||||
KGDB_TESTS_ON_BOOT. This particular option is aimed at automated
|
||||
regression testing and does not require modifying the kernel boot
|
||||
config arguments. If this is turned on, the kgdb test suite can
|
||||
be disabled by specifying "kgdbts=" as a kernel boot argument.
|
||||
</para>
|
||||
</chapter>
|
||||
<chapter id="CommonBackEndReq">
|
||||
<title>Kernel Debugger Internals</title>
|
||||
<sect1 id="kgdbArchitecture">
|
||||
<title>Architecture Specifics</title>
|
||||
<para>
|
||||
The kernel debugger is organized into a number of components:
|
||||
<orderedlist>
|
||||
<listitem><para>The debug core</para>
|
||||
<para>
|
||||
The debug core is found in kernel/debugger/debug_core.c. It contains:
|
||||
<itemizedlist>
|
||||
<listitem><para>A generic OS exception handler which includes
|
||||
sync'ing the processors into a stopped state on an multi-CPU
|
||||
system.</para></listitem>
|
||||
<listitem><para>The API to talk to the kgdb I/O drivers</para></listitem>
|
||||
<listitem><para>The API to make calls to the arch-specific kgdb implementation</para></listitem>
|
||||
<listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
|
||||
<listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
|
||||
<listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem>
|
||||
<listitem><para>The structures and callback API for atomic kernel mode setting.</para>
|
||||
<para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>kgdb arch-specific implementation</para>
|
||||
<para>
|
||||
This implementation is generally found in arch/*/kernel/kgdb.c.
|
||||
As an example, arch/x86/kernel/kgdb.c contains the specifics to
|
||||
implement HW breakpoint as well as the initialization to
|
||||
dynamically register and unregister for the trap handlers on
|
||||
this architecture. The arch-specific portion implements:
|
||||
<itemizedlist>
|
||||
<listitem><para>contains an arch-specific trap catcher which
|
||||
invokes kgdb_handle_exception() to start kgdb about doing its
|
||||
work</para></listitem>
|
||||
<listitem><para>translation to and from gdb specific packet format to pt_regs</para></listitem>
|
||||
<listitem><para>Registration and unregistration of architecture specific trap hooks</para></listitem>
|
||||
<listitem><para>Any special exception handling and cleanup</para></listitem>
|
||||
<listitem><para>NMI exception handling and cleanup</para></listitem>
|
||||
<listitem><para>(optional) HW breakpoints</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>gdbstub frontend (aka kgdb)</para>
|
||||
<para>The gdbstub is located in kernel/debug/gdbstub.c. It contains:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>All the logic to implement the gdb serial protocol</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>kdb frontend</para>
|
||||
<para>The kdb debugger shell is broken down into a number of
|
||||
components. The kdb core is located in kernel/debug/kdb. There
|
||||
are a number of helper functions in some of the other kernel
|
||||
components to make it possible for kdb to examine and report
|
||||
information about the kernel without taking locks that could
|
||||
cause a kernel deadlock. The kdb core contains implements the following functionality.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>A simple shell</para></listitem>
|
||||
<listitem><para>The kdb core command set</para></listitem>
|
||||
<listitem><para>A registration API to register additional kdb shell commands.</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>A good example of a self-contained kdb module
|
||||
is the "ftdump" command for dumping the ftrace buffer. See:
|
||||
kernel/trace/trace_kdb.c</para></listitem>
|
||||
<listitem><para>For an example of how to dynamically register
|
||||
a new kdb command you can build the kdb_hello.ko kernel module
|
||||
from samples/kdb/kdb_hello.c. To build this example you can
|
||||
set CONFIG_SAMPLES=y and CONFIG_SAMPLE_KDB=m in your kernel
|
||||
config. Later run "modprobe kdb_hello" and the next time you
|
||||
enter the kdb shell, you can run the "hello"
|
||||
command.</para></listitem>
|
||||
</itemizedlist></listitem>
|
||||
<listitem><para>The implementation for kdb_printf() which
|
||||
emits messages directly to I/O drivers, bypassing the kernel
|
||||
log.</para></listitem>
|
||||
<listitem><para>SW / HW breakpoint management for the kdb shell</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>kgdb I/O driver</para>
|
||||
<para>
|
||||
Each kgdb I/O driver has to provide an implementation for the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>configuration via built-in or module</para></listitem>
|
||||
<listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
|
||||
<listitem><para>read and write character interface</para></listitem>
|
||||
<listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
|
||||
<listitem><para>(optional) Early debug methodology</para></listitem>
|
||||
</itemizedlist>
|
||||
Any given kgdb I/O driver has to operate very closely with the
|
||||
hardware and must do it in such a way that does not enable
|
||||
interrupts or change other parts of the system context without
|
||||
completely restoring them. The kgdb core will repeatedly "poll"
|
||||
a kgdb I/O driver for characters when it needs input. The I/O
|
||||
driver is expected to return immediately if there is no data
|
||||
available. Doing so allows for the future possibility to touch
|
||||
watchdog hardware in such a way as to have a target system not
|
||||
reset when these are enabled.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
<para>
|
||||
If you are intent on adding kgdb architecture specific support
|
||||
for a new architecture, the architecture should define
|
||||
<constant>HAVE_ARCH_KGDB</constant> in the architecture specific
|
||||
Kconfig file. This will enable kgdb for the architecture, and
|
||||
at that point you must create an architecture specific kgdb
|
||||
implementation.
|
||||
</para>
|
||||
<para>
|
||||
There are a few flags which must be set on every architecture in
|
||||
their <asm/kgdb.h> file. These are:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
NUMREGBYTES: The size in bytes of all of the registers, so
|
||||
that we can ensure they will all fit into a packet.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
BUFMAX: The size in bytes of the buffer GDB will read into.
|
||||
This must be larger than NUMREGBYTES.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
CACHE_FLUSH_IS_SAFE: Set to 1 if it is always safe to call
|
||||
flush_cache_range or flush_icache_range. On some architectures,
|
||||
these functions may not be safe to call on SMP since we keep other
|
||||
CPUs in a holding pattern.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
There are also the following functions for the common backend,
|
||||
found in kernel/kgdb.c, that must be supplied by the
|
||||
architecture-specific backend unless marked as (optional), in
|
||||
which case a default function maybe used if the architecture
|
||||
does not need to provide a specific implementation.
|
||||
</para>
|
||||
!Iinclude/linux/kgdb.h
|
||||
</sect1>
|
||||
<sect1 id="kgdbocDesign">
|
||||
<title>kgdboc internals</title>
|
||||
<sect2>
|
||||
<title>kgdboc and uarts</title>
|
||||
<para>
|
||||
The kgdboc driver is actually a very thin driver that relies on the
|
||||
underlying low level to the hardware driver having "polling hooks"
|
||||
to which the tty driver is attached. In the initial
|
||||
implementation of kgdboc the serial_core was changed to expose a
|
||||
low level UART hook for doing polled mode reading and writing of a
|
||||
single character while in an atomic context. When kgdb makes an I/O
|
||||
request to the debugger, kgdboc invokes a callback in the serial
|
||||
core which in turn uses the callback in the UART driver.</para>
|
||||
<para>
|
||||
When using kgdboc with a UART, the UART driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>
|
||||
#ifdef CONFIG_CONSOLE_POLL
|
||||
.poll_get_char = serial8250_get_poll_char,
|
||||
.poll_put_char = serial8250_put_poll_char,
|
||||
#endif
|
||||
</programlisting>
|
||||
Any implementation specifics around creating a polling driver use the
|
||||
<constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
|
||||
Keep in mind that polling hooks have to be implemented in such a way
|
||||
that they can be called from an atomic context and have to restore
|
||||
the state of the UART chip on return such that the system can return
|
||||
to normal when the debugger detaches. You need to be very careful
|
||||
with any kind of lock you consider, because failing here is most likely
|
||||
going to mean pressing the reset button.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="kgdbocKbd">
|
||||
<title>kgdboc and keyboards</title>
|
||||
<para>The kgdboc driver contains logic to configure communications
|
||||
with an attached keyboard. The keyboard infrastructure is only
|
||||
compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the
|
||||
kernel configuration.</para>
|
||||
<para>The core polled keyboard driver driver for PS/2 type keyboards
|
||||
is in drivers/char/kdb_keyboard.c. This driver is hooked into the
|
||||
debug core when kgdboc populates the callback in the array
|
||||
called <constant>kdb_poll_funcs[]</constant>. The
|
||||
kdb_get_kbd_char() is the top-level function which polls hardware
|
||||
for single character input.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="kgdbocKms">
|
||||
<title>kgdboc and kms</title>
|
||||
<para>The kgdboc driver contains logic to request the graphics
|
||||
display to switch to a text context when you are using
|
||||
"kgdboc=kms,kbd", provided that you have a video driver which has a
|
||||
frame buffer console and atomic kernel mode setting support.</para>
|
||||
<para>
|
||||
Every time the kernel
|
||||
debugger is entered it calls kgdboc_pre_exp_handler() which in turn
|
||||
calls con_debug_enter() in the virtual console layer. On resuming kernel
|
||||
execution, the kernel debugger calls kgdboc_post_exp_handler() which
|
||||
in turn calls con_debug_leave().</para>
|
||||
<para>Any video driver that wants to be compatible with the kernel
|
||||
debugger and the atomic kms callbacks must implement the
|
||||
mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations.
|
||||
For the fb_debug_enter and fb_debug_leave the option exists to use
|
||||
the generic drm fb helper functions or implement something custom for
|
||||
the hardware. The following example shows the initialization of the
|
||||
.mode_set_base_atomic operation in
|
||||
drivers/gpu/drm/i915/intel_display.c:
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
static const struct drm_crtc_helper_funcs intel_helper_funcs = {
|
||||
[...]
|
||||
.mode_set_base_atomic = intel_pipe_set_base_atomic,
|
||||
[...]
|
||||
};
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
</para>
|
||||
<para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in
|
||||
drivers/gpu/drm/i915/intel_fb.c:
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
static struct fb_ops intelfb_ops = {
|
||||
[...]
|
||||
.fb_debug_enter = drm_fb_helper_debug_enter,
|
||||
.fb_debug_leave = drm_fb_helper_debug_leave,
|
||||
[...]
|
||||
};
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
<chapter id="credits">
|
||||
<title>Credits</title>
|
||||
<para>
|
||||
The following people have contributed to this document:
|
||||
<orderedlist>
|
||||
<listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>
|
||||
<listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>
|
||||
</orderedlist>
|
||||
In March 2008 this document was completely rewritten by:
|
||||
<itemizedlist>
|
||||
<listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
|
||||
</itemizedlist>
|
||||
In Jan 2010 this document was updated to include kdb.
|
||||
<itemizedlist>
|
||||
<listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</chapter>
|
||||
</book>
|
||||
|
File diff suppressed because it is too large
Load Diff
|
@ -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 < 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>
|
|
@ -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>
|
File diff suppressed because it is too large
Load Diff
|
@ -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>
|
|
@ -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>
|
|
@ -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>
|
|
@ -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&m=115507374832500&w=2'>the
|
||||
original patch submission</ulink> for more details.
|
||||
</para>
|
||||
!Idrivers/scsi/scsi_netlink.c
|
||||
</sect2>
|
||||
<sect2 id="scsi_scan.c">
|
||||
<title>drivers/scsi/scsi_scan.c</title>
|
||||
<para>
|
||||
Scan a host to determine which (if any) devices are attached.
|
||||
|
||||
The general scanning/probing algorithm is as follows, exceptions are
|
||||
made to it depending on device specific flags, compilation options,
|
||||
and global variable (boot or module load time) settings.
|
||||
|
||||
A specific LUN is scanned via an INQUIRY command; if the LUN has a
|
||||
device attached, a scsi_device is allocated and setup for it.
|
||||
|
||||
For every id of every channel on the given host, start by scanning
|
||||
LUN 0. Skip hosts that don't respond at all to a scan of LUN 0.
|
||||
Otherwise, if LUN 0 has a device attached, allocate and setup a
|
||||
scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN,
|
||||
and scan all of the LUNs returned by the REPORT LUN; else,
|
||||
sequentially scan LUNs up until some maximum is reached, or a LUN is
|
||||
seen that cannot have a device attached to it.
|
||||
</para>
|
||||
!Idrivers/scsi/scsi_scan.c
|
||||
</sect2>
|
||||
<sect2 id="scsi_sysctl.c">
|
||||
<title>drivers/scsi/scsi_sysctl.c</title>
|
||||
<para>
|
||||
Set up the sysctl entry: "/dev/scsi/logging_level"
|
||||
(DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="scsi_sysfs.c">
|
||||
<title>drivers/scsi/scsi_sysfs.c</title>
|
||||
<para>
|
||||
SCSI sysfs interface routines.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_sysfs.c
|
||||
</sect2>
|
||||
<sect2 id="hosts.c">
|
||||
<title>drivers/scsi/hosts.c</title>
|
||||
<para>
|
||||
mid to lowlevel SCSI driver interface
|
||||
</para>
|
||||
!Edrivers/scsi/hosts.c
|
||||
</sect2>
|
||||
<sect2 id="constants.c">
|
||||
<title>drivers/scsi/constants.c</title>
|
||||
<para>
|
||||
mid to lowlevel SCSI driver interface
|
||||
</para>
|
||||
!Edrivers/scsi/constants.c
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="Transport_classes">
|
||||
<title>Transport classes</title>
|
||||
<para>
|
||||
Transport classes are service libraries for drivers in the SCSI
|
||||
lower layer, which expose transport attributes in sysfs.
|
||||
</para>
|
||||
<sect2 id="Fibre_Channel_transport">
|
||||
<title>Fibre Channel transport</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_transport_fc.c defines transport attributes
|
||||
for Fibre Channel.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_transport_fc.c
|
||||
</sect2>
|
||||
<sect2 id="iSCSI_transport">
|
||||
<title>iSCSI transport class</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_transport_iscsi.c defines transport
|
||||
attributes for the iSCSI class, which sends SCSI packets over TCP/IP
|
||||
connections.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_transport_iscsi.c
|
||||
</sect2>
|
||||
<sect2 id="SAS_transport">
|
||||
<title>Serial Attached SCSI (SAS) transport class</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_transport_sas.c defines transport
|
||||
attributes for Serial Attached SCSI, a variant of SATA aimed at
|
||||
large high-end systems.
|
||||
</para>
|
||||
<para>
|
||||
The SAS transport class contains common code to deal with SAS HBAs,
|
||||
an aproximated representation of SAS topologies in the driver model,
|
||||
and various sysfs attributes to expose these topologies and management
|
||||
interfaces to userspace.
|
||||
</para>
|
||||
<para>
|
||||
In addition to the basic SCSI core objects this transport class
|
||||
introduces two additional intermediate objects: The SAS PHY
|
||||
as represented by struct sas_phy defines an "outgoing" PHY on
|
||||
a SAS HBA or Expander, and the SAS remote PHY represented by
|
||||
struct sas_rphy defines an "incoming" PHY on a SAS Expander or
|
||||
end device. Note that this is purely a software concept, the
|
||||
underlying hardware for a PHY and a remote PHY is the exactly
|
||||
the same.
|
||||
</para>
|
||||
<para>
|
||||
There is no concept of a SAS port in this code, users can see
|
||||
what PHYs form a wide port based on the port_identifier attribute,
|
||||
which is the same for all PHYs in a port.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_transport_sas.c
|
||||
</sect2>
|
||||
<sect2 id="SATA_transport">
|
||||
<title>SATA transport class</title>
|
||||
<para>
|
||||
The SATA transport is handled by libata, which has its own book of
|
||||
documentation in this directory.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="SPI_transport">
|
||||
<title>Parallel SCSI (SPI) transport class</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_transport_spi.c defines transport
|
||||
attributes for traditional (fast/wide/ultra) SCSI busses.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_transport_spi.c
|
||||
</sect2>
|
||||
<sect2 id="SRP_transport">
|
||||
<title>SCSI RDMA (SRP) transport class</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_transport_srp.c defines transport
|
||||
attributes for SCSI over Remote Direct Memory Access.
|
||||
</para>
|
||||
!Edrivers/scsi/scsi_transport_srp.c
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
</chapter>
|
||||
|
||||
<chapter id="lower_layer">
|
||||
<title>SCSI lower layer</title>
|
||||
<sect1 id="hba_drivers">
|
||||
<title>Host Bus Adapter transport types</title>
|
||||
<para>
|
||||
Many modern device controllers use the SCSI command set as a protocol to
|
||||
communicate with their devices through many different types of physical
|
||||
connections.
|
||||
</para>
|
||||
<para>
|
||||
In SCSI language a bus capable of carrying SCSI commands is
|
||||
called a "transport", and a controller connecting to such a bus is
|
||||
called a "host bus adapter" (HBA).
|
||||
</para>
|
||||
<sect2 id="scsi_debug.c">
|
||||
<title>Debug transport</title>
|
||||
<para>
|
||||
The file drivers/scsi/scsi_debug.c simulates a host adapter with a
|
||||
variable number of disks (or disk like devices) attached, sharing a
|
||||
common amount of RAM. Does a lot of checking to make sure that we are
|
||||
not getting blocks mixed up, and panics the kernel if anything out of
|
||||
the ordinary is seen.
|
||||
</para>
|
||||
<para>
|
||||
To be more realistic, the simulated devices have the transport
|
||||
attributes of SAS disks.
|
||||
</para>
|
||||
<para>
|
||||
For documentation see
|
||||
<ulink url='http://sg.danny.cz/sg/sdebug26.html'>http://sg.danny.cz/sg/sdebug26.html</ulink>
|
||||
</para>
|
||||
<!-- !Edrivers/scsi/scsi_debug.c -->
|
||||
</sect2>
|
||||
<sect2 id="todo">
|
||||
<title>todo</title>
|
||||
<para>Parallel (fast/wide/ultra) SCSI, USB, SATA,
|
||||
SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband,
|
||||
I20, iSCSI, Parallel ports, netlink...
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
</book>
|
|
@ -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>
|
|
@ -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>
|
|
@ -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>
|
|
@ -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 &z8530_nop to start the chip up
|
||||
as disabled and discarding interrupt events. This ensures that
|
||||
stray interrupts will be mopped up and not hang the bus. Set
|
||||
chanA.dev to point to the device structure itself. The
|
||||
private and name field you may use as you wish. The private field
|
||||
is unused by the Z85230 layer. The name is used for error reporting
|
||||
and it may thus make sense to make it match the network name.
|
||||
</para>
|
||||
<para>
|
||||
Repeat the same operation with the B channel if your chip has
|
||||
both channels wired to something useful. This isn't always the
|
||||
case. If it is not wired then the I/O values do not matter, but
|
||||
you must initialise chanB.dev.
|
||||
</para>
|
||||
<para>
|
||||
If your board has DMA facilities then initialise the txdma and
|
||||
rxdma fields for the relevant channels. You must also allocate the
|
||||
ISA DMA channels and do any necessary board level initialisation
|
||||
to configure them. The low level driver will do the Z8530 and
|
||||
DMA controller programming but not board specific magic.
|
||||
</para>
|
||||
<para>
|
||||
Having initialised the device you can then call
|
||||
<function>z8530_init</function>. This will probe the chip and
|
||||
reset it into a known state. An identification sequence is then
|
||||
run to identify the chip type. If the checks fail to pass the
|
||||
function returns a non zero error code. Typically this indicates
|
||||
that the port given is not valid. After this call the
|
||||
type field of the z8530_dev structure is initialised to either
|
||||
Z8530, Z85C30 or Z85230 according to the chip found.
|
||||
</para>
|
||||
<para>
|
||||
Once you have called z8530_init you can also make use of the utility
|
||||
function <function>z8530_describe</function>. This provides a
|
||||
consistent reporting format for the Z8530 devices, and allows all
|
||||
the drivers to provide consistent reporting.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="Attaching_Network_Interfaces">
|
||||
<title>Attaching Network Interfaces</title>
|
||||
<para>
|
||||
If you wish to use the network interface facilities of the driver,
|
||||
then you need to attach a network device to each channel that is
|
||||
present and in use. In addition to use the generic HDLC
|
||||
you need to follow some additional plumbing rules. They may seem
|
||||
complex but a look at the example hostess_sv11 driver should
|
||||
reassure you.
|
||||
</para>
|
||||
<para>
|
||||
The network device used for each channel should be pointed to by
|
||||
the netdevice field of each channel. The hdlc-> priv field of the
|
||||
network device points to your private data - you will need to be
|
||||
able to find your private data from this.
|
||||
</para>
|
||||
<para>
|
||||
The way most drivers approach this particular problem is to
|
||||
create a structure holding the Z8530 device definition and
|
||||
put that into the private field of the network device. The
|
||||
network device fields of the channels then point back to the
|
||||
network devices.
|
||||
</para>
|
||||
<para>
|
||||
If you wish to use the generic HDLC then you need to register
|
||||
the HDLC device.
|
||||
</para>
|
||||
<para>
|
||||
Before you register your network device you will also need to
|
||||
provide suitable handlers for most of the network device callbacks.
|
||||
See the network device documentation for more details on this.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="Configuring_And_Activating_The_Port">
|
||||
<title>Configuring And Activating The Port</title>
|
||||
<para>
|
||||
The Z85230 driver provides helper functions and tables to load the
|
||||
port registers on the Z8530 chips. When programming the register
|
||||
settings for a channel be aware that the documentation recommends
|
||||
initialisation orders. Strange things happen when these are not
|
||||
followed.
|
||||
</para>
|
||||
<para>
|
||||
<function>z8530_channel_load</function> takes an array of
|
||||
pairs of initialisation values in an array of u8 type. The first
|
||||
value is the Z8530 register number. Add 16 to indicate the alternate
|
||||
register bank on the later chips. The array is terminated by a 255.
|
||||
</para>
|
||||
<para>
|
||||
The driver provides a pair of public tables. The
|
||||
z8530_hdlc_kilostream table is for the UK 'Kilostream' service and
|
||||
also happens to cover most other end host configurations. The
|
||||
z8530_hdlc_kilostream_85230 table is the same configuration using
|
||||
the enhancements of the 85230 chip. The configuration loaded is
|
||||
standard NRZ encoded synchronous data with HDLC bitstuffing. All
|
||||
of the timing is taken from the other end of the link.
|
||||
</para>
|
||||
<para>
|
||||
When writing your own tables be aware that the driver internally
|
||||
tracks register values. It may need to reload values. You should
|
||||
therefore be sure to set registers 1-7, 9-11, 14 and 15 in all
|
||||
configurations. Where the register settings depend on DMA selection
|
||||
the driver will update the bits itself when you open or close.
|
||||
Loading a new table with the interface open is not recommended.
|
||||
</para>
|
||||
<para>
|
||||
There are three standard configurations supported by the core
|
||||
code. In PIO mode the interface is programmed up to use
|
||||
interrupt driven PIO. This places high demands on the host processor
|
||||
to avoid latency. The driver is written to take account of latency
|
||||
issues but it cannot avoid latencies caused by other drivers,
|
||||
notably IDE in PIO mode. Because the drivers allocate buffers you
|
||||
must also prevent MTU changes while the port is open.
|
||||
</para>
|
||||
<para>
|
||||
Once the port is open it will call the rx_function of each channel
|
||||
whenever a completed packet arrived. This is invoked from
|
||||
interrupt context and passes you the channel and a network
|
||||
buffer (struct sk_buff) holding the data. The data includes
|
||||
the CRC bytes so most users will want to trim the last two
|
||||
bytes before processing the data. This function is very timing
|
||||
critical. When you wish to simply discard data the support
|
||||
code provides the function <function>z8530_null_rx</function>
|
||||
to discard the data.
|
||||
</para>
|
||||
<para>
|
||||
To active PIO mode sending and receiving the <function>
|
||||
z8530_sync_open</function> is called. This expects to be passed
|
||||
the network device and the channel. Typically this is called from
|
||||
your network device open callback. On a failure a non zero error
|
||||
status is returned. The <function>z8530_sync_close</function>
|
||||
function shuts down a PIO channel. This must be done before the
|
||||
channel is opened again and before the driver shuts down
|
||||
and unloads.
|
||||
</para>
|
||||
<para>
|
||||
The ideal mode of operation is dual channel DMA mode. Here the
|
||||
kernel driver will configure the board for DMA in both directions.
|
||||
The driver also handles ISA DMA issues such as controller
|
||||
programming and the memory range limit for you. This mode is
|
||||
activated by calling the <function>z8530_sync_dma_open</function>
|
||||
function. On failure a non zero error value is returned.
|
||||
Once this mode is activated it can be shut down by calling the
|
||||
<function>z8530_sync_dma_close</function>. You must call the close
|
||||
function matching the open mode you used.
|
||||
</para>
|
||||
<para>
|
||||
The final supported mode uses a single DMA channel to drive the
|
||||
transmit side. As the Z85C30 has a larger FIFO on the receive
|
||||
channel this tends to increase the maximum speed a little.
|
||||
This is activated by calling the <function>z8530_sync_txdma_open
|
||||
</function>. This returns a non zero error code on failure. The
|
||||
<function>z8530_sync_txdma_close</function> function closes down
|
||||
the Z8530 interface from this mode.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="Network_Layer_Functions">
|
||||
<title>Network Layer Functions</title>
|
||||
<para>
|
||||
The Z8530 layer provides functions to queue packets for
|
||||
transmission. The driver internally buffers the frame currently
|
||||
being transmitted and one further frame (in order to keep back
|
||||
to back transmission running). Any further buffering is up to
|
||||
the caller.
|
||||
</para>
|
||||
<para>
|
||||
The function <function>z8530_queue_xmit</function> takes a network
|
||||
buffer in sk_buff format and queues it for transmission. The
|
||||
caller must provide the entire packet with the exception of the
|
||||
bitstuffing and CRC. This is normally done by the caller via
|
||||
the generic HDLC interface layer. It returns 0 if the buffer has been
|
||||
queued and non zero values for queue full. If the function accepts
|
||||
the buffer it becomes property of the Z8530 layer and the caller
|
||||
should not free it.
|
||||
</para>
|
||||
<para>
|
||||
The function <function>z8530_get_stats</function> returns a pointer
|
||||
to an internally maintained per interface statistics block. This
|
||||
provides most of the interface code needed to implement the network
|
||||
layer get_stats callback.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="Porting_The_Z8530_Driver">
|
||||
<title>Porting The Z8530 Driver</title>
|
||||
<para>
|
||||
The Z8530 driver is written to be portable. In DMA mode it makes
|
||||
assumptions about the use of ISA DMA. These are probably warranted
|
||||
in most cases as the Z85230 in particular was designed to glue to PC
|
||||
type machines. The PIO mode makes no real assumptions.
|
||||
</para>
|
||||
<para>
|
||||
Should you need to retarget the Z8530 driver to another architecture
|
||||
the only code that should need changing are the port I/O functions.
|
||||
At the moment these assume PC I/O port accesses. This may not be
|
||||
appropriate for all platforms. Replacing
|
||||
<function>z8530_read_port</function> and <function>z8530_write_port
|
||||
</function> is intended to be all that is required to port this
|
||||
driver layer.
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="bugs">
|
||||
<title>Known Bugs And Assumptions</title>
|
||||
<para>
|
||||
<variablelist>
|
||||
<varlistentry><term>Interrupt Locking</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The locking in the driver is done via the global cli/sti lock. This
|
||||
makes for relatively poor SMP performance. Switching this to use a
|
||||
per device spin lock would probably materially improve performance.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
|
||||
<varlistentry><term>Occasional Failures</term>
|
||||
<listitem>
|
||||
<para>
|
||||
We have reports of occasional failures when run for very long
|
||||
periods of time and the driver starts to receive junk frames. At
|
||||
the moment the cause of this is not clear.
|
||||
</para>
|
||||
</listitem></varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
<chapter id="pubfunctions">
|
||||
<title>Public Functions Provided</title>
|
||||
!Edrivers/net/wan/z85230.c
|
||||
</chapter>
|
||||
|
||||
<chapter id="intfunctions">
|
||||
<title>Internal Functions</title>
|
||||
!Idrivers/net/wan/z85230.c
|
||||
</chapter>
|
||||
|
||||
</book>
|
|
@ -1 +1,126 @@
|
|||
# -*- makefile -*-
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
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.'
|
||||
|
|
|
@ -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.'
|
|
@ -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
|
||||
acquire the spinlock. Such deadlocks can be avoided by using
|
||||
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
|
||||
and acquire the lock (see Documentation/DocBook/kernel-locking).
|
||||
and acquire the lock (see Documentation/kernel-hacking/locking.rst).
|
||||
|
||||
4.5 How to tell whether MSI/MSI-X is enabled on a device
|
||||
|
||||
|
|
|
@ -55,12 +55,6 @@ Documentation
|
|||
contains information about the problems, which may result by upgrading
|
||||
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
|
||||
----------------------------
|
||||
|
||||
|
|
|
@ -281,6 +281,7 @@ latex_elements = {
|
|||
\\definecolor{NoteColor}{RGB}{204,255,255}
|
||||
\\definecolor{WarningColor}{RGB}{255,204,204}
|
||||
\\definecolor{AttentionColor}{RGB}{255,255,204}
|
||||
\\definecolor{ImportantColor}{RGB}{192,255,204}
|
||||
\\definecolor{OtherColor}{RGB}{204,204,204}
|
||||
\\newlength{\\mynoticelength}
|
||||
\\makeatletter\\newenvironment{coloredbox}[1]{%
|
||||
|
@ -301,7 +302,12 @@ latex_elements = {
|
|||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{attention}}%
|
||||
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
|
||||
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
|
||||
{%
|
||||
\\ifthenelse%
|
||||
{\\equal{\\py@noticetype}{important}}%
|
||||
{\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
|
||||
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
|
||||
}%
|
||||
}%
|
||||
}%
|
||||
}\\makeatother
|
||||
|
@ -339,27 +345,42 @@ if major == 1 and minor > 3:
|
|||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
# Sorted in alphabetical order
|
||||
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',
|
||||
'The kernel development community', 'manual'),
|
||||
('core-api/index', 'core-api.tex', 'The kernel core API 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',
|
||||
'The kernel development community', 'manual'),
|
||||
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
|
||||
'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',
|
||||
('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
|
||||
'The kernel development community', 'manual'),
|
||||
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
|
||||
'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',
|
||||
'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',
|
||||
'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
|
||||
|
|
|
@ -19,6 +19,7 @@ Core utilities
|
|||
workqueue
|
||||
genericirq
|
||||
flexible-arrays
|
||||
librs
|
||||
|
||||
Interfaces for kernel debugging
|
||||
===============================
|
||||
|
|
|
@ -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
|
|
@ -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'),
|
||||
]
|
|
@ -23,6 +23,7 @@ whole; patches welcome!
|
|||
kmemleak
|
||||
kmemcheck
|
||||
gdb-kernel-debugging
|
||||
kgdb
|
||||
|
||||
|
||||
.. only:: subproject and html
|
||||
|
|
|
@ -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>
|
|
@ -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.
|
|
@ -10,7 +10,6 @@ How to write kernel documentation
|
|||
sphinx.rst
|
||||
kernel-doc.rst
|
||||
parse-headers.rst
|
||||
docbook.rst
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
|
|
@ -149,6 +149,16 @@ Domain`_ references.
|
|||
``%CONST``
|
||||
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``
|
||||
Name of an environment variable. (No cross-referencing, just formatting.)
|
||||
|
||||
|
|
|
@ -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
|
||||
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
|
||||
``Documentation``. Some of these will likely be converted to reStructuredText
|
||||
over time, but the bulk of them will remain in plain text.
|
||||
|
|
|
@ -32,7 +32,13 @@ available subsections can be seen below.
|
|||
i2c
|
||||
hsi
|
||||
edac
|
||||
scsi
|
||||
libata
|
||||
mtdnand
|
||||
miscellaneous
|
||||
w1
|
||||
rapidio
|
||||
s390-drivers
|
||||
vme
|
||||
80211/index
|
||||
uio-howto
|
||||
|
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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
|
|
@ -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:
|
|
@ -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...
|
|
@ -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:
|
|
@ -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
|
||||
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
|
||||
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.
|
||||
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
|
||||
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.
|
||||
For forward compatibility reasons applications must zero those fields, and
|
||||
|
|
|
@ -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'),
|
||||
]
|
|
@ -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
|
|
@ -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
|
||||
files to better group them and improving the interfaces like dropping return
|
||||
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.
|
||||
|
||||
|
|
|
@ -51,6 +51,7 @@ merged much easier.
|
|||
process/index
|
||||
dev-tools/index
|
||||
doc-guide/index
|
||||
kernel-hacking/index
|
||||
|
||||
Kernel API documentation
|
||||
------------------------
|
||||
|
@ -67,11 +68,24 @@ needed).
|
|||
driver-api/index
|
||||
core-api/index
|
||||
media/index
|
||||
networking/index
|
||||
input/index
|
||||
gpu/index
|
||||
security/index
|
||||
sound/index
|
||||
crypto/index
|
||||
filesystems/index
|
||||
|
||||
Architecture-specific documentation
|
||||
-----------------------------------
|
||||
|
||||
These books provide programming details about architecture-specific
|
||||
implementation.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
sh/index
|
||||
|
||||
Korean translations
|
||||
-------------------
|
||||
|
|
|
@ -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.
|
||||
|
||||
This style embeds the documentation within the source files, using
|
||||
a few simple conventions. The scripts/kernel-doc perl script, some
|
||||
SGML templates in Documentation/DocBook, and other tools understand
|
||||
a few simple conventions. The scripts/kernel-doc perl script, the
|
||||
Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
|
||||
these conventions, and are used to extract this embedded documentation
|
||||
into various documents.
|
||||
|
||||
|
@ -122,15 +122,9 @@ are:
|
|||
- scripts/kernel-doc
|
||||
|
||||
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.)
|
||||
|
||||
- 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
|
||||
|
||||
This is a program for converting SGML template files into SGML
|
||||
|
@ -145,25 +139,18 @@ are:
|
|||
|
||||
- Makefile
|
||||
|
||||
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
|
||||
to build XML DocBook 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.
|
||||
|
||||
The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
|
||||
are used to build XML DocBook files, LaTeX files, PDF files,
|
||||
ePub files and html files in Documentation/.
|
||||
|
||||
How to extract the documentation
|
||||
--------------------------------
|
||||
|
||||
If you just want to read the ready-made books on the various
|
||||
subsystems (see Documentation/DocBook/*.tmpl), just type 'make
|
||||
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
|
||||
preference. If you would rather read a different format, you can type
|
||||
'make xmldocs' and then use DocBook tools to convert
|
||||
Documentation/DocBook/*.xml to a format of your choice (for example,
|
||||
subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
|
||||
depending on your preference. If you would rather read a different format,
|
||||
you can type 'make xmldocs' and then use DocBook tools to convert
|
||||
Documentation/output/*.xml to a format of your choice (for example,
|
||||
'db2html ...' if 'make htmldocs' was not defined).
|
||||
|
||||
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).
|
||||
*/
|
||||
|
||||
DOC: sections are used in SGML templates files as indicated below.
|
||||
|
||||
|
||||
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.
|
||||
DOC: sections are used in ReST files.
|
||||
|
||||
Tim.
|
||||
*/ <twaugh@redhat.com>
|
||||
|
|
|
@ -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'),
|
||||
]
|
|
@ -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.
|
|
@ -0,0 +1,9 @@
|
|||
=====================
|
||||
Kernel Hacking Guides
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
hacking
|
||||
locking
|
File diff suppressed because it is too large
Load Diff
|
@ -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()`
|
|
@ -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'),
|
||||
]
|
|
@ -0,0 +1,18 @@
|
|||
Linux Networking Documentation
|
||||
==============================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
kapi
|
||||
z8530book
|
||||
|
||||
.. only:: subproject
|
||||
|
||||
Indices
|
||||
=======
|
||||
|
||||
* :ref:`genindex`
|
||||
|
|
@ -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:
|
|
@ -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:
|
|
@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
|
|||
|
||||
Linux documentation for functions is transitioning to inline
|
||||
documentation via specially-formatted comments near their
|
||||
definitions in the source. These comments can be combined with the
|
||||
SGML templates in the Documentation/DocBook directory to make DocBook
|
||||
files, which can then be converted by DocBook stylesheets to PostScript,
|
||||
HTML, PDF files, and several other formats. In order to convert from
|
||||
DocBook format to a format of your choice, you'll need to install Jade as
|
||||
well as the desired DocBook stylesheets.
|
||||
definitions in the source. These comments can be combined with ReST
|
||||
files the Documentation/ directory to make enriched documentation, which can
|
||||
then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
|
||||
In order to convert from ReST format to a format of your choice, you'll need
|
||||
Sphinx.
|
||||
|
||||
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
|
||||
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
|
||||
========================
|
||||
|
@ -409,15 +402,6 @@ Quota-tools
|
|||
|
||||
- <http://sourceforge.net/projects/linuxquota/>
|
||||
|
||||
DocBook Stylesheets
|
||||
-------------------
|
||||
|
||||
- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
|
||||
|
||||
XMLTO XSLT Frontend
|
||||
-------------------
|
||||
|
||||
- <http://cyberelk.net/tim/xmlto/>
|
||||
|
||||
Intel P6 microcode
|
||||
------------------
|
||||
|
|
|
@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
|
|||
make latexdocs
|
||||
make epubdocs
|
||||
|
||||
Currently, there are some documents written on DocBook that are in
|
||||
the process of conversion to ReST. Such documents will be created in the
|
||||
Documentation/DocBook/ directory and can be generated also as
|
||||
Postscript or man pages by running::
|
||||
|
||||
make psdocs
|
||||
make mandocs
|
||||
|
||||
Becoming A Kernel Developer
|
||||
---------------------------
|
||||
|
||||
|
|
|
@ -40,50 +40,18 @@ Enjoy!
|
|||
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}``.
|
||||
|
||||
* Name: **linux/Documentation**
|
||||
|
||||
:Author: Many.
|
||||
:Location: Documentation/
|
||||
:Keywords: text files, Sphinx, DocBook.
|
||||
:Keywords: text files, Sphinx.
|
||||
:Description: Documentation that comes with the kernel sources,
|
||||
inside the Documentation directory. Some pages from this document
|
||||
(including this document itself) have been moved there, and might
|
||||
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
|
||||
------------
|
||||
|
||||
|
|
|
@ -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'),
|
||||
]
|
|
@ -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:
|
|
@ -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'),
|
||||
]
|
|
@ -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"
|
|
@ -197,13 +197,6 @@ ReSTマークアップを使ったドキュメントは Documentation/outputに
|
|||
make latexdocs
|
||||
make epubdocs
|
||||
|
||||
現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
|
||||
す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
|
||||
Postscript または man ページの形式を生成するには以下のようにします - ::
|
||||
|
||||
make psdocs
|
||||
make mandocs
|
||||
|
||||
カーネル開発者になるには
|
||||
------------------------
|
||||
|
||||
|
|
|
@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
|
|||
make latexdocs
|
||||
make epubdocs
|
||||
|
||||
현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
|
||||
문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
|
||||
Postscript 나 man page 로도 만들어질 수 있다::
|
||||
|
||||
make psdocs
|
||||
make mandocs
|
||||
|
||||
커널 개발자가 되는 것
|
||||
---------------------
|
||||
|
||||
|
|
|
@ -3579,7 +3579,6 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/herbert/crypto-2.6.git
|
|||
S: Maintained
|
||||
F: Documentation/crypto/
|
||||
F: Documentation/devicetree/bindings/crypto/
|
||||
F: Documentation/DocBook/crypto-API.tmpl
|
||||
F: arch/*/crypto/
|
||||
F: crypto/
|
||||
F: drivers/crypto/
|
||||
|
@ -7377,7 +7376,7 @@ W: http://kgdb.wiki.kernel.org/
|
|||
L: kgdb-bugreport@lists.sourceforge.net
|
||||
T: git git://git.kernel.org/pub/scm/linux/kernel/git/jwessel/kgdb.git
|
||||
S: Maintained
|
||||
F: Documentation/DocBook/kgdb.tmpl
|
||||
F: Documentation/dev-tools/kgdb.rst
|
||||
F: drivers/misc/kgdbts.c
|
||||
F: drivers/tty/serial/kgdboc.c
|
||||
F: include/linux/kdb.h
|
||||
|
@ -10990,7 +10989,7 @@ S: Supported
|
|||
F: arch/s390/
|
||||
F: drivers/s390/
|
||||
F: Documentation/s390/
|
||||
F: Documentation/DocBook/s390*
|
||||
F: Documentation/driver-api/s390-drivers.rst
|
||||
|
||||
S390 COMMON I/O LAYER
|
||||
M: Sebastian Ott <sebott@linux.vnet.ibm.com>
|
||||
|
|
11
Makefile
11
Makefile
|
@ -1312,7 +1312,7 @@ clean: archclean vmlinuxclean
|
|||
#
|
||||
mrproper: rm-dirs := $(wildcard $(MRPROPER_DIRS))
|
||||
mrproper: rm-files := $(wildcard $(MRPROPER_FILES))
|
||||
mrproper-dirs := $(addprefix _mrproper_,Documentation/DocBook scripts)
|
||||
mrproper-dirs := $(addprefix _mrproper_,scripts)
|
||||
|
||||
PHONY += $(mrproper-dirs) mrproper archmrproper
|
||||
$(mrproper-dirs):
|
||||
|
@ -1416,9 +1416,7 @@ help:
|
|||
@$(MAKE) $(build)=$(package-dir) help
|
||||
@echo ''
|
||||
@echo 'Documentation targets:'
|
||||
@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
|
||||
@echo ''
|
||||
@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
|
||||
@$(MAKE) -f $(srctree)/Documentation/Makefile dochelp
|
||||
@echo ''
|
||||
@echo 'Architecture specific targets ($(SRCARCH)):'
|
||||
@$(if $(archhelp),$(archhelp),\
|
||||
|
@ -1469,9 +1467,8 @@ $(help-board-dirs): help-%:
|
|||
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
|
||||
PHONY += $(DOC_TARGETS)
|
||||
$(DOC_TARGETS): scripts_basic FORCE
|
||||
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
|
||||
$(Q)$(MAKE) $(build)=Documentation -f $(srctree)/Documentation/Makefile.sphinx $@
|
||||
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
|
||||
$(Q)$(MAKE) $(build)=scripts build_docproc
|
||||
$(Q)$(MAKE) $(build)=Documentation $@
|
||||
|
||||
else # KBUILD_EXTMOD
|
||||
|
||||
|
|
|
@ -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
|
||||
* 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)
|
||||
{
|
||||
|
|
|
@ -63,7 +63,7 @@ EXPORT_SYMBOL(sn_io_addr);
|
|||
/**
|
||||
* __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.
|
||||
*
|
||||
* On SN2, we wait for the PIO_WRITE_STATUS SHub register to clear.
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* AHCI hardware documentation:
|
||||
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
|
||||
|
|
|
@ -24,7 +24,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* AHCI hardware documentation:
|
||||
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
|
||||
|
|
|
@ -24,7 +24,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* AHCI hardware documentation:
|
||||
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
|
||||
|
|
|
@ -33,7 +33,7 @@
|
|||
*
|
||||
*
|
||||
* 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/
|
||||
*
|
||||
|
|
|
@ -24,7 +24,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* AHCI hardware documentation:
|
||||
* http://www.intel.com/technology/serialata/pdf/rev1_0.pdf
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* 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
|
||||
* http://www.sata-io.org/
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* 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
|
||||
* http://www.sata-io.org/
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* 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.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
|
||||
* an SCT Write Same command.
|
||||
* Based on WRITE SAME has the UNMAP flag
|
||||
* When set translate to DSM TRIM
|
||||
* When clear translate to SCT Write Same
|
||||
* Based on WRITE SAME has the UNMAP flag:
|
||||
*
|
||||
* - 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)
|
||||
{
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* 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
|
||||
* http://www.sata-io.org/
|
||||
|
|
|
@ -21,7 +21,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
|
@ -17,7 +17,7 @@
|
|||
*
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
|
|
|
@ -21,7 +21,7 @@
|
|||
*
|
||||
*
|
||||
* 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.
|
||||
|
|
|
@ -21,7 +21,7 @@
|
|||
*
|
||||
*
|
||||
* 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.
|
||||
* This driver programs the NVIDIA SATA controller in a similar
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
|
|
|
@ -20,7 +20,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
|
@ -23,7 +23,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Documentation for SiI 3112:
|
||||
* http://gkernel.sourceforge.net/specs/sii/3112A_SiI-DS-0095-B2.pdf.bz2
|
||||
|
|
|
@ -24,7 +24,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Hardware documentation available under NDA.
|
||||
*
|
||||
|
|
|
@ -30,7 +30,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Hardware documentation available under NDA.
|
||||
*
|
||||
|
|
|
@ -24,7 +24,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Hardware documentation available under NDA.
|
||||
*
|
||||
|
|
|
@ -18,7 +18,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Hardware documentation available under NDA.
|
||||
*
|
||||
|
|
|
@ -25,7 +25,7 @@
|
|||
*
|
||||
*
|
||||
* libata documentation is available via 'make {ps|pdf}docs',
|
||||
* as Documentation/DocBook/libata.*
|
||||
* as Documentation/driver-api/libata.rst
|
||||
*
|
||||
* Hardware documentation available under NDA.
|
||||
*
|
||||
|
|
|
@ -26,7 +26,7 @@
|
|||
*
|
||||
*
|
||||
* 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.
|
||||
* Intel 31244 (same hardware interface) documentation presumably
|
||||
|
|
|
@ -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).
|
||||
*
|
||||
* We try operations in the following order:
|
||||
*
|
||||
* (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
|
||||
* NAND_BBT_NO_OOB_BBM is present)
|
||||
* (3) update the BBT
|
||||
*
|
||||
* Note that we retain the first error encountered in (2) or (3), finish the
|
||||
* procedures, and dump the error in the end.
|
||||
*/
|
||||
|
@ -1219,9 +1221,10 @@ int nand_reset(struct nand_chip *chip, int chipnr)
|
|||
* @mtd: mtd info
|
||||
* @ofs: offset to start unlock from
|
||||
* @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
|
||||
* 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
|
||||
*
|
||||
* Returs unlock status.
|
||||
|
|
|
@ -377,6 +377,7 @@ static void phy_sanitize_settings(struct phy_device *phydev)
|
|||
* @cmd: ethtool_cmd
|
||||
*
|
||||
* A few notes about parameter checking:
|
||||
*
|
||||
* - We don't set port or transceiver, so we don't care what they
|
||||
* were set to.
|
||||
* - phy_start_aneg() will make sure forced settings are sane, and
|
||||
|
|
|
@ -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,
|
||||
* causing chip to issue full queue of stale commands
|
||||
* 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(®->mailbox4, ha->req_ring_index);
|
||||
mmiowb();
|
||||
|
|
|
@ -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.
|
||||
*
|
||||
* 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
|
||||
* 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,
|
||||
u64 lun, int *bflagsp,
|
||||
|
|
|
@ -2914,16 +2914,18 @@ EXPORT_SYMBOL(fc_remote_port_add);
|
|||
* 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
|
||||
* 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.
|
||||
* This allows the port to temporarily disappear, then reappear without
|
||||
* disrupting the SCSI device tree attached to it. During the "blocked"
|
||||
* period the port will still exist.
|
||||
* This allows the port to temporarily disappear, then reappear without
|
||||
* disrupting the SCSI device tree attached to it. During the "blocked"
|
||||
* period the port will still exist.
|
||||
*
|
||||
* 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
|
||||
* attached to it. However, we want to semi-persist the target id assigned
|
||||
* to that port if it eventually does exist. The port structure will
|
||||
* remain (although with minimal information) so that the target id
|
||||
* bindings remails.
|
||||
* 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
|
||||
* to that port if it eventually does exist. The port structure will
|
||||
* remain (although with minimal information) so that the target id
|
||||
* bindings remails.
|
||||
*
|
||||
* If the remote port is not an FCP Target, it will be fully torn down
|
||||
* and deallocated, including the fc_remote_port class device.
|
||||
|
|
|
@ -116,8 +116,8 @@ EXPORT_SYMBOL(scsicam_bios_param);
|
|||
* @hds: put heads here
|
||||
* @secs: put sectors here
|
||||
*
|
||||
* Description: determine the BIOS mapping/geometry used to create the partition
|
||||
* table, storing the results in *cyls, *hds, and *secs
|
||||
* Determine the BIOS mapping/geometry used to create the partition
|
||||
* table, storing the results in @cyls, @hds, and @secs
|
||||
*
|
||||
* Returns: -1 on failure, 0 on success.
|
||||
*/
|
||||
|
|
|
@ -41,7 +41,7 @@ menuconfig USB_GADGET
|
|||
don't have this kind of hardware (except maybe inside Linux PDAs).
|
||||
|
||||
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
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@
|
|||
* 2 as published by the Free Software Foundation.
|
||||
*
|
||||
* debugfs is for people to use instead of /proc or /sys.
|
||||
* See Documentation/DocBook/filesystems for more details.
|
||||
* See Documentation/filesystems/ for more details.
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
|
@ -9,7 +9,7 @@
|
|||
* 2 as published by the Free Software Foundation.
|
||||
*
|
||||
* 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
Loading…
Reference in New Issue