|
|
\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{\aasmajor}{0}
\newcommand{\aasminor}{2}
\newcommand{\aaspatch}{0}
\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}
\begin{center}
{\huge\bfseries\documenttitle}
{\large\aasmajor.\aasminor.\aaspatch}
\end{center}
\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 -- the \textit{Advanced Arm Assembler} -- is an open-source cross-assembler for the ARM Instruction Set Architecture.
\subsection{Copyright \& License}
AAS is copyright © 2023 Gabriel Bjørnager Jensen.
AAS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
AAS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with AAS and/or this manual. If not, see \url{https://www.gnu.org/licenses/}.
\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}
First, make sure to meet the prerequisites for installing AAS:
\begin{itemize}
\item Having installed \textit{Rust} and the build system \textit{Cargo}
\begin{itemize}
\item Install either of the \texttt{rust} or \texttt{rustup} packages using pacman (Arch Linux)
\item Install the \texttt{lang/rust} package (FreeBSD)
\item View the official Rust documentation at \url{https://www.rust-lang.org/tools/install/}.
\end{itemize}
\item Having compiled the AAS executable \textbf{using the \textit{release} profile}
\begin{itemize}
\item Run \texttt{cargo build -{}-release}
\end{itemize}
\end{itemize}
Then, to install the executable, simply execute:
\begin{center}
\begin{varwidth}{\linewidth}
\ttfamily
install -m755 \$\{BINDIR\} "target/release/aas"
\end{varwidth}
\end{center}
Wherein \texttt{\$\{BINDIR\}} denotes the destination directory, usually \texttt{"/usr/bin"}.
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{center}
\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{center}
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.}:
\begin{center}
\begin{varwidth}{\linewidth}
\begin{verbatim}
.BYTE #0x7F ; This embeds the value 127 using eight bits.
.THUMB ; All code after this line will be assembled as Thumb code.
\end{verbatim}
\end{varwidth}
\end{center}
An identifier appended with a \texttt{:} (colon) denotes a label:
\begin{center}
\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{center}
\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.
Thumb-exclusive instructions are translated to their equivalent ARM opcode: For example, the following two instructions are identical:
\begin{center}
\begin{varwidth}{\linewidth}
\begin{verbatim}
.ARM
ASR r0, r1
MOV r0, r0, ASR r1
\end{verbatim}
\end{varwidth}
\end{center}
\subsubsection{BYTE}
\textit{Usage: \texttt{.BYTE <value>}}
Embeds the 8-bit value \textit{value} into the executable.
The range of valid values lies in $([0;2^8-1]=[0;255])$.
\subsubsection{DOUBLEWORD}
\textit{Usage: \texttt{.DOUBLEWORD <value>}}
Embeds the 64-bit value \textit{value} into the executable.
The range of valid values lies in $([0;2^{64}-1]=[0;18446744073709551615])$.
\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} into the executable.
The range of valid values lies in $([0;2^{16}-1]=[0;65535])$.
\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} into the executable.
The range of valid values lies in $([0;2^{32}-1]=[0;4294967295])$.
\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}
|
