Subversion Repositories forwardcom

% chapter included in forwardcom.tex
\documentclass[forwardcom.tex]{subfiles}
\begin{document}
\RaggedRight
%\newtheorem{example}{Example}[chapter]  % example numbering
\lstset{language=C}            % formatting for code listing
\lstset{basicstyle=\ttfamily,breaklines=true}
 
 
\chapter{Binary tools} \label{chap:binTools}
All the basic development tools for ForwardCom except compilers are combined into a single executable file named \textbf{forw} or \textbf{forw.exe}.
\vv
 
The tools can be run using the following command lines:
\vv
 
%\begin{table}[]
%\left
%\caption{Commands}
\label{bintoolCommands}
\begin{tabular}{ll}
\hline
assemble & forw -ass assemblyfile objectfile \\ 
disassemble & forw -dis objectfile assemblyfile \\ 
link & forw -link exefile objectfiles libraryfiles \\ 
relink & forw -relink inputfile outputfile objectfiles libraryfiles \\ 
make library & forw -lib libraryfile objectfiles \\
emulate & forw -emu exefile \\
debug & forw -emu exefile  -list=debugout.txt \\
dump & forw -dump objectfile \\ 
help & forw -help \\ 
\hline
\end{tabular}
\vspace{4mm}
 
General options:
 
The following options can be used with most or all of the commands listed above:
 
\begin{tabular}{p{20mm}p{140mm}}
\hline
@file & read additional command line options or file names from file.\\
-ilist=file & alternative instruction list file.\\
-wdNNN & disable Warning NNN.\\
-weNNN & treat Warning NNN as Error. -wex: treat all warnings as errors.\\
-edNNN & disable Error number NNN.\\
-ewNNN & treat Error number NNN as Warning.\\
\hline
\end{tabular}
\vv
 
A list of instructions is stored separately in a comma-separated file named \textbf{instruction\_list.csv}. This file must be present when running the assembler, disassembler, or debugger. The format for the instruction list is defined in table \ref{table:fieldsInInstructionListFile}.
\vv
 
The tools are running in console mode and returning a status value which is nonzero in case of error. This is useful when running the tools from a makefile, shell script, or Windows .bat file.
\vv
 
\section{Assembler}\label{chap:assembler}
\subsection{Introduction} \label{assemblerIntroduction}
The assembler is using a syntax similar to C and Java in order to make the code intelligible to high-level language programmers. 
The details are described in the programming manual in chapter 
\ref{chap:programmingManual}, page \pageref{chap:programmingManual}.
\vv
 
\subsection{Command line} \label{assemblerCommandLine}
The command line for the assembler has the following format:
 
\vv
\hspace{5mm} {\ttfamily forw -ass [options] assemblyfile objectfile}
 
\vv
The following options are supported:\\
\begin{tabular}{|p{25mm}p{135mm}|}
\hline
-list=name & Make output list file. This is useful for checking the generated code.\\
-ilist=name & Specify alternative instruction list name.\\
-b         & Make binary listing in -list file. \\
-O0 & Optimization level 0: The assembler finds the smallest possible instruction that fits the specified operands. \\
-O1 & Optimization level 1 (default): An instruction may be replaced by another instruction that does the same thing more efficiently. For example, \linebreak
{\ttfamily float v1 *= 4} can be replaced by
 {\ttfamily float v1 = mul\_2pow(v1, 2)}. \linebreak
A conditional jump statement is merged with a preceding arithmetic instruction when possible.
 An {\ttfamily if} statement immediately followed by an
 unconditional jump is converted to a single conditional jump.\\
-O3 & Optimization level 3. Enable optimizations that ignore subnormal numbers. For example, {\ttfamily float v1 *= 0.25} can be replaced by {\ttfamily float v1 = mul\_2pow(v1, -2)}.\\
-debug=1  & Include debug information in object file. Currently, debug information includes only label names.\\
-maxerrors=n & Specify maximum number of error messages from the assembler.\\
-datasize=n & Specify maximum combined size of writeable static data sections. Static data can be accessed with 16 bit relative addresses if datasize $\leq$ 32000. 
This makes the code more compact. See page \pageref{SpecifyDataSize}.\\
-codesize=n & Specify maximum combined size of code and read-only sections. \\
           & Inter-module jumps and call tables can use 16 bit relative addresses when codesize $\leq$ 131000, and 24 bit relative addresses when codesize $\leq$ 33000000. \\
           & Read-only static data can be accessed with 16 bit relative addresses if codesize $\leq$ 32000. See page \pageref{SpecifyDataSize}.\\
\hline
\end{tabular}
%\end{table}
\vv
 
