URL https://opencores.org/ocsvn/forwardcom/forwardcom/trunk

# Subversion Repositoriesforwardcom

## [/] [forwardcom/] [manual/] [fwc_bintools.tex] - Blame information for rev 141

Line No. Rev Author Line
1 141 Agner
% chapter included in forwardcom.tex
2
\documentclass[forwardcom.tex]{subfiles}
3
\begin{document}
4
\RaggedRight
5
%\newtheorem{example}{Example}[chapter]  % example numbering
6
\lstset{language=C}            % formatting for code listing
7
\lstset{basicstyle=\ttfamily,breaklines=true}
8
 
9
 
10
\chapter{Binary tools} \label{chap:binTools}
11
All the basic development tools for ForwardCom except compilers are combined into a single executable file named \textbf{forw} or \textbf{forw.exe}.
12
\vv
13
 
14
The tools can be run using the following command lines:
15
\vv
16
 
17
%\begin{table}[]
18
%\left
19
%\caption{Commands}
20
\label{bintoolCommands}
21
\begin{tabular}{ll}
22
\hline
23
assemble & forw -ass assemblyfile objectfile \\
24
disassemble & forw -dis objectfile assemblyfile \\
25
link & forw -link exefile objectfiles libraryfiles \\
26
relink & forw -relink inputfile outputfile objectfiles libraryfiles \\
27
make library & forw -lib libraryfile objectfiles \\
28
emulate & forw -emu exefile \\
29
debug & forw -emu exefile  -list=debugout.txt \\
30
dump & forw -dump objectfile \\
31
help & forw -help \\
32
\hline
33
\end{tabular}
34
\vspace{4mm}
35
 
36
General options:
37
 
38
The following options can be used with most or all of the commands listed above:
39
 
40
\begin{tabular}{p{20mm}p{140mm}}
41
\hline
42
@file & read additional command line options or file names from file.\\
43
-ilist=file & alternative instruction list file.\\
44
-wdNNN & disable Warning NNN.\\
45
-weNNN & treat Warning NNN as Error. -wex: treat all warnings as errors.\\
46
-edNNN & disable Error number NNN.\\
47
-ewNNN & treat Error number NNN as Warning.\\
48
\hline
49
\end{tabular}
50
\vv
51
 
52
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}.
53
\vv
54
 
55
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.
56
\vv
57
 
58
\section{Assembler}\label{chap:assembler}
59
\subsection{Introduction} \label{assemblerIntroduction}
60
The assembler is using a syntax similar to C and Java in order to make the code intelligible to high-level language programmers.
61
The details are described in the programming manual in chapter
62
\ref{chap:programmingManual}, page \pageref{chap:programmingManual}.
63
\vv
64
 
65
\subsection{Command line} \label{assemblerCommandLine}
66
The command line for the assembler has the following format:
67
 
68
\vv
69
\hspace{5mm} {\ttfamily forw -ass [options] assemblyfile objectfile}
70
 
71
\vv
72
The following options are supported:\\
73
\begin{tabular}{|p{25mm}p{135mm}|}
74
\hline
75
-list=name & Make output list file. This is useful for checking the generated code.\\
76
-ilist=name & Specify alternative instruction list name.\\
77
-b         & Make binary listing in -list file. \\
78
-O0 & Optimization level 0: The assembler finds the smallest possible instruction that fits the specified operands. \\
79
-O1 & Optimization level 1 (default): An instruction may be replaced by another instruction that does the same thing more efficiently. For example, \linebreak
80
{\ttfamily float v1 *= 4} can be replaced by
81
 {\ttfamily float v1 = mul\_2pow(v1, 2)}. \linebreak
82
A conditional jump statement is merged with a preceding arithmetic instruction when possible.
83
 An {\ttfamily if} statement immediately followed by an
84
 unconditional jump is converted to a single conditional jump.\\
