diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/aas.tex | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/docs/aas.tex b/docs/aas.tex new file mode 100644 index 0000000..6ded09e --- /dev/null +++ b/docs/aas.tex @@ -0,0 +1,219 @@ +\documentclass[a4paper]{article} + +\usepackage[english]{babel} +\usepackage{fancyhdr} +\usepackage[T1]{fontenc} +\usepackage[margin=2cm]{geometry} +\usepackage[hidelinks, pdfusetitle]{hyperref} +\usepackage{lastpage} +\usepackage{parskip} +\usepackage{titlesec} +\usepackage{varwidth} + +\newcommand{\documenttitle}{Using AAS} + +\title{\documenttitle} +\author{Gabriel Bjørnager Jensen} +\date{2023-12-31} + +\pagestyle{fancy} +\fancyhf{} +\renewcommand{\headrulewidth}{0pt} +\fancyhead[c]{\bfseries \documenttitle} +\fancyfoot[c]{Page $\thepage\over\pageref{LastPage}$} + +\titleformat{\section}{\huge\bfseries}{\thesection}{1ex}{}{} +\titleformat{\subsection}{\large\bfseries}{\thesubsection}{1ex}{}{} + +\begin{document} + \pagenumbering{gobble} + \thispagestyle{empty} + + \vspace*{\fill} + \centerline{\huge\bfseries\documenttitle} + \vspace*{\fill} + + \clearpage + \pagenumbering{arabic} + \begin{center} + Copyright © 2023 Gabriel Bjørnager Jensen. + + This manual is licensed under a Creative Commons Attribution-ShareAlike-4.0 International license. + + See more at \url{https://creativecommons.org/licenses/by-sa/4.0/}. + \end{center} + + \clearpage + \tableofcontents + + \clearpage + \section{About AAS} + AAS -- \textit{Arm Assembler} -- is a cross-assembler for the ARM Instruction Set Architecture. + + \clearpage + \section{Setup} + \subsection{Download} + AAS may be downloaded in source form from one of the following official mirrors: + + \begin{center} + \begin{varwidth}{\linewidth} + \url{https://mandelbrot.dk/aas} + + \url{https://gitlab.com/bjoernager/aas.git} + + \url{https://github.com/bjoernager/aas.git} + \end{varwidth} + \end{center} + + \subsection{Installation} + A PKGBUILD for AAS will likely be provided in the near future at \url{https://mandelbrot.dk/pkgbuild_aas}. + + \clearpage + \section{Usage} + Invoke the assembler using the \texttt{aas} command: + + \begin{center} + \ttfamily + aas \textit{[options]} <input> + \end{center} + + Wherein \textit{options} may be any combination of the following parameters: + + \begin{itemize} + \item -f\quad{} Sets the target executable format + \item -h\quad{} Prints help + \item -m\quad{} Sets the target CPU + \item -v\quad{} Prints the version number + \end{itemize} + + \subsection{Supported Target CPUs} + Only the following identifier is supported when provided to the \texttt{-m} parameter: + + \begin{itemize} + \item arm7tdmi + \end{itemize} + + \subsection{Supported Target Executable Formats} + Only the following identifier is supported when provided to the \texttt{-f} parameter: + + \begin{itemize} + \item elf + \end{itemize} + + \clearpage + \section{Syntax} + The AAS syntax is designed to be largely compatible with the GAS syntax as well as that of the official armasm assembler. + + Comments are denoted with either a \texttt{;} (semicolon) or an \texttt{@} (commercial at). These comments continue until the end of the current line. Multi-line comments are currently not supported. + + \begin{figure}[h] + \centering + + \caption{Example of comments.} + \label{fig:comments} + \begin{varwidth}{\linewidth} + \begin{verbatim} + ; This is a comment. + @ This is also a comment. + mov r0, pc ; This line will be parsed up till the semicolon. + /* + This is an error (for now). + */ + \end{verbatim} + \end{varwidth} + \end{figure} + + An identifier prepended with a \texttt{.} (full stop) denotes an assembler directive\footnote{However, if the identifier is also appended with a \texttt{:} (colon), it denotes a label instead.} (see figure \ref{fig:directives}): + + \begin{figure}[h] + \centering + + \caption{Example of directives.} + \label{fig:directives} + \begin{varwidth}{\linewidth} + \begin{verbatim} + .byte 0x7F ; This embeds the 8-bit value 0xFF. + .thumb ; All code after this line will be assembled as Thumb code. + \end{verbatim} + \end{varwidth} + \end{figure} + + An identifier appended with a \texttt{:} (colon) denotes a label (see figure \ref{fig:labels}). + + \begin{figure}[h] + \centering + + \caption{Example of labels.} + \label{fig:labels} + \begin{varwidth}{\linewidth} + \begin{verbatim} + start: ; This is a label. + _start: ; This is also a label. + .start: ; This is a label as well. + \end{verbatim} + \end{varwidth} + \end{figure} + + \subsection{Accepted Directives} + \subsubsection{arm} + \textit{Usage: \texttt{.arm}} + + Specifies that all following code be assembled into ARM (32-bit) opcodes. May be overriden by a new \texttt{.thumb} directive. + + \subsubsection{byte} + \textit{Usage: \texttt{.byte <value>}} + + Embeds the 8-bit value \textit{value}. + + \subsubsection{doubleword} + \textit{Usage: \texttt{.doubleword <value>}} + + Embeds the 64-bit value \textit{value}. + + \subsubsection{global} + \textit{Usage: \texttt{.global}} + + Specifies that the following label shall be externally visible. + + \subsubsection{halfowrd} + \textit{Usage: \texttt{.halfword <value>}} + + Embeds the 16-bit value \textit{value}. + + \subsubsection{thumb} + \textit{Usage: \texttt{.thumb}} + + Specifies that all following code be assembled into Thumb (16-bit) opcodes. May be overriden by a new \texttt{.arm} directive. + + \subsubsection{word} + \textit{Usage: \texttt{.word <value>}} + + Embeds the 32-bit value \textit{value}. + + \subsection{Character Set} + AAS requires that all input files be encoded in UTF-8 \textbf{only}. + + Outside of strings and comments, only a small subset of ASCII characters are allowed (see figure \ref{fig:characters}). The presence of any character outside of this subset will yield in an error. + + \begin{figure}[h] + \centering + + \caption{ASCII-subset of which character are valid outside strings and comments.} + \label{fig:characters} + \begin{tabular}{|c|c c c c c c c c c c c c c c c c|} + \hline + {} & 0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & A & B & C & D & E & F \\ + \hline + 0 & \textit{NUL} & {} & {} & {} & {} & {} & {} & {} & {} & \textit{HT} & \textit{LF} & {} & {} & {} & {} & {} \\ + 1 & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} & {} \\ + 2 & \textit{SP} & ! & " & \# & {} & {} & {} & {} & {} & {} & * & {} & , & {} & . & {} \\ + 3 & 0 & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 & : & ; & < & {} & > & {} \\ + 4 & @ & A & B & C & D & E & F & G & H & I & J & K & L & M & N & O \\ + 5 & P & Q & R & S & T & U & V & W & X & Y & Z & [ & {} & ] & {} & \_ \\ + 6 & {} & a & b & c & d & e & f & g & h & i & j & k & l & m & n & o \\ + 7 & p & q & r & s & t & u & v & w & x & y & z & {} & {} & {} & {} & {} \\ + \hline + \end{tabular} + \end{figure} + +\end{document} |