Mercurial > hg > index.cgi

comparison docs/manual.docbook.sgml @ 152:a26b045c4e18

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added documentation about OS9 module support in lwlink
author lost@l-w.ca
date Sat, 27 Aug 2011 00:21:35 -0600
parents 42a7a16a058f
children 1e0a0e6cd918
comparison
equal deleted inserted replaced
151:3b58d76ea032 152:a26b045c4e18
135 Both code and data addresses are reset to 0 by the MOD directive. 135 Both code and data addresses are reset to 0 by the MOD directive.
136 </para> 136 </para>
137 137
138 <para> 138 <para>
139 139
140 LWLINK does not, yet, have the ability to create OS9 modules from object 140 As of version 4.5, LWLINK also supports creation of OS9 modules.
141 files.
142 141
143 </para> 142 </para>
144 </section> 143 </section>
145 144
146 <section> 145 <section>
1971 </listitem> 1970 </listitem>
1972 </varlistentry> 1971 </varlistentry>
1973 </variablelist> 1972 </variablelist>
1974 1973
1975 1974
1975
1976 </section>
1977
1978 <section>
1979 <title>Format Specific Linking Notes</title>
1980
1981 <para>Some formats require special information to be able to generate actual
1982 binaries. If the specific format you are interested in is not listed in
1983 this section, then there is nothing special you need to know about to create
1984 a final binary.</para>
1985
1986 <section>
1987 <title>OS9 Modules</title>
1988
1989 <para>OS9 modules need to embed several items into the module header. These
1990 items are the type of module, the langauge of the module, the module
1991 attributes, the module revision number, the data size (bss), and the
1992 execution offset. These are all either calculated or default to reasonable
1993 values.</para>
1994
1995 <para>The data size is calcuated as the sum of all sections named "bss" or
1996 ".bss" in all object files that are linked together.</para>
1997
1998 <para>The execution offset is calculated from the address of the special
1999 symbol "__start" which must be an exported (external) symbol in one of the
2000 objects to be linked.</para>
2001
2002 <para>The type defaults to "Prgrm" or "Program module". The language
2003 defaults to "Objct" or "6809 object code". Attributes default to enabling
2004 the re-entrant flag. And finally, the revision defaults to zero.</para>
2005
2006 <para>The embedded module name is the output filename. If the output
2007 filename includes more than just the filename, this will probably not be
2008 what you want.</para>
2009
2010 <para>The type, language, attributes, revision, and module name can all be
2011 overridden by providing a special section in exactly one of the object files
2012 to be linked. This section is called "__os9" (note the two underscores).
2013 To override the type, language, attributes, or revision values, define a
2014 non-exported symbol in this section called "type", "lang", "attr", or "rev"
2015 respectively. Any other symbols defined are ignored. To override the
2016 module name, include as the only actual code in the section a NUL terminated
2017 string (the FCN directive is useful for this). If there is no code in the
2018 section or it beings with a NUL, the default name will be used. Any of the
2019 preceeding that are not defined in the special section will retain their
2020 default values.</para>
2021
2022 <para>The built-in link script for OS9 modules will place the following
2023 sections, in order, in the module: "code", ".text", "data", ".data". It
2024 will merge all sections with the name "bss" or ".bss" into the "data"
2025 section. All other section names are ignored. What this means is that you
2026 must define your data variables in the a section called "bss" or ".bss" even
2027 though you will be refencing them all as offsets from U. This does have the
2028 unpleasant side effect that all BSS references will end up being 16 bit
2029 offsets because the assembler cannot know what the offset will be once the
2030 linker is finished its work. Thus, if the tightest possible code is
2031 required, having LWASM directly output the module is a better choice.</para>
2032
2033 <para>While the built-in link script is probably sufficient for most
2034 purposes, you can provide your own script. If you provide a custom link
2035 script, you must start your code and data sections at location 000D to
2036 accommodate the module header. Otherwise, you will have an incorrect
2037 location for the execution offset. You must use the ENTRY directive in the
2038 script to define the entry point for the module.</para>
2039
2040 <para>It should also be obvious from the above that you cannot mix the bss
2041 (rmb) definitions with the module code when linking separately. Those
2042 familiar with typical module creation will probably find this an unpleasant
2043 difference but it is unavoidable.</para>
2044
2045 <para>It should also be noted that direct page references should also be
2046 avoided because you cannot know ahead of time whether the linker is going to
2047 end up putting a particular variable in the first 256 bytes of the module's
2048 data space. If, however, you know for certain you will have less than 256
2049 bytes of defined data space across all of the object files that will be
2050 linked, you can instead use forced DP addressing for your data addresses
2051 instead of the ,u notation. When linking with 3rd party libraries, this
2052 practice should be avoided. Also, when creating libraries, always use the
2053 offset from U technique.</para>
2054
2055 </section>
1976 2056
1977 </section> 2057 </section>
1978 2058
1979 </chapter> 2059 </chapter>
1980 2060