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