Creating memory maps in LaTeX using the {bytefield} package (update x2)

I’m currently working on some embedded systems stuff. For the documentation (written in LaTeX, of course!) I was searching for a convenient way to draw memory maps. The creation of external images using LaTeX Draw (which I like) was not a good option, as I wanted to change my memory maps in a source file and propagate the change with a single ‚typeset‘ command.

I wanted to share my solution, as I found nothing there (as a matter of fact, nobody seems to draw memory maps, which means that a lot of documentation is missing them ;__;). I use the real handy ‚bytefield‘ package (maybe the way to go for documenting registers) which is quite lightweight and convenient to use. This is an example of a basic bytefield definition:

\begin{bytefield}{32}
	\bitheader[b]{0,7,8,15,16,23,24,31}\\
	\bitbox{8}{Byte 3} \bitbox{8}{Byte 2}
	\bitbox{8}{Byte 1} \bitbox{8}{Byte 0}
\end{bytefield}

This code snipplet looks like this when typeset:

However, the supported examples made clear, that the creation of memory mappings was not the main use for this package: Memory sections have to be uniform in height. This make a memory layout much less meaningful: I wanted to state the height of every memory section independently. As a solution I hacked a real ugly new latex command \memsection which will make a LaTeX guru cry but does the job quite well. The command takes the end address, the start address, the height of the section (in lines) an a caption as its parameters. The following example shows the command in use:

\begin{bytefield}{24}
	\memsection{ffff ffff}{0040 0000}{15}{-- free --}\\
	\begin{rightwordgroup}{internal memory}
		\memsection{003f ffff}{002f c000}{4}{Special Function Registers}\\
		\memsection{002f bfff}{0007 0000}{3}{-- reseved --}\\
		\memsection{0006 ffff}{0000 0000}{8}{Internal Flash}
	\end{rightwordgroup}\\
\end{bytefield}

When typeset, it looks like this:

Note that the addresses get print with a leading ‚0x‘ and in uppercase. Note also, that the location of newlines (\\) is critcal! This is the implementation of the command:

% facilitates the creation of memory maps. Start address at the bottom, end address at the top.
% Addresses will be print with a leading '0x' and in upper case.
% syntax: \memsection{end address}{start address}{height in lines}{text in box}
\newcommand{\memsection}[4]{
	\bytefieldsetup{bitheight=#3\baselineskip}	% define the height of the memsection
	\bitbox[]{8}{
		\texttt{0x\uppercase{#1}}	 % print end address
		\\ \vspace{#3\baselineskip} \vspace{-2\baselineskip} \vspace{-#3pt} % do some spacing
		\texttt{0x\uppercase{#2}} % print start address
	}
	\bitbox{16}{#4} % print box with caption
}

What’s still missing? I would like to have a symbol to indicate skipped words in really long sections as provided with bytefields \skippedwords command. However, implementing this needs more than my current LaTeX skills.

Update:

I just removed the automatic prefix ‚0x‘ and \uppercase for addresses. That way one can create blank memory sections without any addresses: This can help make crowded layouts more readable:

Updated LaTeX command:

% facilitates the creation of memory maps. Start address at the bottom, end address at the top.
% syntax: \memsection{end address}{start address}{height in lines}{text in box}
\newcommand{\memsection}[4]{
\bytefieldsetup{bitheight=#3\baselineskip}    % define the height of the memsection
\bitbox[]{10}{
\texttt{#1}     % print end address
\\ \vspace{#3\baselineskip} \vspace{-2\baselineskip} \vspace{-#3pt} % do some spacing
\texttt{#2} % print start address
}
\bitbox{16}{#4} % print box with caption
}

Update #2: Fixed the width of the bitbox in the updated command from 8 to 10.

Feel free to share your ideas and/or solutions in the comments!

2 Gedanken zu „Creating memory maps in LaTeX using the {bytefield} package (update x2)

  1. Danke!

    Got some errors, which leaded to the „\bytefieldsetup“ and found out that I need to have bytefield in version 2.0 at least.

    But works now!

    • Thanks for that information! After reading the bytefield manual this also makes sense, since the used macro \rightwordgroup was introduced in v2.0. Users of 1.X could try to use \wordgroupr and \endwordgroupr.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.