diff options
Diffstat (limited to 'docs/aas.tex')
| -rw-r--r-- | docs/aas.tex | 270 |
1 files changed, 0 insertions, 270 deletions
diff --git a/docs/aas.tex b/docs/aas.tex deleted file mode 100644 index f688f53..0000000 --- a/docs/aas.tex +++ /dev/null @@ -1,270 +0,0 @@ -\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} |