85
-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)}.\\
86
-debug=1  & Include debug information in object file. Currently, debug information includes only label names.\\
87
-maxerrors=n & Specify maximum number of error messages from the assembler.\\
88
-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.
89
This makes the code more compact. See page \pageref{SpecifyDataSize}.\\
90
-codesize=n & Specify maximum combined size of code and read-only sections. \\
91
           & 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. \\
92
           & Read-only static data can be accessed with 16 bit relative addresses if codesize $\leq$ 32000. See page \pageref{SpecifyDataSize}.\\
93
\hline
94
\end{tabular}
95
%\end{table}
96
\vv
97
 
98
The preferred extension for file names in ForwardCom are .as for assembly files and .ob for object files.
99
\vv
100
 
101
 
102
 
103
 
104
%%%%%%%%%%%%%%%%%%%
105
 
106
 
107
\section{Disassembler} \label{disassembler}
108
 
109
The disassembler can convert object files and executable files back to assembly language.
110
The command line for the disassembler has the following format:
111
 
112
\vv
113
\hspace{5mm} {\ttfamily forw -dis inputfile outputfile [options]}
114
 
115
\vv
116
The following options are supported:\\
117
\begin{tabular}{|p{22mm}p{140mm}|}
118
\hline
119
-ilist=name & specify alternative instruction list name.\\
120
\hline
121
\end{tabular}
122
\vv
123
 
124
The disassembler produces output lines that may look like this example:
125
 
126
\begin{lstlisting}
127
float v1 = add(v2, 2.5) // 002C _ 227_E 08.0 5 01.02.02.02 _ 4100 00
128
\end{lstlisting}
129
\vv
130
 
131
The comment is interpreted as follows:\\
132
\vv
133
 
134
\begin{tabular}{|p{22mm}p{140mm}|}
135
\hline
136
002C & hexadecimal address relative to the beginning of the current section\\
137
227\_E  & il, mode, and mode2 in the E2 format template. The last digit can indicate various kinds of subdivision of the code format\\
138
08.0 & operation code OP1 and OP2\\
139
5    & operand type. 5 means float\\
140
01.02.02.02 & register fields RD, RS, RT, RU\\
141
\_   & the mask field is unused in this case\\
142
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\\
143
00 & the IM3 field is unused in this case\\
144
\hline
145
\end{tabular}
146
\vspace{4mm}
147
 
148
The addresses shown are byte-addresses for data sections, but word-addresses (i.e. divided by 4) for executable code sections.
149
\vv
150
 
151
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.
152
 The disassembler will assign label names of the form @\_001 where original label names are missing or lost.
153
\vv
154
 
155
 
156
\section{Linker} \label{linker}
157
 
158
The linker joins object files and library files into an executable file.
159
 
160
The command line for the linker has the following format:
161
\vv
162
 
163
{\ttfamily
164
\hspace{5mm} forw -link   outputfile [options] objectfiles libraryfiles \\
165
\hspace{5mm} forw -relink inputfile outputfile [options] objectfiles libraryfiles
166
}
167
\vv
168
 
169
The preferred extensions for file names in ForwardCom are .ob for object files, li. for library files, and .ex for executable files.
170
\vv
171
 
172
\subsection{Linking an executable file} \label{linking}
173
The link command will create an executable file and overwrite any existing file with the same name.
174
\vv
175
 
176
The following options are supported:\\
177
\begin{tabular}{|p{28mm}p{130mm}|}
178
\hline
179
-a & (Default) Add the following object files or library files to the executable.\\
180
-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.\\
181
-m & Add the module(s) with the following name(s) from the previously specified library, even when
182
these modules are not needed for resolving external references.\\
183
-d & Delete the following relinkable modules or libraries from the executable file (when relinking).\\
184
-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.\\
185
-x & Extract relinkable module from executable file. -xall = all relinkable modules.\\
186
-map=filename & Make a link map showing addresses and sizes of sections.\\
187
-debug & Add debugging information to the executable file. Currently, the only debugging information is label names and section names.\\
188
-hex2  & Make a file containing the executable code section in hexadecimal format, with 2 32-bit words per line.\\
189
\hline
190
\end{tabular}
191
\vv
192
 
