source: rtems-tools/linkers/main-page.cpp @ b69cd3f

4.104.11
Last change on this file since b69cd3f was b1e9ab9, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 20, 2014 at 6:46:43 PM

main-page.cpp: Fix spelling issue

  • Property mode set to 100644
File size: 18.8 KB
Line 
1/*
2 * Copyright (c) 2011-2013, Chris Johns <chrisj@rtems.org>
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 */
16
17/**
18 * @mainpage RTEMS Linker Tools
19 *
20 * The RTEMS Linker is a suite of tools that create and manage @subpage rtems-apps
21 * that are dynamically loadable by the @subpage rtems-rtl on target
22 * hardware. The target code uses the standard `dlopen`, `dlclose` type calls
23 * to load and manage modules, object files or archives on the target at
24 * runtime. The RTEMS Linker forms a part of this process by helping managing
25 * the object files, libraries and applications on a host machine. This host
26 * processing simplifies the demands on the target and avoids wastefull excess
27 * of files and data that may not be used at runtime.
28 *
29 * These tools are written in C++ with some 3rd party packages in C. The
30 * license for this RTEMS Tools code is a BSD type open source license. The
31 * package includes code from:
32 *
33 * -# @b efltoolchain - http://sourceforge.net/apps/trac/elftoolchain/
34 * -# @b libiberty - Libiberty code from GCC (GPL)
35 * -# @b fastlz - http://fastlz.org/
36 *
37 * The project uses a C++ demangler and PEX code from the GCC project. This
38 * code is GPL making this project GPL. A platform independent way to execute
39 * sub-processes and capture the output that is not GPL is most welcome.
40 *
41 * @subpage build-me details building this package with @subpage waf.
42 *
43 * The tools provided are:
44 *
45 * - @subpage rtems-ld
46 * - @subpage rtems-syms
47 * - @subpage rtems-rap
48 *
49 * ____________________________________________________________________________
50 * @copyright
51 * Copyright (c) 2011-2013, Chris Johns <chrisj@rtems.org>
52 * @copyright
53 * Permission to use, copy, modify, and/or distribute this software for any
54 * purpose with or without fee is hereby granted, provided that the above
55 * copyright notice and this permission notice appear in all copies.
56 * @copyright
57 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
58 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
59 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
60 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
61 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
62 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
63 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
64 *
65 */
66
67/**
68 * @page rtems-apps RTEMS Applications
69 *
70 * The RTEMS Linker and @ref rtems-rtl provides RTEMS with the ability to
71 * support applications loaded and linked at runtime. RTEMS is a single address
72 * space real-time operating system designed for embedded systems that are
73 * statically linked therefore the idea of applications requires some extra
74 * understanding when applied to RTEMS. They are not essential, rather they are
75 * important in a range of systems that have the resources available to support
76 * them.
77 *
78 * Applications allow:
79 *
80 * - A team to create a single verified base kernel image that is used by all
81 *   team developers. This kernel could be embedded on the target hardware and
82 *   applications loaded over a network. The verified kernel binary used during
83 *   development can be shipped without being changed.
84 *
85 * - Layered applications designed as modules that are loaded at runtime to
86 *   create a specific target environment for a specific system. This approach
87 *   allows development of modules that become verified components. An example
88 *   is the NASA Core Flight Executive.
89 *
90 * - Runtime configuration and loading of features or drivers based on
91 *   configuration data or detected hardware. This is important if your target
92 *   hardware has an external bus such as PCI. You can add a new driver to a
93 *   system without needing to rebuild the kernel and application lowering the
94 *   verify and validation costs. If these are high the savings can be
95 *   substantial.
96 *
97 * RTEMS is a single address space operating system therefore any code loaded
98 * is loaded into that address space. This means applications are not operating
99 * in a separate protected address space you typically get with host type
100 * operating systems. You need to control and manage what you allow to load on
101 * your system. This is no differerent to how single image RTEMS are currently
102 * created and managed. The point being RTEMS applications only changes the way
103 * you package and maintain your applications and do not provide any improved
104 * security or protection. You need to do this as your currently do with
105 * testing and careful design.
106 *
107 * RTEMS is statically linked to a fixed address and does not support dynamic
108 * ELF files. Dynamic ELF files are designed for use in virtual memory
109 * protected address space operating systems. They contain Position Independent
110 * Code (PIC) code, Procedure Linkage Tables (PLT) and Global Offset Tables
111 * (GOT) and are effective in not only allowing dynamic linking at runtime but
112 * also the sharing of the code between separate process address spaces. Using
113 * virtual memory and a memory management unit, a protected address space
114 * operating system can efficiently share code between processes with minimal
115 * performance overhead. RTEMS has no such need because it is a single address
116 * space and all code is shared therefore ELF dynamic files only add complexity
117 * and performance overhead. This means RTEMS needs a target based run-time
118 * link editor that can relocate and fix up static code when loading it and
119 * RTEMS loadable files need to contain the symbols and relocation records to
120 * allow relocation to happen.
121 *
122 * The @ref rtems-rtl supports the followiing file formats:
123 *
124 * -# Relocatable ELF (ELF)
125 * -# RTEMS Application (RAP)
126 * -# Archive (AR) Libraries with GNU extensions
127 *
128 * ### Relocation ELF Files
129 *
130 * The @ref rtems-rtl can load standard relocatable ELF format files. They can
131 * be stripped or unstripped. This ELF file is the standard output from the
132 * compiler and is contained in the standard libraries.
133 *
134 * ### RTEMS Application (RAP) Files.
135 *
136 * The @ref rtems-rtl can load RAP format files. This format is RTEMS specific
137 * and is designed to minimise the overhead and resources needed to load the
138 * file on the target. A RAP file is compressed using LZ77 compression and
139 * contains only the following sections:
140 *
141 * - `.text` - The executable code section.
142 * - `.const` - The constants and strings section.
143 * - `.ctor` - The constructor table section.
144 * - `.dtor` - The destructor table section.
145 * - `.data` - The initialised data section.
146 *
147 * The `.bss` uninitialised data section is only a size. A RAP file also
148 * contains a symbol string table and symbol table that are directly loadable
149 * into into the target memory. Finally the RAP contains the relocation
150 * records. The format is structured so it can be read and processed as a
151 * stream with the need to seek on the file.
152 *
153 * The @ref rtems-ld can output RAP format files suitable for loading. It will
154 * take the object files from the command line and the referenced files from
155 * the libraries and merge all the sections, symbols and relocation records to
156 * create the RAP format file.
157 *
158 * RAP format files are the most efficient way to load applications or modules
159 * because all object files are merged into an single image. Each file loaded
160 * on the target has and overhead therefore lowering the number of files loaded
161 * lowers the overhead. You could also use the standard linker to incrementally
162 * link the command line object files to archieve the same effect.
163 *
164 * ### Archive (AR) Library Files
165 *
166 * The @ref rtems-rtl can load from archive or library type files. The file
167 * name syntax lets a user reference a file in an archive. The format is:
168 *
169 * @par
170 * `libme.a:foo.o@12345`
171 *
172 * where `libme.a` is the archive file name, `foo.o` is the file in the archive
173 * and `@12345` is optionally the offset in the archive where the file
174 * starts. The optional offset helps speed up load by avoiding the file name
175 * table search. If the archive is stable and known the offset will be
176 * fixed. If the file is located at the offset the file name table is searched.
177 *
178 * At this point in time only ELF files can be loaded from archives. Loading of
179 * RAP format files is planned.
180 *
181 * ## An Application
182 *
183 * Applications are created the same way you create standard host type
184 * programs. You compile the source files and link them using the @ref
185 * rtems-ld.
186 *
187 * @code
188 * $ rtems-ld --base my-rtems foo.o bar.o -o my-app.rap -L /lib/path -lstuff
189 * @endcode
190 *
191 * The command line of the @ref rtems-ld is similar to a standard linker with
192 * some extra features specific to RTEMS. You provide a list of object files,
193 * libraries and library paths plus you need to provide the RTEMS kernel image
194 * you will use to load the application. The RTEMS kernel image provides the
195 * symbols in the kernel to the linker. Errors will be generated if symbols are
196 * not located.
197 *
198 * The linker can output a archive of ELF files, a RAP file for a text script
199 * of files that need to be loaded.
200 *
201 * The script lets you load and link the application at runtime on the
202 * target. You need to copy the libraries referenced to the target.
203 *
204 * If you break your application into separate modules and each module
205 * references a symbol in a library that is not in the base image the linker
206 * will include the object file containing the symbol into each application
207 * module. This is only of concern for the RAP format because it merges the
208 * object files together. With the archive and scripts the loader will not load
209 * object files with duplicate symbols.
210 *
211 * @note In time the linker will gain an option to not pull object modules from
212 *       libraries into the RAP file. Another option will be added that will
213 *       copy referenced library object files into a target library all
214 *       application modules can share.
215 *
216 * ## Linking
217 *
218 * The @ref rtems-ld places the command line object files in the output image
219 * and any reference object files found in libraries. If a symbol is located in
220 * the kernel base image it is not searched for in the libraries.
221 *
222 * The architecture is automatically detected by inspecting the first object
223 * file passed on the command line. All future object files loaded must match
224 * the architecture for an error is raised. The linker supports all
225 * architectures in a single binrary. It is not like the GNU tools which are
226 * specific to an architecture.
227 *
228 * The linker needs to be able to locate the C compiler for the architecture
229 * being linked. The compiler can be in the path for a command line option can
230 * explicitly set the compiler. The compiler is used to locate the standard
231 * libraries such as the C library.
232 *
233 *
234 */
235
236/**
237 * @page rtems-rtl RTEMS Target Link Editor
238 *
239 * The RTEMS Target link editor is a C module you link to the RTEMS kernel to
240 * provide the `dlopen`, `dlclose` etc family of calls. This code is a stand
241 * alone project:
242 *
243 * @par
244 * http://git.rtems.org/chrisj/rtl.git
245 */
246
247/**
248 * @page build-me Building The RTEMS Linker
249 *
250 * This package is written in C++ therefore you need a current working C++
251 * compiler for your host. The GCC or clang compilers can be used and clang was
252 * used during the development. The build system is @ref waf.
253 *
254 * -# Clone the git repository:
255 * @code
256 * $ git clone http://git.rtems.org/chrisj/rtl-host.git rtl-host.git
257 * @endcode
258 * -# Configure with the default C++ compiler, default options, and an install
259 * prefix of `$HOME/development/rtems/4.11`:
260 * @code
261 * $ waf configure --prefix=$HOME/development/rtems/4.11
262 * @endcode
263 * With @ref waf you build in the source directory and the @ref waf script
264 * (`wscript`) will create a host specific directory. On MacOS the output is in
265 * `build-darwin`. If you clean the build tree by deleting this directly you
266 * will need to run the configure stage again.
267 * @note The nominal RTEMS prefix is `/opt/rtems-4.11` where `4.11` is the
268 *       version of RTEMS you are building the tools for. If you are using
269 *       RTEMS 4.10 or a different version please use that version number. I
270 *       always work under my home directory and under the `development/rtems`
271 *       tree and then use the version number.
272 * -# Build the tools:
273 * @code
274 * $ waf
275 * @endcode
276 * -# Install the tools to the configured prefix:
277 * @code
278 * $ waf install
279 * @endcode
280 *
281 * You will now have the tools contained in this package build and installed.
282 *
283 * At this stage of the project's development there are no tests. I am wondering
284 * if this could be a suitable GSoC project.
285 *
286 * To build with `clang` use the documented @ref waf method:
287 * @code
288 * $ CC=clang waf configure --prefix=$HOME/development/rtems/4.11
289 * @endcode
290 *
291 * You can add some extra options to @ref waf's configure to change the
292 * configuration. The options are:
293 * @code
294 * --rtems-version=RTEMS_VERSION
295 *                       Set the RTEMS version
296 * --c-opts=C_OPTS       Set build options, default: -O2.
297 * --show-commands       Print the commands as strings.
298 * @endcode
299 *
300 * - @b --rtems-version Set the RTEMS version number.
301 * Not used.
302 * - @b --c-opts Set the C and C++ compiler flags the tools are built with. For
303 * example to disable all optimization flags to allow better debugging do:
304 * @code
305 * $ waf configure --prefix=$HOME/development/rtems/4.11 --c-opts=
306 * @endcode
307 * - @b --show-commands Prints the command string used to the invoke the
308 *   compiler or linker. @ref waf normally prints a summary type line.
309 *
310 */
311
312/**
313 * @page waf Waf
314 *
315 * It is best you install waf by just downloading it from the Waf project
316 * website:
317 *
318 * @par
319 * http://code.google.com/p/waf/
320 *
321 * Waf is a Python program so you will also need to have a current Python
322 * version installed and in your path.
323 *
324 * I download the latest "run from writable folder" version named single waf
325 * file from http://code.google.com/p/waf/downloads/list to `$HOME/bin` and
326 * symlink it to `waf`. The directory `$HOME/bin` is in my path.
327 *
328 * @code
329 * $ cd $HOME/bin
330 * $ curl http://waf.googlecode.com/files/waf-1.7.9 > waf-1.7.9
331 *   % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
332 *                                  Dload  Upload   Total   Spent    Left  Speed
333 * 100 90486  100 90486    0     0  39912      0  0:00:02  0:00:02 --:--:-- 79934
334 * $ rm -f waf
335 * $ chmod +x waf-1.7.9
336 * $ ln -s waf-1.7.9 waf
337 * $ ./waf --version
338 * waf 1.7.9 (9e92489dbc008e4abae9c147b1d63b48296797c2)
339 * @endcode
340 */
341
342/**
343 * @page rtems-ld RTEMS Linker
344 *
345 * The RTEMS Linker is a single tool that lets you create applications. It is a
346 * special kind of linker and does not perform all the functions found in a
347 * normal linker. RAP format output performs a partial increment link.
348 *
349 * ## Command
350 *
351 * `rtems-ld [options] objects`
352 *
353 * ## Options
354 *
355 * - @e Help (@b -h @b --help): \n
356 *   Print the command line help then exit.
357 *
358 * - @e Version (@b -V @b --version): \n
359 *   Print the linker's version then exit.
360 *
361 * - @e Verbose (@b -v @b --verbose): \n
362 *   Control the trace output level. The RTEMS linker is always built with
363 *   trace logic. The more times this appears on the command the more detailed
364 *   the output becomes. The amount of output can be large at higher levels.
365 *
366 * - @e Warnings (@b -w @--warn): \n
367 *   Print warnings.
368 *
369 * - @e Map (@b -M @b --map): \n
370 *   Generate map output to stdout.
371 *
372 * - @e Output (@b -o @b --output): \n
373 *   Set the output file name.
374 *
375 * - @e Output @e Format (@b -O @b --out-format): \n
376 *   Set the output format. The valid formats are:
377 *    Format     | Description
378 *    -----------|----------------------------------------
379 *    @b rap     |RTEMS application (LZ77, single image)
380 *    @b elf     |ELF application (script, ELF files)
381 *    @b script  |Script format (list of object files)
382 *    @b archive |Archive format (collection of ELF files)
383 *
384 * - @e Library @e Path (@b -L @b --lib-path): \n
385 *   Add a library path. More than one path can be added with multiple library
386 *   path options.
387 *
388 * - @e Library (@b -l @b --lib): \n
389 *   Add a library. More than one library can be added with multiple library
390 *   paths.
391 *
392 * - @e No @e Standard @e Libraries (@b -n @b --no-stdlibs): \n
393 *   Do not search the standard libraries. The linker uses the architecture C
394 *   compiler to locate the installed standard libraries and these are
395 *   automatically searched. If this option is used the C compiler is not
396 *   called and the libraries are not added to the search list.
397 *
398 * - @e Entry @e Point (@b -e @b --entry): \n
399 *   Set the entry point. This is used with the RAP format and defaults to
400 *   `rtems`. The entry point is called when a RAP file is loaded by the
401 *   target RAP loader.
402 *
403 * - @e Define @e Symbol (@b -d @b --define): \n
404 *   Add a symbol to the symbol table. More than one symbol can be added
405 *   with multiple define options.
406 *
407 * - @e Undefined @e Symbol (@b -u @b --undefined): \n
408 *   Add an undefined symbol to the undefined symbol list. More than one
409 *   undefined symbol can be added with multiple undefined options. This
410 *   options will pull specific code into the output image.
411 *
412 * - @e RTEMS @e Kernel (@b -b @b --base): \n
413 *   Set the RTEMS kernel image. This is the ELF file of the RTEMS kernel
414 *   that will load the output from the linker. The RTEMS kernel is the
415 *   @e base module or image. The linker does not pull the symbol from a
416 *   library if the symbol is found in the base module. The kernel will
417 *   load the target symbol table with these symbols so they can be
418 *   resolved at runtime.
419 *
420 * - @e Architecture @e C @e Compiler (@b -C @b --cc): \n
421 *   Set the architecture's C compiler. This is used to find the standard
422 *   libraries.
423 *
424 * - @e Tool @e Prefix (@b -E @b --exec-prefix): \n
425 *   Set the tool prefix. The tool prefix is the architecture and this is
426 *   normally automatically set by inspecting the first object file
427 *   loaded. This option allows the automatic detection to be overridden.
428 *
429 * - @e Machine @e Architecture (@b -a @b --march): \n
430 *   Set the machine architecture.
431 *
432 * - @e Machine @e CPU (@b -c @b --mcpu): \n
433 *   Set the machine architecture's CPU.
434 */
435
436/**
437 * @page rtems-syms RTEMS Symbols Utility
438 *
439 * The symbols tool lets you see symbols in various RTEMS support file formats.
440 */
441
442/**
443 * @page rtems-rap RTEMS Application (RAP) Utility
444 *
445 * The symbols tool lets you see symbols in various RTEMS support file formats.
446 */
Note: See TracBrowser for help on using the repository browser.