Mercurial > hg-old > index.cgi

comparison doc/manual.docbook.sgml @ 256:6e2d03188d24 2.x

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated manual to reflect updates for 2.6 release
author lost
date Tue, 22 Dec 2009 04:52:59 +0000
parents b43e3e23583c
children
comparison
equal deleted inserted replaced
255:6363b9ebf825 256:6e2d03188d24
284 </para> 284 </para>
285 </listitem> 285 </listitem>
286 </varlistentry> 286 </varlistentry>
287 287
288 <varlistentry> 288 <varlistentry>
289 <term><option>--includedir=path</option></term>
290 <term><option>-I path</option></term>
291 <listitem>
292 <para>
293 Add <option>path</option> to the end of the include path.
294 </para>
295 </listitem>
296 </varlistentry>
297
298 <varlistentry>
289 <term><option>--help</option></term> 299 <term><option>--help</option></term>
290 <term><option>-?</option></term> 300 <term><option>-?</option></term>
291 <listitem> 301 <listitem>
292 <para> 302 <para>
293 Present a help screen describing the command line options. 303 Present a help screen describing the command line options.
395 <para> 405 <para>
396 The opcode is not treated case sensitively. Neither are register names in 406 The opcode is not treated case sensitively. Neither are register names in
397 the operand fields. Symbols, however, are case sensitive. 407 the operand fields. Symbols, however, are case sensitive.
398 </para> 408 </para>
399 409
400 <para> 410 <para> As of version 2.6, LWASM supports files with line numbers. If line
401 LWASM does not support line numbers in the file. 411 numbers are present, the line must start with a digit. The line number
412 itself must consist only of digits. The line number must then be followed
413 by either the end of the line or exactly one white space character. After
414 that white space character, the lines are interpreted exactly as above.
402 </para> 415 </para>
403 416
404 </section> 417 </section>
405 418
406 <section> 419 <section>
637 Treat the contents of <parameter>filename</parameter> as a string of bytes to 650 Treat the contents of <parameter>filename</parameter> as a string of bytes to
638 be included literally at the current assembly point. This has the same effect 651 be included literally at the current assembly point. This has the same effect
639 as converting the file contents to a series of FCB statements and including 652 as converting the file contents to a series of FCB statements and including
640 those at the current assembly point. 653 those at the current assembly point.
641 </para> 654 </para>
655
656 <para> If <parameter>filename</parameter> beings with a /, the file name
657 will be taken as absolute. Otherwise, the current directory will be
658 searched followed by the search path in the order specified.</para>
659
660 <para> Please note that absolute path detection including drive letters will
661 not function correctly on Windows platforms. Non-absolute inclusion will
662 work, however.</para>
663
642 </listitem> 664 </listitem>
643 </varlistentry> 665 </varlistentry>
644 666
645 </variablelist> 667 </variablelist>
646 668
1035 This directive indicates the end of the macro currently being defined. It 1057 This directive indicates the end of the macro currently being defined. It
1036 causes the assembler to resume interpreting source lines as normal. 1058 causes the assembler to resume interpreting source lines as normal.
1037 </para> 1059 </para>
1038 </listitem> 1060 </listitem>
1039 </variablelist> 1061 </variablelist>
1062
1063 </section>
1064
1065 <section>
1066 <title>Structures</title>
1067 <para>
1068
1069 Structures are used to group related data in a fixed structure. A structure
1070 consists a number of fields, defined in sequential order and which take up
1071 specified size. The assembler does not enforce any means of access within a
1072 structure; it assumes that whatever you are doing, you intended to do.
1073 There are two pseudo ops that are used for defining structures.
1074
1075 </para>
1076
1077 <variablelist>
1078 <varlistentry>
1079 <term><parameter>structname</parameter> STRUCT</term>
1080 <listitem>
1081 <para>
1082
1083 This directive is used to begin the definition of a structure with name
1084 <parameter>structname</parameter>. Subsequent statements all form part of
1085 the structure definition until the end of the structure is declared.
1086
1087 </para>
1088 </listitem>
1089 </varlistentry>
1090 <varlistentry>
1091 <term>ENDSTRUCT</term>
1092 <listitem>
1093 <para>
1094 This directive ends the definition of the structure.
1095 </para>
1096 </listitem>
1097 </varlistentry>
1098 </variablelist>
1099
1100 <para>
1101
1102 Within a structure definition, only reservation pseudo ops are permitted.
1103 Anything else will cause an assembly error.
1104 </para>
1105
1106 <para> Once a structure is defined, you can reserve an area of memory in the
1107 same structure by using the structure name as the opcode. Structures can
1108 also contain fields that are themselves structures. See the example
1109 below.</para>
1110
1111 <programlisting>
1112 tstruct2 STRUCT
1113 f1 rmb 1
1114 f2 rmb 1
1115 ENDSTRUCT
1116
1117 tstruct STRUCT
1118 field1 rmb 2
1119 field2 rmb 3
1120 field3 tstruct2
1121 ENDSTRUCT
1122
1123 ORG $2000
1124 var1 tstruct
1125 var2 tstruct2
1126 </programlisting>
1127
1128 <para>Fields are referenced using a dot (.) as a separator. To refer to the
1129 generic offset within a structure, use the structure name to the left of the
1130 dot. If referring to a field within an actual variable, use the variable's
1131 symbol name to the left of the dot.</para>
1132
1133 <para>You can also refer to the actual size of a structure (or a variable
1134 declared as a structure) using the special symbol sizeof{structname} where
1135 structname will be the name of the structure or the name of the
1136 variable.</para>
1137
1138 <para>Essentially, structures are a shortcut for defining a vast number of
1139 symbols. When a structure is defined, the assembler creates symbols for the
1140 various fields in the form structname.fieldname as well as the appropriate
1141 sizeof{structname} symbol. When a variable is declared as a structure, the
1142 assembler does the same thing using the name of the variable. You will see
1143 these symbols in the symbol table when the assembler is instructed to
1144 provide a listing. For instance, the above listing will create the
1145 following symbols (symbol values in parentheses): tstruct2.f1 (0),
1146 tstruct2.f2 (1), sizeof{tstruct2} (2), tstruct.field1 (0), tstruct.field2
1147 (2), tstruct.field3 (5), tstruct.field3.f1 (5), tstruct.field3.f2 (6),
1148 sizeof{tstruct.field3} (2), sizeof{tstruct} (7), var1 {$2000}, var1.field1
1149 {$2000}, var1.field2 {$2002}, var1.field3 {$2005}, var1.field3.f1 {$2005},
1150 var1.field3.f2 {$2006}, sizeof(var1.field3} (2), sizeof{var1} (7), var2
1151 ($2007), var2.f1 ($2007), var2.f2 ($2008), sizeof{var2} (2). </para>
1040 1152
1041 </section> 1153 </section>
1042 1154
1043 <section> 1155 <section>
1044 <title>Object Files and Sections</title> 1156 <title>Object Files and Sections</title>
1198 Note that <parameter>sym</parameter> may appear as the operand or as the 1310 Note that <parameter>sym</parameter> may appear as the operand or as the
1199 statement's symbol. If there is a symbol on the statement, that will 1311 statement's symbol. If there is a symbol on the statement, that will
1200 take precedence over any operand that is present. 1312 take precedence over any operand that is present.
1201 </para> 1313 </para>
1202 </listitem> 1314 </listitem>
1203 </varlistentry> 1315
1204 1316 </varlistentry>
1317
1318 <varlistentry>
1319 <term><parameter>sym</parameter>EXTDEP</term>
1320 <listitem>
1321
1322 <para>This directive forces an external dependency on
1323 <parameter>sym</parameter>, even if it is never referenced anywhere else in
1324 this file.</para>
1325
1326 </listitem>
1327 </varlistentry>
1205 </variablelist> 1328 </variablelist>
1206 1329
1207 </section> 1330 </section>
1208 1331
1209 <section> 1332 <section>
1886 <entry>section base address reference</entry> 2009 <entry>section base address reference</entry>
1887 </row> 2010 </row>
1888 2011
1889 <row> 2012 <row>
1890 <entry>FF</entry> 2013 <entry>FF</entry>
1891 <entry>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. There is currently only one flag defined. Flag 01 indicates an 8 bit relocation.</entry> 2014 <entry>This term will set flags for the expression. Each one of these terms will set a single flag. All of them should be specified first in an expression. If they are not, the behaviour is undefined. The byte following is the flag. Flag 01 indicates an 8 bit relocation. Flag 02 indicates a zero-width relocation (see the EXTDEP pseudo op in LWASM).</entry>
1892 </row> 2015 </row>
1893 </tbody> 2016 </tbody>
1894 </tgroup> 2017 </tgroup>
1895 </table> 2018 </table>
1896 2019