The preferred extension for file names in ForwardCom are .as for assembly files and .ob for object files.
\vv
 
 
 
 
%%%%%%%%%%%%%%%%%%%
 
 
\section{Disassembler} \label{disassembler}
 
The disassembler can convert object files and executable files back to assembly language.
The command line for the disassembler has the following format:
 
\vv
\hspace{5mm} {\ttfamily forw -dis inputfile outputfile [options]}
 
\vv
The following options are supported:\\
\begin{tabular}{|p{22mm}p{140mm}|}
\hline
-ilist=name & specify alternative instruction list name.\\
\hline
\end{tabular}
\vv
 
The disassembler produces output lines that may look like this example:
 
\begin{lstlisting}
float v1 = add(v2, 2.5) // 002C _ 227_E 08.0 5 01.02.02.02 _ 4100 00
\end{lstlisting}
\vv
 
The comment is interpreted as follows:\\
\vv
 
\begin{tabular}{|p{22mm}p{140mm}|}
\hline
002C & hexadecimal address relative to the beginning of the current section\\
227\_E  & il, mode, and mode2 in the E2 format template. The last digit can indicate various kinds of subdivision of the code format\\
08.0 & operation code OP1 and OP2\\
5    & operand type. 5 means float\\
01.02.02.02 & register fields RD, RS, RT, RU\\
\_   & the mask field is unused in this case\\
4100 & the 16-bit data field IM2 contains the value 2.5 in half precision. If the value had been 2.6 we would need full precision and another code format\\
00 & the IM3 field is unused in this case\\
\hline
\end{tabular}
\vspace{4mm}
 
The addresses shown are byte-addresses for data sections, but word-addresses (i.e. divided by 4) for executable code sections.
\vv
 
The disassembler is used internally to generate a list output for the assembler. The  assembly listing and the disassembly are very similar. The names of local labels are lost in the disassembly unless the -debug option is used when assembling and linking.
 The disassembler will assign label names of the form @\_001 where original label names are missing or lost.
\vv
 
 
\section{Linker} \label{linker}
 
The linker joins object files and library files into an executable file.
 
The command line for the linker has the following format:
\vv
 
{\ttfamily 
\hspace{5mm} forw -link   outputfile [options] objectfiles libraryfiles \\
\hspace{5mm} forw -relink inputfile outputfile [options] objectfiles libraryfiles
}
\vv
 
The preferred extensions for file names in ForwardCom are .ob for object files, li. for library files, and .ex for executable files.
\vv
 
\subsection{Linking an executable file} \label{linking}
The link command will create an executable file and overwrite any existing file with the same name.
\vv
 
The following options are supported:\\
\begin{tabular}{|p{28mm}p{130mm}|}
\hline
-a & (Default) Add the following object files or library files to the executable.\\
-r & The following object files or library files will be added as relinkable modules so that they can be replaced later. The executable file will be relinkable.\\
-m & Add the module(s) with the following name(s) from the previously specified library, even when 
these modules are not needed for resolving external references.\\
-d & Delete the following relinkable modules or libraries from the executable file (when relinking).\\
-u & Allow the executable file to have unresolved external symbols. These symbols can be added later when relinking the incomplete executable file. The executable file will be relinkable.\\ 
-x & Extract relinkable module from executable file. -xall = all relinkable modules.\\
-map=filename & Make a link map showing addresses and sizes of sections.\\
-debug & Add debugging information to the executable file. Currently, the only debugging information is label names and section names.\\
-hex2  & Make a file containing the executable code section in hexadecimal format, with 2 32-bit words per line.\\
\hline
\end{tabular}
\vv
 
This example will create an executable file from the modules file1.ob and file2.ob, and any members of the library library3.li that may be needed:
\begin{lstlisting}[frame=single]
forw -link -debug myprogram.ex file1.ob file2.ob library3.li
\end{lstlisting}
\vspace{4mm}
 
%The linker has no option for making a map file. Use the dump or disassemble commands instead.
\vv
 
 
\subsection{Making a relinkable executable file} \label{makingARelinkableExecutableFile}
A relinkable executable file is a file where some or all of the object modules and libraries can be replaced later and new modules can be added. A relinkable executable file contains more information about symbol names and cross-references than a non-relinkable. This extra information is used only when relinking, it is not loaded into memory when the program is executed.
\vv
 
Any of the modules that are included in a relinkable executable file can be relinkable or non-relinkable. The relinkable modules can be removed or replaced later. The non-relinkable modules are permanent. 
\vv
 
