Mercurial > hg-old > index.cgi

comparison doc/manual.docbook.sgml @ 237:dca5938a64aa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated documentation to reflect recent udates to LWASM
author lost
date Fri, 14 Aug 2009 04:20:15 +0000
parents aa0056ca7319
children b43e3e23583c
comparison
equal deleted inserted replaced
236:a58f49a77441 237:dca5938a64aa
90 Both LWASM and LWLINK can output this format. 90 Both LWASM and LWLINK can output this format.
91 </para> 91 </para>
92 </section> 92 </section>
93 93
94 <section> 94 <section>
95 <title>OS9 Modules</title>
96 <para>
97
98 Since version 2.5, LWASM is able to generate OS9 modules. The syntax is
99 basically the same as for other assemblers. A module starts with the MOD
100 directive and ends with the EMOD directive. The OS9 directive is provided
101 as a shortcut for writing system calls.
102
103 </para>
104
105 <para>
106
107 LWASM does NOT provide an OS9Defs file. You must provide your own. Also note
108 that the common practice of using "ifp1" around the inclusion of the OS9Defs
109 file is discouraged as it is pointless and can lead to unintentional
110 problems and phasing errors. Because LWASM reads each file exactly once,
111 there is no benefit to restricting the inclusion to the first assembly pass.
112
113 </para>
114
115 <para>
116
117 LWLINK does not, yet, have the ability to create OS9 modules from object
118 files.
119
120 </para>
121 </section>
122
123 <section>
95 <title>Object Files</title> 124 <title>Object Files</title>
96 <para>LWASM supports generating a proprietary object file format which is 125 <para>LWASM supports generating a proprietary object file format which is
97 described in <xref linkend="objchap">. LWLINK is then used to link these 126 described in <xref linkend="objchap">. LWLINK is then used to link these
98 object files into a final binary in any of LWLINK's supported binary 127 object files into a final binary in any of LWLINK's supported binary
99 formats.</para> 128 formats.</para>
182 <varlistentry> 211 <varlistentry>
183 <term><option>--format=type</option></term> 212 <term><option>--format=type</option></term>
184 <term><option>-f type</option></term> 213 <term><option>-f type</option></term>
185 <listitem> 214 <listitem>
186 <para> 215 <para>
187 Select the output format. Valid values are <option>obj</option> for the object 216 Select the output format. Valid values are <option>obj</option> for the
188 file target, <option>decb</option> for the DECB LOADM format, and <option>raw</option> 217 object file target, <option>decb</option> for the DECB LOADM format,
189 for a raw binary. 218 <option>os9</option> for creating OS9 modules, and <option>raw</option> for
219 a raw binary.
190 </para> 220 </para>
191 </listitem> 221 </listitem>
192 </varlistentry> 222 </varlistentry>
193 223
194 <varlistentry> 224 <varlistentry>
379 each included file gets its own local symbol scope. A blank line will also 409 each included file gets its own local symbol scope. A blank line will also
380 be considered a local scope barrier. Macros each have their own local symbol 410 be considered a local scope barrier. Macros each have their own local symbol
381 scope as well (which has a side effect that you cannot use a local symbol 411 scope as well (which has a side effect that you cannot use a local symbol
382 as an argument to a macro). There are other factors as well. In general, 412 as an argument to a macro). There are other factors as well. In general,
383 a local symbol is restricted to the block of code it is defined within. 413 a local symbol is restricted to the block of code it is defined within.
414 </para>
415
416 <para>
417 By default, unless assembling to the os9 target, a "$" in the symbol will
418 also make it local. This can be controlled by the "dollarlocal" and
419 "nodollarlocal" pragmas. In the absence of a pragma to the contrary, For
420 the os9 target, a "$" in the symbol will not make it considered local while
421 for all other targets it will.
384 </para> 422 </para>
385 423
386 </section> 424 </section>
387 425
388 <section> 426 <section>
790 828
791 </variablelist> 829 </variablelist>
792 </section> 830 </section>
793 831
794 <section> 832 <section>
833 <title>OS9 Target Directives</title>
834
835 <para>This section includes directives that apply solely to the OS9
836 target.</para>
837
838 <variablelist>
839
840 <varlistentry>
841 <term>OS9 <parameter>syscall</parameter></term>
842 <listitem>
843 <para>
844
845 This directive generates a call to the specified system call. <parameter>syscall</parameter> may be an arbitrary expression.
846
847 </para>
848 </listitem>
849 </varlistentry>
850
851 <varlistentry>
852 <term>MOD <parameter>size</parameter>,<parameter>name</parameter>,<parameter>type</parameter>,<parameter>flags</parameter>,<parameter>execoff</parameter>,<parameter>datasize</parameter></term>
853 <listitem>
854 <para>
855
856 This tells LWASM that the beginning of the actual module is here. It will
857 generate a module header based on the parameters specified. It will also
858 begin calcuating the module CRC.
859
860 </para>
861
862 <para>
863
864 The precise meaning of the various parameters is beyond the scope of this
865 document since it is not a tutorial on OS9 module programming.
866
867 </para>
868
869 </listitem>
870 </varlistentry>
871
872 <varlistentry>
873 <term>EMOD</term>
874 <listitem>
875 <para>
876
877 This marks the end of a module and causes LWASM to emit the calculated CRC
878 for the module.
879
880 </para>
881 </varlistentry>
882
883 </variablelist>
884 </section>
885
886 <section>
795 <title>Miscelaneous Directives</title> 887 <title>Miscelaneous Directives</title>
796 888
797 <para>This section includes directives that do not fit into the other 889 <para>This section includes directives that do not fit into the other
798 categories.</para> 890 categories.</para>
799 891
800 <variablelist> 892 <variablelist>
801 893
802 <varlistentry> 894 <varlistentry>
803 <term>INCLUDE <parameter>filename</parameter></term> 895 <term>INCLUDE <parameter>filename</parameter></term>
804 <listitem> 896 <term>USE <parameter>filename</parameter></term>
805 <para> 897
806 Include the contents of <parameter>filename</parameter> at this point in 898 <listitem> <para> Include the contents of <parameter>filename</parameter> at
807 the assembly as though it were a part of the file currently being processed. 899 this point in the assembly as though it were a part of the file currently
808 Note that whitespace cannot appear in the name of the file. 900 being processed. Note that if whitespace appears in the name of the file,
809 </para> 901 you must enclose <parameter>filename</parameter> in quotes.
902 </para>
903
904 <para>
905 Note that the USE variation is provided only for compatibility with other
906 assemblers. It is recommended to use the INCLUDE variation.</para>
907
810 </listitem> 908 </listitem>
811 </varlistentry> 909 </varlistentry>
812 910
813 <varlistentry> 911 <varlistentry>
814 <term>END <parameter>[expr]</parameter></term> 912 <term>END <parameter>[expr]</parameter></term>
1215 However, depending on the specific dynamics of the project, it may be sufficient 1313 However, depending on the specific dynamics of the project, it may be sufficient
1216 for one or two files to use this pragma internally. 1314 for one or two files to use this pragma internally.
1217 </para> 1315 </para>
1218 </listitem> 1316 </listitem>
1219 </varlistentry> 1317 </varlistentry>
1318
1319 <varlistentry>
1320 <term>dollarlocal</term>
1321 <listitem>
1322
1323 <para>When set, a "$" in a symbol makes it local. When not set, "$" does not
1324 cause a symbol to be local. It is set by default except when using the OS9
1325 target.</para>
1326
1327 </listitem>
1328 </varlistentry>
1329
1330 <varlistentry>
1331 <term>dollarnotlocal</term>
1332 <listitem>
1333
1334 <para> This is the same as the "dollarlocal" pragma except its sense is
1335 reversed. That is, "dollarlocal" and "nodollarnotlocal" are equivalent and
1336 "nodollarlocal" and "dollarnotlocal" are equivalent. </para>
1337
1338 </listitem>
1339 </varlistentry>
1340
1220 </variablelist> 1341 </variablelist>
1221 1342
1222 </section> 1343 </section>
1223 1344
1224 </chapter> 1345 </chapter>