Mercurial > hvf > hvf-old
changeset 341:446f4523a39f doc-HVF-0001-00
manual: completed the first edition
Signed-off-by: Josef 'Jeff' Sipek <jeffpc@josefsipek.net>
author | Josef 'Jeff' Sipek <jeffpc@josefsipek.net> |
---|---|
date | Fri, 07 Aug 2009 19:02:47 -0400 |
parents | 85e41deb5c34 |
children | 1cbc8cc2ce29 |
files | doc/manual/Makefile doc/manual/abi.tex doc/manual/cp-commands.tex doc/manual/cp-directory.tex doc/manual/cp-nss.tex doc/manual/cp-prog.tex doc/manual/front.tex doc/manual/license.tex doc/manual/manual.tex doc/manual/preface.tex |
diffstat | 10 files changed, 130 insertions(+), 14 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/manual/Makefile Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/Makefile Fri Aug 07 19:02:47 2009 -0400 @@ -12,10 +12,6 @@ cp-cmd-list.tex: ./gen-docs.sh -.PHONY: cp-directory-sample.tex -cp-directory-sample.tex: - (echo "\\begin{verbatim}"; cat ../../sys/hvf.directory; echo "\\end{verbatim}") > $@ - clean: - rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex cp-directory-sample.tex + rm -f *.toc *.aux *.cb *.cb2 *.dvi *.log manual.pdf cp-cmd-list.tex rm -rf tex/
--- a/doc/manual/abi.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/abi.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,4 +1,5 @@ \chapter{ABI} +\label{chap:abi} HVF uses the same ABI (s390x) as Linux on z. The following sections attempt to introduce portions of it. For more information see the relevant literature. @@ -35,4 +36,81 @@ \end{center} \section{ELF Binary File Format} -FIXME: describe ELF +This section introduces the ELF binary file format for the s390x ABI. For +more detailed description, see the appropriate standard. + +Each ELF file begins with the following header: + +\begin{lstlisting}[language=C] +typedef struct { + u8 e_ident[16]; + u16 e_type; + u16 e_machine; + u32 e_version; + u64 e_entry; + u64 e_phoff; + u64 e_shoff; + u32 e_flags; + u16 e_ehsize; + u16 e_phentsize; + u16 e_phnum; + u16 e_shentsize; + u16 e_shnum; + u16 e_shstrndx; +} Elf64_Ehdr; +\end{lstlisting} + +\begin{description} +\item[e\_ident] contains several bytes of information: + + Bytes 0-3 contain the magic ASCII string ``\textbackslash x7FELF'', which is + equal to 7F454C46 hex. + + Byte 4 contains the ELF class which should equal 1 for 31-bit files, + and 2 for 64-bit files. + + Byte 5 contains the byte order information. A value of 1 indicates + little endian format, while value of 2 indicates a big endian + format. In HVF this must always be equal to 2. + + Byte 6 contains the ELF file format version. Currently, only one + version is defined --- 1. + + Bytes 7-15 contain other information, however HVF ignores these + fields. + % FIXME: fill this in later + +\item[e\_type] specifies the type of the payload. Currently, HVF expects + only executables, and therefore this field should be set to 2. + +\item[e\_machine] identifies the target architecture. It should always + equal 16 hex identifying it as ESA/390 or z/Architecture. + +\item[e\_version] contains the ELF header version number. It should always + equal to 1. + +\item[e\_entry] is the address of the entry point. That is the location of + the instruction to transfer control to once loading has completed. + +\item[e\_phoff] contains the offset into the file to the first program + header. HVF ignores this field. + +\item[e\_shoff] contains the offset into the file to the first section + header. + +\item[e\_flags] contains processor specific flags. HVF ignores this field. + +\item[e\_ehsize] is the ELF header size. HVF ignores this field. + +\item[e\_phentsize] equals the program header entry size. HVF ignores this + field. + +\item[e\_phnum] is the number of program headers. HVF ignores this field. + +\item[e\_shentsize] equals the section header entry size. + +\item[e\_shnum] is the number of section header. + +\item[e\_shstrndx] contains the section name string table index. HVF + ignores this field. +\end{description}
--- a/doc/manual/cp-commands.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/cp-commands.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,4 +1,5 @@ \chapter{CP Commands} +\label{chap:commands} This chapter details the CP commands. Each command is accompanied by a syntax diagram, authorization level
--- a/doc/manual/cp-directory.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/cp-directory.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,6 +1,8 @@ \chapter{CP Directory} +\label{chap:directory} The directory contains a list of all valid users on the system. Currently, -any changes to the directory require that the nucleus be rebuilt. +any changes to the directory require that the nucleus be rebuilt, and the +system re-IPLed. \section{Directory Syntax} The directory is a simple text file with a declarative syntax used to @@ -64,9 +66,12 @@ \end{syntdiag} \section{Example Directory} +Figure~\ref{fig:directory-sample} is the default directory distributed with +HVF. It defines several users with nearly identical configurations. + \begin{figure*}[htb] \small -\input{cp-directory-sample} +\lstinputlisting{../../sys/hvf.directory} \captionfont \caption{\capfont Example directory defining three users.} \label{fig:directory-sample}
--- a/doc/manual/cp-nss.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/cp-nss.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,4 +1,5 @@ \chapter{CP Named Saved Segments} +\label{chap:nss} XXX: describe NSS file format \section{Supplied Named Saved Segments}
--- a/doc/manual/cp-prog.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/cp-prog.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,5 +1,7 @@ \chapter{CP Programming Interfaces} +\label{chap:prog} \section{DIAGs} -FIXME: list all the diags that are supported -\section{Remote Procedure Call Interface} -FIXME: describe the rpc +Currently, there are no DIAGs supported. + +%\section{Remote Procedure Call Interface} +%FIXME: describe the rpc; currently not supported
--- a/doc/manual/front.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/front.tex Fri Aug 07 19:02:47 2009 -0400 @@ -24,7 +24,7 @@ \hfill HVF-0001-00 \newpage \vspace*{\stretch{1}} -\section*{First Edition (?, 2009)} +\section*{First Edition (August, 2009)} This information in this manual is subject to change without notice. Please address any comments to Josef ``Jeff'' Sipek
--- a/doc/manual/license.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/license.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,4 +1,5 @@ \chapter{License} +\label{chap:license} \begin{center} \Large GNU GENERAL PUBLIC LICENSE\\
--- a/doc/manual/manual.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/manual.tex Fri Aug 07 19:02:47 2009 -0400 @@ -37,6 +37,19 @@ \newcommand{\capfont} \small \newcommand{\captionfont} {} +\usepackage{listings} +\lstset{% +numbers=left, +numberstyle=\footnotesize, +stepnumber=1, +numbersep=5pt, +showspaces=false, +frame=single, +tabsize=8, +captionpos=b, +breaklines=true +} + %\setcounter{tocdepth}{3} \setlength{\parskip}{\baselineskip} @@ -52,7 +65,7 @@ \input{cp-directory} \input{cp-commands} \input{cp-prog} -\input{cp-nss} +%\input{cp-nss} \input{abi} \appendix \input{license}
--- a/doc/manual/preface.tex Fri Aug 07 11:00:40 2009 -0400 +++ b/doc/manual/preface.tex Fri Aug 07 19:02:47 2009 -0400 @@ -1,5 +1,24 @@ \chapter*{Preface} -FIXME: this is where the preface will be +This document includes information about HVF user and developer interfaces, +as well as some internal details. + +Chapter~\ref{chap:directory} describes the handling of the directory. +Including the syntax of the directory file. + +Chapter~\ref{chap:commands} describes each CP command in detail. Each +command includes a syntax diagram, as well as other information such as +purpose, notes, and examples. + +Chapter~\ref{chap:prog} describes the interfaces a developer can use to +communicate with the hypervisor. + +%Chapter~\ref{chap:nss} describes the design of the Named Saved Segment (NSS) +%feature. Additionally, it also describes the NSS supplied with HVF. + +Chapter~\ref{chap:abi} describes HVF's internal ABI. + +Appendix~\ref{chap:license} includes a copy of the GNU General Public +License (version 2) under which HVF is licensed. %\cbstart %\section*{Summary of Changes in Second Edition}