\usepackage{textcomp}
\usepackage{amsmath}
-\title{Mackerel 1.2 User Guide}
+\title{Mackerel 1.3 User Guide}
\author{Barrelfish project}
% \date{\today} % Uncomment (if needed) - date is automatic
\tnnumber{2}
\begin{versionhistory}
\vhEntry{1.2}{31.05.2010}{TR}{Initial version under new formatting}
+\vhEntry{1.3}{15.08.2011}{TR}{Added support for imports and new
+ command-line options}
\end{versionhistory}
% \intro{Abstract} % Insert abstract here
To manually invoke \Mac, run:
-\verb~> mackerel --shift-driver devFile.dev devFile.h~
+\verb~> mackerel --shift-driver -c devFile.dev -o devFile.h~
This will translate a device file into a single C header file containing all
relevant functions for accessing the device, as described in
If you wish to use the (deprecated) bitfield-based back-end instead,
you can use:
-\verb~> mackerel --bitfield-driver devFile.dev devFile.h~
+\verb~> mackerel --bitfield-driver -c devFile.dev -o devFile.h~
This backend should not be used for new code, as it is not portable
across compilers. It is described in
Chapter~\ref{chap:bitfielddriver}.
+\section{Command-line options}
+
+The complete list of comand-line options supported by the current
+Mackerel compiler is as follows:
+\begin{itemize}
+\item \texttt{-c} \textit{filename} or
+ \texttt{--input-file=}\textit{filename}: This option is mandatory
+ and specifies the pathname to be read. This pathname must specify
+ the file: the main input file will not be searched for along the
+ search path.
+
+\item \texttt{-I} \textit{dir} or \texttt{--include-dir}
+ \textit{dir}: this option can be supplied multiple times and
+ specifies the search path for imported files.
+
+\item \texttt{-v} or \texttt{--verbose}: Increases the verbosity level
+ of the compiler.
+
+\item \texttt{-o} \textit{filename} or \texttt{--output-file}
+ \textit{filename}: this option, if supplied, specifies the name of
+ the C header file which will be written by the compiler. If not
+ given, the filename will be derived from the input filename by
+ removing all the directory components (i.e. it will reside in the
+ current working directory) and appending \texttt{.h}.
+
+\item \texttt{-S} or \texttt{shift-driver}: Specifies the shift driver
+ backend; this is the default.
+
+\item \texttt{-B} or \texttt{bitfield-driver}: Specifies the bitfield
+ driver backend; this is deprecated. Furthermore, imports are
+ (deliberately) not supported by the bitfield driver. If multiple
+ \texttt{-S} and \texttt{-B} options are specified, the last one
+ determines the compiler output.
+
+\end{itemize}
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
xxxxxxxxx \= xxxxxxxxx \= xxxxxxxxx \= xxxxxxxxx \= xxxxxxxxx \= xxxxxxxxx \kill
addr \> also \> bytewise \> constants \> datatype \> device \\
io \> lsbfirst \> many \> msbfirst \> pci \> regarray \\
-register \> regtype \> space \> stepwise \> type \> valuewise
+register \> regtype \> space \> stepwise \> type \> valuewise \\
+import
\end{tabbing}
\end{alltt}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Declarations}\label{chap:declarations}
-A \Mac source file must consist of a single \textit{device
+A \Mac source file must consist of zero or more \textit{import}
+declarations, followed by a single \textit{device
specification}, which itself consists of further specifications of
registers, register types, etc.
+\section{Imports}\label{sec:imports}
+
+An import declaration makes the definitions in a different device file
+available in the current device definition, as described below. The
+syntax of an import declaration is as follows:
+
+\begin{syntax}
+import \synit{device};
+\end{syntax}
+
+\begin{description}
+\item[device] is the name of a device from which to import
+ definitions.
+\end{description}
+
+The \Mac compiler will search for a file with the appropriate name and
+parse this at the same time as the main file, along with this file's
+imports, and so on. Cyclic dependencies between device files will not
+cause errors, but at present are unlikely to result in C header files
+which will successfully compile.
+
\section{Devices}\label{sec:devices}
A device declaration in \Mac specifies a particular type of hardware
\begin{description}
\item[name] is an identifier for the device type, and will be used to
- generate identifiers in the target language (typically C). While
- not enforced by the \Mac compiler, by
- convention this should only differ from the name of the file in case
- and suffix, e.g.\ the file \texttt{xapic.dev} defines a device type
- of name \texttt{xAPIC}.
+ generate identifiers in the target language (typically C).
+ The name of the name of the device \emph{must} correspond to the
+ filename of the file, including case sensitivity: for example,
+ the file \texttt{xapic.dev} will define a device type
+ of name \texttt{xapic}.
\item[lsbfirst or msbfirst] optionally specifies the \emph{bit order}
of the declarations
\item[width] is an integer giving the width of the field in bits.
\item[fieldtype] is an optional identifier giving the type of this field.
- This must be the identifier of a \texttt{constants} declaration
+ This must be either the identifier of a \texttt{constants} declaration
somewhere in the enclosing \texttt{device} declaration, for example
- \texttt{type(vdm)}.
+ \texttt{type(vdm)}, or a qualified name of the form
+ \textit{device}\texttt{.}\textit{constdef}, where \textit{device} is
+ the name of a device definition previously imported.
\item[attr] is an optional field
attribute. See section~\ref{sec:fieldattrs} for more information.
\item[type] gives the format of the register. It can consist of
\texttt{type(}\textit{name}\texttt{)}, where \textit{name} is either
the identifer of a register type previously declared with a
- \texttt{regtype} declaration, or one of the built in register
+ \texttt{regtype} declaration; one of the built in register
types \texttt{uint8}, \texttt{uint16}, \texttt{uint32}, or
- \texttt{uint64}.
+ \texttt{uint64}; or a qualified name of the form
+ \textit{device}\texttt{.}\textit{regtype}, where \textit{device} is
+ the name of a device definition previously imported.
Alternatively, the type can be given as a sequence of fields in
braces, exactly as in a \texttt{regtype} declaration. In effect,
projects / barrelfish / commitdiff