This example produces a relinkable executable file where all of the modules are relinkable:
\begin{lstlisting}[frame=single]
forw -link myprogram.ex -r file1.ob file2.ob library3.li
\end{lstlisting}
\vspace{4mm}
 
This example produces a relinkable executable file where file1.ob is permanent and the remaining modules are relinkable:
\begin{lstlisting}[frame=single]
forw -link myprogram.ex -a file1.ob -r file2.ob library3.li
\end{lstlisting}
\vspace{4mm}
 
This example produces a relinkable executable file where all the modules are permanent, but new modules can be added later:
\begin{lstlisting}[frame=single]
forw -link myprogram.ex -a file1.ob file2.ob library3.li -r
\end{lstlisting}
\vspace{4mm}
 
This example produces a relinkable executable file where file1.ob and file2.ob are permanent,  library3.li is relinkable, and module4.ob from library3.li is added explicitly. Note that module4.ob
will be lost by subsequent relinking if there is no reference to it because it is stored as a relinkable library module:
\begin{lstlisting}[frame=single]
forw -link myprogram.ex -a file1.ob file2.ob -r library3.li -m module4.ob
\end{lstlisting}
\vspace{4mm}
 
You can list the relinkable modules contained in an executable file with the dump command:
\begin{lstlisting}[frame=single]
forw -dump -m myprogram.ex
\end{lstlisting}
\vspace{4mm}
 
 
\subsection{Relinking an executable file} \label{relinking}
The relink command will modify an existing relinkable executable file and produce a new relinkable executable file with a different name. The options are the same as above. 
\vv
 
This example will relink an executable file, replacing file2.ob by file2b.ob and replacing library3.li by a newer version of this library with the same name:
\begin{lstlisting}[frame=single]
forw -relink myprogram.ex myprogram2.ex -d file2.ob -r file2b.ob library3.li
\end{lstlisting}
\vspace{4mm}
 
\subsection{Adding a plugin to a relinkable executable file} \label{AddingAPlugin}
You can use the relinking feature to add a plugin to a relinkable executable file.
\vv
 
There are two ways in which the program can access the plugin. The first method is to define a weak external function in the main program and make a public function with the same name in the plugin module. Calling this function will have no effect if the plugin module is not present.
\vv
 
The other way is to define an event handler in the plugin module. This event handler will be called if the event occurs, for example when a menu item is clicked.
\vv
 
This example will add a plugin module plugin4.li to a relinkable executable file. The member start.ob in plugin4.li is added explicitly. The remaining members of plugin4.li are added only if there is a reference to them.
\begin{lstlisting}[frame=single]
forw -relink myprogram.ex myprogram2.ex -r plugin4.li -m start.ob
\end{lstlisting}
\vspace{4mm}
 
\subsection{Extracting a module from a relinkable executable file} \label{ExtractingFromRelinkable}
You can extract modules from a relinkable executable file. This feature is used mainly for testing and debugging purposes. The extracted file is not guaranteed to be identical to the original object file.
\vv
 
\begin{lstlisting}[frame=single]
forw -relink myprogram.ex myprogram2.ex -x file1.ob
\end{lstlisting}
\vspace{4mm}
 
The output file will be written to the current directory and have a name with prefix ''x\_''.
''-xall'' will extract all relinkable modules.
The output executable file (myprogram2.ex in the above example) is specified but not used.
\vv
 
\subsection{Relinking and library functions} \label{relinkingAndLibraryFunctions}
A library function is included in an executable file only if there is a reference to it. The library functions that are included in a relinkable executable file can be reused when relinking. 
If a later addition or modification to the executable file needs a library function that was not included in the original executable then the library has to be added again during relinking.
\vv
 
A relinkable library function in an executable file will be replaced during relinking if a new module or library contains a function with the same name. A library function that was included as non-relinkable in a relinkable executable file cannot be replaced later.
\vv
 
 
\subsection{Relinking and communal sections} \label{relinkingAndCommunalSections}
Communal sections are described on page \pageref{communal}. Communal sections have certain similarities with library functions.
\vv
 
A communal section will not be included in the executable file if there is no reference to it.
You will get a linking error if a later addition or modification to the executable file attempts to reference a symbol in a discarded communal section. There are three ways to fix this problem:
 
\begin{itemize}
\item Make the section not communal
\item Make a reference to the symbol in order to make sure it is always included in the executable file
\item Include a copy of the communal section in a module added when relinking
\end{itemize}
 
A communal section in a relinkable module will retain its properties. A communal section in a non-relinkable module will become non-communal, and any weak symbols in this section will become public and non-weak. If multiple communal sections with the same name are contained in both relinkable and non-relinkable modules then the linker will include only one.
A bigger section is chosen before a smaller one. A section in an object file is chosen before a section in a library file. Finally, the one that comes first on the command line is preferred.
\vv
 