193
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:
194
\begin{lstlisting}[frame=single]
195
forw -link -debug myprogram.ex file1.ob file2.ob library3.li
196
\end{lstlisting}
197
\vspace{4mm}
198
 
199
%The linker has no option for making a map file. Use the dump or disassemble commands instead.
200
\vv
201
 
202
 
203
\subsection{Making a relinkable executable file} \label{makingARelinkableExecutableFile}
204
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.
205
\vv
206
 
207
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.
208
\vv
209
 
210
This example produces a relinkable executable file where all of the modules are relinkable:
211
\begin{lstlisting}[frame=single]
212
forw -link myprogram.ex -r file1.ob file2.ob library3.li
213
\end{lstlisting}
214
\vspace{4mm}
215
 
216
This example produces a relinkable executable file where file1.ob is permanent and the remaining modules are relinkable:
217
\begin{lstlisting}[frame=single]
218
forw -link myprogram.ex -a file1.ob -r file2.ob library3.li
219
\end{lstlisting}
220
\vspace{4mm}
221
 
222
This example produces a relinkable executable file where all the modules are permanent, but new modules can be added later:
223
\begin{lstlisting}[frame=single]
224
forw -link myprogram.ex -a file1.ob file2.ob library3.li -r
225
\end{lstlisting}
226
\vspace{4mm}
227
 
228
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
229
will be lost by subsequent relinking if there is no reference to it because it is stored as a relinkable library module:
230
\begin{lstlisting}[frame=single]
231
forw -link myprogram.ex -a file1.ob file2.ob -r library3.li -m module4.ob
232
\end{lstlisting}
233
\vspace{4mm}
234
 
235
You can list the relinkable modules contained in an executable file with the dump command:
236
\begin{lstlisting}[frame=single]
237
forw -dump -m myprogram.ex
238
\end{lstlisting}
239
\vspace{4mm}
240
 
241
 
242
\subsection{Relinking an executable file} \label{relinking}
243
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.
244
\vv
245
 
246
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:
247
\begin{lstlisting}[frame=single]
248
forw -relink myprogram.ex myprogram2.ex -d file2.ob -r file2b.ob library3.li
249
\end{lstlisting}
250
\vspace{4mm}
251
 
252
\subsection{Adding a plugin to a relinkable executable file} \label{AddingAPlugin}
253
You can use the relinking feature to add a plugin to a relinkable executable file.
254
\vv
255
 
256
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.
257
\vv
258
 
259
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.
260
\vv
261
 
262
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.
263
\begin{lstlisting}[frame=single]
264
forw -relink myprogram.ex myprogram2.ex -r plugin4.li -m start.ob
265
\end{lstlisting}
266
\vspace{4mm}
267
 
268
\subsection{Extracting a module from a relinkable executable file} \label{ExtractingFromRelinkable}
269
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.
270
\vv
271
 
272
\begin{lstlisting}[frame=single]
273
forw -relink myprogram.ex myprogram2.ex -x file1.ob
274
\end{lstlisting}
275
\vspace{4mm}
276
 
277
The output file will be written to the current directory and have a name with prefix ''x\_''.
278
''-xall'' will extract all relinkable modules.
279
The output executable file (myprogram2.ex in the above example) is specified but not used.
280
\vv
281
 
282
\subsection{Relinking and library functions} \label{relinkingAndLibraryFunctions}
283
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.
284
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.
285
\vv
286
 
287
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.
288
\vv
289
 
290
 
291
\subsection{Relinking and communal sections} \label{relinkingAndCommunalSections}
292
Communal sections are described on page \pageref{communal}. Communal sections have certain similarities with library functions.
293
\vv
294
 
295
A communal section will not be included in the executable file if there is no reference to it.
296
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:
297
 
298
\begin{itemize}
299
\item Make the section not communal
300
\item Make a reference to the symbol in order to make sure it is always included in the executable file
301
\item Include a copy of the communal section in a module added when relinking
302
\end{itemize}
303
 
304
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.
305
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.
306
\vv
307
 
