diff --git a/release/latex/Makefile b/release/latex/Makefile new file mode 100644 index 0000000..d748006 --- /dev/null +++ b/release/latex/Makefile @@ -0,0 +1,78 @@ +# Makefile for Sphinx LaTeX output + +ALLDOCS = $(basename $(wildcard *.tex)) +ALLPDF = $(addsuffix .pdf,$(ALLDOCS)) +ALLDVI = $(addsuffix .dvi,$(ALLDOCS)) + +# Prefix for archive names +ARCHIVEPRREFIX = +# Additional LaTeX options +LATEXOPTS = +# format: pdf or dvi +FMT = pdf + +LATEX = latex +PDFLATEX = pdflatex +MAKEINDEX = makeindex + +all: $(ALLPDF) +all-pdf: $(ALLPDF) +all-dvi: $(ALLDVI) +all-ps: all-dvi + for f in *.dvi; do dvips $$f; done + +all-pdf-ja: + for f in *.pdf *.png *.gif *.jpg *.jpeg; do extractbb $$f; done + for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done + for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done + for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done + -for f in *.idx; do mendex -U -f -d "`basename $$f .idx`.dic" -s python.ist $$f; done + for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done + for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done + for f in *.dvi; do dvipdfmx $$f; done + +zip: all-$(FMT) + mkdir $(ARCHIVEPREFIX)docs-$(FMT) + cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT) + zip -q -r -9 $(ARCHIVEPREFIX)docs-$(FMT).zip $(ARCHIVEPREFIX)docs-$(FMT) + rm -r $(ARCHIVEPREFIX)docs-$(FMT) + +tar: all-$(FMT) + mkdir $(ARCHIVEPREFIX)docs-$(FMT) + cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT) + tar cf $(ARCHIVEPREFIX)docs-$(FMT).tar $(ARCHIVEPREFIX)docs-$(FMT) + rm -r $(ARCHIVEPREFIX)docs-$(FMT) + +gz: tar + gzip -9 < $(ARCHIVEPREFIX)docs-$(FMT).tar > $(ARCHIVEPREFIX)docs-$(FMT).tar.gz + +bz2: tar + bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar + +xz: tar + xz -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar + +# The number of LaTeX runs is quite conservative, but I don't expect it +# to get run often, so the little extra time won't hurt. +%.dvi: %.tex + $(LATEX) $(LATEXOPTS) '$<' + $(LATEX) $(LATEXOPTS) '$<' + $(LATEX) $(LATEXOPTS) '$<' + -$(MAKEINDEX) -s python.ist '$(basename $<).idx' + $(LATEX) $(LATEXOPTS) '$<' + $(LATEX) $(LATEXOPTS) '$<' + +%.pdf: %.tex + $(PDFLATEX) $(LATEXOPTS) '$<' + $(PDFLATEX) $(LATEXOPTS) '$<' + $(PDFLATEX) $(LATEXOPTS) '$<' + -$(MAKEINDEX) -s python.ist '$(basename $<).idx' + $(PDFLATEX) $(LATEXOPTS) '$<' + $(PDFLATEX) $(LATEXOPTS) '$<' + +clean: + rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz $(ALLPDF) $(ALLDVI) + +.PHONY: all all-pdf all-dvi all-ps clean zip tar gz bz2 xz +.PHONY: all-pdf-ja + diff --git a/release/latex/devicetree-logo.png b/release/latex/devicetree-logo.png new file mode 100644 index 0000000..e00bb33 Binary files /dev/null and b/release/latex/devicetree-logo.png differ diff --git a/release/latex/devicetree-specification.tex b/release/latex/devicetree-specification.tex index 399ddb5..71ac11e 100644 --- a/release/latex/devicetree-specification.tex +++ b/release/latex/devicetree-specification.tex @@ -25,11 +25,11 @@ \addto\extrasenglish{\def\pageautorefname{page}} \setcounter{tocdepth}{2} -\usepackage{draftwatermark}\SetWatermarkScale{.45}\SetWatermarkText{DRAFT v0.1-pre1-20160524} + \title{Devicetree Specification} \date{24 May 2016} -\release{0.1-pre1-20160524} +\release{0.1} \author{devicetree.org} \newcommand{\sphinxlogo}{\includegraphics{devicetree-logo.png}\par} \renewcommand{\releasename}{Release} @@ -143,10 +143,10 @@ \textbf{Copyright} \begin{DUlineblock}{0em} -\item[] Copyright 2016 Linaro, Ltd. \item[] Copyright 2008,2011 Power.org, Inc. \item[] Copyright 2008,2011 Freescale Semiconductor, Inc. \item[] Copyright 2008,2011 International Business Machines Corporation. +\item[] Copyright 2016 Linaro, Ltd. \item[] Copyright 2016 ARM Ltd. \end{DUlineblock} @@ -168,7 +168,7 @@ identifying or failing to identify any or all such third party intellectual property rights. -THIS SPECIFICATION PROVIDED “AS IS” AND WITHOUT ANY WARRANTY +THIS SPECIFICATION PROVIDED ``AS IS'' AND WITHOUT ANY WARRANTY OF ANY KIND, INCLUDING, WITHOUT LIMITATION, ANY EXPRESS OR IMPLIED WARRANTY OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL LINARO OR ANY MEMBER OF @@ -203,141 +203,26 @@ \newpage \textbf{Acknowledgements} -The power.org Platform Architecture Technical Subcommittee would like +The devicetree.org Technical Steering Committee would like thank the many individuals and companies that contributed to the development this specification through writing, technical discussions and reviews. -\textbf{Individuals} -\begin{itemize}\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt} -\item {} -Hollis Blanchard - -\item {} -Dan Bouvier - -\item {} -Josh Boyer - -\item {} -Becky Bruce - -\item {} -Dale Farnsworth - -\item {} -Kumar Gala - -\item {} -Charles Garcia-Tobin - -\item {} -David Gibson - -\item {} -Ben Herrenschmidt - -\item {} -Rob Herring - -\item {} -Dan Hettena - -\item {} -Olof Johansson - -\item {} -Ashish Kalra - -\item {} -Grant Likely - -\item {} -Jon Loeliger - -\item {} -Hartmut Penner - -\item {} -Mark Rutland - -\item {} -Tim Radzykewycz - -\item {} -Heiko Schick - -\item {} -Jeff Scheel - -\item {} -Timur Tabi - -\item {} -John Traill - -\item {} -John True - -\item {} -Matt Tyrlik - -\item {} -Kanta Vekaria - -\item {} -Dave Willoughby - -\item {} -Scott Wood - -\item {} -Jimi Xenidis - -\item {} -Stuart Yoder - -\end{itemize} - -\textbf{Companies} -\begin{itemize}\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt} -\item {} -ARM - -\item {} -Green Hills Software - -\item {} -IBM - -\item {} -Linaro - -\item {} -Montavista - -\item {} -NXP Semiconductor - -\item {} -Wind River - -\end{itemize} - -\textbf{Other Acknowledgements} +We want to thank the power.org Platform Architecture Technical Subcommittee who +developed and published ePAPR. The text of ePAPR was used as the starting +point for this document. Significant aspects of the Devicetree Specification are based on work done by the Open Firmware Working Group which developed bindings for IEEE-1275. We would like to acknowledge their contributions. We would also like to acknowledge the contribution of the PowerPC and ARM Linux -communities that developed and implemented the flattened device -tree concept. -\newpage\phantomsection\label{license:revision-history} +communities that developed and implemented the flattened devicetree concept. +\phantomsection\label{revhistory:revision-history} \begin{threeparttable} -\capstart\caption{Revision History}\label{license:id1} -\begin{tabulary}{\linewidth}{l l J} +\capstart\caption{Revision History}\label{revhistory:id1} +\begin{tabulary}{\linewidth}{| l l J |} \hline \textsf{\relax Revision @@ -347,29 +232,14 @@ Description }\\ \hline -ePAPR 1.0 - & -7/23/2008 - & -Initial Version -\\ -\hline -ePAPR 1.1 +DTSpec 0.1 & -3/7/2011 +2016-MAY-24 & -Updates include: virtualization chapter, consolidated -representation of cpu nodes, stdin/stdout properties -on /chosen, label property, representation of hardware -threads on cpu nodes, representation of Power ISA -categories on cpu nodes, mmu type property, removal of -some bindings, additional cpu entry requirements for -threaded cpus, miscellaneous cleanup and -clarifications. +Initial prerelease version. Imported ePAPR text +into reStructured Text format and removed Power ISA +specific elements. \\ -\hline -DTSpec 0.1 - & & \\ \hline\end{tabulary} \end{threeparttable} @@ -438,13 +308,13 @@ \section{Purpose and Scope} specified by DTSpec. \item {} -Chapter {\hyperref[devicetree\string-basics:chapter\string-devicetree]{\crossref{\DUrole{std,std-ref}{2}}}} introduces the device tree concept +Chapter {\hyperref[devicetree\string-basics:chapter\string-devicetree]{\crossref{\DUrole{std,std-ref}{2}}}} introduces the devicetree concept and describes its logical structure and standard properties. \item {} Chapter {\hyperref[devicenodes:chapter\string-device\string-node\string-requirements]{\crossref{\DUrole{std,std-ref}{3}}}} specifies the definition of a base set of device nodes required by DTSpec-compliant -device trees. +devicetrees. \item {} Chapter {\hyperref[device\string-bindings:chapter\string-device\string-bindings]{\crossref{\DUrole{std,std-ref}{4}}}} describes device bindings for @@ -452,7 +322,7 @@ \section{Purpose and Scope} \item {} Chapter {\hyperref[flattened\string-format:chapter\string-fdt\string-structure]{\crossref{\DUrole{std,std-ref}{5}}}} specifies the physical structure -of device trees. +of devicetrees. \end{itemize} @@ -472,7 +342,7 @@ \section{Purpose and Scope} The word \emph{may} is used to indicate a course of action permissible within the limits of the standard (\emph{may} equals \emph{is permitted}). -Examples of device tree constructs are frequently shown in \emph{Device Tree +Examples of devicetree constructs are frequently shown in \emph{Devicetree Syntax} form. See section {\hyperref[source\string-language:chapter\string-devicetree\string-source\string-format]{\crossref{\DUrole{std,std-ref}{6}}}} for an overview of this syntax. @@ -510,7 +380,7 @@ \section{Relationship to IEEE™ 1275 and ePAPR} \end{itemize} -What is retained from IEEE-1275 are concepts from the device tree +What is retained from IEEE-1275 are concepts from the devicetree architecture by which a boot program can describe and communicate system hardware information to client program, thus eliminating the need for the client program to have hard-coded descriptions of system hardware. @@ -562,15 +432,15 @@ \section{Definition of Terms} Direct memory access \item[{DTB\index{DTB|textbf}}] \leavevmode\phantomsection\label{introduction:term-dtb} -Device tree blob. Compact binary representation of the device tree. +Devicetree blob. Compact binary representation of the devicetree. \item[{DTC\index{DTC|textbf}}] \leavevmode\phantomsection\label{introduction:term-dtc} -Device tree compiler. An open source tool used to create DTB files +Devicetree compiler. An open source tool used to create DTB files from DTS files. \item[{DTS\index{DTS|textbf}}] \leavevmode\phantomsection\label{introduction:term-dts} -Device tree syntax. A textual representation of a device tree -consumed by the DTC. See Appendix A Device Tree Source Format +Devicetree syntax. A textual representation of a devicetree +consumed by the DTC. See Appendix A Devicetree Source Format (version 1). \item[{effective address\index{effective address|textbf}}] \leavevmode\phantomsection\label{introduction:term-effective-address} @@ -682,7 +552,7 @@ \subsubsection{Node Name Requirements} \begin{threeparttable} \capstart\caption{Valid characters for node names}\label{devicetree-basics:node-name-characters}\label{devicetree-basics:id4} -\begin{tabulary}{\linewidth}{c p{8cm}} +\begin{tabulary}{\linewidth}{| c p{8cm} |} \hline \textsf{\relax Character @@ -934,7 +804,7 @@ \subsubsection{Property Names} \begin{threeparttable} \capstart\caption{Valid characters for property names}\label{devicetree-basics:property-name-characters}\label{devicetree-basics:id6} -\begin{tabulary}{\linewidth}{c p{8cm}} +\begin{tabulary}{\linewidth}{| c p{8cm} |} \hline \textsf{\relax Character @@ -1015,7 +885,7 @@ \subsubsection{Property Values} \hyperref[devicetree-basics:property-values-table]{Table \ref{devicetree-basics:property-values-table}} describes the set of basic value types defined by the DTSpec. -\begin{longtable}{p{4cm} p{12cm}} +\begin{longtable}{| p{4cm} p{12cm} |} \caption{Property values}\label{devicetree-basics:property-values-table}\\ \hline \textsf{\relax @@ -1055,10 +925,10 @@ \subsubsection{Property Values} \begin{quote} \begin{OriginalVerbatim}[commandchars=\\\{\}] -\PYG{n}{address} \PYG{l+m+mi}{11} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{1} \PYG{l+m+mi}{22} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{2} \PYG{l+m+mi}{33} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{3} \PYG{l+m+mi}{44} +address 11 +address+1 22 +address+2 33 +address+3 44 \end{OriginalVerbatim} \end{quote} \\ @@ -1077,14 +947,14 @@ \subsubsection{Property Values} \begin{quote} \begin{OriginalVerbatim}[commandchars=\\\{\}] - \PYG{n}{address} \PYG{l+m+mi}{11} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{1} \PYG{l+m+mi}{22} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{2} \PYG{l+m+mi}{33} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{3} \PYG{l+m+mi}{44} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{4} \PYG{l+m+mi}{55} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{5} \PYG{l+m+mi}{66} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{6} \PYG{l+m+mi}{77} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{7} \PYG{l+m+mi}{88} + address 11 +address+1 22 +address+2 33 +address+3 44 +address+4 55 +address+5 66 +address+6 77 +address+7 88 \end{OriginalVerbatim} \end{quote} \\ @@ -1092,16 +962,16 @@ \subsubsection{Property Values} \code{\textless{}string\textgreater{}} & Strings are printable and null-terminated. Example: the string -“hello” would be represented in memory as: +``hello'' would be represented in memory as: \begin{quote} \begin{OriginalVerbatim}[commandchars=\\\{\}] - \PYG{n}{address} \PYG{l+m+mi}{68} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{h}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{1} \PYG{l+m+mi}{65} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{e}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{2} \PYG{l+m+mi}{6}\PYG{n}{C} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{l}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{3} \PYG{l+m+mi}{6}\PYG{n}{C} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{l}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{4} \PYG{l+m+mi}{6}\PYG{n}{F} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{o}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{5} \PYG{l+m+mi}{00} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+se}{\PYGZbs{}0}\PYG{l+s+s1}{\PYGZsq{}} + address 68 \PYGZsq{}h\PYGZsq{} +address+1 65 \PYGZsq{}e\PYGZsq{} +address+2 6C \PYGZsq{}l\PYGZsq{} +address+3 6C \PYGZsq{}l\PYGZsq{} +address+4 6F \PYGZsq{}o\PYGZsq{} +address+5 00 \PYGZsq{}\PYGZbs{}0\PYGZsq{} \end{OriginalVerbatim} \end{quote} \\ @@ -1129,18 +999,18 @@ \subsubsection{Property Values} \begin{quote} \begin{OriginalVerbatim}[commandchars=\\\{\}] - \PYG{n}{address} \PYG{l+m+mi}{68} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{h}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{1} \PYG{l+m+mi}{65} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{e}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{2} \PYG{l+m+mi}{6}\PYG{n}{C} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{l}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{3} \PYG{l+m+mi}{6}\PYG{n}{C} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{l}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{4} \PYG{l+m+mi}{6}\PYG{n}{F} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{o}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{5} \PYG{l+m+mi}{00} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+se}{\PYGZbs{}0}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{6} \PYG{l+m+mi}{77} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{w}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{7} \PYG{l+m+mi}{6}\PYG{n}{f} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{o}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{8} \PYG{l+m+mi}{72} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{r}\PYG{l+s+s1}{\PYGZsq{}} - \PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{9} \PYG{l+m+mi}{6}\PYG{n}{C} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{l}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{10} \PYG{l+m+mi}{64} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+s1}{d}\PYG{l+s+s1}{\PYGZsq{}} -\PYG{n}{address}\PYG{o}{+}\PYG{l+m+mi}{11} \PYG{l+m+mi}{00} \PYG{l+s+s1}{\PYGZsq{}}\PYG{l+s+se}{\PYGZbs{}0}\PYG{l+s+s1}{\PYGZsq{}} + address 68 \PYGZsq{}h\PYGZsq{} + address+1 65 \PYGZsq{}e\PYGZsq{} + address+2 6C \PYGZsq{}l\PYGZsq{} + address+3 6C \PYGZsq{}l\PYGZsq{} + address+4 6F \PYGZsq{}o\PYGZsq{} + address+5 00 \PYGZsq{}\PYGZbs{}0\PYGZsq{} + address+6 77 \PYGZsq{}w\PYGZsq{} + address+7 6f \PYGZsq{}o\PYGZsq{} + address+8 72 \PYGZsq{}r\PYGZsq{} + address+9 6C \PYGZsq{}l\PYGZsq{} +address+10 64 \PYGZsq{}d\PYGZsq{} +address+11 00 \PYGZsq{}\PYGZbs{}0\PYGZsq{} \end{OriginalVerbatim} \end{quote} \\ @@ -1152,9 +1022,9 @@ \section{Standard Properties} \label{devicetree-basics:standard-properties}\label{devicetree-basics:sect-standard-properties} DTSpec specifies a set of standard properties for device nodes. These properties are described in detail in this section. Device nodes defined -by DTSpec (see Chapter 3, {\hyperref[devicenodes:chapter\string-device\string-node\string-requirements]{\crossref{\DUrole{std,std-ref}{3}}}}) may specify +by DTSpec (see Chapter {\hyperref[devicenodes:chapter\string-device\string-node\string-requirements]{\crossref{\DUrole{std,std-ref}{3}}}}) may specify additional requirements or constraints regarding the use of the standard -properties. {\hyperref[device\string-bindings:chapter\string-device\string-bindings]{\crossref{\DUrole{std,std-ref}{4}}}} that describe the representation +properties. Chapter {\hyperref[device\string-bindings:chapter\string-device\string-bindings]{\crossref{\DUrole{std,std-ref}{4}}}} describes the representation of specific devices may also specify additional requirements. \begin{notice}{note}{Note:} @@ -1180,7 +1050,7 @@ \subsection{compatible} express its compatibility with a family of similar devices, potentially allowing a single device driver to match against several devices. -The recommended format is \code{“manufacturer,model”}, where +The recommended format is \code{"manufacturer,model"}, where \code{manufacturer} is a string describing the name of the manufacturer (such as a stock ticker symbol), and \code{model} specifies the model number. @@ -1189,7 +1059,7 @@ \subsection{compatible} Example: \begin{quote} -\code{compatible = “fsl,mpc8641-uart”, “ns16550";} +\code{compatible = "fsl,mpc8641-uart", "ns16550";} In this example, an operating system would first try to locate a device driver that supported fsl,mpc8641-uart. If a driver was not found, it @@ -1218,7 +1088,7 @@ \subsection{model} Example: \begin{quote} -\code{model = “fsl,MPC8349EMITX”;} +\code{model = "fsl,MPC8349EMITX";} \end{quote} @@ -1243,17 +1113,17 @@ \subsection{phandle} See the following devicetree excerpt: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{pic}\PYG{n+nd}{@10000000} \PYG{p}{\PYGZob{}} - \PYG{n}{phandle} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{1}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{controller}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +pic@10000000 \PYGZob{} + phandle = \PYGZlt{}1\PYGZgt{}; + interrupt\PYGZhy{}controller; +\PYGZcb{}; \end{Verbatim} A \emph{phandle} value of 1 is defined. Another device node could reference the pic node with a phandle value of 1: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{parent} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{1}\PYG{o}{\PYGZgt{}}\PYG{p}{;} +interrupt\PYGZhy{}parent = \PYGZlt{}1\PYGZgt{}; \end{Verbatim} \end{quote} @@ -1282,13 +1152,14 @@ \subsection{status} Description: \begin{quote} -The \emph{status} property indicates the operational status of a device. -Valid values are listed and defined in the following table. +The \code{status} property indicates the operational status of a device. +Valid values are listed and defined in \hyperref[devicetree-basics:table-prop-status-values]{Table \ref{devicetree-basics:table-prop-status-values}}. +\end{quote} \begin{threeparttable} -\capstart\caption{Values for status property}\label{devicetree-basics:id8} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{Values for status property}\label{devicetree-basics:table-prop-status-values}\label{devicetree-basics:id8} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Value @@ -1330,7 +1201,6 @@ \subsection{status} \end{threeparttable} -\end{quote} \subsection{\#address-cells and \#size-cells} @@ -1345,9 +1215,9 @@ \subsection{\#address-cells and \#size-cells} The \emph{\#address-cells} and \emph{\#size-cells} properties may be used in any device node that has children in the devicetree hierarchy and describes how child device nodes should be addressed. The \emph{\#address-cells} -property defines the number of \textless{}u32\textgreater{} cells used to encode the address -field in a child node’s \emph{reg} property. The \emph{\#size-cells} property -defines the number of \textless{}u32\textgreater{} cells used to encode the size field in a +property defines the number of \code{\textless{}u32\textgreater{}} cells used to encode the address +field in a child node's \emph{reg} property. The \emph{\#size-cells} property +defines the number of \code{\textless{}u32\textgreater{}} cells used to encode the size field in a child node’s \emph{reg} property. The \emph{\#address-cells} and \emph{\#size-cells} properties are not inherited from @@ -1366,18 +1236,18 @@ \subsection{\#address-cells and \#size-cells} See the following devicetree excerpt: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{soc} \PYG{p}{\PYGZob{}} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - - \PYG{n}{serial} \PYG{p}{\PYGZob{}} - \PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ns16550}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x4600} \PYG{l+m+mh}{0x100}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{clock}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{0}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupts} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0xA} \PYG{l+m+mh}{0x8}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{parent} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{o}{\PYGZam{}}\PYG{n}{ipic}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +soc \PYGZob{} + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + \PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + + serial \PYGZob{} + compatible = \PYGZdq{}ns16550\PYGZdq{}; + reg = \PYGZlt{}0x4600 0x100\PYGZgt{}; + clock\PYGZhy{}frequency = \PYGZlt{}0\PYGZgt{}; + interrupts = \PYGZlt{}0xA 0x8\PYGZgt{}; + interrupt\PYGZhy{}parent = \PYGZlt{}\PYGZam{}ipic\PYGZgt{}; + \PYGZcb{}; +\PYGZcb{}; \end{Verbatim} In this example, the \emph{\#address-cells} and \emph{\#size-cells} properties of the soc node @@ -1495,21 +1365,21 @@ \subsection{ranges} \begin{quote} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{soc} \PYG{p}{\PYGZob{}} - \PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{simple\PYGZhy{}bus}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}size\PYGZhy{}cells\PYGZus{} = \PYGZlt{}1\PYGZgt{};} - \PYG{n}{ranges} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x0} \PYG{l+m+mh}{0xe0000000} \PYG{l+m+mh}{0x00100000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - - \PYG{n}{serial} \PYG{p}{\PYGZob{}} - \PYG{n}{device\PYGZus{}type} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{serial}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ns16550}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x4600} \PYG{l+m+mh}{0x100}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{clock}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{0}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupts} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0xA} \PYG{l+m+mh}{0x8}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{parent} \PYG{o}{=} \PYG{o}{\PYGZlt{}} \PYG{o}{\PYGZam{}}\PYG{n}{ipic} \PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +soc \PYGZob{} + compatible = \PYGZdq{}simple\PYGZhy{}bus\PYGZdq{}; + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + \PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + ranges = \PYGZlt{}0x0 0xe0000000 0x00100000\PYGZgt{}; + + serial \PYGZob{} + device\PYGZus{}type = \PYGZdq{}serial\PYGZdq{}; + compatible = \PYGZdq{}ns16550\PYGZdq{}; + reg = \PYGZlt{}0x4600 0x100\PYGZgt{}; + clock\PYGZhy{}frequency = \PYGZlt{}0\PYGZgt{}; + interrupts = \PYGZlt{}0xA 0x8\PYGZgt{}; + interrupt\PYGZhy{}parent = \PYGZlt{} \PYGZam{}ipic \PYGZgt{}; + \PYGZcb{}; +\PYGZcb{}; \end{Verbatim} The \code{soc} node specifies a \emph{ranges} property of @@ -1571,8 +1441,8 @@ \subsection{dma-ranges} \end{quote} -\subsection{name} -\label{devicetree-basics:name} +\subsection{name (deprecated)} +\label{devicetree-basics:name-deprecated} Property name: \code{name} Value type: \code{\textless{}string\textgreater{}} @@ -1623,9 +1493,9 @@ \section{Interrupts and Interrupt Mapping} devicetree parent. Each interrupt generating device contains an \emph{interrupts} property with -a value describing one or more interrupt sources for that device—each -source represented with information called an \emph{interrupt specifier}. The -format and meaning of an \emph{interrupt specifier} is interrupt domain +a value describing one or more interrupt sources for that device. Each +source is represented with information called an \emph{interrupt specifier}. +The format and meaning of an \emph{interrupt specifier} is interrupt domain specific, i.e., it is dependent on properties on the node at the root of its interrupt domain. The \emph{\#interrupt-cells} property is used by the root of an interrupt domain to define the number of \code{\textless{}u32\textgreater{}} values @@ -1668,7 +1538,7 @@ \section{Interrupts and Interrupt Mapping} \centering \capstart -\includegraphics{graphviz-e39cfc76de6d5a4bb03961061381981f96280330.pdf} +\includegraphics{graphviz-1d3954672eca688030b49a13a35b6714d9abdcd5.pdf} \caption{Example of the interrupt tree}\label{devicetree-basics:example-interrupt-tree}\label{devicetree-basics:id9}\end{figure} In the example shown in \hyperref[devicetree-basics:example-interrupt-tree]{Fig. \ref{devicetree-basics:example-interrupt-tree}}: @@ -1679,9 +1549,17 @@ \section{Interrupts and Interrupt Mapping} \item {} The interrupt tree root has three children—devices that route their interrupts directly to the \code{open-pic} -* device1 -* PCI host controller -* GPIO Controller +\begin{itemize} +\item {} +device1 + +\item {} +PCI host controller + +\item {} +GPIO Controller + +\end{itemize} \item {} Three interrupt domains exist; one rooted at the \code{open-pic} node, @@ -1889,37 +1767,37 @@ \subsection{Interrupt Mapping Example} \phantomsection\label{devicetree-basics:example-interrupt-mapping} \def\SphinxLiteralBlockLabel{\label{devicetree-basics:example-interrupt-mapping}} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{soc} \PYG{p}{\PYGZob{}} - \PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{simple\PYGZhy{}bus}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - - \PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{p}{\PYGZob{}} - \PYG{n}{clock}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{0}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{controller}\PYG{p}{;} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}0\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}interrupt\PYGZhy{}cells = \PYGZlt{}2\PYGZgt{};} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} - - \PYG{n}{pci} \PYG{p}{\PYGZob{}} - \PYG{c+c1}{\PYGZsh{}interrupt\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}2\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}3\PYGZgt{};} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n+nb}{map}\PYG{o}{\PYGZhy{}}\PYG{n}{mask} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0xf800} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{7}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n+nb}{map} \PYG{o}{=} \PYG{o}{\PYGZlt{}} - \PYG{o}{/}\PYG{o}{*} \PYG{n}{IDSEL} \PYG{l+m+mh}{0x11} \PYG{o}{\PYGZhy{}} \PYG{n}{PCI} \PYG{n}{slot} \PYG{l+m+mi}{1} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x8800} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{1} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{2} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTA} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x8800} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{2} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{3} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTB} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x8800} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{3} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{4} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTC} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x8800} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{4} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{1} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTD} \PYG{o}{*}\PYG{o}{/} - \PYG{o}{/}\PYG{o}{*} \PYG{n}{IDSEL} \PYG{l+m+mh}{0x12} \PYG{o}{\PYGZhy{}} \PYG{n}{PCI} \PYG{n}{slot} \PYG{l+m+mi}{2} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x9000} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{1} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{3} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTA} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x9000} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{2} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{4} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTB} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x9000} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{3} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{1} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTC} \PYG{o}{*}\PYG{o}{/} - \PYG{l+m+mh}{0x9000} \PYG{l+m+mi}{0} \PYG{l+m+mi}{0} \PYG{l+m+mi}{4} \PYG{o}{\PYGZam{}}\PYG{n+nb}{open}\PYG{o}{\PYGZhy{}}\PYG{n}{pic} \PYG{l+m+mi}{2} \PYG{l+m+mi}{1} \PYG{o}{/}\PYG{o}{*} \PYG{n}{INTD} \PYG{o}{*}\PYG{o}{/} - \PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +soc \PYGZob{} + compatible = \PYGZdq{}simple\PYGZhy{}bus\PYGZdq{}; + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + \PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + + open\PYGZhy{}pic \PYGZob{} + clock\PYGZhy{}frequency = \PYGZlt{}0\PYGZgt{}; + interrupt\PYGZhy{}controller; + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}0\PYGZgt{}; + \PYGZsh{}interrupt\PYGZhy{}cells = \PYGZlt{}2\PYGZgt{}; + \PYGZcb{}; + + pci \PYGZob{} + \PYGZsh{}interrupt\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + \PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}2\PYGZgt{}; + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}3\PYGZgt{}; + interrupt\PYGZhy{}map\PYGZhy{}mask = \PYGZlt{}0xf800 0 0 7\PYGZgt{}; + interrupt\PYGZhy{}map = \PYGZlt{} + /* IDSEL 0x11 \PYGZhy{} PCI slot 1 */ + 0x8800 0 0 1 \PYGZam{}open\PYGZhy{}pic 2 1 /* INTA */ + 0x8800 0 0 2 \PYGZam{}open\PYGZhy{}pic 3 1 /* INTB */ + 0x8800 0 0 3 \PYGZam{}open\PYGZhy{}pic 4 1 /* INTC */ + 0x8800 0 0 4 \PYGZam{}open\PYGZhy{}pic 1 1 /* INTD */ + /* IDSEL 0x12 \PYGZhy{} PCI slot 2 */ + 0x9000 0 0 1 \PYGZam{}open\PYGZhy{}pic 3 1 /* INTA */ + 0x9000 0 0 2 \PYGZam{}open\PYGZhy{}pic 4 1 /* INTB */ + 0x9000 0 0 3 \PYGZam{}open\PYGZhy{}pic 1 1 /* INTC */ + 0x9000 0 0 4 \PYGZam{}open\PYGZhy{}pic 2 1 /* INTD */ + \PYGZgt{}; + \PYGZcb{}; +\PYGZcb{}; \end{Verbatim} \let\SphinxLiteralBlockLabel\empty @@ -1938,7 +1816,8 @@ \subsection{Interrupt Mapping Example} \item[] child unit address: \code{0x8800 0 0} \item[] child interrupt specifier: \code{1} \item[] interrupt parent: \code{\&open-pic} -\item[] parent unit address: (empty because \code{\#address-cells = \textbackslash{}\textless{}0\textbackslash{}\textgreater{}} in the open-pic node) +\item[] parent unit address: (empty because \code{\#address-cells = \textless{}0\textgreater{}} in the +open-pic node) \item[] parent interrupt specifier: \code{2 1} \end{DUlineblock} \begin{itemize} @@ -1967,10 +1846,10 @@ \subsection{Interrupt Mapping Example} \item {} The parent has no unit address because the parent interrupt domain -(the open-pic node) has an \emph{\#address-cells} value of 0. +(the open-pic node) has an \emph{\#address-cells} value of \code{\textless{}0\textgreater{}}. \item {} -The parent interrupt specifier is \textless{}2 1\textgreater{}. The number of cells to +The parent interrupt specifier is \code{\textless{}2 1\textgreater{}}. The number of cells to represent the interrupt specifier (two cells) is determined by the \emph{\#interrupt-cells} property on the interrupt parent, the open-pic node. @@ -1980,7 +1859,7 @@ \subsection{Interrupt Mapping Example} the Open PIC interrupt controller (see section {\hyperref[device\string-bindings:sect\string-bindings\string-simple\string-bus]{\crossref{\DUrole{std,std-ref}{4.5}}}}). The value \code{\textless{}2\textgreater{}} specifies the physical interrupt source number on the interrupt controller to -which INTA is wired. The value \textless{}1\textgreater{} specifies the level/sense +which INTA is wired. The value \code{\textless{}1\textgreater{}} specifies the level/sense encoding. \end{itemize} @@ -1989,8 +1868,8 @@ \subsection{Interrupt Mapping Example} \end{itemize} -In this example, the interrupt-map-mask property has a value of \textless{}0xf800 -0 0 7\textgreater{}. This mask is applied to a child unit interrupt specifier before +In this example, the interrupt-map-mask property has a value of \code{\textless{}0xf800 +0 0 7\textgreater{}}. This mask is applied to a child unit interrupt specifier before performing a lookup in the interruptmap table. To perform a lookup of the open-pic interrupt source number for INTB for @@ -2028,10 +1907,10 @@ \chapter{Device Node Requirements} \section{Base Device Node Types} \label{devicenodes:base-device-node-types} The sections that follow specify the requirements for the base set of -device nodes required in an DTSpec-compliant device tree. +device nodes required in an DTSpec-compliant devicetree. -All device trees shall have a root node and the following nodes shall be -present at the root of all device trees: +All devicetrees shall have a root node and the following nodes shall be +present at the root of all devicetrees: \begin{itemize} \item {} One \code{/cpus} node @@ -2044,13 +1923,13 @@ \section{Base Device Node Types} \section{Root node} \label{devicenodes:root-node} -The device tree has a single root node of which all other device nodes +The devicetree has a single root node of which all other device nodes are descendants. The full path to the root node is \code{/}. \begin{threeparttable} \capstart\caption{Root Node Properties}\label{devicenodes:id2} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -2129,13 +2008,13 @@ \section{Root node} \section{\texttt{/aliases} node} \label{devicenodes:aliases-node} -A device tree may have an aliases node (\code{/aliases}) that defines one or -more alias properties. The alias node shall be at the root of the device -tree and have the node name \code{/aliases}. +A devicetree may have an aliases node (\code{/aliases}) that defines one or +more alias properties. The alias node shall be at the root of the devicetree +and have the node name \code{/aliases}. Each property of the \code{/aliases} node defines an alias. The property name specifies the alias name. The property value specifies the full path to -a node in the device tree. For example, the property serial0 = +a node in the devicetree. For example, the property serial0 = \code{"/simple-bus@fe000000/serial@llc500"} defines the alias serial0. Alias names shall be a lowercase text strings of 1 to 31 characters from @@ -2144,7 +2023,7 @@ \section{\texttt{/aliases} node} \begin{threeparttable} \capstart\caption{Valid characters for alias names}\label{devicenodes:id3} -\begin{tabulary}{\linewidth}{c p{8cm}} +\begin{tabulary}{\linewidth}{| c p{8cm} |} \hline \textsf{\relax Character @@ -2182,10 +2061,10 @@ \section{\texttt{/aliases} node} \textbf{Example} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{aliases} \PYG{p}{\PYGZob{}} - \PYG{n}{serial0} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{/simple\PYGZhy{}bus@fe000000/serial@llc500}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{ethernet0} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{/simple\PYGZhy{}bus@fe000000/ethernet@31c000}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} +aliases \PYGZob{} + serial0 = \PYGZdq{}/simple\PYGZhy{}bus@fe000000/serial@llc500\PYGZdq{}; + ethernet0 = \PYGZdq{}/simple\PYGZhy{}bus@fe000000/ethernet@31c000\PYGZdq{}; +\PYGZcb{} \end{Verbatim} Given the alias serial0, a client program can look at the aliases node @@ -2195,7 +2074,7 @@ \section{\texttt{/aliases} node} \section{\texttt{/memory} node} \label{devicenodes:memory-node} -A memory device node is required for all device trees and describes the +A memory device node is required for all devicetrees and describes the physical memory layout for the system. If a system has multiple ranges of memory, multiple memory nodes can be created, or the ranges can be specified in the \emph{reg} property of a single memory node. @@ -2215,10 +2094,16 @@ \section{\texttt{/memory} node} memory reservations) as WIMG = 0b001x. That is: \begin{itemize} \item {} -not Write Through Required not Caching Inhibited Memory Coherence +not Write Through Required \item {} -Required either not Guarded or Guarded (i.e., WIMG = 0b001x) +not Caching Inhibited + +\item {} +Memory Coherence + +\item {} +Required either not Guarded or Guarded \end{itemize} @@ -2227,7 +2112,7 @@ \section{\texttt{/memory} node} \begin{threeparttable} \capstart\caption{\texttt{/memory} Node Properties}\label{devicenodes:id4} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -2287,7 +2172,7 @@ \section{\texttt{/memory} node} {\hyperref[devicetree\string-basics:sect\string-standard\string-properties]{\crossref{\DUrole{std,std-ref}{2.3}}}}) are allowed but are optional. \end{notice} -\textbf{Example} +\textbf{Examples} Given a 64-bit Power system with the following physical memory layout: \begin{itemize} @@ -2299,30 +2184,30 @@ \section{\texttt{/memory} node} \end{itemize} -Memory nodes could be defined as follows, assuming an \code{\#address-cells} == 2 -and \code{\#size-cells} == 2: +Memory nodes could be defined as follows, assuming \code{\#address-cells = \textless{}2\textgreater{}} +and \code{\#size-cells = \textless{}2\textgreater{}}. \textbf{Example \#1} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{memory}\PYG{n+nd}{@0} \PYG{p}{\PYGZob{}} - \PYG{n}{device\PYGZus{}type} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{memory}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x000000000} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x80000000} - \PYG{l+m+mh}{0x000000001} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x00000001} \PYG{l+m+mh}{0x00000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +memory@0 \PYGZob{} + device\PYGZus{}type = \PYGZdq{}memory\PYGZdq{}; + reg = \PYGZlt{}0x000000000 0x00000000 0x00000000 0x80000000 + 0x000000001 0x00000000 0x00000001 0x00000000\PYGZgt{}; +\PYGZcb{}; \end{Verbatim} \textbf{Example \#2} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{memory}\PYG{n+nd}{@0} \PYG{p}{\PYGZob{}} - \PYG{n}{device\PYGZus{}type} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{memory}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x000000000} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x80000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} -\PYG{n}{memory}\PYG{n+nd}{@100000000} \PYG{p}{\PYGZob{}} - \PYG{n}{device\PYGZus{}type} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{memory}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x000000001} \PYG{l+m+mh}{0x00000000} \PYG{l+m+mh}{0x00000001} \PYG{l+m+mh}{0x00000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +memory@0 \PYGZob{} + device\PYGZus{}type = \PYGZdq{}memory\PYGZdq{}; + reg = \PYGZlt{}0x000000000 0x00000000 0x00000000 0x80000000\PYGZgt{}; +\PYGZcb{}; +memory@100000000 \PYGZob{} + device\PYGZus{}type = \PYGZdq{}memory\PYGZdq{}; + reg = \PYGZlt{}0x000000001 0x00000000 0x00000001 0x00000000\PYGZgt{}; +\PYGZcb{}; \end{Verbatim} The \code{reg} property is used to define the address and size of the two @@ -2338,12 +2223,10 @@ \section{\texttt{/chosen} Node} describes parameters chosen or specified by the system firmware at run time. It shall be a child of the root node. -The node name (see {\hyperref[devicetree\string-basics:sect\string-node\string-names]{\crossref{\DUrole{std,std-ref}{2.2.1}}}}) shall be \code{/chosen}. - \begin{threeparttable} \capstart\caption{\texttt{/chosen} Node Properties}\label{devicenodes:id5} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -2411,12 +2294,12 @@ \section{\texttt{/chosen} Node} \textbf{Example} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{chosen} \PYG{p}{\PYGZob{}} - \PYG{n}{bootargs} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +chosen \PYGZob{} + bootargs = \PYGZdq{}root=/dev/nfs rw nfsroot=192.168.1.1 console=ttyS0,115200\PYGZdq{}; +\PYGZcb{}; \end{Verbatim} -Older versions of device trees may be encountered that contain a +Older versions of devicetrees may be encountered that contain a deprecated form of the stdout-path property called linux,stdout-path. For compatibility, a client program might want to support linux,stdout-path if a stdout-path property is not present. The meaning @@ -2425,16 +2308,14 @@ \section{\texttt{/chosen} Node} \section{\texttt{/cpus} Node Properties} \label{devicenodes:cpus-node-properties} -A cpus node is required for all device trees. It does not represent a +A cpus node is required for all devicetrees. It does not represent a real device in the system, but acts as a container for child cpu nodes which represent the systems CPUs. -The node name (see {\hyperref[devicetree\string-basics:sect\string-node\string-names]{\crossref{\DUrole{std,std-ref}{2.2.1}}}}) shall be cpus. - \begin{threeparttable} \capstart\caption{\texttt{/cpus} Node Properties}\label{devicenodes:id6} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -2507,8 +2388,7 @@ \section{\texttt{/cpus/cpu*} Node Properties} at the parent cpus node. This results in a less verbose representation of properties which are identical across all CPUs. -The node name for every cpu node (see {\hyperref[devicetree\string-basics:sect\string-node\string-names]{\crossref{\DUrole{std,std-ref}{2.2.1}}}}) should be -cpu. +The node name for every cpu node should be \code{cpu}. \subsection{General Properties of \texttt{/cpus/cpu*} nodes} @@ -2517,7 +2397,7 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} of the properties described in \hyperref[devicenodes:table-cpu-node-props]{Table \ref{devicenodes:table-cpu-node-props}} are select standard properties with specific applicable detail. -\begin{longtable}{p{2.5cm} p{1cm} p{2cm} p{9.5cm}} +\begin{longtable}{| p{1.5cm} p{1cm} p{2.5cm} p{9.0cm} |} \caption{\texttt{/cpus/cpu*} Node General Properties}\label{devicenodes:table-cpu-node-props}\\ \hline \textsf{\relax @@ -2553,11 +2433,15 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \code{device\_type} & -R +\begin{DUlineblock}{0em} +\item[] R +\end{DUlineblock} & -\code{\textless{}string\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}string\textgreater{}} +\end{DUlineblock} & -Value shall be ``cpu''. +Value shall be \code{"cpu"}. \\ \hline \code{reg} @@ -2566,31 +2450,31 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} & array & -The value of \code{reg} is a \code{\textless{}prop-encoded-array\textgreater{}} +The value of \emph{reg} is a \code{\textless{}prop-encoded-array\textgreater{}} that defines a unique CPU/thread id for the CPU/threads represented by the CPU node. If a CPU supports more than one thread (i.e. -multiple streams of execution) the \code{reg} +multiple streams of execution) the \emph{reg} property is an array with 1 element per -thread. The \code{\#address-cells} on the \code{/cpus} node +thread. The \emph{\#address-cells} on the \code{/cpus} node specifies how many cells each element of the array takes. Software can determine the number -of threads by dividing the size of \code{reg} by -the parent node’s \code{\#address-cells}. +of threads by dividing the size of \emph{reg} by +the parent node's \emph{\#address-cells}. If a CPU/thread can be the target of an -external interrupt the ``reg'' property value +external interrupt the \emph{reg} property value must be a unique CPU/thread id that is addressable by the interrupt controller. If a CPU/thread cannot be the target of an -external interrupt, then ``reg'' must be unique +external interrupt, then \emph{reg} must be unique and out of bounds of the range addressed by the interrupt controller -If a CPU/thread’s PIR is modifiable, a client -program should modify PIR to match the ``reg'' +If a CPU/thread's PIR is modifiable, a client +program should modify PIR to match the \emph{reg} property value. If PIR cannot be modified and the PIR value is distinct from the interrupt controller numberspace, the CPUs binding may @@ -2601,41 +2485,51 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \code{clock-frequency} & \begin{DUlineblock}{0em} -\item[] \item[] R \end{DUlineblock} & -array +\begin{DUlineblock}{0em} +\item[] array +\end{DUlineblock} & Specifies the current clock speed of the CPU -in Hertz. The value is a \textless{}prop-encoded-array\textgreater{} +in Hertz. The value is a \code{\textless{}prop-encoded-array\textgreater{}} in one of two forms: - +\begin{itemize} +\item {} A 32-bit integer consisting of one \code{\textless{}u32\textgreater{}} specifying the frequency. +\item {} A 64-bit integer represented as a \code{\textless{}u64\textgreater{}} specifying the frequency. + +\end{itemize} \\ \hline \code{timebase-frequency} & \begin{DUlineblock}{0em} -\item[] \item[] R \end{DUlineblock} & -array +\begin{DUlineblock}{0em} +\item[] array +\end{DUlineblock} & Specifies the current frequency at which the timebase and decrementer registers are updated (in Hertz). The value is a \textless{}prop-encoded-array\textgreater{} in one of two forms: - +\begin{itemize} +\item {} A 32-bit integer consisting of one \code{\textless{}u32\textgreater{}} specifying the frequency. +\item {} A 64-bit integer represented as a \code{\textless{}u64\textgreater{}}. + +\end{itemize} \\ \hline \code{status} @@ -2648,12 +2542,16 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} CPU. This property shall be present for nodes representing CPUs in a symmetric multiprocessing (SMP) configuration. For a CPU -node the meaning of the “okay” and “disabled” -values are as follows: +node the meaning of the \code{"okay"} and +\code{"disabled"} values are as follows: +\begin{description} +\item[{\code{"okay"} :}] \leavevmode +The CPU is running. -\code{"okay"}. The CPU is running. +\item[{\code{"disabled"} :}] \leavevmode +The CPU is in a quiescent state. -\code{"disabled"}. The CPU is in a quiescent state. +\end{description} A quiescent CPU is in a state where it cannot interfere with the normal operation of other @@ -2675,49 +2573,59 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \hline \code{enable-method} & -SD +\begin{DUlineblock}{0em} +\item[] SD +\end{DUlineblock} & -\code{\textless{}stringlist\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}stringlist\textgreater{}} +\end{DUlineblock} & Describes the method by which a CPU in a disabled state is enabled. This property is required for CPUs with a status property with -a value of “disabled”. The value consists of +a value of \code{"disabled"}. The value consists of one or more strings that define the method to release this CPU. If a client program recognizes any of the methods, it may use it. The value shall be one of the following: - -``spin-table'' The CPU is enabled with the +\begin{description} +\item[{\code{"spin-table"} :}] \leavevmode +The CPU is enabled with the spin table method defined in the DTSpec. -\code{"{[}vendor{]},{[}method{]}"} An -implementation-dependent string that +\item[{\code{"{[}vendor{]},{[}method{]}"} :}] \leavevmode +Implementation dependent string that describes the method by which a CPU is -released from a ``disabled'' state. The -required format is: ``vendor,method'' where -vendor is a string describing the name of +released from a \code{"disabled"} state. The +required format is: \code{"{[}vendor{]},{[}method{]}"}, +where vendor is a string describing the name of the manufacturer and method is a string describing the vendorspecific mechanism. +\end{description} + Example: \code{"fsl,MPC8572DS"} -Note: Other methods may be added to later +\begin{notice}{note}{Note:} +Other methods may be added to later revisions of the DTSpec specification. +\end{notice} \\ \hline \code{cpu-release-addr} & \begin{DUlineblock}{0em} -\item[] \item[] SD \end{DUlineblock} & -\code{\textless{}u64\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}u64\textgreater{}} +\end{DUlineblock} & The cpu-release-addr property is required for cpu nodes that have an enable-method property -value of ``spin-table''. The value specifies the +value of \code{"spin-table"}. The value specifies the physical address of a spin table entry that releases a secondary CPU from its spin loop. \\ @@ -2732,7 +2640,7 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} {\hyperref[devicetree\string-basics:sect\string-standard\string-properties]{\crossref{\DUrole{std,std-ref}{2.3}}}}) are allowed but are optional. \end{notice} -\begin{longtable}{p{2.5cm} p{1cm} p{2cm} p{9.5cm}} +\begin{longtable}{| p{1.5cm} p{1cm} p{2.5cm} p{9.0cm} |} \caption{\texttt{/cpus/cpu*} Node Power ISA Properties}\\ \hline \textsf{\relax @@ -2769,37 +2677,42 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \code{power-isa-version} & \begin{DUlineblock}{0em} -\item[] \item[] O \end{DUlineblock} & -\code{\textless{}string\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}string\textgreater{}} +\end{DUlineblock} & A string that specifies the numerical portion of the Power ISA version string. For example, for an implementation complying with Power ISA Version 2.06, the value of this property would -be ``2.06''. +be \code{"2.06"}. \\ \hline \code{power-isa-*} & -O +\begin{DUlineblock}{0em} +\item[] O +\end{DUlineblock} & -\code{\textless{}empty\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}empty\textgreater{}} +\end{DUlineblock} & -If the power-isa-version property exists, then +If the \code{power-isa-version} property exists, then for each category from the Categories section of Book I of the Power ISA version indicated, the existence of a property named -power-isa-{[}CAT{]}, where {[}CAT{]} is the +\code{power-isa-{[}CAT{]}}, where \code{{[}CAT{]}} is the abbreviated category name with all uppercase letters converted to lowercase, indicates that the category is supported by the implementation. For example, if the power-isa-version property -exists and its value is ``2.06'' and the +exists and its value is \code{"2.06"} and the power-isa-e.hv property exists, then the implementation supports {[}Category:Embedded.Hypervisor{]} as defined in @@ -2809,11 +2722,12 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \code{cache-op-block-size} & \begin{DUlineblock}{0em} -\item[] \item[] SD \end{DUlineblock} & -\code{\textless{}u32\textgreater{}} +\begin{DUlineblock}{0em} +\item[] \code{\textless{}u32\textgreater{}} +\end{DUlineblock} & Specifies the block size in bytes upon which cache block instructions operate (e.g., dcbz). @@ -2824,12 +2738,10 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} \code{reservation-granule-size} & \begin{DUlineblock}{0em} -\item[] \item[] SD \end{DUlineblock} & \begin{DUlineblock}{0em} -\item[] \item[] \code{\textless{}u32\textgreater{}} \end{DUlineblock} & @@ -2846,16 +2758,35 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} Specifies the CPU’s MMU type. Valid values are shown below: +\begin{itemize} +\item {} +\code{"mpc8xx"} + +\item {} +\code{"ppc40x"} + +\item {} +\code{"ppc440"} + +\item {} +\code{"ppc476"} + +\item {} +\code{"power-embedded"} -``mpc8xx'' -``ppc40x'' -``ppc440'' -``ppc476'' -``power-embedded'' -``powerpc-classic'' -``power-server-stab'' -``power-server-slb'' -``none'' +\item {} +\code{"powerpc-classic"} + +\item {} +\code{"power-server-stab"} + +\item {} +\code{"power-server-slb"} + +\item {} +\code{"none"} + +\end{itemize} \\ \hline \multicolumn{4}{|l|}{ Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition @@ -2868,7 +2799,7 @@ \subsection{General Properties of \texttt{/cpus/cpu*} nodes} {\hyperref[devicetree\string-basics:sect\string-standard\string-properties]{\crossref{\DUrole{std,std-ref}{2.3}}}}) are allowed but are optional. \end{notice} -Older versions of device trees may be encountered that contain a +Older versions of devicetree may be encountered that contain a bus-frequency property on CPU nodes. For compatibility, a client-program might want to support bus-frequency. The format of the value is identical to that of clock-frequency. The recommended practice is to @@ -2884,7 +2815,7 @@ \subsection{TLB Properties} \begin{threeparttable} \capstart\caption{\texttt{/cpu/cpu*} Node Power ISA TLB Properties}\label{devicenodes:id9} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -2997,7 +2928,7 @@ \subsection{Internal (L1) Cache Properties} \begin{threeparttable} \capstart\caption{\texttt{/cpu/cpu*} Node Power ISA Cache Properties}\label{devicenodes:id10} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -3017,7 +2948,7 @@ \subsection{Internal (L1) Cache Properties} & If present, specifies the cache has a unified organization. If not present, specifies that -the cache has a Harvard architecture \code{with} +the cache has a Harvard architecture with separate caches for instructions and data. \\ \hline @@ -3028,7 +2959,7 @@ \subsection{Internal (L1) Cache Properties} \code{\textless{}u32\textgreater{}} & Specifies the size in bytes of a unified -cache. Required if the cache is \code{unified} +cache. Required if the cache is unified (combined instructions and data). \\ \hline @@ -3039,7 +2970,7 @@ \subsection{Internal (L1) Cache Properties} \code{\textless{}u32\textgreater{}} & Specifies the number of associativity sets in -a unified cache. Required if the cache \code{is} +a unified cache. Required if the cache is unified (combined instructions and data) \\ \hline @@ -3073,7 +3004,7 @@ \subsection{Internal (L1) Cache Properties} \code{\textless{}u32\textgreater{}} & Specifies the size in bytes of the instruction -cache. Required if the cpu has a \code{separate} +cache. Required if the cpu has a separate cache for instructions. \\ \hline @@ -3129,7 +3060,7 @@ \subsection{Internal (L1) Cache Properties} \code{\textless{}u32\textgreater{}} & Specifies the number of associativity sets in -the data cache. Required if the cpu has \code{a} +the data cache. Required if the cpu has a separate cache for data. \\ \hline @@ -3140,7 +3071,7 @@ \subsection{Internal (L1) Cache Properties} \code{\textless{}u32\textgreater{}} & Specifies the block size in bytes of the data -cache. Required if the cpu has a \code{separate} +cache. Required if the cpu has a separate cache for data. \\ \hline @@ -3180,43 +3111,43 @@ \subsection{Internal (L1) Cache Properties} {\hyperref[devicetree\string-basics:sect\string-standard\string-properties]{\crossref{\DUrole{std,std-ref}{2.3}}}}) are allowed but are optional. \end{notice} -Older versions of device trees may be encountered that contain a -deprecated form of the next-level-cache property called l2-cache. For -compatibility, a client-program may wish to support l2-cache if a -next-level-cache property is not present. The meaning and use of the two -properties is identical. +Older versions of devicetrees may be encountered that contain a +deprecated form of the next-level-cache property called \code{l2-cache}. +For compatibility, a client-program may wish to support \code{l2-cache} +if a next-level-cache property is not present. +The meaning and use of the two properties is identical. \subsection{Example} \label{devicenodes:sect-cpu-node-example}\label{devicenodes:example} -Here is an example of a cpus node with one child cpu node: +Here is an example of a \code{/cpus} node with one child cpu node: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{cpus} \PYG{p}{\PYGZob{}} - \PYG{c+c1}{\PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{};} - \PYG{c+c1}{\PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}0\PYGZgt{};} - \PYG{n}{cpu}\PYG{n+nd}{@0} \PYG{p}{\PYGZob{}} - \PYG{n}{device\PYGZus{}type} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{cpu}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} - \PYG{n}{reg} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{0}\PYG{o}{\PYGZgt{}}\PYG{p}{;} - \PYG{n}{d}\PYG{o}{\PYGZhy{}}\PYG{n}{cache}\PYG{o}{\PYGZhy{}}\PYG{n}{block}\PYG{o}{\PYGZhy{}}\PYG{n}{size} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{32}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{n}{L1} \PYG{o}{\PYGZhy{}} \PYG{l+m+mi}{32} \PYG{n+nb}{bytes} - \PYG{n}{i}\PYG{o}{\PYGZhy{}}\PYG{n}{cache}\PYG{o}{\PYGZhy{}}\PYG{n}{block}\PYG{o}{\PYGZhy{}}\PYG{n}{size} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{32}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{n}{L1} \PYG{o}{\PYGZhy{}} \PYG{l+m+mi}{32} \PYG{n+nb}{bytes} - \PYG{n}{d}\PYG{o}{\PYGZhy{}}\PYG{n}{cache}\PYG{o}{\PYGZhy{}}\PYG{n}{size} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x8000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{n}{L1}\PYG{p}{,} \PYG{l+m+mi}{32}\PYG{n}{K} - \PYG{n}{i}\PYG{o}{\PYGZhy{}}\PYG{n}{cache}\PYG{o}{\PYGZhy{}}\PYG{n}{size} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x8000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{n}{L1}\PYG{p}{,} \PYG{l+m+mi}{32}\PYG{n}{K} - \PYG{n}{timebase}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{82500000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{l+m+mf}{82.5} \PYG{n}{MHz} - \PYG{n}{clock}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{825000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} \PYG{o}{/}\PYG{o}{/} \PYG{l+m+mi}{825} \PYG{n}{MHz} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +cpus \PYGZob{} + \PYGZsh{}address\PYGZhy{}cells = \PYGZlt{}1\PYGZgt{}; + \PYGZsh{}size\PYGZhy{}cells = \PYGZlt{}0\PYGZgt{}; + cpu@0 \PYGZob{} + device\PYGZus{}type = \PYGZdq{}cpu\PYGZdq{}; + reg = \PYGZlt{}0\PYGZgt{}; + d\PYGZhy{}cache\PYGZhy{}block\PYGZhy{}size = \PYGZlt{}32\PYGZgt{}; // L1 \PYGZhy{} 32 bytes + i\PYGZhy{}cache\PYGZhy{}block\PYGZhy{}size = \PYGZlt{}32\PYGZgt{}; // L1 \PYGZhy{} 32 bytes + d\PYGZhy{}cache\PYGZhy{}size = \PYGZlt{}0x8000\PYGZgt{}; // L1, 32K + i\PYGZhy{}cache\PYGZhy{}size = \PYGZlt{}0x8000\PYGZgt{}; // L1, 32K + timebase\PYGZhy{}frequency = \PYGZlt{}82500000\PYGZgt{}; // 82.5 MHz + clock\PYGZhy{}frequency = \PYGZlt{}825000000\PYGZgt{}; // 825 MHz + \PYGZcb{}; +\PYGZcb{}; \end{Verbatim} \section{Multi-level and Shared Cache Nodes (\texttt{/cpus/cpu*/l?-cache})} \label{devicenodes:multi-level-and-shared-cache-nodes-cpus-cpu-l-cache} -Processors and systems may implement additional levels of cache -hierarchy—for example, secondlevel (L2) or third-level (L3) caches. +Processors and systems may implement additional levels of cache hierarchy. +For example, second-level (L2) or third-level (L3) caches. These caches can potentially be tightly integrated to the CPU or possibly shared between multiple CPUs. -A device node with a compatible value of ``cache'' describes these types +A device node with a compatible value of \code{"cache"} describes these types of caches. The cache node shall define a phandle property, and all cpu nodes or @@ -3225,7 +3156,7 @@ \section{Multi-level and Shared Cache Nodes (\texttt{/cpus/cpu*/l?-cache})} cache node. A cache node may be represented under a CPU node or any other -appropriate location in the device tree. +appropriate location in the devicetree. Multiple-level and shared caches are represented with the properties in Table 3-9. The L1 cache properties are described in Table 3-8. @@ -3233,7 +3164,7 @@ \section{Multi-level and Shared Cache Nodes (\texttt{/cpus/cpu*/l?-cache})} \begin{threeparttable} \capstart\caption{\texttt{/cpu/cpu*/l?-cache} Node Power ISA Multiple-level and Shared Cache Properties}\label{devicenodes:id11} -\begin{tabulary}{\linewidth}{l c l J} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -3262,8 +3193,7 @@ \section{Multi-level and Shared Cache Nodes (\texttt{/cpus/cpu*/l?-cache})} \code{\textless{}u32\textgreater{}} & Specifies the level in the cache hierarchy. -For example, a level 2 cache has a value of -2. +For example, a level 2 cache has a value of 2. \\ \hline \multicolumn{4}{|l|}{ Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition @@ -3281,7 +3211,7 @@ \section{Multi-level and Shared Cache Nodes (\texttt{/cpus/cpu*/l?-cache})} \subsection{Example} \label{devicenodes:id1} -See the following example of a device tree representation of two CPUs, +See the following example of a devicetree representation of two CPUs, each with their own on-chip L2 and a shared L3. \begin{Verbatim}[commandchars=\\\{\}] @@ -3298,7 +3228,7 @@ \subsection{Example} next\PYGZhy{}level\PYGZhy{}cache = \PYGZlt{}\PYGZam{}L2\PYGZus{}0\PYGZgt{}; // phandle to L2 L2\PYGZus{}0:l2\PYGZhy{}cache \PYGZob{} - compatible = “cache”; + compatible = \PYGZdq{}cache\PYGZdq{}; cache\PYGZhy{}unified; cache\PYGZhy{}size = \PYGZlt{}0x40000\PYGZgt{}; // 256 KB @@ -3308,7 +3238,7 @@ \subsection{Example} next\PYGZhy{}level\PYGZhy{}cache = \PYGZlt{}\PYGZam{}L3\PYGZgt{}; // phandle to L3 L3:l3\PYGZhy{}cache \PYGZob{} - compatible = “cache”; + compatible = \PYGZdq{}cache\PYGZdq{}; cache\PYGZhy{}unified; cache\PYGZhy{}size = \PYGZlt{}0x40000\PYGZgt{}; // 256 KB cache\PYGZhy{}sets = \PYGZlt{}0x400\PYGZgt{}; // 1024 @@ -3329,7 +3259,7 @@ \subsection{Example} cache\PYGZhy{}level = \PYGZlt{}2\PYGZgt{}; next\PYGZhy{}level\PYGZhy{}cache = \PYGZlt{}\PYGZam{}L2\PYGZus{}1\PYGZgt{}; // phandle to L2 L2\PYGZus{}1:l2\PYGZhy{}cache \PYGZob{} - compatible = “cache”; + compatible = \PYGZdq{}cache\PYGZdq{}; cache\PYGZhy{}unified; cache\PYGZhy{}size = \PYGZlt{}0x40000\PYGZgt{}; // 256 KB cache\PYGZhy{}sets = \PYGZlt{}0x400\PYGZgt{}; // 1024 @@ -3344,7 +3274,7 @@ \subsection{Example} \chapter{Device Bindings} \label{device-bindings::doc}\label{device-bindings:device-bindings}\label{device-bindings:chapter-device-bindings} This chapter contains requirements, known as bindings, for how specific -types and classes of devices are represented in the device tree. The +types and classes of devices are represented in the devicetree. The compatible property of a device node describes the specific binding (or bindings) to which the node complies. @@ -3360,7 +3290,7 @@ \section{Binding Guidelines} \subsection{General Principles} \label{device-bindings:general-principles} -When creating a new device tree representation for a device, a binding +When creating a new devicetree representation for a device, a binding should be created that fully describes the required properties and value of the device. This set of properties shall be sufficiently descriptive to provide device drivers with needed attributes of the device. @@ -3375,7 +3305,7 @@ \subsection{General Principles} Use the standard properties (defined in sections {\hyperref[devicetree\string-basics:sect\string-standard\string-properties]{\crossref{\DUrole{std,std-ref}{2.3}}}} and {\hyperref[devicetree\string-basics:sect\string-interrupts]{\crossref{\DUrole{std,std-ref}{2.4}}}}) as applicable for the new device. This usage typically includes the -\code{reg} and interrupts properties at a minimum. +\code{reg} and \code{interrupts} properties at a minimum. \item {} Use the conventions specified in section {\hyperref[device\string-bindings:chapter\string-device\string-bindings]{\crossref{\DUrole{std,std-ref}{4}}}} @@ -3408,8 +3338,8 @@ \subsubsection{\texttt{clock-frequency} Property} \label{device-bindings:clock-frequency-property} \begin{threeparttable} -\capstart\caption{\texttt{clock-frequency} Property}\label{device-bindings:id2} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{clock-frequency} Property}\label{device-bindings:id3} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3443,8 +3373,8 @@ \subsubsection{\texttt{reg-shift} Property} \label{device-bindings:reg-shift-property} \begin{threeparttable} -\capstart\caption{\texttt{reg-shift} Property}\label{device-bindings:id3} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{reg-shift} Property}\label{device-bindings:id4} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3464,7 +3394,7 @@ \subsubsection{\texttt{reg-shift} Property} number of bytes between registers. The \code{reg-shift} property specifies in bytes how far the discrete device registers are separated from each other. The individual register location -is calculated by using following formula: “registers address” +is calculated by using following formula: ``registers address'' \textless{}\textless{} reg-shift. If unspecified, the default value is 0. For example, in a system where 16540 UART registers are @@ -3482,8 +3412,8 @@ \subsubsection{\texttt{label} Property} \label{device-bindings:label-property} \begin{threeparttable} -\capstart\caption{\texttt{label} Property}\label{device-bindings:id4} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{label} Property}\label{device-bindings:id5} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3527,8 +3457,8 @@ \subsubsection{\texttt{clock-frequency} Property} \label{device-bindings:id1} \begin{threeparttable} -\capstart\caption{\texttt{clock-frequecy} Property}\label{device-bindings:id5} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{clock-frequecy} Property}\label{device-bindings:id6} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3561,7 +3491,7 @@ \subsubsection{\texttt{current-speed} Property} \label{device-bindings:current-speed-property} \begin{threeparttable} -\capstart\caption{\texttt{current-speed} Property}\label{device-bindings:id6} +\capstart\caption{\texttt{current-speed} Property}\label{device-bindings:id7} \begin{tabulary}{\linewidth}{l J} \hline \textsf{\relax @@ -3596,11 +3526,11 @@ \subsection{National Semiconductor 16450/16550 Compatible UART Requirements} \label{device-bindings:national-semiconductor-16450-16550-compatible-uart-requirements} Serial devices compatible to the National Semiconductor 16450/16550 UART (Universal Asynchronous Receiver Transmitter) should be represented in -the device tree using following properties. +the devicetree using following properties. \begin{threeparttable} -\capstart\caption{ns16550 UART Properties}\label{device-bindings:id7} +\capstart\caption{ns16550 UART Properties}\label{device-bindings:id8} \begin{tabulary}{\linewidth}{l c l J} \hline \textsf{\relax @@ -3619,7 +3549,7 @@ \subsection{National Semiconductor 16450/16550 Compatible UART Requirements} & \textless{}string list\textgreater{} & -Value shall include “ns16550”. +Value shall include ``ns16550''. \\ \hline \code{clock-frequency} @@ -3727,8 +3657,8 @@ \subsubsection{\texttt{address-bits} Property} \label{device-bindings:address-bits-property} \begin{threeparttable} -\capstart\caption{\texttt{address-bits} Property}\label{device-bindings:id8} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{address-bits} Property}\label{device-bindings:id9} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3762,8 +3692,8 @@ \subsubsection{\texttt{local-mac-address} Property} \label{device-bindings:local-mac-address-property} \begin{threeparttable} -\capstart\caption{\texttt{local-mac-address} Property}\label{device-bindings:id9} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{local-mac-address} Property}\label{device-bindings:id10} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3796,8 +3726,8 @@ \subsubsection{\texttt{mac-address} Property} \label{device-bindings:mac-address-property} \begin{threeparttable} -\capstart\caption{\texttt{mac-address} Property}\label{device-bindings:id10} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{mac-address} Property}\label{device-bindings:id11} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3834,8 +3764,8 @@ \subsubsection{\texttt{max-frame-size} Property} \label{device-bindings:max-frame-size-property} \begin{threeparttable} -\capstart\caption{\texttt{max-frame-size} Property}\label{device-bindings:id11} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{max-frame-size} Property}\label{device-bindings:id12} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3867,8 +3797,8 @@ \subsubsection{\texttt{max-frame-size} Property} \subsection{Ethernet specific considerations} \label{device-bindings:ethernet-specific-considerations} Network devices based on the IEEE 802.3 collections of LAN standards -(collectively referred to as Ethernet) may be represented in the device -tree using following properties, in addition to properties specified of +(collectively referred to as Ethernet) may be represented in the devicetree +using following properties, in addition to properties specified of the network device class. The properties listed in this section augment the properties listed in @@ -3879,8 +3809,8 @@ \subsubsection{\texttt{max-speed} Property} \label{device-bindings:max-speed-property} \begin{threeparttable} -\capstart\caption{\texttt{max-speed} Property}\label{device-bindings:id12} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{max-speed} Property}\label{device-bindings:id13} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -3913,13 +3843,13 @@ \subsubsection{\texttt{phy-connection-type} Property} \label{device-bindings:phy-connection-type-property} \begin{threeparttable} -\capstart\caption{\texttt{max-speed} Property}\label{device-bindings:id13} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{phy-connection-type} Property}\label{device-bindings:id14} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property } & \textsf{\relax -\code{max-speed} +\code{phy-connection-type} }\\ \hline Value type @@ -3938,7 +3868,7 @@ \subsubsection{\texttt{phy-connection-type} Property} \hline Example & -\code{phy-connection-type = “mii”;} +\code{phy-connection-type = "mii";} \\ \hline\end{tabulary} @@ -3947,8 +3877,8 @@ \subsubsection{\texttt{phy-connection-type} Property} \begin{threeparttable} -\capstart\caption{Defined values for the \texttt{max-speed} Property}\label{device-bindings:id14} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{Defined values for the \texttt{phy-connection-type} Property}\label{device-bindings:id15} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Connection type @@ -3968,7 +3898,7 @@ \subsubsection{\texttt{phy-connection-type} Property} \hline Gigabit Media Independent Interface & -\code{rgmii} +\code{gmii} \\ \hline Reduced Gigabit Media Independent @@ -4005,6 +3935,31 @@ \subsubsection{\texttt{phy-connection-type} Property} & \code{smii} \\ +\hline +Serial Gigabit Media Independent Interface + & +\code{sgmii} +\\ +\hline +Reverse Media Independent Interface + & +\code{rev-mii} +\\ +\hline +10 Gigabits Media Independent Interface + & +\code{xgmii} +\\ +\hline +Multimedia over Coaxial + & +\code{moca} +\\ +\hline +Quad Serial Gigabit Media Independent Interface + & +\code{qsgmii} +\\ \hline\end{tabulary} \end{threeparttable} @@ -4015,8 +3970,8 @@ \subsubsection{\texttt{phy-handle} Property} \label{device-bindings:phy-handle-property} \begin{threeparttable} -\capstart\caption{\texttt{phy-handle} Property}\label{device-bindings:id15} -\begin{tabulary}{\linewidth}{l J} +\capstart\caption{\texttt{phy-handle} Property}\label{device-bindings:id16} +\begin{tabulary}{\linewidth}{| l J |} \hline \textsf{\relax Property @@ -4049,13 +4004,13 @@ \subsubsection{\texttt{phy-handle} Property} \section{Power ISA Open PIC Interrupt Controllers} \label{device-bindings:power-isa-open-pic-interrupt-controllers} -This section specifies the requirements for representing open PIC -compatible interrupt controllers. An open PIC interrupt controller -implements the open PIC architecture (developed jointly by AMD and +This section specifies the requirements for representing Open PIC +compatible interrupt controllers. An Open PIC interrupt controller +implements the Open PIC architecture (developed jointly by AMD and Cyrix) and specified in The Open Programmable Interrupt Controller (PIC) -Register Interface Specification Revision 1.2 ?. +Register Interface Specification Revision 1.2 \phantomsection\label{device-bindings:id2}{\hyperref[references:b18]{\crossref{{[}b18{]}}}}. -Interrupt specifiers in an open PIC interrupt domain are encoded with +Interrupt specifiers in an Open PIC interrupt domain are encoded with two cells. The first cell defines the interrupt number. The second cell defines the sense and level information. @@ -4064,17 +4019,17 @@ \section{Power ISA Open PIC Interrupt Controllers} \begin{quote} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{l+m+mi}{0} \PYG{o}{=} \PYG{n}{low} \PYG{n}{to} \PYG{n}{high} \PYG{n}{edge} \PYG{n}{sensitive} \PYG{n+nb}{type} \PYG{n}{enabled} -\PYG{l+m+mi}{1} \PYG{o}{=} \PYG{n}{active} \PYG{n}{low} \PYG{n}{level} \PYG{n}{sensitive} \PYG{n+nb}{type} \PYG{n}{enabled} -\PYG{l+m+mi}{2} \PYG{o}{=} \PYG{n}{active} \PYG{n}{high} \PYG{n}{level} \PYG{n}{sensitive} \PYG{n+nb}{type} \PYG{n}{enabled} -\PYG{l+m+mi}{3} \PYG{o}{=} \PYG{n}{high} \PYG{n}{to} \PYG{n}{low} \PYG{n}{edge} \PYG{n}{sensitive} \PYG{n+nb}{type} \PYG{n}{enabled} +0 = low to high edge sensitive type enabled +1 = active low level sensitive type enabled +2 = active high level sensitive type enabled +3 = high to low edge sensitive type enabled \end{Verbatim} \end{quote} \begin{threeparttable} -\capstart\caption{Open-PIC properties}\label{device-bindings:id16} -\begin{tabulary}{\linewidth}{l c l J} +\capstart\caption{Open-PIC properties}\label{device-bindings:id17} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -4152,12 +4107,12 @@ \section{\texttt{simple-bus} Compatible Value} System-on-a-chip processors may have an internal I/O bus that cannot be probed for devices. The devices on the bus can be accessed directly without additional configuration required. This type of bus is -represented as a node with a compatible value of “simple-bus”. +represented as a node with a compatible value of ``simple-bus''. \begin{threeparttable} -\capstart\caption{\texttt{simple-bus} Compatible Node Properties}\label{device-bindings:id17} -\begin{tabulary}{\linewidth}{l c l J} +\capstart\caption{\texttt{simple-bus} Compatible Node Properties}\label{device-bindings:id18} +\begin{tabulary}{\linewidth}{| l c l J |} \hline \textsf{\relax Property Name @@ -4199,20 +4154,21 @@ \section{\texttt{simple-bus} Compatible Value} -\chapter{Flat Device Tree Physical Structure} -\label{flattened-format::doc}\label{flattened-format:flat-device-tree-physical-structure}\label{flattened-format:chapter-fdt-structure} +\chapter{Flat Devicetree Physical Structure} +\label{flattened-format:flat-devicetree-physical-structure}\label{flattened-format::doc}\label{flattened-format:chapter-fdt-structure} With the exception of platforms using IEEE1275 Open Firmware {[}IEEE1275{]}, the devicetree data is contained within a single single, linear, pointerless data -structure known as the flattened device tree or device tree blob. - -This data structure consists of a small header (see -{\hyperref[flattened\string-format:sect\string-fdt\string-header]{\crossref{\DUrole{std,std-ref}{5.2}}}}), followed by three variable sized sections: the -memory reservation block (see {\hyperref[flattened\string-format:sect\string-fdt\string-memory\string-reservation\string-block]{\crossref{\DUrole{std,std-ref}{5.3}}}}), -the structure block (see {\hyperref[flattened\string-format:sect\string-fdt\string-structure\string-block]{\crossref{\DUrole{std,std-ref}{5.4}}}}) and the -strings block (see {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}). These should be -present in the flattened device tree in that order. Thus, the device -tree structure as a whole, when loaded into memory at address, will -resemble the diagram in Figure \hyperref[flattened-format:figure-device-tree-structure]{Fig. \ref{flattened-format:figure-device-tree-structure}} +structure known as the flattened devicetree or devicetree blob. + +This data structure consists of a small header +(see section {\hyperref[flattened\string-format:sect\string-fdt\string-header]{\crossref{\DUrole{std,std-ref}{5.2}}}}), +followed by three variable sized sections: +the memory reservation block (see section {\hyperref[flattened\string-format:sect\string-fdt\string-memory\string-reservation\string-block]{\crossref{\DUrole{std,std-ref}{5.3}}}}), +the structure block (see secton {\hyperref[flattened\string-format:sect\string-fdt\string-structure\string-block]{\crossref{\DUrole{std,std-ref}{5.4}}}}), +and the strings block (see section {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}). +These should be present in the flattened devicetree in that order. +Thus, the devicetree structure as a whole, when loaded into memory at address, +will resemble the diagram in \hyperref[flattened-format:figure-device-tree-structure]{Fig. \ref{flattened-format:figure-device-tree-structure}} (lower addresses are at the top of the diagram). \begin{figure}[htbp] \centering @@ -4223,20 +4179,20 @@ \chapter{Flat Device Tree Physical Structure} The (free space) sections may not be present, though in some cases they might be required to satisfy the alignment constraints of the individual -blocks (see {\hyperref[flattened\string-format:sect\string-fdt\string-alignment]{\crossref{\DUrole{std,std-ref}{5.6}}}}). +blocks (see section {\hyperref[flattened\string-format:sect\string-fdt\string-alignment]{\crossref{\DUrole{std,std-ref}{5.6}}}}). \section{Versioning} \label{flattened-format:sect-fdt-versioning}\label{flattened-format:versioning} -Several versions of the flattened device tree structure have been defined since +Several versions of the flattened devicetree structure have been defined since the original definition of the format. Fields in the header give the version, -so that the client program can determine if the device tree is encoded in a +so that the client program can determine if the devicetree is encoded in a compatible format. This document describes only version 17 of the format. DTSpec compliant boot -programs shall provide a device tree of version 17 or later, and should provide -a device tree of a version that is backwards compatible with version 16. -DTSpec compliant client programs shall accept device trees of any version +programs shall provide a devicetree of version 17 or later, and should provide +a devicetree of a version that is backwards compatible with version 16. +DTSpec compliant client programs shall accept devicetrees of any version backwards compatible with version 17 and may accept other versions as well. \begin{notice}{note}{Note:} @@ -4247,32 +4203,32 @@ \section{Versioning} \section{Header} \label{flattened-format:sect-fdt-header}\label{flattened-format:header} -The layout of the header for the device tree is defined by the following +The layout of the header for the devicetree is defined by the following C structure. All the header fields are 32-bit integers, stored in big-endian format. -\textbf{Flattened Device Tree Header Fields} +\textbf{Flattened Devicetree Header Fields} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{struct} \PYG{n}{fdt\PYGZus{}header} \PYG{p}{\PYGZob{}} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{magic}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{totalsize}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{off\PYGZus{}dt\PYGZus{}struct}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{off\PYGZus{}dt\PYGZus{}strings}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{off\PYGZus{}mem\PYGZus{}rsvmap}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{version}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{last\PYGZus{}comp\PYGZus{}version}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{boot\PYGZus{}cpuid\PYGZus{}phys}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{size\PYGZus{}dt\PYGZus{}strings}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{size\PYGZus{}dt\PYGZus{}struct}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +struct fdt\PYGZus{}header \PYGZob{} + uint32\PYGZus{}t magic; + uint32\PYGZus{}t totalsize; + uint32\PYGZus{}t off\PYGZus{}dt\PYGZus{}struct; + uint32\PYGZus{}t off\PYGZus{}dt\PYGZus{}strings; + uint32\PYGZus{}t off\PYGZus{}mem\PYGZus{}rsvmap; + uint32\PYGZus{}t version; + uint32\PYGZus{}t last\PYGZus{}comp\PYGZus{}version; + uint32\PYGZus{}t boot\PYGZus{}cpuid\PYGZus{}phys; + uint32\PYGZus{}t size\PYGZus{}dt\PYGZus{}strings; + uint32\PYGZus{}t size\PYGZus{}dt\PYGZus{}struct; +\PYGZcb{}; \end{Verbatim} \begin{description} \item[{\code{magic}}] \leavevmode This field shall contain the value 0xd00dfeed (big-endian). \item[{\code{totalsize}}] \leavevmode -This field shall contain the total size of the device tree data +This field shall contain the total size of the devicetree data structure. This size shall encompass all sections of the structure: the header, the memory reservation block, structure block and strings block, as well as any free space gaps between the blocks or @@ -4280,47 +4236,47 @@ \section{Header} \item[{\code{off\_dt\_struct}}] \leavevmode This field shall contain the offset in bytes of the structure block -(see {\hyperref[flattened\string-format:sect\string-fdt\string-structure\string-block]{\crossref{\DUrole{std,std-ref}{5.4}}}}) from the beginning of the header. +(see section {\hyperref[flattened\string-format:sect\string-fdt\string-structure\string-block]{\crossref{\DUrole{std,std-ref}{5.4}}}}) from the beginning of the header. \item[{\code{off\_dt\_strings}}] \leavevmode This field shall contain the offset in bytes of the strings block -(see {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}) from the beginning of the header. +(see section {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}) from the beginning of the header. \item[{\code{off\_mem\_rsvmap}}] \leavevmode This field shall contain the offset in bytes of the memory -reservation block (see {\hyperref[flattened\string-format:sect\string-fdt\string-memory\string-reservation\string-block]{\crossref{\DUrole{std,std-ref}{5.3}}}}) +reservation block (see section {\hyperref[flattened\string-format:sect\string-fdt\string-memory\string-reservation\string-block]{\crossref{\DUrole{std,std-ref}{5.3}}}}) from the beginning of the header. \item[{\code{version}}] \leavevmode -This field shall contain the version of the device tree data +This field shall contain the version of the devicetree data structure. The version is 17 if using the structure as defined in -this document. An DTSpec boot program may provide the device tree of +this document. An DTSpec boot program may provide the devicetree of a later version, in which case this field shall contain the version number defined in whichever later document gives the details of that version. \item[{\code{last\_comp\_version}}] \leavevmode -This field shall contain the lowest version of the device tree data +This field shall contain the lowest version of the devicetree data structure with which the version used is backwards compatible. So, for the structure as defined in this document (version 17), this field shall contain 16 because version 17 is backwards compatible with version 16, but not earlier versions. As per section {\hyperref[flattened\string-format:sect\string-fdt\string-versioning]{\crossref{\DUrole{std,std-ref}{5.1}}}}, a DTSpec boot program should provide a -device tree in a format which is backwards compatible with version +devicetree in a format which is backwards compatible with version 16, and thus this field shall always contain 16. \item[{\code{boot\_cpuid\_phys}}] \leavevmode This field shall contain the physical ID of the system’s boot CPU. It shall be identical to the physical ID given in the \code{reg} property -of that CPU node within the device tree. +of that CPU node within the devicetree. \item[{\code{size\_dt\_strings}}] \leavevmode This field shall contain the length in bytes of the strings block -section of the device tree blob. +section of the devicetree blob. \item[{\code{size\_dt\_struct}}] \leavevmode This field shall contain the length in bytes of the structure block -section of the device tree blob. +section of the devicetree blob. \end{description} @@ -4351,7 +4307,7 @@ \subsection{Purpose} in optional extensions to it, or in platform-specific documentation. The reserved regions supplied by a boot program may, but are not -required to, encompass the device tree blob itself. The client program +required to, encompass the devicetree blob itself. The client program shall ensure that it does not overwrite this data structure before it is used, whether or not it is in the reserved areas. @@ -4387,10 +4343,10 @@ \subsection{Format} structure. \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{struct} \PYG{n}{fdt\PYGZus{}reserve\PYGZus{}entry} \PYG{p}{\PYGZob{}} - \PYG{n}{uint64\PYGZus{}t} \PYG{n}{address}\PYG{p}{;} - \PYG{n}{uint64\PYGZus{}t} \PYG{n}{size}\PYG{p}{;} -\PYG{p}{\PYGZcb{}}\PYG{p}{;} +struct fdt\PYGZus{}reserve\PYGZus{}entry \PYGZob{} + uint64\PYGZus{}t address; + uint64\PYGZus{}t size; +\PYGZcb{}; \end{Verbatim} Each pair gives the physical address and size of a reserved memory @@ -4401,20 +4357,20 @@ \subsection{Format} Each uint64\_t in the memory reservation block, and thus the memory reservation block as a whole, shall be located at an 8-byte aligned -offset from the beginning of the device tree blob (see +offset from the beginning of the devicetree blob (see section {\hyperref[flattened\string-format:sect\string-fdt\string-alignment]{\crossref{\DUrole{std,std-ref}{5.6}}}}). \section{Structure Block} \label{flattened-format:sect-fdt-structure-block}\label{flattened-format:structure-block} -The structure block describes the structure and contents of the device -tree itself. It is composed of a sequence of tokens with data, as +The structure block describes the structure and contents of the devicetree +itself. It is composed of a sequence of tokens with data, as described in 0. These are organized into a linear tree structure, as described in 0. Each token in the structure block, and thus the structure block itself, shall be located at a 4-byte aligned offset from the beginning of the -device tree blob (see {\hyperref[flattened\string-format:sect\string-fdt\string-alignment]{\crossref{\DUrole{std,std-ref}{5.6}}}}). +devicetree blob (see {\hyperref[flattened\string-format:sect\string-fdt\string-alignment]{\crossref{\DUrole{std,std-ref}{5.6}}}}). \subsection{Lexical structure} @@ -4432,8 +4388,8 @@ \subsection{Lexical structure} The FDT\_BEGIN\_NODE token marks the beginning of a node’s representation. It shall be followed by the node’s unit name as extra data. The name is stored as a null-terminated string, and -shall include the unit address (see {\hyperref[devicetree\string-basics:sect\string-node\string-names]{\crossref{\DUrole{std,std-ref}{2.2.1}}}}), if any. The -node name is followed by zeroed padding bytes, if necessary for +shall include the unit address (see section {\hyperref[devicetree\string-basics:sect\string-node\string-names]{\crossref{\DUrole{std,std-ref}{2.2.1}}}}), if any. +The node name is followed by zeroed padding bytes, if necessary for alignment, and then the next token, which may be any token except FDT\_END. @@ -4444,25 +4400,26 @@ \subsection{Lexical structure} \item[{\code{FDT\_PROP} (0x00000003)}] \leavevmode The FDT\_PROP token marks the beginning of the representation of one -property in the device tree. It shall be followed by extra data +property in the devicetree. It shall be followed by extra data describing the property. This data consists first of the property’s length and name represented as the following C structure: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{struct} \PYG{p}{\PYGZob{}} - \PYG{n}{uint32\PYGZus{}t} \PYG{n+nb}{len}\PYG{p}{;} - \PYG{n}{uint32\PYGZus{}t} \PYG{n}{nameoff}\PYG{p}{;} -\PYG{p}{\PYGZcb{}} +struct \PYGZob{} + uint32\PYGZus{}t len; + uint32\PYGZus{}t nameoff; +\PYGZcb{} \end{Verbatim} Both the fields in this structure are 32-bit big-endian integers. \begin{itemize} \item {} len gives the length of the property’s value in bytes (which may be -zero, indicating an empty property, see {\hyperref[devicetree\string-basics:sect\string-property\string-values]{\crossref{\DUrole{std,std-ref}{2.2.4.2}}}}). +zero, indicating an empty property, see section {\hyperref[devicetree\string-basics:sect\string-property\string-values]{\crossref{\DUrole{std,std-ref}{2.2.4.2}}}}). \item {} -nameoff gives an offset into the strings block (see {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}) +nameoff gives an offset into the strings block +(see section {\hyperref[flattened\string-format:sect\string-fdt\string-strings\string-block]{\crossref{\DUrole{std,std-ref}{5.5}}}}) at which the property’s name is stored as a null-terminated string. \end{itemize} @@ -4478,7 +4435,7 @@ \subsection{Lexical structure} the next token, which can be any valid token. A property or node definition in the tree can be overwritten with FDT\_NOP tokens to remove it from the tree without needing to move other sections of -the tree’s representation in the device tree blob. +the tree’s representation in the devicetree blob. \item[{\code{FDT\_END} (0x00000009)}] \leavevmode The FDT\_END token marks the end of the structure block. There shall @@ -4493,7 +4450,7 @@ \subsection{Lexical structure} \subsection{Tree structure} \label{flattened-format:tree-structure} -The device tree structure is represented as a linear tree: the +The devicetree structure is represented as a linear tree: the representation of each node begins with an FDT\_BEGIN\_NODE token and ends with an FDT\_END\_NODE token. The node’s properties and subnodes (if any) are represented before the FDT\_END\_NODE, so that the @@ -4513,8 +4470,6 @@ \subsection{Tree structure} \item {} FDT\_BEGIN\_NODE token - -\end{itemize} \begin{itemize} \item {} The node’s name as a null-terminated string @@ -4523,30 +4478,26 @@ \subsection{Tree structure} {[}zeroed padding bytes to align to a 4-byte boundary{]} \end{itemize} -\begin{itemize} + \item {} For each property of the node: - -\end{itemize} -\begin{quote} \begin{itemize} \item {} (optionally) any number of FDT\_NOP tokens \item {} FDT\_PROP token - -\end{itemize} \begin{itemize} \item {} -property information as given in {\hyperref[flattened\string-format:sect\string-fdt\string-lexical\string-structure]{\crossref{\DUrole{std,std-ref}{5.4.1}}}} +property information as given in section {\hyperref[flattened\string-format:sect\string-fdt\string-lexical\string-structure]{\crossref{\DUrole{std,std-ref}{5.4.1}}}} \item {} {[}zeroed padding bytes to align to a 4-byte boundary{]} \end{itemize} -\end{quote} -\begin{itemize} + +\end{itemize} + \item {} Representations of all child nodes in this format @@ -4573,7 +4524,7 @@ \section{Strings Block} offset into the strings block. The strings block has no alignment constraints and may appear at any -offset from the beginning of the device tree blob. +offset from the beginning of the devicetree blob. \section{Alignment} @@ -4584,41 +4535,41 @@ \section{Alignment} aligned to an 8-byte boundary and the structure block to a 4-byte boundary. -Furthermore, the device tree blob as a whole can be relocated without +Furthermore, the devicetree blob as a whole can be relocated without destroying the alignment of the subblocks. As described in the previous sections, the structure and strings blocks -shall have aligned offsets from the beginning of the device tree blob. +shall have aligned offsets from the beginning of the devicetree blob. To ensure the in-memory alignment of the blocks, it is sufficient to -ensure that the device tree as a whole is loaded at an address aligned +ensure that the devicetree as a whole is loaded at an address aligned to the largest alignment of any of the subblocks, that is, to an 8-byte boundary. A DTSpec compliant boot -program shall load the device tree blob at such an aligned address +program shall load the devicetree blob at such an aligned address before passing it to the client program. If an DTSpec client program -relocates the device tree blob in memory, it should only do so to +relocates the devicetree blob in memory, it should only do so to another 8-byte aligned address. -\chapter{Device Tree Source Format (version 1)} -\label{source-language:chapter-devicetree-source-format}\label{source-language:device-tree-source-format-version-1}\label{source-language::doc} -The Device Tree Source (DTS) format is a textual representation of a -device tree in a form that can be processed by dtc into a binary device -tree in the form expected by the kernel. The following description is +\chapter{Devicetree Source Format (version 1)} +\label{source-language:chapter-devicetree-source-format}\label{source-language:devicetree-source-format-version-1}\label{source-language::doc} +The Devicetree Source (DTS) format is a textual representation of a +devicetree in a form that can be processed by dtc into a binary +devicetree in the form expected by the kernel. The following description is not a formal syntax definition of DTS, but describes the basic -constructs used to represent device trees. +constructs used to represent devicetrees. \section{Node and property definitions} \label{source-language:node-and-property-definitions} -Device tree nodes are defined with a node name and unit address with +Devicetree nodes are defined with a node name and unit address with braces marking the start and end of the node definition. They may be preceded by a label. \begin{Verbatim}[commandchars=\\\{\}] -\PYG{p}{[}\PYG{n}{label}\PYG{p}{:}\PYG{p}{]} \PYG{n}{node}\PYG{o}{\PYGZhy{}}\PYG{n}{name}\PYG{p}{[}\PYG{n+nd}{@unit}\PYG{o}{\PYGZhy{}}\PYG{n}{address}\PYG{p}{]} \PYG{p}{\PYGZob{}} - \PYG{p}{[}\PYG{n}{properties} \PYG{n}{definitions}\PYG{p}{]} - \PYG{p}{[}\PYG{n}{child} \PYG{n}{nodes}\PYG{p}{]} -\PYG{p}{\PYGZcb{}} +[label:] node\PYGZhy{}name[@unit\PYGZhy{}address] \PYGZob{} + [properties definitions] + [child nodes] +\PYGZcb{} \end{Verbatim} Nodes may contain property definitions and/or child node definitions. If @@ -4627,14 +4578,14 @@ \section{Node and property definitions} Property definitions are name value pairs in the form: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{p}{[}\PYG{n}{label}\PYG{p}{:}\PYG{p}{]} \PYG{n+nb}{property}\PYG{o}{\PYGZhy{}}\PYG{n}{name} \PYG{o}{=} \PYG{n}{value}\PYG{p}{;} +[label:] property\PYGZhy{}name = value; \end{Verbatim} except for properties with empty (zero length) value which have the form: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{p}{[}\PYG{n}{label}\PYG{p}{:}\PYG{p}{]} \PYG{n+nb}{property}\PYG{o}{\PYGZhy{}}\PYG{n}{name}\PYG{p}{;} +[label:] property\PYGZhy{}name; \end{Verbatim} Property values may be defined as an array of 32-bit integer cells, as @@ -4647,7 +4598,7 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{interrupts} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{17} \PYG{l+m+mh}{0xc}\PYG{o}{\PYGZgt{}}\PYG{p}{;} +interrupts = \PYGZlt{}17 0xc\PYGZgt{}; \end{Verbatim} \begin{itemize} \item {} @@ -4656,7 +4607,7 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{clock}\PYG{o}{\PYGZhy{}}\PYG{n}{frequency} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0x00000001} \PYG{l+m+mh}{0x00000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} +clock\PYGZhy{}frequency = \PYGZlt{}0x00000001 0x00000000\PYGZgt{}; \end{Verbatim} \begin{itemize} \item {} @@ -4667,7 +4618,7 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{simple\PYGZhy{}bus}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} +compatible = \PYGZdq{}simple\PYGZhy{}bus\PYGZdq{}; \end{Verbatim} \begin{itemize} \item {} @@ -4678,13 +4629,13 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{local}\PYG{o}{\PYGZhy{}}\PYG{n}{mac}\PYG{o}{\PYGZhy{}}\PYG{n}{address} \PYG{o}{=} \PYG{p}{[}\PYG{l+m+mi}{00} \PYG{l+m+mi}{00} \PYG{l+m+mi}{12} \PYG{l+m+mi}{34} \PYG{l+m+mi}{56} \PYG{l+m+mi}{78}\PYG{p}{]}\PYG{p}{;} +local\PYGZhy{}mac\PYGZhy{}address = [00 00 12 34 56 78]; \end{Verbatim} or equivalently: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{local}\PYG{o}{\PYGZhy{}}\PYG{n}{mac}\PYG{o}{\PYGZhy{}}\PYG{n}{address} \PYG{o}{=} \PYG{p}{[}\PYG{l+m+mi}{000012345678}\PYG{p}{]}\PYG{p}{;} +local\PYGZhy{}mac\PYGZhy{}address = [000012345678]; \end{Verbatim} \begin{itemize} \item {} @@ -4694,8 +4645,8 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{compatible} \PYG{o}{=} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ns16550}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{ns8250}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} -\PYG{n}{example} \PYG{o}{=} \PYG{o}{\PYGZlt{}}\PYG{l+m+mh}{0xf00f0000} \PYG{l+m+mi}{19}\PYG{o}{\PYGZgt{}}\PYG{p}{,} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{a strange property format}\PYG{l+s+s2}{\PYGZdq{}}\PYG{p}{;} +compatible = \PYGZdq{}ns16550\PYGZdq{}, \PYGZdq{}ns8250\PYGZdq{}; +example = \PYGZlt{}0xf00f0000 19\PYGZgt{}, \PYGZdq{}a strange property format\PYGZdq{}; \end{Verbatim} \begin{itemize} \item {} @@ -4706,13 +4657,13 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{parent} \PYG{o}{=} \PYG{o}{\PYGZlt{}} \PYG{o}{\PYGZam{}}\PYG{n}{mpic} \PYG{o}{\PYGZgt{}}\PYG{p}{;} +interrupt\PYGZhy{}parent = \PYGZlt{} \PYGZam{}mpic \PYGZgt{}; \end{Verbatim} or they may be \& followed by a node’s full path in braces. Example: \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{parent} \PYG{o}{=} \PYG{o}{\PYGZlt{}} \PYG{o}{\PYGZam{}}\PYG{p}{\PYGZob{}}\PYG{o}{/}\PYG{n}{soc}\PYG{o}{/}\PYG{n}{interrupt}\PYG{o}{\PYGZhy{}}\PYG{n}{controller}\PYG{n+nd}{@40000}\PYG{p}{\PYGZcb{}} \PYG{o}{\PYGZgt{}}\PYG{p}{;} +interrupt\PYGZhy{}parent = \PYGZlt{} \PYGZam{}\PYGZob{}/soc/interrupt\PYGZhy{}controller@40000\PYGZcb{} \PYGZgt{}; \end{Verbatim} \begin{itemize} \item {} @@ -4722,7 +4673,7 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{ethernet0} \PYG{o}{=} \PYG{o}{\PYGZam{}}\PYG{n}{EMAC0}\PYG{p}{;} +ethernet0 = \PYGZam{}EMAC0; \end{Verbatim} \begin{itemize} \item {} @@ -4733,9 +4684,9 @@ \section{Node and property definitions} \end{itemize} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{n}{reg} \PYG{o}{=} \PYG{n}{reglabel}\PYG{p}{:} \PYG{o}{\PYGZlt{}}\PYG{l+m+mi}{0} \PYG{n}{sizelabel}\PYG{p}{:} \PYG{l+m+mh}{0x1000000}\PYG{o}{\PYGZgt{}}\PYG{p}{;} -\PYG{n}{prop} \PYG{o}{=} \PYG{p}{[}\PYG{n}{ab} \PYG{n}{cd} \PYG{n}{ef} \PYG{n}{byte4}\PYG{p}{:} \PYG{l+m+mi}{00} \PYG{n}{ff} \PYG{n}{fe}\PYG{p}{]}\PYG{p}{;} -\PYG{n+nb}{str} \PYG{o}{=} \PYG{n}{start}\PYG{p}{:} \PYG{l+s+s2}{\PYGZdq{}}\PYG{l+s+s2}{string value}\PYG{l+s+s2}{\PYGZdq{}} \PYG{n}{end}\PYG{p}{:} \PYG{p}{;} +reg = reglabel: \PYGZlt{}0 sizelabel: 0x1000000\PYGZgt{}; +prop = [ab cd ef byte4: 00 ff fe]; +str = start: \PYGZdq{}string value\PYGZdq{} end: ; \end{Verbatim} @@ -4744,12 +4695,12 @@ \section{File layout} \textbf{Version 1 DTS files have the overall layout:} \begin{Verbatim}[commandchars=\\\{\}] -\PYG{o}{/}\PYG{n}{dts}\PYG{o}{\PYGZhy{}}\PYG{n}{v1}\PYG{o}{/}\PYG{p}{;} -\PYG{p}{[}\PYG{n}{memory} \PYG{n}{reservations}\PYG{p}{]} - \PYG{o}{/} \PYG{p}{\PYGZob{}} - \PYG{p}{[}\PYG{n+nb}{property} \PYG{n}{definitions}\PYG{p}{]} - \PYG{p}{[}\PYG{n}{child} \PYG{n}{nodes}\PYG{p}{]} - \PYG{p}{\PYGZcb{}}\PYG{p}{;} +/dts\PYGZhy{}v1/; +[memory reservations] + / \PYGZob{} + [property definitions] + [child nodes] + \PYGZcb{}; \end{Verbatim} The /dts-v1/; shall be present to identify the file as a version 1 DTS @@ -4757,32 +4708,18 @@ \section{File layout} obsolete version 0, which uses a different format for integers in addition to other small but incompatible changes). -Memory reservations define an entry for the device tree blob’s memory +Memory reservations define an entry for the devicetree blob’s memory reservation table. They have the form: e.g., /memreserve/ \textless{}address\textgreater{} \textless{}length\textgreater{}; Where \textless{}address\textgreater{} and \textless{}length\textgreater{} are 64-bit C-style integers. \begin{itemize} \item {} -The / \{ \}; section defines the root node of the device tree. +The / \{ \}; section defines the root node of the devicetree. \item {} C style (/* ... */) and C++ style (//) comments are supported. \end{itemize} - -\chapter{Indices and tables} -\label{index:indices-and-tables}\label{index::doc}\begin{itemize} -\item {} -\DUrole{xref,std,std-ref}{genindex} - -\item {} -\DUrole{xref,std,std-ref}{modindex} - -\item {} -\DUrole{xref,std,std-ref}{search} - -\end{itemize} - \begin{thebibliography}{IEEE1275} \bibitem[b1]{b1}{\phantomsection\label{references:b1} \emph{Power ISA™}, Version 2.06 Revision B, July 23, 2010. It is @@ -4791,7 +4728,7 @@ \chapter{Indices and tables} \bibitem[IEEE1275]{IEEE1275}{\phantomsection\label{references:ieee1275} \emph{Boot (Initialization Configuration) Firmware: Core Requirements and Practices}, 1994, This is the core standard (also known as IEEE -1275) that defines the device tree concept adopted by the DTSpec and +1275) that defines the devicetree concept adopted by the DTSpec and ePAPR. It is available from Global Engineering (\url{http://global.ihs.com/}). } \bibitem[b3]{b3}{\phantomsection\label{references:b3} @@ -4805,12 +4742,12 @@ \chapter{Indices and tables} \bibitem[b4]{b4}{\phantomsection\label{references:b4} \emph{booting-without-of.txt}, Ben Herrenschmidt, Becky Bruce, et al., From the Linux kernel source tree (\url{http://www.kernel.org/}), -Describes the device tree as used by the Linux kernel. +Describes the devicetree as used by the Linux kernel. } \bibitem[b5]{b5}{\phantomsection\label{references:b5} \emph{Device Trees Everywhere}, David Gibson and Ben Herrenschmidt (\url{http://ozlabs.org/~dgibson/home/papers/dtc-paper.pdf}), An overview -of the concept of the device tree and device tree compiler. +of the concept of the devicetree and devicetree compiler. } \bibitem[b6]{b6}{\phantomsection\label{references:b6} \emph{PCI Bus Binding to: IEEE Std 1275-1994 Standard for Boot diff --git a/release/latex/fncychap.sty b/release/latex/fncychap.sty new file mode 100644 index 0000000..9a56c04 --- /dev/null +++ b/release/latex/fncychap.sty @@ -0,0 +1,683 @@ +%%% Copyright Ulf A. Lindgren +%%% +%%% Note Premission is granted to modify this file under +%%% the condition that it is saved using another +%%% file and package name. +%%% +%%% Revision 1.1 (1997) +%%% +%%% Jan. 8th Modified package name base date option +%%% Jan. 22th Modified FmN and FmTi for error in book.cls +%%% \MakeUppercase{#}->{\MakeUppercase#} +%%% Apr. 6th Modified Lenny option to prevent undesired +%%% skip of line. +%%% Nov. 8th Fixed \@chapapp for AMS +%%% +%%% Revision 1.2 (1998) +%%% +%%% Feb. 11th Fixed appendix problem related to Bjarne +%%% Aug. 11th Fixed problem related to 11pt and 12pt +%%% suggested by Tomas Lundberg. THANKS! +%%% +%%% Revision 1.3 (2004) +%%% Sep. 20th problem with frontmatter, mainmatter and +%%% backmatter, pointed out by Lapo Mori +%%% +%%% Revision 1.31 (2004) +%%% Sep. 21th problem with the Rejne definition streched text +%%% caused ugly gaps in the vrule aligned with the title +%%% text. Kindly pointed out to me by Hendri Adriaens +%%% +%%% Revision 1.32 (2005) +%%% Jun. 23th compatibility problem with the KOMA class 'scrbook.cls' +%%% a remedy is a redefinition of '\@schapter' in +%%% line with that used in KOMA. The problem was pointed +%%% out to me by Mikkel Holm Olsen +%%% +%%% Revision 1.33 (2005) +%%% Aug. 9th misspelled ``TWELV'' corrected, the error was pointed +%%% out to me by George Pearson +%%% +%%% Revision 1.34 (2007) +%%% Added an alternative to Lenny provided by Peter +%%% Osborne (2005-11-28) +%%% Corrected front, main and back matter, based on input +%%% from Bas van Gils (2006-04-24) +%%% Jul. 30th Added Bjornstrup option provided by Jean-Marc +%%% Francois (2007-01-05). +%%% Reverted to \MakeUppercase{#} see rev 1.1, solved +%%% problem with MakeUppercase and MakeLowercase pointed +%%% out by Marco Feuerstein (2007-06-06) + + +%%% Last modified Jul. 2007 + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesPackage{fncychap} + [2007/07/30 v1.34 + LaTeX package (Revised chapters)] + +%%%% For conditional inclusion of color +\newif\ifusecolor +\usecolorfalse + + + +%%%% DEFINITION OF Chapapp variables +\newcommand{\CNV}{\huge\bfseries} +\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}} + + +%%%% DEFINITION OF TheChapter variables +\newcommand{\CNoV}{\huge\bfseries} +\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}} + +\newif\ifUCN +\UCNfalse +\newif\ifLCN +\LCNfalse +\def\ChNameLowerCase{\LCNtrue\UCNfalse} +\def\ChNameUpperCase{\UCNtrue\LCNfalse} +\def\ChNameAsIs{\UCNfalse\LCNfalse} + +%%%%% Fix for AMSBook 971008 + +\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{} + + +%%%%% Fix for Bjarne and appendix 980211 + +\newif\ifinapp +\inappfalse +\renewcommand\appendix{\par + \setcounter{chapter}{0}% + \setcounter{section}{0}% + \inapptrue% + \renewcommand\@chapapp{\appendixname}% + \renewcommand\thechapter{\@Alph\c@chapter}} + +%%%%% Fix for frontmatter, mainmatter, and backmatter 040920 + +\@ifundefined{@mainmatter}{\newif\if@mainmatter \@mainmattertrue}{} + +%%%%% + + + +\newcommand{\FmN}[1]{% +\ifUCN + {\MakeUppercase{#1}}\LCNfalse +\else + \ifLCN + {\MakeLowercase{#1}}\UCNfalse + \else #1 + \fi +\fi} + + +%%%% DEFINITION OF Title variables +\newcommand{\CTV}{\Huge\bfseries} +\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}} + +%%%% DEFINITION OF the basic rule width +\newlength{\RW} +\setlength{\RW}{1pt} +\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}} + +\newif\ifUCT +\UCTfalse +\newif\ifLCT +\LCTfalse +\def\ChTitleLowerCase{\LCTtrue\UCTfalse} +\def\ChTitleUpperCase{\UCTtrue\LCTfalse} +\def\ChTitleAsIs{\UCTfalse\LCTfalse} +\newcommand{\FmTi}[1]{% +\ifUCT + {\MakeUppercase{#1}}\LCTfalse +\else + \ifLCT + {\MakeLowercase{#1}}\UCTfalse + \else {#1} + \fi +\fi} + + + +\newlength{\mylen} +\newlength{\myhi} +\newlength{\px} +\newlength{\py} +\newlength{\pyy} +\newlength{\pxx} + + +\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@} + +\newcommand{\DOCH}{% + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip 20\p@ + } +\newcommand{\DOTI}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } +\newcommand{\DOTIS}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } + +%%%%%% SONNY DEF + +\DeclareOption{Sonny}{% + \ChNameVar{\Large\sf} + \ChNumVar{\Huge} + \ChTitleVar{\Large\sf} + \ChRuleWidth{0.5pt} + \ChNameUpperCase + \renewcommand{\DOCH}{% + \raggedleft + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip 40\p@} + \renewcommand{\DOTI}[1]{% + \CTV\raggedleft\mghrulefill{\RW}\par\nobreak + \vskip 5\p@ + \CTV\FmTi{#1}\par\nobreak + \mghrulefill{\RW}\par\nobreak + \vskip 40\p@} + \renewcommand{\DOTIS}[1]{% + \CTV\raggedleft\mghrulefill{\RW}\par\nobreak + \vskip 5\p@ + \CTV\FmTi{#1}\par\nobreak + \mghrulefill{\RW}\par\nobreak + \vskip 40\p@} +} + +%%%%%% LENNY DEF + +\DeclareOption{Lenny}{% + + \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont} + \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont} + \ChTitleVar{\Huge\bfseries\rm} + \ChRuleWidth{1pt} + \renewcommand{\DOCH}{% + \settowidth{\px}{\CNV\FmN{\@chapapp}} + \addtolength{\px}{2pt} + \settoheight{\py}{\CNV\FmN{\@chapapp}} + \addtolength{\py}{1pt} + + \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter} + \addtolength{\mylen}{1pt} + \settowidth{\pxx}{\CNoV\thechapter} + \addtolength{\pxx}{-1pt} + + \settoheight{\pyy}{\CNoV\thechapter} + \addtolength{\pyy}{-2pt} + \setlength{\myhi}{\pyy} + \addtolength{\myhi}{-1\py} + \par + \parbox[b]{\textwidth}{% + \rule[\py]{\RW}{\myhi}% + \hskip -\RW% + \rule[\pyy]{\px}{\RW}% + \hskip -\px% + \raggedright% + \CNV\FmN{\@chapapp}\space\CNoV\thechapter% + \hskip1pt% + \mghrulefill{\RW}% + \rule{\RW}{\pyy}\par\nobreak% + \vskip -\baselineskip% + \vskip -\pyy% + \hskip \mylen% + \mghrulefill{\RW}\par\nobreak% + \vskip \pyy}% + \vskip 20\p@} + + + \renewcommand{\DOTI}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + + \renewcommand{\DOTIS}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + +%%%%%% Peter Osbornes' version of LENNY DEF + +\DeclareOption{PetersLenny}{% + +% five new lengths +\newlength{\bl} % bottom left : orig \space +\setlength{\bl}{6pt} +\newcommand{\BL}[1]{\setlength{\bl}{#1}} +\newlength{\br} % bottom right : orig 1pt +\setlength{\br}{1pt} +\newcommand{\BR}[1]{\setlength{\br}{#1}} +\newlength{\tl} % top left : orig 2pt +\setlength{\tl}{2pt} +\newcommand{\TL}[1]{\setlength{\tl}{#1}} +\newlength{\trr} % top right :orig 1pt +\setlength{\trr}{1pt} +\newcommand{\TR}[1]{\setlength{\trr}{#1}} +\newlength{\blrule} % top right :orig 1pt +\setlength{\trr}{0pt} +\newcommand{\BLrule}[1]{\setlength{\blrule}{#1}} + + + \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont} + \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont} + \ChTitleVar{\Huge\bfseries\rm} + \ChRuleWidth{1pt} +\renewcommand{\DOCH}{% + + +%%%%%%% tweaks for 1--9 and A--Z +\ifcase\c@chapter\relax% +\or\BL{-3pt}\TL{-4pt}\BR{0pt}\TR{-6pt}%1 +\or\BL{0pt}\TL{-4pt}\BR{2pt}\TR{-4pt}%2 +\or\BL{0pt}\TL{-4pt}\BR{2pt}\TR{-4pt}%3 +\or\BL{0pt}\TL{5pt}\BR{2pt}\TR{-4pt}%4 +\or\BL{0pt}\TL{3pt}\BR{2pt}\TR{-4pt}%5 +\or\BL{-1pt}\TL{0pt}\BR{2pt}\TR{-2pt}%6 +\or\BL{0pt}\TL{-3pt}\BR{2pt}\TR{-2pt}%7 +\or\BL{0pt}\TL{-3pt}\BR{2pt}\TR{-2pt}%8 +\or\BL{0pt}\TL{-3pt}\BR{-4pt}\TR{-2pt}%9 +\or\BL{-3pt}\TL{-3pt}\BR{2pt}\TR{-7pt}%10 +\or\BL{-6pt}\TL{-6pt}\BR{0pt}\TR{-9pt}%11 +\or\BL{-6pt}\TL{-6pt}\BR{2pt}\TR{-7pt}%12 +\or\BL{-5pt}\TL{-5pt}\BR{0pt}\TR{-9pt}%13 +\or\BL{-6pt}\TL{-6pt}\BR{0pt}\TR{-9pt}%14 +\or\BL{-3pt}\TL{-3pt}\BR{3pt}\TR{-6pt}%15 +\or\BL{-3pt}\TL{-3pt}\BR{3pt}\TR{-6pt}%16 +\or\BL{-5pt}\TL{-3pt}\BR{-8pt}\TR{-6pt}%17 +\or\BL{-5pt}\TL{-5pt}\BR{0pt}\TR{-9pt}%18 +\or\BL{-3pt}\TL{-3pt}\BR{-6pt}\TR{-9pt}%19 +\or\BL{0pt}\TL{0pt}\BR{0pt}\TR{-5pt}%20 +\fi + +\ifinapp\ifcase\c@chapter\relax% +\or\BL{0pt}\TL{14pt}\BR{5pt}\TR{-19pt}%A +\or\BL{0pt}\TL{-5pt}\BR{-3pt}\TR{-8pt}%B +\or\BL{-3pt}\TL{-2pt}\BR{1pt}\TR{-6pt}\BLrule{0pt}%C +\or\BL{0pt}\TL{-5pt}\BR{-3pt}\TR{-8pt}\BLrule{0pt}%D +\or\BL{0pt}\TL{-5pt}\BR{2pt}\TR{-3pt}%E +\or\BL{0pt}\TL{-5pt}\BR{-10pt}\TR{-1pt}%F +\or\BL{-3pt}\TL{0pt}\BR{0pt}\TR{-7pt}%G +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%H +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%I +\or\BL{2pt}\TL{0pt}\BR{-3pt}\TR{1pt}%J +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%K +\or\BL{0pt}\TL{-5pt}\BR{2pt}\TR{-19pt}%L +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%M +\or\BL{0pt}\TL{-5pt}\BR{-2pt}\TR{-1pt}%N +\or\BL{-3pt}\TL{-2pt}\BR{-3pt}\TR{-11pt}%O +\or\BL{0pt}\TL{-5pt}\BR{-9pt}\TR{-3pt}%P +\or\BL{-3pt}\TL{-2pt}\BR{-3pt}\TR{-11pt}%Q +\or\BL{0pt}\TL{-5pt}\BR{4pt}\TR{-8pt}%R +\or\BL{-2pt}\TL{-2pt}\BR{-2pt}\TR{-7pt}%S +\or\BL{-3pt}\TL{0pt}\BR{-5pt}\TR{4pt}\BLrule{8pt}%T +\or\BL{-7pt}\TL{-11pt}\BR{-5pt}\TR{-7pt}\BLrule{0pt}%U +\or\BL{-14pt}\TL{-5pt}\BR{-14pt}\TR{-1pt}\BLrule{14pt}%V +\or\BL{-10pt}\TL{-9pt}\BR{-13pt}\TR{-3pt}\BLrule{7pt}%W +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}\BLrule{0pt}%X +\or\BL{-6pt}\TL{-4pt}\BR{-7pt}\TR{1pt}\BLrule{7pt}%Y +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}\BLrule{0pt}%Z +\fi\fi +%%%%%%% + \settowidth{\px}{\CNV\FmN{\@chapapp}} + \addtolength{\px}{\tl} %MOD change 2pt to \tl + \settoheight{\py}{\CNV\FmN{\@chapapp}} + \addtolength{\py}{1pt} + + \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter} + \addtolength{\mylen}{\trr}% MOD change 1pt to \tr + \settowidth{\pxx}{\CNoV\thechapter} + \addtolength{\pxx}{-1pt} + + \settoheight{\pyy}{\CNoV\thechapter} + \addtolength{\pyy}{-2pt} + \setlength{\myhi}{\pyy} + \addtolength{\myhi}{-1\py} + \par + \parbox[b]{\textwidth}{% + \rule[\py]{\RW}{\myhi}% + \hskip -\RW% + \rule[\pyy]{\px}{\RW}% + \hskip -\px% + \raggedright% + \CNV\FmN{\@chapapp}\rule{\blrule}{\RW}\hskip\bl\CNoV\thechapter%MOD +% \CNV\FmN{\@chapapp}\space\CNoV\thechapter %ORIGINAL + \hskip\br% %MOD 1pt to \br + \mghrulefill{\RW}% + \rule{\RW}{\pyy}\par\nobreak% + \vskip -\baselineskip% + \vskip -\pyy% + \hskip \mylen% + \mghrulefill{\RW}\par\nobreak% + \vskip \pyy}% + \vskip 20\p@} + + + \renewcommand{\DOTI}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + + \renewcommand{\DOTIS}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + + +% + + +%%%%%% BJORNSTRUP DEF + +\DeclareOption{Bjornstrup}{% + \usecolortrue + % pzc (Zapf Chancelery) is nice. ppl (Palatino) is cool too. + \ChNumVar{\fontsize{76}{80}\usefont{OT1}{pzc}{m}{n}\selectfont} + \ChTitleVar{\raggedleft\Large\sffamily\bfseries} + + \setlength{\myhi}{10pt} % Space between grey box border and text + \setlength{\mylen}{\textwidth} + \addtolength{\mylen}{-2\myhi} + \renewcommand{\DOCH}{% + \settowidth{\py}{\CNoV\thechapter} + \addtolength{\py}{-10pt} % Amount of space by which the +% % number is shifted right + \fboxsep=0pt% + \colorbox[gray]{.85}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}% + \kern-\py\raise20pt% + \hbox{\color[gray]{.5}\CNoV\thechapter}\\% + } + + \renewcommand{\DOTI}[1]{% + \nointerlineskip\raggedright% + \fboxsep=\myhi% + \vskip-1ex% + \colorbox[gray]{.85}{\parbox[t]{\mylen}{\CTV\FmTi{#1}}}\par\nobreak% + \vskip 40\p@% + } + + \renewcommand{\DOTIS}[1]{% + \fboxsep=0pt + \colorbox[gray]{.85}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}\\% + \nointerlineskip\raggedright% + \fboxsep=\myhi% + \colorbox[gray]{.85}{\parbox[t]{\mylen}{\CTV\FmTi{#1}}}\par\nobreak% + \vskip 40\p@% + } +} + + +%%%%%%% GLENN DEF + + +\DeclareOption{Glenn}{% + \ChNameVar{\bfseries\Large\sf} + \ChNumVar{\Huge} + \ChTitleVar{\bfseries\Large\rm} + \ChRuleWidth{1pt} + \ChNameUpperCase + \ChTitleUpperCase + \renewcommand{\DOCH}{% + \settoheight{\myhi}{\CTV\FmTi{Test}} + \setlength{\py}{\baselineskip} + \addtolength{\py}{\RW} + \addtolength{\py}{\myhi} + \setlength{\pyy}{\py} + \addtolength{\pyy}{-1\RW} + + \raggedright + \CNV\FmN{\@chapapp}\space\CNoV\thechapter + \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak} + + \renewcommand{\DOTI}[1]{% + \addtolength{\pyy}{-4pt} + \settoheight{\myhi}{\CTV\FmTi{#1}} + \addtolength{\myhi}{\py} + \addtolength{\myhi}{-1\RW} + \vskip -1\pyy + \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt + \raggedleft\CTV\FmTi{#1}\par\nobreak + \vskip 80\p@} + +\newlength{\backskip} + \renewcommand{\DOTIS}[1]{% +% \setlength{\py}{10pt} +% \setlength{\pyy}{\py} +% \addtolength{\pyy}{\RW} +% \setlength{\myhi}{\baselineskip} +% \addtolength{\myhi}{\pyy} +% \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak +% \addtolength{}{} +%\vskip -1\baselineskip +% \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt +% \raggedleft\CTV\FmTi{#1}\par\nobreak +% \vskip 60\p@} +%% Fix suggested by Tomas Lundberg + \setlength{\py}{25pt} % eller vad man vill + \setlength{\pyy}{\py} + \setlength{\backskip}{\py} + \addtolength{\backskip}{2pt} + \addtolength{\pyy}{\RW} + \setlength{\myhi}{\baselineskip} + \addtolength{\myhi}{\pyy} + \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak + \vskip -1\backskip + \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 3pt % + \raggedleft\CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + +%%%%%%% CONNY DEF + +\DeclareOption{Conny}{% + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\centering\Huge\rm\bfseries} + \ChNumVar{\Huge} + \ChTitleVar{\centering\Huge\rm} + \ChRuleWidth{2pt} + + \renewcommand{\DOCH}{% + \mghrulefill{3\RW}\par\nobreak + \vskip -0.5\baselineskip + \mghrulefill{\RW}\par\nobreak + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip -0.5\baselineskip + } + \renewcommand{\DOTI}[1]{% + \mghrulefill{\RW}\par\nobreak + \CTV\FmTi{#1}\par\nobreak + \vskip 60\p@ + } + \renewcommand{\DOTIS}[1]{% + \mghrulefill{\RW}\par\nobreak + \CTV\FmTi{#1}\par\nobreak + \vskip 60\p@ + } + } + +%%%%%%% REJNE DEF + +\DeclareOption{Rejne}{% + + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\centering\Large\rm} + \ChNumVar{\Huge} + \ChTitleVar{\centering\Huge\rm} + \ChRuleWidth{1pt} + \renewcommand{\DOCH}{% + \settoheight{\py}{\CNoV\thechapter} + \parskip=0pt plus 1pt % Set parskip to default, just in case v1.31 + \addtolength{\py}{-1pt} + \CNV\FmN{\@chapapp}\par\nobreak + \vskip 20\p@ + \setlength{\myhi}{2\baselineskip} + \setlength{\px}{\myhi} + \addtolength{\px}{-1\RW} + \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip + 10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip 10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak + \vskip -3\p@% Added -2pt vskip to correct for streched text v1.31 + } + \renewcommand{\DOTI}[1]{% + \setlength{\mylen}{\textwidth} + \parskip=0pt plus 1pt % Set parskip to default, just in case v1.31 + \addtolength{\mylen}{-2\RW} + {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule width\RW}\par\nobreak% + \vskip -3pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}% + \vskip 60\p@% Added -2pt in vskip to correct for streched text v1.31 + } + \renewcommand{\DOTIS}[1]{% + \setlength{\py}{\fboxrule} + \setlength{\fboxrule}{\RW} + \setlength{\mylen}{\textwidth} + \addtolength{\mylen}{-2\RW} + \fbox{\parbox{\mylen}{\vskip 2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}} + \setlength{\fboxrule}{\py} + \vskip 60\p@ + } + } + + +%%%%%%% BJARNE DEF + +\DeclareOption{Bjarne}{% + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\raggedleft\normalsize\rm} + \ChNumVar{\raggedleft \bfseries\Large} + \ChTitleVar{\raggedleft \Large\rm} + \ChRuleWidth{1pt} + + +%% Note thechapter -> c@chapter fix appendix bug +%% Fixed misspelled 12 + + \newcounter{AlphaCnt} + \newcounter{AlphaDecCnt} + \newcommand{\AlphaNo}{% + \ifcase\number\theAlphaCnt + \ifnum\c@chapter=0 + ZERO\else{}\fi + \or ONE\or TWO\or THREE\or FOUR\or FIVE + \or SIX\or SEVEN\or EIGHT\or NINE\or TEN + \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN + \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi +} + + \newcommand{\AlphaDecNo}{% + \setcounter{AlphaDecCnt}{0} + \@whilenum\number\theAlphaCnt>0\do + {\addtocounter{AlphaCnt}{-10} + \addtocounter{AlphaDecCnt}{1}} + \ifnum\number\theAlphaCnt=0 + \else + \addtocounter{AlphaDecCnt}{-1} + \addtocounter{AlphaCnt}{10} + \fi + + + \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or + FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi + } + \newcommand{\TheAlphaChapter}{% + + \ifinapp + \thechapter + \else + \setcounter{AlphaCnt}{\c@chapter} + \ifnum\c@chapter<20 + \AlphaNo + \else + \AlphaDecNo\AlphaNo + \fi + \fi + } + \renewcommand{\DOCH}{% + \mghrulefill{\RW}\par\nobreak + \CNV\FmN{\@chapapp}\par\nobreak + \CNoV\TheAlphaChapter\par\nobreak + \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak + \vskip 20\p@ + } + \renewcommand{\DOTI}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } + \renewcommand{\DOTIS}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } +} + +\DeclareOption*{% + \PackageWarning{fancychapter}{unknown style option} + } + +\ProcessOptions* \relax + +\ifusecolor + \RequirePackage{color} +\fi +\def\@makechapterhead#1{% + \vspace*{50\p@}% + {\parindent \z@ \raggedright \normalfont + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter%%%%% Fix for frontmatter, mainmatter, and backmatter 040920 + \DOCH + \fi + \fi + \interlinepenalty\@M + \if@mainmatter%%%%% Fix for frontmatter, mainmatter, and backmatter 060424 + \DOTI{#1}% + \else% + \DOTIS{#1}% + \fi + }} + + +%%% Begin: To avoid problem with scrbook.cls (fncychap version 1.32) + +%%OUT: +%\def\@schapter#1{\if@twocolumn +% \@topnewpage[\@makeschapterhead{#1}]% +% \else +% \@makeschapterhead{#1}% +% \@afterheading +% \fi} + +%%IN: +\def\@schapter#1{% +\if@twocolumn% + \@makeschapterhead{#1}% +\else% + \@makeschapterhead{#1}% + \@afterheading% +\fi} + +%%% End: To avoid problem with scrbook.cls (fncychap version 1.32) + +\def\@makeschapterhead#1{% + \vspace*{50\p@}% + {\parindent \z@ \raggedright + \normalfont + \interlinepenalty\@M + \DOTIS{#1} + \vskip 40\p@ + }} + +\endinput + + diff --git a/release/latex/graphviz-1d3954672eca688030b49a13a35b6714d9abdcd5.pdf b/release/latex/graphviz-1d3954672eca688030b49a13a35b6714d9abdcd5.pdf new file mode 100644 index 0000000..86a5844 Binary files /dev/null and b/release/latex/graphviz-1d3954672eca688030b49a13a35b6714d9abdcd5.pdf differ diff --git a/release/latex/graphviz-23a197b43ca822bb92fb1a341bdd04b0845caa29.pdf b/release/latex/graphviz-23a197b43ca822bb92fb1a341bdd04b0845caa29.pdf new file mode 100644 index 0000000..71540b9 Binary files /dev/null and b/release/latex/graphviz-23a197b43ca822bb92fb1a341bdd04b0845caa29.pdf differ diff --git a/release/latex/graphviz-8bc6c34d442f7e613c5d327992e204083ddaf50f.pdf b/release/latex/graphviz-8bc6c34d442f7e613c5d327992e204083ddaf50f.pdf new file mode 100644 index 0000000..5df3549 Binary files /dev/null and b/release/latex/graphviz-8bc6c34d442f7e613c5d327992e204083ddaf50f.pdf differ diff --git a/release/latex/graphviz-e69f9031183bd8d3b6636722c922fcb66d4843c4.pdf b/release/latex/graphviz-e69f9031183bd8d3b6636722c922fcb66d4843c4.pdf new file mode 100644 index 0000000..a99166b Binary files /dev/null and b/release/latex/graphviz-e69f9031183bd8d3b6636722c922fcb66d4843c4.pdf differ diff --git a/release/latex/newfloat.sty b/release/latex/newfloat.sty new file mode 100644 index 0000000..47ac5e5 --- /dev/null +++ b/release/latex/newfloat.sty @@ -0,0 +1,737 @@ +%% +%% This is file `newfloat.sty', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% newfloat.dtx (with options: `package') +%% +%% Copyright (C) 1994-2016 Axel Sommerfeldt (axel.sommerfeldt@f-m.fm) +%% +%% http://sourceforge.net/projects/latex-caption/ +%% +%% -------------------------------------------------------------------------- +%% +%% This work may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3 +%% of this license or (at your option) any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% and version 1.3 or later is part of all distributions of LaTeX +%% version 2003/12/01 or later. +%% +%% This work has the LPPL maintenance status "maintained". +%% +%% This Current Maintainer of this work is Axel Sommerfeldt. +%% +%% This work consists of the files +%% CHANGELOG, README, SUMMARY, caption.ins, +%% caption.dtx, caption2.dtx, caption3.dtx, +%% bicaption.dtx, ltcaption.dtx, subcaption.dtx, +%% newfloat.dtx, and totalcount.dtx +%% the derived files +%% caption.sty, caption2.sty, caption3.sty, +%% bicaption.sty, ltcaption.sty, subcaption.sty, +%% newfloat.sty, and totalcount.sty +%% and the user manuals +%% caption-deu.tex, caption-eng.tex, and caption-rus.tex. +%% +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +\def\caption@tempa$Id: #1 #2 #3-#4-#5 #6${% + \def\caption@tempa{#3/#4/#5 }\def\caption@tempb{#2 }} +\caption@tempa $Id: newfloat.dtx 109 2015-09-17 09:29:07Z sommerfeldt $ +\ProvidesPackage{newfloat}[\caption@tempa v1.1-\caption@tempb Defining new floating environments (AR)] +\newcommand*\newfloat@Info[1]{% + \PackageInfo{newfloat}{#1}} +\newcommand*\newfloat@InfoNoLine[1]{% + \newfloat@Info{#1\@gobble}} +\newcommand*\newfloat@Error[1]{% + \PackageError{newfloat}{#1}\newfloat@eh} +\newcommand*\newfloat@eh{% + If you do not understand this error, please take a closer look\MessageBreak + at the documentation of the `newfloat' package.\MessageBreak\@ehc} +\RequirePackage{keyval}[1997/11/10] +\newcommand*\newfloat@def[2]{% + \newfloat@ifundefined{#1}{% + \@namedef{#1}{#2}}} +\newcommand*\newfloat@let[2]{% + \newfloat@ifundefined{#1}{% + \expandafter\let\csname #1\endcsname#2}} +\newcommand*\newfloat@ifundefined[2]{% + \@ifundefined{#1}{#2}{% + \newfloat@Info{% + \expandafter\string\csname#1\endcsname\space is already defined}}} +\newcommand*\DeclareFloatingEnvironment{% + \@testopt\@DeclareFloatingEnvironment{}} +\@onlypreamble\DeclareFloatingEnvironment +\def\@DeclareFloatingEnvironment[#1]#2{% + \newfloat@Info{New float `#2' with options `#1'}% + \newfloat@ifundefined{c@#2}{\newcounter{#2}}% + \ifdefined\c@float@type % from float package + \expandafter\edef\csname ftype@#2\endcsname{\the\value{float@type}}% + \addtocounter{float@type}{\value{float@type}}% + \else\ifdefined\c@newflo@tctr % from memoir document class + \expandafter\edef\csname ftype@#2\endcsname{\the\c@newflo@tctr}% + \advance\c@newflo@tctr \c@newflo@tctr + \else + \ifdefined\newfloat@ftype \else + \newcount\newfloat@ftype + \newfloat@ftype=8\relax + \fi + \expandafter\xdef\csname ftype@#2\endcsname{\the\newfloat@ftype}% + \advance\newfloat@ftype\newfloat@ftype + \fi\fi + \newfloat@Info{float type `#2'=\@nameuse{ftype@#2}}% + \newfloat@def{fnum@#2}% + {\@nameuse{#2name}\nobreakspace\@nameuse{the#2}\@nameuse{autodot}}% + \newfloat@capitalize\newfloat@Type{#2}% + \newfloat@let{#2name}{\newfloat@Type}% + \newfloat@def{fleg#2}{\@nameuse{#2name}}% legend naming (memoir) + \newfloat@ifundefined{flegtoc#2}{\@namedef{flegtoc#2}##1{}}% + \ifcsname @tufte@float\endcsname + \newenvironment{#2}[1][htbp]% + {\begin{@tufte@float}[##1]{#2}{}}% + {\end{@tufte@float}}% + \newenvironment{#2*}[1][htbp]% + {\begin{@tufte@float}[##1]{#2}{star}}% + {\end{@tufte@float}}% + \else + \newenvironment{#2}{\@float{#2}}{\end@float}% + \newenvironment{#2*}{\@dblfloat{#2}}{\end@dblfloat}% + \fi + \newfloat@def{listof#2}{\newfloat@listof{#2}}% + \newfloat@def{listof#2s}{\@nameuse{listof#2}}% + \newfloat@def{listof#2es}{\@nameuse{listof#2s}}% + \newfloat@def{newfloat@listof#2@hook}{}% + \ifdefined\l@figure + \newfloat@let{l@#2}{\l@figure}% + \else + \newfloat@def{l@#2}{\@dottedtocline{1}{1.5em}{2.3em}}% + \fi + \edef\newfloat@tempa{List of \newfloat@Type s}% + \newfloat@let{list#2name}{\newfloat@tempa}% + \expandafter\let\csname fst@#2\endcsname\@undefined + \newfloat@ifundefined{fps@#2}{\newfloat@setplacement{#2}{tbp}}% + \newfloat@ifundefined{ext@#2}{\newfloat@setfileext{#2}{lo#2}}% + \newfloat@setoptions*{#2}{#1}% + \@expandtwoargs\newfloat@announce{#2}{\@nameuse{ext@#2}}% + \@ifnextchar[\newfloat@DFE@setname\relax} +\@onlypreamble\@DeclareFloatingEnvironment +\def\newfloat@DFE@setname[#1]{% + \KV@@newfloat@name{#1}% + \@ifnextchar[\newfloat@DFE@setlistname\relax} +\@onlypreamble\newfloat@DFE@setname +\def\newfloat@DFE@setlistname[#1]{% + \KV@@newfloat@listname{#1}} +\@onlypreamble\newfloat@DFE@setlistname +\newcommand*\newfloat@capitalize[2]{% + \edef\newfloat@tempa{\gdef\noexpand#1{\@car#2\@nil}}% + \uppercase\expandafter{\newfloat@tempa}% + \edef\newfloat@tempa{% + \noexpand\g@addto@macro\noexpand#1{\@cdr#2\@nil}}% + \newfloat@tempa} +\newcommand*\newfloat@listof[1]{% + \@expandtwoargs\newfloat@list@of{#1}{\@nameuse{ext@#1}}} +\newcommand*\newfloat@list@of[2]{% + \begingroup + \expandafter\let\expandafter\listfigurename\csname list#1name\endcsname + \def\ext@figure{#2}% + \let\newfloat@starttoc\@starttoc + \def\@starttoc##1{\newfloat@starttoc{#2}}% + \let\newfloat@listoftoc\listoftoc + \def\listoftoc##1{\newfloat@listoftoc{#2}}% + \@nameuse{newfloat@listof#1@hook}% + \listoffigures + \endgroup} +\newcommand*\newfloat@setoptions{% + \@ifstar + {\newfloat@@setoptions\@firstofone}% + {\newfloat@@setoptions\@gobble}} +\newcommand*\newfloat@@setoptions[3]{% + \let\newfloat@within@value\@undefined + \let\newfloat@chapterlistsgaps@value\@undefined + #1{\KV@@newfloat@within\newfloat@within@default}% set default value for new floats + \def\newfloat@type{#2}% + \setkeys{@newfloat}{#3}% + \ifx\newfloat@within@value\@undefined \else + \newfloat@setoption{within}\newfloat@within@value + \fi + \ifx\newfloat@chapterlistsgaps@value\@undefined \else + \newfloat@setoption{chapterlistsgaps}\newfloat@chapterlistsgaps@value + \fi} +\newcommand*\newfloat@within@default{% + \ifcsname c@chapter\endcsname chapter\else none\fi} +\@onlypreamble\newfloat@within@default +\newcommand*\newfloat@setoption[1]{% + \edef\caption@tempa{\noexpand\@nameuse{newfloat@set#1}{\newfloat@type}}% + \caption@tempa} +\newcommand*\newfloat@setfileext[2]{% + \@namedef{ext@#1}{#2}} +\define@key{@newfloat}{fileext}{% + \newfloat@setoption{fileext}{#1}} +\newcommand*\newfloat@setlistname[2]{% + \@namedef{list#1name}{#2}} +\define@key{@newfloat}{listname}{% + \newfloat@setoption{listname}{#1}} +\newcommand*\newfloat@setname[2]{% + \newfloat@@setname{#1}{#2}% + \begingroup + \ifcsname languagename\endcsname + \ifcsname captions\languagename\endcsname + \expandafter\g@addto@macro\csname captions\languagename\endcsname + {\newfloat@@setname{#1}{#2}}% + \fi + \fi + \endgroup} +%%\AtBeginDocument{\let\newfloat@setname\newfloat@@setname} +\newcommand*\newfloat@@setname[2]{% + \@namedef{#1name}{#2}} +\define@key{@newfloat}{name}{% + \newfloat@setoption{name}{#1}} +\newcommand*\newfloat@setplacement[2]{% + \@namedef{fps@#1}{#2}} +\define@key{@newfloat}{placement}{% + \newfloat@setoption{placement}{#1}} +\newcommand*\newfloat@setwithin[2]{% + \ifcsname c@chapter\endcsname + \@removefromreset{#1}{chapter}% + \fi + \@removefromreset{#1}{section}% + \edef\@tempa{#2}% + \ifx\@tempa\@empty + \def\@tempa{none}% + \fi + \def\@tempb{none}% + \ifx\@tempa\@tempb + \ifcsname c@chapter\endcsname + \@chapterlistsgap@off{#1}% + \fi + \newfloat@@setwithin{#1}{}{}% + \else + \def\@tempb{chapter}% + \ifx\@tempa\@tempb + \@addtoreset{#1}{chapter}% + \@chapterlistsgap@on{#1}% + \newfloat@@setwithin{#1}{\ifnum\c@chapter>\z@ \thechapter.\fi}{\theHchapter.}% + \else + \def\@tempb{section}% + \ifx\@tempa\@tempb + \@addtoreset{#1}{section}% + \ifcsname c@chapter\endcsname + \@addtoreset{#1}{chapter}% + \@chapterlistsgap@on{#1}% + \newfloat@@setwithin{#1}{\thesection.}{\theHsection.}% + \else + \newfloat@@setwithin{#1}{\ifnum\c@section>\z@ \thesection.\fi}{\theHsection.}% + \fi + \else + \newfloat@Error{Invalid value `#2' for option `within'}% + \fi + \fi + \fi} +\newcommand*\newfloat@@setwithin[3]{% + \global\@namedef{the#1}{#2\arabic{#1}}% + \global\@namedef{theH#1}{#3\arabic{#1}}} +\define@key{@newfloat}{within}{% + \def\newfloat@within@value{#1}} +\newcommand*\newfloat@setwithout[1]{% + \newfloat@setwithin{#1}{none}} +\define@key{@newfloat}{without}[]{% + \def\newfloat@within@value{none}} +\newcommand*\newfloat@setchapterlistsgaps[2]{% + \edef\@tempa{#2}% + \def\@tempb{off}% + \ifx\@tempa\@tempb + \@chapterlistsgap@off{#1}% + \else + \def\@tempb{on}% + \ifx\@tempa\@tempb + \@chapterlistsgap@on{#1}% + \else + \newfloat@Error{Invalid value `#2' for option `chapterlistsgaps'}% + \fi + \fi} +\define@key{@newfloat}{chapterlistsgaps}{% + \def\newfloat@chapterlistsgaps@value{#1}} +\providecommand*\@removefromreset[2]{{% + \expandafter\let\csname c@#1\endcsname\@removefromreset + \def\@elt##1{% + \expandafter\ifx\csname c@##1\endcsname\@removefromreset + \else + \noexpand\@elt{##1}% + \fi}% + \expandafter\xdef\csname cl@#2\endcsname{% + \csname cl@#2\endcsname}}} +\newcommand*\newfloat@announce[2]{% + \@cons\newfloat@list{{#1}}% + \@cons\newfloat@@list{{#1}}% + \newfloat@ifundefined{newfloat@ext@#2}{% + \@namedef{newfloat@ext@#2}{#1}% + \ifcsname c@lofdepth\endcsname + \newfloat@ifundefined{c@#2depth}{% + \newcounter{#2depth}% + \setcounter{#2depth}{1}}% + \fi + \ifcsname addtotoclist\endcsname + \addtotoclist[float]{#2}% + \newfloat@def{listof#2name}{\@nameuse{list#1name}}% + \fi + }% + \ifcsname contentsuse\endcsname + \contentsuse{#1}{#2}% + \fi + \newfloat@hook{#1}} +\@onlypreamble\newfloat@announce +\newcommand*\newfloat@@list{} +\newcommand*\SetupFloatingEnvironment[1]{% + \newfloat@addtolist{#1}% + \newfloat@setoptions{#1}} +\newcommand\ForEachFloatingEnvironment{% + \@ifstar + {\@ForEachFloatingEnvironment\@gobble}% + {\@ForEachFloatingEnvironment\@iden}} +\newcommand\@ForEachFloatingEnvironment[2]{% + \def\@elt##1{#2}% + \newfloat@list + \let\@elt\relax + #1{\newfloat@addtohook{#2}}} +\providecommand\newfloat@addtohook[1]{% + \toks@=\expandafter{\newfloat@hook{##1}#1}% + \edef\@tempa{\def\noexpand\newfloat@hook####1{\the\toks@}}% + \@tempa} +\providecommand*\newfloat@hook[1]{} +\newcommand\PrepareListOf[1]{% + \expandafter\g@addto@macro\csname newfloat@listof#1@hook\endcsname} +\@onlypreamble\PrepareListOf +\newcommand*\newfloat@list{} +\newcommand*\newfloat@addtolist[1]{% + \newfloat@ifinlist{#1}{}{% + \ifcsname ext@#1\endcsname + \@cons\newfloat@list{{#1}}% + \@namedef{newfloat@ext@\@nameuse{ext@#1}}{#1}% + \newfloat@let{@ifchapterlistsgap@#1}{\@iden}% + \else + \newfloat@Error{`#1' does not seem to be a floating environment}% + \fi}} +\newcommand*\newfloat@ifinlist[1]{% + \let\next\@secondoftwo + \begingroup + \expandafter\let\csname c@#1\endcsname\newfloat@ifinlist + \def\@elt##1{% + \expandafter\ifx\csname c@##1\endcsname\newfloat@ifinlist + \global\let\next\@firstoftwo + \fi}% + \newfloat@list + \endgroup + \next} +\ifcsname ext@figure\endcsname + \newfloat@addtolist{figure} +\fi +\ifcsname ext@table\endcsname + \newfloat@addtolist{table} +\fi +\ifcsname @chapter\endcsname + \providecommand*\@chapterlistsgap{10\p@}% + \providecommand*\@addchapterlistsgap[2]{% + \@nameuse{@ifchapterlistsgap@#1}{% if switched on + \@@addchapterlistsgap{#1}{#2}}} + \providecommand*\@@addchapterlistsgap[2]{% + \@ifundefined{@addchapterlistsgap@#2}{% only once per extension + \@namedef{@addchapterlistsgap@#2}{#1}% + \@@@addchapterlistsgap{#2}}{}} + \providecommand*\@@@addchapterlistsgap[1]{% + \ifdim \@chapterlistsgap>\z@ + \addtocontents{#1}{\protect\addvspace{\@chapterlistsgap}}% + \fi} + \providecommand*\@addchapterlistsgaps{% + \begingroup + \def\@elt##1{% + \@expandtwoargs\@addchapterlistsgap{##1}{\@nameuse{ext@##1}}}% + \newfloat@list + \endgroup} + \providecommand*\@chapterlistsgap@off[1]{% + \expandafter\let\csname @ifchapterlistsgap@#1\endcsname\@gobble + \ifcsname unsettoc\endcsname + \@expandtwoargs\unsettoc{\@nameuse{ext@#1}}{chapteratlist}% + \fi} + \providecommand*\@chapterlistsgap@on[1]{% + \expandafter\let\csname @ifchapterlistsgap@#1\endcsname\@iden + \ifcsname setuptoc\endcsname + \@expandtwoargs\setuptoc{\@nameuse{ext@#1}}{chapteratlist}% + \fi} +\fi +\define@key{newfloat}{chapterlistsgap}{% + \renewcommand*\@chapterlistsgap{#1}} +\define@key{newfloat}{within}{% + \def\newfloat@within@default{#1}% set new default value + \def\@elt##1{\newfloat@setwithin{##1}{#1}}% + \newfloat@list + \let\@elt\relax} +\define@key{newfloat}{without}[]{% + \KV@newfloat@within{none}} +\def\@elt#1{% + \define@key{newfloat}{#1name}{% + \newfloat@setname{#1}{##1}}% + \define@key{newfloat}{list#1name}{% + \newfloat@setname{list#1}{##1}}% + \define@key{newfloat}{#1within}{% + \newfloat@setwithin{#1}{##1}}% + \define@key{newfloat}{#1without}[]{% + \newfloat@setwithout{#1}}% +}% +\newfloat@list +\let\@elt\relax +\define@key{newfloat}{planb}[true]{% + \def\@tempa{#1}% + \def\@tempb{false}% + \ifx\@tempa\@tempb + \let\newfloat@ifplanb\@gobble + \else + \def\@tempb{true}% + \ifx\@tempa\@tempb + \let\newfloat@ifplanb\@iden + \else + \newfloat@Error{Invalid value `#1' for option `planb'}% + \fi + \fi} +\define@key{newfloat}{planb-fileext}{% + \newfloat@Info{Setting Plan B file extension to `#1'} + \xdef\newfloat@addtocontents@ext{#1}} + +\let\@tempc\relax +\@expandtwoargs\setkeys{newfloat}{planb,\@ptionlist{\@currname.\@currext}}% +\AtEndOfPackage{\let\@unprocessedoptions\relax} +\newcommand*\newfloatsetup{\setkeys{newfloat}} +\newcommand\newfloat@replace@chapter[2]{% + \begingroup + \let\if@twocolumn\iffalse + \let\if@mainmatter\iffalse + \let\if@thema\iffalse + \def\@tempa[##1]##2{#1}% + \ifx\@tempa\@chapter + \gdef\@chapter[##1]##2{#2}% + \global\let\newfloat@replace@chapter\@gobbletwo + \else\ifx\@tempa\Hy@org@chapter + \gdef\Hy@org@chapter[##1]##2{#2}% + \global\let\newfloat@replace@chapter\@gobbletwo + \fi\fi + \endgroup} +\ifcsname @chapter\endcsname \else + \let\newfloat@replace@chapter\@gobbletwo +\fi +\newfloat@replace@chapter{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}#1}% + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi +}{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}#1}% + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \chaptermark{#1}% + \@addchapterlistsgaps + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi} +\newfloat@replace@chapter{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}#1}% + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi +}{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}#1}% + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \chaptermark{#1}% + \@addchapterlistsgaps + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi} +\newfloat@replace@chapter{% + \refstepcounter{chapter}% + \ifnum\c@secnumdepth<\z@ \let\@secnumber\@empty + \else \let\@secnumber\thechapter \fi + \typeout{\chaptername\space\@secnumber}% + \def\@toclevel{0}% + \ifx\chaptername\appendixname \@tocwriteb\tocappendix{chapter}{#2}% + \else \@tocwriteb\tocchapter{chapter}{#2}\fi + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \@makechapterhead{#2}\@afterheading +}{% + \refstepcounter{chapter}% + \ifnum\c@secnumdepth<\z@ \let\@secnumber\@empty + \else \let\@secnumber\thechapter \fi + \typeout{\chaptername\space\@secnumber}% + \def\@toclevel{0}% + \ifx\chaptername\appendixname \@tocwriteb\tocappendix{chapter}{#2}% + \else \@tocwriteb\tocchapter{chapter}{#2}\fi + \chaptermark{#1}% + \@addchapterlistsgaps + \@makechapterhead{#2}\@afterheading} +\@ifpackageloaded{tocbasic}{% + \let\newfloat@replace@chapter\@gobbletwo}{} +\ifcsname insertchapterspace\endcsname + \renewcommand*\insertchapterspace{\@addchapterlistsgaps} + \let\newfloat@replace@chapter\@gobbletwo +\fi +\newfloat@replace@chapter{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}\toc@font0 #1}% + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi +}{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}\toc@font0 #1}% + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \chaptermark{#1}% + \@addchapterlistsgaps + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi} + % boek(3).cls [2004/06/07 v2.1a NTG LaTeX document class] +\newfloat@replace@chapter{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}\toc@font0 #1}% + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \chaptermark{#1}% + \addtocontents{lof}{\protect\addvspace{10\p@}}% + \addtocontents{lot}{\protect\addvspace{10\p@}}% + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi +}{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\@chapapp\space\thechapter.}% + \addcontentsline{toc}{chapter}% + {\protect\numberline{\thechapter}\toc@font0 #1}% + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \else + \addcontentsline{toc}{chapter}{\toc@font0 #1}% + \fi + \chaptermark{#1}% + \@addchapterlistsgaps + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi} +\newfloat@replace@chapter{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\chaptername\space\thechapter.} + \if@thema + \ifx\@shortauthor\@empty + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}#1}% + \else + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}% + \@shortauthor\hfill\mbox{}\vskip\normallineskip #1}% + \fi + \else + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}#1}% + \fi + \else + \addcontentsline{toc}{chapter}{#1} + \fi + \else + \addcontentsline{toc}{chapter}{#1} + \fi + \chaptermark{#1} + \addtocontents{lof}{\protect\addvspace{10pt}} + \addtocontents{lot}{\protect\addvspace{10pt}} + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}] + \else + \@makechapterhead{#2} + \@afterheading + \fi +}{% + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter + \refstepcounter{chapter}% + \typeout{\chaptername\space\thechapter.}% + \if@thema + \ifx\@shortauthor\@empty + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}#1}% + \else + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}% + \@shortauthor\hfill\mbox{}\vskip\normallineskip #1}% + \fi + \else + \addcontentsline{toc}{chapter}{% + \protect\numberline{\thechapter.}#1}% + \fi + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \else + \addcontentsline{toc}{chapter}{#1}% + \fi + \chaptermark{#1}% + \@addchapterlistsgaps + \if@twocolumn + \@topnewpage[\@makechapterhead{#2}]% + \else + \@makechapterhead{#2}% + \@afterheading + \fi} +\ifx\newfloat@replace@chapter\@gobbletwo \else + \newfloat@InfoNoLine{% + Unsupported document class, or \noexpand\@chapter\MessageBreak + was already redefined by another package} + \newfloat@InfoNoLine{\string\@chapter\space=\space\meaning\@chapter} + \newfloat@InfoNoLine{\string\Hy@org@chapter\space=\space\meaning\Hy@org@chapter} + \newfloat@ifplanb{% + \newfloat@InfoNoLine{Trying Plan B..}% + \let\newfloat@addtocontents@ORI\addtocontents + \long\def\addtocontents#1#2{% + \newfloat@addtocontents{#1}{#2}#2\addvspace\newfloat@nil}% + \long\def\newfloat@addtocontents#1#2#3\addvspace#4\newfloat@nil{% + \def\newfloat@tempa{#4}% + \ifx\newfloat@tempa\@empty + \newfloat@addtocontents@ORI{#1}{#2}% + \else + \ifx\newfloat@addtocontents@ext\@undefined + \newfloat@Info{Setting Plan B file extension to `#1'...}% + \xdef\newfloat@addtocontents@ext{#1}% + \fi + \edef\newfloat@tempa{#1}% + \ifx\newfloat@tempa\newfloat@addtocontents@ext + \begingroup + \let\addtocontents\newfloat@addtocontents@ORI + \@addchapterlistsgaps + \endgroup + \fi + \fi}} +\fi +\newcommand\newfloat@ForEachNew[2][newfloat@@list]{% + \AtBeginDocument{% + \ifcsname#1\endcsname + \def\@elt##1{#2}% + \newfloat@@list + \let\@elt\relax + \fi}}% +\@onlypreamble\newfloat@ForEachNew +%% \begin{macrocode} +\newfloat@ForEachNew[float@exts]{% + \@nameuse{@ifchapterlistsgap@#1}{% if switched on + \let\float@do=\relax + \edef\@tempa{% + \noexpand\float@exts{\the\float@exts\float@do{\@nameuse{ext@#1}}}}% + \@tempa}} +\newfloat@ForEachNew[FP@floatBegin]{% + \newcounter{FP@#1C}% + \newenvironment{FP#1}{\FP@floatBegin{#1}}{\FP@floatEnd}} +\providecommand*\ext@lstlisting{lol}% +\newfloat@ForEachNew[@rotfloat]{% + \newenvironment{sideways#1}{\@rotfloat{#1}}{\end@rotfloat}% + \newenvironment{sideways#1*}{\@rotdblfloat{#1}}{\end@rotdblfloat}} +\newcommand*\newfloat@For@SC[2]{% + \def#1{b}% = \sidecaptionvpos{#2}{b} (v1.6) + \newenvironment{SC#2}% + {\SC@float[#1]{#2}}{\endSC@float}% + \newenvironment{SC#2*}% + {\SC@dblfloat[#1]{#2}}{\endSC@dblfloat}} +\@onlypreamble\newfloat@For@SC +\newfloat@ForEachNew[SC@float]{% + \expandafter\newfloat@For@SC\csname SC@#1@vpos\endcsname{#1}} +\newfloat@ForEachNew[wrapfloat]{% + \newenvironment{wrap#1}{\wrapfloat{#1}}{\endwrapfloat}} +\endinput +%% +%% End of file `newfloat.sty'. diff --git a/release/latex/python.ist b/release/latex/python.ist new file mode 100644 index 0000000..9ffa0f9 --- /dev/null +++ b/release/latex/python.ist @@ -0,0 +1,11 @@ +line_max 100 +headings_flag 1 +heading_prefix " \\bigletter " + +preamble "\\begin{theindex} +\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}} + +" + +symhead_positive "{Symbols}" +numhead_positive "{Numbers}" diff --git a/release/latex/sphinx.sty b/release/latex/sphinx.sty new file mode 100644 index 0000000..ce17407 --- /dev/null +++ b/release/latex/sphinx.sty @@ -0,0 +1,641 @@ +% +% sphinx.sty +% +% Adapted from the old python.sty, mostly written by Fred Drake, +% by Georg Brandl. +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesPackage{sphinx}[2010/01/15 LaTeX package (Sphinx markup)] + +\@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}} + +\RequirePackage{textcomp} +\RequirePackage{fancybox} +\RequirePackage{titlesec} +\RequirePackage{tabulary} +\RequirePackage{makeidx} +\RequirePackage{framed} +\RequirePackage{ifthen} +%The xcolor package draws better fcolorboxes +%around verbatim code +\IfFileExists{xcolor.sty}{ + \RequirePackage{xcolor} +}{ + \RequirePackage{color} +} +% For highlighted code. +\RequirePackage{fancyvrb} +% For table captions. +\RequirePackage{threeparttable} +% Handle footnotes in tables. +\RequirePackage{footnote} +\makesavenoteenv{tabulary} +% For floating figures in the text. +\RequirePackage{wrapfig} +% Separate paragraphs by space by default. +\RequirePackage{parskip} +% For parsed-literal blocks. +\RequirePackage{alltt} +% Display "real" single quotes in literal blocks. +\RequirePackage{upquote} + +% Redefine these colors to your liking in the preamble. +\definecolor{TitleColor}{rgb}{0.126,0.263,0.361} +\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486} +\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388} +% Redefine these colors to something if you want to have colored +% background and border for code examples. +\definecolor{VerbatimColor}{rgb}{1,1,1} +\definecolor{VerbatimBorderColor}{rgb}{0,0,0} + +% Uncomment these two lines to ignore the paper size and make the page +% size more like a typical published manual. +%\renewcommand{\paperheight}{9in} +%\renewcommand{\paperwidth}{8.5in} % typical squarish manual +%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' + +% use pdfoutput for pTeX and dvipdfmx +% when pTeX (\kanjiskip is defined), set pdfoutput to evade \include{pdfcolor} +\ifx\kanjiskip\undefined\else + \newcount\pdfoutput\pdfoutput=0 +\fi + +\RequirePackage{graphicx} + +% for PDF output, use colors and maximal compression +\newif\ifsphinxpdfoutput\sphinxpdfoutputfalse +\ifx\pdfoutput\undefined\else\ifcase\pdfoutput + \let\py@NormalColor\relax + \let\py@TitleColor\relax +\else + \sphinxpdfoutputtrue + \input{pdfcolor} + \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} + \def\py@TitleColor{\color{TitleColor}} + \pdfcompresslevel=9 +\fi\fi + +% XeLaTeX can do colors, too +\ifx\XeTeXrevision\undefined\else + \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} + \def\py@TitleColor{\color{TitleColor}} +\fi + +% Increase printable page size (copied from fullpage.sty) +\topmargin 0pt +\advance \topmargin by -\headheight +\advance \topmargin by -\headsep + +% attempt to work a little better for A4 users +\textheight \paperheight +\advance\textheight by -2in + +\oddsidemargin 0pt +\evensidemargin 0pt +%\evensidemargin -.25in % for ``manual size'' documents +\marginparwidth 0.5in + +\textwidth \paperwidth +\advance\textwidth by -2in + + +% Style parameters and macros used by most documents here +\raggedbottom +\sloppy +\hbadness = 5000 % don't print trivial gripes + +\pagestyle{empty} % start this way + +% Use this to set the font family for headers and other decor: +\newcommand{\py@HeaderFamily}{\sffamily\bfseries} + +% Redefine the 'normal' header/footer style when using "fancyhdr" package: +\@ifundefined{fancyhf}{}{ + % Use \pagestyle{normal} as the primary pagestyle for text. + \fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} + \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} + \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} + \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} + % define chaptermark with \@chappos when \@chappos is available for Japanese + \ifx\@chappos\undefined\else + \def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}} + \fi + } + % Update the plain style so we get the page number & footer line, + % but not a chapter or section title. This is to keep the first + % page of a chapter and the blank page between chapters `clean.' + \fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0.4pt} + } +} + +% Some custom font markup commands. +% +\newcommand{\strong}[1]{{\textbf{#1}}} +\newcommand{\code}[1]{\texttt{#1}} +\newcommand{\bfcode}[1]{\code{\bfseries#1}} +\newcommand{\email}[1]{\textsf{#1}} +\newcommand{\tablecontinued}[1]{\textsf{#1}} +\newcommand{\titleref}[1]{\emph{#1}} +\newcommand{\menuselection}[1]{\emph{#1}} +\newcommand{\accelerator}[1]{\underline{#1}} +\newcommand{\crossref}[1]{\emph{#1}} +\newcommand{\termref}[1]{\emph{#1}} + +\newcommand*{\sphinxAtStartFootnote}{\mbox{ }} + +% Redefine the Verbatim environment to allow border and background colors. +% The original environment is still used for verbatims within tables. +\let\OriginalVerbatim=\Verbatim +\let\endOriginalVerbatim=\endVerbatim + +% Play with vspace to be able to keep the indentation. +\newlength\Sphinx@scratchlength +\newcommand\Sphinxcolorbox [1]{% + \setlength\Sphinx@scratchlength{\linewidth}% + \advance\Sphinx@scratchlength -\@totalleftmargin % + \fcolorbox{VerbatimBorderColor}{VerbatimColor}{% + \begin{minipage}{\Sphinx@scratchlength}% + #1 + \end{minipage}% + }% +} +% used for split frames for continuation on next and final page +\def\MidFrameCommand{\Sphinxcolorbox} +\let\LastFrameCommand\MidFrameCommand + +% We customize \FrameCommand (for non split frames) and \FirstFrameCommand +% (split frames), in order for the framed environment to insert a Title above +% the frame, which can not be separated by a pagebreak. + +% The title is specified from outside as macro \SphinxVerbatimTitle. +% \SphinxVerbatimTitle is reset to empty after each use of Verbatim environment. + +% It is also possible to use directly framed environment (i.e. not indirectly +% via the Verbatim environment next), then it is \SphinxFrameTitle which specifies +% the title. +\newcommand*\SphinxFrameTitle {} +\newcommand*\SphinxVerbatimTitle {} +\newcommand*\SphinxSetupCaptionForVerbatim [2] +{% + \needspace{\literalblockneedspace}\vspace{\literalblockcaptiontopvspace}% + \def\SphinxVerbatimTitle + {\captionof{#1}{\SphinxLiteralBlockLabel #2}\smallskip }% +} +% \SphinxLiteralBlockLabel will be set dynamically to hold the label for links +\newcommand*\SphinxLiteralBlockLabel {} + +% \SphinxCustomFBox is copied from framed.sty's \CustomFBox, but +% #1=title/caption is to be set _above_ the top rule, not _below_ +% #1 must be "vertical material", it may be left empty. + +% The amsmath patches \stepcounter to inhibit stepping under +% \firstchoice@false. We use it because framed.sty typesets multiple +% times its contents. +\newif\ifSphinx@myfirstframedpass + +\long\def\SphinxCustomFBox#1#2#3#4#5#6#7{% + % we set up amsmath (amstext.sty) conditional to inhibit counter stepping + % except in first pass + \ifSphinx@myfirstframedpass\firstchoice@true + \else\firstchoice@false\fi + \leavevmode\begingroup + \setbox\@tempboxa\hbox{% + \color@begingroup + \kern\fboxsep{#7}\kern\fboxsep + \color@endgroup}% + \hbox{% + \lower\dimexpr#4+\fboxsep+\dp\@tempboxa\hbox{% + \vbox{% + #1% TITLE + \hrule\@height#3\relax + \hbox{% + \vrule\@width#5\relax + \vbox{% + \vskip\fboxsep + \copy\@tempboxa + \vskip\fboxsep}% + \vrule\@width#6\relax}% + #2% + \hrule\@height#4\relax}% + }% + }% + \endgroup + \global\Sphinx@myfirstframedpassfalse +} + +% for non split frames: +\def\FrameCommand{% + % this is inspired from framed.sty v 0.96 2011/10/22 lines 185--190 + % \fcolorbox (see \Sphinxcolorbox above) from color.sty uses \fbox. + \def\fbox{\SphinxCustomFBox{\SphinxFrameTitle}{}% + \fboxrule\fboxrule\fboxrule\fboxrule}% + % \fcolorbox from xcolor.sty may use rather \XC@fbox. + \let\XC@fbox\fbox + \Sphinxcolorbox +} +% for first portion of split frames: +\let\FirstFrameCommand\FrameCommand + +\renewcommand{\Verbatim}[1][1]{% + % list starts new par, but we don't want it to be set apart vertically + \parskip\z@skip + \smallskip + % first, let's check if there is a caption + \ifx\SphinxVerbatimTitle\empty + % there was no caption. Check if nevertheless a label was set. + \ifx\SphinxLiteralBlockLabel\empty\else + % we require some space to be sure hyperlink target from \phantomsection + % will not be separated from upcoming verbatim by a page break + \needspace{\literalblockwithoutcaptionneedspace}% + \phantomsection\SphinxLiteralBlockLabel + \fi + \fi + % non-empty \SphinxVerbatimTitle has label inside it (in case there is one) + \let\SphinxFrameTitle\SphinxVerbatimTitle + \global\Sphinx@myfirstframedpasstrue + % The list environement is needed to control perfectly the vertical + % space. + \list{}{% + \setlength\parskip{0pt}% + \setlength\itemsep{0ex}% + \setlength\topsep{0ex}% + \setlength\partopsep{0pt}% + \setlength\leftmargin{0pt}% + }% + \item\MakeFramed {\FrameRestore}% + \small + \OriginalVerbatim[#1]% +} +\renewcommand{\endVerbatim}{% + \endOriginalVerbatim + \endMakeFramed + \endlist + % LaTeX environments always revert local changes on exit, here e.g. \parskip +} + + +% \moduleauthor{name}{email} +\newcommand{\moduleauthor}[2]{} + +% \sectionauthor{name}{email} +\newcommand{\sectionauthor}[2]{} + +% Augment the sectioning commands used to get our own font family in place, +% and reset some internal data items: +\titleformat{\section}{\Large\py@HeaderFamily}% + {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsection}{\large\py@HeaderFamily}% + {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsubsection}{\py@HeaderFamily}% + {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\paragraph}{\small\py@HeaderFamily}% + {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} + +% {fulllineitems} is the main environment for object descriptions. +% +\newcommand{\py@itemnewline}[1]{% + \@tempdima\linewidth% + \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% +} + +\newenvironment{fulllineitems}{ + \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt + \rightmargin 0pt \topsep -\parskip \partopsep \parskip + \itemsep -\parsep + \let\makelabel=\py@itemnewline} +}{\end{list}} + +% \optional is used for ``[, arg]``, i.e. desc_optional nodes. +\newcommand{\optional}[1]{% + {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} + +\newlength{\py@argswidth} +\newcommand{\py@sigparams}[2]{% + \parbox[t]{\py@argswidth}{#1\code{)}#2}} +\newcommand{\pysigline}[1]{\item[#1]\nopagebreak} +\newcommand{\pysiglinewithargsret}[3]{% + \settowidth{\py@argswidth}{#1\code{(}}% + \addtolength{\py@argswidth}{-2\py@argswidth}% + \addtolength{\py@argswidth}{\linewidth}% + \item[#1\code{(}\py@sigparams{#2}{#3}]} + +% Production lists +% +\newenvironment{productionlist}{ +% \def\optional##1{{\Large[}##1{\Large]}} + \def\production##1##2{\\\code{##1}&::=&\code{##2}} + \def\productioncont##1{\\& &\code{##1}} + \parindent=2em + \indent + \setlength{\LTpre}{0pt} + \setlength{\LTpost}{0pt} + \begin{longtable}[l]{lcl} +}{% + \end{longtable} +} + +% Notices / Admonitions +% +\newlength{\py@noticelength} + +\newcommand{\py@heavybox}{ + \setlength{\fboxrule}{1pt} + \setlength{\fboxsep}{6pt} + \setlength{\py@noticelength}{\linewidth} + \addtolength{\py@noticelength}{-2\fboxsep} + \addtolength{\py@noticelength}{-2\fboxrule} + %\setlength{\shadowsize}{3pt} + \noindent\Sbox + \minipage{\py@noticelength} +} +\newcommand{\py@endheavybox}{ + \endminipage + \endSbox + \fbox{\TheSbox} +} + +\newcommand{\py@lightbox}{% + \par\allowbreak + \noindent\rule{\linewidth}{0.5pt}\par\nobreak + {\parskip\z@skip\noindent}% + } +\newcommand{\py@endlightbox}{% + \par\nobreak + {\parskip\z@skip\noindent\rule[.4\baselineskip]{\linewidth}{0.5pt}}\par + } + +% Some are quite plain: +\newcommand{\py@noticestart@note}{\py@lightbox} +\newcommand{\py@noticeend@note}{\py@endlightbox} +\newcommand{\py@noticestart@hint}{\py@lightbox} +\newcommand{\py@noticeend@hint}{\py@endlightbox} +\newcommand{\py@noticestart@important}{\py@lightbox} +\newcommand{\py@noticeend@important}{\py@endlightbox} +\newcommand{\py@noticestart@tip}{\py@lightbox} +\newcommand{\py@noticeend@tip}{\py@endlightbox} + +% Others gets more visible distinction: +\newcommand{\py@noticestart@warning}{\py@heavybox} +\newcommand{\py@noticeend@warning}{\py@endheavybox} +\newcommand{\py@noticestart@caution}{\py@heavybox} +\newcommand{\py@noticeend@caution}{\py@endheavybox} +\newcommand{\py@noticestart@attention}{\py@heavybox} +\newcommand{\py@noticeend@attention}{\py@endheavybox} +\newcommand{\py@noticestart@danger}{\py@heavybox} +\newcommand{\py@noticeend@danger}{\py@endheavybox} +\newcommand{\py@noticestart@error}{\py@heavybox} +\newcommand{\py@noticeend@error}{\py@endheavybox} + +\newenvironment{notice}[2]{ + \def\py@noticetype{#1} + \csname py@noticestart@#1\endcsname + \strong{#2} +}{\csname py@noticeend@\py@noticetype\endcsname} + +% Allow the release number to be specified independently of the +% \date{}. This allows the date to reflect the document's date and +% release to specify the release that is documented. +% +\newcommand{\py@release}{} +\newcommand{\version}{} +\newcommand{\shortversion}{} +\newcommand{\releaseinfo}{} +\newcommand{\releasename}{Release} +\newcommand{\release}[1]{% + \renewcommand{\py@release}{\releasename\space\version}% + \renewcommand{\version}{#1}} +\newcommand{\setshortversion}[1]{% + \renewcommand{\shortversion}{#1}} +\newcommand{\setreleaseinfo}[1]{% + \renewcommand{\releaseinfo}{#1}} + +% Allow specification of the author's address separately from the +% author's name. This can be used to format them differently, which +% is a good thing. +% +\newcommand{\py@authoraddress}{} +\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} + +% This sets up the fancy chapter headings that make the documents look +% at least a little better than the usual LaTeX output. +% +\@ifundefined{ChTitleVar}{}{ + \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} + \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} + \ChTitleVar{\raggedleft \textrm{\Huge\py@HeaderFamily}} + % This creates chapter heads without the leading \vspace*{}: + \def\@makechapterhead#1{% + {\parindent \z@ \raggedright \normalfont + \ifnum \c@secnumdepth >\m@ne + \DOCH + \fi + \interlinepenalty\@M + \DOTI{#1} + } + } +} + +% Redefine description environment so that it is usable inside fulllineitems. +% +\renewcommand{\description}{% + \list{}{\labelwidth\z@% + \itemindent-\leftmargin% + \labelsep5pt% + \let\makelabel=\descriptionlabel}} + +% Definition lists; requested by AMK for HOWTO documents. Probably useful +% elsewhere as well, so keep in in the general style support. +% +\newenvironment{definitions}{% + \begin{description}% + \def\term##1{\item[##1]\mbox{}\\*[0mm]} +}{% + \end{description}% +} + +% Tell TeX about pathological hyphenation cases: +\hyphenation{Base-HTTP-Re-quest-Hand-ler} + + +% The following is stuff copied from docutils' latex writer. +% +\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} +\newenvironment{optionlist}[1] +{\begin{list}{} + {\setlength{\labelwidth}{#1} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\optionlistlabel}} +}{\end{list}} + +\newlength{\lineblockindentation} +\setlength{\lineblockindentation}{2.5em} +\newenvironment{lineblock}[1] +{\begin{list}{} + {\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \topsep0pt\itemsep0.15\baselineskip\parsep0pt + \leftmargin#1} + \raggedright} +{\end{list}} + +% Redefine includgraphics for avoiding images larger than the screen size +% If the size is not specified. +\let\py@Oldincludegraphics\includegraphics + +\newbox\image@box% +\newdimen\image@width% +\renewcommand\includegraphics[2][\@empty]{% + \ifx#1\@empty% + \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}% + \image@width\wd\image@box% + \ifdim \image@width>\linewidth% + \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}% + \box\image@box% + \else% + \py@Oldincludegraphics{#2}% + \fi% + \else% + \py@Oldincludegraphics[#1]{#2}% + \fi% +} + +% to make pdf with correct encoded bookmarks in Japanese +% this should precede the hyperref package +\ifx\kanjiskip\undefined\else + \usepackage{atbegshi} + \ifx\ucs\undefined + \ifnum 42146=\euc"A4A2 + \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}} + \else + \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}} + \fi + \else + \AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}} + \fi +\fi + +% Include hyperref last. +\RequirePackage[colorlinks,breaklinks, + linkcolor=InnerLinkColor,filecolor=OuterLinkColor, + menucolor=OuterLinkColor,urlcolor=OuterLinkColor, + citecolor=InnerLinkColor]{hyperref} +% Fix anchor placement for figures with captions. +% (Note: we don't use a package option here; instead, we give an explicit +% \capstart for figures that actually have a caption.) +\RequirePackage{hypcap} + +% Set up styles of URL: it should be placed after hyperref +\urlstyle{same} + +% From docutils.writers.latex2e +% inline markup (custom roles) +% \DUrole{#1}{#2} tries \DUrole#1{#2} +\providecommand*{\DUrole}[2]{% + \ifcsname DUrole#1\endcsname% + \csname DUrole#1\endcsname{#2}% + \else% backwards compatibility: try \docutilsrole#1{#2} + \ifcsname docutilsrole#1\endcsname% + \csname docutilsrole#1\endcsname{#2}% + \else% + #2% + \fi% + \fi% +} + +\providecommand*{\DUprovidelength}[2]{ + \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} +} + +\DUprovidelength{\DUlineblockindent}{2.5em} +\ifthenelse{\isundefined{\DUlineblock}}{ + \newenvironment{DUlineblock}[1]{% + \list{}{\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \setlength{\topsep}{0pt} + \setlength{\itemsep}{0.15\baselineskip} + \setlength{\parsep}{0pt} + \setlength{\leftmargin}{#1}} + \raggedright + } + {\endlist} +}{} + + +% From footmisc.sty: allows footnotes in titles +\let\FN@sf@@footnote\footnote +\def\footnote{\ifx\protect\@typeset@protect + \expandafter\FN@sf@@footnote + \else + \expandafter\FN@sf@gobble@opt + \fi +} +\edef\FN@sf@gobble@opt{\noexpand\protect + \expandafter\noexpand\csname FN@sf@gobble@opt \endcsname} +\expandafter\def\csname FN@sf@gobble@opt \endcsname{% + \@ifnextchar[%] + \FN@sf@gobble@twobracket + \@gobble +} +\def\FN@sf@gobble@twobracket[#1]#2{} + +% adjust the margins for footer, +% this works with the jsclasses only (Japanese standard document classes) +\ifx\@jsc@uplatextrue\undefined\else + \hypersetup{setpagesize=false} + \setlength\footskip{2\baselineskip} + \addtolength{\textheight}{-2\baselineskip} +\fi + +% fix the double index and bibliography on the table of contents +% in jsclasses (Japanese standard document classes) +\ifx\@jsc@uplatextrue\undefined\else + \renewcommand{\theindex}{ + \cleardoublepage + \phantomsection + \py@OldTheindex + } + \renewcommand{\thebibliography}[1]{ + \cleardoublepage + \phantomsection + \py@OldThebibliography{1} + } +\fi + +% disable \@chappos in Appendix in pTeX +\ifx\kanjiskip\undefined\else + \let\py@OldAppendix=\appendix + \renewcommand{\appendix}{ + \py@OldAppendix + \gdef\@chappos{} + } +\fi + +% Define literal-block environment +\RequirePackage{newfloat} +\DeclareFloatingEnvironment{literal-block} +\ifx\thechapter\undefined + \SetupFloatingEnvironment{literal-block}{within=section,placement=h} +\else + \SetupFloatingEnvironment{literal-block}{within=chapter,placement=h} +\fi +\SetupFloatingEnvironment{literal-block}{name=List} +% control caption around literal-block +\RequirePackage{capt-of} +\RequirePackage{needspace} +% if the left page space is less than \literalblockneedsapce, insert page-break +\newcommand{\literalblockneedspace}{5\baselineskip} +\newcommand{\literalblockwithoutcaptionneedspace}{1.5\baselineskip} +% margin before the caption of literal-block +\newcommand{\literalblockcaptiontopvspace}{0.5\baselineskip} diff --git a/release/latex/sphinxhowto.cls b/release/latex/sphinxhowto.cls new file mode 100644 index 0000000..26e63a7 --- /dev/null +++ b/release/latex/sphinxhowto.cls @@ -0,0 +1,104 @@ +% +% sphinxhowto.cls for Sphinx (http://sphinx-doc.org/) +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesClass{sphinxhowto}[2009/06/02 Document class (Sphinx HOWTO)] + +% 'oneside' option overriding the 'twoside' default +\newif\if@oneside +\DeclareOption{oneside}{\@onesidetrue} +% Pass remaining document options to the parent class. +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{\sphinxdocclass}} +\ProcessOptions\relax + +% Default to two-side document +\if@oneside +% nothing to do (oneside is the default) +\else +\PassOptionsToClass{twoside}{\sphinxdocclass} +\fi + +\LoadClass{\sphinxdocclass} + +% Set some sane defaults for section numbering depth and TOC depth. You can +% reset these counters in your preamble. +% +\setcounter{secnumdepth}{2} + +% Change the title page to look a bit better, and fit in with the fncychap +% ``Bjarne'' style a bit better. +% +\renewcommand{\maketitle}{ + \rule{\textwidth}{1pt} + \ifsphinxpdfoutput + \begingroup + % These \defs are required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \def\and{and } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright} + \sphinxlogo% + {\rm\Huge\py@HeaderFamily \@title} \par + {\em\large\py@HeaderFamily \py@release\releaseinfo} \par + \vspace{25pt} + {\Large\py@HeaderFamily + \begin{tabular}[t]{c} + \@author + \end{tabular}} \par + \vspace{25pt} + \@date \par + \py@authoraddress \par + \end{flushright} + \@thanks + \setcounter{footnote}{0} + \let\thanks\relax\let\maketitle\relax + %\gdef\@thanks{}\gdef\@author{}\gdef\@title{} +} + +\let\py@OldTableofcontents=\tableofcontents +\renewcommand{\tableofcontents}{ + \begingroup + \parskip = 0mm + \py@OldTableofcontents + \endgroup + \rule{\textwidth}{1pt} + \vspace{12pt} +} + +\@ifundefined{fancyhf}{ + \pagestyle{plain}}{ + \pagestyle{normal}} % start this way; change for +\pagenumbering{arabic} % ToC & chapters + +\thispagestyle{empty} + +% Fix the bibliography environment to add an entry to the Table of +% Contents. +% For an article document class this environment is a section, +% so no page break before it. +\let\py@OldThebibliography=\thebibliography +\renewcommand{\thebibliography}[1]{ + \phantomsection + \py@OldThebibliography{1} + \addcontentsline{toc}{section}{\bibname} +} + +% Same for the indices. +% The memoir class already does this, so we don't duplicate it in that case. +% +\@ifclassloaded{memoir}{}{ + \let\py@OldTheindex=\theindex + \renewcommand{\theindex}{ + \phantomsection + \py@OldTheindex + \addcontentsline{toc}{section}{\indexname} + } +} diff --git a/release/latex/sphinxmanual.cls b/release/latex/sphinxmanual.cls new file mode 100644 index 0000000..a6b9b39 --- /dev/null +++ b/release/latex/sphinxmanual.cls @@ -0,0 +1,148 @@ +% +% sphinxmanual.cls for Sphinx (http://sphinx-doc.org/) +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesClass{sphinxmanual}[2009/06/02 Document class (Sphinx manual)] + +% chapters starting at odd pages (overridden by 'openany' document option) +\PassOptionsToClass{openright}{\sphinxdocclass} + +% 'oneside' option overriding the 'twoside' default +\newif\if@oneside +\DeclareOption{oneside}{\@onesidetrue} +% Pass remaining document options to the parent class. +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{\sphinxdocclass}} +\ProcessOptions\relax + +% Defaults two-side document +\if@oneside +% nothing to do (oneside is the default) +\else +\PassOptionsToClass{twoside}{\sphinxdocclass} +\fi + +\LoadClass{\sphinxdocclass} + +% Set some sane defaults for section numbering depth and TOC depth. You can +% reset these counters in your preamble. +% +\setcounter{secnumdepth}{2} +\setcounter{tocdepth}{1} + +% Change the title page to look a bit better, and fit in with the fncychap +% ``Bjarne'' style a bit better. +% +\renewcommand{\maketitle}{% + \begin{titlepage}% + \let\footnotesize\small + \let\footnoterule\relax + \rule{\textwidth}{1pt}% + \ifsphinxpdfoutput + \begingroup + % These \defs are required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \def\and{and } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright}% + \sphinxlogo% + {\rm\Huge\py@HeaderFamily \@title \par}% + {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par} + \vfill + {\LARGE\py@HeaderFamily + \begin{tabular}[t]{c} + \@author + \end{tabular} + \par} + \vfill\vfill + {\large + \@date \par + \vfill + \py@authoraddress \par + }% + \end{flushright}%\par + \@thanks + \end{titlepage}% + \cleardoublepage% + \setcounter{footnote}{0}% + \let\thanks\relax\let\maketitle\relax + %\gdef\@thanks{}\gdef\@author{}\gdef\@title{} +} + + +% Catch the end of the {abstract} environment, but here make sure the abstract +% is followed by a blank page if the 'openright' option is used. +% +\let\py@OldEndAbstract=\endabstract +\renewcommand{\endabstract}{ + \if@openright + \ifodd\value{page} + \typeout{Adding blank page after the abstract.} + \vfil\pagebreak + \fi + \fi + \py@OldEndAbstract +} + +% This wraps the \tableofcontents macro with all the magic to get the spacing +% right and have the right number of pages if the 'openright' option has been +% used. This eliminates a fair amount of crud in the individual document files. +% +\let\py@OldTableofcontents=\tableofcontents +\renewcommand{\tableofcontents}{% + \pagenumbering{roman}% + \setcounter{page}{1}% + \pagebreak% + \pagestyle{plain}% + {% + \parskip = 0mm% + \py@OldTableofcontents% + \if@openright% + \ifodd\value{page}% + \typeout{Adding blank page after the table of contents.}% + \pagebreak\hspace{0pt}% + \fi% + \fi% + \cleardoublepage% + }% + \pagenumbering{arabic}% + \@ifundefined{fancyhf}{}{\pagestyle{normal}}% +} +\pagenumbering{alph} + +% This is needed to get the width of the section # area wide enough in the +% library reference. Doing it here keeps it the same for all the manuals. +% +\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}} +\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}} + +% Fix the bibliography environment to add an entry to the Table of +% Contents. +% For a report document class this environment is a chapter. +\let\py@OldThebibliography=\thebibliography +\renewcommand{\thebibliography}[1]{ + \cleardoublepage + \phantomsection + \py@OldThebibliography{1} + \addcontentsline{toc}{chapter}{\bibname} +} + +% Same for the indices. +% The memoir class already does this, so we don't duplicate it in that case. +% +\@ifclassloaded{memoir}{}{ + \let\py@OldTheindex=\theindex + \renewcommand{\theindex}{ + \cleardoublepage + \phantomsection + \py@OldTheindex + \addcontentsline{toc}{chapter}{\indexname} + } +} diff --git a/release/latex/tabulary.sty b/release/latex/tabulary.sty new file mode 100644 index 0000000..11fdf74 --- /dev/null +++ b/release/latex/tabulary.sty @@ -0,0 +1,452 @@ +%% +%% This is file `tabulary.sty', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% tabulary.dtx (with options: `package') +%% DRAFT VERSION +%% +%% File `tabulary.dtx'. +%% Copyright (C) 1995 1996 2003 2008 David Carlisle +%% This file may be distributed under the terms of the LPPL. +%% See 00readme.txt for details. +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{tabulary} + [2008/12/01 v0.9 tabulary package (DPC)] +\RequirePackage{array} +\catcode`\Z=14 +\DeclareOption{debugshow}{\catcode`\Z=9\relax} +\ProcessOptions +\def\arraybackslash{\let\\=\@arraycr} +\def\@finalstrut#1{% + \unskip\ifhmode\nobreak\fi\vrule\@width\z@\@height\z@\@depth\dp#1} +\newcount\TY@count +\def\tabulary{% + \let\TY@final\tabular + \let\endTY@final\endtabular + \TY@tabular} +\def\TY@tabular#1{% + \edef\TY@{\@currenvir}% + {\ifnum0=`}\fi + \@ovxx\TY@linewidth + \@ovyy\TY@tablewidth + \count@\z@ + \@tempswatrue + \@whilesw\if@tempswa\fi{% + \advance\count@\@ne + \expandafter\ifx\csname TY@F\the\count@\endcsname\relax + \@tempswafalse + \else + \expandafter\let\csname TY@SF\the\count@\expandafter\endcsname + \csname TY@F\the\count@\endcsname + \global\expandafter\let\csname TY@F\the\count@\endcsname\relax + \expandafter\let\csname TY@S\the\count@\expandafter\endcsname + \csname TY@\the\count@\endcsname + \fi}% + \global\TY@count\@ne + \TY@width\xdef{0pt}% + \global\TY@tablewidth\z@ + \global\TY@linewidth#1\relax +Z\message{^^J^^JTable^^J% +Z Target Width: \the\TY@linewidth^^J% +Z \string\tabcolsep: \the\tabcolsep\space +Z \string\arrayrulewidth: \the\arrayrulewidth\space +Z \string\doublerulesep: \the\doublerulesep^^J% +Z \string\tymin: \the\tymin\space +Z \string\tymax: \the\tymax^^J}% + \let\@classz\TY@classz + \let\verb\TX@verb + \toks@{}\TY@get@body} +\let\TY@@mkpream\@mkpream +\def\TY@mkpream{% + \def\@addamp{% + \if@firstamp \@firstampfalse \else + \global\advance\TY@count\@ne + \edef\@preamble{\@preamble &}\fi + \TY@width\xdef{0pt}}% + \def\@acol{% + \TY@subwidth\col@sep + \@addtopreamble{\hskip\col@sep}}% + \let\@arrayrule\TY@arrayrule + \let\@classvi\TY@classvi + \def\@classv{\save@decl + \expandafter\NC@ecs\@nextchar\extracolsep{}\extracolsep\@@@ + \sbox\z@{\d@llarbegin\@nextchar\d@llarend}% + \TY@subwidth{\wd\z@}% + \@addtopreamble{\d@llarbegin\the@toks\the\count@\relax\d@llarend}% + \prepnext@tok}% + \global\let\@mkpream\TY@@mkpream + \TY@@mkpream} +\def\TY@arrayrule{% + \TY@subwidth\arrayrulewidth + \@addtopreamble \vline} +\def\TY@classvi{\ifcase \@lastchclass + \@acol \or + \TY@subwidth\doublerulesep + \@addtopreamble{\hskip \doublerulesep}\or + \@acol \or + \@classvii + \fi} +\def\TY@tab{% + \setbox\z@\hbox\bgroup + \let\[$\let\]$% + \let\equation$\let\endequation$% + \col@sep\tabcolsep + \let\d@llarbegin\begingroup\let\d@llarend\endgroup + \let\@mkpream\TY@mkpream + \def\multicolumn##1##2##3{\multispan##1\relax}% + \CT@start\TY@tabarray} +\def\TY@tabarray{\@ifnextchar[{\TY@array}{\@array[t]}} +\def\TY@array[#1]{\@array[t]} +\def\TY@width#1{% + \expandafter#1\csname TY@\the\TY@count\endcsname} +\def\TY@subwidth#1{% + \TY@width\dimen@ + \advance\dimen@-#1\relax + \TY@width\xdef{\the\dimen@}% + \global\advance\TY@linewidth-#1\relax} +\def\endtabulary{% + \gdef\@halignto{}% + \let\TY@footnote\footnote% + \def\footnote{}% prevent footnotes from doing anything + \expandafter\TY@tab\the\toks@ + \crcr\omit + {\xdef\TY@save@row{}% + \loop + \advance\TY@count\m@ne + \ifnum\TY@count>\z@ + \xdef\TY@save@row{\TY@save@row&\omit}% + \repeat}\TY@save@row + \endarray\global\setbox1=\lastbox\setbox0=\vbox{\unvbox1 + \unskip\global\setbox1=\lastbox}\egroup + \dimen@\TY@linewidth + \divide\dimen@\TY@count + \ifdim\dimen@<\tymin + \TY@warn{tymin too large (\the\tymin), resetting to \the\dimen@}% + \tymin\dimen@ + \fi + \setbox\tw@=\hbox{\unhbox\@ne + \loop +\@tempdima=\lastskip +\ifdim\@tempdima>\z@ +Z \message{ecs=\the\@tempdima^^J}% + \global\advance\TY@linewidth-\@tempdima +\fi + \unskip + \setbox\tw@=\lastbox + \ifhbox\tw@ +Z \message{Col \the\TY@count: Initial=\the\wd\tw@\space}% + \ifdim\wd\tw@>\tymax + \wd\tw@\tymax +Z \message{> max\space}% +Z \else +Z \message{ \@spaces\space}% + \fi + \TY@width\dimen@ +Z \message{\the\dimen@\space}% + \advance\dimen@\wd\tw@ +Z \message{Final=\the\dimen@\space}% + \TY@width\xdef{\the\dimen@}% + \ifdim\dimen@<\tymin +Z \message{< tymin}% + \global\advance\TY@linewidth-\dimen@ + \expandafter\xdef\csname TY@F\the\TY@count\endcsname + {\the\dimen@}% + \else + \expandafter\ifx\csname TY@F\the\TY@count\endcsname\z@ +Z \message{***}% + \global\advance\TY@linewidth-\dimen@ + \expandafter\xdef\csname TY@F\the\TY@count\endcsname + {\the\dimen@}% + \else +Z \message{> tymin}% + \global\advance\TY@tablewidth\dimen@ + \global\expandafter\let\csname TY@F\the\TY@count\endcsname + \maxdimen + \fi\fi + \advance\TY@count\m@ne + \repeat}% + \TY@checkmin + \TY@checkmin + \TY@checkmin + \TY@checkmin + \TY@count\z@ + \let\TY@box\TY@box@v + \let\footnote\TY@footnote % restore footnotes + {\expandafter\TY@final\the\toks@\endTY@final}% + \count@\z@ + \@tempswatrue + \@whilesw\if@tempswa\fi{% + \advance\count@\@ne + \expandafter\ifx\csname TY@SF\the\count@\endcsname\relax + \@tempswafalse + \else + \global\expandafter\let\csname TY@F\the\count@\expandafter\endcsname + \csname TY@SF\the\count@\endcsname + \global\expandafter\let\csname TY@\the\count@\expandafter\endcsname + \csname TY@S\the\count@\endcsname + \fi}% + \TY@linewidth\@ovxx + \TY@tablewidth\@ovyy + \ifnum0=`{\fi}} +\def\TY@checkmin{% + \let\TY@checkmin\relax +\ifdim\TY@tablewidth>\z@ + \Gscale@div\TY@ratio\TY@linewidth\TY@tablewidth + \ifdim\TY@tablewidth <\TY@linewidth + \def\TY@ratio{1}% + \fi +\else + \TY@warn{No suitable columns!}% + \def\TY@ratio{1}% +\fi +\count@\z@ +Z \message{^^JLine Width: \the\TY@linewidth, +Z Natural Width: \the\TY@tablewidth, +Z Ratio: \TY@ratio^^J}% +\@tempdima\z@ +\loop +\ifnum\count@<\TY@count +\advance\count@\@ne + \ifdim\csname TY@F\the\count@\endcsname>\tymin + \dimen@\csname TY@\the\count@\endcsname + \dimen@\TY@ratio\dimen@ + \ifdim\dimen@<\tymin +Z \message{Column \the\count@\space ->}% + \global\expandafter\let\csname TY@F\the\count@\endcsname\tymin + \global\advance\TY@linewidth-\tymin + \global\advance\TY@tablewidth-\csname TY@\the\count@\endcsname + \let\TY@checkmin\TY@@checkmin + \else + \expandafter\xdef\csname TY@F\the\count@\endcsname{\the\dimen@}% + \advance\@tempdima\csname TY@F\the\count@\endcsname + \fi + \fi +Z \dimen@\csname TY@F\the\count@\endcsname\message{\the\dimen@, }% +\repeat +Z \message{^^JTotal:\the\@tempdima^^J}% +} +\let\TY@@checkmin\TY@checkmin +\newdimen\TY@linewidth +\def\tyformat{\everypar{{\nobreak\hskip\z@skip}}} +\newdimen\tymin +\tymin=10pt +\newdimen\tymax +\tymax=2\textwidth +\def\@testpach{\@chclass + \ifnum \@lastchclass=6 \@ne \@chnum \@ne \else + \ifnum \@lastchclass=7 5 \else + \ifnum \@lastchclass=8 \tw@ \else + \ifnum \@lastchclass=9 \thr@@ + \else \z@ + \ifnum \@lastchclass = 10 \else + \edef\@nextchar{\expandafter\string\@nextchar}% + \@chnum + \if \@nextchar c\z@ \else + \if \@nextchar l\@ne \else + \if \@nextchar r\tw@ \else + \if \@nextchar C7 \else + \if \@nextchar L8 \else + \if \@nextchar R9 \else + \if \@nextchar J10 \else + \z@ \@chclass + \if\@nextchar |\@ne \else + \if \@nextchar !6 \else + \if \@nextchar @7 \else + \if \@nextchar <8 \else + \if \@nextchar >9 \else + 10 + \@chnum + \if \@nextchar m\thr@@\else + \if \@nextchar p4 \else + \if \@nextchar b5 \else + \z@ \@chclass \z@ \@preamerr \z@ \fi \fi \fi \fi\fi \fi \fi\fi \fi + \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi} +\def\TY@classz{% + \@classx + \@tempcnta\count@ + \ifx\TY@box\TY@box@v + \global\advance\TY@count\@ne + \fi + \let\centering c% + \let\raggedright\noindent + \let\raggedleft\indent + \let\arraybackslash\relax + \prepnext@tok + \ifnum\@chnum<4 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \ifnum\@chnum=6 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \@addtopreamble{% + \ifcase\@chnum + \hfil \d@llarbegin\insert@column\d@llarend \hfil \or + \kern\z@ + \d@llarbegin \insert@column \d@llarend \hfil \or + \hfil\kern\z@ \d@llarbegin \insert@column \d@llarend \or + $\vcenter\@startpbox{\@nextchar}\insert@column \@endpbox $\or + \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or + \vbox \@startpbox{\@nextchar}\insert@column \@endpbox \or + \d@llarbegin \insert@column \d@llarend \or% dubious "s" case + \TY@box\centering\or + \TY@box\raggedright\or + \TY@box\raggedleft\or + \TY@box\relax + \fi}\prepnext@tok} +\def\TY@box#1{% + \ifx\centering#1% + \hfil \d@llarbegin\insert@column\d@llarend \hfil \else + \ifx\raggedright#1% + \kern\z@%<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< + \d@llarbegin \insert@column \d@llarend \hfil \else + \ifx\raggedleft#1% + \hfil\kern\z@ \d@llarbegin \insert@column \d@llarend \else + \ifx\relax#1% + \d@llarbegin \insert@column \d@llarend + \fi \fi \fi \fi} +\def\TY@box@v#1{% + \vtop \@startpbox{\csname TY@F\the\TY@count\endcsname}% + #1\arraybackslash\tyformat + \insert@column\@endpbox} +\newdimen\TY@tablewidth +\def\Gscale@div#1#2#3{% + \setlength\dimen@{#3}% + \ifdim\dimen@=\z@ + \PackageError{graphics}{Division by 0}\@eha + \dimen@#2% + \fi + \edef\@tempd{\the\dimen@}% + \setlength\dimen@{#2}% + \count@65536\relax + \ifdim\dimen@<\z@ + \dimen@-\dimen@ + \count@-\count@ + \fi + \loop + \ifdim\dimen@<8192\p@ + \dimen@\tw@\dimen@ + \divide\count@\tw@ + \repeat + \dimen@ii=\@tempd\relax + \divide\dimen@ii\count@ + \divide\dimen@\dimen@ii + \edef#1{\strip@pt\dimen@}} +\long\def\TY@get@body#1\end + {\toks@\expandafter{\the\toks@#1}\TY@find@end} +\def\TY@find@end#1{% + \def\@tempa{#1}% + \ifx\@tempa\TY@\def\@tempa{\end{#1}}\expandafter\@tempa + \else\toks@\expandafter + {\the\toks@\end{#1}}\expandafter\TY@get@body\fi} +\def\TY@warn{% + \PackageWarning{tabulary}} +\catcode`\Z=11 +\AtBeginDocument{ +\@ifpackageloaded{colortbl}{% +\expandafter\def\expandafter\@mkpream\expandafter#\expandafter1% + \expandafter{% + \expandafter\let\expandafter\CT@setup\expandafter\relax + \expandafter\let\expandafter\CT@color\expandafter\relax + \expandafter\let\expandafter\CT@do@color\expandafter\relax + \expandafter\let\expandafter\color\expandafter\relax + \expandafter\let\expandafter\CT@column@color\expandafter\relax + \expandafter\let\expandafter\CT@row@color\expandafter\relax + \@mkpream{#1}} +\let\TY@@mkpream\@mkpream +\def\TY@classz{% + \@classx + \@tempcnta\count@ + \ifx\TY@box\TY@box@v + \global\advance\TY@count\@ne + \fi + \let\centering c% + \let\raggedright\noindent + \let\raggedleft\indent + \let\arraybackslash\relax + \prepnext@tok +\expandafter\CT@extract\the\toks\@tempcnta\columncolor!\@nil + \ifnum\@chnum<4 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \ifnum\@chnum=6 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \@addtopreamble{% + \setbox\z@\hbox\bgroup\bgroup + \ifcase\@chnum + \hskip\stretch{.5}\kern\z@ + \d@llarbegin\insert@column\d@llarend\hskip\stretch{.5}\or + \kern\z@%<<<<<<<<<<<<<<<<<<<<<<<<<<< + \d@llarbegin \insert@column \d@llarend \hfill \or + \hfill\kern\z@ \d@llarbegin \insert@column \d@llarend \or + $\vcenter\@startpbox{\@nextchar}\insert@column \@endpbox $\or + \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or + \vbox \@startpbox{\@nextchar}\insert@column \@endpbox \or + \d@llarbegin \insert@column \d@llarend \or% dubious s case + \TY@box\centering\or + \TY@box\raggedright\or + \TY@box\raggedleft\or + \TY@box\relax + \fi + \egroup\egroup +\begingroup + \CT@setup + \CT@column@color + \CT@row@color + \CT@do@color +\endgroup + \@tempdima\ht\z@ + \advance\@tempdima\minrowclearance + \vrule\@height\@tempdima\@width\z@ +\unhbox\z@ +}\prepnext@tok}% + \def\TY@arrayrule{% + \TY@subwidth\arrayrulewidth + \@addtopreamble{{\CT@arc@\vline}}}% + \def\TY@classvi{\ifcase \@lastchclass + \@acol \or + \TY@subwidth\doublerulesep + \ifx\CT@drsc@\relax + \@addtopreamble{\hskip\doublerulesep}% + \else + \@addtopreamble{{\CT@drsc@\vrule\@width\doublerulesep}}% + \fi\or + \@acol \or + \@classvii + \fi}% +}{% +\let\CT@start\relax +} +} +{\uccode`\*=`\ % +\uppercase{\gdef\TX@verb{% + \leavevmode\null\TX@vwarn + {\ifnum0=`}\fi\ttfamily\let\\\ignorespaces + \@ifstar{\let~*\TX@vb}{\TX@vb}}}} +\def\TX@vb#1{\def\@tempa##1#1{\toks@{##1}\edef\@tempa{\the\toks@}% + \expandafter\TX@v\meaning\@tempa\\ \\\ifnum0=`{\fi}}\@tempa!} +\def\TX@v#1!{\afterassignment\TX@vfirst\let\@tempa= } +\begingroup +\catcode`\*=\catcode`\# +\catcode`\#=12 +\gdef\TX@vfirst{% + \if\@tempa#% + \def\@tempb{\TX@v@#}% + \else + \let\@tempb\TX@v@ + \if\@tempa\space~\else\@tempa\fi + \fi + \@tempb} +\gdef\TX@v@*1 *2{% + \TX@v@hash*1##\relax\if*2\\\else~\expandafter\TX@v@\fi*2} +\gdef\TX@v@hash*1##*2{*1\ifx*2\relax\else#\expandafter\TX@v@hash\fi*2} +\endgroup +\def\TX@vwarn{% + \@warning{\noexpand\verb may be unreliable inside tabularx/y}% + \global\let\TX@vwarn\@empty} +\endinput +%% +%% End of file `tabulary.sty'. diff --git a/source/conf.py b/source/conf.py index 6cd961e..67edcb8 100644 --- a/source/conf.py +++ b/source/conf.py @@ -58,7 +58,7 @@ # built documents. # # The short X.Y version. -version = u'0.1-pre1' +version = u'0.1' # The full version, including alpha/beta/rc tags. release = version diff --git a/source/revhistory.rst b/source/revhistory.rst index 524b314..9afd307 100644 --- a/source/revhistory.rst +++ b/source/revhistory.rst @@ -2,10 +2,10 @@ .. tabularcolumns:: | l l J | .. table:: Revision History - =========== ========== ==================================================== - Revision Date Description - =========== ========== ==================================================== - |spec| 0.1 2016-5-6 Initial prerelease version. Imported |epapr| text - into reStructured Text format and removed Power ISA - specific elements. - =========== ========== ==================================================== + =========== =========== ==================================================== + Revision Date Description + =========== =========== ==================================================== + |spec| 0.1 2016-MAY-24 Initial prerelease version. Imported |epapr| text + into reStructured Text format and removed Power ISA + specific elements. + =========== =========== ====================================================