summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bytefield
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:49:07 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:49:07 +0000
commit007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (patch)
tree90d17e00e572ecb1e24764b6f29c80e098b08d29 /Master/texmf-dist/doc/latex/bytefield
parent950209b26f70aa87ed07c54f82a95b6f03b7c3a0 (diff)
doc/latex
git-svn-id: svn://tug.org/texlive/trunk@84 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/bytefield')
-rw-r--r--Master/texmf-dist/doc/latex/bytefield/README44
-rw-r--r--Master/texmf-dist/doc/latex/bytefield/bytefield.pdfbin0 -> 354304 bytes
-rw-r--r--Master/texmf-dist/doc/latex/bytefield/example.pdfbin0 -> 123564 bytes
-rw-r--r--Master/texmf-dist/doc/latex/bytefield/example.tex500
4 files changed, 544 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/bytefield/README b/Master/texmf-dist/doc/latex/bytefield/README
new file mode 100644
index 00000000000..0828830be07
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bytefield/README
@@ -0,0 +1,44 @@
+ +---------------------------------+
+ | THE BYTEFIELD PACKAGE |
+ | Scott Pakin, scott+bf@pakin.org |
+ +---------------------------------+
+
+
+Description
+-----------
+The bytefield package helps the user create illustrations for network
+protocol specifications and anything else that utilizes fields of
+data. These illustrations show how the bits and bytes are laid out in
+a packet or in memory.
+
+
+Copyright and license
+---------------------
+Copyright (C) 2005 Scott Pakin, scott+bf@pakin.org
+
+This package may be distributed and/or modified under the conditions
+of the LaTeX Project Public License, either version 1.3a 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.3a or later is part of all distributions of LaTeX version
+2004/10/11 or later.
+
+
+Building bytefield
+------------------
+tex bytefield.ins <== Produces bytefield.sty (the package proper)
+latex bytefield.dtx <== Produces bytefield.dvi (the documentation)
+makeindex -s gind.ist bytefield.idx -o bytefield.ind <== Writes an index
+makeindex -s gglo.ist bytefield.glo -o bytefield.gls <== Writes a change log
+latex bytefield.dtx <== Incorporates the index and change log into
+ bytefield.dvi
+
+Note that bytefield comes with pre-built documentation (PDF format,
+U.S. letter-sized paper, 24 pages). Also, there is an example.tex
+file that shows how one might include hyperlinks in a protocol
+diagram. example.tex needs the hyperref package and should be run
+through pdfLaTeX, VTeX, dvipdfm, or any other backend that supports
+hyperref hyperlinks.
diff --git a/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf b/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf
new file mode 100644
index 00000000000..7072acfbd86
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bytefield/bytefield.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/bytefield/example.pdf b/Master/texmf-dist/doc/latex/bytefield/example.pdf
new file mode 100644
index 00000000000..63403122658
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bytefield/example.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/bytefield/example.tex b/Master/texmf-dist/doc/latex/bytefield/example.tex
new file mode 100644
index 00000000000..1c69023fdcd
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bytefield/example.tex
@@ -0,0 +1,500 @@
+\documentclass[11pt]{article}
+\usepackage{fullpage}
+\usepackage{longtable}
+\usepackage{bytefield}
+\usepackage{color}
+\usepackage[bookmarksopen=true]{hyperref}
+
+\title{Integrating \texttt{bytefield} and \texttt{hyperref}}
+\author{\href{http://www.pakin.org/~scott}{Scott Pakin
+ \texttt{<scott+bf@pakin.org>}}}
+\date{21 June 2000}
+\hypersetup{%
+pdftitle={Integrating bytefield and hyperref},
+pdfauthor={Scott Pakin <scott+bf@pakin.org>},
+pdfsubject={Example of bytefield package},
+pdfkeywords={bytefield, hyperref, multicast transport protocol, hyperlink, example}}
+
+% Set up hyperlink colors
+\definecolor{darkred}{rgb}{0.5,0,0}
+\definecolor{darkgreen}{rgb}{0,0.3,0}
+\definecolor{darkblue}{rgb}{0,0,0.5}
+\definecolor{darkbrown}{rgb}{0.28,0.07,0.07}
+\hypersetup{%
+ colorlinks=true,
+ citecolor=darkblue,
+ urlcolor=darkgreen,
+ linkcolor=darkred,
+ menucolor=darkbrown}
+
+\begin{document}
+\sloppy
+\maketitle
+
+\begin{abstract}
+This document is a demonstration of how the \texttt{bytefield} package can
+integrate seamlessly with \texttt{hyperref}. The text that follows was
+copy-and-pasted from
+\href{http://www.rfc-editor.org/rfc/rfc1301.txt}{RFC~1301, ``Multicast
+Transport Protocol''}~\cite{Armstrong92}.
+
+The important thing to note is the way the fields in the protocol diagrams
+(drawn with \texttt{bytefield}) are hyperlinked to their descriptions (with
+\texttt{hyperref}). Few typesetting systems enable authors to specify
+hyperlinks from within a figure to the surrounding text. Fewer still do
+not require hyperlinks to be re-specified when the figure changes.
+\texttt{bytefield}~+ \texttt{hyperref} can do both.
+\end{abstract}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\setcounter{section}{1}
+
+\section{Protocol description}
+
+ MTP is a transport in that it is a client of the network layer (as
+ defined by the OSI networking model).\footnote{The network layer is not
+ specified by MTP. One of the goals is to specify a transport that can be
+ implemented with equal functionality on many network architectures.}
+ MTP provides reliable delivery of client data between one or more
+ communicating processes, as well as a predefined principal process. The
+ collection of processes is called a web.
+
+ In addition to transporting data reliably and efficiently, MTP
+ provides the synchronization necessary for web members to agree on
+ the order of receipt of all messages and can agree on the delivery of
+ the message even in the face of partitions. This ordering and
+ agreement protocol uses serialized tokens granted by the master to
+ producers.
+
+ The processes may have any one of three levels of capability. One
+ member must be the master. The master instantiates and controls the
+ behavior of the web, including its membership and performance. Non
+ master members may be either producer/consumers or pure consumers.
+ The former class of member is permitted to transmit user data to the
+ entire membership (and expected to logically hear itself), while the
+ latter is prohibited from transmitting user data.
+
+ MTP is a negative acknowledgement protocol, exploiting the highly
+ reliable delivery of the local area and wide area network
+ technologies of today. Successful delivery of data is accepted by
+ consuming stations silently rather than having the successful
+ delivery noted to the producing process, thus reducing the amount of
+ reverse traffic required to maintain synchronization.
+
+\subsection{Definition of terms}
+
+\begin{center}
+ \fbox{Skipped; see~\cite{Armstrong92}}
+\end{center}
+
+\subsection{Packet format}
+
+ An MTP packet consists of a transport protocol header followed by a
+ variable amount of data. The protocol header, shown in
+ Figure~\ref{fig:packet-format}, is part of every packet. The remainder
+ of the packet is either user data (packet type = data) or additional
+ transport specific information. The fields in the header are statically
+ defined as n-bit wide quantities. There are no undefined fields or
+ fields that may at any time have undefined values. Reserved fields, if
+ they exist, must always have a value of zero.
+
+\begin{figure}[htbp]
+ \begin{center}
+ \setlength{\byteheight}{6ex}
+ \begin{bytefield}{32}
+ \bitheader{0,7-8,15-16,23-24,31} \\
+
+ \wordgroupr{transport \\ header}
+ % We have to do the \parbox explicitly in the next line because
+ % \hyperlink typesets its argument in horizontal mode.
+ \bitbox{8}{\hyperlink{protocol-version}{\parbox{\width}{\centering protocol version}}} &
+ \bitbox{8}{\hyperlink{packet-type-modifier}{packet type}} &
+ \bitbox{8}{\hyperlink{packet-type-modifier}{type modifier}} &
+ \bitbox{8}{\hyperlink{subchannel}{client channel}} \\
+
+ \wordbox{1}{\hyperlink{source-connect}{source connection identifier}} \\
+
+ \wordbox{1}{\hyperlink{dest-connect}{destination connection identifier}} \\
+
+ \wordbox{1}{\hyperlink{msg-accept}{message acceptance criteria}} \\
+
+ \wordbox{1}{\hyperlink{heartbeat}{heartbeat}} \\
+
+ \bitbox{16}{\hyperlink{window}{window}} &
+ \bitbox{16}{\hyperlink{retention}{retention}}
+ \endwordgroupr \\
+
+ \wordgroupr{data \\ fields}
+ \wordbox[lrt]{1}{%
+ \parbox{0.6\width}{\centering (data content and format dependent on packet type and modifier)}} \\
+ \skippedwords \\
+ \wordbox[lrb]{1}{}
+ \endwordgroupr
+ \end{bytefield}
+ \end{center}
+ \caption{MTP packet format}
+ \label{fig:packet-format}
+\end{figure}
+
+\hypertarget{protocol-version}{\subsubsection{Protocol version}}
+
+ The first 8 bits of the packet are the protocol version number. This
+ document describes version 1 of the Multicast Transport Protocol and
+ thus the version field has a value of 0x01.
+
+\hypertarget{packet-type-modifier}{\subsubsection{Packet type and modifier}}
+
+ The second byte of the header is the packet type and the following
+ byte contains the packet type modifier. Typical control message
+ exchanges are in a request/response pair. The modifier field
+ simplifies the construction of responses by permitting reuse of the
+ incoming message with minimal modification. The following table gives
+ the packet type field values along with their modifiers. The
+ modifiers are valid only in the context of the type. In the prose of
+ the definitions and later in the document, the syntax for referring
+ to one of the entries described in the following table will be
+ type[modifier]. For example, a reference to data[eow] would be a
+ packet of type data with an end of window modifier.
+
+\begin{center}
+\renewcommand{\arraystretch}{1.5}
+\begin{longtable}{llp{0.6\textwidth}}
+ type & modifier & description \\ \hline
+
+ data(0) & data(0) & The packet is one that contains user
+ information. Only the process possessing a
+ transmit token is permitted to send data
+ unless specifically requested to retransmit
+ previously transmitted data. All packets of
+ type data are multicast to the entire web. \\
+
+ & eow(1) & A data packet with the eow (end of window)
+ modifier set indicates that the transmitter
+ intends to send no more packets in this
+ heartbeat either because it has sent as many
+ as permitted given the window parameter or
+ simply has no more data to send during the
+ current heartbeat. This is not client
+ information but rather a hint to be used by
+ transport providers to synchronize the
+ computation and transmission of naks. \\
+
+ & eom(2) & Data[eom] marks the end of the message to the
+ consumers, and the surrendering of the
+ transmit token to the master. And like a
+ data[eow] a data[eom] packet implies the end
+ of window. \\
+ nak(1) & request(0) & A nak[request] packet is a consumer
+ requesting a retransmission of one or more
+ data packets. The data field contains an
+ ordered list of packet sequence numbers that
+ are being requested. Naks of any form are
+ always unicast. \\
+
+ & deny(1) & A nak[deny] message indicates that the
+ producer source of the nak[deny]) cannot
+ retransmit one or more of the packets
+ requested. The process receiving the
+ nak[deny] must report the failure to its
+ client. \\
+
+ empty(2) & dally(0) & An empty[dally] packet is multicast to
+ maintain synchronization when no client data
+ is available. \\
+
+ & cancel(1) & If a producer finds itself in possession of a
+ transmit token and has no data to send, it
+ may cancel the token[request] by multicasting
+ an empty[cancel] message. \\
+
+ & hibernate(2)&If the master possesses all of the web's
+ transmit tokens and all outstanding messages
+ have been accepted or rejected, the master
+ may transmit empty[hibernate] packets at a
+ rate significantly slower than indicated by
+ the web's value of heartbeat. \\
+
+ join(3) & request(0) & A join[request] packet is sent by a process
+ wishing to join a web to the web's unknown
+ TSAP (see section~\ref{sec:dest-connect}). \\
+
+ & confirm(1) & The join[confirm] packet is the master's
+ confirmation of the destination's request to
+ join the web. It will be unicast by the
+ master (and only the master) to the station
+ that sent the join[request]. \\
+
+ & deny(2) & A join[deny] packet indicates permission to
+ join the web was denied. It may only be
+ transmitted by the master and will be unicast
+ to the member that sent the join[request]. \\
+
+ quit(4) & request(0) & A quit[request] may be unicast to the master
+ by any member of the web at any time to
+ indicate the sending process wishes to
+ withdraw from the web. Any member may unicast
+ a quit to another member requesting that the
+ destination member quit the web due to
+ intolerable behavior. The master may
+ multicast a quit[request] requiring that the
+ entire web disband. The request will be
+ multicast at regular heartbeat intervals
+ until there are no responses to retention
+ requests. \\
+
+ & confirm(1) & The quit[confirm] packet is the indication
+ that a quit[request] has been observed and
+ appropriate local action has been taken.
+ Quit[confirm] are always unicast. \\
+
+ token(5) & request(0) & A token[request] is a producing member
+ requesting a transmit token from the master.
+ Such packets are unicast to the master. \\
+
+ & confirm(1) & The token[confirm] packet is sent by the
+ master to assign the transmit token to a
+ member that has requested it. token[confirm]
+ will be unicast to the member being granted
+ the token. \\
+
+ isMember(6)&request(0)& An isMember[request] is soliciting
+ verification that the target member is a
+ recognized member of the web. All forms of
+ the isMember packet are unicast to a specific
+ member. \\
+
+ & confirm(1) & IsMember[confirm] packets are positive
+ responses to isMember[requests]. \\
+
+ & deny(2) & If the member receiving the isMember[request]
+ cannot confirm the target's membership in the
+ web, it responds with a isMember[deny].
+\end{longtable}
+\end{center}
+
+\hypertarget{subchannel}{\subsubsection{Subchannel}}
+
+ The fourth byte of the transport header contains the client's
+ subchannel value. The default value of the subchannel field is zero.
+ Semantics of the subchannel value are defined by the transport client
+ and therefore are only applicable to packets of type data. All other
+ packet types must have a subchannel value of zero.
+
+\hypertarget{source-connect}{\subsubsection{Source connection identifier}}
+
+ The source connection identifier field is a 32 bit field containing a
+ transmitting system unique value assigned at the time the transport
+ is created. The field is used in identifying the particular transport
+ instantiation and is a component of the TSAP\@. Every packet
+ transmitted by the transport must have this field set.
+
+\hypertarget{dest-connect}{\subsubsection{Destination connection identifier}}
+\label{sec:dest-connect}
+
+ The destination connection identifier is the 32 bit identifier of the
+ target transport. From the point of view of a process sending a
+ packet, there are three types of destination connection identifiers.
+ First, there is the unknown connection identifier (0x00000000). The
+ unknown value is used only as the destination connection identifier
+ in the join[request] packet.
+
+ Second, there is the multicast connection identifier gleaned from the
+ join[confirm] message sent by the master. The multicast connection
+ identifier is used in conjunction with the multicast NSAP to form the
+ destination TSAP of all packets multicast to the entire
+ web.\footnote{There's only one such multicast connection identifier per
+ web. If there are multiple processes on the same machine participating
+ in a web, the transport must descriminate between those processes by
+ using the connnection identifier.}
+
+ The last class of connection identifier is a unicast identifier and
+ is used to form the destination TSAP when unicasting packets to
+ individual members. Every member of the web has associated with it a
+ unicast connection identifier that is used to form its own unicast
+ TSAP.
+
+\hypertarget{msg-accept}{\subsubsection{Message acceptance}}
+
+ MTP ensures that all processes agree on which messages are accepted
+ and in what order they are accepted. The master controls this aspect
+ of the protocol by controlling allocation of transmit tokens and
+ setting the status of messages. Once a token for a message has been
+ assigned (see section 3.2.1) the master sets the status of that
+ message according to the following rules~\cite{Armstrong91}:
+
+ \begin{itemize}
+ \item If the master has seen the entire message (i.e., has seen the
+ data[eom] and all intervening data packets), the status is accepted.
+
+ \item If the master has not seen the entire message but believes the
+ message sender is still operational and connected to the master (as
+ determined by the master), the status is pending.
+
+ \item If the master has not seen the entire message and believes the
+ sender to have failed or partitioned away, the status is rejected.
+ \end{itemize}
+
+ Message status is carried in the message acceptance record (see
+ Figure~\ref{fig:msg-accept}) of every packet, and processes learn the
+ status of earlier messages by processing this information.
+
+ The acceptance criteria is a multiple part record that carries the rules
+ of agreement to determine the message acceptance.
+ \hypertarget{synchro}{The most significant 8 bits is a flag that, if not
+ zero, indicates synchronization is required.} The field may vary on a
+ per message basis as directed by producing transport's client. The
+ default is that no synchronization is required.
+
+ \hypertarget{tri-state}{The second part of the record is a 12 element
+ vector that represents the status of the last 12 messages transmitted
+ into the web.}
+
+\begin{figure}[htbp]
+ \begin{center}
+ \setlength{\byteheight}{6ex}
+ \begin{bytefield}{32}
+ \bitheader{0,7-8,15-16,23-24,31} \\
+
+ \bitbox{8}{\hyperlink{synchro}{synchro}} &
+ \bitbox{24}{\hyperlink{tri-state}{tri-state bitmask{[12]}}} \\
+
+ \bitbox{16}{\hyperlink{msg-seq}{message sequence number}} &
+ \bitbox{16}{\hyperlink{packet-seq}{packet sequence number}}
+ \end{bytefield}
+ \end{center}
+ \caption{Message acceptance record}
+ \label{fig:msg-accept}
+\end{figure}
+
+ Each element of the array is two bits in length and may have one of
+ three values: accepted(0), pending(1) or rejected(2). Initially, the
+ bit mask is set to all zeros. When the token for message $m$ is
+ transmitted, the first (left-most) element of the vector represents
+ the the state of message $m - 1$, the second element of the vector is
+ the status of message $m - 2$, and so forth. Therefore the status of
+ the last 12 messages are visible, the status of older messages are
+ lost, logically by shifting the elements out of the vector. Only the
+ master is permitted to set the status of messages. The master is not
+ permitted to shift a status of pending beyond the end of the vector.
+ If that situation arises, the master must instead not confirm any
+ token[request] until the oldest message can be marked as either
+ rejected or accepted.
+
+ \hypertarget{msg-seq}{Message sequence numbers are 16 bit unsigned
+ values.} The field is initialized to zero by the master when the
+ transport is initialized, and incremented by one after each token is
+ granted. Only the master is permitted to change the value of the message
+ sequence number. Once granted, that message sequence number is consumed
+ and the state of the message must eventually become either accepted or
+ rejected. No transmit tokens may be granted if the assignment of a
+ message sequence number that would cause a value of pending to be
+ shifted beyond the end of the status vector.
+
+ \hypertarget{packet-seq}{Packet sequence numbers are unsigned 16 bit
+ numbers assigned by the producing process on a per message basis.}
+ Packet sequence numbers start at a value of zero for each new message
+ and are incremented by one (consumed) for each data packet making up the
+ message. Consumers detecting missing packet sequence numbers must send a
+ nak[request] to the appropriate producer to recover the missed data.
+
+ Control packets always contain the message acceptance criteria with a
+ synchronization flag set to zero (0x00), the highest message sequence
+ number observed and a packet sequence number one greater than
+ previously observed. Control packets do not consume any sequence
+ numbers. Since control messages are not reliably delivered, the
+ acceptance criteria should only be checked to see if they fall within
+ the proper range of message numbers, relative to the current message
+ number of the receiving station. The range of acceptable sequence
+ numbers should be $m-11$ to $m-13$, inclusive, where $m$ is the current
+ message number.
+
+\hypertarget{heartbeat}{\subsubsection{Heartbeat}}
+
+ Heartbeat is an unsigned 32 bit field that has the units of
+ milliseconds. The value of heartbeat is shared by all members of the
+ web. By definition at least one packet (either data, empty or quit
+ from the master) will be multicast into the web within every
+ heartbeat period.
+
+\hypertarget{window}{\subsubsection{Window}}
+
+ The allocation window (or simply window) is a 16 bit unsigned field
+ that indicates the maximum number of data packets that can be
+ multicasted by a member in a single heartbeat. It is the sum of the
+ retransmitted and new data packets.
+
+\hypertarget{retention}{\subsubsection{Retention}}
+
+ The retention field is a 16 bit unsigned value that is the number of
+ heartbeats for which a producer must retain transmitted client data
+ and state for the purpose of retransmission.
+
+\subsection{Transport addresses}
+
+ Associated with each transport are logically three transport service
+ access points (TSAP), logically formed by the concatenation of a
+ network service access point (NSAP) and a transport connection
+ identifier. These TSAPs are the unknown TSAP, the web's multicast
+ TSAP and each individual member's TSAP.
+
+\subsubsection{Unknown transport address}
+
+ Stations that are just joining must use the multicast NSAP associated
+ with the transport, but are not yet aware of either the web's
+ multicast TSAP the master process' TSAP\@. Therefore, joining stations
+ fabricate a temporary TSAP (referred to as a unknown TSAP) by using a
+ connection identifier reserved to mean unknown (0x00000000). The
+ join[confirm] message will be sourced from the master's TSAP and will
+ include the multicast transport connection identifier in the data
+ field. Those values must be extracted from the join[confirm] and
+ remembered by the joining process.
+
+\subsubsection{Web's multicast address}
+
+ The multicast TSAP is formed by logically concatenating the multicast
+ NSAP associated with the transport creation and the transport
+ connection identifier returned in the data field of the join[confirm]
+ packet. If more than one network is involved in the web, then the
+ multicast transport address becomes a list, one for each network
+ represented. This list is supplied in the data field of
+ token[confirm] packets.
+
+ The multicast TSAP is used as the target for all messages that are
+ destined to the entire web, such as data and empty. The master's
+ decision to abandon the transport (quit) is also sent to the
+ multicast transport address.
+
+\subsubsection{Member addresses}
+
+ The member TSAP is formed by using the process' unicast NSAP
+ concatenated with a locally generated unique connection identifier.
+ That TSAP must be the source of every packet transmitted by the
+ process, regardless of its destination, for the lifetime of the
+ transport.
+
+ Packets unicast to specific members must contain the appropriate
+ TSAP\@. For producers and consumers this is not difficult. The only
+ TSAPs of interest are the master and the station(s) currently
+ transmitting data.
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{thebibliography}{AFM91}
+\bibitem[AFM91]{Armstrong91}
+S.~Armstrong, A.~Freier, and K.~Marzullo.
+\emph{MTP: An atomic multicast transport protocol}.
+Xerox Webster Research Center technical report X9100359,
+March 1991.
+
+\bibitem[AFM92]{Armstrong92}
+S.~Armstrong, A.~Freier, and K.~Marzullo.
+\emph{Multicast transport protocol}.
+RFC 1301, Internet Engineering Task Force, February 1992.
+Available from \url{http://www.rfc-editor.org/rfc/rfc1301.txt}.
+\end{thebibliography}
+
+\end{document}