308
\subsection{Making a hexadecimal file} \label{makingAHexadecimalFile}
309
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.
310
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.
311
\vv
312
 
313
 
314
\section{Library manager} \label{libraryManager}
315
 
316
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.
317
\vv
318
 
319
The command line for the library manager has the following format:
320
\vv
321
 
322
\hspace{5mm} {\ttfamily forw -lib libraryfile [options] objectfiles}
323
\vv
324
 
325
The following options are supported:\\
326
\begin{tabular}{|p{10mm}p{150mm}|}
327
\hline
328
-a & (Default) Add the following object files to the library. Any existing object file with the same name will be replaced.\\
329
-d & Delete the following object files from the library.\\
330
-l & List object file members.\\
331
-l2 & List object file members and their exported symbols.\\
332
-l3 & List object file members and their exported and imported symbols.\\
333
-x & Extract the following object files from the library.\\
334
-xall & Extract all object files from the library. \\
335
\hline
336
\end{tabular}
337
\vv
338
 
339
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.
340
\vv
341
 
342
The preferred extension for file names in ForwardCom are .ob for object files and .li for library files.
343
\vv
344
 
345
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.
346
\vv
347
 
348
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.
349
\vv
350
 
351
A standard C library is provided with the name libc.li.
352
A library of mathematical functions is provided with the name math.li.
353
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.
354
\vv
355
 
356
\section{Emulator and debugger} \label{emulator}
357
 
358
The emulator can execute a ForwardCom executable file on another platform. It is useful for testing and debugging.
359
\vv
360
 
361
The command line for the emulator has the following format:
362
\vv
363
 
364
\hspace{5mm} {\ttfamily forw -emu executable\_file [options]}
365
\vv
366
 
367
\vv
368
The following options are supported:\\
369
\begin{tabular}{|p{22mm}p{140mm}|}
370
\hline
371
-list=name & Make list file with debug output.\\
372
-maxlines=n & Maximum number of instructions in debug output list.\\
373
-ilist=name & Specify alternative instruction list name.\\
374
\hline
375
\end{tabular}
376
\vv
377
 
378
The debug list output will show all executed instructions and their results.
379
It is recommended to use the -debug option when assembling and linking in order to preserve label names in the debug output.
380
\vv
381
 
382
Interactive single-step debugging is currently not supported in the emulator.
383
\vv
384
 
385
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.
386
Most optional features are supported by the emulator, including exception handling, rounding control, and subnormal numbers.
387
\vv
388
 
389
\section{Dump utililty} \label{dumpUtililty}
390
 
391
The dump utility can show metadata from object files and executable files.
392
\vv
393
 
394
The command line for the dump utility has the following format:
395
\vv
396
 
397
\hspace{5mm} {\ttfamily forw -dump-options object\_file }
398
\vv
399
 
400
The following options are supported:\\
401
\begin{tabular}{|p{10mm}p{150mm}|}
402
\hline
403
f & file header.\\
404
h & section headers.\\
405
l & link map.\\
406
s & symbol table.\\
407
n & string table.\\
408
r & relocation records.\\
409
m & relinkable modules.\\
410
\hline
411
\end{tabular}
412
\vv
413
 
414
 
415
\section{Compiling the forw tools} \label{compilingForw}
416
These tools can be compiled for Windows, Linux, MacOS, and other platforms.
417
\vv
418
 
419
To compile for Windows using Visual Studio, use the project files forw.sln and  forw.vcxproj.
420
\vv
421
 
422
To compile for Linux or other platforms using a Gnu or Clang compiler, use Gnu make with the command make -f forw.make
423
\vv
424
 
425
See the file forwardcom\_sourcecode\_documentation for details.
426
\vv
427
 
428
 
429
\section{Code examples} \label{codeExamples}
430
A collection of code examples are provided in the examples folder. You can try an example by assembling, linking, and emulating it as follows:
431
\vv
432
 
433
forw -ass hello.as \\
434
forw -link hello.ex hello.ob libc.li \\
435
forw -emu hello.ex
436
\vv
437
 
438
 
439
\end{document}