\subsection{Making a hexadecimal file} \label{makingAHexadecimalFile}
A hexadecimal file may be needed for coding a loader into ROM memory. The hexadecimal file is generated in the same way as an executable file, using the -hex option. 
The output file will contain the executable code section in hexadecimal format. The number of 32-bits per line is specified as a suffix, e.g. -hex2 gives 2 words per line. Each line contains a hexadecimal number in big endian format.
\vv
 
 
\section{Library manager} \label{libraryManager}
 
A function library is a collection of object files each defining one or more functions that can be called from other modules. The library manager can make a function library and add or remove modules in it.
\vv
 
The command line for the library manager has the following format:
\vv
 
\hspace{5mm} {\ttfamily forw -lib libraryfile [options] objectfiles}
\vv
 
The following options are supported:\\
\begin{tabular}{|p{10mm}p{150mm}|}
\hline
-a & (Default) Add the following object files to the library. Any existing object file with the same name will be replaced.\\
-d & Delete the following object files from the library.\\
-l & List object file members.\\
-l2 & List object file members and their exported symbols.\\
-l3 & List object file members and their exported and imported symbols.\\
-x & Extract the following object files from the library.\\
-xall & Extract all object files from the library. \\
\hline
\end{tabular}
\vv
 
If a library with the specified name already exists, then it will be modified by adding, deleting, or replacing object files. The library will be created if it does not already exists.
\vv
 
The preferred extension for file names in ForwardCom are .ob for object files and .li for library files.
\vv
 
The names of the object files are stored in the library without the file path so that they can be extracted on another computer with a different directory structure. The library cannot contain multiple object files with the same name.
\vv
 
The ForwardCom system has only one type of library files. The same library can be used for static and runtime linking and for relinking of an executable file.
\vv
 
A standard C library is provided with the name libc.li. 
A library of mathematical functions is provided with the name math.li. 
A lightweight version of libc.li is provided with the name libc-light.li for the small softcore with limited capabilities and no system calls.
\vv
 
\section{Emulator and debugger} \label{emulator}
 
The emulator can execute a ForwardCom executable file on another platform. It is useful for testing and debugging.
\vv
 
The command line for the emulator has the following format:
\vv
 
\hspace{5mm} {\ttfamily forw -emu executable\_file [options]}
\vv
 
\vv
The following options are supported:\\
\begin{tabular}{|p{22mm}p{140mm}|}
\hline
-list=name & Make list file with debug output.\\
-maxlines=n & Maximum number of instructions in debug output list.\\
-ilist=name & Specify alternative instruction list name.\\
\hline
\end{tabular}
\vv
 
The debug list output will show all executed instructions and their results. 
It is recommended to use the -debug option when assembling and linking in order to preserve label names in the debug output.
\vv
 
Interactive single-step debugging is currently not supported in the emulator.
\vv
 
The current version of the emulator supports all general instructions but only few system instructions. Integers of 8, 16, 32, and 64 bits are supported. Floating point numbers with half, single, and double precision are supported. Quadruple precision is not supported. Only few instructions with 128 bit integers are supported. 
Most optional features are supported by the emulator, including exception handling, rounding control, and subnormal numbers.
\vv
 
\section{Dump utililty} \label{dumpUtililty}
 
The dump utility can show metadata from object files and executable files.
\vv
 
The command line for the dump utility has the following format:
\vv
 
\hspace{5mm} {\ttfamily forw -dump-options object\_file }
\vv
 
The following options are supported:\\
\begin{tabular}{|p{10mm}p{150mm}|}
\hline
f & file header.\\
h & section headers.\\
l & link map.\\
s & symbol table.\\
n & string table.\\
r & relocation records.\\
m & relinkable modules.\\
\hline
\end{tabular}
\vv
 
 
\section{Compiling the forw tools} \label{compilingForw}
These tools can be compiled for Windows, Linux, MacOS, and other platforms. 
\vv
 
To compile for Windows using Visual Studio, use the project files forw.sln and  forw.vcxproj.
\vv
 
To compile for Linux or other platforms using a Gnu or Clang compiler, use Gnu make with the command make -f forw.make
\vv
 
See the file forwardcom\_sourcecode\_documentation for details.
\vv
 
 
\section{Code examples} \label{codeExamples}
A collection of code examples are provided in the examples folder. You can try an example by assembling, linking, and emulating it as follows:
\vv
 
forw -ass hello.as \\
forw -link hello.ex hello.ob libc.li \\
forw -emu hello.ex
\vv
 
 
\end{document}