| 1 |
% \iffalse |
| 2 |
% |
| 3 |
% register.dtx |
| 4 |
% Register diagrams with field descriptions |
| 5 |
% |
| 6 |
% Author: Matthew Lovell ([email protected]) |
| 7 |
% Copyright 2001-2020 by Matthew B. Lovell |
| 8 |
% |
| 9 |
% Run LaTeX on the file `register.ins' to get a .sty-file and |
| 10 |
% then on `register.dtx' to obtain instructions. |
| 11 |
% |
| 12 |
% This program is provided under the terms of the |
| 13 |
% LaTeX Project Public License distributed from CTAN |
| 14 |
% archives in directory macros/latex/base/lppl.txt. |
| 15 |
% |
| 16 |
% This program consists of register.dtx, register.ins, |
| 17 |
% reg_reset.pl, and reg_table.pl. |
| 18 |
% |
| 19 |
%<*dtx> |
| 20 |
\ProvidesFile{register.dtx} |
| 21 |
%</dtx> |
| 22 |
% \fi |
| 23 |
% \CheckSum{804} |
| 24 |
% |
| 25 |
% \def\fileversion{v2.0} |
| 26 |
% \def\filedate{2020/03/22} |
| 27 |
% \title{Register diagrams with field descriptions} |
| 28 |
% \author{Matthew Lovell\\ |
| 29 |
% \texttt{[email protected]} |
| 30 |
% } |
| 31 |
% \date{\filedate} |
| 32 |
% \maketitle |
| 33 |
% |
| 34 |
% \providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@} |
| 35 |
% |
| 36 |
% \begin{abstract} |
| 37 |
% The |register| package is designed for typesetting |
| 38 |
% the programmable elements in digital hardware, i.e., registers. |
| 39 |
% Such registers typically have many fields and can be quite wide; |
| 40 |
% they are thus a challenge to typeset in a consistent manner. |
| 41 |
% This package attempts to address such issues. It is similar |
| 42 |
% in some aspects to the |bitfield| package by Reuben Thomas and the |
| 43 |
% |bytefield| package by Scott Pakin. Authors may also wish to |
| 44 |
% inspect the |bitpattern| package by Jean-Marc Bourguet. |
| 45 |
% \end{abstract} |
| 46 |
% |
| 47 |
% \StopEventually |
| 48 |
% |
| 49 |
% \iffalse |
| 50 |
%<*driver> |
| 51 |
\documentclass{ltxdoc} |
| 52 |
\RequirePackage{textcomp} |
| 53 |
\RequirePackage[TRflags,TRboxed,color]{register} |
| 54 |
\RequirePackage{amsmath} |
| 55 |
\RequirePackage{amssymb} |
| 56 |
\setlength{\regWidth}{0.98\textwidth} |
| 57 |
\setlength{\TRwidth}{40pt} |
| 58 |
\RecordChanges |
| 59 |
\begin{document} |
| 60 |
\DocInput{register.dtx} |
| 61 |
% \PrintChanges |
| 62 |
\end{document} |
| 63 |
%</driver> |
| 64 |
% \fi |
| 65 |
% |
| 66 |
% \listofregisters |
| 67 |
% |
| 68 |
% |
| 69 |
% \section{Introduction} \label{sec:background} |
| 70 |
% |
| 71 |
% My group at work designed the memory and I/O controllers for servers |
| 72 |
% and workstations. Historically, our chip documentation was done |
| 73 |
% with FrameMaker or Microsoft Word. While these approaches have |
| 74 |
% various disadvantages, one of the most egregious was register |
| 75 |
% documentation. |
| 76 |
% |
| 77 |
% The recent chips have 64-bit wide control-status registers (CSR) |
| 78 |
% or, more simply, registers. Add the fact that many of these |
| 79 |
% registers have a large number of single-bit fields, and you get a |
| 80 |
% typesetting challenge. The typical solution was to describe such |
| 81 |
% registers using a table, typing field names vertically if space |
| 82 |
% became a problem. For a complicated register, these tables became |
| 83 |
% quite complex and filled a large portion of a page. |
| 84 |
% |
| 85 |
% When we decided to evaluate \LaTeX{} for documentation, we had three |
| 86 |
% goals in mind with respect to registers: |
| 87 |
% \begin{enumerate} |
| 88 |
% \item Create a method of documenting registers which was consistent |
| 89 |
% and easy to read, regardless of the number of fields within a |
| 90 |
% register. |
| 91 |
% \item Automate the creation of lists of registers, both in order |
| 92 |
% of appearance within the text and in memory address order. |
| 93 |
% \item Enable the automatic extraction of documented register reset |
| 94 |
% values in order to verify register functionality in the chip |
| 95 |
% itself. |
| 96 |
% \end{enumerate} |
| 97 |
% The |register| package is my attempt at meeting all three goals. It |
| 98 |
% was first put into use in April 1999; it may be not be |
| 99 |
% pretty to all eyes, but it certainly has proven itself stable. |
| 100 |
% |
| 101 |
% In order to promote \LaTeX{} within our group at the time, we also |
| 102 |
% adopted \LyX{}. The |register| package thus attempts to work well |
| 103 |
% within that environment. All \LyX{}-specific code, however, is |
| 104 |
% controlled via package options. |
| 105 |
% |
| 106 |
% \subsection{Feedback} |
| 107 |
% |
| 108 |
% As |register| is my first \LaTeX{} package, I would welcome |
| 109 |
% feedback regarding problems, new features, or more proper means of |
| 110 |
% implementing existing features. For example, is there an |
| 111 |
% ``official'' method for determining the current font's maximum |
| 112 |
% height and depth (see Section~\ref{sec:reg_fields} for details)? I |
| 113 |
% would also appreciate knowing whether anyone ever actually uses it. |
| 114 |
% |
| 115 |
% It might also be worthwhile to investigate combining |register| with |
| 116 |
% |bitfield| or |bytefield|. |
| 117 |
% |
| 118 |
% \section{Examples} |
| 119 |
|
| 120 |
% Register~\ref{Diagnostic Control} depicts a register with many |
| 121 |
% single-bit fields. Registers such as this stress any scheme of |
| 122 |
% typesetting, since the field names are so much longer than the space |
| 123 |
% available for them within the diagram. By typesetting the field |
| 124 |
% names at an angle, |register| manages to be consistent regardless of |
| 125 |
% the number or width of fields. This rotation, however, means that |
| 126 |
% documents which use |register| must be produced using PostScript. |
| 127 |
% |
| 128 |
% \begin{register}{H}{Diagnostic Control}{0x1F28}^^A NAME=DIAG_CTRL1 |
| 129 |
% \label{Diagnostic Control}^^A |
| 130 |
% \regfield{reserved}{1}{63}{0}^^A |
| 131 |
% \regfield{cmp\_ack64}{1}{62}{0}^^A |
| 132 |
% \regfield{cmp\_req64}{1}{61}{0}^^A |
| 133 |
% \regfield{cmp\_devsel}{1}{60}{0}^^A |
| 134 |
% \regfield{cmp\_stop}{1}{59}{0}^^A |
| 135 |
% \regfield{cmp\_trdy}{1}{58}{0}^^A |
| 136 |
% \regfield{cmp\_irdy}{1}{57}{0}^^A |
| 137 |
% \regfield{cmp\_frame}{1}{56}{0}^^A |
| 138 |
% \regfield{reserved}{1}{55}{0}^^A |
| 139 |
% \regfield{mask\_ack64}{1}{54}{0}^^A |
| 140 |
% \regfield{mask\_req64}{1}{53}{0}^^A |
| 141 |
% \regfield{mask\_devsel}{1}{52}{0}^^A |
| 142 |
% \regfield{mask\_stop}{1}{51}{0}^^A |
| 143 |
% \regfield{mask\_trdy}{1}{50}{0}^^A |
| 144 |
% \regfield{mask\_irdy}{1}{49}{0}^^A |
| 145 |
% \regfield{mask\_frame}{1}{48}{0}^^A |
| 146 |
% \regfield{cmp\_cbe}{8}{40}{0}^^A |
| 147 |
% \regfield{mask\_cbe}{8}{32}{0}^^A |
| 148 |
% \reglabel{Reset}^^A |
| 149 |
% \regnewline^^A |
| 150 |
% \regfield{reserved}{1}{31}{0}^^A |
| 151 |
% \regfield{cmp\_arb}{7}{24}{0}^^A |
| 152 |
% \regfield{reserved}{1}{23}{0}^^A |
| 153 |
% \regfield{mask\_arb}{7}{16}{0}^^A |
| 154 |
% \regfield{reserved}{5}{11}{0}^^A |
| 155 |
% \regfield{grp\_en\_cntl}{1}{10}{0}^^A |
| 156 |
% \regfield{grp\_en\_cbe}{1}{9}{0}^^A |
| 157 |
% \regfield{grp\_en\_arb}{1}{8}{0}^^A |
| 158 |
% \regfield{grp\_en\_fifo}{1}{7}{0}^^A |
| 159 |
% \regfield{dly\_frame}{1}{6}{0}^^A |
| 160 |
% \regfield{level\_frame}{1}{5}{0}^^A |
| 161 |
% \regfield{level\_cntl}{1}{4}{0}^^A |
| 162 |
% \regfield{level\_cbe}{1}{3}{0}^^A |
| 163 |
% \regfield{level\_arb}{1}{2}{0}^^A |
| 164 |
% \regfield{hlt\_trg\_on\_1}{1}{1}{0}^^A |
| 165 |
% \regfield{alwys\_cnt\_1}{1}{0}{0}^^A |
| 166 |
% \reglabel{Reset}^^A |
| 167 |
% \regnewline^^A |
| 168 |
% \end{register} |
| 169 |
% |
| 170 |
% Register~\ref{Function Class} is an example of a register one could |
| 171 |
% derive from the PCI specification. It is a miscellaneous register |
| 172 |
% in a PCI card which controls device independent functions. Note the |
| 173 |
% field descriptions which, in this case, are actually part of the |
| 174 |
% float. |
| 175 |
% |
| 176 |
% \begin{register}{htbp}{Function Class}{0x0008}^^A NAME=FC |
| 177 |
% \label{Function Class}^^A |
| 178 |
% \regfield{BIST}{8}{56}{0}^^A READ_ONLY |
| 179 |
% \regfield{Header Type}{8}{48}{0}^^A READ_ONLY |
| 180 |
% \regfield{Latency Timer}{8}{40}{0}^^A |
| 181 |
% \regfield{Line Size}{8}{32}{0}^^A |
| 182 |
% \reglabel{Reset}^^A |
| 183 |
% \regnewline^^A |
| 184 |
% \regfield{Class Code}{24}{8}{{0x060000}}^^A READ_ONLY |
| 185 |
% \regfield{Revision}{8}{0}{{0x10}}^^A READ_ONLY |
| 186 |
% \reglabel{Reset}^^A |
| 187 |
% \regnewline^^A |
| 188 |
% \begin{regdesc}^^A |
| 189 |
% |
| 190 |
% \begin{reglist}[Latency Timer] |
| 191 |
% \item [BIST](Read only) Always returns 0. |
| 192 |
% \item [Header~Type](Read only) Always returns 0. |
| 193 |
% \item [Latency~Timer]PCI Latency Timer value (PCI 2.2 spec, Section 6.2.4). |
| 194 |
% \item [Line~Size]PCI Cache Line Size (PCI 2.2 spec, Section 6.2.4). Valid |
| 195 |
% values are listed below; any other value will be treated as indicating |
| 196 |
% 64 byte cache lines. |
| 197 |
% \begin{description} |
| 198 |
% \item [0010\_0000]128 bytes |
| 199 |
% \item [0001\_0000]64 bytes |
| 200 |
% \end{description} |
| 201 |
% \item [Class~Code](Read only) PCI Class Code (PCI 2.2 spec, Section 6.2.1). |
| 202 |
% Chip identifies itself as a Host bridge. |
| 203 |
% \item [Revision](Read only) Chip revision number. Bits 4--7 provide the major |
| 204 |
% revision number, and bits 0--3 provide the minor |
| 205 |
% revision number. |
| 206 |
% \end{reglist} |
| 207 |
% \end{regdesc} |
| 208 |
% \end{register} |
| 209 |
% |
| 210 |
% A final example is shown in Figure~\ref{fig:regbus_cycle}. This |
| 211 |
% example shows that the register drawing macros don't have to be used |
| 212 |
% solely within a |register| float or environment. With Version~1.8, |
| 213 |
% an unnumbered register environment is also available, using |
| 214 |
% |register*|. Diagrams produced using the starred environment |
| 215 |
% typeset just the register name, omitting the ``Register'' and number |
| 216 |
% prefix. |
| 217 |
% |
| 218 |
% \begin{figure}[H] |
| 219 |
% \begin{center}^^A |
| 220 |
% \regfieldb{write\_en}{1}{15}^^A |
| 221 |
% \regfieldb{reserved}{2}{13}^^A |
| 222 |
% \regfieldb{function}{1}{12}^^A |
| 223 |
% \regfieldb{block}{4}{8}^^A |
| 224 |
% \regfieldb{register}{5}{3}^^A |
| 225 |
% \regfieldb{reserved}{3}{0}^^A |
| 226 |
% \reglabelb{Address phase} \\ |
| 227 |
% \regfieldb{reserved}{8}{8}^^A |
| 228 |
% \regfieldb{BE}{8}{0}^^A |
| 229 |
% \reglabelb{BE phase}^^A |
| 230 |
% \end{center}^^A |
| 231 |
% \caption{Address and BE phases for register access}\label{fig:regbus_cycle} |
| 232 |
% \end{figure} |
| 233 |
% |
| 234 |
% |
| 235 |
% \section{User Interface} \label{sec:user} |
| 236 |
% |
| 237 |
% The user interface for register diagrams could be regarded as |
| 238 |
% overly verbose. The main idea behind the parameters was to allow |
| 239 |
% \LaTeX{} \emph{and} accompanying Perl scripts to decipher register |
| 240 |
% fields and reset values. The simplest way to show the interface |
| 241 |
% is via another example. Below is a 64-bit register. |
| 242 |
% \begin{register}{H}{Example}{0x250}^^A name=example |
| 243 |
% \label{example}^^A |
| 244 |
% \regfield{FIFO depth}{6}{58}{{random}}^^A |
| 245 |
% \regfield{Something}{4}{54}{1100}^^A |
| 246 |
% \regfield{Status}{21}{33}{{uninitialized}}^^A |
| 247 |
% \regfield{Enable}{1}{32}{1}^^A |
| 248 |
% \reglabel{Reset}\regnewline^^A |
| 249 |
% \regfield{Counter}{10}{22}{{0x244}}^^A READ_ONLY |
| 250 |
% \regfield{Howdy}{5}{17}{1_1010}^^A |
| 251 |
% \regfield{Control}{1}{16}{-}^^A |
| 252 |
% \regfield{Hardfail}{1}{15}{1}^^A |
| 253 |
% \regfield{Data}{15}{0}{{uninitialized}}^^A |
| 254 |
% \reglabel{Reset}\regnewline^^A |
| 255 |
% \end{register} |
| 256 |
% |
| 257 |
% It was created with the following commands: |
| 258 |
% |
| 259 |
% \begin{verbatim} |
| 260 |
% \begin{register}{H}{Example}{0x250}% name=example |
| 261 |
% \label{example}% |
| 262 |
% \regfield{FIFO depth}{6}{58}{{random}}% |
| 263 |
% \regfield{Something}{4}{54}{1100}% |
| 264 |
% \regfield{Status}{21}{33}{{uninitialized}}% |
| 265 |
% \regfield{Enable}{1}{32}{1}% |
| 266 |
% \reglabel{Reset}\regnewline% |
| 267 |
% \regfield{Counter}{10}{22}{{0x244}}% READ_ONLY |
| 268 |
% \regfield{Howdy}{5}{17}{1_1010}% |
| 269 |
% \regfield{Control}{1}{16}{-}% |
| 270 |
% \regfield{Hardfail}{1}{15}{1}% |
| 271 |
% \regfield{Data}{15}{0}{{uninitialized}}% |
| 272 |
% \reglabel{Reset}%\regnewline% |
| 273 |
% \end{register} |
| 274 |
% \end{verbatim} |
| 275 |
% |
| 276 |
% \begin{macro}{register} |
| 277 |
% \begin{macro}{\listofregisters} |
| 278 |
% The register environment begins with |\begin{register}|. The three |
| 279 |
% parameters to the environment are the float specification (|h|, |H|, |
| 280 |
% |t|, |b|, or |p|); the register name; and the register's offset in |
| 281 |
% memory space. These parameters become the register caption as well |
| 282 |
% as the entry in the list of registers, which is typeset using |
| 283 |
% |\listofregisters|. |
| 284 |
% \end{macro} |
| 285 |
% \end{macro} |
| 286 |
% \hspace*{\MacroIndent}|\begin{register}{|\meta{placement}|}{|^^A |
| 287 |
% \meta{register name}|}{|\meta{register offset}|}| |
| 288 |
% |
| 289 |
% \begin{macro}{\regfield} |
| 290 |
% Each register field is then typeset using |\regfield|. The fields |
| 291 |
% must be specified\footnote{Provided you're a little-endian person!} |
| 292 |
% starting with the most-significant bit. The |\regfield| macro takes |
| 293 |
% four parameters: field name, field length (in bits), starting bit |
| 294 |
% number, and reset value. The reset value, unless you pass it as a |
| 295 |
% single token (see example), will be spread apart to fill up the |
| 296 |
% width of the field. The reset value, since it could be just a |
| 297 |
% very long binary number, can be interrupted with underscores to |
| 298 |
% improve readability. |
| 299 |
% \end{macro} |
| 300 |
% \hspace*{\MacroIndent}|\regfield{|\meta{name}|}{|\meta{length}|}{|^^A |
| 301 |
% \meta{start bit}|}{|\meta{reset value}|}|\\[2pt] |
| 302 |
% |
| 303 |
% Note that the comments that are shown in the code are for the |
| 304 |
% benefit of the helper scripts that accompany the |register| |
| 305 |
% package. Those scripts are quite old and have \emph{not} been |
| 306 |
% updated to be tolerant of the optional color argument that is now |
| 307 |
% supported. However, the general notion of using embedded comments |
| 308 |
% to augment register or field information is still applicable, if |
| 309 |
% one is using this package with the intent of generating HDL code |
| 310 |
% from documentation. |
| 311 |
% |
| 312 |
% \begin{macro}{\regBitWidth} |
| 313 |
% \begin{macro}{\regnewline} |
| 314 |
% \begin{macro}{\reglabel} |
| 315 |
% The macro |\regBitWidth| specifies the maximum number of bits to be |
| 316 |
% typeset on a single line. Once a line has been completed, a new line |
| 317 |
% can be inserted via |\regnewline|. Before starting a new line, |
| 318 |
% however, an appropriate label for the reset value should be typed. |
| 319 |
% This label is generated via |\reglabel|, which takes the string to |
| 320 |
% typeset as a single parameter. The package, via the macro |
| 321 |
% |\regResetName|, assumes that |Reset| will be used in order to set |
| 322 |
% some lengths appropriately; it really only matters for very full |
| 323 |
% lines. In a future version, it may be possible to make |
| 324 |
% |\regResetName| be the default parameter to |\reglabel|. |
| 325 |
% \end{macro} |
| 326 |
% \end{macro} |
| 327 |
% \end{macro} |
| 328 |
% \hspace*{\MacroIndent}|\reglabel{|\meta{reset label}|}|\\[2pt] |
| 329 |
% |
| 330 |
% |
| 331 |
% As another example, consider Register~\ref{Configuration} below, which has |
| 332 |
% field descriptions as part of the float. This diagram was created |
| 333 |
% with the following code: |
| 334 |
% \begin{verbatim} |
| 335 |
% \begin{register}{htbp}{Configuration}{0x2848}% name=CONFIG |
| 336 |
% \label{Configuration}% |
| 337 |
% \regfield{soft reset perf}{1}{63}{0}% STATUS |
| 338 |
% \regfield{reserved}{30}{33}{0}% |
| 339 |
% \regfield{Test mode}{1}{32}{0}% |
| 340 |
% \reglabel{Reset}\regnewline% |
| 341 |
% \regfield{reserved}{13}{19}{0}% |
| 342 |
% \regfield{\parbox[b]{0pt}{Request Depth}}{7}{12}{1}% |
| 343 |
% \regfield{reserved}{3}{9}{0}% |
| 344 |
% \regfield{line\_2x\_L}{1}{8}{?}% STATUS |
| 345 |
% \regfield{reserved}{1}{7}{0}% |
| 346 |
% \regfield{ill\_cmd\_enable}{1}{6}{0}% |
| 347 |
% \regfield{LPCE}{1}{5}{0}% |
| 348 |
% \regfield{DVI disable}{1}{4}{0}% |
| 349 |
% \regfield{SBA enable}{1}{3}{0}% |
| 350 |
% \regfield{reserved}{2}{1}{0}% |
| 351 |
% \regfield{line\_2x\_enable}{1}{0}{0}% READ_ONLY |
| 352 |
% \reglabel{Reset}\regnewline% |
| 353 |
% \begin{regdesc}\begin{reglist}[Request~Depth] |
| 354 |
% \item [line\_2x\_enable]Setting this bit enables the chip |
| 355 |
% to utilize a second connected data line. |
| 356 |
% \item [SBA~enable]Setting this bit activates the sideband-address port. |
| 357 |
% The SBA port is only useable in a double-line configuration. |
| 358 |
% \item [DVI~disable]Setting this bit \emph{turns off} DVI extraction for |
| 359 |
% DMA requests. |
| 360 |
% \item [LPCE]Line Parity Check Enable. |
| 361 |
% \item [ill\_cmd\_enable]\TR{3}Illegal Command enable. |
| 362 |
% This bit is new for TR3. |
| 363 |
% \item [line\_2x\_L](Read only) Indicates whether this chip is connected |
| 364 |
% to a second data line. When this bit is 0, a second line |
| 365 |
% is available. |
| 366 |
% \item [Request~Depth]Controls number of outstanding DMA requests. |
| 367 |
% \item [Test~mode]Activates data line test mode. |
| 368 |
% \item [soft~reset~perf]\TR{4}Indicates that a soft reset has been |
| 369 |
% performed. This bit is new for TR4. |
| 370 |
% \end{reglist}\end{regdesc}\end{register} |
| 371 |
% \end{verbatim} |
| 372 |
% |
| 373 |
% |
| 374 |
% \begin{register}{htbp}{Configuration}{0x2848}^^A NAME=CONFIG |
| 375 |
% \label{Configuration}^^A |
| 376 |
% \regfield{soft reset perf}{1}{63}{0}^^A STATUS |
| 377 |
% \regfield{reserved}{30}{33}{0}^^A |
| 378 |
% \regfield{Test mode}{1}{32}{0}^^A |
| 379 |
% \reglabel{Reset}\regnewline^^A |
| 380 |
% \regfield{reserved}{13}{19}{0}^^A |
| 381 |
% \regfield{\parbox[b]{0pt}{Request Depth}}{7}{12}{1}^^A |
| 382 |
% \regfield{reserved}{3}{9}{0}^^A |
| 383 |
% \regfield{line\_2x\_L}{1}{8}{?}^^A STATUS |
| 384 |
% \regfield{reserved}{1}{7}{0}^^A |
| 385 |
% \regfield{ill\_cmd\_enable}{1}{6}{0}^^A |
| 386 |
% \regfield{PCE}{1}{5}{0}^^A |
| 387 |
% \regfield{DVI disable}{1}{4}{0}^^A |
| 388 |
% \regfield{SBA enable}{1}{3}{0}^^A |
| 389 |
% \regfield{reserved}{2}{1}{0}^^A |
| 390 |
% \regfield{line\_2x\_enable}{1}{0}{0}^^A READ_ONLY |
| 391 |
% \reglabel{Reset}\regnewline^^A |
| 392 |
% |
| 393 |
% \begin{regdesc}\begin{reglist}[Request~Depth] |
| 394 |
% \item [line\_2x\_enable]Setting this bit enables this chip to utilize a second |
| 395 |
% connected data line. |
| 396 |
% \item [SBA~enable]Setting this bit activates the sideband-address port. |
| 397 |
% The SBA port is only useable in a double-line configuration. |
| 398 |
% \item [DVI~disable]Setting this bit \emph{turns off} DVI extraction for |
| 399 |
% DMA requests. |
| 400 |
% \item [LPCE]Line Parity Check Enable. |
| 401 |
% \item [ill\_cmd\_enable]\TR{3}Illegal OCMD enable. |
| 402 |
% This bit is new for TR3. |
| 403 |
% \item [line\_2x\_L](Read only) Indicates whether this chip is connected |
| 404 |
% to a second data line. When this bit is 0, a second line is available. |
| 405 |
% \item [Request~Depth]Controls number of outstanding DMA requests. |
| 406 |
% \item [Test~mode]Activates data line test mode. |
| 407 |
% \item [soft~reset~perf]\TR{4}Indicates that a soft reset has been |
| 408 |
% performed. This bit is new for TR4. |
| 409 |
% \end{reglist}\end{regdesc}\end{register} |
| 410 |
% |
| 411 |
% \begin{macro}{regdesc} |
| 412 |
% \begin{macro}{reglist} |
| 413 |
% \begin{macro}{lyxlist} |
| 414 |
|
| 415 |
% This example uses the |regdesc| environment, which can either be |
| 416 |
% part of a register float or used standalone. The purpose of |
| 417 |
% |regdesc| is really just to turn on centering and, when the |LyX| |
| 418 |
% package option is specified, redefine the |lyxlist| environment. If |
| 419 |
% one is using \LyX{}, then register field descriptions can be entered |
| 420 |
% using its List type. If one is typing \LaTeX{} directly, just use |
| 421 |
% the |reglist| list definition. |
| 422 |
% \end{macro} |
| 423 |
% \end{macro} |
| 424 |
% \end{macro} |
| 425 |
% |
| 426 |
% The |regdesc| and |reglist| environments both take optional |
| 427 |
% arguments. For |regdesc|, the optional argument specifies how wide |
| 428 |
% the register description body should be. The default value is 90\% |
| 429 |
% of |\textwidth|. For |reglist|, the optional argument is the |
| 430 |
% longest field name, which allows the list to be spaced appropriately |
| 431 |
% (like examples given in \emph{The \LaTeX{} Companion}). |
| 432 |
% |
| 433 |
% \begin{macro}{\regfieldb} |
| 434 |
% Finally, if a register with no reset values is desired, one can use |
| 435 |
% the |\regfieldb| macro. It takes the same first three arguments as |
| 436 |
% |\regfield|. Figure~\ref{fig:regbus_cycle} was produced using |\regfieldb|. |
| 437 |
% \end{macro} |
| 438 |
% |
| 439 |
% |
| 440 |
% |
| 441 |
% \subsection{TR Flags} |
| 442 |
% |
| 443 |
% \begin{macro}{\TR} |
| 444 |
% The previous example also shows the TR flags. These marginal notes can |
| 445 |
% be used to denote features that are specific to a particular release |
| 446 |
% of a chip. These macros were created since \LaTeX{}'s |\marginpar| |
| 447 |
% is itself a float; as such it cannot be nested inside other floats. |
| 448 |
% The |\TR| macros thus implement something very similar to the |
| 449 |
% solution for Problem~14.28 in \emph{The \TeX{}book}. |
| 450 |
|
| 451 |
% TR flags are turned on via the |TRflags| package option. If the |
| 452 |
% option is not specified, then the |\TR| macro still exists but is |
| 453 |
% empty. The TR flags are placed inside an |\fbox| if the |TRboxed| |
| 454 |
% package option is specified. |
| 455 |
% |
| 456 |
% For two-sided documents, the TR flags are placed in the outer |
| 457 |
% margins. The placement decision is made by placing labels for each |
| 458 |
% TR flag and then determining even/odd page numbering in a subsequent |
| 459 |
% \LaTeX{} run. |
| 460 |
% \end{macro} |
| 461 |
% |
| 462 |
% \subsection{Background Colors} \label{sec:colors} |
| 463 |
% |
| 464 |
% With Version 1.7, this package also supports an optional |color| package option. If that option |
| 465 |
% is present, then |xcolor| is loaded and the |\regfield| and |\regfieldb| macros support an |
| 466 |
% optional first argument that is used as fill color for the boxes drawn by |\framebox|. Internally, |
| 467 |
% |\colorbox| is used to provide this functionality. |
| 468 |
% |
| 469 |
% Repeating our example from earlier, but with some fill colors specified: |
| 470 |
% \begin{verbatim} |
| 471 |
% \begin{register}{H}{Color Example}{0x250}% name=example |
| 472 |
% \label{colexample}% |
| 473 |
% \regfield{FIFO depth}{6}{58}{{random}}% |
| 474 |
% \regfield[green!30]{Something}{4}{54}{1100}% |
| 475 |
% \regfield[gray!20]{Status}{21}{33}{{uninitialized}}% |
| 476 |
% \regfield{Enable}{1}{32}{1}% |
| 477 |
% \reglabel{Reset}\regnewline% |
| 478 |
% \regfield{Counter}{10}{22}{{0x244}}% READ_ONLY |
| 479 |
% \regfield[red!20]{Howdy}{5}{17}{1_1010}% |
| 480 |
% \regfield{Control}{1}{16}{-}% |
| 481 |
% \regfield[yellow!50]{Hardfail}{1}{15}{1}% |
| 482 |
% \regfield[gray!20]{Data}{15}{0}{{uninitialized}}% |
| 483 |
% \reglabel{Reset}%\regnewline% |
| 484 |
% \end{register} |
| 485 |
% \end{verbatim} |
| 486 |
% now yields the following: |
| 487 |
% \begin{register}{H}{Color Example}{0x250}^^A name=example |
| 488 |
% \label{colexample}^^A |
| 489 |
% \regfield{FIFO depth}{6}{58}{{random}}^^A |
| 490 |
% \regfield[green!30]{Something}{4}{54}{1100}^^A |
| 491 |
% \regfield[gray!20]{Status}{21}{33}{{uninitialized}}^^A |
| 492 |
% \regfield{Enable}{1}{32}{1}^^A |
| 493 |
% \reglabel{Reset}\regnewline^^A |
| 494 |
% \regfield{Counter}{10}{22}{{0x244}}^^A READ_ONLY |
| 495 |
% \regfield[red!20]{Howdy}{5}{17}{1_1010}^^A |
| 496 |
% \regfield{Control}{1}{16}{-}^^A |
| 497 |
% \regfield[yellow!50]{Hardfail}{1}{15}{1}^^A |
| 498 |
% \regfield[gray!20]{Data}{15}{0}{{uninitialized}}^^A |
| 499 |
% \reglabel{Reset}%\regnewline^^A |
| 500 |
% \end{register} |
| 501 |
% |
| 502 |
% \section{Helper Scripts} \label{sec:scripts} |
| 503 |
% |
| 504 |
% A (now old) Perl module and a Perl script are included as part of the |
| 505 |
% |register| package. The module augments the package by |
| 506 |
% providing the ability to parse the register macro information into |
| 507 |
% Perl. This information consists of the parameters used within |
| 508 |
% the macros themselves, as well as the comments which follow. If |
| 509 |
% you examine the last register example, you will notice that some |
| 510 |
% fields specify |READ\_ONLY| or |STATUS| in a comment. The |
| 511 |
% ``directives'' can be used to indicate that particular fields are |
| 512 |
% unaffected by writes or unaffected by reset, respectively. |
| 513 |
% |
| 514 |
% The script, |reg_list.pl|, utilizes the Perl module to produce lists |
| 515 |
% of registers in offset-order or to generate reset value and mask |
| 516 |
% information for each register. The later data can be used in |
| 517 |
% simulation to ensure that registers behave as documented. |
| 518 |
% |
| 519 |
% Users are cautioned that the Perl script, since it is no longer in |
| 520 |
% active use by the author, has not been modified to support the |
| 521 |
% optional color argument for the |regfield| macro. |
| 522 |
% |
| 523 |
% \section{Version History} \label{sec:history} |
| 524 |
% |
| 525 |
% \begin{itemize} |
| 526 |
% \item [\textbf{v0.1}] (1999/03/29) First release |
| 527 |
% \item [\textbf{v0.2}] (2000/01/29) Added regdesc environment, for use under LyX |
| 528 |
% \item [\textbf{v0.21}] (2000/03/12) Fixed minute problem shown in regs with lots of 1-bit fields |
| 529 |
% \item [\textbf{v0.3}] (2000/06/19) Added reglabelb macro, for setting label without a drop |
| 530 |
% \item [\textbf{v0.31}] (2000/07/11) Modified names of lengths used within macros |
| 531 |
% \item [\textbf{v0.32}] (2000/08/02) Modified regdesc env to use regdescsep for vertical separation |
| 532 |
% \item [\textbf{v0.4}] (2001/08/11) Added macros for marginal Tape Release flags |
| 533 |
% \item [\textbf{v0.5}] (2001/08/12) Added package options for handling LyX, hyperref, and TR flags |
| 534 |
% \item [\textbf{v0.6}] (2001/08/19) Moved chapter redefinition into package; improved TR flags |
| 535 |
% \item [\textbf{v1.0}] (2001/09/06) Created .dtx documentation; first public release |
| 536 |
% \item [\textbf{v1.01}] (2003/01/17) Removed automatic label in register diagrams |
| 537 |
% \item [\textbf{v1.1}] (2003/02/15) Changed length manipulation to work with parskip package |
| 538 |
% \item [\textbf{v1.2}] (2003/03/31) Removed requirement to specify register offset |
| 539 |
% \item [\textbf{v1.3}] (2003/11/24) Changed how center is handled within register environment |
| 540 |
% \item [\textbf{v1.4}] (2004/08/16) Now provide a boolean set only in register context |
| 541 |
% \item [\textbf{v1.5}] (2007/03/08) Corrected use of conditionals used in spreading register reset value |
| 542 |
% \item [\textbf{v1.6}] (2011/01/11) Mainmatter correction suggested by Kjetil Oftedal |
| 543 |
% \item [\textbf{v1.6.1}] (2018/05/19) Published with updated email address; no functional changes |
| 544 |
% \item [\textbf{v1.7}] (2018/08/18) Added color option to package, suggested by Marco Stolba |
| 545 |
% \item [\textbf{v1.8}] (2018/11/10) Added unnumbered |register*| environment, suggested and written by Stephan Bauroth |
| 546 |
% \item [\textbf{v1.9}] (2019/01/01) Switched to a re-definable macro to provide default float name and LoR name, suggested by Benyuan Liu. |
| 547 |
% \item [\textbf{v2.0}] (2020/03/22) Added package options for captions and replaced |\bf| usage, suggested by Andrea Bettati. % |
| 548 |
% Also attempt to work better with |memoir| class. |
| 549 |
% \end{itemize} |
| 550 |
% |
| 551 |
% |
| 552 |
% ^^A ------------------------------------------------------------------------- |
| 553 |
% \newpage |
| 554 |
% |
| 555 |
% \section{Implementation} \label{sec:docstrip} |
| 556 |
% |
| 557 |
% \subsection{Identification \& Options} \label{sec:id} |
| 558 |
% |
| 559 |
% The |register| document class can only be used with \LaTeXe, so we make |
| 560 |
% sure that an appropriate message is displayed when another \TeX{} |
| 561 |
% format is used. |
| 562 |
% \begin{macrocode} |
| 563 |
%<*package>\NeedsTeXFormat{LaTeX2e} |
| 564 |
% \end{macrocode} |
| 565 |
% |
| 566 |
% Announce the name and unconditionally load most of the required packages: |
| 567 |
% \begin{macrocode} |
| 568 |
\ProvidesPackage{register} [2020/03/22 v2.0 Register macros with |
| 569 |
hyperref/LyX support] |
| 570 |
|
| 571 |
\RequirePackage{ifthen}[1997/11/02] |
| 572 |
\RequirePackage{graphicx}[1997/06/09] |
| 573 |
\RequirePackage{float}[2001/07/25] |
| 574 |
\RequirePackage{calc}[1998/06/07] |
| 575 |
% \end{macrocode} |
| 576 |
% |
| 577 |
% Declare the package options and some booleans. There are options indicating |
| 578 |
% whether |register| is being used with \LyX{} or |hyperref|. The marginal |
| 579 |
% TR flags can also be turned on or off with an option. A new package |
| 580 |
% option, |botcaption| serves to change the default caption location to |
| 581 |
% below the register diagram, rather than above. Finally, |nocaption| turns |
| 582 |
% off the |\caption| invocation internal to the |register| environment |
| 583 |
% entirely, for users who would rather craft their own caption. Note than |
| 584 |
% one can specify \emph{both} |botcaption| and |nocaption| -- explicit |
| 585 |
% author-specified captions would then appear at the bottom of each diagram. |
| 586 |
% \begin{macrocode} |
| 587 |
% |
| 588 |
\DeclareOption{LyX}{\setboolean{RegisterLyX}{true}} |
| 589 |
\DeclareOption{hyperref}{\setboolean{RegisterHyperref}{true}} |
| 590 |
\DeclareOption{TRflags}{\setboolean{RegisterTRFlags}{true}} |
| 591 |
\DeclareOption{TRboxed}{\setboolean{RegisterTRBoxed}{true}} |
| 592 |
\DeclareOption{color}{\setboolean{RegisterColors}{true}} |
| 593 |
\DeclareOption{botcaption}{\setboolean{RegisterBottom}{true}} |
| 594 |
\DeclareOption{nocaption}{\setboolean{RegisterNoCaption}{true}} |
| 595 |
|
| 596 |
\DeclareOption*{% Emit a warning for other options |
| 597 |
\PackageWarning{register}{Unknown option '\CurrentOption'}% |
| 598 |
} |
| 599 |
|
| 600 |
\newboolean{RegisterLyX}% Work with LyX |
| 601 |
\newboolean{RegisterHyperref}% Work with hyperref package |
| 602 |
\newboolean{RegisterTRFlags}% TR release flags |
| 603 |
\newboolean{RegisterTRBoxed}% Place frame around TR flags |
| 604 |
\newboolean{RegisterColors}% Permit color-filling register fields |
| 605 |
\newboolean{RegisterBottom}% Move caption location to beneath register |
| 606 |
\newboolean{RegisterNoCaption}% Disable environment's built-in caption |
| 607 |
|
| 608 |
\setboolean{RegisterLyX}{false} |
| 609 |
\setboolean{RegisterHyperref}{false} |
| 610 |
\setboolean{RegisterTRFlags}{false} |
| 611 |
\setboolean{RegisterTRBoxed}{false} |
| 612 |
\setboolean{RegisterColors}{false} |
| 613 |
\setboolean{RegisterBottom}{false} |
| 614 |
\setboolean{RegisterNoCaption}{false} |
| 615 |
|
| 616 |
\ProcessOptions\relax % Process package options |
| 617 |
% \end{macrocode} |
| 618 |
% |
| 619 |
% |
| 620 |
% If the |color| package option has been specified, go ahead and |
| 621 |
% load the |xcolor| package as well. |
| 622 |
% \begin{macrocode} |
| 623 |
\ifthenelse{\boolean{RegisterColors}}{\RequirePackage{xcolor}[2007/01/21]}{} |
| 624 |
% \end{macrocode} |
| 625 |
% |
| 626 |
% Next, provide a flag indicating when one is inside a register |
| 627 |
% context. Some users may wish to define macros, for example, |
| 628 |
% which make use of |\marginpar|. Those cannot be used inside |
| 629 |
% of a floating register. So, this flag is provided to |
| 630 |
% provide something to test against. |
| 631 |
% \begin{macrocode} |
| 632 |
\newboolean{RegisterContext} |
| 633 |
\setboolean{RegisterContext}{false} |
| 634 |
% \end{macrocode} |
| 635 |
% |
| 636 |
% \begin{macro}{\regFloatName} |
| 637 |
% \begin{macro}{\regListName} |
| 638 |
% \begin{macro}{\regResetName} |
| 639 |
% Below are some macros that support a little internationalization, expanded |
| 640 |
% upon a suggestion from Benyuan Liu. |
| 641 |
% The |\regFloatName| provides the default string used to label each register diagram. |
| 642 |
% The string with which to label reset values is |\regResetName|. |
| 643 |
% The font size for field names and for the |\regResetName| is controlled by |\regLabelSize|, defined further below. |
| 644 |
% \end{macro} |
| 645 |
% \end{macro} |
| 646 |
% \end{macro} |
| 647 |
% |
| 648 |
% \begin{macrocode} |
| 649 |
\newcommand{\regFloatName}{Register} |
| 650 |
\newcommand{\regListName}{List of Registers} |
| 651 |
\newcommand{\regResetName}{Reset} |
| 652 |
% \end{macrocode} |
| 653 |
|
| 654 |
|
| 655 |
% \subsection{New Float Declaration} \label{sec:float} |
| 656 |
% |
| 657 |
% Declare the new register float type and the lengths which the |
| 658 |
% macros will use. The register diagrams tend to look best with |
| 659 |
% the caption at the top of the float. Note, however, that caption |
| 660 |
% placement \emph{can} be changed in the document itself. For example, |
| 661 |
% one can use the macro |\floatstyle{plain}|, followed by |
| 662 |
% |\restylefloat{Regfloat}|, to alter how all subsequent register |
| 663 |
% captions are typeset. |
| 664 |
% |
| 665 |
% \begin{macrocode} |
| 666 |
\ifthenelse{\boolean{RegisterBottom}}{\floatstyle{plain}}{\floatstyle{plaintop}} |
| 667 |
% \end{macrocode} |
| 668 |
% |
| 669 |
% If |\chapter| is defined in |
| 670 |
% the current document class, then the register diagrams will count |
| 671 |
% by chapter, otherwise they will count by section. |
| 672 |
% |
| 673 |
% \begin{macrocode} |
| 674 |
\@ifundefined{chapter} |
| 675 |
{\newfloat{Regfloat}{tbp}{rdf}[section]} |
| 676 |
{\newfloat{Regfloat}{tbp}{rdf}[chapter]} |
| 677 |
\floatname{Regfloat}{\regFloatName} |
| 678 |
% \end{macrocode} |
| 679 |
% |
| 680 |
% \subsection{Style Parameters} \label{sec:style} |
| 681 |
% |
| 682 |
% \begin{macro}{\regWidth} |
| 683 |
% \begin{macro}{\regBitWidth} |
| 684 |
% The |\regWidth| length controls how physically wide the register |
| 685 |
% diagrams are, while |\regBitWidth| specifies how the maximum |
| 686 |
% number of bits per line in the diagram. The default value |
| 687 |
% for |\regWidth| is 95\% of the width of the main text body. |
| 688 |
% \end{macro} |
| 689 |
% \end{macro} |
| 690 |
% |
| 691 |
% \begin{macro}{\regBitSize} |
| 692 |
% \begin{macro}{\regBitFamily} |
| 693 |
% \begin{macro}{\regResetSize} |
| 694 |
% \begin{macro}{\regLabelSize} |
| 695 |
% \begin{macro}{\regLabelFamily} |
| 696 |
% \begin{macro}{\regDescFamily} |
| 697 |
% The |\regBitSize| command controls the font size |
| 698 |
% used for bit values, |\regResetSize| controls the font size used |
| 699 |
% for reset values, and |\regBitFamily| controls which font family |
| 700 |
% is used to denote bit positions. |
| 701 |
% Finally, |\regDescFamily| controls the appearance of field names |
| 702 |
% within register descriptions. |
| 703 |
% \end{macro} |
| 704 |
% \end{macro} |
| 705 |
% \end{macro} |
| 706 |
% \end{macro} |
| 707 |
% \end{macro} |
| 708 |
% \end{macro} |
| 709 |
% |
| 710 |
% \begin{macrocode} |
| 711 |
\newlength{\regWidth} |
| 712 |
\newlength{\regFieldLen} |
| 713 |
\newlength{\regLabelAdjust} |
| 714 |
\newlength{\regResetHeight} |
| 715 |
\newlength{\regResetDepth} |
| 716 |
\newlength{\regResetDrop} |
| 717 |
\newlength{\regDescSkip} |
| 718 |
\newlength{\regRsvdHeight} |
| 719 |
\newlength{\regRsvdDrop} |
| 720 |
\newlength{\regFboxSep} |
| 721 |
\setlength{\regWidth}{0.95\textwidth} |
| 722 |
\newcommand{\regBitWidth}{32} |
| 723 |
\newcommand{\regBitSize}{\tiny} |
| 724 |
\newcommand{\regBitFamily}{\sffamily} |
| 725 |
\newcommand{\regResetSize}{\scriptsize} |
| 726 |
\newcommand{\regLabelSize}{\footnotesize} |
| 727 |
\newcommand{\regLabelFamily}{\rmfamily} |
| 728 |
\newcommand{\regDescFamily}{\bfseries} |
| 729 |
% \end{macrocode} |
| 730 |
% The lengths below control the vertical spacing between a |
| 731 |
% register diagrams and the register field descriptions. This |
| 732 |
% distance must change when the |\regdesc| is part of the |\Regfloat| |
| 733 |
% or standalone. |
| 734 |
% \begin{macrocode} |
| 735 |
\newlength{\regdescsep} |
| 736 |
\newlength{\oldregdescsep} |
| 737 |
\setlength{\regdescsep}{-\medskipamount} |
| 738 |
|
| 739 |
\newsavebox{\Label} |
| 740 |
\newsavebox{\RotatedLabel} |
| 741 |
\newcounter{upperbit} |
| 742 |
\newcounter{lowerbit} |
| 743 |
% \end{macrocode} |
| 744 |
% |
| 745 |
% \subsection{Register macros} \label{sec:regdesc} |
| 746 |
% |
| 747 |
% \begin{macro}{\reglist} |
| 748 |
% Define a new environment for register field descriptions, |
| 749 |
% beneath a register diagram. These descriptions can indicate what |
| 750 |
% a particular field is used for, whether it is read-only, etc. The |
| 751 |
% field descriptions themselves are in a |\reglist| list environment, |
| 752 |
% unless \LyX{} is being used. |
| 753 |
% \end{macro} |
| 754 |
% \begin{macrocode} |
| 755 |
\newenvironment{reglist}[1][M] |
| 756 |
{\begin{list}{} |
| 757 |
{\settowidth{\labelwidth}{\regDescFamily #1} |
| 758 |
\addtolength{\labelwidth}{\labelsep} |
| 759 |
\setlength{\leftmargin}{\labelwidth} |
| 760 |
\addtolength{\leftmargin}{\labelsep} |
| 761 |
\addtolength{\leftmargin}{0.5\regDescSkip} |
| 762 |
\addtolength{\rightmargin}{0.5\regDescSkip} |
| 763 |
\setlength{\topsep}{0pt} |
| 764 |
\setlength{\itemsep}{0pt} |
| 765 |
\setlength{\parsep}{0.5\baselineskip} |
| 766 |
\renewcommand{\makelabel}[1]{\regDescFamily ##1 \hfill}}} |
| 767 |
{\end{list}} |
| 768 |
% \end{macrocode} |
| 769 |
% |
| 770 |
% |
| 771 |
% \begin{macro}{\regdesc} |
| 772 |
% Next is the |\regdesc| environment. If \LyX{} is being used, |
| 773 |
% the environment temporarily redefines the |lyxlist| environment, which |
| 774 |
% is what \LyX{} provides as the default list structure. Otherwise, |
| 775 |
% the user is left to use |\reglist|. The redefinition should look very |
| 776 |
% similar to that for |\reglist|. |
| 777 |
% |
| 778 |
% In all cases, |\regdesc| starts by attempting to place a small |
| 779 |
% amount of vertical space between it and the presumed register |
| 780 |
% diagram immediately above it. |
| 781 |
% \end{macro} |
| 782 |
% \begin{macrocode} |
| 783 |
\newenvironment{regdesc}[1][0.90\textwidth]% |
| 784 |
% --------------------------------------------- |
| 785 |
{% |
| 786 |
\setlength{\regDescSkip}{\textwidth - #1}% |
| 787 |
\vspace{\regdescsep}% |
| 788 |
\ifthenelse{\boolean{RegisterLyX}}{% |
| 789 |
\renewenvironment{lyxlist}[1] |
| 790 |
{\begin{list}{} |
| 791 |
{\settowidth{\labelwidth}{\regDescFamily ##1} |
| 792 |
\addtolength{\labelwidth}{\labelsep} |
| 793 |
\setlength{\leftmargin}{\labelwidth} |
| 794 |
\addtolength{\leftmargin}{\labelsep} |
| 795 |
\addtolength{\leftmargin}{0.5\regDescSkip} |
| 796 |
\addtolength{\rightmargin}{0.5\regDescSkip} |
| 797 |
\setlength{\topsep}{0pt} |
| 798 |
%\setlength{\partopsep}{0pt} |
| 799 |
\renewcommand{\makelabel}[1]{\regDescFamily ####1 \hfill}}} |
| 800 |
{\end{list}}}{}% |
| 801 |
% endif |
| 802 |
% set spacing appropriately |
| 803 |
\leftskip 0.5\regDescSkip% |
| 804 |
\rightskip 0.5\regDescSkip% |
| 805 |
\parfillskip=\z@ plus 1fil% |
| 806 |
\parskip=0.5\baselineskip \advance\parskip by 0pt plus 2pt% |
| 807 |
}% end begin{regdesc} |
| 808 |
% -------------------------------------------- |
| 809 |
{\vskip\baselineskip} |
| 810 |
% \end{macrocode} |
| 811 |
% |
| 812 |
% \begin{macro}{\regnewline} |
| 813 |
% This command allows a register diagram to be broken into multiple lines |
| 814 |
% \end{macro} |
| 815 |
% \begin{macrocode} |
| 816 |
\newcommand{\regnewline}{\\*} |
| 817 |
% \end{macrocode} |
| 818 |
% |
| 819 |
% |
| 820 |
% \begin{macro}{\register} |
| 821 |
% This environment declares the floating environment in which a |
| 822 |
% register diagram and, optionally, its field descriptions can be |
| 823 |
% typeset. It takes as arguments the float type (h, t, p, H); the |
| 824 |
% register name; and the register offset/address. |
| 825 |
% \end{macro} |
| 826 |
% \begin{macrocode} |
| 827 |
\newenvironment{register}[3] |
| 828 |
{\begin{Regfloat}[#1]% |
| 829 |
\setlength{\leftskip}{0pt}% |
| 830 |
\setlength{\oldregdescsep}{\regdescsep}% |
| 831 |
\setlength{\regdescsep}{0.5\baselineskip}% |
| 832 |
\setlength{\partopsep}{0pt}% |
| 833 |
\setlength{\topsep}{0pt}% |
| 834 |
\setboolean{RegisterContext}{true}% |
| 835 |
\ifthenelse{\boolean{RegisterNoCaption}}{}% |
| 836 |
{\ifthenelse{\equal{#3}{}}% |
| 837 |
{\caption[#2]{\textsc{#2}}}% else |
| 838 |
{\caption[#2]{\textsc{#2} ({#3})}}% |
| 839 |
}% |
| 840 |
\centering} |
| 841 |
{% restore lengths |
| 842 |
\leftskip\z@% |
| 843 |
\rightskip\z@% |
| 844 |
\parfillskip=\z@ plus 1fil% |
| 845 |
\setlength{\regdescsep}{\oldregdescsep}% |
| 846 |
\setboolean{RegisterContext}{false}% |
| 847 |
\end{Regfloat}} |
| 848 |
% \end{macrocode} |
| 849 |
% |
| 850 |
% \begin{macro}{\register*} |
| 851 |
% This register* environment provides for an unnumbered or ``captionless'' register; |
| 852 |
% registers in such an environment are not added to the list of registers. |
| 853 |
% \end{macro} |
| 854 |
% \begin{macrocode} |
| 855 |
\newenvironment{register*}[3] |
| 856 |
{\begin{Regfloat}[#1]% |
| 857 |
\setlength{\leftskip}{0pt}% |
| 858 |
\setlength{\oldregdescsep}{\regdescsep}% |
| 859 |
\setlength{\regdescsep}{0.5\baselineskip}% |
| 860 |
\setlength{\partopsep}{0pt}% |
| 861 |
\setlength{\topsep}{0pt}% |
| 862 |
\setboolean{RegisterContext}{true}% |
| 863 |
\ifthenelse{\equal{#3}{}}% |
| 864 |
{\centering\textsc{#2}\\}% else |
| 865 |
{\centering\textsc{#2} ({#3})\\}% |
| 866 |
\centering} |
| 867 |
{% restore lengths |
| 868 |
\leftskip\z@% |
| 869 |
\rightskip\z@% |
| 870 |
\parfillskip=\z@ plus 1fil% |
| 871 |
\setlength{\regdescsep}{\oldregdescsep}% |
| 872 |
\setboolean{RegisterContext}{false}% |
| 873 |
\end{Regfloat}} |
| 874 |
% \end{macrocode} |
| 875 |
% |
| 876 |
% |
| 877 |
% \begin{macro}{\regUnderScore} |
| 878 |
% \begin{macro}{\regFiller} |
| 879 |
% \begin{macro}{\regSpread} |
| 880 |
% The next definitions provide a method of spreading out |
| 881 |
% an argument, i.e., placing |\hfill|'s between each character. |
| 882 |
% They can be used to space the reset value of a register field |
| 883 |
% appropriately. Previous versions of these macros used \TeX{}'s |
| 884 |
% conditionals incorrectly. |
| 885 |
% |
| 886 |
% If you are using the |underscore| package, you should |
| 887 |
% \emph{repeat} the definition of |\regUnderScore|, after loading |
| 888 |
% |underscore| in order to observe the changes made by that package. |
| 889 |
% The spreading macros below strive to strip out underscores. |
| 890 |
% \end{macro} |
| 891 |
% \end{macro} |
| 892 |
% \end{macro} |
| 893 |
% \begin{macrocode} |
| 894 |
\def\regUnderScore{_}% |
| 895 |
\def\regFiller#1{\def\regInner{#1}% |
| 896 |
\ifx\regInner\regUnderScore% |
| 897 |
\else% |
| 898 |
\ifnum\count0>0% |
| 899 |
\hfill#1% |
| 900 |
\else#1\fi% |
| 901 |
\fi% |
| 902 |
\advance\count0 by 1% |
| 903 |
} |
| 904 |
\def\regSpread#1{\count0=0{}\regSpreadaux#1\empty} |
| 905 |
\def\regSpreadaux#1#2\empty{\def\aux{#1}%\show#1% |
| 906 |
\ifx\aux\empty% |
| 907 |
\else% |
| 908 |
\def\aux{#2}% |
| 909 |
\regFiller{#1}% |
| 910 |
\ifx\aux\empty% |
| 911 |
\else% |
| 912 |
\regSpreadaux#2\empty% |
| 913 |
\fi\fi} |
| 914 |
% \end{macrocode} |
| 915 |
% |
| 916 |
% |
| 917 |
% \subsubsection{Register fields} \label{sec:reg_fields} |
| 918 |
% |
| 919 |
% Define some internal utility macros which get called repeatedly. |
| 920 |
% These macros figure out some of the dimensions of the current font |
| 921 |
% (is there a better way to do this?), construct and rotate label |
| 922 |
% boxes, and typeset bit positions. |
| 923 |
% \begin{macrocode} |
| 924 |
\newcommand{\setRegLengths}{% |
| 925 |
% Compute basic width of a single bit |
| 926 |
\settowidth{\regFieldLen}{\regLabelSize \regResetName}% |
| 927 |
\setlength{\regFieldLen}{\regWidth - \regFieldLen}% |
| 928 |
\setlength{\regFieldLen}{\regFieldLen / \regBitWidth}% |
| 929 |
% Figure out height and depth of reset field in current font |
| 930 |
% Is there a more ``official'' method to do this? |
| 931 |
\settodepth{\regResetDepth}{\regResetSize ()jgpq}% |
| 932 |
\settoheight{\regResetHeight}{\regResetSize ()ABCjkl}% |
| 933 |
\addtolength{\regResetHeight}{\regResetDepth}% |
| 934 |
% Compute how far to drop the reset fields down. The value at |
| 935 |
% the end is effectively the separation between the bit position |
| 936 |
% box and the reset value box. |
| 937 |
\setlength{\regResetDrop}{\regResetHeight + 2\fboxsep - 2\fboxrule + 3pt}% |
| 938 |
% New lengths to support colorbox use, when fboxsep gets set to 0 |
| 939 |
\setlength{\regRsvdDrop}{\regResetDrop + \fboxsep}% |
| 940 |
\setlength{\regRsvdHeight}{\regResetHeight + 2\fboxsep}% |
| 941 |
\setlength{\regFboxSep}{\fboxsep}% |
| 942 |
} |
| 943 |
% \end{macrocode} |
| 944 |
% These macros assembly, rotate, and typset the register field name. |
| 945 |
% It is the use of |\rotatebox| below which makes |register| require |
| 946 |
% PostScript processing. |
| 947 |
% \begin{macrocode} |
| 948 |
\newcommand{\regMakeFieldName}[1]{% |
| 949 |
% Create box to hold label |
| 950 |
\savebox{\Label}{\regLabelSize\regLabelFamily #1}% |
| 951 |
} |
| 952 |
\newcommand{\regRotateFieldName}{% |
| 953 |
\savebox{\RotatedLabel}{\rotatebox[origin=lB]{45}{\usebox{\Label}}}% |
| 954 |
\makebox[0pt][l]{\raisebox{\regResetHeight + \fboxsep + \depth + 1pt}% |
| 955 |
{\hspace{\regLabelAdjust}\usebox{\RotatedLabel}}}% |
| 956 |
} |
| 957 |
% \end{macrocode} |
| 958 |
% The |\typesetRegBits| macro constructs the frame for a particular |
| 959 |
% register field and sets the starting and ending bit positions |
| 960 |
% within that frame. |
| 961 |
% \begin{macrocode} |
| 962 |
\newcommand{\typesetRegBits}[1]{% |
| 963 |
\ifthenelse{#1 > 1}% |
| 964 |
{\framebox[\regFieldLen][c]% |
| 965 |
{\regBitSize \rule[-1\regResetDepth]{0pt}{\regResetHeight}% |
| 966 |
\regBitFamily\arabic{upperbit} \hfill \arabic{lowerbit}}}% |
| 967 |
{\framebox[\regFieldLen][c]% |
| 968 |
{\regBitSize \rule[-1\regResetDepth]{0pt}{\regResetHeight}% |
| 969 |
\regBitFamily\arabic{lowerbit}}}% |
| 970 |
} |
| 971 |
% \end{macrocode} |
| 972 |
% This macro constructs a frame, below the bit position frame, |
| 973 |
% displaying the reset (or some other) value for a register field. |
| 974 |
% \begin{macrocode} |
| 975 |
\newcommand{\typesetRegReset}[1]{% |
| 976 |
% Typeset reset value in a framebox |
| 977 |
\makebox[0pt][l]{\raisebox{-1\regResetDrop}{\framebox[\regFieldLen][c]% |
| 978 |
% Place an invisible rule to control the box |
| 979 |
% surrounding the reset field |
| 980 |
{\regResetSize \rule[-1\regResetDepth]{0pt}{\regResetHeight}\regSpread{#1}}}}% |
| 981 |
} |
| 982 |
% \end{macrocode} |
| 983 |
% |
| 984 |
% |
| 985 |
% |
| 986 |
% \begin{macro}{\regfieldNoColor} |
| 987 |
% The macros below are the user interface to the register drawing |
| 988 |
% routines. The first of these, |\regfieldNoColor| takes four arguments: |
| 989 |
% the field name, field length (in bits), the starting bit number, |
| 990 |
% and the field's reset value. This is the version of the macro that |
| 991 |
% does not make any use of |\colorbox|. |
| 992 |
% \end{macro} |
| 993 |
% \begin{macrocode} |
| 994 |
\newcommand{\regfieldNoColor}[4]{% |
| 995 |
% Compute overall field length |
| 996 |
\setRegLengths% |
| 997 |
\setlength{\regFieldLen}{#2\regFieldLen + \fboxrule}% |
| 998 |
% Figure out bit positions |
| 999 |
\setcounter{lowerbit}{#3}% |
| 1000 |
\setcounter{upperbit}{#3 + #2 - 1}% |
| 1001 |
\regMakeFieldName{#1}% |
| 1002 |
% Figure out how far over to place label, accounting for height |
| 1003 |
\setlength{\regLabelAdjust}{0.5\regFieldLen - 0.707107\ht\Label}% |
| 1004 |
% Now, rotate and type the label |
| 1005 |
\regRotateFieldName% |
| 1006 |
\typesetRegReset{#4}% |
| 1007 |
% Typeset bit positions in a framebox |
| 1008 |
\typesetRegBits{#2}% |
| 1009 |
\hspace{-1\fboxrule}% |
| 1010 |
} |
| 1011 |
% \end{macrocode} |
| 1012 |
% |
| 1013 |
% |
| 1014 |
% |
| 1015 |
% \begin{macro}{\regfieldbNoColor} |
| 1016 |
% The |\regfieldbNoColor| macro can be used to construct a register diagram |
| 1017 |
% without reset values. It's parameters are thus the same |
| 1018 |
% as for |\regfieldNoColor| with the omission of reset value. |
| 1019 |
% \end{macro} |
| 1020 |
% \begin{macrocode} |
| 1021 |
\newcommand{\regfieldbNoColor}[3]{% |
| 1022 |
% Compute overall field length |
| 1023 |
\setRegLengths% |
| 1024 |
\setlength{\regFieldLen}{#2\regFieldLen + \fboxrule}% |
| 1025 |
% Figure out bit positions |
| 1026 |
\setcounter{lowerbit}{#3}% |
| 1027 |
\setcounter{upperbit}{#3 + #2 - 1}% |
| 1028 |
% Create box to hold label |
| 1029 |
\regMakeFieldName{#1}% |
| 1030 |
% Figure out how far over to place label, accounting for height |
| 1031 |
\setlength{\regLabelAdjust}{0.5\regFieldLen - 0.707107\ht\Label}% |
| 1032 |
% Now, rotate and typeset the label |
| 1033 |
\regRotateFieldName% |
| 1034 |
% Typeset bit positions |
| 1035 |
\typesetRegBits{#2}% |
| 1036 |
\hspace{-1\fboxrule}% |
| 1037 |
} |
| 1038 |
% \end{macrocode} |
| 1039 |
% |
| 1040 |
% \begin{macro}{\typesetRegColorBits} |
| 1041 |
% \begin{macro}{\typesetRegColorReset} |
| 1042 |
% \begin{macro}{\regfieldColor} |
| 1043 |
% \begin{macro}{\regfieldbColor} |
| 1044 |
% Now, we define versions of the same macros that make use of |\colorbox|, taking |
| 1045 |
% an additional argument that specifies the fill color to use. |
| 1046 |
% \end{macro} |
| 1047 |
% \end{macro} |
| 1048 |
% \end{macro} |
| 1049 |
% \end{macro} |
| 1050 |
% \begin{macrocode} |
| 1051 |
\ifthenelse{\boolean{RegisterColors}}{% |
| 1052 |
\newcommand{\typesetRegColorBits}[2]{% |
| 1053 |
\ifthenelse{#2 > 1}% |
| 1054 |
{\setlength\fboxsep{0pt}% |
| 1055 |
\colorbox{#1}{% |
| 1056 |
\framebox[\regFieldLen][c]% |
| 1057 |
{\regBitSize \rule[-1\regResetDepth - \regFboxSep]{0pt}% |
| 1058 |
{\regResetHeight + 2\regFboxSep}% |
| 1059 |
\regBitFamily\hspace{\regFboxSep}% |
| 1060 |
\arabic{upperbit} \hfill \arabic{lowerbit}% |
| 1061 |
\hspace{\regFboxSep}}}}% |
| 1062 |
{\setlength\fboxsep{0pt}% |
| 1063 |
\colorbox{#1}{% |
| 1064 |
\framebox[\regFieldLen][c]% |
| 1065 |
{\regBitSize \rule[-1\regResetDepth - \regFboxSep]{0pt}% |
| 1066 |
{\regResetHeight + 2\regFboxSep}% |
| 1067 |
\regBitFamily\arabic{lowerbit}}}}% |
| 1068 |
\setlength\fboxsep{\regFboxSep}% |
| 1069 |
} |
| 1070 |
\newcommand{\typesetRegColorReset}[2]{% |
| 1071 |
% Typeset reset value in a framebox |
| 1072 |
\makebox[0pt][l]{\raisebox{-1\regRsvdDrop}{% |
| 1073 |
\setlength\fboxsep{0pt}% |
| 1074 |
\colorbox{#1}{\framebox[\regFieldLen][c]% |
| 1075 |
% Place an invisible rule to control the box surrounding the reset field |
| 1076 |
{\regResetSize \rule[-1\regResetDepth]{0pt}{\regRsvdHeight}% |
| 1077 |
\raisebox{\regFboxSep}{\makebox[\regFieldLen]% |
| 1078 |
{\hspace{\regFboxSep}\regSpread{#2}\hspace{\regFboxSep}}}}}% |
| 1079 |
}}} |
| 1080 |
\newcommand{\regfieldColor}[5]{% |
| 1081 |
% Compute overall field length |
| 1082 |
\setRegLengths% |
| 1083 |
\setlength{\regFieldLen}{#3\regFieldLen + \fboxrule}% |
| 1084 |
% Figure out bit positions |
| 1085 |
\setcounter{lowerbit}{#4}% |
| 1086 |
\setcounter{upperbit}{#4 + #3 - 1}% |
| 1087 |
\regMakeFieldName{#2}% |
| 1088 |
% Figure out how far over to place label, accounting for height |
| 1089 |
\setlength{\regLabelAdjust}{0.5\regFieldLen - 0.707107\ht\Label}% |
| 1090 |
% Now, rotate and type the label |
| 1091 |
\regRotateFieldName% |
| 1092 |
\typesetRegColorReset{#1}{#5}% |
| 1093 |
% Typeset bit positions in a framebox |
| 1094 |
\typesetRegColorBits{#1}{#3}% |
| 1095 |
\hspace{-1\fboxrule}% |
| 1096 |
} |
| 1097 |
\newcommand{\regfieldbColor}[4]{% |
| 1098 |
% Compute overall field length |
| 1099 |
\setRegLengths% |
| 1100 |
\setlength{\regFieldLen}{#3\regFieldLen + \fboxrule}% |
| 1101 |
% Figure out bit positions |
| 1102 |
\setcounter{lowerbit}{#4}% |
| 1103 |
\setcounter{upperbit}{#4 + #3 - 1}% |
| 1104 |
% Create box to hold label |
| 1105 |
\regMakeFieldName{#2}% |
| 1106 |
% Figure out how far over to place label, accounting for height |
| 1107 |
\setlength{\regLabelAdjust}{0.5\regFieldLen - 0.707107\ht\Label}% |
| 1108 |
% Now, rotate and typeset the label |
| 1109 |
\regRotateFieldName% |
| 1110 |
% Typeset bit positions |
| 1111 |
\typesetRegColorBits{#1}{#3}% |
| 1112 |
\hspace{-1\fboxrule}% |
| 1113 |
} |
| 1114 |
}{} |
| 1115 |
% \end{macrocode} |
| 1116 |
% |
| 1117 |
% |
| 1118 |
% \begin{macro}{\regfield} |
| 1119 |
% \begin{macro}{\regfieldb} |
| 1120 |
% Next, provide definitions for the |\regfield| and |\regfieldb| macros that are |
| 1121 |
% intended for direct use within the register diagrams. These commands just check |
| 1122 |
% for the presence of a non-empty optional argument and, based upon that, decide |
| 1123 |
% whether to invoke the Color or NoColor variants of the typesetting macros. |
| 1124 |
% \end{macro} |
| 1125 |
% \end{macro} |
| 1126 |
% \begin{macrocode} |
| 1127 |
\ifthenelse{\boolean{RegisterColors}}{ |
| 1128 |
\newcommand{\regfield}[5][]{% |
| 1129 |
\ifthenelse{\equal{#1}{}}{% |
| 1130 |
\regfieldNoColor{#2}{#3}{#4}{#5}}% |
| 1131 |
{\regfieldColor{#1}{#2}{#3}{#4}{#5}}} |
| 1132 |
\newcommand{\regfieldb}[4][]{% |
| 1133 |
\ifthenelse{\equal{#1}{}}{% |
| 1134 |
\regfieldbNoColor{#2}{#3}{#4}}% |
| 1135 |
{\regfieldbColor{#1}{#2}{#3}{#4}}} |
| 1136 |
}{ |
| 1137 |
\newcommand{\regfield}[5][]{% |
| 1138 |
\regfieldNoColor{#2}{#3}{#4}{#5}}% |
| 1139 |
\newcommand{\regfieldb}[4][]{% |
| 1140 |
\regfieldbNoColor{#2}{#3}{#4}}% |
| 1141 |
} |
| 1142 |
% \end{macrocode} |
| 1143 |
% |
| 1144 |
% \begin{macro}{\regbits} |
| 1145 |
% The |\regbits| macro typesets a register field without |
| 1146 |
% showing bit positions. As such, it only takes three |
| 1147 |
% parameters: field name, field bit length, and field value. |
| 1148 |
% \end{macro} |
| 1149 |
% \begin{macrocode} |
| 1150 |
\newcommand{\regbits}[3]{% |
| 1151 |
% Compute overall field length |
| 1152 |
\setRegLengths% |
| 1153 |
\setlength{\regFieldLen}{#2\regFieldLen + \fboxrule}% |
| 1154 |
% Figure out bit positions |
| 1155 |
\setcounter{lowerbit}{#3}% |
| 1156 |
\setcounter{upperbit}{#3 + #2 - 1}% |
| 1157 |
% Create box to hold label |
| 1158 |
\regMakeFieldName{#1}% |
| 1159 |
% Figure out how far over to place label, accounting for height |
| 1160 |
\setlength{\regLabelAdjust}{0.5\regFieldLen - 0.707107\ht\Label}% |
| 1161 |
% Now, rotate and typeset the label |
| 1162 |
\regRotateFieldName% |
| 1163 |
% Typeset field value |
| 1164 |
\framebox[\regFieldLen][c]% |
| 1165 |
{\tiny\regSpread{#3}}% |
| 1166 |
\hspace{-1\fboxrule}% |
| 1167 |
} |
| 1168 |
% \end{macrocode} |
| 1169 |
% |
| 1170 |
% |
| 1171 |
% |
| 1172 |
% \begin{macro}{\regspace} |
| 1173 |
% \begin{macro}{\reglabel} |
| 1174 |
% \begin{macro}{\reglabelb} |
| 1175 |
% Finally, define some additional utility macros. An invisible box |
| 1176 |
% with the same width as a specified number of bits is typeset by |
| 1177 |
% |\regspace|. It takes as its sole parameter the desired |
| 1178 |
% bitwidth. The |\reglabel| macro typesets the label for the reset |
| 1179 |
% field in register diagrams. Finally, |\reglabelb| performs the |
| 1180 |
% same function, but without any drop. |
| 1181 |
% \end{macro} |
| 1182 |
% \end{macro} |
| 1183 |
% \end{macro} |
| 1184 |
% \begin{macrocode} |
| 1185 |
\newcommand{\regspace}[1]{% |
| 1186 |
% Compute overall field length |
| 1187 |
\setRegLengths% |
| 1188 |
\setlength{\regFieldLen}{#1\regFieldLen + \fboxrule}% |
| 1189 |
\makebox[\regFieldLen]{}% |
| 1190 |
} |
| 1191 |
|
| 1192 |
\newcommand{\reglabel}[1]{% |
| 1193 |
\settowidth{\regFieldLen}{\regLabelSize \regResetName}% |
| 1194 |
\setlength{\regResetDrop}{\regResetDrop + 0.5\fboxsep}% |
| 1195 |
$\,$\raisebox{-1\regResetDrop}{\makebox[\regFieldLen][l]% |
| 1196 |
{\regLabelSize\regBitFamily #1}}% |
| 1197 |
} |
| 1198 |
|
| 1199 |
\newcommand{\reglabelb}[1]{% |
| 1200 |
\settowidth{\regFieldLen}{\regLabelSize \regResetName}% |
| 1201 |
$\,$\raisebox{-0.5\fboxsep}{\makebox[\regFieldLen][l]% |
| 1202 |
{\regLabelSize\regBitFamily #1}}% |
| 1203 |
} |
| 1204 |
% \end{macrocode} |
| 1205 |
% |
| 1206 |
% |
| 1207 |
% |
| 1208 |
% \subsubsection{Hyperref Interface} \label{sec:hyperref} |
| 1209 |
% |
| 1210 |
% This code helps with the hyperlinks to register floats |
| 1211 |
% when producing linked PDF. |
| 1212 |
% \begin{macrocode} |
| 1213 |
\ifthenelse{\boolean{RegisterHyperref}}{% |
| 1214 |
% Define a counter for the hyperref package. Otherwise, |
| 1215 |
% the hyperlinks to registers don't work correctly |
| 1216 |
\@namedef{theHRegfloat}{\theRegfloat} |
| 1217 |
|
| 1218 |
% Define a bookmark level for Regfloats (for hyperref package) |
| 1219 |
\def\toclevel@Regfloat{0} |
| 1220 |
}{} |
| 1221 |
% \end{macrocode} |
| 1222 |
% |
| 1223 |
% |
| 1224 |
% |
| 1225 |
% |
| 1226 |
% \subsubsection{List of Registers} \label{sec:list} |
| 1227 |
% |
| 1228 |
% The code below redefines what the |float| package specifies |
| 1229 |
% in order to provide a hook for changing the format of the |
| 1230 |
% ToC line for registers. |
| 1231 |
% \begin{macrocode} |
| 1232 |
\newcommand{\listofregisters}{% |
| 1233 |
\@ifundefined{ext@Regfloat}{\float@error{Regfloat}}{% |
| 1234 |
\@ifundefined{chapter}{\def\@tempa{\section*}}% |
| 1235 |
{\def\@tempa{\chapter*}}% |
| 1236 |
\@tempa{\regListName\@mkboth{\uppercase{\regListName}}% |
| 1237 |
{\uppercase{\regListName}}}% |
| 1238 |
\addcontentsline{toc}{chapter}{\regListName}% |
| 1239 |
\@starttoc{\@nameuse{ext@Regfloat}}}} |
| 1240 |
\newcommand\l@Regfloat{\@dottedtocline{1}{1.5em}{2.3em}} |
| 1241 |
% \end{macrocode} |
| 1242 |
% |
| 1243 |
% |
| 1244 |
% The |\chapter| command, if present, is also redefined in order |
| 1245 |
% to get identical chapter-related spacing in the list of registers |
| 1246 |
% as appears in the LoF and LoT. Kjetil Oftedal provided a fix |
| 1247 |
% wherein we test that @mainmatter is defined prior to using it. |
| 1248 |
% |
| 1249 |
% This change to |\chapter| is not particularly friendly if one is |
| 1250 |
% using the |memoir| package, however! So, we first check what |
| 1251 |
% document class is being used. If |memoir| is being used, we invoke |
| 1252 |
% its |\memchapinfo| hook rather than attempt any redefinition of |
| 1253 |
% |\chapter|. |
| 1254 |
% |
| 1255 |
% |
| 1256 |
% \begin{macrocode} |
| 1257 |
\@ifundefined{@mainmatter}{\newif\if@mainmatter \@mainmattertrue}{} |
| 1258 |
\@ifclassloaded{memoir}{% |
| 1259 |
\renewcommand{\memchapinfo}[4]{% |
| 1260 |
\addtocontents{rdf}{\protect\addvspace{10pt}}} |
| 1261 |
}{% |
| 1262 |
\@ifundefined{chapter}{} |
| 1263 |
{% Adjust chapter definition slightly for Regfloats |
| 1264 |
\def\@chapter[#1]#2{\ifnum \c@secnumdepth >\m@ne |
| 1265 |
\if@mainmatter |
| 1266 |
\refstepcounter{chapter}% |
| 1267 |
\typeout{\@chapapp\space\thechapter.}% |
| 1268 |
\addcontentsline{toc}{chapter}% |
| 1269 |
{\protect\numberline{\thechapter}#1}% |
| 1270 |
\else |
| 1271 |
\addcontentsline{toc}{chapter}{#1}% |
| 1272 |
\fi |
| 1273 |
\else |
| 1274 |
\addcontentsline{toc}{chapter}{#1}% |
| 1275 |
\fi |
| 1276 |
\chaptermark{#1}% |
| 1277 |
\addtocontents{lof}{\protect\addvspace{10\p@}}% |
| 1278 |
\addtocontents{lot}{\protect\addvspace{10\p@}}% |
| 1279 |
\addtocontents{rdf}{\protect\addvspace{10\p@}}% --- Add space --- |
| 1280 |
\if@twocolumn |
| 1281 |
\@topnewpage[\@makechapterhead{#2}]% |
| 1282 |
\else |
| 1283 |
\@makechapterhead{#2}% |
| 1284 |
\@afterheading |
| 1285 |
\fi} |
| 1286 |
}} |
| 1287 |
% \end{macrocode} |
| 1288 |
% |
| 1289 |
% |
| 1290 |
% |
| 1291 |
% \subsection{TR flag macros} \label{sec:TRflags}% |
| 1292 |
% |
| 1293 |
% Define a mechanism for including TR flags in register descriptions, |
| 1294 |
% as well as possibly in the main body of the text. One cannot just |
| 1295 |
% use |\marginpar|'s within a register description, since they are |
| 1296 |
% typically part of a register float. \LaTeX{}'s |\marginpar| command is |
| 1297 |
% \emph{also} considered a float, so they cannot be nested. |
| 1298 |
% |
| 1299 |
% So, we resort to using some lower level \LaTeX{}. This certainly |
| 1300 |
% isn't the most elegant way to get the flags, but I think it will |
| 1301 |
% work for the majority of cases. |
| 1302 |
% |
| 1303 |
% The |\TR{x}| command is intended to be placed at the start of |
| 1304 |
% a register field description, so that the alignment is |
| 1305 |
% obvious on the page. To also get decent alignment in |
| 1306 |
% main body text, it is necessary to have a second definition. |
| 1307 |
% So, we'll see these commands get redefined inside regdesc, |
| 1308 |
% below. |
| 1309 |
% |
| 1310 |
% The TR flags also decide which page they are on by placing |
| 1311 |
% labels and testing the resulting pagenumber. This enables |
| 1312 |
% the flags to be placed in the outer margin in two-sided |
| 1313 |
% documents. |
| 1314 |
% |
| 1315 |
% \begin{macro}{\TRfamily} |
| 1316 |
% \begin{macro}{\TRwidth} |
| 1317 |
% The font family used for the TR flags can be controlled via |
| 1318 |
% |\TRfamily|. The width available for TR flags is controlled |
| 1319 |
% by |\TRwidth|, which by default is set to |\marginparwidth|. |
| 1320 |
% Setting the width may be important if you are using the |
| 1321 |
% |TRboxed| package option. |
| 1322 |
% \end{macro} |
| 1323 |
% \end{macro} |
| 1324 |
% |
| 1325 |
% \begin{macrocode} |
| 1326 |
% Define a pageref which will work with \isodd |
| 1327 |
\newcommand\@GetTRSecondParam{} |
| 1328 |
\long\def\@GetTRSecondParam#1#2#3\@nil{#2} |
| 1329 |
\newcommand*{\GetTRPageRef}[1]{% |
| 1330 |
\expandafter\expandafter\expandafter\@GetTRSecondParam |
| 1331 |
\csname r@#1\endcsname |
| 1332 |
0% dummy, if the reference is undefined |
| 1333 |
\@nil |
| 1334 |
} |
| 1335 |
|
| 1336 |
\newcommand{\TRfamily}{\sffamily} |
| 1337 |
\newcounter{T@peReleaseTag} |
| 1338 |
\newlength{\TRwidth} |
| 1339 |
\setlength{\TRwidth}{\marginparwidth} |
| 1340 |
\newlength{\T@peReleaseDepth} |
| 1341 |
|
| 1342 |
% Internal command to form the actual TR margin note. |
| 1343 |
\newcommand{\TRwriteout}[1]{% |
| 1344 |
\makebox[\TRwidth][c]{% |
| 1345 |
\raisebox{\T@peReleaseDepth}{% |
| 1346 |
\ifthenelse{\boolean{RegisterTRBoxed}}% |
| 1347 |
{\fbox{\TRfamily #1}}% |
| 1348 |
{\TRfamily #1}}}% |
| 1349 |
} |
| 1350 |
|
| 1351 |
% Internal command to typeset a TR flag in the right margin |
| 1352 |
\newcommand{\TRrightlabel}[1]{% |
| 1353 |
% Place a strut in order to set line depth |
| 1354 |
\mbox{}\strut\settodepth{\T@peReleaseDepth}{\strut}% |
| 1355 |
\vadjust{\hspace{\textwidth}\hspace{\marginparsep}% |
| 1356 |
\smash{\rlap{\TRwriteout{#1}}}}} |
| 1357 |
|
| 1358 |
% Internal command to typeset a TR flag in the left margin |
| 1359 |
\ifthenelse{\boolean{@twoside}}{ |
| 1360 |
% Two-sided document |
| 1361 |
\newcommand{\TRleftlabel}[1]{% |
| 1362 |
% Place a strut in order to set line depth |
| 1363 |
\mbox{}\strut\settodepth{\T@peReleaseDepth}{\strut}% |
| 1364 |
\vadjust{\smash{\llap{\TRwriteout{#1}}\kern\marginparsep}}} |
| 1365 |
}{ |
| 1366 |
% Otherwise, the command is the same as rightlabel |
| 1367 |
\newcommand{\TRleftlabel}[1]{% |
| 1368 |
\TRrightlabel{#1}} |
| 1369 |
} |
| 1370 |
% \end{macrocode} |
| 1371 |
% |
| 1372 |
% |
| 1373 |
% \begin{macro}{\TR} |
| 1374 |
% Finally, the user-level command is simply |\TR|. |
| 1375 |
% \end{macro} |
| 1376 |
% \begin{macrocode} |
| 1377 |
\ifthenelse{\boolean{RegisterTRFlags}}{ |
| 1378 |
\newcommand{\TR}[1]{% |
| 1379 |
\stepcounter{T@peReleaseTag}% |
| 1380 |
\label{TapeReleaseTag-\theT@peReleaseTag}% |
| 1381 |
\ifthenelse{\isodd{\GetTRPageRef{TapeReleaseTag-\theT@peReleaseTag}}}% |
| 1382 |
{\TRrightlabel{TR\hspace{1pt}#1}}% |
| 1383 |
{\TRleftlabel{TR\hspace{1pt}#1}}% |
| 1384 |
}} |
| 1385 |
{\newcommand{\TR}[1]{}} |
| 1386 |
% \end{macrocode} |
| 1387 |
% |
| 1388 |
% \par |
| 1389 |
% Enjoy! Happy documenting. |
| 1390 |
% |
| 1391 |
% |
| 1392 |
% \Finale |
| 1393 |
% |
| 1394 |
\endinput |
| 1395 |
|
| 1396 |
%% \CharacterTable |
| 1397 |
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z |
| 1398 |
%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z |
| 1399 |
%% Digits \0\1\2\3\4\5\6\7\8\9 |
| 1400 |
%% Exclamation \! Double quote \" Hash (number) \# |
| 1401 |
%% Dollar \$ Percent \% Ampersand \& |
| 1402 |
%% Acute accent \' Left paren \( Right paren \) |
| 1403 |
%% Asterisk \* Plus \+ Comma \, |
| 1404 |
%% Minus \- Point \. Solidus \/ |
| 1405 |
%% Colon \: Semicolon \; Less than \< |
| 1406 |
%% Equals \= Greater than \> Question mark \? |
| 1407 |
%% Commercial at \@ Left bracket \[ Backslash \\ |
| 1408 |
%% Right bracket \] Circumflex \^ Underscore \_ |
| 1409 |
%% Grave accent \` Left brace \{ Vertical bar \| |
| 1410 |
%% Right brace \} Tilde \~} |
| 1411 |
|
| 1412 |
%%% Local Variables: |
| 1413 |
%%% mode: LaTeX |
| 1414 |
%%% End: |
| 1415 |
|