Mercurial > hg-old > index.cgi

comparison doc/manual.docbook.sgml @ 150:f0881c115010

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More major documentation upgrades
author lost
date Fri, 30 Jan 2009 02:55:30 +0000
parents 6efe1e02043d
children 71561c12b20b
comparison
equal deleted inserted replaced
149:3706ede361ea 150:f0881c115010
167 <varlistentry> 167 <varlistentry>
168 <term><option>--obj</option></term> 168 <term><option>--obj</option></term>
169 <listitem> 169 <listitem>
170 <para> 170 <para>
171 Select the proprietary object file format as the output target. 171 Select the proprietary object file format as the output target.
172 </para>
173 </listitem>
174 </varlistentry>
175
176 <varlistentry>
177 <term><option>--output=FILE</option></term>
178 <term><option>-o FILE</option></term>
179 <listitem>
180 <para>
181 This option specifies the name of the output file. If not specified, the
182 default is <option>a.out</option>.
172 </para> 183 </para>
173 </listitem> 184 </listitem>
174 </varlistentry> 185 </varlistentry>
175 186
176 <varlistentry> 187 <varlistentry>
1038 </chapter> 1049 </chapter>
1039 1050
1040 <chapter> 1051 <chapter>
1041 <title>LWLINK</title> 1052 <title>LWLINK</title>
1042 <para> 1053 <para>
1043 </para> 1054 The LWTOOLS linker is called LWLINK. This chapter documents the various features
1055 of the linker.
1056 </para>
1057
1058 <section>
1059 <title>Command Line Options</title>
1060 <para>
1061 The binary for LWLINK is called "lwlink". Note that the binary is in lower
1062 case. lwlink takes the following command line arguments.
1063 </para>
1064 <variablelist>
1065 <varlistentry>
1066 <term><option>--decb</option></term>
1067 <term><option>-b</option></term>
1068 <listitem>
1069 <para>
1070 Selects the DECB output format target. This is equivalent to <option>--format=decb</option>
1071 </para>
1072 </listitem>
1073 </varlistentry>
1074
1075 <varlistentry>
1076 <term><option>--output=FILE</option></term>
1077 <term><option>-o FILE</option></term>
1078 <listitem>
1079 <para>
1080 This option specifies the name of the output file. If not specified, the
1081 default is <option>a.out</option>.
1082 </para>
1083 </listitem>
1084 </varlistentry>
1085
1086 <varlistentry>
1087 <term><option>--format=TYPE</option></term>
1088 <term><option>-f TYPE</option></term>
1089 <listitem>
1090 <para>
1091 This option specifies the output format. Valid values are <option>decb</option>
1092 and <option>raw</option>
1093 </para>
1094 </listitem>
1095 </varlistentry>
1096
1097 <varlistentry>
1098 <term><option>--raw</option></term>
1099 <term><option>-r</option></term>
1100 <listitem>
1101 <para>
1102 This option specifies the raw output format.
1103 It is equivalent to <option>--format=raw</option>.
1104 and <option>raw</option>
1105 </para>
1106 </listitem>
1107 </varlistentry>
1108
1109 <varlistentry>
1110 <term><option>--script=FILE</option></term>
1111 <term><option>-s</option></term>
1112 <listitem>
1113 <para>
1114 This option allows specifying a linking script to override the linker's
1115 built in defaults.
1116 </para>
1117 </listitem>
1118 </varlistentry>
1119
1120 <varlistentry>
1121 <term><option>--debug</option></term>
1122 <term><option>-d</option></term>
1123 <listitem>
1124 <para>
1125 This option increases the debugging level. It is only useful for LWTOOLS
1126 developers.
1127 </para>
1128 </listitem>
1129 </varlistentry>
1130
1131 <varlistentry>
1132 <term><option>--help</option></term>
1133 <term><option>-?</option></term>
1134 <listitem>
1135 <para>
1136 This provides a listing of command line options and a brief description
1137 of each.
1138 </para>
1139 </listitem>
1140 </varlistentry>
1141
1142 <varlistentry>
1143 <term><option>--usage</option></term>
1144 <listitem>
1145 <para>
1146 This will display a usage summary.
1147 of each.
1148 </para>
1149 </listitem>
1150 </varlistentry>
1151
1152
1153 <varlistentry>
1154 <term><option>--version</option></term>
1155 <term><option>-V</option></term>
1156 <listitem>
1157 <para>
1158 This will display the version of LWLINK.
1159 of each.
1160 </para>
1161 </listitem>
1162 </varlistentry>
1163
1164 </section>
1165
1166 <section>
1167 <title>Linker Operation</title>
1168
1169 <para>
1170 LWLINK takes one or more files in the LWTOOLS object file format and links
1171 them into a single binary. While the precise method is slightly different,
1172 linking can be conceptualized as the following steps.
1173 </para>
1174
1175 <orderedlist>
1176 <listitem>
1177 <para>
1178 First, the linker loads a linking script. If no script is specified, it
1179 loads a built-in default script based on the output format selected. This
1180 script tells the linker how to lay out the various sections in the final
1181 binary.
1182 </para>
1183 </listitem>
1184
1185 <listitem>
1186 <para>
1187 Next, the linker reads all the input files into memory. At this time, it
1188 flags any format errors in those files. It constructs a table of symbols
1189 for each object at this time.
1190 </para>
1191 </listitem>
1192
1193 <listitem>
1194 <para>
1195 The linker then proceeds with organizing the sections loaded from each file
1196 according to the linking script. As it does so, it is able to assign addresses
1197 to each symbol defined in each object file. At this time, the linker may
1198 also collapse different instances of the same section name into a single
1199 section by appending the data from each subsequent instance of the section
1200 to the first instance of the section.
1201 </para>
1202 </listitem>
1203
1204 <listitem>
1205 <para>
1206 Next, the linker looks through every object file for every incomplete reference.
1207 It then attempts to fully resolve that reference. If it cannot do so, it
1208 throws an error. Once a reference is resolved, the value is placed into
1209 the binary code at the specified section. It should be noted that an
1210 incomplete reference can reference either a symbol internal to the object
1211 file or an external symbol which is in the export list of another object
1212 file.
1213 </para>
1214 </listitem>
1215
1216 <listitem>
1217 <para>
1218 If all of the above steps are successful, the linker opens the output file
1219 and actually constructs the binary.
1220 </para>
1221 </listitem>
1222 </orderedlist>
1223
1224 </section>
1225
1226 <section
1227 <title>Linking Scripts</title>
1228 <para>
1229 A linker script is used to instruct the linker about how to assemble the
1230 various sections into a completed binary. It consists of a series of
1231 directives which are considered in the order they are encountered.
1232 </para>
1233 <para>
1234 The sections will appear in the resulting binary in the order they are
1235 specified in the script file. If a referenced section is not found, the linker will behave as though the
1236 section did exist but had a zero size, no relocations, and no exports.
1237 A section should only be referenced once. Any subsequent references will have
1238 an undefined effect.
1239 </para>
1240
1241 <para>
1242 All numbers are in linking scripts are specified in hexadecimal. All directives
1243 are case sensitive although the hexadecimal numbers are not.
1244 </para>
1245
1246 <para>A section name can be specified as a "*", then any section not
1247 already matched by the script will be matched. The "*" can be followed
1248 by a comma and a flag to narrow the section down slightly, also.
1249 If the flag is "!bss", then any section that is not flagged as a bss section
1250 will be matched. If the flag is "bss", then any section that is flagged as
1251 bss will be matched.
1252 </para>
1253
1254 <para>The following directives are understood in a linker script.</para>
1255 <variablelist>
1256 <varlistentry>
1257 <term>section <parameter>name</parameter> load <parameter>addr</parameter></term>
1258 <listitem><para>
1259
1260 This causes the section <parameter>name</parameter> to load at
1261 <parameter>addr</parameter>. For the raw target, only one "load at" entry is
1262 allowed for non-bss sections and it must be the first one. For raw targets,
1263 it affects the addresses the linker assigns to symbols but has no other
1264 affect on the output. bss sections may all have separate load addresses but
1265 since they will not appear in the binary anyway, this is okay.
1266 </para><para>
1267 For the decb target, each "load" entry will cause a new "block" to be
1268 output to the binary which will contain the load address. It is legal for
1269 sections to overlap in this manner - the linker assumes the loader will sort
1270 everything out.
1271 </para></listitem>
1272 </varlistentry>
1273
1274 <varlistentry>
1275 <term>section <parameter>name</parameter></term>
1276 <listitem><para>
1277
1278 This will cause the section <parameter>name</parameter> to load after the previously listed
1279 section.
1280 </para></listitem></varlistentry>
1281 <varlistentry>
1282 <term>exec <parameter>addr or sym</parameter></term>
1283 <listitem>
1284 <para>
1285 This will cause the execution address (entry point) to be the address
1286 specified (in hex) or the specified symbol name. The symbol name must
1287 match a symbol that is exported by one of the object files being linked.
1288 This has no effect for targets that do not encode the entry point into the
1289 resulting file. If not specified, the entry point is assumed to be address 0
1290 which is probably not what you want. The default link scripts for targets
1291 that support this directive automatically starts at the beginning of the
1292 first section (usually "init" or "code") that is emitted in the binary.
1293 </para>
1294 </listitem>
1295 </varlistentry>
1296
1297 <varlistentry>
1298 <term>pad <parameter>size</parameter></term>
1299 <listitem><para>
1300 This will cause the output file to be padded with NUL bytes to be exactly
1301 <parameter>size</parameter> bytes in length. This only makes sense for a raw target.
1302 </para>
1303 </listitem>
1304 </varlistentry>
1305 </variablelist>
1306
1307
1308
1309 </section>
1310
1044 </chapter> 1311 </chapter>
1045 1312
1046 <chapter id="objchap"> 1313 <chapter id="objchap">
1047 <title>Object Files</title> 1314 <title>Object Files</title>
1048 <para> 1315 <para>
1049 LWTOOLS uses a proprietary object file format. It is proprietary in the sense 1316 LWTOOLS uses a proprietary object file format. It is proprietary in the sense
1050 that it is specific to LWTOOLS, not that it is a hidden format. It would be 1317 that it is specific to LWTOOLS, not that it is a hidden format. It would be
1051 hard to keep it hidden in an open source tool chain anyway. This chapter 1318 hard to keep it hidden in an open source tool chain anyway. This chapter
1052 documents the object file format. 1319 documents the object file format.
1053 </para> 1320 </para>
1321
1322 <para>
1323 An object file consists of a series of sections each of which contains a
1324 list of exported symbols, a list of incomplete references, and a list of
1325 "local" symbols which may be used in calculating incomplete references. Each
1326 section will obviously also contain the object code.
1327 </para>
1328
1329 <para>
1330 Exported symbols must be completely resolved to an address within the
1331 section it is exported from. That is, an exported symbol must be a constant
1332 rather than defined in terms of other symbols.</para>
1333
1334 <para>
1335 Each object file starts with a magic number and version number. The magic
1336 number is the string "LWOBJ16" for this 16 bit object file format. The only
1337 defined version number is currently 0. Thus, the first 8 bytes of the object
1338 file are <code>4C574F424A313600</code>
1339 </para>
1340
1341 <para>
1342 Each section has the following items in order:
1343 </para>
1344
1345 <itemizedlist>
1346 <listitem><para>section name</para></listitem>
1347 <listitem><para>flags</para></listitem>
1348 <listitem><para>list of local symbols (and addresses within the section)</para></listitem>
1349 <listitem><para>list of exported symbols (and addresses within the section)</para></listitem>
1350 <listitem><para>list of incomplete references along with the expressions to calculate them</para></listitem>
1351 <listitem><para>the actual object code (for non-BSS sections)</para></listitem>
1352 </itemizedlist>
1353
1354 <para>
1355 The section starts with the name of the section with a NUL termination
1356 followed by a series of flag bytes terminated by NUL. There are only two
1357 flag bytes defined. A NUL (0) indicates no more flags and a value of 1
1358 indicates the section is a BSS section. For a BSS section, no actual
1359 code is included in the object file.
1360 </para>
1361
1362 <para>
1363 Either a NULL section name or end of file indicate the presence of no more
1364 sections.
1365 </para>
1366
1367 <para>
1368 Each entry in the exported and local symbols table consists of the symbol
1369 (NUL terminated) followed by two bytes which contain the value in big endian
1370 order. The end of a symbol table is indicated by a NULL symbol name.
1371 </para>
1372
1373 <para>
1374 Each entry in the incomplete references table consists of an expression
1375 followed by a 16 bit offset where the reference goes. Expressions are
1376 defined as a series of terms up to an "end of expression" term. Each term
1377 consists of a single byte which identifies the type of term (see below)
1378 followed by any data required by the term. Then end of the list is flagged
1379 by a NULL expression (only an end of expression term).
1380 </para>
1381
1382 <table frame="all"><title>Object File Term Types</title>
1383 <tgroup cols="2">
1384 <thead>
1385 <row>
1386 <entry>TERMTYPE</entry>
1387 <entry>Meaning</entry>
1388 </row>
1389 </thead>
1390 <tbody>
1391 <row>
1392 <entry>00</entry>
1393 <entry>end of expression</entry>
1394 </row>
1395
1396 <row>
1397 <entry>01</entry>
1398 <entry>integer (16 bit in big endian order follows)</entry>
1399 </row>
1400 <row>
1401 <entry>02</entry>
1402 <entry> external symbol reference (NUL terminated symbol name follows)</entry>
1403 </row>
1404
1405 <row>
1406 <entry>03</entry>
1407 <entry>local symbol reference (NUL terminated symbol name follows)</entry>
1408 </row>
1409
1410 <row>
1411 <entry>04</entry>
1412 <entry>operator (1 byte operator number)</entry>
1413 </row>
1414 <row>
1415 <entry>05</entry>
1416 <entry>section base address reference</entry>
1417 </row>
1418 </tbody>
1419 </tgroup>
1420 </table>
1421
1422 <para>
1423 External references are resolved using other object files while local
1424 references are resolved using the local symbol table(s) from this file. This
1425 allows local symbols that are not exported to have the same names as
1426 exported symbols or external references.
1427 </para>
1428
1429 <table frame="all"><title>Object File Operator Numbers</title>
1430 <tgroup cols="2">
1431 <thead>
1432 <row>
1433 <entry>Number</entry>
1434 <entry>Operator</entry>
1435 </row>
1436 </thead>
1437 <tbody>
1438 <row>
1439 <entry>01</entry>
1440 <entry>addition (+)</entry>
1441 </row>
1442 <row>
1443 <entry>02</entry>
1444 <entry>subtraction (-)</entry>
1445 </row>
1446 <row>
1447 <entry>03</entry>
1448 <entry>multiplication (*)</entry>
1449 </row>
1450 <row>
1451 <entry>04</entry>
1452 <entry>division (/)</entry>
1453 </row>
1454 <row>
1455 <entry>05</entry>
1456 <entry>modulus (%)</entry>
1457 </row>
1458 <row>
1459 <entry>06</entry>
1460 <entry>integer division (\) (same as division)</entry>
1461 </row>
1462
1463 <row>
1464 <entry>07</entry>
1465 <entry>bitwise and</entry>
1466 </row>
1467
1468 <row>
1469 <entry>08</entry>
1470 <entry>bitwise or</entry>
1471 </row>
1472
1473 <row>
1474 <entry>09</entry>
1475 <entry>bitwise xor</entry>
1476 </row>
1477
1478 <row>
1479 <entry>0A</entry>
1480 <entry>boolean and</entry>
1481 </row>
1482
1483 <row>
1484 <entry>0B</entry>
1485 <entry>boolean or</entry>
1486 </row>
1487
1488 <row>
1489 <entry>0C</entry>
1490 <entry>unary negation, 2's complement (-)</entry>
1491 </row>
1492
1493 <row>
1494 <entry>0D</entry>
1495 <entry>unary 1's complement (^)</entry>
1496 </row>
1497 </tbody>
1498 </tgroup>
1499 </table>
1500
1501 <para>
1502 An expression is represented in a postfix manner with both operands for
1503 binary operators preceding the operator and the single operand for unary
1504 operators preceding the operator.
1505 </para>
1506
1054 </chapter> 1507 </chapter>
1055 </book> 1508 </book>
1056 1509