doc/README.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
   7 <title>Bold - The Byte Optimized Linker</title>
   8 <meta name="author" content="Amand Tihon" />
   9 <meta name="date" content="Aug 15, 2009" />
  10 <meta name="copyright" content="GNU GPL version 3 + Exception, see copyright file." />
  11 <style type="text/css">
  12
  13 /*
  14 :Author: David Goodger (goodger@python.org)
  15 :Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
  16 :Copyright: This stylesheet has been placed in the public domain.
  17
  18 Default cascading style sheet for the HTML output of Docutils.
  19
  20 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
  21 customize this style sheet.
  22 */
  23
  24 /* used to remove borders from tables and images */
  25 .borderless, table.borderless td, table.borderless th {
  26   border: 0 }
  27
  28 table.borderless td, table.borderless th {
  29   /* Override padding for "table.docutils td" with "! important".
  30      The right padding separates the table cells. */
  31   padding: 0 0.5em 0 0 ! important }
  32
  33 .first {
  34   /* Override more specific margin styles with "! important". */
  35   margin-top: 0 ! important }
  36
  37 .last, .with-subtitle {
  38   margin-bottom: 0 ! important }
  39
  40 .hidden {
  41   display: none }
  42
  43 a.toc-backref {
  44   text-decoration: none ;
  45   color: black }
  46
  47 blockquote.epigraph {
  48   margin: 2em 5em ; }
  49
  50 dl.docutils dd {
  51   margin-bottom: 0.5em }
  52
  53 /* Uncomment (and remove this text!) to get bold-faced definition list terms
  54 dl.docutils dt {
  55   font-weight: bold }
  56 */
  57
  58 div.abstract {
  59   margin: 2em 5em }
  60
  61 div.abstract p.topic-title {
  62   font-weight: bold ;
  63   text-align: center }
  64
  65 div.admonition, div.attention, div.caution, div.danger, div.error,
  66 div.hint, div.important, div.note, div.tip, div.warning {
  67   margin: 2em ;
  68   border: medium outset ;
  69   padding: 1em }
  70
  71 div.admonition p.admonition-title, div.hint p.admonition-title,
  72 div.important p.admonition-title, div.note p.admonition-title,
  73 div.tip p.admonition-title {
  74   font-weight: bold ;
  75   font-family: sans-serif }
  76
  77 div.attention p.admonition-title, div.caution p.admonition-title,
  78 div.danger p.admonition-title, div.error p.admonition-title,
  79 div.warning p.admonition-title {
  80   color: red ;
  81   font-weight: bold ;
  82   font-family: sans-serif }
  83
  84 /* Uncomment (and remove this text!) to get reduced vertical space in
  85    compound paragraphs.
  86 div.compound .compound-first, div.compound .compound-middle {
  87   margin-bottom: 0.5em }
  88
  89 div.compound .compound-last, div.compound .compound-middle {
  90   margin-top: 0.5em }
  91 */
  92
  93 div.dedication {
  94   margin: 2em 5em ;
  95   text-align: center ;
  96   font-style: italic }
  97
  98 div.dedication p.topic-title {
  99   font-weight: bold ;
 100   font-style: normal }
 101
 102 div.figure {
 103   margin-left: 2em ;
 104   margin-right: 2em }
 105
 106 div.footer, div.header {
 107   clear: both;
 108   font-size: smaller }
 109
 110 div.line-block {
 111   display: block ;
 112   margin-top: 1em ;
 113   margin-bottom: 1em }
 114
 115 div.line-block div.line-block {
 116   margin-top: 0 ;
 117   margin-bottom: 0 ;
 118   margin-left: 1.5em }
 119
 120 div.sidebar {
 121   margin: 0 0 0.5em 1em ;
 122   border: medium outset ;
 123   padding: 1em ;
 124   background-color: #ffffee ;
 125   width: 40% ;
 126   float: right ;
 127   clear: right }
 128
 129 div.sidebar p.rubric {
 130   font-family: sans-serif ;
 131   font-size: medium }
 132
 133 div.system-messages {
 134   margin: 5em }
 135
 136 div.system-messages h1 {
 137   color: red }
 138
 139 div.system-message {
 140   border: medium outset ;
 141   padding: 1em }
 142
 143 div.system-message p.system-message-title {
 144   color: red ;
 145   font-weight: bold }
 146
 147 div.topic {
 148   margin: 2em }
 149
 150 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
 151 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
 152   margin-top: 0.4em }
 153
 154 h1.title {
 155   text-align: center }
 156
 157 h2.subtitle {
 158   text-align: center }
 159
 160 hr.docutils {
 161   width: 75% }
 162
 163 img.align-left {
 164   clear: left }
 165
 166 img.align-right {
 167   clear: right }
 168
 169 ol.simple, ul.simple {
 170   margin-bottom: 1em }
 171
 172 ol.arabic {
 173   list-style: decimal }
 174
 175 ol.loweralpha {
 176   list-style: lower-alpha }
 177
 178 ol.upperalpha {
 179   list-style: upper-alpha }
 180
 181 ol.lowerroman {
 182   list-style: lower-roman }
 183
 184 ol.upperroman {
 185   list-style: upper-roman }
 186
 187 p.attribution {
 188   text-align: right ;
 189   margin-left: 50% }
 190
 191 p.caption {
 192   font-style: italic }
 193
 194 p.credits {
 195   font-style: italic ;
 196   font-size: smaller }
 197
 198 p.label {
 199   white-space: nowrap }
 200
 201 p.rubric {
 202   font-weight: bold ;
 203   font-size: larger ;
 204   color: maroon ;
 205   text-align: center }
 206
 207 p.sidebar-title {
 208   font-family: sans-serif ;
 209   font-weight: bold ;
 210   font-size: larger }
 211
 212 p.sidebar-subtitle {
 213   font-family: sans-serif ;
 214   font-weight: bold }
 215
 216 p.topic-title {
 217   font-weight: bold }
 218
 219 pre.address {
 220   margin-bottom: 0 ;
 221   margin-top: 0 ;
 222   font-family: serif ;
 223   font-size: 100% }
 224
 225 pre.literal-block, pre.doctest-block {
 226   margin-left: 2em ;
 227   margin-right: 2em }
 228
 229 span.classifier {
 230   font-family: sans-serif ;
 231   font-style: oblique }
 232
 233 span.classifier-delimiter {
 234   font-family: sans-serif ;
 235   font-weight: bold }
 236
 237 span.interpreted {
 238   font-family: sans-serif }
 239
 240 span.option {
 241   white-space: nowrap }
 242
 243 span.pre {
 244   white-space: pre }
 245
 246 span.problematic {
 247   color: red }
 248
 249 span.section-subtitle {
 250   /* font-size relative to parent (h1..h6 element) */
 251   font-size: 80% }
 252
 253 table.citation {
 254   border-left: solid 1px gray;
 255   margin-left: 1px }
 256
 257 table.docinfo {
 258   margin: 2em 4em }
 259
 260 table.docutils {
 261   margin-top: 0.5em ;
 262   margin-bottom: 0.5em }
 263
 264 table.footnote {
 265   border-left: solid 1px black;
 266   margin-left: 1px }
 267
 268 table.docutils td, table.docutils th,
 269 table.docinfo td, table.docinfo th {
 270   padding-left: 0.5em ;
 271   padding-right: 0.5em ;
 272   vertical-align: top }
 273
 274 table.docutils th.field-name, table.docinfo th.docinfo-name {
 275   font-weight: bold ;
 276   text-align: left ;
 277   white-space: nowrap ;
 278   padding-left: 0 }
 279
 280 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
 281 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
 282   font-size: 100% }
 283
 284 ul.auto-toc {
 285   list-style-type: none }
 286
 287 </style>
 288 </head>
 289 <body>
 290 <div class="document" id="bold-the-byte-optimized-linker">
 291 <h1 class="title">Bold - The Byte Optimized Linker</h1>
 292 <table class="docinfo" frame="void" rules="none">
 293 <col class="docinfo-name" />
 294 <col class="docinfo-content" />
 295 <tbody valign="top">
 296 <tr><th class="docinfo-name">Author:</th>
 297 <td>Amand Tihon</td></tr>
 298 <tr><th class="docinfo-name">Contact:</th>
 299 <td>&lt;<a class="reference external" href="mailto:amand.tihon&#64;alrj.org">amand.tihon&#64;alrj.org</a>&gt;</td></tr>
 300 <tr><th class="docinfo-name">Version:</th>
 301 <td>0.2.1</td></tr>
 302 <tr><th class="docinfo-name">Date:</th>
 303 <td>Aug 15, 2009</td></tr>
 304 <tr><th class="docinfo-name">Copyright:</th>
 305 <td>GNU GPL version 3 + Exception, see copyright file.</td></tr>
 306 </tbody>
 307 </table>
 308 <!-- HTML version generated with LC_ALL=C rst2html -t README > README.html -->
 309 <div class="contents topic" id="table-of-contents">
 310 <p class="topic-title first">Table of contents</p>
 311 <ul class="auto-toc simple">
 312 <li><a class="reference internal" href="#abstract" id="id1">1&nbsp;&nbsp;&nbsp;Abstract</a></li>
 313 <li><a class="reference internal" href="#rationale" id="id2">2&nbsp;&nbsp;&nbsp;Rationale</a></li>
 314 <li><a class="reference internal" href="#getting-bold" id="id3">3&nbsp;&nbsp;&nbsp;Getting Bold</a></li>
 315 <li><a class="reference internal" href="#requirements" id="id4">4&nbsp;&nbsp;&nbsp;Requirements</a></li>
 316 <li><a class="reference internal" href="#installation" id="id5">5&nbsp;&nbsp;&nbsp;Installation</a></li>
 317 <li><a class="reference internal" href="#using-bold" id="id6">6&nbsp;&nbsp;&nbsp;Using Bold</a><ul class="auto-toc">
 318 <li><a class="reference internal" href="#synopsys" id="id7">6.1&nbsp;&nbsp;&nbsp;Synopsys</a></li>
 319 <li><a class="reference internal" href="#description" id="id8">6.2&nbsp;&nbsp;&nbsp;Description</a></li>
 320 <li><a class="reference internal" href="#options" id="id9">6.3&nbsp;&nbsp;&nbsp;Options</a></li>
 321 <li><a class="reference internal" href="#notes" id="id10">6.4&nbsp;&nbsp;&nbsp;Notes</a></li>
 322 </ul>
 323 </li>
 324 <li><a class="reference internal" href="#internals" id="id11">7&nbsp;&nbsp;&nbsp;Internals</a><ul class="auto-toc">
 325 <li><a class="reference internal" href="#external-symbols-resolution" id="id12">7.1&nbsp;&nbsp;&nbsp;External symbols resolution</a></li>
 326 <li><a class="reference internal" href="#calling-from-c" id="id13">7.2&nbsp;&nbsp;&nbsp;Calling from C</a></li>
 327 <li><a class="reference internal" href="#aligning" id="id14">7.3&nbsp;&nbsp;&nbsp;Aligning</a></li>
 328 <li><a class="reference internal" href="#additional-trick-1-dt-debug" id="id15">7.4&nbsp;&nbsp;&nbsp;Additional Trick 1: DT_DEBUG</a></li>
 329 <li><a class="reference internal" href="#additional-trick-2-short-dynamic-table" id="id16">7.5&nbsp;&nbsp;&nbsp;Additional Trick 2: Short DYNAMIC table</a></li>
 330 </ul>
 331 </li>
 332 <li><a class="reference internal" href="#examples" id="id17">8&nbsp;&nbsp;&nbsp;Examples</a></li>
 333 </ul>
 334 </div>
 335 <div class="section" id="abstract">
 336 <h1>1&nbsp;&nbsp;&nbsp;Abstract</h1>
 337 <p>Bold is an ELF linker, currently only targetting x86_64 under Linux. Being
 338 limited in capabilities, it should not be considered as an all-purpose linker.</p>
 339 </div>
 340 <div class="section" id="rationale">
 341 <h1>2&nbsp;&nbsp;&nbsp;Rationale</h1>
 342 <p>Bold's main purpose is to generate very small executable programs.</p>
 343 <p>While <tt class="docutils literal"><span class="pre">ld</span></tt> from the GNU binutils can do almost anything anyone would ever
 344 need, some specific goals need an awful lot of tweaking, or can simply not be
 345 achieved. Bold uses several tricks to reduce the size of the final executable
 346 binary.</p>
 347 </div>
 348 <div class="section" id="getting-bold">
 349 <h1>3&nbsp;&nbsp;&nbsp;Getting Bold</h1>
 350 <p>You can download the tarball from <a class="reference external" href="http://www.alrj.org/projects/bold">http://www.alrj.org/projects/bold</a>
 351 or get the latest development version with the following git command:</p>
 352 <pre class="literal-block">
 353 git clone http://git.alrj.org/git/bold.git
 354 </pre>
 355 <p>A gitweb interface is also available at <a class="reference external" href="http://git.alrj.org/">http://git.alrj.org/</a></p>
 356 </div>
 357 <div class="section" id="requirements">
 358 <h1>4&nbsp;&nbsp;&nbsp;Requirements</h1>
 359 <p>Bold itself is entirely written in Python. There are no additionnal
 360 dependencies.</p>
 361 <p>The runtime library that contains the external symbols resolver is written
 362 in assembler (Intel syntax). An assembler like Nasm or Yasm is needed to
 363 recompile the source code into an object file.</p>
 364 </div>
 365 <div class="section" id="installation">
 366 <h1>5&nbsp;&nbsp;&nbsp;Installation</h1>
 367 <p>Go into Bold's directory, and run</p>
 368 <pre class="literal-block">
 369 python setup.py build
 370 </pre>
 371 <p>Then, as root or using sudo, run</p>
 372 <pre class="literal-block">
 373 python setup.py install
 374 </pre>
 375 </div>
 376 <div class="section" id="using-bold">
 377 <h1>6&nbsp;&nbsp;&nbsp;Using Bold</h1>
 378 <div class="section" id="synopsys">
 379 <h2>6.1&nbsp;&nbsp;&nbsp;Synopsys</h2>
 380 <blockquote>
 381 bold [options] objfile...</blockquote>
 382 </div>
 383 <div class="section" id="description">
 384 <h2>6.2&nbsp;&nbsp;&nbsp;Description</h2>
 385 <p>Bold combines a number of object files, relocate their data and resolves their
 386 symbols references, in order to generate executable binaries.</p>
 387 <p>Bold has only one, very specific purpose: making small executables.</p>
 388 </div>
 389 <div class="section" id="options">
 390 <h2>6.3&nbsp;&nbsp;&nbsp;Options</h2>
 391 <table class="docutils option-list" frame="void" rules="none">
 392 <col class="option" />
 393 <col class="description" />
 394 <tbody valign="top">
 395 <tr><td class="option-group">
 396 <kbd><span class="option">--version</span></kbd></td>
 397 <td>Show program's version and exit.</td></tr>
 398 <tr><td class="option-group">
 399 <kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
 400 <td>Show help message and exit.</td></tr>
 401 <tr><td class="option-group" colspan="2">
 402 <kbd><span class="option">-e <var>SYMBOL</var></span>, <span class="option">--entry=<var>SYMBOL</var></span></kbd></td>
 403 </tr>
 404 <tr><td>&nbsp;</td><td>Use SYMBOL as the explicit symbol for beginning execution of your program.
 405 If <tt class="docutils literal"><span class="pre">--raw</span></tt> is specified, it defaults to <tt class="docutils literal"><span class="pre">_start</span></tt>.</td></tr>
 406 <tr><td class="option-group" colspan="2">
 407 <kbd><span class="option">-l <var>LIBNAME</var></span>, <span class="option">--library=<var>LIBNAME</var></span></kbd></td>
 408 </tr>
 409 <tr><td>&nbsp;</td><td>Link against the shared library specified by LIBNAME. Bold relies on python's
 410 ctypes module to find the libraries. This option may be used any number of
 411 times.</td></tr>
 412 <tr><td class="option-group" colspan="2">
 413 <kbd><span class="option">-L <var>DIRECTORY</var></span>, <span class="option">--library-path=<var>DIRECTORY</var></span></kbd></td>
 414 </tr>
 415 <tr><td>&nbsp;</td><td>This option does nothing, and is present ony for compatibility reasons. It
 416 MAY get implemented in the future, though. This option may be used any number
 417 of times.</td></tr>
 418 <tr><td class="option-group" colspan="2">
 419 <kbd><span class="option">-o <var>FILE</var></span>, <span class="option">--output=<var>FILE</var></span></kbd></td>
 420 </tr>
 421 <tr><td>&nbsp;</td><td>Set the output file name (default value is a.out).</td></tr>
 422 <tr><td class="option-group">
 423 <kbd><span class="option">--raw</span></kbd></td>
 424 <td>Don't include the builtin external symbols resolution code. This is
 425 described in details further in this document.</td></tr>
 426 <tr><td class="option-group">
 427 <kbd><span class="option">-c</span>, <span class="option">--ccall</span></kbd></td>
 428 <td>Make external symbols directly callable by C, without having to declare the
 429 pointers on functions. This option adds 6 bytes for each externally defined
 430 function. This is described in details further in this document.</td></tr>
 431 <tr><td class="option-group">
 432 <kbd><span class="option">-a</span>, <span class="option">--align</span></kbd></td>
 433 <td>Align the wrappers for external symbols on an 8 byte boundary, to take
 434 advantage of the RIP-relative addressing. This is described in details
 435 further in this document.</td></tr>
 436 </tbody>
 437 </table>
 438 </div>
 439 <div class="section" id="notes">
 440 <h2>6.4&nbsp;&nbsp;&nbsp;Notes</h2>
 441 <p>The <tt class="docutils literal"><span class="pre">LD_PRELOAD</span></tt> environment variable may not always work (as expected or
 442 at all).</p>
 443 <p>The <tt class="docutils literal"><span class="pre">main()</span></tt> function is called without any argument. Its return code is used
 444 as exit code, though.</p>
 445 </div>
 446 </div>
 447 <div class="section" id="internals">
 448 <h1>7&nbsp;&nbsp;&nbsp;Internals</h1>
 449 <div class="section" id="external-symbols-resolution">
 450 <h2>7.1&nbsp;&nbsp;&nbsp;External symbols resolution</h2>
 451 <p>The &quot;import by hash&quot; method is from parapete, leblane, las, as described on
 452 <a class="reference external" href="http://www.pouet.net/topic.php?which=5392">http://www.pouet.net/topic.php?which=5392</a></p>
 453 </div>
 454 <div class="section" id="calling-from-c">
 455 <h2>7.2&nbsp;&nbsp;&nbsp;Calling from C</h2>
 456 <p>If you write your code in C and need to call the external symbols, you
 457 basically have two options. The first one is to redefine them (or define new
 458 ones) to call by pointers. For instance,</p>
 459 <pre class="literal-block">
 460 int SDL_Init(int);
 461 </pre>
 462 <p>would become:</p>
 463 <pre class="literal-block">
 464 int (*SDL_Init)(int);
 465 </pre>
 466 <p>Repeat it for all functions, or write a tool to automate it (hint: look at
 467 <a class="reference external" href="http://research.mercury-labs.org/ibh-i386-0.2.2.tar.gz">http://research.mercury-labs.org/ibh-i386-0.2.2.tar.gz</a> for help).</p>
 468 <p>There's a second possibility however, and it's the one used by Bold when you
 469 specify the <tt class="docutils literal"><span class="pre">--ccall</span></tt> option: make the resolved symbol point, not to the
 470 address of the function, but to a JMP instruction to the actual address:</p>
 471 <pre class="literal-block">
 472 global SDL_Init
 473
 474 .text
 475
 476 SDL_Init:          jmp [rel _bold__SDL_Init]
 477 SDL_SetVideoMode:  jmp [rel _bold__SDL_SetVideoMode]
 478
 479 .bss
 480
 481 _bold__SDL_Init          resq        ; Filled by the import by hash code
 482 _bold__SDL_SetVideoMode  resq
 483 </pre>
 484 <p>This approach takes 6 bytes (the JMP instruction) for each external function
 485 used.</p>
 486 </div>
 487 <div class="section" id="aligning">
 488 <h2>7.3&nbsp;&nbsp;&nbsp;Aligning</h2>
 489 <p>The x86_64 architecture has this nice thing called &quot;RIP-relative addressing&quot;.
 490 If all the JMP instructions are in the same order than the pointers to the
 491 functions they refer to, having them aligned with the pointers would result
 492 in identical instructions. This is done with the <tt class="docutils literal"><span class="pre">--align</span></tt> option.</p>
 493 <p>Adding two null bytes between each JMP enlarges the final executable by
 494 2 x (number of function - 1) bytes, and may seem to go against our goal.
 495 However, the result is a repetition of the <em>same eight bytes</em>, something that
 496 can improve compression a lot!</p>
 497 </div>
 498 <div class="section" id="additional-trick-1-dt-debug">
 499 <h2>7.4&nbsp;&nbsp;&nbsp;Additional Trick 1: DT_DEBUG</h2>
 500 <p>Bold declares a global symbol named <tt class="docutils literal"><span class="pre">_dt_debug</span></tt>, that points to the value of
 501 the <tt class="docutils literal"><span class="pre">DT_DEBUG</span></tt> entry of the <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table, for easy access. Just in case,
 502 the <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table can also be reached using the global <tt class="docutils literal"><span class="pre">_DYNAMIC</span></tt> symbol.</p>
 503 </div>
 504 <div class="section" id="additional-trick-2-short-dynamic-table">
 505 <h2>7.5&nbsp;&nbsp;&nbsp;Additional Trick 2: Short DYNAMIC table</h2>
 506 <p>Executables generated by <tt class="docutils literal"><span class="pre">ld</span></tt> usually have a lot of entries in their
 507 <tt class="docutils literal"><span class="pre">DYNAMIC</span></tt> table. Bold puts only the strict necessary:</p>
 508 <ul class="simple">
 509 <li>One <tt class="docutils literal"><span class="pre">DT_NEEDED</span></tt> entry for each shared library to load (obviously).</li>
 510 <li>A <tt class="docutils literal"><span class="pre">DT_SYMTAB</span></tt> entry, with null-pointer. Without this one, the interpreter
 511 wouldn't do its job.</li>
 512 <li>a <tt class="docutils literal"><span class="pre">DT_DEBUG</span></tt> entry, that will be used for symbol resolution.</li>
 513 </ul>
 514 <p>And that's it!</p>
 515 </div>
 516 </div>
 517 <div class="section" id="examples">
 518 <h1>8&nbsp;&nbsp;&nbsp;Examples</h1>
 519 <p>The <tt class="docutils literal"><span class="pre">examples/</span></tt> directory contains a port of the <em>flow2</em> intro
 520 (<a class="reference external" href="http://www.pouet.net/prod.php?which=30589">http://www.pouet.net/prod.php?which=30589</a>). Adding the dropper is left as an
 521 exercise for the reader.</p>
 522 </div>
 523 </div>
 524 <div class="footer">
 525 <hr class="footer" />
 526 Generated on: 2009-08-15 21:17 UTC.
 527
 528 </div>
 529 </body>
 530 </html>