There has been a fair amount of activity in the docs tree this time
around. Highlights include: - Conversion of a bunch of security documentation into RST - The conversion of the remaining DocBook templates by The Amazing Mauro Machine. We can now drop the entire DocBook build chain. - The usual collection of fixes and minor updates. -----BEGIN PGP SIGNATURE----- iQIcBAABAgAGBQJZWkGAAAoJEI3ONVYwIuV6rf0P/0B3JTiVPKS/WUx53+jzbAi4 1BN7dmmuMxE1bWpgdEq+ac4aKxm07iAojuntuMj0qz/ZB1WARcmvEqqzI5i4wfq9 5MrLduLkyuWfr4MOPseKJ2VK83p8nkMOiO7jmnBsilu7fE4nF+5YY9j4cVaArfMy cCQvAGjQzvej2eiWMGUSLHn4QFKh00aD7cwKyBVsJ08b27C9xL0J2LQyCDZ4yDgf 37/MH3puEd3HX/4qAwLonIxT3xrIrrbDturqLU7OSKcWTtGZNrYyTFbwR3RQtqWd H8YZVg2Uyhzg9MYhkbQ2E5dEjUP4mkegcp6/JTINH++OOPpTbdTJgirTx7VTkSf1 +kL8t7+Ayxd0FH3+77GJ5RMj8LUK6rj5cZfU5nClFQKWXP9UL3IelQ3Nl+SpdM8v ZAbR2KjKgH9KS6+cbIhgFYlvY+JgPkOVruwbIAc7wXVM3ibk1sWoBOFEujcbueWh yDpQv3l1UX0CKr3jnevJoW26LtEbGFtC7gSKZ+3btyeSBpWFGlii42KNycEGwUW0 ezlwryDVHzyTUiKllNmkdK4v73mvPsZHEjgmme4afKAIiUilmcUF4XcqD86hISFT t+UJLA/zEU+0sJe26o2nK6GNJzmo4oCtVyxfhRe26Ojs1n80xlYgnZRfuIYdd31Z nwLBnwDCHAOyX91WXp9G =cVjZ -----END PGP SIGNATURE----- Merge tag 'docs-4.13' of git://git.lwn.net/linux Pull documentation updates from Jonathan Corbet: "There has been a fair amount of activity in the docs tree this time around. Highlights include: - Conversion of a bunch of security documentation into RST - The conversion of the remaining DocBook templates by The Amazing Mauro Machine. We can now drop the entire DocBook build chain. - The usual collection of fixes and minor updates" * tag 'docs-4.13' of git://git.lwn.net/linux: (90 commits) scripts/kernel-doc: handle DECLARE_HASHTABLE Documentation: atomic_ops.txt is core-api/atomic_ops.rst Docs: clean up some DocBook loose ends Make the main documentation title less Geocities Docs: Use kernel-figure in vidioc-g-selection.rst Docs: fix table problems in ras.rst Docs: Fix breakage with Sphinx 1.5 and upper Docs: Include the Latex "ifthen" package doc/kokr/howto: Only send regression fixes after -rc1 docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters doc: Document suitability of IBM Verse for kernel development Doc: fix a markup error in coding-style.rst docs: driver-api: i2c: remove some outdated information Documentation: DMA API: fix a typo in a function name Docs: Insert missing space to separate link from text doc/ko_KR/memory-barriers: Update control-dependencies example Documentation, kbuild: fix typo "minimun" -> "minimum" docs: Fix some formatting issues in request-key.rst doc: ReSTify keys-trusted-encrypted.txt doc: ReSTify keys-request-key.txt ...
This commit is contained in:
commit
650fc870a2
|
@ -24,8 +24,6 @@ DMA-ISA-LPC.txt
|
||||||
- How to do DMA with ISA (and LPC) devices.
|
- How to do DMA with ISA (and LPC) devices.
|
||||||
DMA-attributes.txt
|
DMA-attributes.txt
|
||||||
- listing of the various possible attributes a DMA region can have
|
- listing of the various possible attributes a DMA region can have
|
||||||
DocBook/
|
|
||||||
- directory with DocBook templates etc. for kernel documentation.
|
|
||||||
EDID/
|
EDID/
|
||||||
- directory with info on customizing EDID for broken gfx/displays.
|
- directory with info on customizing EDID for broken gfx/displays.
|
||||||
IPMI.txt
|
IPMI.txt
|
||||||
|
@ -40,8 +38,6 @@ Intel-IOMMU.txt
|
||||||
- basic info on the Intel IOMMU virtualization support.
|
- basic info on the Intel IOMMU virtualization support.
|
||||||
Makefile
|
Makefile
|
||||||
- It's not of interest for those who aren't touching the build system.
|
- It's not of interest for those who aren't touching the build system.
|
||||||
Makefile.sphinx
|
|
||||||
- It's not of interest for those who aren't touching the build system.
|
|
||||||
PCI/
|
PCI/
|
||||||
- info related to PCI drivers.
|
- info related to PCI drivers.
|
||||||
RCU/
|
RCU/
|
||||||
|
@ -264,6 +260,8 @@ logo.gif
|
||||||
- full colour GIF image of Linux logo (penguin - Tux).
|
- full colour GIF image of Linux logo (penguin - Tux).
|
||||||
logo.txt
|
logo.txt
|
||||||
- info on creator of above logo & site to get additional images from.
|
- info on creator of above logo & site to get additional images from.
|
||||||
|
lsm.txt
|
||||||
|
- Linux Security Modules: General Security Hooks for Linux
|
||||||
lzo.txt
|
lzo.txt
|
||||||
- kernel LZO decompressor input formats
|
- kernel LZO decompressor input formats
|
||||||
m68k/
|
m68k/
|
||||||
|
|
|
@ -692,7 +692,7 @@ of preallocated entries is defined per architecture. If it is too low for you
|
||||||
boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
|
boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
|
||||||
architectural default.
|
architectural default.
|
||||||
|
|
||||||
void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
|
void debug_dma_mapping_error(struct device *dev, dma_addr_t dma_addr);
|
||||||
|
|
||||||
dma-debug interface debug_dma_mapping_error() to debug drivers that fail
|
dma-debug interface debug_dma_mapping_error() to debug drivers that fail
|
||||||
to check DMA mapping errors on addresses returned by dma_map_single() and
|
to check DMA mapping errors on addresses returned by dma_map_single() and
|
||||||
|
|
17
Documentation/DocBook/.gitignore
vendored
17
Documentation/DocBook/.gitignore
vendored
|
@ -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>include/linux/w1.h</title>
|
|
||||||
<para>W1 kernel API functions.</para>
|
|
||||||
!Iinclude/linux/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.c">
|
|
||||||
<title>drivers/w1/w1_family.c</title>
|
|
||||||
<para>Allows registering device family operations.</para>
|
|
||||||
!Edrivers/w1/w1_family.c
|
|
||||||
</sect2>
|
|
||||||
|
|
||||||
<sect2 id="w1_internal.h">
|
|
||||||
<title>drivers/w1/w1_internal.h</title>
|
|
||||||
<para>W1 internal initialization for master devices.</para>
|
|
||||||
!Idrivers/w1/w1_internal.h
|
|
||||||
</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 :=
|
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
|
a different interrupt, the driver will deadlock trying to recursively
|
||||||
acquire the spinlock. Such deadlocks can be avoided by using
|
acquire the spinlock. Such deadlocks can be avoided by using
|
||||||
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
|
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
|
||||||
and acquire the lock (see Documentation/DocBook/kernel-locking).
|
and acquire the lock (see Documentation/kernel-hacking/locking.rst).
|
||||||
|
|
||||||
4.5 How to tell whether MSI/MSI-X is enabled on a device
|
4.5 How to tell whether MSI/MSI-X is enabled on a device
|
||||||
|
|
||||||
|
|
|
@ -1,3 +1,7 @@
|
||||||
|
=======
|
||||||
|
LoadPin
|
||||||
|
=======
|
||||||
|
|
||||||
LoadPin is a Linux Security Module that ensures all kernel-loaded files
|
LoadPin is a Linux Security Module that ensures all kernel-loaded files
|
||||||
(modules, firmware, etc) all originate from the same filesystem, with
|
(modules, firmware, etc) all originate from the same filesystem, with
|
||||||
the expectation that such a filesystem is backed by a read-only device
|
the expectation that such a filesystem is backed by a read-only device
|
||||||
|
@ -5,13 +9,13 @@ such as dm-verity or CDROM. This allows systems that have a verified
|
||||||
and/or unchangeable filesystem to enforce module and firmware loading
|
and/or unchangeable filesystem to enforce module and firmware loading
|
||||||
restrictions without needing to sign the files individually.
|
restrictions without needing to sign the files individually.
|
||||||
|
|
||||||
The LSM is selectable at build-time with CONFIG_SECURITY_LOADPIN, and
|
The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and
|
||||||
can be controlled at boot-time with the kernel command line option
|
can be controlled at boot-time with the kernel command line option
|
||||||
"loadpin.enabled". By default, it is enabled, but can be disabled at
|
"``loadpin.enabled``". By default, it is enabled, but can be disabled at
|
||||||
boot ("loadpin.enabled=0").
|
boot ("``loadpin.enabled=0``").
|
||||||
|
|
||||||
LoadPin starts pinning when it sees the first file loaded. If the
|
LoadPin starts pinning when it sees the first file loaded. If the
|
||||||
block device backing the filesystem is not read-only, a sysctl is
|
block device backing the filesystem is not read-only, a sysctl is
|
||||||
created to toggle pinning: /proc/sys/kernel/loadpin/enabled. (Having
|
created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having
|
||||||
a mutable filesystem means pinning is mutable too, but having the
|
a mutable filesystem means pinning is mutable too, but having the
|
||||||
sysctl allows for easy testing on systems with a mutable filesystem.)
|
sysctl allows for easy testing on systems with a mutable filesystem.)
|
|
@ -1,27 +1,33 @@
|
||||||
|
=======
|
||||||
|
SELinux
|
||||||
|
=======
|
||||||
|
|
||||||
If you want to use SELinux, chances are you will want
|
If you want to use SELinux, chances are you will want
|
||||||
to use the distro-provided policies, or install the
|
to use the distro-provided policies, or install the
|
||||||
latest reference policy release from
|
latest reference policy release from
|
||||||
|
|
||||||
http://oss.tresys.com/projects/refpolicy
|
http://oss.tresys.com/projects/refpolicy
|
||||||
|
|
||||||
However, if you want to install a dummy policy for
|
However, if you want to install a dummy policy for
|
||||||
testing, you can do using 'mdp' provided under
|
testing, you can do using ``mdp`` provided under
|
||||||
scripts/selinux. Note that this requires the selinux
|
scripts/selinux. Note that this requires the selinux
|
||||||
userspace to be installed - in particular you will
|
userspace to be installed - in particular you will
|
||||||
need checkpolicy to compile a kernel, and setfiles and
|
need checkpolicy to compile a kernel, and setfiles and
|
||||||
fixfiles to label the filesystem.
|
fixfiles to label the filesystem.
|
||||||
|
|
||||||
1. Compile the kernel with selinux enabled.
|
1. Compile the kernel with selinux enabled.
|
||||||
2. Type 'make' to compile mdp.
|
2. Type ``make`` to compile ``mdp``.
|
||||||
3. Make sure that you are not running with
|
3. Make sure that you are not running with
|
||||||
SELinux enabled and a real policy. If
|
SELinux enabled and a real policy. If
|
||||||
you are, reboot with selinux disabled
|
you are, reboot with selinux disabled
|
||||||
before continuing.
|
before continuing.
|
||||||
4. Run install_policy.sh:
|
4. Run install_policy.sh::
|
||||||
|
|
||||||
cd scripts/selinux
|
cd scripts/selinux
|
||||||
sh install_policy.sh
|
sh install_policy.sh
|
||||||
|
|
||||||
Step 4 will create a new dummy policy valid for your
|
Step 4 will create a new dummy policy valid for your
|
||||||
kernel, with a single selinux user, role, and type.
|
kernel, with a single selinux user, role, and type.
|
||||||
It will compile the policy, will set your SELINUXTYPE to
|
It will compile the policy, will set your ``SELINUXTYPE`` to
|
||||||
dummy in /etc/selinux/config, install the compiled policy
|
``dummy`` in ``/etc/selinux/config``, install the compiled policy
|
||||||
as 'dummy', and relabel your filesystem.
|
as ``dummy``, and relabel your filesystem.
|
|
@ -1,3 +1,6 @@
|
||||||
|
=====
|
||||||
|
Smack
|
||||||
|
=====
|
||||||
|
|
||||||
|
|
||||||
"Good for you, you've decided to clean the elevator!"
|
"Good for you, you've decided to clean the elevator!"
|
||||||
|
@ -14,6 +17,7 @@ available to determine which is best suited to the problem
|
||||||
at hand.
|
at hand.
|
||||||
|
|
||||||
Smack consists of three major components:
|
Smack consists of three major components:
|
||||||
|
|
||||||
- The kernel
|
- The kernel
|
||||||
- Basic utilities, which are helpful but not required
|
- Basic utilities, which are helpful but not required
|
||||||
- Configuration data
|
- Configuration data
|
||||||
|
@ -39,16 +43,24 @@ The current git repository for Smack user space is:
|
||||||
This should make and install on most modern distributions.
|
This should make and install on most modern distributions.
|
||||||
There are five commands included in smackutil:
|
There are five commands included in smackutil:
|
||||||
|
|
||||||
chsmack - display or set Smack extended attribute values
|
chsmack:
|
||||||
smackctl - load the Smack access rules
|
display or set Smack extended attribute values
|
||||||
smackaccess - report if a process with one label has access
|
|
||||||
to an object with another
|
smackctl:
|
||||||
|
load the Smack access rules
|
||||||
|
|
||||||
|
smackaccess:
|
||||||
|
report if a process with one label has access
|
||||||
|
to an object with another
|
||||||
|
|
||||||
These two commands are obsolete with the introduction of
|
These two commands are obsolete with the introduction of
|
||||||
the smackfs/load2 and smackfs/cipso2 interfaces.
|
the smackfs/load2 and smackfs/cipso2 interfaces.
|
||||||
|
|
||||||
smackload - properly formats data for writing to smackfs/load
|
smackload:
|
||||||
smackcipso - properly formats data for writing to smackfs/cipso
|
properly formats data for writing to smackfs/load
|
||||||
|
|
||||||
|
smackcipso:
|
||||||
|
properly formats data for writing to smackfs/cipso
|
||||||
|
|
||||||
In keeping with the intent of Smack, configuration data is
|
In keeping with the intent of Smack, configuration data is
|
||||||
minimal and not strictly required. The most important
|
minimal and not strictly required. The most important
|
||||||
|
@ -56,15 +68,15 @@ configuration step is mounting the smackfs pseudo filesystem.
|
||||||
If smackutil is installed the startup script will take care
|
If smackutil is installed the startup script will take care
|
||||||
of this, but it can be manually as well.
|
of this, but it can be manually as well.
|
||||||
|
|
||||||
Add this line to /etc/fstab:
|
Add this line to ``/etc/fstab``::
|
||||||
|
|
||||||
smackfs /sys/fs/smackfs smackfs defaults 0 0
|
smackfs /sys/fs/smackfs smackfs defaults 0 0
|
||||||
|
|
||||||
The /sys/fs/smackfs directory is created by the kernel.
|
The ``/sys/fs/smackfs`` directory is created by the kernel.
|
||||||
|
|
||||||
Smack uses extended attributes (xattrs) to store labels on filesystem
|
Smack uses extended attributes (xattrs) to store labels on filesystem
|
||||||
objects. The attributes are stored in the extended attribute security
|
objects. The attributes are stored in the extended attribute security
|
||||||
name space. A process must have CAP_MAC_ADMIN to change any of these
|
name space. A process must have ``CAP_MAC_ADMIN`` to change any of these
|
||||||
attributes.
|
attributes.
|
||||||
|
|
||||||
The extended attributes that Smack uses are:
|
The extended attributes that Smack uses are:
|
||||||
|
@ -73,14 +85,17 @@ SMACK64
|
||||||
Used to make access control decisions. In almost all cases
|
Used to make access control decisions. In almost all cases
|
||||||
the label given to a new filesystem object will be the label
|
the label given to a new filesystem object will be the label
|
||||||
of the process that created it.
|
of the process that created it.
|
||||||
|
|
||||||
SMACK64EXEC
|
SMACK64EXEC
|
||||||
The Smack label of a process that execs a program file with
|
The Smack label of a process that execs a program file with
|
||||||
this attribute set will run with this attribute's value.
|
this attribute set will run with this attribute's value.
|
||||||
|
|
||||||
SMACK64MMAP
|
SMACK64MMAP
|
||||||
Don't allow the file to be mmapped by a process whose Smack
|
Don't allow the file to be mmapped by a process whose Smack
|
||||||
label does not allow all of the access permitted to a process
|
label does not allow all of the access permitted to a process
|
||||||
with the label contained in this attribute. This is a very
|
with the label contained in this attribute. This is a very
|
||||||
specific use case for shared libraries.
|
specific use case for shared libraries.
|
||||||
|
|
||||||
SMACK64TRANSMUTE
|
SMACK64TRANSMUTE
|
||||||
Can only have the value "TRUE". If this attribute is present
|
Can only have the value "TRUE". If this attribute is present
|
||||||
on a directory when an object is created in the directory and
|
on a directory when an object is created in the directory and
|
||||||
|
@ -89,27 +104,29 @@ SMACK64TRANSMUTE
|
||||||
gets the label of the directory instead of the label of the
|
gets the label of the directory instead of the label of the
|
||||||
creating process. If the object being created is a directory
|
creating process. If the object being created is a directory
|
||||||
the SMACK64TRANSMUTE attribute is set as well.
|
the SMACK64TRANSMUTE attribute is set as well.
|
||||||
|
|
||||||
SMACK64IPIN
|
SMACK64IPIN
|
||||||
This attribute is only available on file descriptors for sockets.
|
This attribute is only available on file descriptors for sockets.
|
||||||
Use the Smack label in this attribute for access control
|
Use the Smack label in this attribute for access control
|
||||||
decisions on packets being delivered to this socket.
|
decisions on packets being delivered to this socket.
|
||||||
|
|
||||||
SMACK64IPOUT
|
SMACK64IPOUT
|
||||||
This attribute is only available on file descriptors for sockets.
|
This attribute is only available on file descriptors for sockets.
|
||||||
Use the Smack label in this attribute for access control
|
Use the Smack label in this attribute for access control
|
||||||
decisions on packets coming from this socket.
|
decisions on packets coming from this socket.
|
||||||
|
|
||||||
There are multiple ways to set a Smack label on a file:
|
There are multiple ways to set a Smack label on a file::
|
||||||
|
|
||||||
# attr -S -s SMACK64 -V "value" path
|
# attr -S -s SMACK64 -V "value" path
|
||||||
# chsmack -a value path
|
# chsmack -a value path
|
||||||
|
|
||||||
A process can see the Smack label it is running with by
|
A process can see the Smack label it is running with by
|
||||||
reading /proc/self/attr/current. A process with CAP_MAC_ADMIN
|
reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN``
|
||||||
can set the process Smack by writing there.
|
can set the process Smack by writing there.
|
||||||
|
|
||||||
Most Smack configuration is accomplished by writing to files
|
Most Smack configuration is accomplished by writing to files
|
||||||
in the smackfs filesystem. This pseudo-filesystem is mounted
|
in the smackfs filesystem. This pseudo-filesystem is mounted
|
||||||
on /sys/fs/smackfs.
|
on ``/sys/fs/smackfs``.
|
||||||
|
|
||||||
access
|
access
|
||||||
Provided for backward compatibility. The access2 interface
|
Provided for backward compatibility. The access2 interface
|
||||||
|
@ -120,6 +137,7 @@ access
|
||||||
this file. The next read will indicate whether the access
|
this file. The next read will indicate whether the access
|
||||||
would be permitted. The text will be either "1" indicating
|
would be permitted. The text will be either "1" indicating
|
||||||
access, or "0" indicating denial.
|
access, or "0" indicating denial.
|
||||||
|
|
||||||
access2
|
access2
|
||||||
This interface reports whether a subject with the specified
|
This interface reports whether a subject with the specified
|
||||||
Smack label has a particular access to an object with a
|
Smack label has a particular access to an object with a
|
||||||
|
@ -127,13 +145,17 @@ access2
|
||||||
this file. The next read will indicate whether the access
|
this file. The next read will indicate whether the access
|
||||||
would be permitted. The text will be either "1" indicating
|
would be permitted. The text will be either "1" indicating
|
||||||
access, or "0" indicating denial.
|
access, or "0" indicating denial.
|
||||||
|
|
||||||
ambient
|
ambient
|
||||||
This contains the Smack label applied to unlabeled network
|
This contains the Smack label applied to unlabeled network
|
||||||
packets.
|
packets.
|
||||||
|
|
||||||
change-rule
|
change-rule
|
||||||
This interface allows modification of existing access control rules.
|
This interface allows modification of existing access control rules.
|
||||||
The format accepted on write is:
|
The format accepted on write is::
|
||||||
|
|
||||||
"%s %s %s %s"
|
"%s %s %s %s"
|
||||||
|
|
||||||
where the first string is the subject label, the second the
|
where the first string is the subject label, the second the
|
||||||
object label, the third the access to allow and the fourth the
|
object label, the third the access to allow and the fourth the
|
||||||
access to deny. The access strings may contain only the characters
|
access to deny. The access strings may contain only the characters
|
||||||
|
@ -141,47 +163,63 @@ change-rule
|
||||||
modified by enabling the permissions in the third string and disabling
|
modified by enabling the permissions in the third string and disabling
|
||||||
those in the fourth string. If there is no such rule it will be
|
those in the fourth string. If there is no such rule it will be
|
||||||
created using the access specified in the third and the fourth strings.
|
created using the access specified in the third and the fourth strings.
|
||||||
|
|
||||||
cipso
|
cipso
|
||||||
Provided for backward compatibility. The cipso2 interface
|
Provided for backward compatibility. The cipso2 interface
|
||||||
is preferred and should be used instead.
|
is preferred and should be used instead.
|
||||||
This interface allows a specific CIPSO header to be assigned
|
This interface allows a specific CIPSO header to be assigned
|
||||||
to a Smack label. The format accepted on write is:
|
to a Smack label. The format accepted on write is::
|
||||||
|
|
||||||
"%24s%4d%4d"["%4d"]...
|
"%24s%4d%4d"["%4d"]...
|
||||||
|
|
||||||
The first string is a fixed Smack label. The first number is
|
The first string is a fixed Smack label. The first number is
|
||||||
the level to use. The second number is the number of categories.
|
the level to use. The second number is the number of categories.
|
||||||
The following numbers are the categories.
|
The following numbers are the categories::
|
||||||
"level-3-cats-5-19 3 2 5 19"
|
|
||||||
|
"level-3-cats-5-19 3 2 5 19"
|
||||||
|
|
||||||
cipso2
|
cipso2
|
||||||
This interface allows a specific CIPSO header to be assigned
|
This interface allows a specific CIPSO header to be assigned
|
||||||
to a Smack label. The format accepted on write is:
|
to a Smack label. The format accepted on write is::
|
||||||
"%s%4d%4d"["%4d"]...
|
|
||||||
|
"%s%4d%4d"["%4d"]...
|
||||||
|
|
||||||
The first string is a long Smack label. The first number is
|
The first string is a long Smack label. The first number is
|
||||||
the level to use. The second number is the number of categories.
|
the level to use. The second number is the number of categories.
|
||||||
The following numbers are the categories.
|
The following numbers are the categories::
|
||||||
"level-3-cats-5-19 3 2 5 19"
|
|
||||||
|
"level-3-cats-5-19 3 2 5 19"
|
||||||
|
|
||||||
direct
|
direct
|
||||||
This contains the CIPSO level used for Smack direct label
|
This contains the CIPSO level used for Smack direct label
|
||||||
representation in network packets.
|
representation in network packets.
|
||||||
|
|
||||||
doi
|
doi
|
||||||
This contains the CIPSO domain of interpretation used in
|
This contains the CIPSO domain of interpretation used in
|
||||||
network packets.
|
network packets.
|
||||||
|
|
||||||
ipv6host
|
ipv6host
|
||||||
This interface allows specific IPv6 internet addresses to be
|
This interface allows specific IPv6 internet addresses to be
|
||||||
treated as single label hosts. Packets are sent to single
|
treated as single label hosts. Packets are sent to single
|
||||||
label hosts only from processes that have Smack write access
|
label hosts only from processes that have Smack write access
|
||||||
to the host label. All packets received from single label hosts
|
to the host label. All packets received from single label hosts
|
||||||
are given the specified label. The format accepted on write is:
|
are given the specified label. The format accepted on write is::
|
||||||
|
|
||||||
"%h:%h:%h:%h:%h:%h:%h:%h label" or
|
"%h:%h:%h:%h:%h:%h:%h:%h label" or
|
||||||
"%h:%h:%h:%h:%h:%h:%h:%h/%d label".
|
"%h:%h:%h:%h:%h:%h:%h:%h/%d label".
|
||||||
|
|
||||||
The "::" address shortcut is not supported.
|
The "::" address shortcut is not supported.
|
||||||
If label is "-DELETE" a matched entry will be deleted.
|
If label is "-DELETE" a matched entry will be deleted.
|
||||||
|
|
||||||
load
|
load
|
||||||
Provided for backward compatibility. The load2 interface
|
Provided for backward compatibility. The load2 interface
|
||||||
is preferred and should be used instead.
|
is preferred and should be used instead.
|
||||||
This interface allows access control rules in addition to
|
This interface allows access control rules in addition to
|
||||||
the system defined rules to be specified. The format accepted
|
the system defined rules to be specified. The format accepted
|
||||||
on write is:
|
on write is::
|
||||||
|
|
||||||
"%24s%24s%5s"
|
"%24s%24s%5s"
|
||||||
|
|
||||||
where the first string is the subject label, the second the
|
where the first string is the subject label, the second the
|
||||||
object label, and the third the requested access. The access
|
object label, and the third the requested access. The access
|
||||||
string may contain only the characters "rwxat-", and specifies
|
string may contain only the characters "rwxat-", and specifies
|
||||||
|
@ -189,17 +227,21 @@ load
|
||||||
permissions that are not allowed. The string "r-x--" would
|
permissions that are not allowed. The string "r-x--" would
|
||||||
specify read and execute access. Labels are limited to 23
|
specify read and execute access. Labels are limited to 23
|
||||||
characters in length.
|
characters in length.
|
||||||
|
|
||||||
load2
|
load2
|
||||||
This interface allows access control rules in addition to
|
This interface allows access control rules in addition to
|
||||||
the system defined rules to be specified. The format accepted
|
the system defined rules to be specified. The format accepted
|
||||||
on write is:
|
on write is::
|
||||||
|
|
||||||
"%s %s %s"
|
"%s %s %s"
|
||||||
|
|
||||||
where the first string is the subject label, the second the
|
where the first string is the subject label, the second the
|
||||||
object label, and the third the requested access. The access
|
object label, and the third the requested access. The access
|
||||||
string may contain only the characters "rwxat-", and specifies
|
string may contain only the characters "rwxat-", and specifies
|
||||||
which sort of access is allowed. The "-" is a placeholder for
|
which sort of access is allowed. The "-" is a placeholder for
|
||||||
permissions that are not allowed. The string "r-x--" would
|
permissions that are not allowed. The string "r-x--" would
|
||||||
specify read and execute access.
|
specify read and execute access.
|
||||||
|
|
||||||
load-self
|
load-self
|
||||||
Provided for backward compatibility. The load-self2 interface
|
Provided for backward compatibility. The load-self2 interface
|
||||||
is preferred and should be used instead.
|
is preferred and should be used instead.
|
||||||
|
@ -208,66 +250,83 @@ load-self
|
||||||
otherwise be permitted, and are intended to provide additional
|
otherwise be permitted, and are intended to provide additional
|
||||||
restrictions on the process. The format is the same as for
|
restrictions on the process. The format is the same as for
|
||||||
the load interface.
|
the load interface.
|
||||||
|
|
||||||
load-self2
|
load-self2
|
||||||
This interface allows process specific access rules to be
|
This interface allows process specific access rules to be
|
||||||
defined. These rules are only consulted if access would
|
defined. These rules are only consulted if access would
|
||||||
otherwise be permitted, and are intended to provide additional
|
otherwise be permitted, and are intended to provide additional
|
||||||
restrictions on the process. The format is the same as for
|
restrictions on the process. The format is the same as for
|
||||||
the load2 interface.
|
the load2 interface.
|
||||||
|
|
||||||
logging
|
logging
|
||||||
This contains the Smack logging state.
|
This contains the Smack logging state.
|
||||||
|
|
||||||
mapped
|
mapped
|
||||||
This contains the CIPSO level used for Smack mapped label
|
This contains the CIPSO level used for Smack mapped label
|
||||||
representation in network packets.
|
representation in network packets.
|
||||||
|
|
||||||
netlabel
|
netlabel
|
||||||
This interface allows specific internet addresses to be
|
This interface allows specific internet addresses to be
|
||||||
treated as single label hosts. Packets are sent to single
|
treated as single label hosts. Packets are sent to single
|
||||||
label hosts without CIPSO headers, but only from processes
|
label hosts without CIPSO headers, but only from processes
|
||||||
that have Smack write access to the host label. All packets
|
that have Smack write access to the host label. All packets
|
||||||
received from single label hosts are given the specified
|
received from single label hosts are given the specified
|
||||||
label. The format accepted on write is:
|
label. The format accepted on write is::
|
||||||
|
|
||||||
"%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
|
"%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label".
|
||||||
|
|
||||||
If the label specified is "-CIPSO" the address is treated
|
If the label specified is "-CIPSO" the address is treated
|
||||||
as a host that supports CIPSO headers.
|
as a host that supports CIPSO headers.
|
||||||
|
|
||||||
onlycap
|
onlycap
|
||||||
This contains labels processes must have for CAP_MAC_ADMIN
|
This contains labels processes must have for CAP_MAC_ADMIN
|
||||||
and CAP_MAC_OVERRIDE to be effective. If this file is empty
|
and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty
|
||||||
these capabilities are effective at for processes with any
|
these capabilities are effective at for processes with any
|
||||||
label. The values are set by writing the desired labels, separated
|
label. The values are set by writing the desired labels, separated
|
||||||
by spaces, to the file or cleared by writing "-" to the file.
|
by spaces, to the file or cleared by writing "-" to the file.
|
||||||
|
|
||||||
ptrace
|
ptrace
|
||||||
This is used to define the current ptrace policy
|
This is used to define the current ptrace policy
|
||||||
0 - default: this is the policy that relies on Smack access rules.
|
|
||||||
For the PTRACE_READ a subject needs to have a read access on
|
0 - default:
|
||||||
object. For the PTRACE_ATTACH a read-write access is required.
|
this is the policy that relies on Smack access rules.
|
||||||
1 - exact: this is the policy that limits PTRACE_ATTACH. Attach is
|
For the ``PTRACE_READ`` a subject needs to have a read access on
|
||||||
|
object. For the ``PTRACE_ATTACH`` a read-write access is required.
|
||||||
|
|
||||||
|
1 - exact:
|
||||||
|
this is the policy that limits ``PTRACE_ATTACH``. Attach is
|
||||||
only allowed when subject's and object's labels are equal.
|
only allowed when subject's and object's labels are equal.
|
||||||
PTRACE_READ is not affected. Can be overridden with CAP_SYS_PTRACE.
|
``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``.
|
||||||
2 - draconian: this policy behaves like the 'exact' above with an
|
|
||||||
exception that it can't be overridden with CAP_SYS_PTRACE.
|
2 - draconian:
|
||||||
|
this policy behaves like the 'exact' above with an
|
||||||
|
exception that it can't be overridden with ``CAP_SYS_PTRACE``.
|
||||||
|
|
||||||
revoke-subject
|
revoke-subject
|
||||||
Writing a Smack label here sets the access to '-' for all access
|
Writing a Smack label here sets the access to '-' for all access
|
||||||
rules with that subject label.
|
rules with that subject label.
|
||||||
|
|
||||||
unconfined
|
unconfined
|
||||||
If the kernel is configured with CONFIG_SECURITY_SMACK_BRINGUP
|
If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP``
|
||||||
a process with CAP_MAC_ADMIN can write a label into this interface.
|
a process with ``CAP_MAC_ADMIN`` can write a label into this interface.
|
||||||
Thereafter, accesses that involve that label will be logged and
|
Thereafter, accesses that involve that label will be logged and
|
||||||
the access permitted if it wouldn't be otherwise. Note that this
|
the access permitted if it wouldn't be otherwise. Note that this
|
||||||
is dangerous and can ruin the proper labeling of your system.
|
is dangerous and can ruin the proper labeling of your system.
|
||||||
It should never be used in production.
|
It should never be used in production.
|
||||||
|
|
||||||
relabel-self
|
relabel-self
|
||||||
This interface contains a list of labels to which the process can
|
This interface contains a list of labels to which the process can
|
||||||
transition to, by writing to /proc/self/attr/current.
|
transition to, by writing to ``/proc/self/attr/current``.
|
||||||
Normally a process can change its own label to any legal value, but only
|
Normally a process can change its own label to any legal value, but only
|
||||||
if it has CAP_MAC_ADMIN. This interface allows a process without
|
if it has ``CAP_MAC_ADMIN``. This interface allows a process without
|
||||||
CAP_MAC_ADMIN to relabel itself to one of labels from predefined list.
|
``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list.
|
||||||
A process without CAP_MAC_ADMIN can change its label only once. When it
|
A process without ``CAP_MAC_ADMIN`` can change its label only once. When it
|
||||||
does, this list will be cleared.
|
does, this list will be cleared.
|
||||||
The values are set by writing the desired labels, separated
|
The values are set by writing the desired labels, separated
|
||||||
by spaces, to the file or cleared by writing "-" to the file.
|
by spaces, to the file or cleared by writing "-" to the file.
|
||||||
|
|
||||||
If you are using the smackload utility
|
If you are using the smackload utility
|
||||||
you can add access rules in /etc/smack/accesses. They take the form:
|
you can add access rules in ``/etc/smack/accesses``. They take the form::
|
||||||
|
|
||||||
subjectlabel objectlabel access
|
subjectlabel objectlabel access
|
||||||
|
|
||||||
|
@ -277,14 +336,14 @@ object with objectlabel. If there is no rule no access is allowed.
|
||||||
|
|
||||||
Look for additional programs on http://schaufler-ca.com
|
Look for additional programs on http://schaufler-ca.com
|
||||||
|
|
||||||
From the Smack Whitepaper:
|
The Simplified Mandatory Access Control Kernel (Whitepaper)
|
||||||
|
===========================================================
|
||||||
The Simplified Mandatory Access Control Kernel
|
|
||||||
|
|
||||||
Casey Schaufler
|
Casey Schaufler
|
||||||
casey@schaufler-ca.com
|
casey@schaufler-ca.com
|
||||||
|
|
||||||
Mandatory Access Control
|
Mandatory Access Control
|
||||||
|
------------------------
|
||||||
|
|
||||||
Computer systems employ a variety of schemes to constrain how information is
|
Computer systems employ a variety of schemes to constrain how information is
|
||||||
shared among the people and services using the machine. Some of these schemes
|
shared among the people and services using the machine. Some of these schemes
|
||||||
|
@ -297,6 +356,7 @@ access control mechanisms because you don't have a choice regarding the users
|
||||||
or programs that have access to pieces of data.
|
or programs that have access to pieces of data.
|
||||||
|
|
||||||
Bell & LaPadula
|
Bell & LaPadula
|
||||||
|
---------------
|
||||||
|
|
||||||
From the middle of the 1980's until the turn of the century Mandatory Access
|
From the middle of the 1980's until the turn of the century Mandatory Access
|
||||||
Control (MAC) was very closely associated with the Bell & LaPadula security
|
Control (MAC) was very closely associated with the Bell & LaPadula security
|
||||||
|
@ -306,6 +366,7 @@ within the Capital Beltway and Scandinavian supercomputer centers but was
|
||||||
often sited as failing to address general needs.
|
often sited as failing to address general needs.
|
||||||
|
|
||||||
Domain Type Enforcement
|
Domain Type Enforcement
|
||||||
|
-----------------------
|
||||||
|
|
||||||
Around the turn of the century Domain Type Enforcement (DTE) became popular.
|
Around the turn of the century Domain Type Enforcement (DTE) became popular.
|
||||||
This scheme organizes users, programs, and data into domains that are
|
This scheme organizes users, programs, and data into domains that are
|
||||||
|
@ -316,6 +377,7 @@ necessary to provide a secure domain mapping leads to the scheme being
|
||||||
disabled or used in limited ways in the majority of cases.
|
disabled or used in limited ways in the majority of cases.
|
||||||
|
|
||||||
Smack
|
Smack
|
||||||
|
-----
|
||||||
|
|
||||||
Smack is a Mandatory Access Control mechanism designed to provide useful MAC
|
Smack is a Mandatory Access Control mechanism designed to provide useful MAC
|
||||||
while avoiding the pitfalls of its predecessors. The limitations of Bell &
|
while avoiding the pitfalls of its predecessors. The limitations of Bell &
|
||||||
|
@ -326,46 +388,55 @@ Enforcement and avoided by defining access controls in terms of the access
|
||||||
modes already in use.
|
modes already in use.
|
||||||
|
|
||||||
Smack Terminology
|
Smack Terminology
|
||||||
|
-----------------
|
||||||
|
|
||||||
The jargon used to talk about Smack will be familiar to those who have dealt
|
The jargon used to talk about Smack will be familiar to those who have dealt
|
||||||
with other MAC systems and shouldn't be too difficult for the uninitiated to
|
with other MAC systems and shouldn't be too difficult for the uninitiated to
|
||||||
pick up. There are four terms that are used in a specific way and that are
|
pick up. There are four terms that are used in a specific way and that are
|
||||||
especially important:
|
especially important:
|
||||||
|
|
||||||
Subject: A subject is an active entity on the computer system.
|
Subject:
|
||||||
|
A subject is an active entity on the computer system.
|
||||||
On Smack a subject is a task, which is in turn the basic unit
|
On Smack a subject is a task, which is in turn the basic unit
|
||||||
of execution.
|
of execution.
|
||||||
|
|
||||||
Object: An object is a passive entity on the computer system.
|
Object:
|
||||||
|
An object is a passive entity on the computer system.
|
||||||
On Smack files of all types, IPC, and tasks can be objects.
|
On Smack files of all types, IPC, and tasks can be objects.
|
||||||
|
|
||||||
Access: Any attempt by a subject to put information into or get
|
Access:
|
||||||
|
Any attempt by a subject to put information into or get
|
||||||
information from an object is an access.
|
information from an object is an access.
|
||||||
|
|
||||||
Label: Data that identifies the Mandatory Access Control
|
Label:
|
||||||
|
Data that identifies the Mandatory Access Control
|
||||||
characteristics of a subject or an object.
|
characteristics of a subject or an object.
|
||||||
|
|
||||||
These definitions are consistent with the traditional use in the security
|
These definitions are consistent with the traditional use in the security
|
||||||
community. There are also some terms from Linux that are likely to crop up:
|
community. There are also some terms from Linux that are likely to crop up:
|
||||||
|
|
||||||
Capability: A task that possesses a capability has permission to
|
Capability:
|
||||||
|
A task that possesses a capability has permission to
|
||||||
violate an aspect of the system security policy, as identified by
|
violate an aspect of the system security policy, as identified by
|
||||||
the specific capability. A task that possesses one or more
|
the specific capability. A task that possesses one or more
|
||||||
capabilities is a privileged task, whereas a task with no
|
capabilities is a privileged task, whereas a task with no
|
||||||
capabilities is an unprivileged task.
|
capabilities is an unprivileged task.
|
||||||
|
|
||||||
Privilege: A task that is allowed to violate the system security
|
Privilege:
|
||||||
|
A task that is allowed to violate the system security
|
||||||
policy is said to have privilege. As of this writing a task can
|
policy is said to have privilege. As of this writing a task can
|
||||||
have privilege either by possessing capabilities or by having an
|
have privilege either by possessing capabilities or by having an
|
||||||
effective user of root.
|
effective user of root.
|
||||||
|
|
||||||
Smack Basics
|
Smack Basics
|
||||||
|
------------
|
||||||
|
|
||||||
Smack is an extension to a Linux system. It enforces additional restrictions
|
Smack is an extension to a Linux system. It enforces additional restrictions
|
||||||
on what subjects can access which objects, based on the labels attached to
|
on what subjects can access which objects, based on the labels attached to
|
||||||
each of the subject and the object.
|
each of the subject and the object.
|
||||||
|
|
||||||
Labels
|
Labels
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
Smack labels are ASCII character strings. They can be up to 255 characters
|
Smack labels are ASCII character strings. They can be up to 255 characters
|
||||||
long, but keeping them to twenty-three characters is recommended.
|
long, but keeping them to twenty-three characters is recommended.
|
||||||
|
@ -377,7 +448,7 @@ contain unprintable characters, the "/" (slash), the "\" (backslash), the "'"
|
||||||
(quote) and '"' (double-quote) characters.
|
(quote) and '"' (double-quote) characters.
|
||||||
Smack labels cannot begin with a '-'. This is reserved for special options.
|
Smack labels cannot begin with a '-'. This is reserved for special options.
|
||||||
|
|
||||||
There are some predefined labels:
|
There are some predefined labels::
|
||||||
|
|
||||||
_ Pronounced "floor", a single underscore character.
|
_ Pronounced "floor", a single underscore character.
|
||||||
^ Pronounced "hat", a single circumflex character.
|
^ Pronounced "hat", a single circumflex character.
|
||||||
|
@ -390,14 +461,18 @@ of a process will usually be assigned by the system initialization
|
||||||
mechanism.
|
mechanism.
|
||||||
|
|
||||||
Access Rules
|
Access Rules
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
Smack uses the traditional access modes of Linux. These modes are read,
|
Smack uses the traditional access modes of Linux. These modes are read,
|
||||||
execute, write, and occasionally append. There are a few cases where the
|
execute, write, and occasionally append. There are a few cases where the
|
||||||
access mode may not be obvious. These include:
|
access mode may not be obvious. These include:
|
||||||
|
|
||||||
Signals: A signal is a write operation from the subject task to
|
Signals:
|
||||||
|
A signal is a write operation from the subject task to
|
||||||
the object task.
|
the object task.
|
||||||
Internet Domain IPC: Transmission of a packet is considered a
|
|
||||||
|
Internet Domain IPC:
|
||||||
|
Transmission of a packet is considered a
|
||||||
write operation from the source task to the destination task.
|
write operation from the source task to the destination task.
|
||||||
|
|
||||||
Smack restricts access based on the label attached to a subject and the label
|
Smack restricts access based on the label attached to a subject and the label
|
||||||
|
@ -417,6 +492,7 @@ order:
|
||||||
7. Any other access is denied.
|
7. Any other access is denied.
|
||||||
|
|
||||||
Smack Access Rules
|
Smack Access Rules
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
With the isolation provided by Smack access separation is simple. There are
|
With the isolation provided by Smack access separation is simple. There are
|
||||||
many interesting cases where limited access by subjects to objects with
|
many interesting cases where limited access by subjects to objects with
|
||||||
|
@ -427,8 +503,9 @@ be "born" highly classified. To accommodate such schemes Smack includes a
|
||||||
mechanism for specifying rules allowing access between labels.
|
mechanism for specifying rules allowing access between labels.
|
||||||
|
|
||||||
Access Rule Format
|
Access Rule Format
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The format of an access rule is:
|
The format of an access rule is::
|
||||||
|
|
||||||
subject-label object-label access
|
subject-label object-label access
|
||||||
|
|
||||||
|
@ -446,7 +523,7 @@ describe access modes:
|
||||||
|
|
||||||
Uppercase values for the specification letters are allowed as well.
|
Uppercase values for the specification letters are allowed as well.
|
||||||
Access mode specifications can be in any order. Examples of acceptable rules
|
Access mode specifications can be in any order. Examples of acceptable rules
|
||||||
are:
|
are::
|
||||||
|
|
||||||
TopSecret Secret rx
|
TopSecret Secret rx
|
||||||
Secret Unclass R
|
Secret Unclass R
|
||||||
|
@ -456,7 +533,7 @@ are:
|
||||||
New Old rRrRr
|
New Old rRrRr
|
||||||
Closed Off -
|
Closed Off -
|
||||||
|
|
||||||
Examples of unacceptable rules are:
|
Examples of unacceptable rules are::
|
||||||
|
|
||||||
Top Secret Secret rx
|
Top Secret Secret rx
|
||||||
Ace Ace r
|
Ace Ace r
|
||||||
|
@ -469,6 +546,7 @@ access specifications. The dash is a placeholder, so "a-r" is the same
|
||||||
as "ar". A lone dash is used to specify that no access should be allowed.
|
as "ar". A lone dash is used to specify that no access should be allowed.
|
||||||
|
|
||||||
Applying Access Rules
|
Applying Access Rules
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The developers of Linux rarely define new sorts of things, usually importing
|
The developers of Linux rarely define new sorts of things, usually importing
|
||||||
schemes and concepts from other systems. Most often, the other systems are
|
schemes and concepts from other systems. Most often, the other systems are
|
||||||
|
@ -511,6 +589,7 @@ one process to another requires that the sender have write access to the
|
||||||
receiver. The receiver is not required to have read access to the sender.
|
receiver. The receiver is not required to have read access to the sender.
|
||||||
|
|
||||||
Setting Access Rules
|
Setting Access Rules
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The configuration file /etc/smack/accesses contains the rules to be set at
|
The configuration file /etc/smack/accesses contains the rules to be set at
|
||||||
system startup. The contents are written to the special file
|
system startup. The contents are written to the special file
|
||||||
|
@ -520,6 +599,7 @@ one rule, with the most recently specified overriding any earlier
|
||||||
specification.
|
specification.
|
||||||
|
|
||||||
Task Attribute
|
Task Attribute
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The Smack label of a process can be read from /proc/<pid>/attr/current. A
|
The Smack label of a process can be read from /proc/<pid>/attr/current. A
|
||||||
process can read its own Smack label from /proc/self/attr/current. A
|
process can read its own Smack label from /proc/self/attr/current. A
|
||||||
|
@ -527,12 +607,14 @@ privileged process can change its own Smack label by writing to
|
||||||
/proc/self/attr/current but not the label of another process.
|
/proc/self/attr/current but not the label of another process.
|
||||||
|
|
||||||
File Attribute
|
File Attribute
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The Smack label of a filesystem object is stored as an extended attribute
|
The Smack label of a filesystem object is stored as an extended attribute
|
||||||
named SMACK64 on the file. This attribute is in the security namespace. It can
|
named SMACK64 on the file. This attribute is in the security namespace. It can
|
||||||
only be changed by a process with privilege.
|
only be changed by a process with privilege.
|
||||||
|
|
||||||
Privilege
|
Privilege
|
||||||
|
~~~~~~~~~
|
||||||
|
|
||||||
A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
|
A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged.
|
||||||
CAP_MAC_OVERRIDE allows the process access to objects it would
|
CAP_MAC_OVERRIDE allows the process access to objects it would
|
||||||
|
@ -540,6 +622,7 @@ be denied otherwise. CAP_MAC_ADMIN allows a process to change
|
||||||
Smack data, including rules and attributes.
|
Smack data, including rules and attributes.
|
||||||
|
|
||||||
Smack Networking
|
Smack Networking
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
As mentioned before, Smack enforces access control on network protocol
|
As mentioned before, Smack enforces access control on network protocol
|
||||||
transmissions. Every packet sent by a Smack process is tagged with its Smack
|
transmissions. Every packet sent by a Smack process is tagged with its Smack
|
||||||
|
@ -551,6 +634,7 @@ packet has write access to the receiving process and if that is not the case
|
||||||
the packet is dropped.
|
the packet is dropped.
|
||||||
|
|
||||||
CIPSO Configuration
|
CIPSO Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
It is normally unnecessary to specify the CIPSO configuration. The default
|
It is normally unnecessary to specify the CIPSO configuration. The default
|
||||||
values used by the system handle all internal cases. Smack will compose CIPSO
|
values used by the system handle all internal cases. Smack will compose CIPSO
|
||||||
|
@ -571,13 +655,13 @@ discarded. The DOI is 3 by default. The value can be read from
|
||||||
The label and category set are mapped to a Smack label as defined in
|
The label and category set are mapped to a Smack label as defined in
|
||||||
/etc/smack/cipso.
|
/etc/smack/cipso.
|
||||||
|
|
||||||
A Smack/CIPSO mapping has the form:
|
A Smack/CIPSO mapping has the form::
|
||||||
|
|
||||||
smack level [category [category]*]
|
smack level [category [category]*]
|
||||||
|
|
||||||
Smack does not expect the level or category sets to be related in any
|
Smack does not expect the level or category sets to be related in any
|
||||||
particular way and does not assume or assign accesses based on them. Some
|
particular way and does not assume or assign accesses based on them. Some
|
||||||
examples of mappings:
|
examples of mappings::
|
||||||
|
|
||||||
TopSecret 7
|
TopSecret 7
|
||||||
TS:A,B 7 1 2
|
TS:A,B 7 1 2
|
||||||
|
@ -597,25 +681,30 @@ value can be read from /sys/fs/smackfs/direct and changed by writing to
|
||||||
/sys/fs/smackfs/direct.
|
/sys/fs/smackfs/direct.
|
||||||
|
|
||||||
Socket Attributes
|
Socket Attributes
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
There are two attributes that are associated with sockets. These attributes
|
There are two attributes that are associated with sockets. These attributes
|
||||||
can only be set by privileged tasks, but any task can read them for their own
|
can only be set by privileged tasks, but any task can read them for their own
|
||||||
sockets.
|
sockets.
|
||||||
|
|
||||||
SMACK64IPIN: The Smack label of the task object. A privileged
|
SMACK64IPIN:
|
||||||
|
The Smack label of the task object. A privileged
|
||||||
program that will enforce policy may set this to the star label.
|
program that will enforce policy may set this to the star label.
|
||||||
|
|
||||||
SMACK64IPOUT: The Smack label transmitted with outgoing packets.
|
SMACK64IPOUT:
|
||||||
|
The Smack label transmitted with outgoing packets.
|
||||||
A privileged program may set this to match the label of another
|
A privileged program may set this to match the label of another
|
||||||
task with which it hopes to communicate.
|
task with which it hopes to communicate.
|
||||||
|
|
||||||
Smack Netlabel Exceptions
|
Smack Netlabel Exceptions
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You will often find that your labeled application has to talk to the outside,
|
You will often find that your labeled application has to talk to the outside,
|
||||||
unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
|
unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel
|
||||||
where you can add some exceptions in the form of :
|
where you can add some exceptions in the form of::
|
||||||
@IP1 LABEL1 or
|
|
||||||
@IP2/MASK LABEL2
|
@IP1 LABEL1 or
|
||||||
|
@IP2/MASK LABEL2
|
||||||
|
|
||||||
It means that your application will have unlabeled access to @IP1 if it has
|
It means that your application will have unlabeled access to @IP1 if it has
|
||||||
write access on LABEL1, and access to the subnet @IP2/MASK if it has write
|
write access on LABEL1, and access to the subnet @IP2/MASK if it has write
|
||||||
|
@ -624,28 +713,32 @@ access on LABEL2.
|
||||||
Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
|
Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask
|
||||||
first, like in classless IPv4 routing.
|
first, like in classless IPv4 routing.
|
||||||
|
|
||||||
A special label '@' and an option '-CIPSO' can be used there :
|
A special label '@' and an option '-CIPSO' can be used there::
|
||||||
@ means Internet, any application with any label has access to it
|
|
||||||
-CIPSO means standard CIPSO networking
|
|
||||||
|
|
||||||
If you don't know what CIPSO is and don't plan to use it, you can just do :
|
@ means Internet, any application with any label has access to it
|
||||||
echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
|
-CIPSO means standard CIPSO networking
|
||||||
echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
|
|
||||||
|
If you don't know what CIPSO is and don't plan to use it, you can just do::
|
||||||
|
|
||||||
|
echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
|
||||||
|
echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
|
||||||
|
|
||||||
If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
|
If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled
|
||||||
Internet access, you can have :
|
Internet access, you can have::
|
||||||
echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
|
|
||||||
echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
|
|
||||||
echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
|
|
||||||
|
|
||||||
|
echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel
|
||||||
|
echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel
|
||||||
|
echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel
|
||||||
|
|
||||||
Writing Applications for Smack
|
Writing Applications for Smack
|
||||||
|
------------------------------
|
||||||
|
|
||||||
There are three sorts of applications that will run on a Smack system. How an
|
There are three sorts of applications that will run on a Smack system. How an
|
||||||
application interacts with Smack will determine what it will have to do to
|
application interacts with Smack will determine what it will have to do to
|
||||||
work properly under Smack.
|
work properly under Smack.
|
||||||
|
|
||||||
Smack Ignorant Applications
|
Smack Ignorant Applications
|
||||||
|
---------------------------
|
||||||
|
|
||||||
By far the majority of applications have no reason whatever to care about the
|
By far the majority of applications have no reason whatever to care about the
|
||||||
unique properties of Smack. Since invoking a program has no impact on the
|
unique properties of Smack. Since invoking a program has no impact on the
|
||||||
|
@ -653,12 +746,14 @@ Smack label associated with the process the only concern likely to arise is
|
||||||
whether the process has execute access to the program.
|
whether the process has execute access to the program.
|
||||||
|
|
||||||
Smack Relevant Applications
|
Smack Relevant Applications
|
||||||
|
---------------------------
|
||||||
|
|
||||||
Some programs can be improved by teaching them about Smack, but do not make
|
Some programs can be improved by teaching them about Smack, but do not make
|
||||||
any security decisions themselves. The utility ls(1) is one example of such a
|
any security decisions themselves. The utility ls(1) is one example of such a
|
||||||
program.
|
program.
|
||||||
|
|
||||||
Smack Enforcing Applications
|
Smack Enforcing Applications
|
||||||
|
----------------------------
|
||||||
|
|
||||||
These are special programs that not only know about Smack, but participate in
|
These are special programs that not only know about Smack, but participate in
|
||||||
the enforcement of system policy. In most cases these are the programs that
|
the enforcement of system policy. In most cases these are the programs that
|
||||||
|
@ -666,15 +761,16 @@ set up user sessions. There are also network services that provide information
|
||||||
to processes running with various labels.
|
to processes running with various labels.
|
||||||
|
|
||||||
File System Interfaces
|
File System Interfaces
|
||||||
|
----------------------
|
||||||
|
|
||||||
Smack maintains labels on file system objects using extended attributes. The
|
Smack maintains labels on file system objects using extended attributes. The
|
||||||
Smack label of a file, directory, or other file system object can be obtained
|
Smack label of a file, directory, or other file system object can be obtained
|
||||||
using getxattr(2).
|
using getxattr(2)::
|
||||||
|
|
||||||
len = getxattr("/", "security.SMACK64", value, sizeof (value));
|
len = getxattr("/", "security.SMACK64", value, sizeof (value));
|
||||||
|
|
||||||
will put the Smack label of the root directory into value. A privileged
|
will put the Smack label of the root directory into value. A privileged
|
||||||
process can set the Smack label of a file system object with setxattr(2).
|
process can set the Smack label of a file system object with setxattr(2)::
|
||||||
|
|
||||||
len = strlen("Rubble");
|
len = strlen("Rubble");
|
||||||
rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
|
rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0);
|
||||||
|
@ -683,17 +779,18 @@ will set the Smack label of /foo to "Rubble" if the program has appropriate
|
||||||
privilege.
|
privilege.
|
||||||
|
|
||||||
Socket Interfaces
|
Socket Interfaces
|
||||||
|
-----------------
|
||||||
|
|
||||||
The socket attributes can be read using fgetxattr(2).
|
The socket attributes can be read using fgetxattr(2).
|
||||||
|
|
||||||
A privileged process can set the Smack label of outgoing packets with
|
A privileged process can set the Smack label of outgoing packets with
|
||||||
fsetxattr(2).
|
fsetxattr(2)::
|
||||||
|
|
||||||
len = strlen("Rubble");
|
len = strlen("Rubble");
|
||||||
rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
|
rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0);
|
||||||
|
|
||||||
will set the Smack label "Rubble" on packets going out from the socket if the
|
will set the Smack label "Rubble" on packets going out from the socket if the
|
||||||
program has appropriate privilege.
|
program has appropriate privilege::
|
||||||
|
|
||||||
rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
|
rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0);
|
||||||
|
|
||||||
|
@ -701,33 +798,40 @@ will set the Smack label "*" as the object label against which incoming
|
||||||
packets will be checked if the program has appropriate privilege.
|
packets will be checked if the program has appropriate privilege.
|
||||||
|
|
||||||
Administration
|
Administration
|
||||||
|
--------------
|
||||||
|
|
||||||
Smack supports some mount options:
|
Smack supports some mount options:
|
||||||
|
|
||||||
smackfsdef=label: specifies the label to give files that lack
|
smackfsdef=label:
|
||||||
|
specifies the label to give files that lack
|
||||||
the Smack label extended attribute.
|
the Smack label extended attribute.
|
||||||
|
|
||||||
smackfsroot=label: specifies the label to assign the root of the
|
smackfsroot=label:
|
||||||
|
specifies the label to assign the root of the
|
||||||
file system if it lacks the Smack extended attribute.
|
file system if it lacks the Smack extended attribute.
|
||||||
|
|
||||||
smackfshat=label: specifies a label that must have read access to
|
smackfshat=label:
|
||||||
|
specifies a label that must have read access to
|
||||||
all labels set on the filesystem. Not yet enforced.
|
all labels set on the filesystem. Not yet enforced.
|
||||||
|
|
||||||
smackfsfloor=label: specifies a label to which all labels set on the
|
smackfsfloor=label:
|
||||||
|
specifies a label to which all labels set on the
|
||||||
filesystem must have read access. Not yet enforced.
|
filesystem must have read access. Not yet enforced.
|
||||||
|
|
||||||
These mount options apply to all file system types.
|
These mount options apply to all file system types.
|
||||||
|
|
||||||
Smack auditing
|
Smack auditing
|
||||||
|
--------------
|
||||||
|
|
||||||
If you want Smack auditing of security events, you need to set CONFIG_AUDIT
|
If you want Smack auditing of security events, you need to set CONFIG_AUDIT
|
||||||
in your kernel configuration.
|
in your kernel configuration.
|
||||||
By default, all denied events will be audited. You can change this behavior by
|
By default, all denied events will be audited. You can change this behavior by
|
||||||
writing a single character to the /sys/fs/smackfs/logging file :
|
writing a single character to the /sys/fs/smackfs/logging file::
|
||||||
0 : no logging
|
|
||||||
1 : log denied (default)
|
0 : no logging
|
||||||
2 : log accepted
|
1 : log denied (default)
|
||||||
3 : log denied & accepted
|
2 : log accepted
|
||||||
|
3 : log denied & accepted
|
||||||
|
|
||||||
Events are logged as 'key=value' pairs, for each event you at least will get
|
Events are logged as 'key=value' pairs, for each event you at least will get
|
||||||
the subject, the object, the rights requested, the action, the kernel function
|
the subject, the object, the rights requested, the action, the kernel function
|
||||||
|
@ -735,6 +839,7 @@ that triggered the event, plus other pairs depending on the type of event
|
||||||
audited.
|
audited.
|
||||||
|
|
||||||
Bringup Mode
|
Bringup Mode
|
||||||
|
------------
|
||||||
|
|
||||||
Bringup mode provides logging features that can make application
|
Bringup mode provides logging features that can make application
|
||||||
configuration and system bringup easier. Configure the kernel with
|
configuration and system bringup easier. Configure the kernel with
|
|
@ -1,13 +1,14 @@
|
||||||
|
====
|
||||||
|
Yama
|
||||||
|
====
|
||||||
|
|
||||||
Yama is a Linux Security Module that collects system-wide DAC security
|
Yama is a Linux Security Module that collects system-wide DAC security
|
||||||
protections that are not handled by the core kernel itself. This is
|
protections that are not handled by the core kernel itself. This is
|
||||||
selectable at build-time with CONFIG_SECURITY_YAMA, and can be controlled
|
selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled
|
||||||
at run-time through sysctls in /proc/sys/kernel/yama:
|
at run-time through sysctls in ``/proc/sys/kernel/yama``:
|
||||||
|
|
||||||
- ptrace_scope
|
ptrace_scope
|
||||||
|
============
|
||||||
==============================================================
|
|
||||||
|
|
||||||
ptrace_scope:
|
|
||||||
|
|
||||||
As Linux grows in popularity, it will become a larger target for
|
As Linux grows in popularity, it will become a larger target for
|
||||||
malware. One particularly troubling weakness of the Linux process
|
malware. One particularly troubling weakness of the Linux process
|
||||||
|
@ -25,47 +26,49 @@ exist and remain possible if ptrace is allowed to operate as before.
|
||||||
Since ptrace is not commonly used by non-developers and non-admins, system
|
Since ptrace is not commonly used by non-developers and non-admins, system
|
||||||
builders should be allowed the option to disable this debugging system.
|
builders should be allowed the option to disable this debugging system.
|
||||||
|
|
||||||
For a solution, some applications use prctl(PR_SET_DUMPABLE, ...) to
|
For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to
|
||||||
specifically disallow such ptrace attachment (e.g. ssh-agent), but many
|
specifically disallow such ptrace attachment (e.g. ssh-agent), but many
|
||||||
do not. A more general solution is to only allow ptrace directly from a
|
do not. A more general solution is to only allow ptrace directly from a
|
||||||
parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still
|
parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still
|
||||||
work), or with CAP_SYS_PTRACE (i.e. "gdb --pid=PID", and "strace -p PID"
|
work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID"
|
||||||
still work as root).
|
still work as root).
|
||||||
|
|
||||||
In mode 1, software that has defined application-specific relationships
|
In mode 1, software that has defined application-specific relationships
|
||||||
between a debugging process and its inferior (crash handlers, etc),
|
between a debugging process and its inferior (crash handlers, etc),
|
||||||
prctl(PR_SET_PTRACER, pid, ...) can be used. An inferior can declare which
|
``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which
|
||||||
other process (and its descendants) are allowed to call PTRACE_ATTACH
|
other process (and its descendants) are allowed to call ``PTRACE_ATTACH``
|
||||||
against it. Only one such declared debugging process can exists for
|
against it. Only one such declared debugging process can exists for
|
||||||
each inferior at a time. For example, this is used by KDE, Chromium, and
|
each inferior at a time. For example, this is used by KDE, Chromium, and
|
||||||
Firefox's crash handlers, and by Wine for allowing only Wine processes
|
Firefox's crash handlers, and by Wine for allowing only Wine processes
|
||||||
to ptrace each other. If a process wishes to entirely disable these ptrace
|
to ptrace each other. If a process wishes to entirely disable these ptrace
|
||||||
restrictions, it can call prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)
|
restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)``
|
||||||
so that any otherwise allowed process (even those in external pid namespaces)
|
so that any otherwise allowed process (even those in external pid namespaces)
|
||||||
may attach.
|
may attach.
|
||||||
|
|
||||||
The sysctl settings (writable only with CAP_SYS_PTRACE) are:
|
The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are:
|
||||||
|
|
||||||
0 - classic ptrace permissions: a process can PTRACE_ATTACH to any other
|
0 - classic ptrace permissions:
|
||||||
|
a process can ``PTRACE_ATTACH`` to any other
|
||||||
process running under the same uid, as long as it is dumpable (i.e.
|
process running under the same uid, as long as it is dumpable (i.e.
|
||||||
did not transition uids, start privileged, or have called
|
did not transition uids, start privileged, or have called
|
||||||
prctl(PR_SET_DUMPABLE...) already). Similarly, PTRACE_TRACEME is
|
``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is
|
||||||
unchanged.
|
unchanged.
|
||||||
|
|
||||||
1 - restricted ptrace: a process must have a predefined relationship
|
1 - restricted ptrace:
|
||||||
with the inferior it wants to call PTRACE_ATTACH on. By default,
|
a process must have a predefined relationship
|
||||||
|
with the inferior it wants to call ``PTRACE_ATTACH`` on. By default,
|
||||||
this relationship is that of only its descendants when the above
|
this relationship is that of only its descendants when the above
|
||||||
classic criteria is also met. To change the relationship, an
|
classic criteria is also met. To change the relationship, an
|
||||||
inferior can call prctl(PR_SET_PTRACER, debugger, ...) to declare
|
inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare
|
||||||
an allowed debugger PID to call PTRACE_ATTACH on the inferior.
|
an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior.
|
||||||
Using PTRACE_TRACEME is unchanged.
|
Using ``PTRACE_TRACEME`` is unchanged.
|
||||||
|
|
||||||
2 - admin-only attach: only processes with CAP_SYS_PTRACE may use ptrace
|
2 - admin-only attach:
|
||||||
with PTRACE_ATTACH, or through children calling PTRACE_TRACEME.
|
only processes with ``CAP_SYS_PTRACE`` may use ptrace
|
||||||
|
with ``PTRACE_ATTACH``, or through children calling ``PTRACE_TRACEME``.
|
||||||
|
|
||||||
3 - no attach: no processes may use ptrace with PTRACE_ATTACH nor via
|
3 - no attach:
|
||||||
PTRACE_TRACEME. Once set, this sysctl value cannot be changed.
|
no processes may use ptrace with ``PTRACE_ATTACH`` nor via
|
||||||
|
``PTRACE_TRACEME``. Once set, this sysctl value cannot be changed.
|
||||||
|
|
||||||
The original children-only logic was based on the restrictions in grsecurity.
|
The original children-only logic was based on the restrictions in grsecurity.
|
||||||
|
|
||||||
==============================================================
|
|
|
@ -1,4 +1,9 @@
|
||||||
--- What is AppArmor? ---
|
========
|
||||||
|
AppArmor
|
||||||
|
========
|
||||||
|
|
||||||
|
What is AppArmor?
|
||||||
|
=================
|
||||||
|
|
||||||
AppArmor is MAC style security extension for the Linux kernel. It implements
|
AppArmor is MAC style security extension for the Linux kernel. It implements
|
||||||
a task centered policy, with task "profiles" being created and loaded
|
a task centered policy, with task "profiles" being created and loaded
|
||||||
|
@ -6,34 +11,41 @@ from user space. Tasks on the system that do not have a profile defined for
|
||||||
them run in an unconfined state which is equivalent to standard Linux DAC
|
them run in an unconfined state which is equivalent to standard Linux DAC
|
||||||
permissions.
|
permissions.
|
||||||
|
|
||||||
--- How to enable/disable ---
|
How to enable/disable
|
||||||
|
=====================
|
||||||
|
|
||||||
set CONFIG_SECURITY_APPARMOR=y
|
set ``CONFIG_SECURITY_APPARMOR=y``
|
||||||
|
|
||||||
If AppArmor should be selected as the default security module then
|
If AppArmor should be selected as the default security module then set::
|
||||||
set CONFIG_DEFAULT_SECURITY="apparmor"
|
|
||||||
and CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
|
CONFIG_DEFAULT_SECURITY="apparmor"
|
||||||
|
CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1
|
||||||
|
|
||||||
Build the kernel
|
Build the kernel
|
||||||
|
|
||||||
If AppArmor is not the default security module it can be enabled by passing
|
If AppArmor is not the default security module it can be enabled by passing
|
||||||
security=apparmor on the kernel's command line.
|
``security=apparmor`` on the kernel's command line.
|
||||||
|
|
||||||
If AppArmor is the default security module it can be disabled by passing
|
If AppArmor is the default security module it can be disabled by passing
|
||||||
apparmor=0, security=XXXX (where XXX is valid security module), on the
|
``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the
|
||||||
kernel's command line
|
kernel's command line.
|
||||||
|
|
||||||
For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
|
For AppArmor to enforce any restrictions beyond standard Linux DAC permissions
|
||||||
policy must be loaded into the kernel from user space (see the Documentation
|
policy must be loaded into the kernel from user space (see the Documentation
|
||||||
and tools links).
|
and tools links).
|
||||||
|
|
||||||
--- Documentation ---
|
Documentation
|
||||||
|
=============
|
||||||
|
|
||||||
Documentation can be found on the wiki.
|
Documentation can be found on the wiki, linked below.
|
||||||
|
|
||||||
--- Links ---
|
Links
|
||||||
|
=====
|
||||||
|
|
||||||
Mailing List - apparmor@lists.ubuntu.com
|
Mailing List - apparmor@lists.ubuntu.com
|
||||||
|
|
||||||
Wiki - http://apparmor.wiki.kernel.org/
|
Wiki - http://apparmor.wiki.kernel.org/
|
||||||
|
|
||||||
User space tools - https://launchpad.net/apparmor
|
User space tools - https://launchpad.net/apparmor
|
||||||
|
|
||||||
Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
|
Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/apparmor-dev.git
|
|
@ -1,12 +1,13 @@
|
||||||
Linux Security Module framework
|
===========================
|
||||||
-------------------------------
|
Linux Security Module Usage
|
||||||
|
===========================
|
||||||
|
|
||||||
The Linux Security Module (LSM) framework provides a mechanism for
|
The Linux Security Module (LSM) framework provides a mechanism for
|
||||||
various security checks to be hooked by new kernel extensions. The name
|
various security checks to be hooked by new kernel extensions. The name
|
||||||
"module" is a bit of a misnomer since these extensions are not actually
|
"module" is a bit of a misnomer since these extensions are not actually
|
||||||
loadable kernel modules. Instead, they are selectable at build-time via
|
loadable kernel modules. Instead, they are selectable at build-time via
|
||||||
CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
|
CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the
|
||||||
"security=..." kernel command line argument, in the case where multiple
|
``"security=..."`` kernel command line argument, in the case where multiple
|
||||||
LSMs were built into a given kernel.
|
LSMs were built into a given kernel.
|
||||||
|
|
||||||
The primary users of the LSM interface are Mandatory Access Control
|
The primary users of the LSM interface are Mandatory Access Control
|
||||||
|
@ -19,23 +20,22 @@ in the core functionality of Linux itself.
|
||||||
Without a specific LSM built into the kernel, the default LSM will be the
|
Without a specific LSM built into the kernel, the default LSM will be the
|
||||||
Linux capabilities system. Most LSMs choose to extend the capabilities
|
Linux capabilities system. Most LSMs choose to extend the capabilities
|
||||||
system, building their checks on top of the defined capability hooks.
|
system, building their checks on top of the defined capability hooks.
|
||||||
For more details on capabilities, see capabilities(7) in the Linux
|
For more details on capabilities, see ``capabilities(7)`` in the Linux
|
||||||
man-pages project.
|
man-pages project.
|
||||||
|
|
||||||
A list of the active security modules can be found by reading
|
A list of the active security modules can be found by reading
|
||||||
/sys/kernel/security/lsm. This is a comma separated list, and
|
``/sys/kernel/security/lsm``. This is a comma separated list, and
|
||||||
will always include the capability module. The list reflects the
|
will always include the capability module. The list reflects the
|
||||||
order in which checks are made. The capability module will always
|
order in which checks are made. The capability module will always
|
||||||
be first, followed by any "minor" modules (e.g. Yama) and then
|
be first, followed by any "minor" modules (e.g. Yama) and then
|
||||||
the one "major" module (e.g. SELinux) if there is one configured.
|
the one "major" module (e.g. SELinux) if there is one configured.
|
||||||
|
|
||||||
Based on https://lkml.org/lkml/2007/10/26/215,
|
.. toctree::
|
||||||
a new LSM is accepted into the kernel when its intent (a description of
|
:maxdepth: 1
|
||||||
what it tries to protect against and in what cases one would expect to
|
|
||||||
use it) has been appropriately documented in Documentation/security/.
|
|
||||||
This allows an LSM's code to be easily compared to its goals, and so
|
|
||||||
that end users and distros can make a more informed decision about which
|
|
||||||
LSMs suit their requirements.
|
|
||||||
|
|
||||||
For extensive documentation on the available LSM hook interfaces, please
|
apparmor
|
||||||
see include/linux/security.h.
|
LoadPin
|
||||||
|
SELinux
|
||||||
|
Smack
|
||||||
|
tomoyo
|
||||||
|
Yama
|
|
@ -1,21 +1,30 @@
|
||||||
--- What is TOMOYO? ---
|
======
|
||||||
|
TOMOYO
|
||||||
|
======
|
||||||
|
|
||||||
|
What is TOMOYO?
|
||||||
|
===============
|
||||||
|
|
||||||
TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel.
|
TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel.
|
||||||
|
|
||||||
LiveCD-based tutorials are available at
|
LiveCD-based tutorials are available at
|
||||||
|
|
||||||
http://tomoyo.sourceforge.jp/1.7/1st-step/ubuntu10.04-live/
|
http://tomoyo.sourceforge.jp/1.7/1st-step/ubuntu10.04-live/
|
||||||
http://tomoyo.sourceforge.jp/1.7/1st-step/centos5-live/ .
|
http://tomoyo.sourceforge.jp/1.7/1st-step/centos5-live/
|
||||||
|
|
||||||
Though these tutorials use non-LSM version of TOMOYO, they are useful for you
|
Though these tutorials use non-LSM version of TOMOYO, they are useful for you
|
||||||
to know what TOMOYO is.
|
to know what TOMOYO is.
|
||||||
|
|
||||||
--- How to enable TOMOYO? ---
|
How to enable TOMOYO?
|
||||||
|
=====================
|
||||||
|
|
||||||
Build the kernel with CONFIG_SECURITY_TOMOYO=y and pass "security=tomoyo" on
|
Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``security=tomoyo`` on
|
||||||
kernel's command line.
|
kernel's command line.
|
||||||
|
|
||||||
Please see http://tomoyo.sourceforge.jp/2.3/ for details.
|
Please see http://tomoyo.sourceforge.jp/2.3/ for details.
|
||||||
|
|
||||||
--- Where is documentation? ---
|
Where is documentation?
|
||||||
|
=======================
|
||||||
|
|
||||||
User <-> Kernel interface documentation is available at
|
User <-> Kernel interface documentation is available at
|
||||||
http://tomoyo.sourceforge.jp/2.3/policy-reference.html .
|
http://tomoyo.sourceforge.jp/2.3/policy-reference.html .
|
||||||
|
@ -42,7 +51,8 @@ History of TOMOYO?
|
||||||
Realities of Mainlining
|
Realities of Mainlining
|
||||||
http://sourceforge.jp/projects/tomoyo/docs/lfj2008.pdf
|
http://sourceforge.jp/projects/tomoyo/docs/lfj2008.pdf
|
||||||
|
|
||||||
--- What is future plan? ---
|
What is future plan?
|
||||||
|
====================
|
||||||
|
|
||||||
We believe that inode based security and name based security are complementary
|
We believe that inode based security and name based security are complementary
|
||||||
and both should be used together. But unfortunately, so far, we cannot enable
|
and both should be used together. But unfortunately, so far, we cannot enable
|
|
@ -55,12 +55,6 @@ Documentation
|
||||||
contains information about the problems, which may result by upgrading
|
contains information about the problems, which may result by upgrading
|
||||||
your kernel.
|
your kernel.
|
||||||
|
|
||||||
- The Documentation/DocBook/ subdirectory contains several guides for
|
|
||||||
kernel developers and users. These guides can be rendered in a
|
|
||||||
number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others.
|
|
||||||
After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``,
|
|
||||||
or ``make mandocs`` will render the documentation in the requested format.
|
|
||||||
|
|
||||||
Installing the kernel source
|
Installing the kernel source
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
|
|
|
@ -62,6 +62,7 @@ configure specific aspects of kernel behavior to your liking.
|
||||||
ras
|
ras
|
||||||
pm/index
|
pm/index
|
||||||
thunderbolt
|
thunderbolt
|
||||||
|
LSM/index
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
||||||
|
|
|
@ -727,7 +727,8 @@
|
||||||
See also Documentation/input/joystick-parport.txt
|
See also Documentation/input/joystick-parport.txt
|
||||||
|
|
||||||
ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
|
ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot
|
||||||
time. See Documentation/dynamic-debug-howto.txt for
|
time. See
|
||||||
|
Documentation/admin-guide/dynamic-debug-howto.rst for
|
||||||
details. Deprecated, see dyndbg.
|
details. Deprecated, see dyndbg.
|
||||||
|
|
||||||
debug [KNL] Enable kernel debugging (events log level).
|
debug [KNL] Enable kernel debugging (events log level).
|
||||||
|
@ -890,7 +891,8 @@
|
||||||
dyndbg[="val"] [KNL,DYNAMIC_DEBUG]
|
dyndbg[="val"] [KNL,DYNAMIC_DEBUG]
|
||||||
module.dyndbg[="val"]
|
module.dyndbg[="val"]
|
||||||
Enable debug messages at boot time. See
|
Enable debug messages at boot time. See
|
||||||
Documentation/dynamic-debug-howto.txt for details.
|
Documentation/admin-guide/dynamic-debug-howto.rst
|
||||||
|
for details.
|
||||||
|
|
||||||
nompx [X86] Disables Intel Memory Protection Extensions.
|
nompx [X86] Disables Intel Memory Protection Extensions.
|
||||||
See Documentation/x86/intel_mpx.txt for more
|
See Documentation/x86/intel_mpx.txt for more
|
||||||
|
|
|
@ -344,9 +344,9 @@ for more than 2 channels, like Fully Buffered DIMMs (FB-DIMMs) memory
|
||||||
controllers. The following example will assume 2 channels:
|
controllers. The following example will assume 2 channels:
|
||||||
|
|
||||||
+------------+-----------------------+
|
+------------+-----------------------+
|
||||||
| Chip | Channels |
|
| CS Rows | Channels |
|
||||||
| Select +-----------+-----------+
|
+------------+-----------+-----------+
|
||||||
| rows | ``ch0`` | ``ch1`` |
|
| | ``ch0`` | ``ch1`` |
|
||||||
+============+===========+===========+
|
+============+===========+===========+
|
||||||
| ``csrow0`` | DIMM_A0 | DIMM_B0 |
|
| ``csrow0`` | DIMM_A0 | DIMM_B0 |
|
||||||
+------------+ | |
|
+------------+ | |
|
||||||
|
@ -698,7 +698,7 @@ information indicating that errors have been detected::
|
||||||
The structure of the message is:
|
The structure of the message is:
|
||||||
|
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
| Content + Example |
|
| Content | Example |
|
||||||
+=======================================+=============+
|
+=======================================+=============+
|
||||||
| The memory controller | MC0 |
|
| The memory controller | MC0 |
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
|
@ -713,7 +713,7 @@ The structure of the message is:
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
| The error syndrome | 0xb741 |
|
| The error syndrome | 0xb741 |
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
| Memory row | row 0 +
|
| Memory row | row 0 |
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
| Memory channel | channel 1 |
|
| Memory channel | channel 1 |
|
||||||
+---------------------------------------+-------------+
|
+---------------------------------------+-------------+
|
||||||
|
|
|
@ -271,8 +271,7 @@ latex_elements = {
|
||||||
|
|
||||||
# Additional stuff for the LaTeX preamble.
|
# Additional stuff for the LaTeX preamble.
|
||||||
'preamble': '''
|
'preamble': '''
|
||||||
% Adjust margins
|
\\usepackage{ifthen}
|
||||||
\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
|
|
||||||
|
|
||||||
% Allow generate some pages in landscape
|
% Allow generate some pages in landscape
|
||||||
\\usepackage{lscape}
|
\\usepackage{lscape}
|
||||||
|
@ -281,6 +280,7 @@ latex_elements = {
|
||||||
\\definecolor{NoteColor}{RGB}{204,255,255}
|
\\definecolor{NoteColor}{RGB}{204,255,255}
|
||||||
\\definecolor{WarningColor}{RGB}{255,204,204}
|
\\definecolor{WarningColor}{RGB}{255,204,204}
|
||||||
\\definecolor{AttentionColor}{RGB}{255,255,204}
|
\\definecolor{AttentionColor}{RGB}{255,255,204}
|
||||||
|
\\definecolor{ImportantColor}{RGB}{192,255,204}
|
||||||
\\definecolor{OtherColor}{RGB}{204,204,204}
|
\\definecolor{OtherColor}{RGB}{204,204,204}
|
||||||
\\newlength{\\mynoticelength}
|
\\newlength{\\mynoticelength}
|
||||||
\\makeatletter\\newenvironment{coloredbox}[1]{%
|
\\makeatletter\\newenvironment{coloredbox}[1]{%
|
||||||
|
@ -301,7 +301,12 @@ latex_elements = {
|
||||||
\\ifthenelse%
|
\\ifthenelse%
|
||||||
{\\equal{\\py@noticetype}{attention}}%
|
{\\equal{\\py@noticetype}{attention}}%
|
||||||
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
|
{\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
|
||||||
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
|
{%
|
||||||
|
\\ifthenelse%
|
||||||
|
{\\equal{\\py@noticetype}{important}}%
|
||||||
|
{\\colorbox{ImportantColor}{\\usebox{\\@tempboxa}}}%
|
||||||
|
{\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
|
||||||
|
}%
|
||||||
}%
|
}%
|
||||||
}%
|
}%
|
||||||
}\\makeatother
|
}\\makeatother
|
||||||
|
@ -336,30 +341,51 @@ latex_elements = {
|
||||||
if major == 1 and minor > 3:
|
if major == 1 and minor > 3:
|
||||||
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
|
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
|
||||||
|
|
||||||
|
if major == 1 and minor <= 4:
|
||||||
|
latex_elements['preamble'] += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}'
|
||||||
|
elif major == 1 and (minor > 5 or (minor == 5 and patch >= 3)):
|
||||||
|
latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=0.5in'
|
||||||
|
|
||||||
|
|
||||||
# Grouping the document tree into LaTeX files. List of tuples
|
# Grouping the document tree into LaTeX files. List of tuples
|
||||||
# (source start file, target name, title,
|
# (source start file, target name, title,
|
||||||
# author, documentclass [howto, manual, or own class]).
|
# author, documentclass [howto, manual, or own class]).
|
||||||
|
# Sorted in alphabetical order
|
||||||
latex_documents = [
|
latex_documents = [
|
||||||
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
|
|
||||||
'The kernel development community', 'manual'),
|
|
||||||
('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
|
('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
('core-api/index', 'core-api.tex', 'The kernel core API manual',
|
('core-api/index', 'core-api.tex', 'The kernel core API manual',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
|
('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('dev-tools/index', 'dev-tools.tex', 'Development tools for the Kernel',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
|
('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
|
('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
|
||||||
'The kernel development community', 'manual'),
|
|
||||||
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
|
|
||||||
'The kernel development community', 'manual'),
|
|
||||||
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
|
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
|
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
|
('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To Hacking The Linux Kernel',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
|
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
|
('networking/index', 'networking.tex', 'Linux Networking Documentation',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
('security/index', 'security.tex', 'The kernel security subsystem manual',
|
('security/index', 'security.tex', 'The kernel security subsystem manual',
|
||||||
'The kernel development community', 'manual'),
|
'The kernel development community', 'manual'),
|
||||||
|
('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
]
|
]
|
||||||
|
|
||||||
# The name of an image file (relative to this directory) to place at the top of
|
# The name of an image file (relative to this directory) to place at the top of
|
||||||
|
|
|
@ -10,7 +10,10 @@ properties:
|
||||||
|
|
||||||
1. Objects are opaque pointers. The implementation does not care where they
|
1. Objects are opaque pointers. The implementation does not care where they
|
||||||
point (if anywhere) or what they point to (if anything).
|
point (if anywhere) or what they point to (if anything).
|
||||||
.. note:: Pointers to objects _must_ be zero in the least significant bit.
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Pointers to objects _must_ be zero in the least significant bit.
|
||||||
|
|
||||||
2. Objects do not need to contain linkage blocks for use by the array. This
|
2. Objects do not need to contain linkage blocks for use by the array. This
|
||||||
permits an object to be located in multiple arrays simultaneously.
|
permits an object to be located in multiple arrays simultaneously.
|
||||||
|
|
|
@ -19,6 +19,7 @@ Core utilities
|
||||||
workqueue
|
workqueue
|
||||||
genericirq
|
genericirq
|
||||||
flexible-arrays
|
flexible-arrays
|
||||||
|
librs
|
||||||
|
|
||||||
Interfaces for kernel debugging
|
Interfaces for kernel debugging
|
||||||
===============================
|
===============================
|
||||||
|
|
212
Documentation/core-api/librs.rst
Normal file
212
Documentation/core-api/librs.rst
Normal file
|
@ -0,0 +1,212 @@
|
||||||
|
==========================================
|
||||||
|
Reed-Solomon Library Programming Interface
|
||||||
|
==========================================
|
||||||
|
|
||||||
|
:Author: Thomas Gleixner
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
The generic Reed-Solomon Library provides encoding, decoding and error
|
||||||
|
correction functions.
|
||||||
|
|
||||||
|
Reed-Solomon codes are used in communication and storage applications to
|
||||||
|
ensure data integrity.
|
||||||
|
|
||||||
|
This documentation is provided for developers who want to utilize the
|
||||||
|
functions provided by the library.
|
||||||
|
|
||||||
|
Known Bugs And Assumptions
|
||||||
|
==========================
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
This chapter provides examples of how to use the library.
|
||||||
|
|
||||||
|
Initializing
|
||||||
|
------------
|
||||||
|
|
||||||
|
The init function init_rs returns a pointer to an rs decoder structure,
|
||||||
|
which holds the necessary information for encoding, decoding and error
|
||||||
|
correction with the given polynomial. It either uses an existing
|
||||||
|
matching decoder or creates a new one. On creation all the lookup tables
|
||||||
|
for fast en/decoding are created. The function may take a while, so make
|
||||||
|
sure not to call it in critical code paths.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* the Reed Solomon control structure */
|
||||||
|
static struct rs_control *rs_decoder;
|
||||||
|
|
||||||
|
/* Symbolsize is 10 (bits)
|
||||||
|
* Primitive polynomial is x^10+x^3+1
|
||||||
|
* first consecutive root is 0
|
||||||
|
* primitive element to generate roots = 1
|
||||||
|
* generator polynomial degree (number of roots) = 6
|
||||||
|
*/
|
||||||
|
rs_decoder = init_rs (10, 0x409, 0, 1, 6);
|
||||||
|
|
||||||
|
|
||||||
|
Encoding
|
||||||
|
--------
|
||||||
|
|
||||||
|
The encoder calculates the Reed-Solomon code over the given data length
|
||||||
|
and stores the result in the parity buffer. Note that the parity buffer
|
||||||
|
must be initialized before calling the encoder.
|
||||||
|
|
||||||
|
The expanded data can be inverted on the fly by providing a non-zero
|
||||||
|
inversion mask. The expanded data is XOR'ed with the mask. This is used
|
||||||
|
e.g. for FLASH ECC, where the all 0xFF is inverted to an all 0x00. The
|
||||||
|
Reed-Solomon code for all 0x00 is all 0x00. The code is inverted before
|
||||||
|
storing to FLASH so it is 0xFF too. This prevents that reading from an
|
||||||
|
erased FLASH results in ECC errors.
|
||||||
|
|
||||||
|
The databytes are expanded to the given symbol size on the fly. There is
|
||||||
|
no support for encoding continuous bitstreams with a symbol size != 8 at
|
||||||
|
the moment. If it is necessary it should be not a big deal to implement
|
||||||
|
such functionality.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6];
|
||||||
|
/* Initialize the parity buffer */
|
||||||
|
memset(par, 0, sizeof(par));
|
||||||
|
/* Encode 512 byte in data8. Store parity in buffer par */
|
||||||
|
encode_rs8 (rs_decoder, data8, 512, par, 0);
|
||||||
|
|
||||||
|
|
||||||
|
Decoding
|
||||||
|
--------
|
||||||
|
|
||||||
|
The decoder calculates the syndrome over the given data length and the
|
||||||
|
received parity symbols and corrects errors in the data.
|
||||||
|
|
||||||
|
If a syndrome is available from a hardware decoder then the syndrome
|
||||||
|
calculation is skipped.
|
||||||
|
|
||||||
|
The correction of the data buffer can be suppressed by providing a
|
||||||
|
correction pattern buffer and an error location buffer to the decoder.
|
||||||
|
The decoder stores the calculated error location and the correction
|
||||||
|
bitmask in the given buffers. This is useful for hardware decoders which
|
||||||
|
use a weird bit ordering scheme.
|
||||||
|
|
||||||
|
The databytes are expanded to the given symbol size on the fly. There is
|
||||||
|
no support for decoding continuous bitstreams with a symbolsize != 8 at
|
||||||
|
the moment. If it is necessary it should be not a big deal to implement
|
||||||
|
such functionality.
|
||||||
|
|
||||||
|
Decoding with syndrome calculation, direct data correction
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr;
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, data8, par, 512, NULL, 0, NULL, 0, NULL);
|
||||||
|
|
||||||
|
|
||||||
|
Decoding with syndrome given by hardware decoder, direct data correction
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6], syn[6];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr;
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Get syndrome from hardware decoder */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, data8, par, 512, syn, 0, NULL, 0, NULL);
|
||||||
|
|
||||||
|
|
||||||
|
Decoding with syndrome given by hardware decoder, no direct data correction.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Note: It's not necessary to give data and received parity to the
|
||||||
|
decoder.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* Parity buffer. Size = number of roots */
|
||||||
|
uint16_t par[6], syn[6], corr[8];
|
||||||
|
uint8_t data[512];
|
||||||
|
int numerr, errpos[8];
|
||||||
|
/* Receive data */
|
||||||
|
.....
|
||||||
|
/* Receive parity */
|
||||||
|
.....
|
||||||
|
/* Get syndrome from hardware decoder */
|
||||||
|
.....
|
||||||
|
/* Decode 512 byte in data8.*/
|
||||||
|
numerr = decode_rs8 (rs_decoder, NULL, NULL, 512, syn, 0, errpos, 0, corr);
|
||||||
|
for (i = 0; i < numerr; i++) {
|
||||||
|
do_error_correction_in_your_buffer(errpos[i], corr[i]);
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
Cleanup
|
||||||
|
-------
|
||||||
|
|
||||||
|
The function free_rs frees the allocated resources, if the caller is
|
||||||
|
the last user of the decoder.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
/* Release resources */
|
||||||
|
free_rs(rs_decoder);
|
||||||
|
|
||||||
|
|
||||||
|
Structures
|
||||||
|
==========
|
||||||
|
|
||||||
|
This chapter contains the autogenerated documentation of the structures
|
||||||
|
which are used in the Reed-Solomon Library and are relevant for a
|
||||||
|
developer.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/rslib.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Public Functions Provided
|
||||||
|
=========================
|
||||||
|
|
||||||
|
This chapter contains the autogenerated documentation of the
|
||||||
|
Reed-Solomon functions which are exported.
|
||||||
|
|
||||||
|
.. kernel-doc:: lib/reed_solomon/reed_solomon.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Credits
|
||||||
|
=======
|
||||||
|
|
||||||
|
The library code for encoding and decoding was written by Phil Karn.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
Copyright 2002, Phil Karn, KA9Q
|
||||||
|
May be used under the terms of the GNU General Public License (GPL)
|
||||||
|
|
||||||
|
|
||||||
|
The wrapper functions and interfaces are written by Thomas Gleixner.
|
||||||
|
|
||||||
|
Many users have provided bugfixes, improvements and helping hands for
|
||||||
|
testing. Thanks a lot.
|
||||||
|
|
||||||
|
The following people have contributed to this document:
|
||||||
|
|
||||||
|
Thomas Gleixner\ tglx@linutronix.de
|
|
@ -265,7 +265,7 @@ mandatory:
|
||||||
|
|
||||||
The caller passes a pointer to the following struct with all of the fields
|
The caller passes a pointer to the following struct with all of the fields
|
||||||
cleared, except for data, datalen and quotalen [see
|
cleared, except for data, datalen and quotalen [see
|
||||||
Documentation/security/keys.txt].
|
Documentation/security/keys/core.rst].
|
||||||
|
|
||||||
struct key_preparsed_payload {
|
struct key_preparsed_payload {
|
||||||
char *description;
|
char *description;
|
||||||
|
|
10
Documentation/crypto/conf.py
Normal file
10
Documentation/crypto/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = 'Linux Kernel Crypto API'
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
|
@ -23,6 +23,7 @@ whole; patches welcome!
|
||||||
kmemleak
|
kmemleak
|
||||||
kmemcheck
|
kmemcheck
|
||||||
gdb-kernel-debugging
|
gdb-kernel-debugging
|
||||||
|
kgdb
|
||||||
|
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
907
Documentation/dev-tools/kgdb.rst
Normal file
907
Documentation/dev-tools/kgdb.rst
Normal file
|
@ -0,0 +1,907 @@
|
||||||
|
=================================================
|
||||||
|
Using kgdb, kdb and the kernel debugger internals
|
||||||
|
=================================================
|
||||||
|
|
||||||
|
:Author: Jason Wessel
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
The kernel has two different debugger front ends (kdb and kgdb) which
|
||||||
|
interface to the debug core. It is possible to use either of the
|
||||||
|
debugger front ends and dynamically transition between them if you
|
||||||
|
configure the kernel properly at compile and runtime.
|
||||||
|
|
||||||
|
Kdb is simplistic shell-style interface which you can use on a system
|
||||||
|
console with a keyboard or serial console. You can use it to inspect
|
||||||
|
memory, registers, process lists, dmesg, and even set breakpoints to
|
||||||
|
stop in a certain location. Kdb is not a source level debugger, although
|
||||||
|
you can set breakpoints and execute some basic kernel run control. Kdb
|
||||||
|
is mainly aimed at doing some analysis to aid in development or
|
||||||
|
diagnosing kernel problems. You can access some symbols by name in
|
||||||
|
kernel built-ins or in kernel modules if the code was built with
|
||||||
|
``CONFIG_KALLSYMS``.
|
||||||
|
|
||||||
|
Kgdb is intended to be used as a source level debugger for the Linux
|
||||||
|
kernel. It is used along with gdb to debug a Linux kernel. The
|
||||||
|
expectation is that gdb can be used to "break in" to the kernel to
|
||||||
|
inspect memory, variables and look through call stack information
|
||||||
|
similar to the way an application developer would use gdb to debug an
|
||||||
|
application. It is possible to place breakpoints in kernel code and
|
||||||
|
perform some limited execution stepping.
|
||||||
|
|
||||||
|
Two machines are required for using kgdb. One of these machines is a
|
||||||
|
development machine and the other is the target machine. The kernel to
|
||||||
|
be debugged runs on the target machine. The development machine runs an
|
||||||
|
instance of gdb against the vmlinux file which contains the symbols (not
|
||||||
|
a boot image such as bzImage, zImage, uImage...). In gdb the developer
|
||||||
|
specifies the connection parameters and connects to kgdb. The type of
|
||||||
|
connection a developer makes with gdb depends on the availability of
|
||||||
|
kgdb I/O modules compiled as built-ins or loadable kernel modules in the
|
||||||
|
test machine's kernel.
|
||||||
|
|
||||||
|
Compiling a kernel
|
||||||
|
==================
|
||||||
|
|
||||||
|
- In order to enable compilation of kdb, you must first enable kgdb.
|
||||||
|
|
||||||
|
- The kgdb test compile options are described in the kgdb test suite
|
||||||
|
chapter.
|
||||||
|
|
||||||
|
Kernel config options for kgdb
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
To enable ``CONFIG_KGDB`` you should look under
|
||||||
|
:menuselection:`Kernel hacking --> Kernel debugging` and select
|
||||||
|
:menuselection:`KGDB: kernel debugger`.
|
||||||
|
|
||||||
|
While it is not a hard requirement that you have symbols in your vmlinux
|
||||||
|
file, gdb tends not to be very useful without the symbolic data, so you
|
||||||
|
will want to turn on ``CONFIG_DEBUG_INFO`` which is called
|
||||||
|
:menuselection:`Compile the kernel with debug info` in the config menu.
|
||||||
|
|
||||||
|
It is advised, but not required, that you turn on the
|
||||||
|
``CONFIG_FRAME_POINTER`` kernel option which is called :menuselection:`Compile
|
||||||
|
the kernel with frame pointers` in the config menu. This option inserts code
|
||||||
|
to into the compiled executable which saves the frame information in
|
||||||
|
registers or on the stack at different points which allows a debugger
|
||||||
|
such as gdb to more accurately construct stack back traces while
|
||||||
|
debugging the kernel.
|
||||||
|
|
||||||
|
If the architecture that you are using supports the kernel option
|
||||||
|
``CONFIG_STRICT_KERNEL_RWX``, you should consider turning it off. This
|
||||||
|
option will prevent the use of software breakpoints because it marks
|
||||||
|
certain regions of the kernel's memory space as read-only. If kgdb
|
||||||
|
supports it for the architecture you are using, you can use hardware
|
||||||
|
breakpoints if you desire to run with the ``CONFIG_STRICT_KERNEL_RWX``
|
||||||
|
option turned on, else you need to turn off this option.
|
||||||
|
|
||||||
|
Next you should choose one of more I/O drivers to interconnect debugging
|
||||||
|
host and debugged target. Early boot debugging requires a KGDB I/O
|
||||||
|
driver that supports early debugging and the driver must be built into
|
||||||
|
the kernel directly. Kgdb I/O driver configuration takes place via
|
||||||
|
kernel or module parameters which you can learn more about in the in the
|
||||||
|
section that describes the parameter kgdboc.
|
||||||
|
|
||||||
|
Here is an example set of ``.config`` symbols to enable or disable for kgdb::
|
||||||
|
|
||||||
|
# CONFIG_STRICT_KERNEL_RWX is not set
|
||||||
|
CONFIG_FRAME_POINTER=y
|
||||||
|
CONFIG_KGDB=y
|
||||||
|
CONFIG_KGDB_SERIAL_CONSOLE=y
|
||||||
|
|
||||||
|
Kernel config options for kdb
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Kdb is quite a bit more complex than the simple gdbstub sitting on top
|
||||||
|
of the kernel's debug core. Kdb must implement a shell, and also adds
|
||||||
|
some helper functions in other parts of the kernel, responsible for
|
||||||
|
printing out interesting data such as what you would see if you ran
|
||||||
|
``lsmod``, or ``ps``. In order to build kdb into the kernel you follow the
|
||||||
|
same steps as you would for kgdb.
|
||||||
|
|
||||||
|
The main config option for kdb is ``CONFIG_KGDB_KDB`` which is called
|
||||||
|
:menuselection:`KGDB_KDB: include kdb frontend for kgdb` in the config menu.
|
||||||
|
In theory you would have already also selected an I/O driver such as the
|
||||||
|
``CONFIG_KGDB_SERIAL_CONSOLE`` interface if you plan on using kdb on a
|
||||||
|
serial port, when you were configuring kgdb.
|
||||||
|
|
||||||
|
If you want to use a PS/2-style keyboard with kdb, you would select
|
||||||
|
``CONFIG_KDB_KEYBOARD`` which is called :menuselection:`KGDB_KDB: keyboard as
|
||||||
|
input device` in the config menu. The ``CONFIG_KDB_KEYBOARD`` option is not
|
||||||
|
used for anything in the gdb interface to kgdb. The ``CONFIG_KDB_KEYBOARD``
|
||||||
|
option only works with kdb.
|
||||||
|
|
||||||
|
Here is an example set of ``.config`` symbols to enable/disable kdb::
|
||||||
|
|
||||||
|
# CONFIG_STRICT_KERNEL_RWX is not set
|
||||||
|
CONFIG_FRAME_POINTER=y
|
||||||
|
CONFIG_KGDB=y
|
||||||
|
CONFIG_KGDB_SERIAL_CONSOLE=y
|
||||||
|
CONFIG_KGDB_KDB=y
|
||||||
|
CONFIG_KDB_KEYBOARD=y
|
||||||
|
|
||||||
|
Kernel Debugger Boot Arguments
|
||||||
|
==============================
|
||||||
|
|
||||||
|
This section describes the various runtime kernel parameters that affect
|
||||||
|
the configuration of the kernel debugger. The following chapter covers
|
||||||
|
using kdb and kgdb as well as providing some examples of the
|
||||||
|
configuration parameters.
|
||||||
|
|
||||||
|
Kernel parameter: kgdboc
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
The kgdboc driver was originally an abbreviation meant to stand for
|
||||||
|
"kgdb over console". Today it is the primary mechanism to configure how
|
||||||
|
to communicate from gdb to kgdb as well as the devices you want to use
|
||||||
|
to interact with the kdb shell.
|
||||||
|
|
||||||
|
For kgdb/gdb, kgdboc is designed to work with a single serial port. It
|
||||||
|
is intended to cover the circumstance where you want to use a serial
|
||||||
|
console as your primary console as well as using it to perform kernel
|
||||||
|
debugging. It is also possible to use kgdb on a serial port which is not
|
||||||
|
designated as a system console. Kgdboc may be configured as a kernel
|
||||||
|
built-in or a kernel loadable module. You can only make use of
|
||||||
|
``kgdbwait`` and early debugging if you build kgdboc into the kernel as
|
||||||
|
a built-in.
|
||||||
|
|
||||||
|
Optionally you can elect to activate kms (Kernel Mode Setting)
|
||||||
|
integration. When you use kms with kgdboc and you have a video driver
|
||||||
|
that has atomic mode setting hooks, it is possible to enter the debugger
|
||||||
|
on the graphics console. When the kernel execution is resumed, the
|
||||||
|
previous graphics mode will be restored. This integration can serve as a
|
||||||
|
useful tool to aid in diagnosing crashes or doing analysis of memory
|
||||||
|
with kdb while allowing the full graphics console applications to run.
|
||||||
|
|
||||||
|
kgdboc arguments
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Usage::
|
||||||
|
|
||||||
|
kgdboc=[kms][[,]kbd][[,]serial_device][,baud]
|
||||||
|
|
||||||
|
The order listed above must be observed if you use any of the optional
|
||||||
|
configurations together.
|
||||||
|
|
||||||
|
Abbreviations:
|
||||||
|
|
||||||
|
- kms = Kernel Mode Setting
|
||||||
|
|
||||||
|
- kbd = Keyboard
|
||||||
|
|
||||||
|
You can configure kgdboc to use the keyboard, and/or a serial device
|
||||||
|
depending on if you are using kdb and/or kgdb, in one of the following
|
||||||
|
scenarios. The order listed above must be observed if you use any of the
|
||||||
|
optional configurations together. Using kms + only gdb is generally not
|
||||||
|
a useful combination.
|
||||||
|
|
||||||
|
Using loadable module or built-in
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
1. As a kernel built-in:
|
||||||
|
|
||||||
|
Use the kernel boot argument::
|
||||||
|
|
||||||
|
kgdboc=<tty-device>,[baud]
|
||||||
|
|
||||||
|
2. As a kernel loadable module:
|
||||||
|
|
||||||
|
Use the command::
|
||||||
|
|
||||||
|
modprobe kgdboc kgdboc=<tty-device>,[baud]
|
||||||
|
|
||||||
|
Here are two examples of how you might format the kgdboc string. The
|
||||||
|
first is for an x86 target using the first serial port. The second
|
||||||
|
example is for the ARM Versatile AB using the second serial port.
|
||||||
|
|
||||||
|
1. ``kgdboc=ttyS0,115200``
|
||||||
|
|
||||||
|
2. ``kgdboc=ttyAMA1,115200``
|
||||||
|
|
||||||
|
Configure kgdboc at runtime with sysfs
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
At run time you can enable or disable kgdboc by echoing a parameters
|
||||||
|
into the sysfs. Here are two examples:
|
||||||
|
|
||||||
|
1. Enable kgdboc on ttyS0::
|
||||||
|
|
||||||
|
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
|
||||||
|
|
||||||
|
2. Disable kgdboc::
|
||||||
|
|
||||||
|
echo "" > /sys/module/kgdboc/parameters/kgdboc
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
You do not need to specify the baud if you are configuring the
|
||||||
|
console on tty which is already configured or open.
|
||||||
|
|
||||||
|
More examples
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
You can configure kgdboc to use the keyboard, and/or a serial device
|
||||||
|
depending on if you are using kdb and/or kgdb, in one of the following
|
||||||
|
scenarios.
|
||||||
|
|
||||||
|
1. kdb and kgdb over only a serial port::
|
||||||
|
|
||||||
|
kgdboc=<serial_device>[,baud]
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
kgdboc=ttyS0,115200
|
||||||
|
|
||||||
|
2. kdb and kgdb with keyboard and a serial port::
|
||||||
|
|
||||||
|
kgdboc=kbd,<serial_device>[,baud]
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
kgdboc=kbd,ttyS0,115200
|
||||||
|
|
||||||
|
3. kdb with a keyboard::
|
||||||
|
|
||||||
|
kgdboc=kbd
|
||||||
|
|
||||||
|
4. kdb with kernel mode setting::
|
||||||
|
|
||||||
|
kgdboc=kms,kbd
|
||||||
|
|
||||||
|
5. kdb with kernel mode setting and kgdb over a serial port::
|
||||||
|
|
||||||
|
kgdboc=kms,kbd,ttyS0,115200
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Kgdboc does not support interrupting the target via the gdb remote
|
||||||
|
protocol. You must manually send a :kbd:`SysRq-G` unless you have a proxy
|
||||||
|
that splits console output to a terminal program. A console proxy has a
|
||||||
|
separate TCP port for the debugger and a separate TCP port for the
|
||||||
|
"human" console. The proxy can take care of sending the :kbd:`SysRq-G`
|
||||||
|
for you.
|
||||||
|
|
||||||
|
When using kgdboc with no debugger proxy, you can end up connecting the
|
||||||
|
debugger at one of two entry points. If an exception occurs after you
|
||||||
|
have loaded kgdboc, a message should print on the console stating it is
|
||||||
|
waiting for the debugger. In this case you disconnect your terminal
|
||||||
|
program and then connect the debugger in its place. If you want to
|
||||||
|
interrupt the target system and forcibly enter a debug session you have
|
||||||
|
to issue a :kbd:`Sysrq` sequence and then type the letter :kbd:`g`. Then you
|
||||||
|
disconnect the terminal session and connect gdb. Your options if you
|
||||||
|
don't like this are to hack gdb to send the :kbd:`SysRq-G` for you as well as
|
||||||
|
on the initial connect, or to use a debugger proxy that allows an
|
||||||
|
unmodified gdb to do the debugging.
|
||||||
|
|
||||||
|
Kernel parameter: ``kgdbwait``
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
The Kernel command line option ``kgdbwait`` makes kgdb wait for a
|
||||||
|
debugger connection during booting of a kernel. You can only use this
|
||||||
|
option if you compiled a kgdb I/O driver into the kernel and you
|
||||||
|
specified the I/O driver configuration as a kernel command line option.
|
||||||
|
The kgdbwait parameter should always follow the configuration parameter
|
||||||
|
for the kgdb I/O driver in the kernel command line else the I/O driver
|
||||||
|
will not be configured prior to asking the kernel to use it to wait.
|
||||||
|
|
||||||
|
The kernel will stop and wait as early as the I/O driver and
|
||||||
|
architecture allows when you use this option. If you build the kgdb I/O
|
||||||
|
driver as a loadable kernel module kgdbwait will not do anything.
|
||||||
|
|
||||||
|
Kernel parameter: ``kgdbcon``
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
The ``kgdbcon`` feature allows you to see :c:func:`printk` messages inside gdb
|
||||||
|
while gdb is connected to the kernel. Kdb does not make use of the kgdbcon
|
||||||
|
feature.
|
||||||
|
|
||||||
|
Kgdb supports using the gdb serial protocol to send console messages to
|
||||||
|
the debugger when the debugger is connected and running. There are two
|
||||||
|
ways to activate this feature.
|
||||||
|
|
||||||
|
1. Activate with the kernel command line option::
|
||||||
|
|
||||||
|
kgdbcon
|
||||||
|
|
||||||
|
2. Use sysfs before configuring an I/O driver::
|
||||||
|
|
||||||
|
echo 1 > /sys/module/kgdb/parameters/kgdb_use_con
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
If you do this after you configure the kgdb I/O driver, the
|
||||||
|
setting will not take effect until the next point the I/O is
|
||||||
|
reconfigured.
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
You cannot use kgdboc + kgdbcon on a tty that is an
|
||||||
|
active system console. An example of incorrect usage is::
|
||||||
|
|
||||||
|
console=ttyS0,115200 kgdboc=ttyS0 kgdbcon
|
||||||
|
|
||||||
|
It is possible to use this option with kgdboc on a tty that is not a
|
||||||
|
system console.
|
||||||
|
|
||||||
|
Run time parameter: ``kgdbreboot``
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
The kgdbreboot feature allows you to change how the debugger deals with
|
||||||
|
the reboot notification. You have 3 choices for the behavior. The
|
||||||
|
default behavior is always set to 0.
|
||||||
|
|
||||||
|
.. tabularcolumns:: |p{0.4cm}|p{11.5cm}|p{5.6cm}|
|
||||||
|
|
||||||
|
.. flat-table::
|
||||||
|
:widths: 1 10 8
|
||||||
|
|
||||||
|
* - 1
|
||||||
|
- ``echo -1 > /sys/module/debug_core/parameters/kgdbreboot``
|
||||||
|
- Ignore the reboot notification entirely.
|
||||||
|
|
||||||
|
* - 2
|
||||||
|
- ``echo 0 > /sys/module/debug_core/parameters/kgdbreboot``
|
||||||
|
- Send the detach message to any attached debugger client.
|
||||||
|
|
||||||
|
* - 3
|
||||||
|
- ``echo 1 > /sys/module/debug_core/parameters/kgdbreboot``
|
||||||
|
- Enter the debugger on reboot notify.
|
||||||
|
|
||||||
|
Using kdb
|
||||||
|
=========
|
||||||
|
|
||||||
|
Quick start for kdb on a serial port
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
This is a quick example of how to use kdb.
|
||||||
|
|
||||||
|
1. Configure kgdboc at boot using kernel parameters::
|
||||||
|
|
||||||
|
console=ttyS0,115200 kgdboc=ttyS0,115200
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
Configure kgdboc after the kernel has booted; assuming you are using
|
||||||
|
a serial port console::
|
||||||
|
|
||||||
|
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
|
||||||
|
|
||||||
|
2. Enter the kernel debugger manually or by waiting for an oops or
|
||||||
|
fault. There are several ways you can enter the kernel debugger
|
||||||
|
manually; all involve using the :kbd:`SysRq-G`, which means you must have
|
||||||
|
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
|
||||||
|
|
||||||
|
- When logged in as root or with a super user session you can run::
|
||||||
|
|
||||||
|
echo g > /proc/sysrq-trigger
|
||||||
|
|
||||||
|
- Example using minicom 2.2
|
||||||
|
|
||||||
|
Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
|
||||||
|
|
||||||
|
- When you have telneted to a terminal server that supports sending
|
||||||
|
a remote break
|
||||||
|
|
||||||
|
Press: :kbd:`CTRL-]`
|
||||||
|
|
||||||
|
Type in: ``send break``
|
||||||
|
|
||||||
|
Press: :kbd:`Enter` :kbd:`g`
|
||||||
|
|
||||||
|
3. From the kdb prompt you can run the ``help`` command to see a complete
|
||||||
|
list of the commands that are available.
|
||||||
|
|
||||||
|
Some useful commands in kdb include:
|
||||||
|
|
||||||
|
=========== =================================================================
|
||||||
|
``lsmod`` Shows where kernel modules are loaded
|
||||||
|
``ps`` Displays only the active processes
|
||||||
|
``ps A`` Shows all the processes
|
||||||
|
``summary`` Shows kernel version info and memory usage
|
||||||
|
``bt`` Get a backtrace of the current process using :c:func:`dump_stack`
|
||||||
|
``dmesg`` View the kernel syslog buffer
|
||||||
|
``go`` Continue the system
|
||||||
|
=========== =================================================================
|
||||||
|
|
||||||
|
4. When you are done using kdb you need to consider rebooting the system
|
||||||
|
or using the ``go`` command to resuming normal kernel execution. If you
|
||||||
|
have paused the kernel for a lengthy period of time, applications
|
||||||
|
that rely on timely networking or anything to do with real wall clock
|
||||||
|
time could be adversely affected, so you should take this into
|
||||||
|
consideration when using the kernel debugger.
|
||||||
|
|
||||||
|
Quick start for kdb using a keyboard connected console
|
||||||
|
------------------------------------------------------
|
||||||
|
|
||||||
|
This is a quick example of how to use kdb with a keyboard.
|
||||||
|
|
||||||
|
1. Configure kgdboc at boot using kernel parameters::
|
||||||
|
|
||||||
|
kgdboc=kbd
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
Configure kgdboc after the kernel has booted::
|
||||||
|
|
||||||
|
echo kbd > /sys/module/kgdboc/parameters/kgdboc
|
||||||
|
|
||||||
|
2. Enter the kernel debugger manually or by waiting for an oops or
|
||||||
|
fault. There are several ways you can enter the kernel debugger
|
||||||
|
manually; all involve using the :kbd:`SysRq-G`, which means you must have
|
||||||
|
enabled ``CONFIG_MAGIC_SysRq=y`` in your kernel config.
|
||||||
|
|
||||||
|
- When logged in as root or with a super user session you can run::
|
||||||
|
|
||||||
|
echo g > /proc/sysrq-trigger
|
||||||
|
|
||||||
|
- Example using a laptop keyboard:
|
||||||
|
|
||||||
|
Press and hold down: :kbd:`Alt`
|
||||||
|
|
||||||
|
Press and hold down: :kbd:`Fn`
|
||||||
|
|
||||||
|
Press and release the key with the label: :kbd:`SysRq`
|
||||||
|
|
||||||
|
Release: :kbd:`Fn`
|
||||||
|
|
||||||
|
Press and release: :kbd:`g`
|
||||||
|
|
||||||
|
Release: :kbd:`Alt`
|
||||||
|
|
||||||
|
- Example using a PS/2 101-key keyboard
|
||||||
|
|
||||||
|
Press and hold down: :kbd:`Alt`
|
||||||
|
|
||||||
|
Press and release the key with the label: :kbd:`SysRq`
|
||||||
|
|
||||||
|
Press and release: :kbd:`g`
|
||||||
|
|
||||||
|
Release: :kbd:`Alt`
|
||||||
|
|
||||||
|
3. Now type in a kdb command such as ``help``, ``dmesg``, ``bt`` or ``go`` to
|
||||||
|
continue kernel execution.
|
||||||
|
|
||||||
|
Using kgdb / gdb
|
||||||
|
================
|
||||||
|
|
||||||
|
In order to use kgdb you must activate it by passing configuration
|
||||||
|
information to one of the kgdb I/O drivers. If you do not pass any
|
||||||
|
configuration information kgdb will not do anything at all. Kgdb will
|
||||||
|
only actively hook up to the kernel trap hooks if a kgdb I/O driver is
|
||||||
|
loaded and configured. If you unconfigure a kgdb I/O driver, kgdb will
|
||||||
|
unregister all the kernel hook points.
|
||||||
|
|
||||||
|
All kgdb I/O drivers can be reconfigured at run time, if
|
||||||
|
``CONFIG_SYSFS`` and ``CONFIG_MODULES`` are enabled, by echo'ing a new
|
||||||
|
config string to ``/sys/module/<driver>/parameter/<option>``. The driver
|
||||||
|
can be unconfigured by passing an empty string. You cannot change the
|
||||||
|
configuration while the debugger is attached. Make sure to detach the
|
||||||
|
debugger with the ``detach`` command prior to trying to unconfigure a
|
||||||
|
kgdb I/O driver.
|
||||||
|
|
||||||
|
Connecting with gdb to a serial port
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
1. Configure kgdboc
|
||||||
|
|
||||||
|
Configure kgdboc at boot using kernel parameters::
|
||||||
|
|
||||||
|
kgdboc=ttyS0,115200
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
Configure kgdboc after the kernel has booted::
|
||||||
|
|
||||||
|
echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc
|
||||||
|
|
||||||
|
2. Stop kernel execution (break into the debugger)
|
||||||
|
|
||||||
|
In order to connect to gdb via kgdboc, the kernel must first be
|
||||||
|
stopped. There are several ways to stop the kernel which include
|
||||||
|
using kgdbwait as a boot argument, via a :kbd:`SysRq-G`, or running the
|
||||||
|
kernel until it takes an exception where it waits for the debugger to
|
||||||
|
attach.
|
||||||
|
|
||||||
|
- When logged in as root or with a super user session you can run::
|
||||||
|
|
||||||
|
echo g > /proc/sysrq-trigger
|
||||||
|
|
||||||
|
- Example using minicom 2.2
|
||||||
|
|
||||||
|
Press: :kbd:`CTRL-A` :kbd:`f` :kbd:`g`
|
||||||
|
|
||||||
|
- When you have telneted to a terminal server that supports sending
|
||||||
|
a remote break
|
||||||
|
|
||||||
|
Press: :kbd:`CTRL-]`
|
||||||
|
|
||||||
|
Type in: ``send break``
|
||||||
|
|
||||||
|
Press: :kbd:`Enter` :kbd:`g`
|
||||||
|
|
||||||
|
3. Connect from gdb
|
||||||
|
|
||||||
|
Example (using a directly connected port)::
|
||||||
|
|
||||||
|
% gdb ./vmlinux
|
||||||
|
(gdb) set remotebaud 115200
|
||||||
|
(gdb) target remote /dev/ttyS0
|
||||||
|
|
||||||
|
|
||||||
|
Example (kgdb to a terminal server on TCP port 2012)::
|
||||||
|
|
||||||
|
% gdb ./vmlinux
|
||||||
|
(gdb) target remote 192.168.2.2:2012
|
||||||
|
|
||||||
|
|
||||||
|
Once connected, you can debug a kernel the way you would debug an
|
||||||
|
application program.
|
||||||
|
|
||||||
|
If you are having problems connecting or something is going seriously
|
||||||
|
wrong while debugging, it will most often be the case that you want
|
||||||
|
to enable gdb to be verbose about its target communications. You do
|
||||||
|
this prior to issuing the ``target remote`` command by typing in::
|
||||||
|
|
||||||
|
set debug remote 1
|
||||||
|
|
||||||
|
Remember if you continue in gdb, and need to "break in" again, you need
|
||||||
|
to issue an other :kbd:`SysRq-G`. It is easy to create a simple entry point by
|
||||||
|
putting a breakpoint at ``sys_sync`` and then you can run ``sync`` from a
|
||||||
|
shell or script to break into the debugger.
|
||||||
|
|
||||||
|
kgdb and kdb interoperability
|
||||||
|
=============================
|
||||||
|
|
||||||
|
It is possible to transition between kdb and kgdb dynamically. The debug
|
||||||
|
core will remember which you used the last time and automatically start
|
||||||
|
in the same mode.
|
||||||
|
|
||||||
|
Switching between kdb and kgdb
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
Switching from kgdb to kdb
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
There are two ways to switch from kgdb to kdb: you can use gdb to issue
|
||||||
|
a maintenance packet, or you can blindly type the command ``$3#33``.
|
||||||
|
Whenever the kernel debugger stops in kgdb mode it will print the
|
||||||
|
message ``KGDB or $3#33 for KDB``. It is important to note that you have
|
||||||
|
to type the sequence correctly in one pass. You cannot type a backspace
|
||||||
|
or delete because kgdb will interpret that as part of the debug stream.
|
||||||
|
|
||||||
|
1. Change from kgdb to kdb by blindly typing::
|
||||||
|
|
||||||
|
$3#33
|
||||||
|
|
||||||
|
2. Change from kgdb to kdb with gdb::
|
||||||
|
|
||||||
|
maintenance packet 3
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Now you must kill gdb. Typically you press :kbd:`CTRL-Z` and issue
|
||||||
|
the command::
|
||||||
|
|
||||||
|
kill -9 %
|
||||||
|
|
||||||
|
Change from kdb to kgdb
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
There are two ways you can change from kdb to kgdb. You can manually
|
||||||
|
enter kgdb mode by issuing the kgdb command from the kdb shell prompt,
|
||||||
|
or you can connect gdb while the kdb shell prompt is active. The kdb
|
||||||
|
shell looks for the typical first commands that gdb would issue with the
|
||||||
|
gdb remote protocol and if it sees one of those commands it
|
||||||
|
automatically changes into kgdb mode.
|
||||||
|
|
||||||
|
1. From kdb issue the command::
|
||||||
|
|
||||||
|
kgdb
|
||||||
|
|
||||||
|
Now disconnect your terminal program and connect gdb in its place
|
||||||
|
|
||||||
|
2. At the kdb prompt, disconnect the terminal program and connect gdb in
|
||||||
|
its place.
|
||||||
|
|
||||||
|
Running kdb commands from gdb
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
It is possible to run a limited set of kdb commands from gdb, using the
|
||||||
|
gdb monitor command. You don't want to execute any of the run control or
|
||||||
|
breakpoint operations, because it can disrupt the state of the kernel
|
||||||
|
debugger. You should be using gdb for breakpoints and run control
|
||||||
|
operations if you have gdb connected. The more useful commands to run
|
||||||
|
are things like lsmod, dmesg, ps or possibly some of the memory
|
||||||
|
information commands. To see all the kdb commands you can run
|
||||||
|
``monitor help``.
|
||||||
|
|
||||||
|
Example::
|
||||||
|
|
||||||
|
(gdb) monitor ps
|
||||||
|
1 idle process (state I) and
|
||||||
|
27 sleeping system daemon (state M) processes suppressed,
|
||||||
|
use 'ps A' to see all.
|
||||||
|
Task Addr Pid Parent [*] cpu State Thread Command
|
||||||
|
|
||||||
|
0xc78291d0 1 0 0 0 S 0xc7829404 init
|
||||||
|
0xc7954150 942 1 0 0 S 0xc7954384 dropbear
|
||||||
|
0xc78789c0 944 1 0 0 S 0xc7878bf4 sh
|
||||||
|
(gdb)
|
||||||
|
|
||||||
|
kgdb Test Suite
|
||||||
|
===============
|
||||||
|
|
||||||
|
When kgdb is enabled in the kernel config you can also elect to enable
|
||||||
|
the config parameter ``KGDB_TESTS``. Turning this on will enable a special
|
||||||
|
kgdb I/O module which is designed to test the kgdb internal functions.
|
||||||
|
|
||||||
|
The kgdb tests are mainly intended for developers to test the kgdb
|
||||||
|
internals as well as a tool for developing a new kgdb architecture
|
||||||
|
specific implementation. These tests are not really for end users of the
|
||||||
|
Linux kernel. The primary source of documentation would be to look in
|
||||||
|
the ``drivers/misc/kgdbts.c`` file.
|
||||||
|
|
||||||
|
The kgdb test suite can also be configured at compile time to run the
|
||||||
|
core set of tests by setting the kernel config parameter
|
||||||
|
``KGDB_TESTS_ON_BOOT``. This particular option is aimed at automated
|
||||||
|
regression testing and does not require modifying the kernel boot config
|
||||||
|
arguments. If this is turned on, the kgdb test suite can be disabled by
|
||||||
|
specifying ``kgdbts=`` as a kernel boot argument.
|
||||||
|
|
||||||
|
Kernel Debugger Internals
|
||||||
|
=========================
|
||||||
|
|
||||||
|
Architecture Specifics
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
The kernel debugger is organized into a number of components:
|
||||||
|
|
||||||
|
1. The debug core
|
||||||
|
|
||||||
|
The debug core is found in ``kernel/debugger/debug_core.c``. It
|
||||||
|
contains:
|
||||||
|
|
||||||
|
- A generic OS exception handler which includes sync'ing the
|
||||||
|
processors into a stopped state on an multi-CPU system.
|
||||||
|
|
||||||
|
- The API to talk to the kgdb I/O drivers
|
||||||
|
|
||||||
|
- The API to make calls to the arch-specific kgdb implementation
|
||||||
|
|
||||||
|
- The logic to perform safe memory reads and writes to memory while
|
||||||
|
using the debugger
|
||||||
|
|
||||||
|
- A full implementation for software breakpoints unless overridden
|
||||||
|
by the arch
|
||||||
|
|
||||||
|
- The API to invoke either the kdb or kgdb frontend to the debug
|
||||||
|
core.
|
||||||
|
|
||||||
|
- The structures and callback API for atomic kernel mode setting.
|
||||||
|
|
||||||
|
.. note:: kgdboc is where the kms callbacks are invoked.
|
||||||
|
|
||||||
|
2. kgdb arch-specific implementation
|
||||||
|
|
||||||
|
This implementation is generally found in ``arch/*/kernel/kgdb.c``. As
|
||||||
|
an example, ``arch/x86/kernel/kgdb.c`` contains the specifics to
|
||||||
|
implement HW breakpoint as well as the initialization to dynamically
|
||||||
|
register and unregister for the trap handlers on this architecture.
|
||||||
|
The arch-specific portion implements:
|
||||||
|
|
||||||
|
- contains an arch-specific trap catcher which invokes
|
||||||
|
:c:func:`kgdb_handle_exception` to start kgdb about doing its work
|
||||||
|
|
||||||
|
- translation to and from gdb specific packet format to :c:type:`pt_regs`
|
||||||
|
|
||||||
|
- Registration and unregistration of architecture specific trap
|
||||||
|
hooks
|
||||||
|
|
||||||
|
- Any special exception handling and cleanup
|
||||||
|
|
||||||
|
- NMI exception handling and cleanup
|
||||||
|
|
||||||
|
- (optional) HW breakpoints
|
||||||
|
|
||||||
|
3. gdbstub frontend (aka kgdb)
|
||||||
|
|
||||||
|
The gdbstub is located in ``kernel/debug/gdbstub.c``. It contains:
|
||||||
|
|
||||||
|
- All the logic to implement the gdb serial protocol
|
||||||
|
|
||||||
|
4. kdb frontend
|
||||||
|
|
||||||
|
The kdb debugger shell is broken down into a number of components.
|
||||||
|
The kdb core is located in kernel/debug/kdb. There are a number of
|
||||||
|
helper functions in some of the other kernel components to make it
|
||||||
|
possible for kdb to examine and report information about the kernel
|
||||||
|
without taking locks that could cause a kernel deadlock. The kdb core
|
||||||
|
contains implements the following functionality.
|
||||||
|
|
||||||
|
- A simple shell
|
||||||
|
|
||||||
|
- The kdb core command set
|
||||||
|
|
||||||
|
- A registration API to register additional kdb shell commands.
|
||||||
|
|
||||||
|
- A good example of a self-contained kdb module is the ``ftdump``
|
||||||
|
command for dumping the ftrace buffer. See:
|
||||||
|
``kernel/trace/trace_kdb.c``
|
||||||
|
|
||||||
|
- For an example of how to dynamically register a new kdb command
|
||||||
|
you can build the kdb_hello.ko kernel module from
|
||||||
|
``samples/kdb/kdb_hello.c``. To build this example you can set
|
||||||
|
``CONFIG_SAMPLES=y`` and ``CONFIG_SAMPLE_KDB=m`` in your kernel
|
||||||
|
config. Later run ``modprobe kdb_hello`` and the next time you
|
||||||
|
enter the kdb shell, you can run the ``hello`` command.
|
||||||
|
|
||||||
|
- The implementation for :c:func:`kdb_printf` which emits messages directly
|
||||||
|
to I/O drivers, bypassing the kernel log.
|
||||||
|
|
||||||
|
- SW / HW breakpoint management for the kdb shell
|
||||||
|
|
||||||
|
5. kgdb I/O driver
|
||||||
|
|
||||||
|
Each kgdb I/O driver has to provide an implementation for the
|
||||||
|
following:
|
||||||
|
|
||||||
|
- configuration via built-in or module
|
||||||
|
|
||||||
|
- dynamic configuration and kgdb hook registration calls
|
||||||
|
|
||||||
|
- read and write character interface
|
||||||
|
|
||||||
|
- A cleanup handler for unconfiguring from the kgdb core
|
||||||
|
|
||||||
|
- (optional) Early debug methodology
|
||||||
|
|
||||||
|
Any given kgdb I/O driver has to operate very closely with the
|
||||||
|
hardware and must do it in such a way that does not enable interrupts
|
||||||
|
or change other parts of the system context without completely
|
||||||
|
restoring them. The kgdb core will repeatedly "poll" a kgdb I/O
|
||||||
|
driver for characters when it needs input. The I/O driver is expected
|
||||||
|
to return immediately if there is no data available. Doing so allows
|
||||||
|
for the future possibility to touch watchdog hardware in such a way
|
||||||
|
as to have a target system not reset when these are enabled.
|
||||||
|
|
||||||
|
If you are intent on adding kgdb architecture specific support for a new
|
||||||
|
architecture, the architecture should define ``HAVE_ARCH_KGDB`` in the
|
||||||
|
architecture specific Kconfig file. This will enable kgdb for the
|
||||||
|
architecture, and at that point you must create an architecture specific
|
||||||
|
kgdb implementation.
|
||||||
|
|
||||||
|
There are a few flags which must be set on every architecture in their
|
||||||
|
``asm/kgdb.h`` file. These are:
|
||||||
|
|
||||||
|
- ``NUMREGBYTES``:
|
||||||
|
The size in bytes of all of the registers, so that we
|
||||||
|
can ensure they will all fit into a packet.
|
||||||
|
|
||||||
|
- ``BUFMAX``:
|
||||||
|
The size in bytes of the buffer GDB will read into. This must
|
||||||
|
be larger than NUMREGBYTES.
|
||||||
|
|
||||||
|
- ``CACHE_FLUSH_IS_SAFE``:
|
||||||
|
Set to 1 if it is always safe to call
|
||||||
|
flush_cache_range or flush_icache_range. On some architectures,
|
||||||
|
these functions may not be safe to call on SMP since we keep other
|
||||||
|
CPUs in a holding pattern.
|
||||||
|
|
||||||
|
There are also the following functions for the common backend, found in
|
||||||
|
``kernel/kgdb.c``, that must be supplied by the architecture-specific
|
||||||
|
backend unless marked as (optional), in which case a default function
|
||||||
|
maybe used if the architecture does not need to provide a specific
|
||||||
|
implementation.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/kgdb.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
kgdboc internals
|
||||||
|
----------------
|
||||||
|
|
||||||
|
kgdboc and uarts
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The kgdboc driver is actually a very thin driver that relies on the
|
||||||
|
underlying low level to the hardware driver having "polling hooks" to
|
||||||
|
which the tty driver is attached. In the initial implementation of
|
||||||
|
kgdboc the serial_core was changed to expose a low level UART hook for
|
||||||
|
doing polled mode reading and writing of a single character while in an
|
||||||
|
atomic context. When kgdb makes an I/O request to the debugger, kgdboc
|
||||||
|
invokes a callback in the serial core which in turn uses the callback in
|
||||||
|
the UART driver.
|
||||||
|
|
||||||
|
When using kgdboc with a UART, the UART driver must implement two
|
||||||
|
callbacks in the :c:type:`struct uart_ops <uart_ops>`.
|
||||||
|
Example from ``drivers/8250.c``::
|
||||||
|
|
||||||
|
|
||||||
|
#ifdef CONFIG_CONSOLE_POLL
|
||||||
|
.poll_get_char = serial8250_get_poll_char,
|
||||||
|
.poll_put_char = serial8250_put_poll_char,
|
||||||
|
#endif
|
||||||
|
|
||||||
|
|
||||||
|
Any implementation specifics around creating a polling driver use the
|
||||||
|
``#ifdef CONFIG_CONSOLE_POLL``, as shown above. Keep in mind that
|
||||||
|
polling hooks have to be implemented in such a way that they can be
|
||||||
|
called from an atomic context and have to restore the state of the UART
|
||||||
|
chip on return such that the system can return to normal when the
|
||||||
|
debugger detaches. You need to be very careful with any kind of lock you
|
||||||
|
consider, because failing here is most likely going to mean pressing the
|
||||||
|
reset button.
|
||||||
|
|
||||||
|
kgdboc and keyboards
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The kgdboc driver contains logic to configure communications with an
|
||||||
|
attached keyboard. The keyboard infrastructure is only compiled into the
|
||||||
|
kernel when ``CONFIG_KDB_KEYBOARD=y`` is set in the kernel configuration.
|
||||||
|
|
||||||
|
The core polled keyboard driver driver for PS/2 type keyboards is in
|
||||||
|
``drivers/char/kdb_keyboard.c``. This driver is hooked into the debug core
|
||||||
|
when kgdboc populates the callback in the array called
|
||||||
|
:c:type:`kdb_poll_funcs[]`. The :c:func:`kdb_get_kbd_char` is the top-level
|
||||||
|
function which polls hardware for single character input.
|
||||||
|
|
||||||
|
kgdboc and kms
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The kgdboc driver contains logic to request the graphics display to
|
||||||
|
switch to a text context when you are using ``kgdboc=kms,kbd``, provided
|
||||||
|
that you have a video driver which has a frame buffer console and atomic
|
||||||
|
kernel mode setting support.
|
||||||
|
|
||||||
|
Every time the kernel debugger is entered it calls
|
||||||
|
:c:func:`kgdboc_pre_exp_handler` which in turn calls :c:func:`con_debug_enter`
|
||||||
|
in the virtual console layer. On resuming kernel execution, the kernel
|
||||||
|
debugger calls :c:func:`kgdboc_post_exp_handler` which in turn calls
|
||||||
|
:c:func:`con_debug_leave`.
|
||||||
|
|
||||||
|
Any video driver that wants to be compatible with the kernel debugger
|
||||||
|
and the atomic kms callbacks must implement the ``mode_set_base_atomic``,
|
||||||
|
``fb_debug_enter`` and ``fb_debug_leave operations``. For the
|
||||||
|
``fb_debug_enter`` and ``fb_debug_leave`` the option exists to use the
|
||||||
|
generic drm fb helper functions or implement something custom for the
|
||||||
|
hardware. The following example shows the initialization of the
|
||||||
|
.mode_set_base_atomic operation in
|
||||||
|
drivers/gpu/drm/i915/intel_display.c::
|
||||||
|
|
||||||
|
|
||||||
|
static const struct drm_crtc_helper_funcs intel_helper_funcs = {
|
||||||
|
[...]
|
||||||
|
.mode_set_base_atomic = intel_pipe_set_base_atomic,
|
||||||
|
[...]
|
||||||
|
};
|
||||||
|
|
||||||
|
|
||||||
|
Here is an example of how the i915 driver initializes the
|
||||||
|
fb_debug_enter and fb_debug_leave functions to use the generic drm
|
||||||
|
helpers in ``drivers/gpu/drm/i915/intel_fb.c``::
|
||||||
|
|
||||||
|
|
||||||
|
static struct fb_ops intelfb_ops = {
|
||||||
|
[...]
|
||||||
|
.fb_debug_enter = drm_fb_helper_debug_enter,
|
||||||
|
.fb_debug_leave = drm_fb_helper_debug_leave,
|
||||||
|
[...]
|
||||||
|
};
|
||||||
|
|
||||||
|
|
||||||
|
Credits
|
||||||
|
=======
|
||||||
|
|
||||||
|
The following people have contributed to this document:
|
||||||
|
|
||||||
|
1. Amit Kale <amitkale@linsyssoft.com>
|
||||||
|
|
||||||
|
2. Tom Rini <trini@kernel.crashing.org>
|
||||||
|
|
||||||
|
In March 2008 this document was completely rewritten by:
|
||||||
|
|
||||||
|
- Jason Wessel <jason.wessel@windriver.com>
|
||||||
|
|
||||||
|
In Jan 2010 this document was updated to include kdb.
|
||||||
|
|
||||||
|
- Jason Wessel <jason.wessel@windriver.com>
|
|
@ -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
|
sphinx.rst
|
||||||
kernel-doc.rst
|
kernel-doc.rst
|
||||||
parse-headers.rst
|
parse-headers.rst
|
||||||
docbook.rst
|
|
||||||
|
|
||||||
.. only:: subproject and html
|
.. only:: subproject and html
|
||||||
|
|
||||||
|
|
|
@ -149,6 +149,16 @@ Domain`_ references.
|
||||||
``%CONST``
|
``%CONST``
|
||||||
Name of a constant. (No cross-referencing, just formatting.)
|
Name of a constant. (No cross-referencing, just formatting.)
|
||||||
|
|
||||||
|
````literal````
|
||||||
|
A literal block that should be handled as-is. The output will use a
|
||||||
|
``monospaced font``.
|
||||||
|
|
||||||
|
Useful if you need to use special characters that would otherwise have some
|
||||||
|
meaning either by kernel-doc script of by reStructuredText.
|
||||||
|
|
||||||
|
This is particularly useful if you need to use things like ``%ph`` inside
|
||||||
|
a function description.
|
||||||
|
|
||||||
``$ENVVAR``
|
``$ENVVAR``
|
||||||
Name of an environment variable. (No cross-referencing, just formatting.)
|
Name of an environment variable. (No cross-referencing, just formatting.)
|
||||||
|
|
||||||
|
|
|
@ -15,11 +15,6 @@ are used to describe the functions and types and design of the code. The
|
||||||
kernel-doc comments have some special structure and formatting, but beyond that
|
kernel-doc comments have some special structure and formatting, but beyond that
|
||||||
they are also treated as reStructuredText.
|
they are also treated as reStructuredText.
|
||||||
|
|
||||||
There is also the deprecated DocBook toolchain to generate documentation from
|
|
||||||
DocBook XML template files under ``Documentation/DocBook``. The DocBook files
|
|
||||||
are to be converted to reStructuredText, and the toolchain is slated to be
|
|
||||||
removed.
|
|
||||||
|
|
||||||
Finally, there are thousands of plain text documentation files scattered around
|
Finally, there are thousands of plain text documentation files scattered around
|
||||||
``Documentation``. Some of these will likely be converted to reStructuredText
|
``Documentation``. Some of these will likely be converted to reStructuredText
|
||||||
over time, but the bulk of them will remain in plain text.
|
over time, but the bulk of them will remain in plain text.
|
||||||
|
|
|
@ -118,7 +118,6 @@ defkeymap.c
|
||||||
devlist.h*
|
devlist.h*
|
||||||
devicetable-offsets.h
|
devicetable-offsets.h
|
||||||
dnotify_test
|
dnotify_test
|
||||||
docproc
|
|
||||||
dslm
|
dslm
|
||||||
dtc
|
dtc
|
||||||
elf2ecoff
|
elf2ecoff
|
||||||
|
|
|
@ -13,8 +13,8 @@ I2C is a multi-master bus; open drain signaling is used to arbitrate
|
||||||
between masters, as well as to handshake and to synchronize clocks from
|
between masters, as well as to handshake and to synchronize clocks from
|
||||||
slower clients.
|
slower clients.
|
||||||
|
|
||||||
The Linux I2C programming interfaces support only the master side of bus
|
The Linux I2C programming interfaces support the master side of bus
|
||||||
interactions, not the slave side. The programming interface is
|
interactions and the slave side. The programming interface is
|
||||||
structured around two kinds of driver, and two kinds of device. An I2C
|
structured around two kinds of driver, and two kinds of device. An I2C
|
||||||
"Adapter Driver" abstracts the controller hardware; it binds to a
|
"Adapter Driver" abstracts the controller hardware; it binds to a
|
||||||
physical device (perhaps a PCI device or platform_device) and exposes a
|
physical device (perhaps a PCI device or platform_device) and exposes a
|
||||||
|
@ -22,9 +22,8 @@ physical device (perhaps a PCI device or platform_device) and exposes a
|
||||||
I2C bus segment it manages. On each I2C bus segment will be I2C devices
|
I2C bus segment it manages. On each I2C bus segment will be I2C devices
|
||||||
represented by a :c:type:`struct i2c_client <i2c_client>`.
|
represented by a :c:type:`struct i2c_client <i2c_client>`.
|
||||||
Those devices will be bound to a :c:type:`struct i2c_driver
|
Those devices will be bound to a :c:type:`struct i2c_driver
|
||||||
<i2c_driver>`, which should follow the standard Linux driver
|
<i2c_driver>`, which should follow the standard Linux driver model. There
|
||||||
model. (At this writing, a legacy model is more widely used.) There are
|
are functions to perform various I2C protocol operations; at this writing
|
||||||
functions to perform various I2C protocol operations; at this writing
|
|
||||||
all such functions are usable only from task context.
|
all such functions are usable only from task context.
|
||||||
|
|
||||||
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
|
The System Management Bus (SMBus) is a sibling protocol. Most SMBus
|
||||||
|
|
|
@ -32,7 +32,13 @@ available subsections can be seen below.
|
||||||
i2c
|
i2c
|
||||||
hsi
|
hsi
|
||||||
edac
|
edac
|
||||||
|
scsi
|
||||||
|
libata
|
||||||
|
mtdnand
|
||||||
miscellaneous
|
miscellaneous
|
||||||
|
w1
|
||||||
|
rapidio
|
||||||
|
s390-drivers
|
||||||
vme
|
vme
|
||||||
80211/index
|
80211/index
|
||||||
uio-howto
|
uio-howto
|
||||||
|
|
1031
Documentation/driver-api/libata.rst
Normal file
1031
Documentation/driver-api/libata.rst
Normal file
File diff suppressed because it is too large
Load diff
1007
Documentation/driver-api/mtdnand.rst
Normal file
1007
Documentation/driver-api/mtdnand.rst
Normal file
File diff suppressed because it is too large
Load diff
107
Documentation/driver-api/rapidio.rst
Normal file
107
Documentation/driver-api/rapidio.rst
Normal file
|
@ -0,0 +1,107 @@
|
||||||
|
=======================
|
||||||
|
RapidIO Subsystem Guide
|
||||||
|
=======================
|
||||||
|
|
||||||
|
:Author: Matt Porter
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
RapidIO is a high speed switched fabric interconnect with features aimed
|
||||||
|
at the embedded market. RapidIO provides support for memory-mapped I/O
|
||||||
|
as well as message-based transactions over the switched fabric network.
|
||||||
|
RapidIO has a standardized discovery mechanism not unlike the PCI bus
|
||||||
|
standard that allows simple detection of devices in a network.
|
||||||
|
|
||||||
|
This documentation is provided for developers intending to support
|
||||||
|
RapidIO on new architectures, write new drivers, or to understand the
|
||||||
|
subsystem internals.
|
||||||
|
|
||||||
|
Known Bugs and Limitations
|
||||||
|
==========================
|
||||||
|
|
||||||
|
Bugs
|
||||||
|
----
|
||||||
|
|
||||||
|
None. ;)
|
||||||
|
|
||||||
|
Limitations
|
||||||
|
-----------
|
||||||
|
|
||||||
|
1. Access/management of RapidIO memory regions is not supported
|
||||||
|
|
||||||
|
2. Multiple host enumeration is not supported
|
||||||
|
|
||||||
|
RapidIO driver interface
|
||||||
|
========================
|
||||||
|
|
||||||
|
Drivers are provided a set of calls in order to interface with the
|
||||||
|
subsystem to gather info on devices, request/map memory region
|
||||||
|
resources, and manage mailboxes/doorbells.
|
||||||
|
|
||||||
|
Functions
|
||||||
|
---------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/rio_drv.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio-driver.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Internals
|
||||||
|
=========
|
||||||
|
|
||||||
|
This chapter contains the autogenerated documentation of the RapidIO
|
||||||
|
subsystem.
|
||||||
|
|
||||||
|
Structures
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/rio.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Enumeration and Discovery
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio-scan.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Driver functionality
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio-access.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Device model support
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/rapidio/rio-driver.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
PPC32 support
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/powerpc/sysdev/fsl_rio.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Credits
|
||||||
|
=======
|
||||||
|
|
||||||
|
The following people have contributed to the RapidIO subsystem directly
|
||||||
|
or indirectly:
|
||||||
|
|
||||||
|
1. Matt Porter\ mporter@kernel.crashing.org
|
||||||
|
|
||||||
|
2. Randy Vinson\ rvinson@mvista.com
|
||||||
|
|
||||||
|
3. Dan Malek\ dan@embeddedalley.com
|
||||||
|
|
||||||
|
The following people have contributed to this document:
|
||||||
|
|
||||||
|
1. Matt Porter\ mporter@kernel.crashing.org
|
111
Documentation/driver-api/s390-drivers.rst
Normal file
111
Documentation/driver-api/s390-drivers.rst
Normal file
|
@ -0,0 +1,111 @@
|
||||||
|
===================================
|
||||||
|
Writing s390 channel device drivers
|
||||||
|
===================================
|
||||||
|
|
||||||
|
:Author: Cornelia Huck
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
This document describes the interfaces available for device drivers that
|
||||||
|
drive s390 based channel attached I/O devices. This includes interfaces
|
||||||
|
for interaction with the hardware and interfaces for interacting with
|
||||||
|
the common driver core. Those interfaces are provided by the s390 common
|
||||||
|
I/O layer.
|
||||||
|
|
||||||
|
The document assumes a familarity with the technical terms associated
|
||||||
|
with the s390 channel I/O architecture. For a description of this
|
||||||
|
architecture, please refer to the "z/Architecture: Principles of
|
||||||
|
Operation", IBM publication no. SA22-7832.
|
||||||
|
|
||||||
|
While most I/O devices on a s390 system are typically driven through the
|
||||||
|
channel I/O mechanism described here, there are various other methods
|
||||||
|
(like the diag interface). These are out of the scope of this document.
|
||||||
|
|
||||||
|
Some additional information can also be found in the kernel source under
|
||||||
|
Documentation/s390/driver-model.txt.
|
||||||
|
|
||||||
|
The ccw bus
|
||||||
|
===========
|
||||||
|
|
||||||
|
The ccw bus typically contains the majority of devices available to a
|
||||||
|
s390 system. Named after the channel command word (ccw), the basic
|
||||||
|
command structure used to address its devices, the ccw bus contains
|
||||||
|
so-called channel attached devices. They are addressed via I/O
|
||||||
|
subchannels, visible on the css bus. A device driver for
|
||||||
|
channel-attached devices, however, will never interact with the
|
||||||
|
subchannel directly, but only via the I/O device on the ccw bus, the ccw
|
||||||
|
device.
|
||||||
|
|
||||||
|
I/O functions for channel-attached devices
|
||||||
|
------------------------------------------
|
||||||
|
|
||||||
|
Some hardware structures have been translated into C structures for use
|
||||||
|
by the common I/O layer and device drivers. For more information on the
|
||||||
|
hardware structures represented here, please consult the Principles of
|
||||||
|
Operation.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/cio.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
ccw devices
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Devices that want to initiate channel I/O need to attach to the ccw bus.
|
||||||
|
Interaction with the driver core is done via the common I/O layer, which
|
||||||
|
provides the abstractions of ccw devices and ccw device drivers.
|
||||||
|
|
||||||
|
The functions that initiate or terminate channel I/O all act upon a ccw
|
||||||
|
device structure. Device drivers must not bypass those functions or
|
||||||
|
strange side effects may happen.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/ccwdev.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/device.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/device_ops.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The channel-measurement facility
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
The channel-measurement facility provides a means to collect measurement
|
||||||
|
data which is made available by the channel subsystem for each channel
|
||||||
|
attached device.
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/cmb.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/cmf.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The ccwgroup bus
|
||||||
|
================
|
||||||
|
|
||||||
|
The ccwgroup bus only contains artificial devices, created by the user.
|
||||||
|
Many networking devices (e.g. qeth) are in fact composed of several ccw
|
||||||
|
devices (like read, write and data channel for qeth). The ccwgroup bus
|
||||||
|
provides a mechanism to create a meta-device which contains those ccw
|
||||||
|
devices as slave devices and can be associated with the netdevice.
|
||||||
|
|
||||||
|
ccw group devices
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/s390/include/asm/ccwgroup.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/ccwgroup.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Generic interfaces
|
||||||
|
==================
|
||||||
|
|
||||||
|
Some interfaces are available to other drivers that do not necessarily
|
||||||
|
have anything to do with the busses described above, but still are
|
||||||
|
indirectly using basic infrastructure in the common I/O layer. One
|
||||||
|
example is the support for adapter interrupts.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/s390/cio/airq.c
|
||||||
|
:export:
|
344
Documentation/driver-api/scsi.rst
Normal file
344
Documentation/driver-api/scsi.rst
Normal file
|
@ -0,0 +1,344 @@
|
||||||
|
=====================
|
||||||
|
SCSI Interfaces Guide
|
||||||
|
=====================
|
||||||
|
|
||||||
|
:Author: James Bottomley
|
||||||
|
:Author: Rob Landley
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
Protocol vs bus
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Once upon a time, the Small Computer Systems Interface defined both a
|
||||||
|
parallel I/O bus and a data protocol to connect a wide variety of
|
||||||
|
peripherals (disk drives, tape drives, modems, printers, scanners,
|
||||||
|
optical drives, test equipment, and medical devices) to a host computer.
|
||||||
|
|
||||||
|
Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
|
||||||
|
out of use, the SCSI command set is more widely used than ever to
|
||||||
|
communicate with devices over a number of different busses.
|
||||||
|
|
||||||
|
The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian
|
||||||
|
peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
|
||||||
|
bytes long, often followed by an associated data payload.
|
||||||
|
|
||||||
|
SCSI commands can be transported over just about any kind of bus, and
|
||||||
|
are the default protocol for storage devices attached to USB, SATA, SAS,
|
||||||
|
Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also
|
||||||
|
commonly exchanged over Infiniband,
|
||||||
|
`I20 <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP
|
||||||
|
(`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel
|
||||||
|
ports <http://cyberelk.net/tim/parport/parscsi.html>`__.
|
||||||
|
|
||||||
|
Design of the Linux SCSI subsystem
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
The SCSI subsystem uses a three layer design, with upper, mid, and low
|
||||||
|
layers. Every operation involving the SCSI subsystem (such as reading a
|
||||||
|
sector from a disk) uses one driver at each of the 3 levels: one upper
|
||||||
|
layer driver, one lower layer driver, and the SCSI midlayer.
|
||||||
|
|
||||||
|
The SCSI upper layer provides the interface between userspace and the
|
||||||
|
kernel, in the form of block and char device nodes for I/O and ioctl().
|
||||||
|
The SCSI lower layer contains drivers for specific hardware devices.
|
||||||
|
|
||||||
|
In between is the SCSI mid-layer, analogous to a network routing layer
|
||||||
|
such as the IPv4 stack. The SCSI mid-layer routes a packet based data
|
||||||
|
protocol between the upper layer's /dev nodes and the corresponding
|
||||||
|
devices in the lower layer. It manages command queues, provides error
|
||||||
|
handling and power management functions, and responds to ioctl()
|
||||||
|
requests.
|
||||||
|
|
||||||
|
SCSI upper layer
|
||||||
|
================
|
||||||
|
|
||||||
|
The upper layer supports the user-kernel interface by providing device
|
||||||
|
nodes.
|
||||||
|
|
||||||
|
sd (SCSI Disk)
|
||||||
|
--------------
|
||||||
|
|
||||||
|
sd (sd_mod.o)
|
||||||
|
|
||||||
|
sr (SCSI CD-ROM)
|
||||||
|
----------------
|
||||||
|
|
||||||
|
sr (sr_mod.o)
|
||||||
|
|
||||||
|
st (SCSI Tape)
|
||||||
|
--------------
|
||||||
|
|
||||||
|
st (st.o)
|
||||||
|
|
||||||
|
sg (SCSI Generic)
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
sg (sg.o)
|
||||||
|
|
||||||
|
ch (SCSI Media Changer)
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
ch (ch.c)
|
||||||
|
|
||||||
|
SCSI mid layer
|
||||||
|
==============
|
||||||
|
|
||||||
|
SCSI midlayer implementation
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
include/scsi/scsi_device.h
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: include/scsi/scsi_device.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/scsi/scsi.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Main file for the SCSI midlayer.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsicam.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
`SCSI Common Access
|
||||||
|
Method <http://www.t10.org/ftp/t10/drafts/cam/cam-r12b.pdf>`__ support
|
||||||
|
functions, for use with HDIO_GETGEO, etc.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsicam.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_error.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Common SCSI error/timeout handling routines.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_error.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_devinfo.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Manage scsi_dev_info_list, which tracks blacklisted and whitelisted
|
||||||
|
devices.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_devinfo.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_ioctl.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Handle ioctl() calls for SCSI devices.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_ioctl.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_lib.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
SCSI queuing library.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_lib.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_lib_dma.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
SCSI library functions depending on DMA (map and unmap scatter-gather
|
||||||
|
lists).
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_lib_dma.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_module.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_module.c contains legacy support for
|
||||||
|
old-style host templates. It should never be used by any new driver.
|
||||||
|
|
||||||
|
drivers/scsi/scsi_proc.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The functions in this file provide an interface between the PROC file
|
||||||
|
system and the SCSI device drivers It is mainly used for debugging,
|
||||||
|
statistics and to pass information directly to the lowlevel driver. I.E.
|
||||||
|
plumbing to manage /proc/scsi/\*
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_proc.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_netlink.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Infrastructure to provide async events from transports to userspace via
|
||||||
|
netlink, using a single NETLINK_SCSITRANSPORT protocol for all
|
||||||
|
transports. See `the original patch
|
||||||
|
submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for
|
||||||
|
more details.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_netlink.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_scan.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Scan a host to determine which (if any) devices are attached. The
|
||||||
|
general scanning/probing algorithm is as follows, exceptions are made to
|
||||||
|
it depending on device specific flags, compilation options, and global
|
||||||
|
variable (boot or module load time) settings. A specific LUN is scanned
|
||||||
|
via an INQUIRY command; if the LUN has a device attached, a scsi_device
|
||||||
|
is allocated and setup for it. For every id of every channel on the
|
||||||
|
given host, start by scanning LUN 0. Skip hosts that don't respond at
|
||||||
|
all to a scan of LUN 0. Otherwise, if LUN 0 has a device attached,
|
||||||
|
allocate and setup a scsi_device for it. If target is SCSI-3 or up,
|
||||||
|
issue a REPORT LUN, and scan all of the LUNs returned by the REPORT LUN;
|
||||||
|
else, sequentially scan LUNs up until some maximum is reached, or a LUN
|
||||||
|
is seen that cannot have a device attached to it.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_scan.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/scsi/scsi_sysctl.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Set up the sysctl entry: "/dev/scsi/logging_level"
|
||||||
|
(DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level.
|
||||||
|
|
||||||
|
drivers/scsi/scsi_sysfs.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
SCSI sysfs interface routines.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_sysfs.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/hosts.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
mid to lowlevel SCSI driver interface
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/hosts.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/scsi/constants.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
mid to lowlevel SCSI driver interface
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/constants.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Transport classes
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Transport classes are service libraries for drivers in the SCSI lower
|
||||||
|
layer, which expose transport attributes in sysfs.
|
||||||
|
|
||||||
|
Fibre Channel transport
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_transport_fc.c defines transport attributes
|
||||||
|
for Fibre Channel.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_transport_fc.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
iSCSI transport class
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_transport_iscsi.c defines transport
|
||||||
|
attributes for the iSCSI class, which sends SCSI packets over TCP/IP
|
||||||
|
connections.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_transport_iscsi.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Serial Attached SCSI (SAS) transport class
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_transport_sas.c defines transport
|
||||||
|
attributes for Serial Attached SCSI, a variant of SATA aimed at large
|
||||||
|
high-end systems.
|
||||||
|
|
||||||
|
The SAS transport class contains common code to deal with SAS HBAs, an
|
||||||
|
aproximated representation of SAS topologies in the driver model, and
|
||||||
|
various sysfs attributes to expose these topologies and management
|
||||||
|
interfaces to userspace.
|
||||||
|
|
||||||
|
In addition to the basic SCSI core objects this transport class
|
||||||
|
introduces two additional intermediate objects: The SAS PHY as
|
||||||
|
represented by struct sas_phy defines an "outgoing" PHY on a SAS HBA or
|
||||||
|
Expander, and the SAS remote PHY represented by struct sas_rphy defines
|
||||||
|
an "incoming" PHY on a SAS Expander or end device. Note that this is
|
||||||
|
purely a software concept, the underlying hardware for a PHY and a
|
||||||
|
remote PHY is the exactly the same.
|
||||||
|
|
||||||
|
There is no concept of a SAS port in this code, users can see what PHYs
|
||||||
|
form a wide port based on the port_identifier attribute, which is the
|
||||||
|
same for all PHYs in a port.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_transport_sas.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
SATA transport class
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The SATA transport is handled by libata, which has its own book of
|
||||||
|
documentation in this directory.
|
||||||
|
|
||||||
|
Parallel SCSI (SPI) transport class
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_transport_spi.c defines transport
|
||||||
|
attributes for traditional (fast/wide/ultra) SCSI busses.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_transport_spi.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
SCSI RDMA (SRP) transport class
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_transport_srp.c defines transport
|
||||||
|
attributes for SCSI over Remote Direct Memory Access.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/scsi/scsi_transport_srp.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
SCSI lower layer
|
||||||
|
================
|
||||||
|
|
||||||
|
Host Bus Adapter transport types
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
Many modern device controllers use the SCSI command set as a protocol to
|
||||||
|
communicate with their devices through many different types of physical
|
||||||
|
connections.
|
||||||
|
|
||||||
|
In SCSI language a bus capable of carrying SCSI commands is called a
|
||||||
|
"transport", and a controller connecting to such a bus is called a "host
|
||||||
|
bus adapter" (HBA).
|
||||||
|
|
||||||
|
Debug transport
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The file drivers/scsi/scsi_debug.c simulates a host adapter with a
|
||||||
|
variable number of disks (or disk like devices) attached, sharing a
|
||||||
|
common amount of RAM. Does a lot of checking to make sure that we are
|
||||||
|
not getting blocks mixed up, and panics the kernel if anything out of
|
||||||
|
the ordinary is seen.
|
||||||
|
|
||||||
|
To be more realistic, the simulated devices have the transport
|
||||||
|
attributes of SAS disks.
|
||||||
|
|
||||||
|
For documentation see http://sg.danny.cz/sg/sdebug26.html
|
||||||
|
|
||||||
|
todo
|
||||||
|
~~~~
|
||||||
|
|
||||||
|
Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel,
|
||||||
|
FireWire, ATAPI devices, Infiniband, I20, iSCSI, Parallel ports,
|
||||||
|
netlink...
|
70
Documentation/driver-api/w1.rst
Normal file
70
Documentation/driver-api/w1.rst
Normal file
|
@ -0,0 +1,70 @@
|
||||||
|
======================
|
||||||
|
W1: Dallas' 1-wire bus
|
||||||
|
======================
|
||||||
|
|
||||||
|
:Author: David Fries
|
||||||
|
|
||||||
|
W1 API internal to the kernel
|
||||||
|
=============================
|
||||||
|
|
||||||
|
W1 API internal to the kernel
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
include/linux/w1.h
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
W1 kernel API functions.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/w1.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/w1/w1.c
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
W1 core functions.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/w1/w1.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
drivers/w1/w1_family.c
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Allows registering device family operations.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/w1/w1_family.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
drivers/w1/w1_internal.h
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
W1 internal initialization for master devices.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/w1/w1_internal.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
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
|
FOURCC definitions are located in the linux/videodev2.h header. However, and
|
||||||
despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
|
despite starting with the V4L2_PIX_FMT_prefix, they are not restricted to V4L2
|
||||||
and don't require usage of the V4L2 subsystem. FOURCC documentation is
|
and don't require usage of the V4L2 subsystem. FOURCC documentation is
|
||||||
available in Documentation/DocBook/v4l/pixfmt.xml.
|
available in Documentation/media/uapi/v4l/pixfmt.rst.
|
||||||
|
|
||||||
To select a format, applications set the grayscale field to the desired FOURCC.
|
To select a format, applications set the grayscale field to the desired FOURCC.
|
||||||
For YUV formats, they should also select the appropriate colorspace by setting
|
For YUV formats, they should also select the appropriate colorspace by setting
|
||||||
the colorspace field to one of the colorspaces listed in linux/videodev2.h and
|
the colorspace field to one of the colorspaces listed in linux/videodev2.h and
|
||||||
documented in Documentation/DocBook/v4l/colorspaces.xml.
|
documented in Documentation/media/uapi/v4l/colorspaces.rst.
|
||||||
|
|
||||||
The red, green, blue and transp fields are not used with the FOURCC-based API.
|
The red, green, blue and transp fields are not used with the FOURCC-based API.
|
||||||
For forward compatibility reasons applications must zero those fields, and
|
For forward compatibility reasons applications must zero those fields, and
|
||||||
|
|
10
Documentation/filesystems/conf.py
Normal file
10
Documentation/filesystems/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = "Linux Filesystems API"
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'filesystems.tex', project,
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
317
Documentation/filesystems/index.rst
Normal file
317
Documentation/filesystems/index.rst
Normal file
|
@ -0,0 +1,317 @@
|
||||||
|
=====================
|
||||||
|
Linux Filesystems API
|
||||||
|
=====================
|
||||||
|
|
||||||
|
The Linux VFS
|
||||||
|
=============
|
||||||
|
|
||||||
|
The Filesystem types
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/fs.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
The Directory Cache
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/dcache.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/dcache.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Inode Handling
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/inode.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/bad_inode.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Registration and Superblocks
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/super.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
File Locks
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/locks.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/locks.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Other Functions
|
||||||
|
---------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/mpage.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/namei.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/buffer.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: block/bio.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/seq_file.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/filesystems.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/fs-writeback.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/block_dev.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The proc filesystem
|
||||||
|
===================
|
||||||
|
|
||||||
|
sysctl interface
|
||||||
|
----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: kernel/sysctl.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
proc filesystem interface
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/proc/base.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Events based on file descriptors
|
||||||
|
================================
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/eventfd.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The Filesystem for Exporting Kernel Objects
|
||||||
|
===========================================
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/sysfs/file.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/sysfs/symlink.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The debugfs filesystem
|
||||||
|
======================
|
||||||
|
|
||||||
|
debugfs interface
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/debugfs/inode.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/debugfs/file.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
The Linux Journalling API
|
||||||
|
=========================
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
Details
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
The journalling layer is easy to use. You need to first of all create a
|
||||||
|
journal_t data structure. There are two calls to do this dependent on
|
||||||
|
how you decide to allocate the physical media on which the journal
|
||||||
|
resides. The :c:func:`jbd2_journal_init_inode` call is for journals stored in
|
||||||
|
filesystem inodes, or the :c:func:`jbd2_journal_init_dev` call can be used
|
||||||
|
for journal stored on a raw device (in a continuous range of blocks). A
|
||||||
|
journal_t is a typedef for a struct pointer, so when you are finally
|
||||||
|
finished make sure you call :c:func:`jbd2_journal_destroy` on it to free up
|
||||||
|
any used kernel memory.
|
||||||
|
|
||||||
|
Once you have got your journal_t object you need to 'mount' or load the
|
||||||
|
journal file. The journalling layer expects the space for the journal
|
||||||
|
was already allocated and initialized properly by the userspace tools.
|
||||||
|
When loading the journal you must call :c:func:`jbd2_journal_load` to process
|
||||||
|
journal contents. If the client file system detects the journal contents
|
||||||
|
does not need to be processed (or even need not have valid contents), it
|
||||||
|
may call :c:func:`jbd2_journal_wipe` to clear the journal contents before
|
||||||
|
calling :c:func:`jbd2_journal_load`.
|
||||||
|
|
||||||
|
Note that jbd2_journal_wipe(..,0) calls
|
||||||
|
:c:func:`jbd2_journal_skip_recovery` for you if it detects any outstanding
|
||||||
|
transactions in the journal and similarly :c:func:`jbd2_journal_load` will
|
||||||
|
call :c:func:`jbd2_journal_recover` if necessary. I would advise reading
|
||||||
|
:c:func:`ext4_load_journal` in fs/ext4/super.c for examples on this stage.
|
||||||
|
|
||||||
|
Now you can go ahead and start modifying the underlying filesystem.
|
||||||
|
Almost.
|
||||||
|
|
||||||
|
You still need to actually journal your filesystem changes, this is done
|
||||||
|
by wrapping them into transactions. Additionally you also need to wrap
|
||||||
|
the modification of each of the buffers with calls to the journal layer,
|
||||||
|
so it knows what the modifications you are actually making are. To do
|
||||||
|
this use :c:func:`jbd2_journal_start` which returns a transaction handle.
|
||||||
|
|
||||||
|
:c:func:`jbd2_journal_start` and its counterpart :c:func:`jbd2_journal_stop`,
|
||||||
|
which indicates the end of a transaction are nestable calls, so you can
|
||||||
|
reenter a transaction if necessary, but remember you must call
|
||||||
|
:c:func:`jbd2_journal_stop` the same number of times as
|
||||||
|
:c:func:`jbd2_journal_start` before the transaction is completed (or more
|
||||||
|
accurately leaves the update phase). Ext4/VFS makes use of this feature to
|
||||||
|
simplify handling of inode dirtying, quota support, etc.
|
||||||
|
|
||||||
|
Inside each transaction you need to wrap the modifications to the
|
||||||
|
individual buffers (blocks). Before you start to modify a buffer you
|
||||||
|
need to call :c:func:`jbd2_journal_get_create_access()` /
|
||||||
|
:c:func:`jbd2_journal_get_write_access()` /
|
||||||
|
:c:func:`jbd2_journal_get_undo_access()` as appropriate, this allows the
|
||||||
|
journalling layer to copy the unmodified
|
||||||
|
data if it needs to. After all the buffer may be part of a previously
|
||||||
|
uncommitted transaction. At this point you are at last ready to modify a
|
||||||
|
buffer, and once you are have done so you need to call
|
||||||
|
:c:func:`jbd2_journal_dirty_metadata`. Or if you've asked for access to a
|
||||||
|
buffer you now know is now longer required to be pushed back on the
|
||||||
|
device you can call :c:func:`jbd2_journal_forget` in much the same way as you
|
||||||
|
might have used :c:func:`bforget` in the past.
|
||||||
|
|
||||||
|
A :c:func:`jbd2_journal_flush` may be called at any time to commit and
|
||||||
|
checkpoint all your transactions.
|
||||||
|
|
||||||
|
Then at umount time , in your :c:func:`put_super` you can then call
|
||||||
|
:c:func:`jbd2_journal_destroy` to clean up your in-core journal object.
|
||||||
|
|
||||||
|
Unfortunately there a couple of ways the journal layer can cause a
|
||||||
|
deadlock. The first thing to note is that each task can only have a
|
||||||
|
single outstanding transaction at any one time, remember nothing commits
|
||||||
|
until the outermost :c:func:`jbd2_journal_stop`. This means you must complete
|
||||||
|
the transaction at the end of each file/inode/address etc. operation you
|
||||||
|
perform, so that the journalling system isn't re-entered on another
|
||||||
|
journal. Since transactions can't be nested/batched across differing
|
||||||
|
journals, and another filesystem other than yours (say ext4) may be
|
||||||
|
modified in a later syscall.
|
||||||
|
|
||||||
|
The second case to bear in mind is that :c:func:`jbd2_journal_start` can block
|
||||||
|
if there isn't enough space in the journal for your transaction (based
|
||||||
|
on the passed nblocks param) - when it blocks it merely(!) needs to wait
|
||||||
|
for transactions to complete and be committed from other tasks, so
|
||||||
|
essentially we are waiting for :c:func:`jbd2_journal_stop`. So to avoid
|
||||||
|
deadlocks you must treat :c:func:`jbd2_journal_start` /
|
||||||
|
:c:func:`jbd2_journal_stop` as if they were semaphores and include them in
|
||||||
|
your semaphore ordering rules to prevent
|
||||||
|
deadlocks. Note that :c:func:`jbd2_journal_extend` has similar blocking
|
||||||
|
behaviour to :c:func:`jbd2_journal_start` so you can deadlock here just as
|
||||||
|
easily as on :c:func:`jbd2_journal_start`.
|
||||||
|
|
||||||
|
Try to reserve the right number of blocks the first time. ;-). This will
|
||||||
|
be the maximum number of blocks you are going to touch in this
|
||||||
|
transaction. I advise having a look at at least ext4_jbd.h to see the
|
||||||
|
basis on which ext4 uses to make these decisions.
|
||||||
|
|
||||||
|
Another wriggle to watch out for is your on-disk block allocation
|
||||||
|
strategy. Why? Because, if you do a delete, you need to ensure you
|
||||||
|
haven't reused any of the freed blocks until the transaction freeing
|
||||||
|
these blocks commits. If you reused these blocks and crash happens,
|
||||||
|
there is no way to restore the contents of the reallocated blocks at the
|
||||||
|
end of the last fully committed transaction. One simple way of doing
|
||||||
|
this is to mark blocks as free in internal in-memory block allocation
|
||||||
|
structures only after the transaction freeing them commits. Ext4 uses
|
||||||
|
journal commit callback for this purpose.
|
||||||
|
|
||||||
|
With journal commit callbacks you can ask the journalling layer to call
|
||||||
|
a callback function when the transaction is finally committed to disk,
|
||||||
|
so that you can do some of your own management. You ask the journalling
|
||||||
|
layer for calling the callback by simply setting
|
||||||
|
``journal->j_commit_callback`` function pointer and that function is
|
||||||
|
called after each transaction commit. You can also use
|
||||||
|
``transaction->t_private_list`` for attaching entries to a transaction
|
||||||
|
that need processing when the transaction commits.
|
||||||
|
|
||||||
|
JBD2 also provides a way to block all transaction updates via
|
||||||
|
:c:func:`jbd2_journal_lock_updates()` /
|
||||||
|
:c:func:`jbd2_journal_unlock_updates()`. Ext4 uses this when it wants a
|
||||||
|
window with a clean and stable fs for a moment. E.g.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
|
||||||
|
jbd2_journal_lock_updates() //stop new stuff happening..
|
||||||
|
jbd2_journal_flush() // checkpoint everything.
|
||||||
|
..do stuff on stable fs
|
||||||
|
jbd2_journal_unlock_updates() // carry on with filesystem use.
|
||||||
|
|
||||||
|
The opportunities for abuse and DOS attacks with this should be obvious,
|
||||||
|
if you allow unprivileged userspace to trigger codepaths containing
|
||||||
|
these calls.
|
||||||
|
|
||||||
|
Summary
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
Using the journal is a matter of wrapping the different context changes,
|
||||||
|
being each mount, each modification (transaction) and each changed
|
||||||
|
buffer to tell the journalling layer about them.
|
||||||
|
|
||||||
|
Data Types
|
||||||
|
----------
|
||||||
|
|
||||||
|
The journalling layer uses typedefs to 'hide' the concrete definitions
|
||||||
|
of the structures used. As a client of the JBD2 layer you can just rely
|
||||||
|
on the using the pointer as a magic cookie of some sort. Obviously the
|
||||||
|
hiding is not enforced as this is 'C'.
|
||||||
|
|
||||||
|
Structures
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/jbd2.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Functions
|
||||||
|
---------
|
||||||
|
|
||||||
|
The functions here are split into two groups those that affect a journal
|
||||||
|
as a whole, and those which are used to manage transactions
|
||||||
|
|
||||||
|
Journal Level
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/jbd2/journal.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/jbd2/recovery.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Transasction Level
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/jbd2/transaction.c
|
||||||
|
|
||||||
|
See also
|
||||||
|
--------
|
||||||
|
|
||||||
|
`Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen
|
||||||
|
Tweedie <http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz>`__
|
||||||
|
|
||||||
|
`Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen
|
||||||
|
Tweedie <http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html>`__
|
||||||
|
|
||||||
|
splice API
|
||||||
|
==========
|
||||||
|
|
||||||
|
splice is a method for moving blocks of data around inside the kernel,
|
||||||
|
without continually transferring them between the kernel and user space.
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/splice.c
|
||||||
|
|
||||||
|
pipes API
|
||||||
|
=========
|
||||||
|
|
||||||
|
Pipe interfaces are all for in-kernel (builtin image) use. They are not
|
||||||
|
exported for use by modules.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/pipe_fs_i.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: fs/pipe.c
|
|
@ -55,7 +55,7 @@ request-key will find the first matching line and corresponding program. In
|
||||||
this case, /some/other/program will handle all uid lookups and
|
this case, /some/other/program will handle all uid lookups and
|
||||||
/usr/sbin/nfs.idmap will handle gid, user, and group lookups.
|
/usr/sbin/nfs.idmap will handle gid, user, and group lookups.
|
||||||
|
|
||||||
See <file:Documentation/security/keys-request-key.txt> for more information
|
See <file:Documentation/security/keys/request-key.rst> for more information
|
||||||
about the request-key function.
|
about the request-key function.
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -228,7 +228,7 @@ The DRM reference documentation is still lacking kerneldoc in a few areas. The
|
||||||
task would be to clean up interfaces like moving functions around between
|
task would be to clean up interfaces like moving functions around between
|
||||||
files to better group them and improving the interfaces like dropping return
|
files to better group them and improving the interfaces like dropping return
|
||||||
values for functions that never fail. Then write kerneldoc for all exported
|
values for functions that never fail. Then write kerneldoc for all exported
|
||||||
functions and an overview section and integrate it all into the drm DocBook.
|
functions and an overview section and integrate it all into the drm book.
|
||||||
|
|
||||||
See https://dri.freedesktop.org/docs/drm/ for what's there already.
|
See https://dri.freedesktop.org/docs/drm/ for what's there already.
|
||||||
|
|
||||||
|
|
|
@ -3,8 +3,8 @@
|
||||||
You can adapt this file completely to your liking, but it should at least
|
You can adapt this file completely to your liking, but it should at least
|
||||||
contain the root `toctree` directive.
|
contain the root `toctree` directive.
|
||||||
|
|
||||||
Welcome to The Linux Kernel's documentation
|
The Linux Kernel documentation
|
||||||
===========================================
|
==============================
|
||||||
|
|
||||||
This is the top level of the kernel's documentation tree. Kernel
|
This is the top level of the kernel's documentation tree. Kernel
|
||||||
documentation, like the kernel itself, is very much a work in progress;
|
documentation, like the kernel itself, is very much a work in progress;
|
||||||
|
@ -51,6 +51,7 @@ merged much easier.
|
||||||
process/index
|
process/index
|
||||||
dev-tools/index
|
dev-tools/index
|
||||||
doc-guide/index
|
doc-guide/index
|
||||||
|
kernel-hacking/index
|
||||||
|
|
||||||
Kernel API documentation
|
Kernel API documentation
|
||||||
------------------------
|
------------------------
|
||||||
|
@ -67,11 +68,24 @@ needed).
|
||||||
driver-api/index
|
driver-api/index
|
||||||
core-api/index
|
core-api/index
|
||||||
media/index
|
media/index
|
||||||
|
networking/index
|
||||||
input/index
|
input/index
|
||||||
gpu/index
|
gpu/index
|
||||||
security/index
|
security/index
|
||||||
sound/index
|
sound/index
|
||||||
crypto/index
|
crypto/index
|
||||||
|
filesystems/index
|
||||||
|
|
||||||
|
Architecture-specific documentation
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
These books provide programming details about architecture-specific
|
||||||
|
implementation.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
sh/index
|
||||||
|
|
||||||
Korean translations
|
Korean translations
|
||||||
-------------------
|
-------------------
|
||||||
|
|
|
@ -1331,7 +1331,7 @@ See subsequent chapter for the syntax of the Kbuild file.
|
||||||
--- 7.5 mandatory-y
|
--- 7.5 mandatory-y
|
||||||
|
|
||||||
mandatory-y is essentially used by include/uapi/asm-generic/Kbuild.asm
|
mandatory-y is essentially used by include/uapi/asm-generic/Kbuild.asm
|
||||||
to define the minimun set of headers that must be exported in
|
to define the minimum set of headers that must be exported in
|
||||||
include/asm.
|
include/asm.
|
||||||
|
|
||||||
The convention is to list one subdir per line and
|
The convention is to list one subdir per line and
|
||||||
|
|
|
@ -17,8 +17,8 @@ The format for this documentation is called the kernel-doc format.
|
||||||
It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
|
It is documented in this Documentation/kernel-doc-nano-HOWTO.txt file.
|
||||||
|
|
||||||
This style embeds the documentation within the source files, using
|
This style embeds the documentation within the source files, using
|
||||||
a few simple conventions. The scripts/kernel-doc perl script, some
|
a few simple conventions. The scripts/kernel-doc perl script, the
|
||||||
SGML templates in Documentation/DocBook, and other tools understand
|
Documentation/sphinx/kerneldoc.py Sphinx extension and other tools understand
|
||||||
these conventions, and are used to extract this embedded documentation
|
these conventions, and are used to extract this embedded documentation
|
||||||
into various documents.
|
into various documents.
|
||||||
|
|
||||||
|
@ -122,15 +122,9 @@ are:
|
||||||
- scripts/kernel-doc
|
- scripts/kernel-doc
|
||||||
|
|
||||||
This is a perl script that hunts for the block comments and can mark
|
This is a perl script that hunts for the block comments and can mark
|
||||||
them up directly into DocBook, man, text, and HTML. (No, not
|
them up directly into DocBook, ReST, man, text, and HTML. (No, not
|
||||||
texinfo.)
|
texinfo.)
|
||||||
|
|
||||||
- Documentation/DocBook/*.tmpl
|
|
||||||
|
|
||||||
These are SGML template files, which are normal SGML files with
|
|
||||||
special place-holders for where the extracted documentation should
|
|
||||||
go.
|
|
||||||
|
|
||||||
- scripts/docproc.c
|
- scripts/docproc.c
|
||||||
|
|
||||||
This is a program for converting SGML template files into SGML
|
This is a program for converting SGML template files into SGML
|
||||||
|
@ -145,25 +139,18 @@ are:
|
||||||
|
|
||||||
- Makefile
|
- Makefile
|
||||||
|
|
||||||
The targets 'xmldocs', 'psdocs', 'pdfdocs', and 'htmldocs' are used
|
The targets 'xmldocs', 'latexdocs', 'pdfdocs', 'epubdocs'and 'htmldocs'
|
||||||
to build XML DocBook files, PostScript files, PDF files, and html files
|
are used to build XML DocBook files, LaTeX files, PDF files,
|
||||||
in Documentation/DocBook. The older target 'sgmldocs' is equivalent
|
ePub files and html files in Documentation/.
|
||||||
to 'xmldocs'.
|
|
||||||
|
|
||||||
- Documentation/DocBook/Makefile
|
|
||||||
|
|
||||||
This is where C files are associated with SGML templates.
|
|
||||||
|
|
||||||
|
|
||||||
How to extract the documentation
|
How to extract the documentation
|
||||||
--------------------------------
|
--------------------------------
|
||||||
|
|
||||||
If you just want to read the ready-made books on the various
|
If you just want to read the ready-made books on the various
|
||||||
subsystems (see Documentation/DocBook/*.tmpl), just type 'make
|
subsystems, just type 'make epubdocs', or 'make pdfdocs', or 'make htmldocs',
|
||||||
psdocs', or 'make pdfdocs', or 'make htmldocs', depending on your
|
depending on your preference. If you would rather read a different format,
|
||||||
preference. If you would rather read a different format, you can type
|
you can type 'make xmldocs' and then use DocBook tools to convert
|
||||||
'make xmldocs' and then use DocBook tools to convert
|
Documentation/output/*.xml to a format of your choice (for example,
|
||||||
Documentation/DocBook/*.xml to a format of your choice (for example,
|
|
||||||
'db2html ...' if 'make htmldocs' was not defined).
|
'db2html ...' if 'make htmldocs' was not defined).
|
||||||
|
|
||||||
If you want to see man pages instead, you can do this:
|
If you want to see man pages instead, you can do this:
|
||||||
|
@ -329,37 +316,7 @@ This is done by using a DOC: section keyword with a section title. E.g.:
|
||||||
* hardware, software, or its subject(s).
|
* hardware, software, or its subject(s).
|
||||||
*/
|
*/
|
||||||
|
|
||||||
DOC: sections are used in SGML templates files as indicated below.
|
DOC: sections are used in ReST files.
|
||||||
|
|
||||||
|
|
||||||
How to make new SGML template files
|
|
||||||
-----------------------------------
|
|
||||||
|
|
||||||
SGML template files (*.tmpl) are like normal SGML files, except that
|
|
||||||
they can contain escape sequences where extracted documentation should
|
|
||||||
be inserted.
|
|
||||||
|
|
||||||
!E<filename> is replaced by the documentation, in <filename>, for
|
|
||||||
functions that are exported using EXPORT_SYMBOL: the function list is
|
|
||||||
collected from files listed in Documentation/DocBook/Makefile.
|
|
||||||
|
|
||||||
!I<filename> is replaced by the documentation for functions that are
|
|
||||||
_not_ exported using EXPORT_SYMBOL.
|
|
||||||
|
|
||||||
!D<filename> is used to name additional files to search for functions
|
|
||||||
exported using EXPORT_SYMBOL.
|
|
||||||
|
|
||||||
!F<filename> <function [functions...]> is replaced by the
|
|
||||||
documentation, in <filename>, for the functions listed.
|
|
||||||
|
|
||||||
!P<filename> <section title> is replaced by the contents of the DOC:
|
|
||||||
section titled <section title> from <filename>.
|
|
||||||
Spaces are allowed in <section title>; do not quote the <section title>.
|
|
||||||
|
|
||||||
!C<filename> is replaced by nothing, but makes the tools check that
|
|
||||||
all DOC: sections and documented functions, symbols, etc. are used.
|
|
||||||
This makes sense to use when you use !F/!P only and want to verify
|
|
||||||
that all documentation is included.
|
|
||||||
|
|
||||||
Tim.
|
Tim.
|
||||||
*/ <twaugh@redhat.com>
|
*/ <twaugh@redhat.com>
|
||||||
|
|
10
Documentation/kernel-hacking/conf.py
Normal file
10
Documentation/kernel-hacking/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = "Kernel Hacking Guides"
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'kernel-hacking.tex', project,
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
811
Documentation/kernel-hacking/hacking.rst
Normal file
811
Documentation/kernel-hacking/hacking.rst
Normal file
|
@ -0,0 +1,811 @@
|
||||||
|
============================================
|
||||||
|
Unreliable Guide To Hacking The Linux Kernel
|
||||||
|
============================================
|
||||||
|
|
||||||
|
:Author: Rusty Russell
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
|
||||||
|
Kernel Hacking. This document describes the common routines and general
|
||||||
|
requirements for kernel code: its goal is to serve as a primer for Linux
|
||||||
|
kernel development for experienced C programmers. I avoid implementation
|
||||||
|
details: that's what the code is for, and I ignore whole tracts of
|
||||||
|
useful routines.
|
||||||
|
|
||||||
|
Before you read this, please understand that I never wanted to write
|
||||||
|
this document, being grossly under-qualified, but I always wanted to
|
||||||
|
read it, and this was the only way. I hope it will grow into a
|
||||||
|
compendium of best practice, common starting points and random
|
||||||
|
information.
|
||||||
|
|
||||||
|
The Players
|
||||||
|
===========
|
||||||
|
|
||||||
|
At any time each of the CPUs in a system can be:
|
||||||
|
|
||||||
|
- not associated with any process, serving a hardware interrupt;
|
||||||
|
|
||||||
|
- not associated with any process, serving a softirq or tasklet;
|
||||||
|
|
||||||
|
- running in kernel space, associated with a process (user context);
|
||||||
|
|
||||||
|
- running a process in user space.
|
||||||
|
|
||||||
|
There is an ordering between these. The bottom two can preempt each
|
||||||
|
other, but above that is a strict hierarchy: each can only be preempted
|
||||||
|
by the ones above it. For example, while a softirq is running on a CPU,
|
||||||
|
no other softirq will preempt it, but a hardware interrupt can. However,
|
||||||
|
any other CPUs in the system execute independently.
|
||||||
|
|
||||||
|
We'll see a number of ways that the user context can block interrupts,
|
||||||
|
to become truly non-preemptable.
|
||||||
|
|
||||||
|
User Context
|
||||||
|
------------
|
||||||
|
|
||||||
|
User context is when you are coming in from a system call or other trap:
|
||||||
|
like userspace, you can be preempted by more important tasks and by
|
||||||
|
interrupts. You can sleep, by calling :c:func:`schedule()`.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
You are always in user context on module load and unload, and on
|
||||||
|
operations on the block device layer.
|
||||||
|
|
||||||
|
In user context, the ``current`` pointer (indicating the task we are
|
||||||
|
currently executing) is valid, and :c:func:`in_interrupt()`
|
||||||
|
(``include/linux/preempt.h``) is false.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Beware that if you have preemption or softirqs disabled (see below),
|
||||||
|
:c:func:`in_interrupt()` will return a false positive.
|
||||||
|
|
||||||
|
Hardware Interrupts (Hard IRQs)
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
Timer ticks, network cards and keyboard are examples of real hardware
|
||||||
|
which produce interrupts at any time. The kernel runs interrupt
|
||||||
|
handlers, which services the hardware. The kernel guarantees that this
|
||||||
|
handler is never re-entered: if the same interrupt arrives, it is queued
|
||||||
|
(or dropped). Because it disables interrupts, this handler has to be
|
||||||
|
fast: frequently it simply acknowledges the interrupt, marks a 'software
|
||||||
|
interrupt' for execution and exits.
|
||||||
|
|
||||||
|
You can tell you are in a hardware interrupt, because
|
||||||
|
:c:func:`in_irq()` returns true.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Beware that this will return a false positive if interrupts are
|
||||||
|
disabled (see below).
|
||||||
|
|
||||||
|
Software Interrupt Context: Softirqs and Tasklets
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
Whenever a system call is about to return to userspace, or a hardware
|
||||||
|
interrupt handler exits, any 'software interrupts' which are marked
|
||||||
|
pending (usually by hardware interrupts) are run (``kernel/softirq.c``).
|
||||||
|
|
||||||
|
Much of the real interrupt handling work is done here. Early in the
|
||||||
|
transition to SMP, there were only 'bottom halves' (BHs), which didn't
|
||||||
|
take advantage of multiple CPUs. Shortly after we switched from wind-up
|
||||||
|
computers made of match-sticks and snot, we abandoned this limitation
|
||||||
|
and switched to 'softirqs'.
|
||||||
|
|
||||||
|
``include/linux/interrupt.h`` lists the different softirqs. A very
|
||||||
|
important softirq is the timer softirq (``include/linux/timer.h``): you
|
||||||
|
can register to have it call functions for you in a given length of
|
||||||
|
time.
|
||||||
|
|
||||||
|
Softirqs are often a pain to deal with, since the same softirq will run
|
||||||
|
simultaneously on more than one CPU. For this reason, tasklets
|
||||||
|
(``include/linux/interrupt.h``) are more often used: they are
|
||||||
|
dynamically-registrable (meaning you can have as many as you want), and
|
||||||
|
they also guarantee that any tasklet will only run on one CPU at any
|
||||||
|
time, although different tasklets can run simultaneously.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The name 'tasklet' is misleading: they have nothing to do with
|
||||||
|
'tasks', and probably more to do with some bad vodka Alexey
|
||||||
|
Kuznetsov had at the time.
|
||||||
|
|
||||||
|
You can tell you are in a softirq (or tasklet) using the
|
||||||
|
:c:func:`in_softirq()` macro (``include/linux/preempt.h``).
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Beware that this will return a false positive if a
|
||||||
|
:ref:`botton half lock <local_bh_disable>` is held.
|
||||||
|
|
||||||
|
Some Basic Rules
|
||||||
|
================
|
||||||
|
|
||||||
|
No memory protection
|
||||||
|
If you corrupt memory, whether in user context or interrupt context,
|
||||||
|
the whole machine will crash. Are you sure you can't do what you
|
||||||
|
want in userspace?
|
||||||
|
|
||||||
|
No floating point or MMX
|
||||||
|
The FPU context is not saved; even in user context the FPU state
|
||||||
|
probably won't correspond with the current process: you would mess
|
||||||
|
with some user process' FPU state. If you really want to do this,
|
||||||
|
you would have to explicitly save/restore the full FPU state (and
|
||||||
|
avoid context switches). It is generally a bad idea; use fixed point
|
||||||
|
arithmetic first.
|
||||||
|
|
||||||
|
A rigid stack limit
|
||||||
|
Depending on configuration options the kernel stack is about 3K to
|
||||||
|
6K for most 32-bit architectures: it's about 14K on most 64-bit
|
||||||
|
archs, and often shared with interrupts so you can't use it all.
|
||||||
|
Avoid deep recursion and huge local arrays on the stack (allocate
|
||||||
|
them dynamically instead).
|
||||||
|
|
||||||
|
The Linux kernel is portable
|
||||||
|
Let's keep it that way. Your code should be 64-bit clean, and
|
||||||
|
endian-independent. You should also minimize CPU specific stuff,
|
||||||
|
e.g. inline assembly should be cleanly encapsulated and minimized to
|
||||||
|
ease porting. Generally it should be restricted to the
|
||||||
|
architecture-dependent part of the kernel tree.
|
||||||
|
|
||||||
|
ioctls: Not writing a new system call
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
A system call generally looks like this::
|
||||||
|
|
||||||
|
asmlinkage long sys_mycall(int arg)
|
||||||
|
{
|
||||||
|
return 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
First, in most cases you don't want to create a new system call. You
|
||||||
|
create a character device and implement an appropriate ioctl for it.
|
||||||
|
This is much more flexible than system calls, doesn't have to be entered
|
||||||
|
in every architecture's ``include/asm/unistd.h`` and
|
||||||
|
``arch/kernel/entry.S`` file, and is much more likely to be accepted by
|
||||||
|
Linus.
|
||||||
|
|
||||||
|
If all your routine does is read or write some parameter, consider
|
||||||
|
implementing a :c:func:`sysfs()` interface instead.
|
||||||
|
|
||||||
|
Inside the ioctl you're in user context to a process. When a error
|
||||||
|
occurs you return a negated errno (see
|
||||||
|
``include/uapi/asm-generic/errno-base.h``,
|
||||||
|
``include/uapi/asm-generic/errno.h`` and ``include/linux/errno.h``),
|
||||||
|
otherwise you return 0.
|
||||||
|
|
||||||
|
After you slept you should check if a signal occurred: the Unix/Linux
|
||||||
|
way of handling signals is to temporarily exit the system call with the
|
||||||
|
``-ERESTARTSYS`` error. The system call entry code will switch back to
|
||||||
|
user context, process the signal handler and then your system call will
|
||||||
|
be restarted (unless the user disabled that). So you should be prepared
|
||||||
|
to process the restart, e.g. if you're in the middle of manipulating
|
||||||
|
some data structure.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
if (signal_pending(current))
|
||||||
|
return -ERESTARTSYS;
|
||||||
|
|
||||||
|
|
||||||
|
If you're doing longer computations: first think userspace. If you
|
||||||
|
**really** want to do it in kernel you should regularly check if you need
|
||||||
|
to give up the CPU (remember there is cooperative multitasking per CPU).
|
||||||
|
Idiom::
|
||||||
|
|
||||||
|
cond_resched(); /* Will sleep */
|
||||||
|
|
||||||
|
|
||||||
|
A short note on interface design: the UNIX system call motto is "Provide
|
||||||
|
mechanism not policy".
|
||||||
|
|
||||||
|
Recipes for Deadlock
|
||||||
|
====================
|
||||||
|
|
||||||
|
You cannot call any routines which may sleep, unless:
|
||||||
|
|
||||||
|
- You are in user context.
|
||||||
|
|
||||||
|
- You do not own any spinlocks.
|
||||||
|
|
||||||
|
- You have interrupts enabled (actually, Andi Kleen says that the
|
||||||
|
scheduling code will enable them for you, but that's probably not
|
||||||
|
what you wanted).
|
||||||
|
|
||||||
|
Note that some functions may sleep implicitly: common ones are the user
|
||||||
|
space access functions (\*_user) and memory allocation functions
|
||||||
|
without ``GFP_ATOMIC``.
|
||||||
|
|
||||||
|
You should always compile your kernel ``CONFIG_DEBUG_ATOMIC_SLEEP`` on,
|
||||||
|
and it will warn you if you break these rules. If you **do** break the
|
||||||
|
rules, you will eventually lock up your box.
|
||||||
|
|
||||||
|
Really.
|
||||||
|
|
||||||
|
Common Routines
|
||||||
|
===============
|
||||||
|
|
||||||
|
:c:func:`printk()`
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/printk.h``
|
||||||
|
|
||||||
|
:c:func:`printk()` feeds kernel messages to the console, dmesg, and
|
||||||
|
the syslog daemon. It is useful for debugging and reporting errors, and
|
||||||
|
can be used inside interrupt context, but use with caution: a machine
|
||||||
|
which has its console flooded with printk messages is unusable. It uses
|
||||||
|
a format string mostly compatible with ANSI C printf, and C string
|
||||||
|
concatenation to give it a first "priority" argument::
|
||||||
|
|
||||||
|
printk(KERN_INFO "i = %u\n", i);
|
||||||
|
|
||||||
|
|
||||||
|
See ``include/linux/kern_levels.h``; for other ``KERN_`` values; these are
|
||||||
|
interpreted by syslog as the level. Special case: for printing an IP
|
||||||
|
address use::
|
||||||
|
|
||||||
|
__be32 ipaddress;
|
||||||
|
printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
|
||||||
|
|
||||||
|
|
||||||
|
:c:func:`printk()` internally uses a 1K buffer and does not catch
|
||||||
|
overruns. Make sure that will be enough.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
You will know when you are a real kernel hacker when you start
|
||||||
|
typoing printf as printk in your user programs :)
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Another sidenote: the original Unix Version 6 sources had a comment
|
||||||
|
on top of its printf function: "Printf should not be used for
|
||||||
|
chit-chat". You should follow that advice.
|
||||||
|
|
||||||
|
:c:func:`copy_to_user()` / :c:func:`copy_from_user()` / :c:func:`get_user()` / :c:func:`put_user()`
|
||||||
|
---------------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/uaccess.h`` / ``asm/uaccess.h``
|
||||||
|
|
||||||
|
**[SLEEPS]**
|
||||||
|
|
||||||
|
:c:func:`put_user()` and :c:func:`get_user()` are used to get
|
||||||
|
and put single values (such as an int, char, or long) from and to
|
||||||
|
userspace. A pointer into userspace should never be simply dereferenced:
|
||||||
|
data should be copied using these routines. Both return ``-EFAULT`` or
|
||||||
|
0.
|
||||||
|
|
||||||
|
:c:func:`copy_to_user()` and :c:func:`copy_from_user()` are
|
||||||
|
more general: they copy an arbitrary amount of data to and from
|
||||||
|
userspace.
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
Unlike :c:func:`put_user()` and :c:func:`get_user()`, they
|
||||||
|
return the amount of uncopied data (ie. 0 still means success).
|
||||||
|
|
||||||
|
[Yes, this moronic interface makes me cringe. The flamewar comes up
|
||||||
|
every year or so. --RR.]
|
||||||
|
|
||||||
|
The functions may sleep implicitly. This should never be called outside
|
||||||
|
user context (it makes no sense), with interrupts disabled, or a
|
||||||
|
spinlock held.
|
||||||
|
|
||||||
|
:c:func:`kmalloc()`/:c:func:`kfree()`
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/slab.h``
|
||||||
|
|
||||||
|
**[MAY SLEEP: SEE BELOW]**
|
||||||
|
|
||||||
|
These routines are used to dynamically request pointer-aligned chunks of
|
||||||
|
memory, like malloc and free do in userspace, but
|
||||||
|
:c:func:`kmalloc()` takes an extra flag word. Important values:
|
||||||
|
|
||||||
|
``GFP_KERNEL``
|
||||||
|
May sleep and swap to free memory. Only allowed in user context, but
|
||||||
|
is the most reliable way to allocate memory.
|
||||||
|
|
||||||
|
``GFP_ATOMIC``
|
||||||
|
Don't sleep. Less reliable than ``GFP_KERNEL``, but may be called
|
||||||
|
from interrupt context. You should **really** have a good
|
||||||
|
out-of-memory error-handling strategy.
|
||||||
|
|
||||||
|
``GFP_DMA``
|
||||||
|
Allocate ISA DMA lower than 16MB. If you don't know what that is you
|
||||||
|
don't need it. Very unreliable.
|
||||||
|
|
||||||
|
If you see a sleeping function called from invalid context warning
|
||||||
|
message, then maybe you called a sleeping allocation function from
|
||||||
|
interrupt context without ``GFP_ATOMIC``. You should really fix that.
|
||||||
|
Run, don't walk.
|
||||||
|
|
||||||
|
If you are allocating at least ``PAGE_SIZE`` (``asm/page.h`` or
|
||||||
|
``asm/page_types.h``) bytes, consider using :c:func:`__get_free_pages()`
|
||||||
|
(``include/linux/gfp.h``). It takes an order argument (0 for page sized,
|
||||||
|
1 for double page, 2 for four pages etc.) and the same memory priority
|
||||||
|
flag word as above.
|
||||||
|
|
||||||
|
If you are allocating more than a page worth of bytes you can use
|
||||||
|
:c:func:`vmalloc()`. It'll allocate virtual memory in the kernel
|
||||||
|
map. This block is not contiguous in physical memory, but the MMU makes
|
||||||
|
it look like it is for you (so it'll only look contiguous to the CPUs,
|
||||||
|
not to external device drivers). If you really need large physically
|
||||||
|
contiguous memory for some weird device, you have a problem: it is
|
||||||
|
poorly supported in Linux because after some time memory fragmentation
|
||||||
|
in a running kernel makes it hard. The best way is to allocate the block
|
||||||
|
early in the boot process via the :c:func:`alloc_bootmem()`
|
||||||
|
routine.
|
||||||
|
|
||||||
|
Before inventing your own cache of often-used objects consider using a
|
||||||
|
slab cache in ``include/linux/slab.h``
|
||||||
|
|
||||||
|
:c:func:`current()`
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Defined in ``include/asm/current.h``
|
||||||
|
|
||||||
|
This global variable (really a macro) contains a pointer to the current
|
||||||
|
task structure, so is only valid in user context. For example, when a
|
||||||
|
process makes a system call, this will point to the task structure of
|
||||||
|
the calling process. It is **not NULL** in interrupt context.
|
||||||
|
|
||||||
|
:c:func:`mdelay()`/:c:func:`udelay()`
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/asm/delay.h`` / ``include/linux/delay.h``
|
||||||
|
|
||||||
|
The :c:func:`udelay()` and :c:func:`ndelay()` functions can be
|
||||||
|
used for small pauses. Do not use large values with them as you risk
|
||||||
|
overflow - the helper function :c:func:`mdelay()` is useful here, or
|
||||||
|
consider :c:func:`msleep()`.
|
||||||
|
|
||||||
|
:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()`
|
||||||
|
-----------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/asm/byteorder.h``
|
||||||
|
|
||||||
|
The :c:func:`cpu_to_be32()` family (where the "32" can be replaced
|
||||||
|
by 64 or 16, and the "be" can be replaced by "le") are the general way
|
||||||
|
to do endian conversions in the kernel: they return the converted value.
|
||||||
|
All variations supply the reverse as well:
|
||||||
|
:c:func:`be32_to_cpu()`, etc.
|
||||||
|
|
||||||
|
There are two major variations of these functions: the pointer
|
||||||
|
variation, such as :c:func:`cpu_to_be32p()`, which take a pointer
|
||||||
|
to the given type, and return the converted value. The other variation
|
||||||
|
is the "in-situ" family, such as :c:func:`cpu_to_be32s()`, which
|
||||||
|
convert value referred to by the pointer, and return void.
|
||||||
|
|
||||||
|
:c:func:`local_irq_save()`/:c:func:`local_irq_restore()`
|
||||||
|
--------------------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/irqflags.h``
|
||||||
|
|
||||||
|
These routines disable hard interrupts on the local CPU, and restore
|
||||||
|
them. They are reentrant; saving the previous state in their one
|
||||||
|
``unsigned long flags`` argument. If you know that interrupts are
|
||||||
|
enabled, you can simply use :c:func:`local_irq_disable()` and
|
||||||
|
:c:func:`local_irq_enable()`.
|
||||||
|
|
||||||
|
.. _local_bh_disable:
|
||||||
|
|
||||||
|
:c:func:`local_bh_disable()`/:c:func:`local_bh_enable()`
|
||||||
|
--------------------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/bottom_half.h``
|
||||||
|
|
||||||
|
|
||||||
|
These routines disable soft interrupts on the local CPU, and restore
|
||||||
|
them. They are reentrant; if soft interrupts were disabled before, they
|
||||||
|
will still be disabled after this pair of functions has been called.
|
||||||
|
They prevent softirqs and tasklets from running on the current CPU.
|
||||||
|
|
||||||
|
:c:func:`smp_processor_id()`
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/smp.h``
|
||||||
|
|
||||||
|
:c:func:`get_cpu()` disables preemption (so you won't suddenly get
|
||||||
|
moved to another CPU) and returns the current processor number, between
|
||||||
|
0 and ``NR_CPUS``. Note that the CPU numbers are not necessarily
|
||||||
|
continuous. You return it again with :c:func:`put_cpu()` when you
|
||||||
|
are done.
|
||||||
|
|
||||||
|
If you know you cannot be preempted by another task (ie. you are in
|
||||||
|
interrupt context, or have preemption disabled) you can use
|
||||||
|
smp_processor_id().
|
||||||
|
|
||||||
|
``__init``/``__exit``/``__initdata``
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/init.h``
|
||||||
|
|
||||||
|
After boot, the kernel frees up a special section; functions marked with
|
||||||
|
``__init`` and data structures marked with ``__initdata`` are dropped
|
||||||
|
after boot is complete: similarly modules discard this memory after
|
||||||
|
initialization. ``__exit`` is used to declare a function which is only
|
||||||
|
required on exit: the function will be dropped if this file is not
|
||||||
|
compiled as a module. See the header file for use. Note that it makes no
|
||||||
|
sense for a function marked with ``__init`` to be exported to modules
|
||||||
|
with :c:func:`EXPORT_SYMBOL()` or :c:func:`EXPORT_SYMBOL_GPL()`- this
|
||||||
|
will break.
|
||||||
|
|
||||||
|
:c:func:`__initcall()`/:c:func:`module_init()`
|
||||||
|
----------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/init.h`` / ``include/linux/module.h``
|
||||||
|
|
||||||
|
Many parts of the kernel are well served as a module
|
||||||
|
(dynamically-loadable parts of the kernel). Using the
|
||||||
|
:c:func:`module_init()` and :c:func:`module_exit()` macros it
|
||||||
|
is easy to write code without #ifdefs which can operate both as a module
|
||||||
|
or built into the kernel.
|
||||||
|
|
||||||
|
The :c:func:`module_init()` macro defines which function is to be
|
||||||
|
called at module insertion time (if the file is compiled as a module),
|
||||||
|
or at boot time: if the file is not compiled as a module the
|
||||||
|
:c:func:`module_init()` macro becomes equivalent to
|
||||||
|
:c:func:`__initcall()`, which through linker magic ensures that
|
||||||
|
the function is called on boot.
|
||||||
|
|
||||||
|
The function can return a negative error number to cause module loading
|
||||||
|
to fail (unfortunately, this has no effect if the module is compiled
|
||||||
|
into the kernel). This function is called in user context with
|
||||||
|
interrupts enabled, so it can sleep.
|
||||||
|
|
||||||
|
:c:func:`module_exit()`
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
|
||||||
|
Defined in ``include/linux/module.h``
|
||||||
|
|
||||||
|
This macro defines the function to be called at module removal time (or
|
||||||
|
never, in the case of the file compiled into the kernel). It will only
|
||||||
|
be called if the module usage count has reached zero. This function can
|
||||||
|
also sleep, but cannot fail: everything must be cleaned up by the time
|
||||||
|
it returns.
|
||||||
|
|
||||||
|
Note that this macro is optional: if it is not present, your module will
|
||||||
|
not be removable (except for 'rmmod -f').
|
||||||
|
|
||||||
|
:c:func:`try_module_get()`/:c:func:`module_put()`
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/module.h``
|
||||||
|
|
||||||
|
These manipulate the module usage count, to protect against removal (a
|
||||||
|
module also can't be removed if another module uses one of its exported
|
||||||
|
symbols: see below). Before calling into module code, you should call
|
||||||
|
:c:func:`try_module_get()` on that module: if it fails, then the
|
||||||
|
module is being removed and you should act as if it wasn't there.
|
||||||
|
Otherwise, you can safely enter the module, and call
|
||||||
|
:c:func:`module_put()` when you're finished.
|
||||||
|
|
||||||
|
Most registerable structures have an owner field, such as in the
|
||||||
|
:c:type:`struct file_operations <file_operations>` structure.
|
||||||
|
Set this field to the macro ``THIS_MODULE``.
|
||||||
|
|
||||||
|
Wait Queues ``include/linux/wait.h``
|
||||||
|
====================================
|
||||||
|
|
||||||
|
**[SLEEPS]**
|
||||||
|
|
||||||
|
A wait queue is used to wait for someone to wake you up when a certain
|
||||||
|
condition is true. They must be used carefully to ensure there is no
|
||||||
|
race condition. You declare a :c:type:`wait_queue_head_t`, and then processes
|
||||||
|
which want to wait for that condition declare a :c:type:`wait_queue_entry_t`
|
||||||
|
referring to themselves, and place that in the queue.
|
||||||
|
|
||||||
|
Declaring
|
||||||
|
---------
|
||||||
|
|
||||||
|
You declare a ``wait_queue_head_t`` using the
|
||||||
|
:c:func:`DECLARE_WAIT_QUEUE_HEAD()` macro, or using the
|
||||||
|
:c:func:`init_waitqueue_head()` routine in your initialization
|
||||||
|
code.
|
||||||
|
|
||||||
|
Queuing
|
||||||
|
-------
|
||||||
|
|
||||||
|
Placing yourself in the waitqueue is fairly complex, because you must
|
||||||
|
put yourself in the queue before checking the condition. There is a
|
||||||
|
macro to do this: :c:func:`wait_event_interruptible()`
|
||||||
|
(``include/linux/wait.h``) The first argument is the wait queue head, and
|
||||||
|
the second is an expression which is evaluated; the macro returns 0 when
|
||||||
|
this expression is true, or ``-ERESTARTSYS`` if a signal is received. The
|
||||||
|
:c:func:`wait_event()` version ignores signals.
|
||||||
|
|
||||||
|
Waking Up Queued Tasks
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Call :c:func:`wake_up()` (``include/linux/wait.h``);, which will wake
|
||||||
|
up every process in the queue. The exception is if one has
|
||||||
|
``TASK_EXCLUSIVE`` set, in which case the remainder of the queue will
|
||||||
|
not be woken. There are other variants of this basic function available
|
||||||
|
in the same header.
|
||||||
|
|
||||||
|
Atomic Operations
|
||||||
|
=================
|
||||||
|
|
||||||
|
Certain operations are guaranteed atomic on all platforms. The first
|
||||||
|
class of operations work on :c:type:`atomic_t` (``include/asm/atomic.h``);
|
||||||
|
this contains a signed integer (at least 32 bits long), and you must use
|
||||||
|
these functions to manipulate or read :c:type:`atomic_t` variables.
|
||||||
|
:c:func:`atomic_read()` and :c:func:`atomic_set()` get and set
|
||||||
|
the counter, :c:func:`atomic_add()`, :c:func:`atomic_sub()`,
|
||||||
|
:c:func:`atomic_inc()`, :c:func:`atomic_dec()`, and
|
||||||
|
:c:func:`atomic_dec_and_test()` (returns true if it was
|
||||||
|
decremented to zero).
|
||||||
|
|
||||||
|
Yes. It returns true (i.e. != 0) if the atomic variable is zero.
|
||||||
|
|
||||||
|
Note that these functions are slower than normal arithmetic, and so
|
||||||
|
should not be used unnecessarily.
|
||||||
|
|
||||||
|
The second class of atomic operations is atomic bit operations on an
|
||||||
|
``unsigned long``, defined in ``include/linux/bitops.h``. These
|
||||||
|
operations generally take a pointer to the bit pattern, and a bit
|
||||||
|
number: 0 is the least significant bit. :c:func:`set_bit()`,
|
||||||
|
:c:func:`clear_bit()` and :c:func:`change_bit()` set, clear,
|
||||||
|
and flip the given bit. :c:func:`test_and_set_bit()`,
|
||||||
|
:c:func:`test_and_clear_bit()` and
|
||||||
|
:c:func:`test_and_change_bit()` do the same thing, except return
|
||||||
|
true if the bit was previously set; these are particularly useful for
|
||||||
|
atomically setting flags.
|
||||||
|
|
||||||
|
It is possible to call these operations with bit indices greater than
|
||||||
|
``BITS_PER_LONG``. The resulting behavior is strange on big-endian
|
||||||
|
platforms though so it is a good idea not to do this.
|
||||||
|
|
||||||
|
Symbols
|
||||||
|
=======
|
||||||
|
|
||||||
|
Within the kernel proper, the normal linking rules apply (ie. unless a
|
||||||
|
symbol is declared to be file scope with the ``static`` keyword, it can
|
||||||
|
be used anywhere in the kernel). However, for modules, a special
|
||||||
|
exported symbol table is kept which limits the entry points to the
|
||||||
|
kernel proper. Modules can also export symbols.
|
||||||
|
|
||||||
|
:c:func:`EXPORT_SYMBOL()`
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/export.h``
|
||||||
|
|
||||||
|
This is the classic method of exporting a symbol: dynamically loaded
|
||||||
|
modules will be able to use the symbol as normal.
|
||||||
|
|
||||||
|
:c:func:`EXPORT_SYMBOL_GPL()`
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
Defined in ``include/linux/export.h``
|
||||||
|
|
||||||
|
Similar to :c:func:`EXPORT_SYMBOL()` except that the symbols
|
||||||
|
exported by :c:func:`EXPORT_SYMBOL_GPL()` can only be seen by
|
||||||
|
modules with a :c:func:`MODULE_LICENSE()` that specifies a GPL
|
||||||
|
compatible license. It implies that the function is considered an
|
||||||
|
internal implementation issue, and not really an interface. Some
|
||||||
|
maintainers and developers may however require EXPORT_SYMBOL_GPL()
|
||||||
|
when adding any new APIs or functionality.
|
||||||
|
|
||||||
|
Routines and Conventions
|
||||||
|
========================
|
||||||
|
|
||||||
|
Double-linked lists ``include/linux/list.h``
|
||||||
|
--------------------------------------------
|
||||||
|
|
||||||
|
There used to be three sets of linked-list routines in the kernel
|
||||||
|
headers, but this one is the winner. If you don't have some particular
|
||||||
|
pressing need for a single list, it's a good choice.
|
||||||
|
|
||||||
|
In particular, :c:func:`list_for_each_entry()` is useful.
|
||||||
|
|
||||||
|
Return Conventions
|
||||||
|
------------------
|
||||||
|
|
||||||
|
For code called in user context, it's very common to defy C convention,
|
||||||
|
and return 0 for success, and a negative error number (eg. ``-EFAULT``) for
|
||||||
|
failure. This can be unintuitive at first, but it's fairly widespread in
|
||||||
|
the kernel.
|
||||||
|
|
||||||
|
Using :c:func:`ERR_PTR()` (``include/linux/err.h``) to encode a
|
||||||
|
negative error number into a pointer, and :c:func:`IS_ERR()` and
|
||||||
|
:c:func:`PTR_ERR()` to get it back out again: avoids a separate
|
||||||
|
pointer parameter for the error number. Icky, but in a good way.
|
||||||
|
|
||||||
|
Breaking Compilation
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Linus and the other developers sometimes change function or structure
|
||||||
|
names in development kernels; this is not done just to keep everyone on
|
||||||
|
their toes: it reflects a fundamental change (eg. can no longer be
|
||||||
|
called with interrupts on, or does extra checks, or doesn't do checks
|
||||||
|
which were caught before). Usually this is accompanied by a fairly
|
||||||
|
complete note to the linux-kernel mailing list; search the archive.
|
||||||
|
Simply doing a global replace on the file usually makes things **worse**.
|
||||||
|
|
||||||
|
Initializing structure members
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
The preferred method of initializing structures is to use designated
|
||||||
|
initialisers, as defined by ISO C99, eg::
|
||||||
|
|
||||||
|
static struct block_device_operations opt_fops = {
|
||||||
|
.open = opt_open,
|
||||||
|
.release = opt_release,
|
||||||
|
.ioctl = opt_ioctl,
|
||||||
|
.check_media_change = opt_media_change,
|
||||||
|
};
|
||||||
|
|
||||||
|
|
||||||
|
This makes it easy to grep for, and makes it clear which structure
|
||||||
|
fields are set. You should do this because it looks cool.
|
||||||
|
|
||||||
|
GNU Extensions
|
||||||
|
--------------
|
||||||
|
|
||||||
|
GNU Extensions are explicitly allowed in the Linux kernel. Note that
|
||||||
|
some of the more complex ones are not very well supported, due to lack
|
||||||
|
of general use, but the following are considered standard (see the GCC
|
||||||
|
info page section "C Extensions" for more details - Yes, really the info
|
||||||
|
page, the man page is only a short summary of the stuff in info).
|
||||||
|
|
||||||
|
- Inline functions
|
||||||
|
|
||||||
|
- Statement expressions (ie. the ({ and }) constructs).
|
||||||
|
|
||||||
|
- Declaring attributes of a function / variable / type
|
||||||
|
(__attribute__)
|
||||||
|
|
||||||
|
- typeof
|
||||||
|
|
||||||
|
- Zero length arrays
|
||||||
|
|
||||||
|
- Macro varargs
|
||||||
|
|
||||||
|
- Arithmetic on void pointers
|
||||||
|
|
||||||
|
- Non-Constant initializers
|
||||||
|
|
||||||
|
- Assembler Instructions (not outside arch/ and include/asm/)
|
||||||
|
|
||||||
|
- Function names as strings (__func__).
|
||||||
|
|
||||||
|
- __builtin_constant_p()
|
||||||
|
|
||||||
|
Be wary when using long long in the kernel, the code gcc generates for
|
||||||
|
it is horrible and worse: division and multiplication does not work on
|
||||||
|
i386 because the GCC runtime functions for it are missing from the
|
||||||
|
kernel environment.
|
||||||
|
|
||||||
|
C++
|
||||||
|
---
|
||||||
|
|
||||||
|
Using C++ in the kernel is usually a bad idea, because the kernel does
|
||||||
|
not provide the necessary runtime environment and the include files are
|
||||||
|
not tested for it. It is still possible, but not recommended. If you
|
||||||
|
really want to do this, forget about exceptions at least.
|
||||||
|
|
||||||
|
NUMif
|
||||||
|
-----
|
||||||
|
|
||||||
|
It is generally considered cleaner to use macros in header files (or at
|
||||||
|
the top of .c files) to abstract away functions rather than using \`#if'
|
||||||
|
pre-processor statements throughout the source code.
|
||||||
|
|
||||||
|
Putting Your Stuff in the Kernel
|
||||||
|
================================
|
||||||
|
|
||||||
|
In order to get your stuff into shape for official inclusion, or even to
|
||||||
|
make a neat patch, there's administrative work to be done:
|
||||||
|
|
||||||
|
- Figure out whose pond you've been pissing in. Look at the top of the
|
||||||
|
source files, inside the ``MAINTAINERS`` file, and last of all in the
|
||||||
|
``CREDITS`` file. You should coordinate with this person to make sure
|
||||||
|
you're not duplicating effort, or trying something that's already
|
||||||
|
been rejected.
|
||||||
|
|
||||||
|
Make sure you put your name and EMail address at the top of any files
|
||||||
|
you create or mangle significantly. This is the first place people
|
||||||
|
will look when they find a bug, or when **they** want to make a change.
|
||||||
|
|
||||||
|
- Usually you want a configuration option for your kernel hack. Edit
|
||||||
|
``Kconfig`` in the appropriate directory. The Config language is
|
||||||
|
simple to use by cut and paste, and there's complete documentation in
|
||||||
|
``Documentation/kbuild/kconfig-language.txt``.
|
||||||
|
|
||||||
|
In your description of the option, make sure you address both the
|
||||||
|
expert user and the user who knows nothing about your feature.
|
||||||
|
Mention incompatibilities and issues here. **Definitely** end your
|
||||||
|
description with “if in doubt, say N” (or, occasionally, \`Y'); this
|
||||||
|
is for people who have no idea what you are talking about.
|
||||||
|
|
||||||
|
- Edit the ``Makefile``: the CONFIG variables are exported here so you
|
||||||
|
can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
|
||||||
|
is documented in ``Documentation/kbuild/makefiles.txt``.
|
||||||
|
|
||||||
|
- Put yourself in ``CREDITS`` if you've done something noteworthy,
|
||||||
|
usually beyond a single file (your name should be at the top of the
|
||||||
|
source files anyway). ``MAINTAINERS`` means you want to be consulted
|
||||||
|
when changes are made to a subsystem, and hear about bugs; it implies
|
||||||
|
a more-than-passing commitment to some part of the code.
|
||||||
|
|
||||||
|
- Finally, don't forget to read
|
||||||
|
``Documentation/process/submitting-patches.rst`` and possibly
|
||||||
|
``Documentation/process/submitting-drivers.rst``.
|
||||||
|
|
||||||
|
Kernel Cantrips
|
||||||
|
===============
|
||||||
|
|
||||||
|
Some favorites from browsing the source. Feel free to add to this list.
|
||||||
|
|
||||||
|
``arch/x86/include/asm/delay.h``::
|
||||||
|
|
||||||
|
#define ndelay(n) (__builtin_constant_p(n) ? \
|
||||||
|
((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
|
||||||
|
__ndelay(n))
|
||||||
|
|
||||||
|
|
||||||
|
``include/linux/fs.h``::
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Kernel pointers have redundant information, so we can use a
|
||||||
|
* scheme where we can return either an error code or a dentry
|
||||||
|
* pointer with the same return value.
|
||||||
|
*
|
||||||
|
* This should be a per-architecture thing, to allow different
|
||||||
|
* error and pointer decisions.
|
||||||
|
*/
|
||||||
|
#define ERR_PTR(err) ((void *)((long)(err)))
|
||||||
|
#define PTR_ERR(ptr) ((long)(ptr))
|
||||||
|
#define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
|
||||||
|
|
||||||
|
``arch/x86/include/asm/uaccess_32.h:``::
|
||||||
|
|
||||||
|
#define copy_to_user(to,from,n) \
|
||||||
|
(__builtin_constant_p(n) ? \
|
||||||
|
__constant_copy_to_user((to),(from),(n)) : \
|
||||||
|
__generic_copy_to_user((to),(from),(n)))
|
||||||
|
|
||||||
|
|
||||||
|
``arch/sparc/kernel/head.S:``::
|
||||||
|
|
||||||
|
/*
|
||||||
|
* Sun people can't spell worth damn. "compatability" indeed.
|
||||||
|
* At least we *know* we can't spell, and use a spell-checker.
|
||||||
|
*/
|
||||||
|
|
||||||
|
/* Uh, actually Linus it is I who cannot spell. Too much murky
|
||||||
|
* Sparc assembly will do this to ya.
|
||||||
|
*/
|
||||||
|
C_LABEL(cputypvar):
|
||||||
|
.asciz "compatibility"
|
||||||
|
|
||||||
|
/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
|
||||||
|
.align 4
|
||||||
|
C_LABEL(cputypvar_sun4m):
|
||||||
|
.asciz "compatible"
|
||||||
|
|
||||||
|
|
||||||
|
``arch/sparc/lib/checksum.S:``::
|
||||||
|
|
||||||
|
/* Sun, you just can't beat me, you just can't. Stop trying,
|
||||||
|
* give up. I'm serious, I am going to kick the living shit
|
||||||
|
* out of you, game over, lights out.
|
||||||
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
Thanks
|
||||||
|
======
|
||||||
|
|
||||||
|
Thanks to Andi Kleen for the idea, answering my questions, fixing my
|
||||||
|
mistakes, filling content, etc. Philipp Rumpf for more spelling and
|
||||||
|
clarity fixes, and some excellent non-obvious points. Werner Almesberger
|
||||||
|
for giving me a great summary of :c:func:`disable_irq()`, and Jes
|
||||||
|
Sorensen and Andrea Arcangeli added caveats. Michael Elizabeth Chastain
|
||||||
|
for checking and adding to the Configure section. Telsa Gwynne for
|
||||||
|
teaching me DocBook.
|
9
Documentation/kernel-hacking/index.rst
Normal file
9
Documentation/kernel-hacking/index.rst
Normal file
|
@ -0,0 +1,9 @@
|
||||||
|
=====================
|
||||||
|
Kernel Hacking Guides
|
||||||
|
=====================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
hacking
|
||||||
|
locking
|
1446
Documentation/kernel-hacking/locking.rst
Normal file
1446
Documentation/kernel-hacking/locking.rst
Normal file
File diff suppressed because it is too large
Load diff
201
Documentation/lsm.txt
Normal file
201
Documentation/lsm.txt
Normal file
|
@ -0,0 +1,201 @@
|
||||||
|
========================================================
|
||||||
|
Linux Security Modules: General Security Hooks for Linux
|
||||||
|
========================================================
|
||||||
|
|
||||||
|
:Author: Stephen Smalley
|
||||||
|
:Author: Timothy Fraser
|
||||||
|
:Author: Chris Vance
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The APIs described in this book are outdated.
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
In March 2001, the National Security Agency (NSA) gave a presentation
|
||||||
|
about Security-Enhanced Linux (SELinux) at the 2.5 Linux Kernel Summit.
|
||||||
|
SELinux is an implementation of flexible and fine-grained
|
||||||
|
nondiscretionary access controls in the Linux kernel, originally
|
||||||
|
implemented as its own particular kernel patch. Several other security
|
||||||
|
projects (e.g. RSBAC, Medusa) have also developed flexible access
|
||||||
|
control architectures for the Linux kernel, and various projects have
|
||||||
|
developed particular access control models for Linux (e.g. LIDS, DTE,
|
||||||
|
SubDomain). Each project has developed and maintained its own kernel
|
||||||
|
patch to support its security needs.
|
||||||
|
|
||||||
|
In response to the NSA presentation, Linus Torvalds made a set of
|
||||||
|
remarks that described a security framework he would be willing to
|
||||||
|
consider for inclusion in the mainstream Linux kernel. He described a
|
||||||
|
general framework that would provide a set of security hooks to control
|
||||||
|
operations on kernel objects and a set of opaque security fields in
|
||||||
|
kernel data structures for maintaining security attributes. This
|
||||||
|
framework could then be used by loadable kernel modules to implement any
|
||||||
|
desired model of security. Linus also suggested the possibility of
|
||||||
|
migrating the Linux capabilities code into such a module.
|
||||||
|
|
||||||
|
The Linux Security Modules (LSM) project was started by WireX to develop
|
||||||
|
such a framework. LSM is a joint development effort by several security
|
||||||
|
projects, including Immunix, SELinux, SGI and Janus, and several
|
||||||
|
individuals, including Greg Kroah-Hartman and James Morris, to develop a
|
||||||
|
Linux kernel patch that implements this framework. The patch is
|
||||||
|
currently tracking the 2.4 series and is targeted for integration into
|
||||||
|
the 2.5 development series. This technical report provides an overview
|
||||||
|
of the framework and the example capabilities security module provided
|
||||||
|
by the LSM kernel patch.
|
||||||
|
|
||||||
|
LSM Framework
|
||||||
|
=============
|
||||||
|
|
||||||
|
The LSM kernel patch provides a general kernel framework to support
|
||||||
|
security modules. In particular, the LSM framework is primarily focused
|
||||||
|
on supporting access control modules, although future development is
|
||||||
|
likely to address other security needs such as auditing. By itself, the
|
||||||
|
framework does not provide any additional security; it merely provides
|
||||||
|
the infrastructure to support security modules. The LSM kernel patch
|
||||||
|
also moves most of the capabilities logic into an optional security
|
||||||
|
module, with the system defaulting to the traditional superuser logic.
|
||||||
|
This capabilities module is discussed further in
|
||||||
|
`LSM Capabilities Module <#cap>`__.
|
||||||
|
|
||||||
|
The LSM kernel patch adds security fields to kernel data structures and
|
||||||
|
inserts calls to hook functions at critical points in the kernel code to
|
||||||
|
manage the security fields and to perform access control. It also adds
|
||||||
|
functions for registering and unregistering security modules, and adds a
|
||||||
|
general :c:func:`security()` system call to support new system calls
|
||||||
|
for security-aware applications.
|
||||||
|
|
||||||
|
The LSM security fields are simply ``void*`` pointers. For process and
|
||||||
|
program execution security information, security fields were added to
|
||||||
|
:c:type:`struct task_struct <task_struct>` and
|
||||||
|
:c:type:`struct linux_binprm <linux_binprm>`. For filesystem
|
||||||
|
security information, a security field was added to :c:type:`struct
|
||||||
|
super_block <super_block>`. For pipe, file, and socket security
|
||||||
|
information, security fields were added to :c:type:`struct inode
|
||||||
|
<inode>` and :c:type:`struct file <file>`. For packet and
|
||||||
|
network device security information, security fields were added to
|
||||||
|
:c:type:`struct sk_buff <sk_buff>` and :c:type:`struct
|
||||||
|
net_device <net_device>`. For System V IPC security information,
|
||||||
|
security fields were added to :c:type:`struct kern_ipc_perm
|
||||||
|
<kern_ipc_perm>` and :c:type:`struct msg_msg
|
||||||
|
<msg_msg>`; additionally, the definitions for :c:type:`struct
|
||||||
|
msg_msg <msg_msg>`, struct msg_queue, and struct shmid_kernel
|
||||||
|
were moved to header files (``include/linux/msg.h`` and
|
||||||
|
``include/linux/shm.h`` as appropriate) to allow the security modules to
|
||||||
|
use these definitions.
|
||||||
|
|
||||||
|
Each LSM hook is a function pointer in a global table, security_ops.
|
||||||
|
This table is a :c:type:`struct security_operations
|
||||||
|
<security_operations>` structure as defined by
|
||||||
|
``include/linux/security.h``. Detailed documentation for each hook is
|
||||||
|
included in this header file. At present, this structure consists of a
|
||||||
|
collection of substructures that group related hooks based on the kernel
|
||||||
|
object (e.g. task, inode, file, sk_buff, etc) as well as some top-level
|
||||||
|
hook function pointers for system operations. This structure is likely
|
||||||
|
to be flattened in the future for performance. The placement of the hook
|
||||||
|
calls in the kernel code is described by the "called:" lines in the
|
||||||
|
per-hook documentation in the header file. The hook calls can also be
|
||||||
|
easily found in the kernel code by looking for the string
|
||||||
|
"security_ops->".
|
||||||
|
|
||||||
|
Linus mentioned per-process security hooks in his original remarks as a
|
||||||
|
possible alternative to global security hooks. However, if LSM were to
|
||||||
|
start from the perspective of per-process hooks, then the base framework
|
||||||
|
would have to deal with how to handle operations that involve multiple
|
||||||
|
processes (e.g. kill), since each process might have its own hook for
|
||||||
|
controlling the operation. This would require a general mechanism for
|
||||||
|
composing hooks in the base framework. Additionally, LSM would still
|
||||||
|
need global hooks for operations that have no process context (e.g.
|
||||||
|
network input operations). Consequently, LSM provides global security
|
||||||
|
hooks, but a security module is free to implement per-process hooks
|
||||||
|
(where that makes sense) by storing a security_ops table in each
|
||||||
|
process' security field and then invoking these per-process hooks from
|
||||||
|
the global hooks. The problem of composition is thus deferred to the
|
||||||
|
module.
|
||||||
|
|
||||||
|
The global security_ops table is initialized to a set of hook functions
|
||||||
|
provided by a dummy security module that provides traditional superuser
|
||||||
|
logic. A :c:func:`register_security()` function (in
|
||||||
|
``security/security.c``) is provided to allow a security module to set
|
||||||
|
security_ops to refer to its own hook functions, and an
|
||||||
|
:c:func:`unregister_security()` function is provided to revert
|
||||||
|
security_ops to the dummy module hooks. This mechanism is used to set
|
||||||
|
the primary security module, which is responsible for making the final
|
||||||
|
decision for each hook.
|
||||||
|
|
||||||
|
LSM also provides a simple mechanism for stacking additional security
|
||||||
|
modules with the primary security module. It defines
|
||||||
|
:c:func:`register_security()` and
|
||||||
|
:c:func:`unregister_security()` hooks in the :c:type:`struct
|
||||||
|
security_operations <security_operations>` structure and
|
||||||
|
provides :c:func:`mod_reg_security()` and
|
||||||
|
:c:func:`mod_unreg_security()` functions that invoke these hooks
|
||||||
|
after performing some sanity checking. A security module can call these
|
||||||
|
functions in order to stack with other modules. However, the actual
|
||||||
|
details of how this stacking is handled are deferred to the module,
|
||||||
|
which can implement these hooks in any way it wishes (including always
|
||||||
|
returning an error if it does not wish to support stacking). In this
|
||||||
|
manner, LSM again defers the problem of composition to the module.
|
||||||
|
|
||||||
|
Although the LSM hooks are organized into substructures based on kernel
|
||||||
|
object, all of the hooks can be viewed as falling into two major
|
||||||
|
categories: hooks that are used to manage the security fields and hooks
|
||||||
|
that are used to perform access control. Examples of the first category
|
||||||
|
of hooks include the :c:func:`alloc_security()` and
|
||||||
|
:c:func:`free_security()` hooks defined for each kernel data
|
||||||
|
structure that has a security field. These hooks are used to allocate
|
||||||
|
and free security structures for kernel objects. The first category of
|
||||||
|
hooks also includes hooks that set information in the security field
|
||||||
|
after allocation, such as the :c:func:`post_lookup()` hook in
|
||||||
|
:c:type:`struct inode_security_ops <inode_security_ops>`.
|
||||||
|
This hook is used to set security information for inodes after
|
||||||
|
successful lookup operations. An example of the second category of hooks
|
||||||
|
is the :c:func:`permission()` hook in :c:type:`struct
|
||||||
|
inode_security_ops <inode_security_ops>`. This hook checks
|
||||||
|
permission when accessing an inode.
|
||||||
|
|
||||||
|
LSM Capabilities Module
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The LSM kernel patch moves most of the existing POSIX.1e capabilities
|
||||||
|
logic into an optional security module stored in the file
|
||||||
|
``security/capability.c``. This change allows users who do not want to
|
||||||
|
use capabilities to omit this code entirely from their kernel, instead
|
||||||
|
using the dummy module for traditional superuser logic or any other
|
||||||
|
module that they desire. This change also allows the developers of the
|
||||||
|
capabilities logic to maintain and enhance their code more freely,
|
||||||
|
without needing to integrate patches back into the base kernel.
|
||||||
|
|
||||||
|
In addition to moving the capabilities logic, the LSM kernel patch could
|
||||||
|
move the capability-related fields from the kernel data structures into
|
||||||
|
the new security fields managed by the security modules. However, at
|
||||||
|
present, the LSM kernel patch leaves the capability fields in the kernel
|
||||||
|
data structures. In his original remarks, Linus suggested that this
|
||||||
|
might be preferable so that other security modules can be easily stacked
|
||||||
|
with the capabilities module without needing to chain multiple security
|
||||||
|
structures on the security field. It also avoids imposing extra overhead
|
||||||
|
on the capabilities module to manage the security fields. However, the
|
||||||
|
LSM framework could certainly support such a move if it is determined to
|
||||||
|
be desirable, with only a few additional changes described below.
|
||||||
|
|
||||||
|
At present, the capabilities logic for computing process capabilities on
|
||||||
|
:c:func:`execve()` and :c:func:`set\*uid()`, checking
|
||||||
|
capabilities for a particular process, saving and checking capabilities
|
||||||
|
for netlink messages, and handling the :c:func:`capget()` and
|
||||||
|
:c:func:`capset()` system calls have been moved into the
|
||||||
|
capabilities module. There are still a few locations in the base kernel
|
||||||
|
where capability-related fields are directly examined or modified, but
|
||||||
|
the current version of the LSM patch does allow a security module to
|
||||||
|
completely replace the assignment and testing of capabilities. These few
|
||||||
|
locations would need to be changed if the capability-related fields were
|
||||||
|
moved into the security field. The following is a list of known
|
||||||
|
locations that still perform such direct examination or modification of
|
||||||
|
capability-related fields:
|
||||||
|
|
||||||
|
- ``fs/open.c``::c:func:`sys_access()`
|
||||||
|
|
||||||
|
- ``fs/lockd/host.c``::c:func:`nlm_bind_host()`
|
||||||
|
|
||||||
|
- ``fs/nfsd/auth.c``::c:func:`nfsd_setuser()`
|
||||||
|
|
||||||
|
- ``fs/proc/array.c``::c:func:`task_cap()`
|
|
@ -129,8 +129,8 @@ Selection targets and flags are documented in
|
||||||
|
|
||||||
.. _sel-const-adjust:
|
.. _sel-const-adjust:
|
||||||
|
|
||||||
.. figure:: constraints.*
|
.. kernel-figure:: constraints.svg
|
||||||
:alt: constraints.pdf / constraints.svg
|
:alt: constraints.svg
|
||||||
:align: center
|
:align: center
|
||||||
|
|
||||||
Size adjustments with constraint flags.
|
Size adjustments with constraint flags.
|
||||||
|
|
|
@ -498,11 +498,11 @@ And a couple of implicit varieties:
|
||||||
This means that ACQUIRE acts as a minimal "acquire" operation and
|
This means that ACQUIRE acts as a minimal "acquire" operation and
|
||||||
RELEASE acts as a minimal "release" operation.
|
RELEASE acts as a minimal "release" operation.
|
||||||
|
|
||||||
A subset of the atomic operations described in atomic_ops.txt have ACQUIRE
|
A subset of the atomic operations described in core-api/atomic_ops.rst have
|
||||||
and RELEASE variants in addition to fully-ordered and relaxed (no barrier
|
ACQUIRE and RELEASE variants in addition to fully-ordered and relaxed (no
|
||||||
semantics) definitions. For compound atomics performing both a load and a
|
barrier semantics) definitions. For compound atomics performing both a load
|
||||||
store, ACQUIRE semantics apply only to the load and RELEASE semantics apply
|
and a store, ACQUIRE semantics apply only to the load and RELEASE semantics
|
||||||
only to the store portion of the operation.
|
apply only to the store portion of the operation.
|
||||||
|
|
||||||
Memory barriers are only required where there's a possibility of interaction
|
Memory barriers are only required where there's a possibility of interaction
|
||||||
between two CPUs or between a CPU and a device. If it can be guaranteed that
|
between two CPUs or between a CPU and a device. If it can be guaranteed that
|
||||||
|
|
10
Documentation/networking/conf.py
Normal file
10
Documentation/networking/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = "Linux Networking Documentation"
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'networking.tex', project,
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
|
@ -143,7 +143,7 @@ the key will be discarded and recreated when the data it holds has expired.
|
||||||
dns_query() returns a copy of the value attached to the key, or an error if
|
dns_query() returns a copy of the value attached to the key, or an error if
|
||||||
that is indicated instead.
|
that is indicated instead.
|
||||||
|
|
||||||
See <file:Documentation/security/keys-request-key.txt> for further
|
See <file:Documentation/security/keys/request-key.rst> for further
|
||||||
information about request-key function.
|
information about request-key function.
|
||||||
|
|
||||||
|
|
||||||
|
|
18
Documentation/networking/index.rst
Normal file
18
Documentation/networking/index.rst
Normal file
|
@ -0,0 +1,18 @@
|
||||||
|
Linux Networking Documentation
|
||||||
|
==============================
|
||||||
|
|
||||||
|
Contents:
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
kapi
|
||||||
|
z8530book
|
||||||
|
|
||||||
|
.. only:: subproject
|
||||||
|
|
||||||
|
Indices
|
||||||
|
=======
|
||||||
|
|
||||||
|
* :ref:`genindex`
|
||||||
|
|
147
Documentation/networking/kapi.rst
Normal file
147
Documentation/networking/kapi.rst
Normal file
|
@ -0,0 +1,147 @@
|
||||||
|
=========================================
|
||||||
|
Linux Networking and Network Devices APIs
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
Linux Networking
|
||||||
|
================
|
||||||
|
|
||||||
|
Networking Base Types
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/net.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Socket Buffer Functions
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/skbuff.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/net/sock.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/socket.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/skbuff.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/sock.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/datagram.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/stream.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Socket Filter
|
||||||
|
-------------
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/filter.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Generic Network Statistics
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/uapi/linux/gen_stats.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/gen_stats.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/gen_estimator.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
SUN RPC subsystem
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/xdr.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/svc_xprt.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/xprt.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/sched.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/socklib.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/stats.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/rpc_pipe.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/rpcb_clnt.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sunrpc/clnt.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
WiMAX
|
||||||
|
-----
|
||||||
|
|
||||||
|
.. kernel-doc:: net/wimax/op-msg.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/wimax/op-reset.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/wimax/op-rfkill.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/wimax/stack.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/net/wimax.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/uapi/linux/wimax.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Network device support
|
||||||
|
======================
|
||||||
|
|
||||||
|
Driver Support
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. kernel-doc:: net/core/dev.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/ethernet/eth.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: net/sched/sch_generic.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/etherdevice.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: include/linux/netdevice.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
PHY Support
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/phy.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/phy.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/phy_device.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/phy_device.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/mdio_bus.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/phy/mdio_bus.c
|
||||||
|
:internal:
|
256
Documentation/networking/z8530book.rst
Normal file
256
Documentation/networking/z8530book.rst
Normal file
|
@ -0,0 +1,256 @@
|
||||||
|
=======================
|
||||||
|
Z8530 Programming Guide
|
||||||
|
=======================
|
||||||
|
|
||||||
|
:Author: Alan Cox
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
The Z85x30 family synchronous/asynchronous controller chips are used on
|
||||||
|
a large number of cheap network interface cards. The kernel provides a
|
||||||
|
core interface layer that is designed to make it easy to provide WAN
|
||||||
|
services using this chip.
|
||||||
|
|
||||||
|
The current driver only support synchronous operation. Merging the
|
||||||
|
asynchronous driver support into this code to allow any Z85x30 device to
|
||||||
|
be used as both a tty interface and as a synchronous controller is a
|
||||||
|
project for Linux post the 2.4 release
|
||||||
|
|
||||||
|
Driver Modes
|
||||||
|
============
|
||||||
|
|
||||||
|
The Z85230 driver layer can drive Z8530, Z85C30 and Z85230 devices in
|
||||||
|
three different modes. Each mode can be applied to an individual channel
|
||||||
|
on the chip (each chip has two channels).
|
||||||
|
|
||||||
|
The PIO synchronous mode supports the most common Z8530 wiring. Here the
|
||||||
|
chip is interface to the I/O and interrupt facilities of the host
|
||||||
|
machine but not to the DMA subsystem. When running PIO the Z8530 has
|
||||||
|
extremely tight timing requirements. Doing high speeds, even with a
|
||||||
|
Z85230 will be tricky. Typically you should expect to achieve at best
|
||||||
|
9600 baud with a Z8C530 and 64Kbits with a Z85230.
|
||||||
|
|
||||||
|
The DMA mode supports the chip when it is configured to use dual DMA
|
||||||
|
channels on an ISA bus. The better cards tend to support this mode of
|
||||||
|
operation for a single channel. With DMA running the Z85230 tops out
|
||||||
|
when it starts to hit ISA DMA constraints at about 512Kbits. It is worth
|
||||||
|
noting here that many PC machines hang or crash when the chip is driven
|
||||||
|
fast enough to hold the ISA bus solid.
|
||||||
|
|
||||||
|
Transmit DMA mode uses a single DMA channel. The DMA channel is used for
|
||||||
|
transmission as the transmit FIFO is smaller than the receive FIFO. it
|
||||||
|
gives better performance than pure PIO mode but is nowhere near as ideal
|
||||||
|
as pure DMA mode.
|
||||||
|
|
||||||
|
Using the Z85230 driver
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The Z85230 driver provides the back end interface to your board. To
|
||||||
|
configure a Z8530 interface you need to detect the board and to identify
|
||||||
|
its ports and interrupt resources. It is also your problem to verify the
|
||||||
|
resources are available.
|
||||||
|
|
||||||
|
Having identified the chip you need to fill in a struct z8530_dev,
|
||||||
|
which describes each chip. This object must exist until you finally
|
||||||
|
shutdown the board. Firstly zero the active field. This ensures nothing
|
||||||
|
goes off without you intending it. The irq field should be set to the
|
||||||
|
interrupt number of the chip. (Each chip has a single interrupt source
|
||||||
|
rather than each channel). You are responsible for allocating the
|
||||||
|
interrupt line. The interrupt handler should be set to
|
||||||
|
:c:func:`z8530_interrupt()`. The device id should be set to the
|
||||||
|
z8530_dev structure pointer. Whether the interrupt can be shared or not
|
||||||
|
is board dependent, and up to you to initialise.
|
||||||
|
|
||||||
|
The structure holds two channel structures. Initialise chanA.ctrlio and
|
||||||
|
chanA.dataio with the address of the control and data ports. You can or
|
||||||
|
this with Z8530_PORT_SLEEP to indicate your interface needs the 5uS
|
||||||
|
delay for chip settling done in software. The PORT_SLEEP option is
|
||||||
|
architecture specific. Other flags may become available on future
|
||||||
|
platforms, eg for MMIO. Initialise the chanA.irqs to &z8530_nop to
|
||||||
|
start the chip up as disabled and discarding interrupt events. This
|
||||||
|
ensures that stray interrupts will be mopped up and not hang the bus.
|
||||||
|
Set chanA.dev to point to the device structure itself. The private and
|
||||||
|
name field you may use as you wish. The private field is unused by the
|
||||||
|
Z85230 layer. The name is used for error reporting and it may thus make
|
||||||
|
sense to make it match the network name.
|
||||||
|
|
||||||
|
Repeat the same operation with the B channel if your chip has both
|
||||||
|
channels wired to something useful. This isn't always the case. If it is
|
||||||
|
not wired then the I/O values do not matter, but you must initialise
|
||||||
|
chanB.dev.
|
||||||
|
|
||||||
|
If your board has DMA facilities then initialise the txdma and rxdma
|
||||||
|
fields for the relevant channels. You must also allocate the ISA DMA
|
||||||
|
channels and do any necessary board level initialisation to configure
|
||||||
|
them. The low level driver will do the Z8530 and DMA controller
|
||||||
|
programming but not board specific magic.
|
||||||
|
|
||||||
|
Having initialised the device you can then call
|
||||||
|
:c:func:`z8530_init()`. This will probe the chip and reset it into
|
||||||
|
a known state. An identification sequence is then run to identify the
|
||||||
|
chip type. If the checks fail to pass the function returns a non zero
|
||||||
|
error code. Typically this indicates that the port given is not valid.
|
||||||
|
After this call the type field of the z8530_dev structure is
|
||||||
|
initialised to either Z8530, Z85C30 or Z85230 according to the chip
|
||||||
|
found.
|
||||||
|
|
||||||
|
Once you have called z8530_init you can also make use of the utility
|
||||||
|
function :c:func:`z8530_describe()`. This provides a consistent
|
||||||
|
reporting format for the Z8530 devices, and allows all the drivers to
|
||||||
|
provide consistent reporting.
|
||||||
|
|
||||||
|
Attaching Network Interfaces
|
||||||
|
============================
|
||||||
|
|
||||||
|
If you wish to use the network interface facilities of the driver, then
|
||||||
|
you need to attach a network device to each channel that is present and
|
||||||
|
in use. In addition to use the generic HDLC you need to follow some
|
||||||
|
additional plumbing rules. They may seem complex but a look at the
|
||||||
|
example hostess_sv11 driver should reassure you.
|
||||||
|
|
||||||
|
The network device used for each channel should be pointed to by the
|
||||||
|
netdevice field of each channel. The hdlc-> priv field of the network
|
||||||
|
device points to your private data - you will need to be able to find
|
||||||
|
your private data from this.
|
||||||
|
|
||||||
|
The way most drivers approach this particular problem is to create a
|
||||||
|
structure holding the Z8530 device definition and put that into the
|
||||||
|
private field of the network device. The network device fields of the
|
||||||
|
channels then point back to the network devices.
|
||||||
|
|
||||||
|
If you wish to use the generic HDLC then you need to register the HDLC
|
||||||
|
device.
|
||||||
|
|
||||||
|
Before you register your network device you will also need to provide
|
||||||
|
suitable handlers for most of the network device callbacks. See the
|
||||||
|
network device documentation for more details on this.
|
||||||
|
|
||||||
|
Configuring And Activating The Port
|
||||||
|
===================================
|
||||||
|
|
||||||
|
The Z85230 driver provides helper functions and tables to load the port
|
||||||
|
registers on the Z8530 chips. When programming the register settings for
|
||||||
|
a channel be aware that the documentation recommends initialisation
|
||||||
|
orders. Strange things happen when these are not followed.
|
||||||
|
|
||||||
|
:c:func:`z8530_channel_load()` takes an array of pairs of
|
||||||
|
initialisation values in an array of u8 type. The first value is the
|
||||||
|
Z8530 register number. Add 16 to indicate the alternate register bank on
|
||||||
|
the later chips. The array is terminated by a 255.
|
||||||
|
|
||||||
|
The driver provides a pair of public tables. The z8530_hdlc_kilostream
|
||||||
|
table is for the UK 'Kilostream' service and also happens to cover most
|
||||||
|
other end host configurations. The z8530_hdlc_kilostream_85230 table
|
||||||
|
is the same configuration using the enhancements of the 85230 chip. The
|
||||||
|
configuration loaded is standard NRZ encoded synchronous data with HDLC
|
||||||
|
bitstuffing. All of the timing is taken from the other end of the link.
|
||||||
|
|
||||||
|
When writing your own tables be aware that the driver internally tracks
|
||||||
|
register values. It may need to reload values. You should therefore be
|
||||||
|
sure to set registers 1-7, 9-11, 14 and 15 in all configurations. Where
|
||||||
|
the register settings depend on DMA selection the driver will update the
|
||||||
|
bits itself when you open or close. Loading a new table with the
|
||||||
|
interface open is not recommended.
|
||||||
|
|
||||||
|
There are three standard configurations supported by the core code. In
|
||||||
|
PIO mode the interface is programmed up to use interrupt driven PIO.
|
||||||
|
This places high demands on the host processor to avoid latency. The
|
||||||
|
driver is written to take account of latency issues but it cannot avoid
|
||||||
|
latencies caused by other drivers, notably IDE in PIO mode. Because the
|
||||||
|
drivers allocate buffers you must also prevent MTU changes while the
|
||||||
|
port is open.
|
||||||
|
|
||||||
|
Once the port is open it will call the rx_function of each channel
|
||||||
|
whenever a completed packet arrived. This is invoked from interrupt
|
||||||
|
context and passes you the channel and a network buffer (struct
|
||||||
|
sk_buff) holding the data. The data includes the CRC bytes so most
|
||||||
|
users will want to trim the last two bytes before processing the data.
|
||||||
|
This function is very timing critical. When you wish to simply discard
|
||||||
|
data the support code provides the function
|
||||||
|
:c:func:`z8530_null_rx()` to discard the data.
|
||||||
|
|
||||||
|
To active PIO mode sending and receiving the ``z8530_sync_open`` is called.
|
||||||
|
This expects to be passed the network device and the channel. Typically
|
||||||
|
this is called from your network device open callback. On a failure a
|
||||||
|
non zero error status is returned.
|
||||||
|
The :c:func:`z8530_sync_close()` function shuts down a PIO
|
||||||
|
channel. This must be done before the channel is opened again and before
|
||||||
|
the driver shuts down and unloads.
|
||||||
|
|
||||||
|
The ideal mode of operation is dual channel DMA mode. Here the kernel
|
||||||
|
driver will configure the board for DMA in both directions. The driver
|
||||||
|
also handles ISA DMA issues such as controller programming and the
|
||||||
|
memory range limit for you. This mode is activated by calling the
|
||||||
|
:c:func:`z8530_sync_dma_open()` function. On failure a non zero
|
||||||
|
error value is returned. Once this mode is activated it can be shut down
|
||||||
|
by calling the :c:func:`z8530_sync_dma_close()`. You must call
|
||||||
|
the close function matching the open mode you used.
|
||||||
|
|
||||||
|
The final supported mode uses a single DMA channel to drive the transmit
|
||||||
|
side. As the Z85C30 has a larger FIFO on the receive channel this tends
|
||||||
|
to increase the maximum speed a little. This is activated by calling the
|
||||||
|
``z8530_sync_txdma_open``. This returns a non zero error code on failure. The
|
||||||
|
:c:func:`z8530_sync_txdma_close()` function closes down the Z8530
|
||||||
|
interface from this mode.
|
||||||
|
|
||||||
|
Network Layer Functions
|
||||||
|
=======================
|
||||||
|
|
||||||
|
The Z8530 layer provides functions to queue packets for transmission.
|
||||||
|
The driver internally buffers the frame currently being transmitted and
|
||||||
|
one further frame (in order to keep back to back transmission running).
|
||||||
|
Any further buffering is up to the caller.
|
||||||
|
|
||||||
|
The function :c:func:`z8530_queue_xmit()` takes a network buffer
|
||||||
|
in sk_buff format and queues it for transmission. The caller must
|
||||||
|
provide the entire packet with the exception of the bitstuffing and CRC.
|
||||||
|
This is normally done by the caller via the generic HDLC interface
|
||||||
|
layer. It returns 0 if the buffer has been queued and non zero values
|
||||||
|
for queue full. If the function accepts the buffer it becomes property
|
||||||
|
of the Z8530 layer and the caller should not free it.
|
||||||
|
|
||||||
|
The function :c:func:`z8530_get_stats()` returns a pointer to an
|
||||||
|
internally maintained per interface statistics block. This provides most
|
||||||
|
of the interface code needed to implement the network layer get_stats
|
||||||
|
callback.
|
||||||
|
|
||||||
|
Porting The Z8530 Driver
|
||||||
|
========================
|
||||||
|
|
||||||
|
The Z8530 driver is written to be portable. In DMA mode it makes
|
||||||
|
assumptions about the use of ISA DMA. These are probably warranted in
|
||||||
|
most cases as the Z85230 in particular was designed to glue to PC type
|
||||||
|
machines. The PIO mode makes no real assumptions.
|
||||||
|
|
||||||
|
Should you need to retarget the Z8530 driver to another architecture the
|
||||||
|
only code that should need changing are the port I/O functions. At the
|
||||||
|
moment these assume PC I/O port accesses. This may not be appropriate
|
||||||
|
for all platforms. Replacing :c:func:`z8530_read_port()` and
|
||||||
|
``z8530_write_port`` is intended to be all that is required to port
|
||||||
|
this driver layer.
|
||||||
|
|
||||||
|
Known Bugs And Assumptions
|
||||||
|
==========================
|
||||||
|
|
||||||
|
Interrupt Locking
|
||||||
|
The locking in the driver is done via the global cli/sti lock. This
|
||||||
|
makes for relatively poor SMP performance. Switching this to use a
|
||||||
|
per device spin lock would probably materially improve performance.
|
||||||
|
|
||||||
|
Occasional Failures
|
||||||
|
We have reports of occasional failures when run for very long
|
||||||
|
periods of time and the driver starts to receive junk frames. At the
|
||||||
|
moment the cause of this is not clear.
|
||||||
|
|
||||||
|
Public Functions Provided
|
||||||
|
=========================
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/wan/z85230.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Internal Functions
|
||||||
|
==================
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/net/wan/z85230.c
|
||||||
|
:internal:
|
|
@ -116,12 +116,11 @@ DevFS has been obsoleted in favour of udev
|
||||||
|
|
||||||
Linux documentation for functions is transitioning to inline
|
Linux documentation for functions is transitioning to inline
|
||||||
documentation via specially-formatted comments near their
|
documentation via specially-formatted comments near their
|
||||||
definitions in the source. These comments can be combined with the
|
definitions in the source. These comments can be combined with ReST
|
||||||
SGML templates in the Documentation/DocBook directory to make DocBook
|
files the Documentation/ directory to make enriched documentation, which can
|
||||||
files, which can then be converted by DocBook stylesheets to PostScript,
|
then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
|
||||||
HTML, PDF files, and several other formats. In order to convert from
|
In order to convert from ReST format to a format of your choice, you'll need
|
||||||
DocBook format to a format of your choice, you'll need to install Jade as
|
Sphinx.
|
||||||
well as the desired DocBook stylesheets.
|
|
||||||
|
|
||||||
Util-linux
|
Util-linux
|
||||||
----------
|
----------
|
||||||
|
@ -323,12 +322,6 @@ PDF outputs, it is recommended to use version 1.4.6.
|
||||||
functionalities required for ``XeLaTex`` to work. For PDF output you'll also
|
functionalities required for ``XeLaTex`` to work. For PDF output you'll also
|
||||||
need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
|
need ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
|
||||||
|
|
||||||
Other tools
|
|
||||||
-----------
|
|
||||||
|
|
||||||
In order to produce documentation from DocBook, you'll also need ``xmlto``.
|
|
||||||
Please notice, however, that we're currently migrating all documents to use
|
|
||||||
``Sphinx``.
|
|
||||||
|
|
||||||
Getting updated software
|
Getting updated software
|
||||||
========================
|
========================
|
||||||
|
@ -409,15 +402,6 @@ Quota-tools
|
||||||
|
|
||||||
- <http://sourceforge.net/projects/linuxquota/>
|
- <http://sourceforge.net/projects/linuxquota/>
|
||||||
|
|
||||||
DocBook Stylesheets
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/>
|
|
||||||
|
|
||||||
XMLTO XSLT Frontend
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
- <http://cyberelk.net/tim/xmlto/>
|
|
||||||
|
|
||||||
Intel P6 microcode
|
Intel P6 microcode
|
||||||
------------------
|
------------------
|
||||||
|
|
|
@ -980,8 +980,8 @@ do so, though, and doing so unnecessarily can limit optimization.
|
||||||
|
|
||||||
When writing a single inline assembly statement containing multiple
|
When writing a single inline assembly statement containing multiple
|
||||||
instructions, put each instruction on a separate line in a separate quoted
|
instructions, put each instruction on a separate line in a separate quoted
|
||||||
string, and end each string except the last with \n\t to properly indent the
|
string, and end each string except the last with ``\n\t`` to properly indent
|
||||||
next instruction in the assembly output:
|
the next instruction in the assembly output:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
|
|
@ -167,6 +167,11 @@ Lotus Notes (GUI)
|
||||||
|
|
||||||
Run away from it.
|
Run away from it.
|
||||||
|
|
||||||
|
IBM Verse (Web GUI)
|
||||||
|
*******************
|
||||||
|
|
||||||
|
See Lotus Notes.
|
||||||
|
|
||||||
Mutt (TUI)
|
Mutt (TUI)
|
||||||
**********
|
**********
|
||||||
|
|
||||||
|
|
|
@ -180,14 +180,6 @@ They can also be generated on LaTeX and ePub formats with::
|
||||||
make latexdocs
|
make latexdocs
|
||||||
make epubdocs
|
make epubdocs
|
||||||
|
|
||||||
Currently, there are some documents written on DocBook that are in
|
|
||||||
the process of conversion to ReST. Such documents will be created in the
|
|
||||||
Documentation/DocBook/ directory and can be generated also as
|
|
||||||
Postscript or man pages by running::
|
|
||||||
|
|
||||||
make psdocs
|
|
||||||
make mandocs
|
|
||||||
|
|
||||||
Becoming A Kernel Developer
|
Becoming A Kernel Developer
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
|
|
|
@ -40,50 +40,18 @@ Enjoy!
|
||||||
Docs at the Linux Kernel tree
|
Docs at the Linux Kernel tree
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
|
||||||
The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``.
|
|
||||||
The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
|
The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
|
||||||
|
|
||||||
* Name: **linux/Documentation**
|
* Name: **linux/Documentation**
|
||||||
|
|
||||||
:Author: Many.
|
:Author: Many.
|
||||||
:Location: Documentation/
|
:Location: Documentation/
|
||||||
:Keywords: text files, Sphinx, DocBook.
|
:Keywords: text files, Sphinx.
|
||||||
:Description: Documentation that comes with the kernel sources,
|
:Description: Documentation that comes with the kernel sources,
|
||||||
inside the Documentation directory. Some pages from this document
|
inside the Documentation directory. Some pages from this document
|
||||||
(including this document itself) have been moved there, and might
|
(including this document itself) have been moved there, and might
|
||||||
be more up to date than the web version.
|
be more up to date than the web version.
|
||||||
|
|
||||||
* Title: **The Kernel Hacking HOWTO**
|
|
||||||
|
|
||||||
:Author: Various Talented People, and Rusty.
|
|
||||||
:Location: Documentation/DocBook/kernel-hacking.tmpl
|
|
||||||
:Keywords: HOWTO, kernel contexts, deadlock, locking, modules,
|
|
||||||
symbols, return conventions.
|
|
||||||
:Description: From the Introduction: "Please understand that I
|
|
||||||
never wanted to write this document, being grossly underqualified,
|
|
||||||
but I always wanted to read it, and this was the only way. I
|
|
||||||
simply explain some best practices, and give reading entry-points
|
|
||||||
into the kernel sources. I avoid implementation details: that's
|
|
||||||
what the code is for, and I ignore whole tracts of useful
|
|
||||||
routines. This document assumes familiarity with C, and an
|
|
||||||
understanding of what the kernel is, and how it is used. It was
|
|
||||||
originally written for the 2.3 kernels, but nearly all of it
|
|
||||||
applies to 2.2 too; 2.0 is slightly different".
|
|
||||||
|
|
||||||
* Title: **Linux Kernel Locking HOWTO**
|
|
||||||
|
|
||||||
:Author: Various Talented People, and Rusty.
|
|
||||||
:Location: Documentation/DocBook/kernel-locking.tmpl
|
|
||||||
:Keywords: locks, locking, spinlock, semaphore, atomic, race
|
|
||||||
condition, bottom halves, tasklets, softirqs.
|
|
||||||
:Description: The title says it all: document describing the
|
|
||||||
locking system in the Linux Kernel either in uniprocessor or SMP
|
|
||||||
systems.
|
|
||||||
:Notes: "It was originally written for the later (>2.3.47) 2.3
|
|
||||||
kernels, but most of it applies to 2.2 too; 2.0 is slightly
|
|
||||||
different". Freely redistributable under the conditions of the GNU
|
|
||||||
General Public License.
|
|
||||||
|
|
||||||
On-line docs
|
On-line docs
|
||||||
------------
|
------------
|
||||||
|
|
||||||
|
|
|
@ -1,26 +0,0 @@
|
||||||
00-INDEX
|
|
||||||
- this file.
|
|
||||||
LSM.txt
|
|
||||||
- description of the Linux Security Module framework.
|
|
||||||
SELinux.txt
|
|
||||||
- how to get started with the SELinux security enhancement.
|
|
||||||
Smack.txt
|
|
||||||
- documentation on the Smack Linux Security Module.
|
|
||||||
Yama.txt
|
|
||||||
- documentation on the Yama Linux Security Module.
|
|
||||||
apparmor.txt
|
|
||||||
- documentation on the AppArmor security extension.
|
|
||||||
credentials.txt
|
|
||||||
- documentation about credentials in Linux.
|
|
||||||
keys-ecryptfs.txt
|
|
||||||
- description of the encryption keys for the ecryptfs filesystem.
|
|
||||||
keys-request-key.txt
|
|
||||||
- description of the kernel key request service.
|
|
||||||
keys-trusted-encrypted.txt
|
|
||||||
- info on the Trusted and Encrypted keys in the kernel key ring service.
|
|
||||||
keys.txt
|
|
||||||
- description of the kernel key retention service.
|
|
||||||
tomoyo.txt
|
|
||||||
- documentation on the TOMOYO Linux Security Module.
|
|
||||||
IMA-templates.txt
|
|
||||||
- documentation on the template management mechanism for IMA.
|
|
|
@ -1,9 +1,12 @@
|
||||||
IMA Template Management Mechanism
|
=================================
|
||||||
|
IMA Template Management Mechanism
|
||||||
|
=================================
|
||||||
|
|
||||||
|
|
||||||
==== INTRODUCTION ====
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
The original 'ima' template is fixed length, containing the filedata hash
|
The original ``ima`` template is fixed length, containing the filedata hash
|
||||||
and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
|
and pathname. The filedata hash is limited to 20 bytes (md5/sha1).
|
||||||
The pathname is a null terminated string, limited to 255 characters.
|
The pathname is a null terminated string, limited to 255 characters.
|
||||||
To overcome these limitations and to add additional file metadata, it is
|
To overcome these limitations and to add additional file metadata, it is
|
||||||
|
@ -28,61 +31,64 @@ a new data type, developers define the field identifier and implement
|
||||||
two functions, init() and show(), respectively to generate and display
|
two functions, init() and show(), respectively to generate and display
|
||||||
measurement entries. Defining a new template descriptor requires
|
measurement entries. Defining a new template descriptor requires
|
||||||
specifying the template format (a string of field identifiers separated
|
specifying the template format (a string of field identifiers separated
|
||||||
by the '|' character) through the 'ima_template_fmt' kernel command line
|
by the ``|`` character) through the ``ima_template_fmt`` kernel command line
|
||||||
parameter. At boot time, IMA initializes the chosen template descriptor
|
parameter. At boot time, IMA initializes the chosen template descriptor
|
||||||
by translating the format into an array of template fields structures taken
|
by translating the format into an array of template fields structures taken
|
||||||
from the set of the supported ones.
|
from the set of the supported ones.
|
||||||
|
|
||||||
After the initialization step, IMA will call ima_alloc_init_template()
|
After the initialization step, IMA will call ``ima_alloc_init_template()``
|
||||||
(new function defined within the patches for the new template management
|
(new function defined within the patches for the new template management
|
||||||
mechanism) to generate a new measurement entry by using the template
|
mechanism) to generate a new measurement entry by using the template
|
||||||
descriptor chosen through the kernel configuration or through the newly
|
descriptor chosen through the kernel configuration or through the newly
|
||||||
introduced 'ima_template' and 'ima_template_fmt' kernel command line parameters.
|
introduced ``ima_template`` and ``ima_template_fmt`` kernel command line parameters.
|
||||||
It is during this phase that the advantages of the new architecture are
|
It is during this phase that the advantages of the new architecture are
|
||||||
clearly shown: the latter function will not contain specific code to handle
|
clearly shown: the latter function will not contain specific code to handle
|
||||||
a given template but, instead, it simply calls the init() method of the template
|
a given template but, instead, it simply calls the ``init()`` method of the template
|
||||||
fields associated to the chosen template descriptor and store the result
|
fields associated to the chosen template descriptor and store the result
|
||||||
(pointer to allocated data and data length) in the measurement entry structure.
|
(pointer to allocated data and data length) in the measurement entry structure.
|
||||||
|
|
||||||
The same mechanism is employed to display measurements entries.
|
The same mechanism is employed to display measurements entries.
|
||||||
The functions ima[_ascii]_measurements_show() retrieve, for each entry,
|
The functions ``ima[_ascii]_measurements_show()`` retrieve, for each entry,
|
||||||
the template descriptor used to produce that entry and call the show()
|
the template descriptor used to produce that entry and call the show()
|
||||||
method for each item of the array of template fields structures.
|
method for each item of the array of template fields structures.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
==== SUPPORTED TEMPLATE FIELDS AND DESCRIPTORS ====
|
Supported Template Fields and Descriptors
|
||||||
|
=========================================
|
||||||
|
|
||||||
In the following, there is the list of supported template fields
|
In the following, there is the list of supported template fields
|
||||||
('<identifier>': description), that can be used to define new template
|
``('<identifier>': description)``, that can be used to define new template
|
||||||
descriptors by adding their identifier to the format string
|
descriptors by adding their identifier to the format string
|
||||||
(support for more data types will be added later):
|
(support for more data types will be added later):
|
||||||
|
|
||||||
- 'd': the digest of the event (i.e. the digest of a measured file),
|
- 'd': the digest of the event (i.e. the digest of a measured file),
|
||||||
calculated with the SHA1 or MD5 hash algorithm;
|
calculated with the SHA1 or MD5 hash algorithm;
|
||||||
- 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
|
- 'n': the name of the event (i.e. the file name), with size up to 255 bytes;
|
||||||
- 'd-ng': the digest of the event, calculated with an arbitrary hash
|
- 'd-ng': the digest of the event, calculated with an arbitrary hash
|
||||||
algorithm (field format: [<hash algo>:]digest, where the digest
|
algorithm (field format: [<hash algo>:]digest, where the digest
|
||||||
prefix is shown only if the hash algorithm is not SHA1 or MD5);
|
prefix is shown only if the hash algorithm is not SHA1 or MD5);
|
||||||
- 'n-ng': the name of the event, without size limitations;
|
- 'n-ng': the name of the event, without size limitations;
|
||||||
- 'sig': the file signature.
|
- 'sig': the file signature.
|
||||||
|
|
||||||
|
|
||||||
Below, there is the list of defined template descriptors:
|
Below, there is the list of defined template descriptors:
|
||||||
- "ima": its format is 'd|n';
|
|
||||||
- "ima-ng" (default): its format is 'd-ng|n-ng';
|
- "ima": its format is ``d|n``;
|
||||||
- "ima-sig": its format is 'd-ng|n-ng|sig'.
|
- "ima-ng" (default): its format is ``d-ng|n-ng``;
|
||||||
|
- "ima-sig": its format is ``d-ng|n-ng|sig``.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
==== USE ====
|
Use
|
||||||
|
===
|
||||||
|
|
||||||
To specify the template descriptor to be used to generate measurement entries,
|
To specify the template descriptor to be used to generate measurement entries,
|
||||||
currently the following methods are supported:
|
currently the following methods are supported:
|
||||||
|
|
||||||
- select a template descriptor among those supported in the kernel
|
- select a template descriptor among those supported in the kernel
|
||||||
configuration ('ima-ng' is the default choice);
|
configuration (``ima-ng`` is the default choice);
|
||||||
- specify a template descriptor name from the kernel command line through
|
- specify a template descriptor name from the kernel command line through
|
||||||
the 'ima_template=' parameter;
|
the ``ima_template=`` parameter;
|
||||||
- register a new template descriptor with custom format through the kernel
|
- register a new template descriptor with custom format through the kernel
|
||||||
command line parameter 'ima_template_fmt='.
|
command line parameter ``ima_template_fmt=``.
|
14
Documentation/security/LSM.rst
Normal file
14
Documentation/security/LSM.rst
Normal file
|
@ -0,0 +1,14 @@
|
||||||
|
=================================
|
||||||
|
Linux Security Module Development
|
||||||
|
=================================
|
||||||
|
|
||||||
|
Based on https://lkml.org/lkml/2007/10/26/215,
|
||||||
|
a new LSM is accepted into the kernel when its intent (a description of
|
||||||
|
what it tries to protect against and in what cases one would expect to
|
||||||
|
use it) has been appropriately documented in ``Documentation/security/LSM``.
|
||||||
|
This allows an LSM's code to be easily compared to its goals, and so
|
||||||
|
that end users and distros can make a more informed decision about which
|
||||||
|
LSMs suit their requirements.
|
||||||
|
|
||||||
|
For extensive documentation on the available LSM hook interfaces, please
|
||||||
|
see ``include/linux/lsm_hooks.h``.
|
|
@ -1,8 +0,0 @@
|
||||||
project = "The kernel security subsystem manual"
|
|
||||||
|
|
||||||
tags.add("subproject")
|
|
||||||
|
|
||||||
latex_documents = [
|
|
||||||
('index', 'security.tex', project,
|
|
||||||
'The kernel development community', 'manual'),
|
|
||||||
]
|
|
|
@ -1,38 +1,18 @@
|
||||||
====================
|
====================
|
||||||
CREDENTIALS IN LINUX
|
Credentials in Linux
|
||||||
====================
|
====================
|
||||||
|
|
||||||
By: David Howells <dhowells@redhat.com>
|
By: David Howells <dhowells@redhat.com>
|
||||||
|
|
||||||
Contents:
|
.. contents:: :local:
|
||||||
|
|
||||||
(*) Overview.
|
Overview
|
||||||
|
|
||||||
(*) Types of credentials.
|
|
||||||
|
|
||||||
(*) File markings.
|
|
||||||
|
|
||||||
(*) Task credentials.
|
|
||||||
|
|
||||||
- Immutable credentials.
|
|
||||||
- Accessing task credentials.
|
|
||||||
- Accessing another task's credentials.
|
|
||||||
- Altering credentials.
|
|
||||||
- Managing credentials.
|
|
||||||
|
|
||||||
(*) Open file credentials.
|
|
||||||
|
|
||||||
(*) Overriding the VFS's use of credentials.
|
|
||||||
|
|
||||||
|
|
||||||
========
|
|
||||||
OVERVIEW
|
|
||||||
========
|
========
|
||||||
|
|
||||||
There are several parts to the security check performed by Linux when one
|
There are several parts to the security check performed by Linux when one
|
||||||
object acts upon another:
|
object acts upon another:
|
||||||
|
|
||||||
(1) Objects.
|
1. Objects.
|
||||||
|
|
||||||
Objects are things in the system that may be acted upon directly by
|
Objects are things in the system that may be acted upon directly by
|
||||||
userspace programs. Linux has a variety of actionable objects, including:
|
userspace programs. Linux has a variety of actionable objects, including:
|
||||||
|
@ -48,7 +28,7 @@ object acts upon another:
|
||||||
As a part of the description of all these objects there is a set of
|
As a part of the description of all these objects there is a set of
|
||||||
credentials. What's in the set depends on the type of object.
|
credentials. What's in the set depends on the type of object.
|
||||||
|
|
||||||
(2) Object ownership.
|
2. Object ownership.
|
||||||
|
|
||||||
Amongst the credentials of most objects, there will be a subset that
|
Amongst the credentials of most objects, there will be a subset that
|
||||||
indicates the ownership of that object. This is used for resource
|
indicates the ownership of that object. This is used for resource
|
||||||
|
@ -57,7 +37,7 @@ object acts upon another:
|
||||||
In a standard UNIX filesystem, for instance, this will be defined by the
|
In a standard UNIX filesystem, for instance, this will be defined by the
|
||||||
UID marked on the inode.
|
UID marked on the inode.
|
||||||
|
|
||||||
(3) The objective context.
|
3. The objective context.
|
||||||
|
|
||||||
Also amongst the credentials of those objects, there will be a subset that
|
Also amongst the credentials of those objects, there will be a subset that
|
||||||
indicates the 'objective context' of that object. This may or may not be
|
indicates the 'objective context' of that object. This may or may not be
|
||||||
|
@ -67,7 +47,7 @@ object acts upon another:
|
||||||
The objective context is used as part of the security calculation that is
|
The objective context is used as part of the security calculation that is
|
||||||
carried out when an object is acted upon.
|
carried out when an object is acted upon.
|
||||||
|
|
||||||
(4) Subjects.
|
4. Subjects.
|
||||||
|
|
||||||
A subject is an object that is acting upon another object.
|
A subject is an object that is acting upon another object.
|
||||||
|
|
||||||
|
@ -77,10 +57,10 @@ object acts upon another:
|
||||||
|
|
||||||
Objects other than tasks may under some circumstances also be subjects.
|
Objects other than tasks may under some circumstances also be subjects.
|
||||||
For instance an open file may send SIGIO to a task using the UID and EUID
|
For instance an open file may send SIGIO to a task using the UID and EUID
|
||||||
given to it by a task that called fcntl(F_SETOWN) upon it. In this case,
|
given to it by a task that called ``fcntl(F_SETOWN)`` upon it. In this case,
|
||||||
the file struct will have a subjective context too.
|
the file struct will have a subjective context too.
|
||||||
|
|
||||||
(5) The subjective context.
|
5. The subjective context.
|
||||||
|
|
||||||
A subject has an additional interpretation of its credentials. A subset
|
A subject has an additional interpretation of its credentials. A subset
|
||||||
of its credentials forms the 'subjective context'. The subjective context
|
of its credentials forms the 'subjective context'. The subjective context
|
||||||
|
@ -92,7 +72,7 @@ object acts upon another:
|
||||||
from the real UID and GID that normally form the objective context of the
|
from the real UID and GID that normally form the objective context of the
|
||||||
task.
|
task.
|
||||||
|
|
||||||
(6) Actions.
|
6. Actions.
|
||||||
|
|
||||||
Linux has a number of actions available that a subject may perform upon an
|
Linux has a number of actions available that a subject may perform upon an
|
||||||
object. The set of actions available depends on the nature of the subject
|
object. The set of actions available depends on the nature of the subject
|
||||||
|
@ -101,7 +81,7 @@ object acts upon another:
|
||||||
Actions include reading, writing, creating and deleting files; forking or
|
Actions include reading, writing, creating and deleting files; forking or
|
||||||
signalling and tracing tasks.
|
signalling and tracing tasks.
|
||||||
|
|
||||||
(7) Rules, access control lists and security calculations.
|
7. Rules, access control lists and security calculations.
|
||||||
|
|
||||||
When a subject acts upon an object, a security calculation is made. This
|
When a subject acts upon an object, a security calculation is made. This
|
||||||
involves taking the subjective context, the objective context and the
|
involves taking the subjective context, the objective context and the
|
||||||
|
@ -111,7 +91,7 @@ object acts upon another:
|
||||||
|
|
||||||
There are two main sources of rules:
|
There are two main sources of rules:
|
||||||
|
|
||||||
(a) Discretionary access control (DAC):
|
a. Discretionary access control (DAC):
|
||||||
|
|
||||||
Sometimes the object will include sets of rules as part of its
|
Sometimes the object will include sets of rules as part of its
|
||||||
description. This is an 'Access Control List' or 'ACL'. A Linux
|
description. This is an 'Access Control List' or 'ACL'. A Linux
|
||||||
|
@ -127,7 +107,7 @@ object acts upon another:
|
||||||
A Linux file might also sport a POSIX ACL. This is a list of rules
|
A Linux file might also sport a POSIX ACL. This is a list of rules
|
||||||
that grants various permissions to arbitrary subjects.
|
that grants various permissions to arbitrary subjects.
|
||||||
|
|
||||||
(b) Mandatory access control (MAC):
|
b. Mandatory access control (MAC):
|
||||||
|
|
||||||
The system as a whole may have one or more sets of rules that get
|
The system as a whole may have one or more sets of rules that get
|
||||||
applied to all subjects and objects, regardless of their source.
|
applied to all subjects and objects, regardless of their source.
|
||||||
|
@ -139,65 +119,65 @@ object acts upon another:
|
||||||
that says that this action is either granted or denied.
|
that says that this action is either granted or denied.
|
||||||
|
|
||||||
|
|
||||||
====================
|
Types of Credentials
|
||||||
TYPES OF CREDENTIALS
|
|
||||||
====================
|
====================
|
||||||
|
|
||||||
The Linux kernel supports the following types of credentials:
|
The Linux kernel supports the following types of credentials:
|
||||||
|
|
||||||
(1) Traditional UNIX credentials.
|
1. Traditional UNIX credentials.
|
||||||
|
|
||||||
Real User ID
|
- Real User ID
|
||||||
Real Group ID
|
- Real Group ID
|
||||||
|
|
||||||
The UID and GID are carried by most, if not all, Linux objects, even if in
|
The UID and GID are carried by most, if not all, Linux objects, even if in
|
||||||
some cases it has to be invented (FAT or CIFS files for example, which are
|
some cases it has to be invented (FAT or CIFS files for example, which are
|
||||||
derived from Windows). These (mostly) define the objective context of
|
derived from Windows). These (mostly) define the objective context of
|
||||||
that object, with tasks being slightly different in some cases.
|
that object, with tasks being slightly different in some cases.
|
||||||
|
|
||||||
Effective, Saved and FS User ID
|
- Effective, Saved and FS User ID
|
||||||
Effective, Saved and FS Group ID
|
- Effective, Saved and FS Group ID
|
||||||
Supplementary groups
|
- Supplementary groups
|
||||||
|
|
||||||
These are additional credentials used by tasks only. Usually, an
|
These are additional credentials used by tasks only. Usually, an
|
||||||
EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID
|
EUID/EGID/GROUPS will be used as the subjective context, and real UID/GID
|
||||||
will be used as the objective. For tasks, it should be noted that this is
|
will be used as the objective. For tasks, it should be noted that this is
|
||||||
not always true.
|
not always true.
|
||||||
|
|
||||||
(2) Capabilities.
|
2. Capabilities.
|
||||||
|
|
||||||
Set of permitted capabilities
|
- Set of permitted capabilities
|
||||||
Set of inheritable capabilities
|
- Set of inheritable capabilities
|
||||||
Set of effective capabilities
|
- Set of effective capabilities
|
||||||
Capability bounding set
|
- Capability bounding set
|
||||||
|
|
||||||
These are only carried by tasks. They indicate superior capabilities
|
These are only carried by tasks. They indicate superior capabilities
|
||||||
granted piecemeal to a task that an ordinary task wouldn't otherwise have.
|
granted piecemeal to a task that an ordinary task wouldn't otherwise have.
|
||||||
These are manipulated implicitly by changes to the traditional UNIX
|
These are manipulated implicitly by changes to the traditional UNIX
|
||||||
credentials, but can also be manipulated directly by the capset() system
|
credentials, but can also be manipulated directly by the ``capset()``
|
||||||
call.
|
system call.
|
||||||
|
|
||||||
The permitted capabilities are those caps that the process might grant
|
The permitted capabilities are those caps that the process might grant
|
||||||
itself to its effective or permitted sets through capset(). This
|
itself to its effective or permitted sets through ``capset()``. This
|
||||||
inheritable set might also be so constrained.
|
inheritable set might also be so constrained.
|
||||||
|
|
||||||
The effective capabilities are the ones that a task is actually allowed to
|
The effective capabilities are the ones that a task is actually allowed to
|
||||||
make use of itself.
|
make use of itself.
|
||||||
|
|
||||||
The inheritable capabilities are the ones that may get passed across
|
The inheritable capabilities are the ones that may get passed across
|
||||||
execve().
|
``execve()``.
|
||||||
|
|
||||||
The bounding set limits the capabilities that may be inherited across
|
The bounding set limits the capabilities that may be inherited across
|
||||||
execve(), especially when a binary is executed that will execute as UID 0.
|
``execve()``, especially when a binary is executed that will execute as
|
||||||
|
UID 0.
|
||||||
|
|
||||||
(3) Secure management flags (securebits).
|
3. Secure management flags (securebits).
|
||||||
|
|
||||||
These are only carried by tasks. These govern the way the above
|
These are only carried by tasks. These govern the way the above
|
||||||
credentials are manipulated and inherited over certain operations such as
|
credentials are manipulated and inherited over certain operations such as
|
||||||
execve(). They aren't used directly as objective or subjective
|
execve(). They aren't used directly as objective or subjective
|
||||||
credentials.
|
credentials.
|
||||||
|
|
||||||
(4) Keys and keyrings.
|
4. Keys and keyrings.
|
||||||
|
|
||||||
These are only carried by tasks. They carry and cache security tokens
|
These are only carried by tasks. They carry and cache security tokens
|
||||||
that don't fit into the other standard UNIX credentials. They are for
|
that don't fit into the other standard UNIX credentials. They are for
|
||||||
|
@ -218,7 +198,7 @@ The Linux kernel supports the following types of credentials:
|
||||||
|
|
||||||
For more information on using keys, see Documentation/security/keys.txt.
|
For more information on using keys, see Documentation/security/keys.txt.
|
||||||
|
|
||||||
(5) LSM
|
5. LSM
|
||||||
|
|
||||||
The Linux Security Module allows extra controls to be placed over the
|
The Linux Security Module allows extra controls to be placed over the
|
||||||
operations that a task may do. Currently Linux supports several LSM
|
operations that a task may do. Currently Linux supports several LSM
|
||||||
|
@ -228,7 +208,7 @@ The Linux kernel supports the following types of credentials:
|
||||||
rules (policies) that say what operations a task with one label may do to
|
rules (policies) that say what operations a task with one label may do to
|
||||||
an object with another label.
|
an object with another label.
|
||||||
|
|
||||||
(6) AF_KEY
|
6. AF_KEY
|
||||||
|
|
||||||
This is a socket-based approach to credential management for networking
|
This is a socket-based approach to credential management for networking
|
||||||
stacks [RFC 2367]. It isn't discussed by this document as it doesn't
|
stacks [RFC 2367]. It isn't discussed by this document as it doesn't
|
||||||
|
@ -244,25 +224,19 @@ network filesystem where the credentials of the opened file should be presented
|
||||||
to the server, regardless of who is actually doing a read or a write upon it.
|
to the server, regardless of who is actually doing a read or a write upon it.
|
||||||
|
|
||||||
|
|
||||||
=============
|
File Markings
|
||||||
FILE MARKINGS
|
|
||||||
=============
|
=============
|
||||||
|
|
||||||
Files on disk or obtained over the network may have annotations that form the
|
Files on disk or obtained over the network may have annotations that form the
|
||||||
objective security context of that file. Depending on the type of filesystem,
|
objective security context of that file. Depending on the type of filesystem,
|
||||||
this may include one or more of the following:
|
this may include one or more of the following:
|
||||||
|
|
||||||
(*) UNIX UID, GID, mode;
|
* UNIX UID, GID, mode;
|
||||||
|
* Windows user ID;
|
||||||
(*) Windows user ID;
|
* Access control list;
|
||||||
|
* LSM security label;
|
||||||
(*) Access control list;
|
* UNIX exec privilege escalation bits (SUID/SGID);
|
||||||
|
* File capabilities exec privilege escalation bits.
|
||||||
(*) LSM security label;
|
|
||||||
|
|
||||||
(*) UNIX exec privilege escalation bits (SUID/SGID);
|
|
||||||
|
|
||||||
(*) File capabilities exec privilege escalation bits.
|
|
||||||
|
|
||||||
These are compared to the task's subjective security context, and certain
|
These are compared to the task's subjective security context, and certain
|
||||||
operations allowed or disallowed as a result. In the case of execve(), the
|
operations allowed or disallowed as a result. In the case of execve(), the
|
||||||
|
@ -270,8 +244,7 @@ privilege escalation bits come into play, and may allow the resulting process
|
||||||
extra privileges, based on the annotations on the executable file.
|
extra privileges, based on the annotations on the executable file.
|
||||||
|
|
||||||
|
|
||||||
================
|
Task Credentials
|
||||||
TASK CREDENTIALS
|
|
||||||
================
|
================
|
||||||
|
|
||||||
In Linux, all of a task's credentials are held in (uid, gid) or through
|
In Linux, all of a task's credentials are held in (uid, gid) or through
|
||||||
|
@ -282,20 +255,20 @@ task_struct.
|
||||||
Once a set of credentials has been prepared and committed, it may not be
|
Once a set of credentials has been prepared and committed, it may not be
|
||||||
changed, barring the following exceptions:
|
changed, barring the following exceptions:
|
||||||
|
|
||||||
(1) its reference count may be changed;
|
1. its reference count may be changed;
|
||||||
|
|
||||||
(2) the reference count on the group_info struct it points to may be changed;
|
2. the reference count on the group_info struct it points to may be changed;
|
||||||
|
|
||||||
(3) the reference count on the security data it points to may be changed;
|
3. the reference count on the security data it points to may be changed;
|
||||||
|
|
||||||
(4) the reference count on any keyrings it points to may be changed;
|
4. the reference count on any keyrings it points to may be changed;
|
||||||
|
|
||||||
(5) any keyrings it points to may be revoked, expired or have their security
|
5. any keyrings it points to may be revoked, expired or have their security
|
||||||
attributes changed; and
|
attributes changed; and
|
||||||
|
|
||||||
(6) the contents of any keyrings to which it points may be changed (the whole
|
6. the contents of any keyrings to which it points may be changed (the whole
|
||||||
point of keyrings being a shared set of credentials, modifiable by anyone
|
point of keyrings being a shared set of credentials, modifiable by anyone
|
||||||
with appropriate access).
|
with appropriate access).
|
||||||
|
|
||||||
To alter anything in the cred struct, the copy-and-replace principle must be
|
To alter anything in the cred struct, the copy-and-replace principle must be
|
||||||
adhered to. First take a copy, then alter the copy and then use RCU to change
|
adhered to. First take a copy, then alter the copy and then use RCU to change
|
||||||
|
@ -303,37 +276,37 @@ the task pointer to make it point to the new copy. There are wrappers to aid
|
||||||
with this (see below).
|
with this (see below).
|
||||||
|
|
||||||
A task may only alter its _own_ credentials; it is no longer permitted for a
|
A task may only alter its _own_ credentials; it is no longer permitted for a
|
||||||
task to alter another's credentials. This means the capset() system call is no
|
task to alter another's credentials. This means the ``capset()`` system call
|
||||||
longer permitted to take any PID other than the one of the current process.
|
is no longer permitted to take any PID other than the one of the current
|
||||||
Also keyctl_instantiate() and keyctl_negate() functions no longer permit
|
process. Also ``keyctl_instantiate()`` and ``keyctl_negate()`` functions no
|
||||||
attachment to process-specific keyrings in the requesting process as the
|
longer permit attachment to process-specific keyrings in the requesting
|
||||||
instantiating process may need to create them.
|
process as the instantiating process may need to create them.
|
||||||
|
|
||||||
|
|
||||||
IMMUTABLE CREDENTIALS
|
Immutable Credentials
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
Once a set of credentials has been made public (by calling commit_creds() for
|
Once a set of credentials has been made public (by calling ``commit_creds()``
|
||||||
example), it must be considered immutable, barring two exceptions:
|
for example), it must be considered immutable, barring two exceptions:
|
||||||
|
|
||||||
(1) The reference count may be altered.
|
1. The reference count may be altered.
|
||||||
|
|
||||||
(2) Whilst the keyring subscriptions of a set of credentials may not be
|
2. Whilst the keyring subscriptions of a set of credentials may not be
|
||||||
changed, the keyrings subscribed to may have their contents altered.
|
changed, the keyrings subscribed to may have their contents altered.
|
||||||
|
|
||||||
To catch accidental credential alteration at compile time, struct task_struct
|
To catch accidental credential alteration at compile time, struct task_struct
|
||||||
has _const_ pointers to its credential sets, as does struct file. Furthermore,
|
has _const_ pointers to its credential sets, as does struct file. Furthermore,
|
||||||
certain functions such as get_cred() and put_cred() operate on const pointers,
|
certain functions such as ``get_cred()`` and ``put_cred()`` operate on const
|
||||||
thus rendering casts unnecessary, but require to temporarily ditch the const
|
pointers, thus rendering casts unnecessary, but require to temporarily ditch
|
||||||
qualification to be able to alter the reference count.
|
the const qualification to be able to alter the reference count.
|
||||||
|
|
||||||
|
|
||||||
ACCESSING TASK CREDENTIALS
|
Accessing Task Credentials
|
||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
A task being able to alter only its own credentials permits the current process
|
A task being able to alter only its own credentials permits the current process
|
||||||
to read or replace its own credentials without the need for any form of locking
|
to read or replace its own credentials without the need for any form of locking
|
||||||
- which simplifies things greatly. It can just call:
|
-- which simplifies things greatly. It can just call::
|
||||||
|
|
||||||
const struct cred *current_cred()
|
const struct cred *current_cred()
|
||||||
|
|
||||||
|
@ -341,7 +314,7 @@ to get a pointer to its credentials structure, and it doesn't have to release
|
||||||
it afterwards.
|
it afterwards.
|
||||||
|
|
||||||
There are convenience wrappers for retrieving specific aspects of a task's
|
There are convenience wrappers for retrieving specific aspects of a task's
|
||||||
credentials (the value is simply returned in each case):
|
credentials (the value is simply returned in each case)::
|
||||||
|
|
||||||
uid_t current_uid(void) Current's real UID
|
uid_t current_uid(void) Current's real UID
|
||||||
gid_t current_gid(void) Current's real GID
|
gid_t current_gid(void) Current's real GID
|
||||||
|
@ -354,7 +327,7 @@ credentials (the value is simply returned in each case):
|
||||||
struct user_struct *current_user(void) Current's user account
|
struct user_struct *current_user(void) Current's user account
|
||||||
|
|
||||||
There are also convenience wrappers for retrieving specific associated pairs of
|
There are also convenience wrappers for retrieving specific associated pairs of
|
||||||
a task's credentials:
|
a task's credentials::
|
||||||
|
|
||||||
void current_uid_gid(uid_t *, gid_t *);
|
void current_uid_gid(uid_t *, gid_t *);
|
||||||
void current_euid_egid(uid_t *, gid_t *);
|
void current_euid_egid(uid_t *, gid_t *);
|
||||||
|
@ -365,12 +338,12 @@ them from the current task's credentials.
|
||||||
|
|
||||||
|
|
||||||
In addition, there is a function for obtaining a reference on the current
|
In addition, there is a function for obtaining a reference on the current
|
||||||
process's current set of credentials:
|
process's current set of credentials::
|
||||||
|
|
||||||
const struct cred *get_current_cred(void);
|
const struct cred *get_current_cred(void);
|
||||||
|
|
||||||
and functions for getting references to one of the credentials that don't
|
and functions for getting references to one of the credentials that don't
|
||||||
actually live in struct cred:
|
actually live in struct cred::
|
||||||
|
|
||||||
struct user_struct *get_current_user(void);
|
struct user_struct *get_current_user(void);
|
||||||
struct group_info *get_current_groups(void);
|
struct group_info *get_current_groups(void);
|
||||||
|
@ -378,22 +351,22 @@ actually live in struct cred:
|
||||||
which get references to the current process's user accounting structure and
|
which get references to the current process's user accounting structure and
|
||||||
supplementary groups list respectively.
|
supplementary groups list respectively.
|
||||||
|
|
||||||
Once a reference has been obtained, it must be released with put_cred(),
|
Once a reference has been obtained, it must be released with ``put_cred()``,
|
||||||
free_uid() or put_group_info() as appropriate.
|
``free_uid()`` or ``put_group_info()`` as appropriate.
|
||||||
|
|
||||||
|
|
||||||
ACCESSING ANOTHER TASK'S CREDENTIALS
|
Accessing Another Task's Credentials
|
||||||
------------------------------------
|
------------------------------------
|
||||||
|
|
||||||
Whilst a task may access its own credentials without the need for locking, the
|
Whilst a task may access its own credentials without the need for locking, the
|
||||||
same is not true of a task wanting to access another task's credentials. It
|
same is not true of a task wanting to access another task's credentials. It
|
||||||
must use the RCU read lock and rcu_dereference().
|
must use the RCU read lock and ``rcu_dereference()``.
|
||||||
|
|
||||||
The rcu_dereference() is wrapped by:
|
The ``rcu_dereference()`` is wrapped by::
|
||||||
|
|
||||||
const struct cred *__task_cred(struct task_struct *task);
|
const struct cred *__task_cred(struct task_struct *task);
|
||||||
|
|
||||||
This should be used inside the RCU read lock, as in the following example:
|
This should be used inside the RCU read lock, as in the following example::
|
||||||
|
|
||||||
void foo(struct task_struct *t, struct foo_data *f)
|
void foo(struct task_struct *t, struct foo_data *f)
|
||||||
{
|
{
|
||||||
|
@ -410,39 +383,40 @@ This should be used inside the RCU read lock, as in the following example:
|
||||||
|
|
||||||
Should it be necessary to hold another task's credentials for a long period of
|
Should it be necessary to hold another task's credentials for a long period of
|
||||||
time, and possibly to sleep whilst doing so, then the caller should get a
|
time, and possibly to sleep whilst doing so, then the caller should get a
|
||||||
reference on them using:
|
reference on them using::
|
||||||
|
|
||||||
const struct cred *get_task_cred(struct task_struct *task);
|
const struct cred *get_task_cred(struct task_struct *task);
|
||||||
|
|
||||||
This does all the RCU magic inside of it. The caller must call put_cred() on
|
This does all the RCU magic inside of it. The caller must call put_cred() on
|
||||||
the credentials so obtained when they're finished with.
|
the credentials so obtained when they're finished with.
|
||||||
|
|
||||||
[*] Note: The result of __task_cred() should not be passed directly to
|
.. note::
|
||||||
get_cred() as this may race with commit_cred().
|
The result of ``__task_cred()`` should not be passed directly to
|
||||||
|
``get_cred()`` as this may race with ``commit_cred()``.
|
||||||
|
|
||||||
There are a couple of convenience functions to access bits of another task's
|
There are a couple of convenience functions to access bits of another task's
|
||||||
credentials, hiding the RCU magic from the caller:
|
credentials, hiding the RCU magic from the caller::
|
||||||
|
|
||||||
uid_t task_uid(task) Task's real UID
|
uid_t task_uid(task) Task's real UID
|
||||||
uid_t task_euid(task) Task's effective UID
|
uid_t task_euid(task) Task's effective UID
|
||||||
|
|
||||||
If the caller is holding the RCU read lock at the time anyway, then:
|
If the caller is holding the RCU read lock at the time anyway, then::
|
||||||
|
|
||||||
__task_cred(task)->uid
|
__task_cred(task)->uid
|
||||||
__task_cred(task)->euid
|
__task_cred(task)->euid
|
||||||
|
|
||||||
should be used instead. Similarly, if multiple aspects of a task's credentials
|
should be used instead. Similarly, if multiple aspects of a task's credentials
|
||||||
need to be accessed, RCU read lock should be used, __task_cred() called, the
|
need to be accessed, RCU read lock should be used, ``__task_cred()`` called,
|
||||||
result stored in a temporary pointer and then the credential aspects called
|
the result stored in a temporary pointer and then the credential aspects called
|
||||||
from that before dropping the lock. This prevents the potentially expensive
|
from that before dropping the lock. This prevents the potentially expensive
|
||||||
RCU magic from being invoked multiple times.
|
RCU magic from being invoked multiple times.
|
||||||
|
|
||||||
Should some other single aspect of another task's credentials need to be
|
Should some other single aspect of another task's credentials need to be
|
||||||
accessed, then this can be used:
|
accessed, then this can be used::
|
||||||
|
|
||||||
task_cred_xxx(task, member)
|
task_cred_xxx(task, member)
|
||||||
|
|
||||||
where 'member' is a non-pointer member of the cred struct. For instance:
|
where 'member' is a non-pointer member of the cred struct. For instance::
|
||||||
|
|
||||||
uid_t task_cred_xxx(task, suid);
|
uid_t task_cred_xxx(task, suid);
|
||||||
|
|
||||||
|
@ -451,7 +425,7 @@ magic. This may not be used for pointer members as what they point to may
|
||||||
disappear the moment the RCU read lock is dropped.
|
disappear the moment the RCU read lock is dropped.
|
||||||
|
|
||||||
|
|
||||||
ALTERING CREDENTIALS
|
Altering Credentials
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
As previously mentioned, a task may only alter its own credentials, and may not
|
As previously mentioned, a task may only alter its own credentials, and may not
|
||||||
|
@ -459,7 +433,7 @@ alter those of another task. This means that it doesn't need to use any
|
||||||
locking to alter its own credentials.
|
locking to alter its own credentials.
|
||||||
|
|
||||||
To alter the current process's credentials, a function should first prepare a
|
To alter the current process's credentials, a function should first prepare a
|
||||||
new set of credentials by calling:
|
new set of credentials by calling::
|
||||||
|
|
||||||
struct cred *prepare_creds(void);
|
struct cred *prepare_creds(void);
|
||||||
|
|
||||||
|
@ -467,9 +441,10 @@ this locks current->cred_replace_mutex and then allocates and constructs a
|
||||||
duplicate of the current process's credentials, returning with the mutex still
|
duplicate of the current process's credentials, returning with the mutex still
|
||||||
held if successful. It returns NULL if not successful (out of memory).
|
held if successful. It returns NULL if not successful (out of memory).
|
||||||
|
|
||||||
The mutex prevents ptrace() from altering the ptrace state of a process whilst
|
The mutex prevents ``ptrace()`` from altering the ptrace state of a process
|
||||||
security checks on credentials construction and changing is taking place as
|
whilst security checks on credentials construction and changing is taking place
|
||||||
the ptrace state may alter the outcome, particularly in the case of execve().
|
as the ptrace state may alter the outcome, particularly in the case of
|
||||||
|
``execve()``.
|
||||||
|
|
||||||
The new credentials set should be altered appropriately, and any security
|
The new credentials set should be altered appropriately, and any security
|
||||||
checks and hooks done. Both the current and the proposed sets of credentials
|
checks and hooks done. Both the current and the proposed sets of credentials
|
||||||
|
@ -478,36 +453,37 @@ still at this point.
|
||||||
|
|
||||||
|
|
||||||
When the credential set is ready, it should be committed to the current process
|
When the credential set is ready, it should be committed to the current process
|
||||||
by calling:
|
by calling::
|
||||||
|
|
||||||
int commit_creds(struct cred *new);
|
int commit_creds(struct cred *new);
|
||||||
|
|
||||||
This will alter various aspects of the credentials and the process, giving the
|
This will alter various aspects of the credentials and the process, giving the
|
||||||
LSM a chance to do likewise, then it will use rcu_assign_pointer() to actually
|
LSM a chance to do likewise, then it will use ``rcu_assign_pointer()`` to
|
||||||
commit the new credentials to current->cred, it will release
|
actually commit the new credentials to ``current->cred``, it will release
|
||||||
current->cred_replace_mutex to allow ptrace() to take place, and it will notify
|
``current->cred_replace_mutex`` to allow ``ptrace()`` to take place, and it
|
||||||
the scheduler and others of the changes.
|
will notify the scheduler and others of the changes.
|
||||||
|
|
||||||
This function is guaranteed to return 0, so that it can be tail-called at the
|
This function is guaranteed to return 0, so that it can be tail-called at the
|
||||||
end of such functions as sys_setresuid().
|
end of such functions as ``sys_setresuid()``.
|
||||||
|
|
||||||
Note that this function consumes the caller's reference to the new credentials.
|
Note that this function consumes the caller's reference to the new credentials.
|
||||||
The caller should _not_ call put_cred() on the new credentials afterwards.
|
The caller should _not_ call ``put_cred()`` on the new credentials afterwards.
|
||||||
|
|
||||||
Furthermore, once this function has been called on a new set of credentials,
|
Furthermore, once this function has been called on a new set of credentials,
|
||||||
those credentials may _not_ be changed further.
|
those credentials may _not_ be changed further.
|
||||||
|
|
||||||
|
|
||||||
Should the security checks fail or some other error occur after prepare_creds()
|
Should the security checks fail or some other error occur after
|
||||||
has been called, then the following function should be invoked:
|
``prepare_creds()`` has been called, then the following function should be
|
||||||
|
invoked::
|
||||||
|
|
||||||
void abort_creds(struct cred *new);
|
void abort_creds(struct cred *new);
|
||||||
|
|
||||||
This releases the lock on current->cred_replace_mutex that prepare_creds() got
|
This releases the lock on ``current->cred_replace_mutex`` that
|
||||||
and then releases the new credentials.
|
``prepare_creds()`` got and then releases the new credentials.
|
||||||
|
|
||||||
|
|
||||||
A typical credentials alteration function would look something like this:
|
A typical credentials alteration function would look something like this::
|
||||||
|
|
||||||
int alter_suid(uid_t suid)
|
int alter_suid(uid_t suid)
|
||||||
{
|
{
|
||||||
|
@ -529,53 +505,50 @@ A typical credentials alteration function would look something like this:
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
MANAGING CREDENTIALS
|
Managing Credentials
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
There are some functions to help manage credentials:
|
There are some functions to help manage credentials:
|
||||||
|
|
||||||
(*) void put_cred(const struct cred *cred);
|
- ``void put_cred(const struct cred *cred);``
|
||||||
|
|
||||||
This releases a reference to the given set of credentials. If the
|
This releases a reference to the given set of credentials. If the
|
||||||
reference count reaches zero, the credentials will be scheduled for
|
reference count reaches zero, the credentials will be scheduled for
|
||||||
destruction by the RCU system.
|
destruction by the RCU system.
|
||||||
|
|
||||||
(*) const struct cred *get_cred(const struct cred *cred);
|
- ``const struct cred *get_cred(const struct cred *cred);``
|
||||||
|
|
||||||
This gets a reference on a live set of credentials, returning a pointer to
|
This gets a reference on a live set of credentials, returning a pointer to
|
||||||
that set of credentials.
|
that set of credentials.
|
||||||
|
|
||||||
(*) struct cred *get_new_cred(struct cred *cred);
|
- ``struct cred *get_new_cred(struct cred *cred);``
|
||||||
|
|
||||||
This gets a reference on a set of credentials that is under construction
|
This gets a reference on a set of credentials that is under construction
|
||||||
and is thus still mutable, returning a pointer to that set of credentials.
|
and is thus still mutable, returning a pointer to that set of credentials.
|
||||||
|
|
||||||
|
|
||||||
=====================
|
Open File Credentials
|
||||||
OPEN FILE CREDENTIALS
|
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
When a new file is opened, a reference is obtained on the opening task's
|
When a new file is opened, a reference is obtained on the opening task's
|
||||||
credentials and this is attached to the file struct as 'f_cred' in place of
|
credentials and this is attached to the file struct as ``f_cred`` in place of
|
||||||
'f_uid' and 'f_gid'. Code that used to access file->f_uid and file->f_gid
|
``f_uid`` and ``f_gid``. Code that used to access ``file->f_uid`` and
|
||||||
should now access file->f_cred->fsuid and file->f_cred->fsgid.
|
``file->f_gid`` should now access ``file->f_cred->fsuid`` and
|
||||||
|
``file->f_cred->fsgid``.
|
||||||
|
|
||||||
It is safe to access f_cred without the use of RCU or locking because the
|
It is safe to access ``f_cred`` without the use of RCU or locking because the
|
||||||
pointer will not change over the lifetime of the file struct, and nor will the
|
pointer will not change over the lifetime of the file struct, and nor will the
|
||||||
contents of the cred struct pointed to, barring the exceptions listed above
|
contents of the cred struct pointed to, barring the exceptions listed above
|
||||||
(see the Task Credentials section).
|
(see the Task Credentials section).
|
||||||
|
|
||||||
|
|
||||||
=======================================
|
Overriding the VFS's Use of Credentials
|
||||||
OVERRIDING THE VFS'S USE OF CREDENTIALS
|
|
||||||
=======================================
|
=======================================
|
||||||
|
|
||||||
Under some circumstances it is desirable to override the credentials used by
|
Under some circumstances it is desirable to override the credentials used by
|
||||||
the VFS, and that can be done by calling into such as vfs_mkdir() with a
|
the VFS, and that can be done by calling into such as ``vfs_mkdir()`` with a
|
||||||
different set of credentials. This is done in the following places:
|
different set of credentials. This is done in the following places:
|
||||||
|
|
||||||
(*) sys_faccessat().
|
* ``sys_faccessat()``.
|
||||||
|
* ``do_coredump()``.
|
||||||
(*) do_coredump().
|
* nfs4recover.c.
|
||||||
|
|
||||||
(*) nfs4recover.c.
|
|
|
@ -1,7 +1,13 @@
|
||||||
======================
|
======================
|
||||||
Security documentation
|
Security Documentation
|
||||||
======================
|
======================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
credentials
|
||||||
|
IMA-templates
|
||||||
|
keys/index
|
||||||
|
LSM
|
||||||
|
self-protection
|
||||||
tpm/index
|
tpm/index
|
||||||
|
|
File diff suppressed because it is too large
Load diff
|
@ -1,4 +1,6 @@
|
||||||
Encrypted keys for the eCryptfs filesystem
|
==========================================
|
||||||
|
Encrypted keys for the eCryptfs filesystem
|
||||||
|
==========================================
|
||||||
|
|
||||||
ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
|
ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
|
||||||
file using a randomly generated File Encryption Key (FEK).
|
file using a randomly generated File Encryption Key (FEK).
|
||||||
|
@ -35,20 +37,23 @@ controlled environment. Another advantage is that the key is not exposed to
|
||||||
threats of malicious software, because it is available in clear form only at
|
threats of malicious software, because it is available in clear form only at
|
||||||
kernel level.
|
kernel level.
|
||||||
|
|
||||||
Usage:
|
Usage::
|
||||||
|
|
||||||
keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
|
keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
|
||||||
keyctl add encrypted name "load hex_blob" ring
|
keyctl add encrypted name "load hex_blob" ring
|
||||||
keyctl update keyid "update key-type:master-key-name"
|
keyctl update keyid "update key-type:master-key-name"
|
||||||
|
|
||||||
name:= '<16 hexadecimal characters>'
|
Where::
|
||||||
key-type:= 'trusted' | 'user'
|
|
||||||
keylen:= 64
|
name:= '<16 hexadecimal characters>'
|
||||||
|
key-type:= 'trusted' | 'user'
|
||||||
|
keylen:= 64
|
||||||
|
|
||||||
|
|
||||||
Example of encrypted key usage with the eCryptfs filesystem:
|
Example of encrypted key usage with the eCryptfs filesystem:
|
||||||
|
|
||||||
Create an encrypted key "1000100010001000" of length 64 bytes with format
|
Create an encrypted key "1000100010001000" of length 64 bytes with format
|
||||||
'ecryptfs' and save it using a previously loaded user key "test":
|
'ecryptfs' and save it using a previously loaded user key "test"::
|
||||||
|
|
||||||
$ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
|
$ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
|
||||||
19184530
|
19184530
|
||||||
|
@ -62,7 +67,7 @@ Create an encrypted key "1000100010001000" of length 64 bytes with format
|
||||||
$ keyctl pipe 19184530 > ecryptfs.blob
|
$ keyctl pipe 19184530 > ecryptfs.blob
|
||||||
|
|
||||||
Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
|
Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
|
||||||
into the '/secret' directory:
|
into the '/secret' directory::
|
||||||
|
|
||||||
$ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
|
$ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
|
||||||
ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
|
ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
|
11
Documentation/security/keys/index.rst
Normal file
11
Documentation/security/keys/index.rst
Normal file
|
@ -0,0 +1,11 @@
|
||||||
|
===========
|
||||||
|
Kernel Keys
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
core
|
||||||
|
ecryptfs
|
||||||
|
request-key
|
||||||
|
trusted-encrypted
|
|
@ -1,19 +1,19 @@
|
||||||
===================
|
===================
|
||||||
KEY REQUEST SERVICE
|
Key Request Service
|
||||||
===================
|
===================
|
||||||
|
|
||||||
The key request service is part of the key retention service (refer to
|
The key request service is part of the key retention service (refer to
|
||||||
Documentation/security/keys.txt). This document explains more fully how
|
Documentation/security/keys.txt). This document explains more fully how
|
||||||
the requesting algorithm works.
|
the requesting algorithm works.
|
||||||
|
|
||||||
The process starts by either the kernel requesting a service by calling
|
The process starts by either the kernel requesting a service by calling
|
||||||
request_key*():
|
``request_key*()``::
|
||||||
|
|
||||||
struct key *request_key(const struct key_type *type,
|
struct key *request_key(const struct key_type *type,
|
||||||
const char *description,
|
const char *description,
|
||||||
const char *callout_info);
|
const char *callout_info);
|
||||||
|
|
||||||
or:
|
or::
|
||||||
|
|
||||||
struct key *request_key_with_auxdata(const struct key_type *type,
|
struct key *request_key_with_auxdata(const struct key_type *type,
|
||||||
const char *description,
|
const char *description,
|
||||||
|
@ -21,14 +21,14 @@ or:
|
||||||
size_t callout_len,
|
size_t callout_len,
|
||||||
void *aux);
|
void *aux);
|
||||||
|
|
||||||
or:
|
or::
|
||||||
|
|
||||||
struct key *request_key_async(const struct key_type *type,
|
struct key *request_key_async(const struct key_type *type,
|
||||||
const char *description,
|
const char *description,
|
||||||
const char *callout_info,
|
const char *callout_info,
|
||||||
size_t callout_len);
|
size_t callout_len);
|
||||||
|
|
||||||
or:
|
or::
|
||||||
|
|
||||||
struct key *request_key_async_with_auxdata(const struct key_type *type,
|
struct key *request_key_async_with_auxdata(const struct key_type *type,
|
||||||
const char *description,
|
const char *description,
|
||||||
|
@ -36,7 +36,7 @@ or:
|
||||||
size_t callout_len,
|
size_t callout_len,
|
||||||
void *aux);
|
void *aux);
|
||||||
|
|
||||||
Or by userspace invoking the request_key system call:
|
Or by userspace invoking the request_key system call::
|
||||||
|
|
||||||
key_serial_t request_key(const char *type,
|
key_serial_t request_key(const char *type,
|
||||||
const char *description,
|
const char *description,
|
||||||
|
@ -67,38 +67,37 @@ own upcall mechanisms. If they do, then those should be substituted for the
|
||||||
forking and execution of /sbin/request-key.
|
forking and execution of /sbin/request-key.
|
||||||
|
|
||||||
|
|
||||||
===========
|
The Process
|
||||||
THE PROCESS
|
|
||||||
===========
|
===========
|
||||||
|
|
||||||
A request proceeds in the following manner:
|
A request proceeds in the following manner:
|
||||||
|
|
||||||
(1) Process A calls request_key() [the userspace syscall calls the kernel
|
1) Process A calls request_key() [the userspace syscall calls the kernel
|
||||||
interface].
|
interface].
|
||||||
|
|
||||||
(2) request_key() searches the process's subscribed keyrings to see if there's
|
2) request_key() searches the process's subscribed keyrings to see if there's
|
||||||
a suitable key there. If there is, it returns the key. If there isn't,
|
a suitable key there. If there is, it returns the key. If there isn't,
|
||||||
and callout_info is not set, an error is returned. Otherwise the process
|
and callout_info is not set, an error is returned. Otherwise the process
|
||||||
proceeds to the next step.
|
proceeds to the next step.
|
||||||
|
|
||||||
(3) request_key() sees that A doesn't have the desired key yet, so it creates
|
3) request_key() sees that A doesn't have the desired key yet, so it creates
|
||||||
two things:
|
two things:
|
||||||
|
|
||||||
(a) An uninstantiated key U of requested type and description.
|
a) An uninstantiated key U of requested type and description.
|
||||||
|
|
||||||
(b) An authorisation key V that refers to key U and notes that process A
|
b) An authorisation key V that refers to key U and notes that process A
|
||||||
is the context in which key U should be instantiated and secured, and
|
is the context in which key U should be instantiated and secured, and
|
||||||
from which associated key requests may be satisfied.
|
from which associated key requests may be satisfied.
|
||||||
|
|
||||||
(4) request_key() then forks and executes /sbin/request-key with a new session
|
4) request_key() then forks and executes /sbin/request-key with a new session
|
||||||
keyring that contains a link to auth key V.
|
keyring that contains a link to auth key V.
|
||||||
|
|
||||||
(5) /sbin/request-key assumes the authority associated with key U.
|
5) /sbin/request-key assumes the authority associated with key U.
|
||||||
|
|
||||||
(6) /sbin/request-key execs an appropriate program to perform the actual
|
6) /sbin/request-key execs an appropriate program to perform the actual
|
||||||
instantiation.
|
instantiation.
|
||||||
|
|
||||||
(7) The program may want to access another key from A's context (say a
|
7) The program may want to access another key from A's context (say a
|
||||||
Kerberos TGT key). It just requests the appropriate key, and the keyring
|
Kerberos TGT key). It just requests the appropriate key, and the keyring
|
||||||
search notes that the session keyring has auth key V in its bottom level.
|
search notes that the session keyring has auth key V in its bottom level.
|
||||||
|
|
||||||
|
@ -106,15 +105,15 @@ A request proceeds in the following manner:
|
||||||
UID, GID, groups and security info of process A as if it was process A,
|
UID, GID, groups and security info of process A as if it was process A,
|
||||||
and come up with key W.
|
and come up with key W.
|
||||||
|
|
||||||
(8) The program then does what it must to get the data with which to
|
8) The program then does what it must to get the data with which to
|
||||||
instantiate key U, using key W as a reference (perhaps it contacts a
|
instantiate key U, using key W as a reference (perhaps it contacts a
|
||||||
Kerberos server using the TGT) and then instantiates key U.
|
Kerberos server using the TGT) and then instantiates key U.
|
||||||
|
|
||||||
(9) Upon instantiating key U, auth key V is automatically revoked so that it
|
9) Upon instantiating key U, auth key V is automatically revoked so that it
|
||||||
may not be used again.
|
may not be used again.
|
||||||
|
|
||||||
(10) The program then exits 0 and request_key() deletes key V and returns key
|
10) The program then exits 0 and request_key() deletes key V and returns key
|
||||||
U to the caller.
|
U to the caller.
|
||||||
|
|
||||||
This also extends further. If key W (step 7 above) didn't exist, key W would
|
This also extends further. If key W (step 7 above) didn't exist, key W would
|
||||||
be created uninstantiated, another auth key (X) would be created (as per step
|
be created uninstantiated, another auth key (X) would be created (as per step
|
||||||
|
@ -127,8 +126,7 @@ This is because process A's keyrings can't simply be attached to
|
||||||
of them, and (b) it requires the same UID/GID/Groups all the way through.
|
of them, and (b) it requires the same UID/GID/Groups all the way through.
|
||||||
|
|
||||||
|
|
||||||
====================================
|
Negative Instantiation And Rejection
|
||||||
NEGATIVE INSTANTIATION AND REJECTION
|
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
Rather than instantiating a key, it is possible for the possessor of an
|
Rather than instantiating a key, it is possible for the possessor of an
|
||||||
|
@ -145,23 +143,22 @@ signal, the key under construction will be automatically negatively
|
||||||
instantiated for a short amount of time.
|
instantiated for a short amount of time.
|
||||||
|
|
||||||
|
|
||||||
====================
|
The Search Algorithm
|
||||||
THE SEARCH ALGORITHM
|
|
||||||
====================
|
====================
|
||||||
|
|
||||||
A search of any particular keyring proceeds in the following fashion:
|
A search of any particular keyring proceeds in the following fashion:
|
||||||
|
|
||||||
(1) When the key management code searches for a key (keyring_search_aux) it
|
1) When the key management code searches for a key (keyring_search_aux) it
|
||||||
firstly calls key_permission(SEARCH) on the keyring it's starting with,
|
firstly calls key_permission(SEARCH) on the keyring it's starting with,
|
||||||
if this denies permission, it doesn't search further.
|
if this denies permission, it doesn't search further.
|
||||||
|
|
||||||
(2) It considers all the non-keyring keys within that keyring and, if any key
|
2) It considers all the non-keyring keys within that keyring and, if any key
|
||||||
matches the criteria specified, calls key_permission(SEARCH) on it to see
|
matches the criteria specified, calls key_permission(SEARCH) on it to see
|
||||||
if the key is allowed to be found. If it is, that key is returned; if
|
if the key is allowed to be found. If it is, that key is returned; if
|
||||||
not, the search continues, and the error code is retained if of higher
|
not, the search continues, and the error code is retained if of higher
|
||||||
priority than the one currently set.
|
priority than the one currently set.
|
||||||
|
|
||||||
(3) It then considers all the keyring-type keys in the keyring it's currently
|
3) It then considers all the keyring-type keys in the keyring it's currently
|
||||||
searching. It calls key_permission(SEARCH) on each keyring, and if this
|
searching. It calls key_permission(SEARCH) on each keyring, and if this
|
||||||
grants permission, it recurses, executing steps (2) and (3) on that
|
grants permission, it recurses, executing steps (2) and (3) on that
|
||||||
keyring.
|
keyring.
|
||||||
|
@ -173,20 +170,20 @@ returned.
|
||||||
When search_process_keyrings() is invoked, it performs the following searches
|
When search_process_keyrings() is invoked, it performs the following searches
|
||||||
until one succeeds:
|
until one succeeds:
|
||||||
|
|
||||||
(1) If extant, the process's thread keyring is searched.
|
1) If extant, the process's thread keyring is searched.
|
||||||
|
|
||||||
(2) If extant, the process's process keyring is searched.
|
2) If extant, the process's process keyring is searched.
|
||||||
|
|
||||||
(3) The process's session keyring is searched.
|
3) The process's session keyring is searched.
|
||||||
|
|
||||||
(4) If the process has assumed the authority associated with a request_key()
|
4) If the process has assumed the authority associated with a request_key()
|
||||||
authorisation key then:
|
authorisation key then:
|
||||||
|
|
||||||
(a) If extant, the calling process's thread keyring is searched.
|
a) If extant, the calling process's thread keyring is searched.
|
||||||
|
|
||||||
(b) If extant, the calling process's process keyring is searched.
|
b) If extant, the calling process's process keyring is searched.
|
||||||
|
|
||||||
(c) The calling process's session keyring is searched.
|
c) The calling process's session keyring is searched.
|
||||||
|
|
||||||
The moment one succeeds, all pending errors are discarded and the found key is
|
The moment one succeeds, all pending errors are discarded and the found key is
|
||||||
returned.
|
returned.
|
||||||
|
@ -194,7 +191,7 @@ returned.
|
||||||
Only if all these fail does the whole thing fail with the highest priority
|
Only if all these fail does the whole thing fail with the highest priority
|
||||||
error. Note that several errors may have come from LSM.
|
error. Note that several errors may have come from LSM.
|
||||||
|
|
||||||
The error priority is:
|
The error priority is::
|
||||||
|
|
||||||
EKEYREVOKED > EKEYEXPIRED > ENOKEY
|
EKEYREVOKED > EKEYEXPIRED > ENOKEY
|
||||||
|
|
|
@ -1,4 +1,6 @@
|
||||||
Trusted and Encrypted Keys
|
==========================
|
||||||
|
Trusted and Encrypted Keys
|
||||||
|
==========================
|
||||||
|
|
||||||
Trusted and Encrypted Keys are two new key types added to the existing kernel
|
Trusted and Encrypted Keys are two new key types added to the existing kernel
|
||||||
key ring service. Both of these new types are variable length symmetric keys,
|
key ring service. Both of these new types are variable length symmetric keys,
|
||||||
|
@ -20,7 +22,8 @@ By default, trusted keys are sealed under the SRK, which has the default
|
||||||
authorization value (20 zeros). This can be set at takeownership time with the
|
authorization value (20 zeros). This can be set at takeownership time with the
|
||||||
trouser's utility: "tpm_takeownership -u -z".
|
trouser's utility: "tpm_takeownership -u -z".
|
||||||
|
|
||||||
Usage:
|
Usage::
|
||||||
|
|
||||||
keyctl add trusted name "new keylen [options]" ring
|
keyctl add trusted name "new keylen [options]" ring
|
||||||
keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring
|
keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring
|
||||||
keyctl update key "update [options]"
|
keyctl update key "update [options]"
|
||||||
|
@ -64,19 +67,22 @@ The decrypted portion of encrypted keys can contain either a simple symmetric
|
||||||
key or a more complex structure. The format of the more complex structure is
|
key or a more complex structure. The format of the more complex structure is
|
||||||
application specific, which is identified by 'format'.
|
application specific, which is identified by 'format'.
|
||||||
|
|
||||||
Usage:
|
Usage::
|
||||||
|
|
||||||
keyctl add encrypted name "new [format] key-type:master-key-name keylen"
|
keyctl add encrypted name "new [format] key-type:master-key-name keylen"
|
||||||
ring
|
ring
|
||||||
keyctl add encrypted name "load hex_blob" ring
|
keyctl add encrypted name "load hex_blob" ring
|
||||||
keyctl update keyid "update key-type:master-key-name"
|
keyctl update keyid "update key-type:master-key-name"
|
||||||
|
|
||||||
format:= 'default | ecryptfs'
|
Where::
|
||||||
key-type:= 'trusted' | 'user'
|
|
||||||
|
format:= 'default | ecryptfs'
|
||||||
|
key-type:= 'trusted' | 'user'
|
||||||
|
|
||||||
|
|
||||||
Examples of trusted and encrypted key usage:
|
Examples of trusted and encrypted key usage:
|
||||||
|
|
||||||
Create and save a trusted key named "kmk" of length 32 bytes:
|
Create and save a trusted key named "kmk" of length 32 bytes::
|
||||||
|
|
||||||
$ keyctl add trusted kmk "new 32" @u
|
$ keyctl add trusted kmk "new 32" @u
|
||||||
440502848
|
440502848
|
||||||
|
@ -99,7 +105,7 @@ Create and save a trusted key named "kmk" of length 32 bytes:
|
||||||
|
|
||||||
$ keyctl pipe 440502848 > kmk.blob
|
$ keyctl pipe 440502848 > kmk.blob
|
||||||
|
|
||||||
Load a trusted key from the saved blob:
|
Load a trusted key from the saved blob::
|
||||||
|
|
||||||
$ keyctl add trusted kmk "load `cat kmk.blob`" @u
|
$ keyctl add trusted kmk "load `cat kmk.blob`" @u
|
||||||
268728824
|
268728824
|
||||||
|
@ -114,7 +120,7 @@ Load a trusted key from the saved blob:
|
||||||
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
|
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
|
||||||
e4a8aea2b607ec96931e6f4d4fe563ba
|
e4a8aea2b607ec96931e6f4d4fe563ba
|
||||||
|
|
||||||
Reseal a trusted key under new pcr values:
|
Reseal a trusted key under new pcr values::
|
||||||
|
|
||||||
$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
|
$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
|
||||||
$ keyctl print 268728824
|
$ keyctl print 268728824
|
||||||
|
@ -135,11 +141,13 @@ compromised by a user level problem, and when sealed to specific boot PCR
|
||||||
values, protects against boot and offline attacks. Create and save an
|
values, protects against boot and offline attacks. Create and save an
|
||||||
encrypted key "evm" using the above trusted key "kmk":
|
encrypted key "evm" using the above trusted key "kmk":
|
||||||
|
|
||||||
option 1: omitting 'format'
|
option 1: omitting 'format'::
|
||||||
|
|
||||||
$ keyctl add encrypted evm "new trusted:kmk 32" @u
|
$ keyctl add encrypted evm "new trusted:kmk 32" @u
|
||||||
159771175
|
159771175
|
||||||
|
|
||||||
option 2: explicitly defining 'format' as 'default'
|
option 2: explicitly defining 'format' as 'default'::
|
||||||
|
|
||||||
$ keyctl add encrypted evm "new default trusted:kmk 32" @u
|
$ keyctl add encrypted evm "new default trusted:kmk 32" @u
|
||||||
159771175
|
159771175
|
||||||
|
|
||||||
|
@ -150,7 +158,7 @@ option 2: explicitly defining 'format' as 'default'
|
||||||
|
|
||||||
$ keyctl pipe 159771175 > evm.blob
|
$ keyctl pipe 159771175 > evm.blob
|
||||||
|
|
||||||
Load an encrypted key "evm" from saved blob:
|
Load an encrypted key "evm" from saved blob::
|
||||||
|
|
||||||
$ keyctl add encrypted evm "load `cat evm.blob`" @u
|
$ keyctl add encrypted evm "load `cat evm.blob`" @u
|
||||||
831684262
|
831684262
|
||||||
|
@ -164,4 +172,4 @@ Other uses for trusted and encrypted keys, such as for disk and file encryption
|
||||||
are anticipated. In particular the new format 'ecryptfs' has been defined in
|
are anticipated. In particular the new format 'ecryptfs' has been defined in
|
||||||
in order to use encrypted keys to mount an eCryptfs filesystem. More details
|
in order to use encrypted keys to mount an eCryptfs filesystem. More details
|
||||||
about the usage can be found in the file
|
about the usage can be found in the file
|
||||||
'Documentation/security/keys-ecryptfs.txt'.
|
``Documentation/security/keys-ecryptfs.txt``.
|
|
@ -1,4 +1,6 @@
|
||||||
# Kernel Self-Protection
|
======================
|
||||||
|
Kernel Self-Protection
|
||||||
|
======================
|
||||||
|
|
||||||
Kernel self-protection is the design and implementation of systems and
|
Kernel self-protection is the design and implementation of systems and
|
||||||
structures within the Linux kernel to protect against security flaws in
|
structures within the Linux kernel to protect against security flaws in
|
||||||
|
@ -26,7 +28,8 @@ mentioning them, since these aspects need to be explored, dealt with,
|
||||||
and/or accepted.
|
and/or accepted.
|
||||||
|
|
||||||
|
|
||||||
## Attack Surface Reduction
|
Attack Surface Reduction
|
||||||
|
========================
|
||||||
|
|
||||||
The most fundamental defense against security exploits is to reduce the
|
The most fundamental defense against security exploits is to reduce the
|
||||||
areas of the kernel that can be used to redirect execution. This ranges
|
areas of the kernel that can be used to redirect execution. This ranges
|
||||||
|
@ -34,13 +37,15 @@ from limiting the exposed APIs available to userspace, making in-kernel
|
||||||
APIs hard to use incorrectly, minimizing the areas of writable kernel
|
APIs hard to use incorrectly, minimizing the areas of writable kernel
|
||||||
memory, etc.
|
memory, etc.
|
||||||
|
|
||||||
### Strict kernel memory permissions
|
Strict kernel memory permissions
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
When all of kernel memory is writable, it becomes trivial for attacks
|
When all of kernel memory is writable, it becomes trivial for attacks
|
||||||
to redirect execution flow. To reduce the availability of these targets
|
to redirect execution flow. To reduce the availability of these targets
|
||||||
the kernel needs to protect its memory with a tight set of permissions.
|
the kernel needs to protect its memory with a tight set of permissions.
|
||||||
|
|
||||||
#### Executable code and read-only data must not be writable
|
Executable code and read-only data must not be writable
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Any areas of the kernel with executable memory must not be writable.
|
Any areas of the kernel with executable memory must not be writable.
|
||||||
While this obviously includes the kernel text itself, we must consider
|
While this obviously includes the kernel text itself, we must consider
|
||||||
|
@ -51,18 +56,19 @@ kernel, they are implemented in a way where the memory is temporarily
|
||||||
made writable during the update, and then returned to the original
|
made writable during the update, and then returned to the original
|
||||||
permissions.)
|
permissions.)
|
||||||
|
|
||||||
In support of this are CONFIG_STRICT_KERNEL_RWX and
|
In support of this are ``CONFIG_STRICT_KERNEL_RWX`` and
|
||||||
CONFIG_STRICT_MODULE_RWX, which seek to make sure that code is not
|
``CONFIG_STRICT_MODULE_RWX``, which seek to make sure that code is not
|
||||||
writable, data is not executable, and read-only data is neither writable
|
writable, data is not executable, and read-only data is neither writable
|
||||||
nor executable.
|
nor executable.
|
||||||
|
|
||||||
Most architectures have these options on by default and not user selectable.
|
Most architectures have these options on by default and not user selectable.
|
||||||
For some architectures like arm that wish to have these be selectable,
|
For some architectures like arm that wish to have these be selectable,
|
||||||
the architecture Kconfig can select ARCH_OPTIONAL_KERNEL_RWX to enable
|
the architecture Kconfig can select ARCH_OPTIONAL_KERNEL_RWX to enable
|
||||||
a Kconfig prompt. CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT determines
|
a Kconfig prompt. ``CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT`` determines
|
||||||
the default setting when ARCH_OPTIONAL_KERNEL_RWX is enabled.
|
the default setting when ARCH_OPTIONAL_KERNEL_RWX is enabled.
|
||||||
|
|
||||||
#### Function pointers and sensitive variables must not be writable
|
Function pointers and sensitive variables must not be writable
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Vast areas of kernel memory contain function pointers that are looked
|
Vast areas of kernel memory contain function pointers that are looked
|
||||||
up by the kernel and used to continue execution (e.g. descriptor/vector
|
up by the kernel and used to continue execution (e.g. descriptor/vector
|
||||||
|
@ -74,8 +80,8 @@ so that they live in the .rodata section instead of the .data section
|
||||||
of the kernel, gaining the protection of the kernel's strict memory
|
of the kernel, gaining the protection of the kernel's strict memory
|
||||||
permissions as described above.
|
permissions as described above.
|
||||||
|
|
||||||
For variables that are initialized once at __init time, these can
|
For variables that are initialized once at ``__init`` time, these can
|
||||||
be marked with the (new and under development) __ro_after_init
|
be marked with the (new and under development) ``__ro_after_init``
|
||||||
attribute.
|
attribute.
|
||||||
|
|
||||||
What remains are variables that are updated rarely (e.g. GDT). These
|
What remains are variables that are updated rarely (e.g. GDT). These
|
||||||
|
@ -85,7 +91,8 @@ of their lifetime read-only. (For example, when being updated, only the
|
||||||
CPU thread performing the update would be given uninterruptible write
|
CPU thread performing the update would be given uninterruptible write
|
||||||
access to the memory.)
|
access to the memory.)
|
||||||
|
|
||||||
#### Segregation of kernel memory from userspace memory
|
Segregation of kernel memory from userspace memory
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The kernel must never execute userspace memory. The kernel must also never
|
The kernel must never execute userspace memory. The kernel must also never
|
||||||
access userspace memory without explicit expectation to do so. These
|
access userspace memory without explicit expectation to do so. These
|
||||||
|
@ -95,10 +102,11 @@ By blocking userspace memory in this way, execution and data parsing
|
||||||
cannot be passed to trivially-controlled userspace memory, forcing
|
cannot be passed to trivially-controlled userspace memory, forcing
|
||||||
attacks to operate entirely in kernel memory.
|
attacks to operate entirely in kernel memory.
|
||||||
|
|
||||||
### Reduced access to syscalls
|
Reduced access to syscalls
|
||||||
|
--------------------------
|
||||||
|
|
||||||
One trivial way to eliminate many syscalls for 64-bit systems is building
|
One trivial way to eliminate many syscalls for 64-bit systems is building
|
||||||
without CONFIG_COMPAT. However, this is rarely a feasible scenario.
|
without ``CONFIG_COMPAT``. However, this is rarely a feasible scenario.
|
||||||
|
|
||||||
The "seccomp" system provides an opt-in feature made available to
|
The "seccomp" system provides an opt-in feature made available to
|
||||||
userspace, which provides a way to reduce the number of kernel entry
|
userspace, which provides a way to reduce the number of kernel entry
|
||||||
|
@ -112,7 +120,8 @@ to trusted processes. This would keep the scope of kernel entry points
|
||||||
restricted to the more regular set of normally available to unprivileged
|
restricted to the more regular set of normally available to unprivileged
|
||||||
userspace.
|
userspace.
|
||||||
|
|
||||||
### Restricting access to kernel modules
|
Restricting access to kernel modules
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
The kernel should never allow an unprivileged user the ability to
|
The kernel should never allow an unprivileged user the ability to
|
||||||
load specific kernel modules, since that would provide a facility to
|
load specific kernel modules, since that would provide a facility to
|
||||||
|
@ -127,11 +136,12 @@ for debate in some scenarios.)
|
||||||
To protect against even privileged users, systems may need to either
|
To protect against even privileged users, systems may need to either
|
||||||
disable module loading entirely (e.g. monolithic kernel builds or
|
disable module loading entirely (e.g. monolithic kernel builds or
|
||||||
modules_disabled sysctl), or provide signed modules (e.g.
|
modules_disabled sysctl), or provide signed modules (e.g.
|
||||||
CONFIG_MODULE_SIG_FORCE, or dm-crypt with LoadPin), to keep from having
|
``CONFIG_MODULE_SIG_FORCE``, or dm-crypt with LoadPin), to keep from having
|
||||||
root load arbitrary kernel code via the module loader interface.
|
root load arbitrary kernel code via the module loader interface.
|
||||||
|
|
||||||
|
|
||||||
## Memory integrity
|
Memory integrity
|
||||||
|
================
|
||||||
|
|
||||||
There are many memory structures in the kernel that are regularly abused
|
There are many memory structures in the kernel that are regularly abused
|
||||||
to gain execution control during an attack, By far the most commonly
|
to gain execution control during an attack, By far the most commonly
|
||||||
|
@ -139,16 +149,18 @@ understood is that of the stack buffer overflow in which the return
|
||||||
address stored on the stack is overwritten. Many other examples of this
|
address stored on the stack is overwritten. Many other examples of this
|
||||||
kind of attack exist, and protections exist to defend against them.
|
kind of attack exist, and protections exist to defend against them.
|
||||||
|
|
||||||
### Stack buffer overflow
|
Stack buffer overflow
|
||||||
|
---------------------
|
||||||
|
|
||||||
The classic stack buffer overflow involves writing past the expected end
|
The classic stack buffer overflow involves writing past the expected end
|
||||||
of a variable stored on the stack, ultimately writing a controlled value
|
of a variable stored on the stack, ultimately writing a controlled value
|
||||||
to the stack frame's stored return address. The most widely used defense
|
to the stack frame's stored return address. The most widely used defense
|
||||||
is the presence of a stack canary between the stack variables and the
|
is the presence of a stack canary between the stack variables and the
|
||||||
return address (CONFIG_CC_STACKPROTECTOR), which is verified just before
|
return address (``CONFIG_CC_STACKPROTECTOR``), which is verified just before
|
||||||
the function returns. Other defenses include things like shadow stacks.
|
the function returns. Other defenses include things like shadow stacks.
|
||||||
|
|
||||||
### Stack depth overflow
|
Stack depth overflow
|
||||||
|
--------------------
|
||||||
|
|
||||||
A less well understood attack is using a bug that triggers the
|
A less well understood attack is using a bug that triggers the
|
||||||
kernel to consume stack memory with deep function calls or large stack
|
kernel to consume stack memory with deep function calls or large stack
|
||||||
|
@ -158,27 +170,31 @@ important changes need to be made for better protections: moving the
|
||||||
sensitive thread_info structure elsewhere, and adding a faulting memory
|
sensitive thread_info structure elsewhere, and adding a faulting memory
|
||||||
hole at the bottom of the stack to catch these overflows.
|
hole at the bottom of the stack to catch these overflows.
|
||||||
|
|
||||||
### Heap memory integrity
|
Heap memory integrity
|
||||||
|
---------------------
|
||||||
|
|
||||||
The structures used to track heap free lists can be sanity-checked during
|
The structures used to track heap free lists can be sanity-checked during
|
||||||
allocation and freeing to make sure they aren't being used to manipulate
|
allocation and freeing to make sure they aren't being used to manipulate
|
||||||
other memory areas.
|
other memory areas.
|
||||||
|
|
||||||
### Counter integrity
|
Counter integrity
|
||||||
|
-----------------
|
||||||
|
|
||||||
Many places in the kernel use atomic counters to track object references
|
Many places in the kernel use atomic counters to track object references
|
||||||
or perform similar lifetime management. When these counters can be made
|
or perform similar lifetime management. When these counters can be made
|
||||||
to wrap (over or under) this traditionally exposes a use-after-free
|
to wrap (over or under) this traditionally exposes a use-after-free
|
||||||
flaw. By trapping atomic wrapping, this class of bug vanishes.
|
flaw. By trapping atomic wrapping, this class of bug vanishes.
|
||||||
|
|
||||||
### Size calculation overflow detection
|
Size calculation overflow detection
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
Similar to counter overflow, integer overflows (usually size calculations)
|
Similar to counter overflow, integer overflows (usually size calculations)
|
||||||
need to be detected at runtime to kill this class of bug, which
|
need to be detected at runtime to kill this class of bug, which
|
||||||
traditionally leads to being able to write past the end of kernel buffers.
|
traditionally leads to being able to write past the end of kernel buffers.
|
||||||
|
|
||||||
|
|
||||||
## Statistical defenses
|
Probabilistic defenses
|
||||||
|
======================
|
||||||
|
|
||||||
While many protections can be considered deterministic (e.g. read-only
|
While many protections can be considered deterministic (e.g. read-only
|
||||||
memory cannot be written to), some protections provide only statistical
|
memory cannot be written to), some protections provide only statistical
|
||||||
|
@ -186,7 +202,8 @@ defense, in that an attack must gather enough information about a
|
||||||
running system to overcome the defense. While not perfect, these do
|
running system to overcome the defense. While not perfect, these do
|
||||||
provide meaningful defenses.
|
provide meaningful defenses.
|
||||||
|
|
||||||
### Canaries, blinding, and other secrets
|
Canaries, blinding, and other secrets
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
It should be noted that things like the stack canary discussed earlier
|
It should be noted that things like the stack canary discussed earlier
|
||||||
are technically statistical defenses, since they rely on a secret value,
|
are technically statistical defenses, since they rely on a secret value,
|
||||||
|
@ -201,7 +218,8 @@ It is critical that the secret values used must be separate (e.g.
|
||||||
different canary per stack) and high entropy (e.g. is the RNG actually
|
different canary per stack) and high entropy (e.g. is the RNG actually
|
||||||
working?) in order to maximize their success.
|
working?) in order to maximize their success.
|
||||||
|
|
||||||
### Kernel Address Space Layout Randomization (KASLR)
|
Kernel Address Space Layout Randomization (KASLR)
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
Since the location of kernel memory is almost always instrumental in
|
Since the location of kernel memory is almost always instrumental in
|
||||||
mounting a successful attack, making the location non-deterministic
|
mounting a successful attack, making the location non-deterministic
|
||||||
|
@ -209,22 +227,25 @@ raises the difficulty of an exploit. (Note that this in turn makes
|
||||||
the value of information exposures higher, since they may be used to
|
the value of information exposures higher, since they may be used to
|
||||||
discover desired memory locations.)
|
discover desired memory locations.)
|
||||||
|
|
||||||
#### Text and module base
|
Text and module base
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
By relocating the physical and virtual base address of the kernel at
|
By relocating the physical and virtual base address of the kernel at
|
||||||
boot-time (CONFIG_RANDOMIZE_BASE), attacks needing kernel code will be
|
boot-time (``CONFIG_RANDOMIZE_BASE``), attacks needing kernel code will be
|
||||||
frustrated. Additionally, offsetting the module loading base address
|
frustrated. Additionally, offsetting the module loading base address
|
||||||
means that even systems that load the same set of modules in the same
|
means that even systems that load the same set of modules in the same
|
||||||
order every boot will not share a common base address with the rest of
|
order every boot will not share a common base address with the rest of
|
||||||
the kernel text.
|
the kernel text.
|
||||||
|
|
||||||
#### Stack base
|
Stack base
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
If the base address of the kernel stack is not the same between processes,
|
If the base address of the kernel stack is not the same between processes,
|
||||||
or even not the same between syscalls, targets on or beyond the stack
|
or even not the same between syscalls, targets on or beyond the stack
|
||||||
become more difficult to locate.
|
become more difficult to locate.
|
||||||
|
|
||||||
#### Dynamic memory base
|
Dynamic memory base
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up
|
Much of the kernel's dynamic memory (e.g. kmalloc, vmalloc, etc) ends up
|
||||||
being relatively deterministic in layout due to the order of early-boot
|
being relatively deterministic in layout due to the order of early-boot
|
||||||
|
@ -232,7 +253,8 @@ initializations. If the base address of these areas is not the same
|
||||||
between boots, targeting them is frustrated, requiring an information
|
between boots, targeting them is frustrated, requiring an information
|
||||||
exposure specific to the region.
|
exposure specific to the region.
|
||||||
|
|
||||||
#### Structure layout
|
Structure layout
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
By performing a per-build randomization of the layout of sensitive
|
By performing a per-build randomization of the layout of sensitive
|
||||||
structures, attacks must either be tuned to known kernel builds or expose
|
structures, attacks must either be tuned to known kernel builds or expose
|
||||||
|
@ -240,26 +262,30 @@ enough kernel memory to determine structure layouts before manipulating
|
||||||
them.
|
them.
|
||||||
|
|
||||||
|
|
||||||
## Preventing Information Exposures
|
Preventing Information Exposures
|
||||||
|
================================
|
||||||
|
|
||||||
Since the locations of sensitive structures are the primary target for
|
Since the locations of sensitive structures are the primary target for
|
||||||
attacks, it is important to defend against exposure of both kernel memory
|
attacks, it is important to defend against exposure of both kernel memory
|
||||||
addresses and kernel memory contents (since they may contain kernel
|
addresses and kernel memory contents (since they may contain kernel
|
||||||
addresses or other sensitive things like canary values).
|
addresses or other sensitive things like canary values).
|
||||||
|
|
||||||
### Unique identifiers
|
Unique identifiers
|
||||||
|
------------------
|
||||||
|
|
||||||
Kernel memory addresses must never be used as identifiers exposed to
|
Kernel memory addresses must never be used as identifiers exposed to
|
||||||
userspace. Instead, use an atomic counter, an idr, or similar unique
|
userspace. Instead, use an atomic counter, an idr, or similar unique
|
||||||
identifier.
|
identifier.
|
||||||
|
|
||||||
### Memory initialization
|
Memory initialization
|
||||||
|
---------------------
|
||||||
|
|
||||||
Memory copied to userspace must always be fully initialized. If not
|
Memory copied to userspace must always be fully initialized. If not
|
||||||
explicitly memset(), this will require changes to the compiler to make
|
explicitly memset(), this will require changes to the compiler to make
|
||||||
sure structure holes are cleared.
|
sure structure holes are cleared.
|
||||||
|
|
||||||
### Memory poisoning
|
Memory poisoning
|
||||||
|
----------------
|
||||||
|
|
||||||
When releasing memory, it is best to poison the contents (clear stack on
|
When releasing memory, it is best to poison the contents (clear stack on
|
||||||
syscall return, wipe heap memory on a free), to avoid reuse attacks that
|
syscall return, wipe heap memory on a free), to avoid reuse attacks that
|
||||||
|
@ -267,9 +293,10 @@ rely on the old contents of memory. This frustrates many uninitialized
|
||||||
variable attacks, stack content exposures, heap content exposures, and
|
variable attacks, stack content exposures, heap content exposures, and
|
||||||
use-after-free attacks.
|
use-after-free attacks.
|
||||||
|
|
||||||
### Destination tracking
|
Destination tracking
|
||||||
|
--------------------
|
||||||
|
|
||||||
To help kill classes of bugs that result in kernel addresses being
|
To help kill classes of bugs that result in kernel addresses being
|
||||||
written to userspace, the destination of writes needs to be tracked. If
|
written to userspace, the destination of writes needs to be tracked. If
|
||||||
the buffer is destined for userspace (e.g. seq_file backed /proc files),
|
the buffer is destined for userspace (e.g. seq_file backed ``/proc`` files),
|
||||||
it should automatically censor sensitive values.
|
it should automatically censor sensitive values.
|
10
Documentation/sh/conf.py
Normal file
10
Documentation/sh/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = "SuperH architecture implementation manual"
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'sh.tex', project,
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
59
Documentation/sh/index.rst
Normal file
59
Documentation/sh/index.rst
Normal file
|
@ -0,0 +1,59 @@
|
||||||
|
=======================
|
||||||
|
SuperH Interfaces Guide
|
||||||
|
=======================
|
||||||
|
|
||||||
|
:Author: Paul Mundt
|
||||||
|
|
||||||
|
Memory Management
|
||||||
|
=================
|
||||||
|
|
||||||
|
SH-4
|
||||||
|
----
|
||||||
|
|
||||||
|
Store Queue API
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/sh/kernel/cpu/sh4/sq.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
SH-5
|
||||||
|
----
|
||||||
|
|
||||||
|
TLB Interfaces
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/sh/mm/tlb-sh5.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/sh/include/asm/tlb_64.h
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
Machine Specific Interfaces
|
||||||
|
===========================
|
||||||
|
|
||||||
|
mach-dreamcast
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/sh/boards/mach-dreamcast/rtc.c
|
||||||
|
:internal:
|
||||||
|
|
||||||
|
mach-x3proto
|
||||||
|
------------
|
||||||
|
|
||||||
|
.. kernel-doc:: arch/sh/boards/mach-x3proto/ilsel.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Busses
|
||||||
|
======
|
||||||
|
|
||||||
|
SuperHyway
|
||||||
|
----------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/sh/superhyway/superhyway.c
|
||||||
|
:export:
|
||||||
|
|
||||||
|
Maple
|
||||||
|
-----
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/sh/maple/maple.c
|
||||||
|
:export:
|
10
Documentation/sound/conf.py
Normal file
10
Documentation/sound/conf.py
Normal file
|
@ -0,0 +1,10 @@
|
||||||
|
# -*- coding: utf-8; mode: python -*-
|
||||||
|
|
||||||
|
project = "Linux Sound Subsystem Documentation"
|
||||||
|
|
||||||
|
tags.add("subproject")
|
||||||
|
|
||||||
|
latex_documents = [
|
||||||
|
('index', 'sound.tex', project,
|
||||||
|
'The kernel development community', 'manual'),
|
||||||
|
]
|
|
@ -1,18 +0,0 @@
|
||||||
#
|
|
||||||
# Pandoc doesn't grok <function> or <structname>, so convert them
|
|
||||||
# ahead of time.
|
|
||||||
#
|
|
||||||
# Use the following escapes to pass through pandoc:
|
|
||||||
# $bq = "`"
|
|
||||||
# $lt = "<"
|
|
||||||
# $gt = ">"
|
|
||||||
#
|
|
||||||
s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1()$bq%g
|
|
||||||
s%<function>\([^<(]\+\)</function>%:c:func:$bq\1()$bq%g
|
|
||||||
s%<structname>struct *\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
|
|
||||||
s%struct <structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
|
|
||||||
s%<structname>\([^<]\+\)</structname>%:c:type:$bqstruct \1 $lt\1$gt$bq%g
|
|
||||||
#
|
|
||||||
# Wrap docproc directives in para and code blocks.
|
|
||||||
#
|
|
||||||
s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%
|
|
|
@ -1,23 +0,0 @@
|
||||||
#
|
|
||||||
# Unescape.
|
|
||||||
#
|
|
||||||
s/$bq/`/g
|
|
||||||
s/$lt/</g
|
|
||||||
s/$gt/>/g
|
|
||||||
#
|
|
||||||
# pandoc thinks that both "_" needs to be escaped. Remove the extra
|
|
||||||
# backslashes.
|
|
||||||
#
|
|
||||||
s/\\_/_/g
|
|
||||||
#
|
|
||||||
# Unwrap docproc directives.
|
|
||||||
#
|
|
||||||
s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n :export:/
|
|
||||||
s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n :internal:/
|
|
||||||
s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :functions: \2/
|
|
||||||
s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :doc: \2/
|
|
||||||
s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
|
|
||||||
#
|
|
||||||
# Trim trailing whitespace.
|
|
||||||
#
|
|
||||||
s/[[:space:]]*$//
|
|
|
@ -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 latexdocs
|
||||||
make epubdocs
|
make epubdocs
|
||||||
|
|
||||||
現在、幾つかの DocBook形式で書かれたドキュメントは ReST形式に転換中で
|
|
||||||
す。それらのドキュメントはDocumentation/DocBook ディレクトリに生成され、
|
|
||||||
Postscript または man ページの形式を生成するには以下のようにします - ::
|
|
||||||
|
|
||||||
make psdocs
|
|
||||||
make mandocs
|
|
||||||
|
|
||||||
カーネル開発者になるには
|
カーネル開発者になるには
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
|
|
|
@ -191,13 +191,6 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된
|
||||||
make latexdocs
|
make latexdocs
|
||||||
make epubdocs
|
make epubdocs
|
||||||
|
|
||||||
현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
|
|
||||||
문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
|
|
||||||
Postscript 나 man page 로도 만들어질 수 있다::
|
|
||||||
|
|
||||||
make psdocs
|
|
||||||
make mandocs
|
|
||||||
|
|
||||||
커널 개발자가 되는 것
|
커널 개발자가 되는 것
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
@ -270,15 +263,17 @@ pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세
|
||||||
선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은
|
선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은
|
||||||
https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
|
https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
|
||||||
패치파일의 형식으로 보내는 것도 무관하다.
|
패치파일의 형식으로 보내는 것도 무관하다.
|
||||||
- 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
|
- 2주 후에 -rc1 커널이 릴리즈되며 여기서부터의 주안점은 새로운 커널을
|
||||||
미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
|
가능한한 안정되게 하는 것이다. 이 시점에서의 대부분의 패치들은
|
||||||
완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
|
|
||||||
것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
|
|
||||||
드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
|
|
||||||
회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
|
회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
|
||||||
생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
|
생겨난 버그)를 고쳐야 한다. 이전부터 존재한 버그는 회귀가 아니므로, 그런
|
||||||
배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
|
버그에 대한 수정사항은 중요한 경우에만 보내져야 한다. 완전히 새로운
|
||||||
공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
|
드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는 것을 기억해라.
|
||||||
|
왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가 드라이버 외부의 다른
|
||||||
|
부분에는 영향을 주지 않으므로 그런 변경은 회귀를 일으킬 만한 위험을 가지고
|
||||||
|
있지 않기 때문이다. -rc1이 배포된 이후에 git를 사용하여 패치들을 Linus에게
|
||||||
|
보낼수 있지만 패치들은 공식적인 메일링 리스트로 보내서 검토를 받을 필요가
|
||||||
|
있다.
|
||||||
- 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
|
- 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
|
||||||
있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
|
있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
|
||||||
것이다.
|
것이다.
|
||||||
|
@ -359,7 +354,7 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다.
|
||||||
버그 보고
|
버그 보고
|
||||||
---------
|
---------
|
||||||
|
|
||||||
https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는
|
https://bugzilla.kernel.org 는 리눅스 커널 개발자들이 커널의 버그를 추적하는
|
||||||
곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
|
곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
|
||||||
권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
|
권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
|
||||||
|
|
||||||
|
|
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue