Debian Codegraph @

texmf-dist/source/latex/register/register.dtx

raw
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