path: root/docs/aas.tex

\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}