"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc9.html" (28 Aug 2020, 39630 Bytes) of package /linux/misc/nasm-2.15.05-xdoc.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml">
    4 <head>
    5 <title>NASM - The Netwide Assembler</title>
    6 <link href="nasmdoc.css" rel="stylesheet" type="text/css" />
    7 <link href="local.css" rel="stylesheet" type="text/css" />
    8 </head>
    9 <body>
   10 <ul class="navbar">
   11 <li class="first"><a class="prev" href="nasmdoc8.html">Chapter 8</a></li>
   12 <li><a class="next" href="nasmdo10.html">Chapter 10</a></li>
   13 <li><a class="toc" href="nasmdoc0.html">Contents</a></li>
   14 <li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
   15 </ul>
   16 <div class="title">
   17 <h1>NASM - The Netwide Assembler</h1>
   18 <span class="subtitle">version 2.15.05</span>
   19 </div>
   20 <div class="contents"
   21 >
   22 <h2 id="chapter-9">Chapter 9: Writing 16-bit Code (DOS, Windows 3/3.1)</h2>
   23 <p>This chapter attempts to cover some of the common issues encountered
   24 when writing 16-bit code to run under <code>MS-DOS</code> or
   25 <code>Windows 3.x</code>. It covers how to link programs to produce
   26 <code>.EXE</code> or <code>.COM</code> files, how to write
   27 <code>.SYS</code> device drivers, and how to interface assembly language
   28 code with 16-bit C compilers and with Borland Pascal.</p>
   29 <h3 id="section-9.1">9.1 Producing <code>.EXE</code> Files</h3>
   30 <p>Any large program written under DOS needs to be built as a
   31 <code>.EXE</code> file: only <code>.EXE</code> files have the necessary
   32 internal structure required to span more than one 64K segment. Windows
   33 programs, also, have to be built as <code>.EXE</code> files, since Windows
   34 does not support the <code>.COM</code> format.</p>
   35 <p>In general, you generate <code>.EXE</code> files by using the
   36 <code>obj</code> output format to produce one or more <code>.obj</code>
   37 files, and then linking them together using a linker. However, NASM also
   38 supports the direct generation of simple DOS <code>.EXE</code> files using
   39 the <code>bin</code> output format (by using <code>DB</code> and
   40 <code>DW</code> to construct the <code>.EXE</code> file header), and a
   41 macro package is supplied to do this. Thanks to Yann Guidon for
   42 contributing the code for this.</p>
   43 <p>NASM may also support <code>.EXE</code> natively as another output
   44 format in future releases.</p>
   45 <h4 id="section-9.1.1">9.1.1 Using the <code>obj</code> Format To Generate <code>.EXE</code> Files</h4>
   46 <p>This section describes the usual method of generating <code>.EXE</code>
   47 files by linking <code>.OBJ</code> files together.</p>
   48 <p>Most 16-bit programming language packages come with a suitable linker;
   49 if you have none of these, there is a free linker called VAL, available in
   50 <code>LZH</code> archive format from
   51 <a href="ftp://x2ftp.oulu.fi/pub/msdos/programming/lang/"><code>x2ftp.oulu.fi</code></a>.
   52 An LZH archiver can be found at
   53 <a href="ftp://ftp.simtel.net/pub/simtelnet/msdos/arcers"><code>ftp.simtel.net</code></a>.
   54 There is another `free' linker (though this one doesn't come with sources)
   55 called FREELINK, available from
   56 <a href="http://www.pcorner.com/tpc/old/3-101.html"><code>www.pcorner.com</code></a>.
   57 A third, <code>djlink</code>, written by DJ Delorie, is available at
   58 <a href="http://www.delorie.com/djgpp/16bit/djlink/"><code>www.delorie.com</code></a>.
   59 A fourth linker, <code>ALINK</code>, written by Anthony A.J. Williams, is
   60 available at
   61 <a href="http://alink.sourceforge.net"><code>alink.sourceforge.net</code></a>.</p>
   62 <p>When linking several <code>.OBJ</code> files into a <code>.EXE</code>
   63 file, you should ensure that exactly one of them has a start point defined
   64 (using the <code>..start</code> special symbol defined by the
   65 <code>obj</code> format: see <a href="nasmdoc8.html#section-8.4.6">section
   66 8.4.6</a>). If no module defines a start point, the linker will not know
   67 what value to give the entry-point field in the output file header; if more
   68 than one defines a start point, the linker will not know <em>which</em>
   69 value to use.</p>
   70 <p>An example of a NASM source file which can be assembled to a
   71 <code>.OBJ</code> file and linked on its own to a <code>.EXE</code> is
   72 given here. It demonstrates the basic principles of defining a stack,
   73 initialising the segment registers, and declaring a start point. This file
   74 is also provided in the <code>test</code> subdirectory of the NASM
   75 archives, under the name <code>objexe.asm</code>.</p>
   76 <pre>
   77 segment code 
   79 ..start: 
   80         mov     ax,data 
   81         mov     ds,ax 
   82         mov     ax,stack 
   83         mov     ss,ax 
   84         mov     sp,stacktop
   85 </pre>
   86 <p>This initial piece of code sets up <code>DS</code> to point to the data
   87 segment, and initializes <code>SS</code> and <code>SP</code> to point to
   88 the top of the provided stack. Notice that interrupts are implicitly
   89 disabled for one instruction after a move into <code>SS</code>, precisely
   90 for this situation, so that there's no chance of an interrupt occurring
   91 between the loads of <code>SS</code> and <code>SP</code> and not having a
   92 stack to execute on.</p>
   93 <p>Note also that the special symbol <code>..start</code> is defined at the
   94 beginning of this code, which means that will be the entry point into the
   95 resulting executable file.</p>
   96 <pre>
   97         mov     dx,hello 
   98         mov     ah,9 
   99         int     0x21
  100 </pre>
  101 <p>The above is the main program: load <code>DS:DX</code> with a pointer to
  102 the greeting message (<code>hello</code> is implicitly relative to the
  103 segment <code>data</code>, which was loaded into <code>DS</code> in the
  104 setup code, so the full pointer is valid), and call the DOS print-string
  105 function.</p>
  106 <pre>
  107         mov     ax,0x4c00 
  108         int     0x21
  109 </pre>
  110 <p>This terminates the program using another DOS system call.</p>
  111 <pre>
  112 segment data 
  114 hello:  db      'hello, world', 13, 10, '$'
  115 </pre>
  116 <p>The data segment contains the string we want to display.</p>
  117 <pre>
  118 segment stack stack 
  119         resb 64 
  120 stacktop:
  121 </pre>
  122 <p>The above code declares a stack segment containing 64 bytes of
  123 uninitialized stack space, and points <code>stacktop</code> at the top of
  124 it. The directive <code>segment stack stack</code> defines a segment
  125 <em>called</em> <code>stack</code>, and also of <em>type</em>
  126 <code>STACK</code>. The latter is not necessary to the correct running of
  127 the program, but linkers are likely to issue warnings or errors if your
  128 program has no segment of type <code>STACK</code>.</p>
  129 <p>The above file, when assembled into a <code>.OBJ</code> file, will link
  130 on its own to a valid <code>.EXE</code> file, which when run will print
  131 `hello, world' and then exit.</p>
  132 <h4 id="section-9.1.2">9.1.2 Using the <code>bin</code> Format To Generate <code>.EXE</code> Files</h4>
  133 <p>The <code>.EXE</code> file format is simple enough that it's possible to
  134 build a <code>.EXE</code> file by writing a pure-binary program and
  135 sticking a 32-byte header on the front. This header is simple enough that
  136 it can be generated using <code>DB</code> and <code>DW</code> commands by
  137 NASM itself, so that you can use the <code>bin</code> output format to
  138 directly generate <code>.EXE</code> files.</p>
  139 <p>Included in the NASM archives, in the <code>misc</code> subdirectory, is
  140 a file <code>exebin.mac</code> of macros. It defines three macros:
  141 <code>EXE_begin</code>, <code>EXE_stack</code> and <code>EXE_end</code>.</p>
  142 <p>To produce a <code>.EXE</code> file using this method, you should start
  143 by using <code>%include</code> to load the <code>exebin.mac</code> macro
  144 package into your source file. You should then issue the
  145 <code>EXE_begin</code> macro call (which takes no arguments) to generate
  146 the file header data. Then write code as normal for the <code>bin</code>
  147 format &ndash; you can use all three standard sections <code>.text</code>,
  148 <code>.data</code> and <code>.bss</code>. At the end of the file you should
  149 call the <code>EXE_end</code> macro (again, no arguments), which defines
  150 some symbols to mark section sizes, and these symbols are referred to in
  151 the header code generated by <code>EXE_begin</code>.</p>
  152 <p>In this model, the code you end up writing starts at <code>0x100</code>,
  153 just like a <code>.COM</code> file &ndash; in fact, if you strip off the
  154 32-byte header from the resulting <code>.EXE</code> file, you will have a
  155 valid <code>.COM</code> program. All the segment bases are the same, so you
  156 are limited to a 64K program, again just like a <code>.COM</code> file.
  157 Note that an <code>ORG</code> directive is issued by the
  158 <code>EXE_begin</code> macro, so you should not explicitly issue one of
  159 your own.</p>
  160 <p>You can't directly refer to your segment base value, unfortunately,
  161 since this would require a relocation in the header, and things would get a
  162 lot more complicated. So you should get your segment base by copying it out
  163 of <code>CS</code> instead.</p>
  164 <p>On entry to your <code>.EXE</code> file, <code>SS:SP</code> are already
  165 set up to point to the top of a 2Kb stack. You can adjust the default stack
  166 size of 2Kb by calling the <code>EXE_stack</code> macro. For example, to
  167 change the stack size of your program to 64 bytes, you would call
  168 <code>EXE_stack 64</code>.</p>
  169 <p>A sample program which generates a <code>.EXE</code> file in this way is
  170 given in the <code>test</code> subdirectory of the NASM archive, as
  171 <code>binexe.asm</code>.</p>
  172 <h3 id="section-9.2">9.2 Producing <code>.COM</code> Files</h3>
  173 <p>While large DOS programs must be written as <code>.EXE</code> files,
  174 small ones are often better written as <code>.COM</code> files.
  175 <code>.COM</code> files are pure binary, and therefore most easily produced
  176 using the <code>bin</code> output format.</p>
  177 <h4 id="section-9.2.1">9.2.1 Using the <code>bin</code> Format To Generate <code>.COM</code> Files</h4>
  178 <p><code>.COM</code> files expect to be loaded at offset <code>100h</code>
  179 into their segment (though the segment may change). Execution then begins
  180 at <code>100h</code>, i.e. right at the start of the program. So to write a
  181 <code>.COM</code> program, you would create a source file looking like</p>
  182 <pre>
  183         org 100h 
  185 section .text 
  187 start: 
  188         ; put your code here 
  190 section .data 
  192         ; put data items here 
  194 section .bss 
  196         ; put uninitialized data here
  197 </pre>
  198 <p>The <code>bin</code> format puts the <code>.text</code> section first in
  199 the file, so you can declare data or BSS items before beginning to write
  200 code if you want to and the code will still end up at the front of the file
  201 where it belongs.</p>
  202 <p>The BSS (uninitialized data) section does not take up space in the
  203 <code>.COM</code> file itself: instead, addresses of BSS items are resolved
  204 to point at space beyond the end of the file, on the grounds that this will
  205 be free memory when the program is run. Therefore you should not rely on
  206 your BSS being initialized to all zeros when you run.</p>
  207 <p>To assemble the above program, you should use a command line like</p>
  208 <pre>
  209 nasm myprog.asm -fbin -o myprog.com
  210 </pre>
  211 <p>The <code>bin</code> format would produce a file called
  212 <code>myprog</code> if no explicit output file name were specified, so you
  213 have to override it and give the desired file name.</p>
  214 <h4 id="section-9.2.2">9.2.2 Using the <code>obj</code> Format To Generate <code>.COM</code> Files</h4>
  215 <p>If you are writing a <code>.COM</code> program as more than one module,
  216 you may wish to assemble several <code>.OBJ</code> files and link them
  217 together into a <code>.COM</code> program. You can do this, provided you
  218 have a linker capable of outputting <code>.COM</code> files directly (TLINK
  219 does this), or alternatively a converter program such as
  220 <code>EXE2BIN</code> to transform the <code>.EXE</code> file output from
  221 the linker into a <code>.COM</code> file.</p>
  222 <p>If you do this, you need to take care of several things:</p>
  223 <ul>
  224 <li>
  225 <p>The first object file containing code should start its code segment with
  226 a line like <code>RESB 100h</code>. This is to ensure that the code begins
  227 at offset <code>100h</code> relative to the beginning of the code segment,
  228 so that the linker or converter program does not have to adjust address
  229 references within the file when generating the <code>.COM</code> file.
  230 Other assemblers use an <code>ORG</code> directive for this purpose, but
  231 <code>ORG</code> in NASM is a format-specific directive to the
  232 <code>bin</code> output format, and does not mean the same thing as it does
  233 in MASM-compatible assemblers.</p>
  234 </li>
  235 <li>
  236 <p>You don't need to define a stack segment.</p>
  237 </li>
  238 <li>
  239 <p>All your segments should be in the same group, so that every time your
  240 code or data references a symbol offset, all offsets are relative to the
  241 same segment base. This is because, when a <code>.COM</code> file is
  242 loaded, all the segment registers contain the same value.</p>
  243 </li>
  244 </ul>
  245 <h3 id="section-9.3">9.3 Producing <code>.SYS</code> Files</h3>
  246 <p>MS-DOS device drivers &ndash; <code>.SYS</code> files &ndash; are pure
  247 binary files, similar to <code>.COM</code> files, except that they start at
  248 origin zero rather than <code>100h</code>. Therefore, if you are writing a
  249 device driver using the <code>bin</code> format, you do not need the
  250 <code>ORG</code> directive, since the default origin for <code>bin</code>
  251 is zero. Similarly, if you are using <code>obj</code>, you do not need the
  252 <code>RESB 100h</code> at the start of your code segment.</p>
  253 <p><code>.SYS</code> files start with a header structure, containing
  254 pointers to the various routines inside the driver which do the work. This
  255 structure should be defined at the start of the code segment, even though
  256 it is not actually code.</p>
  257 <p>For more information on the format of <code>.SYS</code> files, and the
  258 data which has to go in the header structure, a list of books is given in
  259 the Frequently Asked Questions list for the newsgroup
  260 <a href="news:comp.os.msdos.programmer"><code>comp.os.msdos.programmer</code></a>.</p>
  261 <h3 id="section-9.4">9.4 Interfacing to 16-bit C Programs</h3>
  262 <p>This section covers the basics of writing assembly routines that call,
  263 or are called from, C programs. To do this, you would typically write an
  264 assembly module as a <code>.OBJ</code> file, and link it with your C
  265 modules to produce a mixed-language program.</p>
  266 <h4 id="section-9.4.1">9.4.1 External Symbol Names</h4>
  267 <p>C compilers have the convention that the names of all global symbols
  268 (functions or data) they define are formed by prefixing an underscore to
  269 the name as it appears in the C program. So, for example, the function a C
  270 programmer thinks of as <code>printf</code> appears to an assembly language
  271 programmer as <code>_printf</code>. This means that in your assembly
  272 programs, you can define symbols without a leading underscore, and not have
  273 to worry about name clashes with C symbols.</p>
  274 <p>If you find the underscores inconvenient, you can define macros to
  275 replace the <code>GLOBAL</code> and <code>EXTERN</code> directives as
  276 follows:</p>
  277 <pre>
  278 %macro  cglobal 1 
  280   global  _%1 
  281   %define %1 _%1 
  283 %endmacro 
  285 %macro  cextern 1 
  287   extern  _%1 
  288   %define %1 _%1 
  290 %endmacro
  291 </pre>
  292 <p>(These forms of the macros only take one argument at a time; a
  293 <code>%rep</code> construct could solve this.)</p>
  294 <p>If you then declare an external like this:</p>
  295 <pre>
  296 cextern printf
  297 </pre>
  298 <p>then the macro will expand it as</p>
  299 <pre>
  300 extern  _printf 
  301 %define printf _printf
  302 </pre>
  303 <p>Thereafter, you can reference <code>printf</code> as if it was a symbol,
  304 and the preprocessor will put the leading underscore on where necessary.</p>
  305 <p>The <code>cglobal</code> macro works similarly. You must use
  306 <code>cglobal</code> before defining the symbol in question, but you would
  307 have had to do that anyway if you used <code>GLOBAL</code>.</p>
  308 <p>Also see <a href="nasmdoc2.html#section-2.1.28">section 2.1.28</a>.</p>
  309 <h4 id="section-9.4.2">9.4.2 Memory Models</h4>
  310 <p>NASM contains no mechanism to support the various C memory models
  311 directly; you have to keep track yourself of which one you are writing for.
  312 This means you have to keep track of the following things:</p>
  313 <ul>
  314 <li>
  315 <p>In models using a single code segment (tiny, small and compact),
  316 functions are near. This means that function pointers, when stored in data
  317 segments or pushed on the stack as function arguments, are 16 bits long and
  318 contain only an offset field (the <code>CS</code> register never changes
  319 its value, and always gives the segment part of the full function address),
  320 and that functions are called using ordinary near <code>CALL</code>
  321 instructions and return using <code>RETN</code> (which, in NASM, is
  322 synonymous with <code>RET</code> anyway). This means both that you should
  323 write your own routines to return with <code>RETN</code>, and that you
  324 should call external C routines with near <code>CALL</code> instructions.</p>
  325 </li>
  326 <li>
  327 <p>In models using more than one code segment (medium, large and huge),
  328 functions are far. This means that function pointers are 32 bits long
  329 (consisting of a 16-bit offset followed by a 16-bit segment), and that
  330 functions are called using <code>CALL FAR</code> (or
  331 <code>CALL seg:offset</code>) and return using <code>RETF</code>. Again,
  332 you should therefore write your own routines to return with
  333 <code>RETF</code> and use <code>CALL FAR</code> to call external routines.</p>
  334 </li>
  335 <li>
  336 <p>In models using a single data segment (tiny, small and medium), data
  337 pointers are 16 bits long, containing only an offset field (the
  338 <code>DS</code> register doesn't change its value, and always gives the
  339 segment part of the full data item address).</p>
  340 </li>
  341 <li>
  342 <p>In models using more than one data segment (compact, large and huge),
  343 data pointers are 32 bits long, consisting of a 16-bit offset followed by a
  344 16-bit segment. You should still be careful not to modify <code>DS</code>
  345 in your routines without restoring it afterwards, but <code>ES</code> is
  346 free for you to use to access the contents of 32-bit data pointers you are
  347 passed.</p>
  348 </li>
  349 <li>
  350 <p>The huge memory model allows single data items to exceed 64K in size. In
  351 all other memory models, you can access the whole of a data item just by
  352 doing arithmetic on the offset field of the pointer you are given, whether
  353 a segment field is present or not; in huge model, you have to be more
  354 careful of your pointer arithmetic.</p>
  355 </li>
  356 <li>
  357 <p>In most memory models, there is a <em>default</em> data segment, whose
  358 segment address is kept in <code>DS</code> throughout the program. This
  359 data segment is typically the same segment as the stack, kept in
  360 <code>SS</code>, so that functions' local variables (which are stored on
  361 the stack) and global data items can both be accessed easily without
  362 changing <code>DS</code>. Particularly large data items are typically
  363 stored in other segments. However, some memory models (though not the
  364 standard ones, usually) allow the assumption that <code>SS</code> and
  365 <code>DS</code> hold the same value to be removed. Be careful about
  366 functions' local variables in this latter case.</p>
  367 </li>
  368 </ul>
  369 <p>In models with a single code segment, the segment is called
  370 <code>_TEXT</code>, so your code segment must also go by this name in order
  371 to be linked into the same place as the main code segment. In models with a
  372 single data segment, or with a default data segment, it is called
  373 <code>_DATA</code>.</p>
  374 <h4 id="section-9.4.3">9.4.3 Function Definitions and Function Calls</h4>
  375 <p>The C calling convention in 16-bit programs is as follows. In the
  376 following description, the words <em>caller</em> and <em>callee</em> are
  377 used to denote the function doing the calling and the function which gets
  378 called.</p>
  379 <ul>
  380 <li>
  381 <p>The caller pushes the function's parameters on the stack, one after
  382 another, in reverse order (right to left, so that the first argument
  383 specified to the function is pushed last).</p>
  384 </li>
  385 <li>
  386 <p>The caller then executes a <code>CALL</code> instruction to pass control
  387 to the callee. This <code>CALL</code> is either near or far depending on
  388 the memory model.</p>
  389 </li>
  390 <li>
  391 <p>The callee receives control, and typically (although this is not
  392 actually necessary, in functions which do not need to access their
  393 parameters) starts by saving the value of <code>SP</code> in
  394 <code>BP</code> so as to be able to use <code>BP</code> as a base pointer
  395 to find its parameters on the stack. However, the caller was probably doing
  396 this too, so part of the calling convention states that <code>BP</code>
  397 must be preserved by any C function. Hence the callee, if it is going to
  398 set up <code>BP</code> as a <em>frame pointer</em>, must push the previous
  399 value first.</p>
  400 </li>
  401 <li>
  402 <p>The callee may then access its parameters relative to <code>BP</code>.
  403 The word at <code>[BP]</code> holds the previous value of <code>BP</code>
  404 as it was pushed; the next word, at <code>[BP+2]</code>, holds the offset
  405 part of the return address, pushed implicitly by <code>CALL</code>. In a
  406 small-model (near) function, the parameters start after that, at
  407 <code>[BP+4]</code>; in a large-model (far) function, the segment part of
  408 the return address lives at <code>[BP+4]</code>, and the parameters begin
  409 at <code>[BP+6]</code>. The leftmost parameter of the function, since it
  410 was pushed last, is accessible at this offset from <code>BP</code>; the
  411 others follow, at successively greater offsets. Thus, in a function such as
  412 <code>printf</code> which takes a variable number of parameters, the
  413 pushing of the parameters in reverse order means that the function knows
  414 where to find its first parameter, which tells it the number and type of
  415 the remaining ones.</p>
  416 </li>
  417 <li>
  418 <p>The callee may also wish to decrease <code>SP</code> further, so as to
  419 allocate space on the stack for local variables, which will then be
  420 accessible at negative offsets from <code>BP</code>.</p>
  421 </li>
  422 <li>
  423 <p>The callee, if it wishes to return a value to the caller, should leave
  424 the value in <code>AL</code>, <code>AX</code> or <code>DX:AX</code>
  425 depending on the size of the value. Floating-point results are sometimes
  426 (depending on the compiler) returned in <code>ST0</code>.</p>
  427 </li>
  428 <li>
  429 <p>Once the callee has finished processing, it restores <code>SP</code>
  430 from <code>BP</code> if it had allocated local stack space, then pops the
  431 previous value of <code>BP</code>, and returns via <code>RETN</code> or
  432 <code>RETF</code> depending on memory model.</p>
  433 </li>
  434 <li>
  435 <p>When the caller regains control from the callee, the function parameters
  436 are still on the stack, so it typically adds an immediate constant to
  437 <code>SP</code> to remove them (instead of executing a number of slow
  438 <code>POP</code> instructions). Thus, if a function is accidentally called
  439 with the wrong number of parameters due to a prototype mismatch, the stack
  440 will still be returned to a sensible state since the caller, which
  441 <em>knows</em> how many parameters it pushed, does the removing.</p>
  442 </li>
  443 </ul>
  444 <p>It is instructive to compare this calling convention with that for
  445 Pascal programs (described in <a href="#section-9.5.1">section 9.5.1</a>).
  446 Pascal has a simpler convention, since no functions have variable numbers
  447 of parameters. Therefore the callee knows how many parameters it should
  448 have been passed, and is able to deallocate them from the stack itself by
  449 passing an immediate argument to the <code>RET</code> or <code>RETF</code>
  450 instruction, so the caller does not have to do it. Also, the parameters are
  451 pushed in left-to-right order, not right-to-left, which means that a
  452 compiler can give better guarantees about sequence points without
  453 performance suffering.</p>
  454 <p>Thus, you would define a function in C style in the following way. The
  455 following example is for small model:</p>
  456 <pre>
  457 global  _myfunc 
  459 _myfunc: 
  460         push    bp 
  461         mov     bp,sp 
  462         sub     sp,0x40         ; 64 bytes of local stack space 
  463         mov     bx,[bp+4]       ; first parameter to function 
  465         ; some more code 
  467         mov     sp,bp           ; undo "sub sp,0x40" above 
  468         pop     bp 
  469         ret
  470 </pre>
  471 <p>For a large-model function, you would replace <code>RET</code> by
  472 <code>RETF</code>, and look for the first parameter at <code>[BP+6]</code>
  473 instead of <code>[BP+4]</code>. Of course, if one of the parameters is a
  474 pointer, then the offsets of <em>subsequent</em> parameters will change
  475 depending on the memory model as well: far pointers take up four bytes on
  476 the stack when passed as a parameter, whereas near pointers take up two.</p>
  477 <p>At the other end of the process, to call a C function from your assembly
  478 code, you would do something like this:</p>
  479 <pre>
  480 extern  _printf 
  482       ; and then, further down... 
  484       push    word [myint]        ; one of my integer variables 
  485       push    word mystring       ; pointer into my data segment 
  486       call    _printf 
  487       add     sp,byte 4           ; `byte' saves space 
  489       ; then those data items... 
  491 segment _DATA 
  493 myint         dw    1234 
  494 mystring      db    'This number -&gt; %d &lt;- should be 1234',10,0
  495 </pre>
  496 <p>This piece of code is the small-model assembly equivalent of the C code</p>
  497 <pre>
  498     int myint = 1234; 
  499     printf("This number -&gt; %d &lt;- should be 1234\n", myint);
  500 </pre>
  501 <p>In large model, the function-call code might look more like this. In
  502 this example, it is assumed that <code>DS</code> already holds the segment
  503 base of the segment <code>_DATA</code>. If not, you would have to
  504 initialize it first.</p>
  505 <pre>
  506       push    word [myint] 
  507       push    word seg mystring   ; Now push the segment, and... 
  508       push    word mystring       ; ... offset of "mystring" 
  509       call    far _printf 
  510       add    sp,byte 6
  511 </pre>
  512 <p>The integer value still takes up one word on the stack, since large
  513 model does not affect the size of the <code>int</code> data type. The first
  514 argument (pushed last) to <code>printf</code>, however, is a data pointer,
  515 and therefore has to contain a segment and offset part. The segment should
  516 be stored second in memory, and therefore must be pushed first. (Of course,
  517 <code>PUSH DS</code> would have been a shorter instruction than
  518 <code>PUSH WORD SEG mystring</code>, if <code>DS</code> was set up as the
  519 above example assumed.) Then the actual call becomes a far call, since
  520 functions expect far calls in large model; and <code>SP</code> has to be
  521 increased by 6 rather than 4 afterwards to make up for the extra word of
  522 parameters.</p>
  523 <h4 id="section-9.4.4">9.4.4 Accessing Data Items</h4>
  524 <p>To get at the contents of C variables, or to declare variables which C
  525 can access, you need only declare the names as <code>GLOBAL</code> or
  526 <code>EXTERN</code>. (Again, the names require leading underscores, as
  527 stated in <a href="#section-9.4.1">section 9.4.1</a>.) Thus, a C variable
  528 declared as <code>int i</code> can be accessed from assembler as</p>
  529 <pre>
  530 extern _i 
  532         mov ax,[_i]
  533 </pre>
  534 <p>And to declare your own integer variable which C programs can access as
  535 <code>extern int j</code>, you do this (making sure you are assembling in
  536 the <code>_DATA</code> segment, if necessary):</p>
  537 <pre>
  538 global  _j 
  540 _j      dw      0
  541 </pre>
  542 <p>To access a C array, you need to know the size of the components of the
  543 array. For example, <code>int</code> variables are two bytes long, so if a
  544 C program declares an array as <code>int a[10]</code>, you can access
  545 <code>a[3]</code> by coding <code>mov ax,[_a+6]</code>. (The byte offset 6
  546 is obtained by multiplying the desired array index, 3, by the size of the
  547 array element, 2.) The sizes of the C base types in 16-bit compilers are: 1
  548 for <code>char</code>, 2 for <code>short</code> and <code>int</code>, 4 for
  549 <code>long</code> and <code>float</code>, and 8 for <code>double</code>.</p>
  550 <p>To access a C data structure, you need to know the offset from the base
  551 of the structure to the field you are interested in. You can either do this
  552 by converting the C structure definition into a NASM structure definition
  553 (using <code>STRUC</code>), or by calculating the one offset and using just
  554 that.</p>
  555 <p>To do either of these, you should read your C compiler's manual to find
  556 out how it organizes data structures. NASM gives no special alignment to
  557 structure members in its own <code>STRUC</code> macro, so you have to
  558 specify alignment yourself if the C compiler generates it. Typically, you
  559 might find that a structure like</p>
  560 <pre>
  561 struct { 
  562     char c; 
  563     int i; 
  564 } foo;
  565 </pre>
  566 <p>might be four bytes long rather than three, since the <code>int</code>
  567 field would be aligned to a two-byte boundary. However, this sort of
  568 feature tends to be a configurable option in the C compiler, either using
  569 command-line options or <code>#pragma</code> lines, so you have to find out
  570 how your own compiler does it.</p>
  571 <h4 id="section-9.4.5">9.4.5 <code>c16.mac</code>: Helper Macros for the 16-bit C Interface</h4>
  572 <p>Included in the NASM archives, in the <code>misc</code> directory, is a
  573 file <code>c16.mac</code> of macros. It defines three macros:
  574 <code>proc</code>, <code>arg</code> and <code>endproc</code>. These are
  575 intended to be used for C-style procedure definitions, and they automate a
  576 lot of the work involved in keeping track of the calling convention.</p>
  577 <p>(An alternative, TASM compatible form of <code>arg</code> is also now
  578 built into NASM's preprocessor. See
  579 <a href="nasmdoc4.html#section-4.8">section 4.8</a> for details.)</p>
  580 <p>An example of an assembly function using the macro set is given here:</p>
  581 <pre>
  582 proc    _nearproc 
  584 %$i     arg 
  585 %$j     arg 
  586         mov     ax,[bp + %$i] 
  587         mov     bx,[bp + %$j] 
  588         add     ax,[bx] 
  590 endproc
  591 </pre>
  592 <p>This defines <code>_nearproc</code> to be a procedure taking two
  593 arguments, the first (<code>i</code>) an integer and the second
  594 (<code>j</code>) a pointer to an integer. It returns <code>i + *j</code>.</p>
  595 <p>Note that the <code>arg</code> macro has an <code>EQU</code> as the
  596 first line of its expansion, and since the label before the macro call gets
  597 prepended to the first line of the expanded macro, the <code>EQU</code>
  598 works, defining <code>%$i</code> to be an offset from <code>BP</code>. A
  599 context-local variable is used, local to the context pushed by the
  600 <code>proc</code> macro and popped by the <code>endproc</code> macro, so
  601 that the same argument name can be used in later procedures. Of course, you
  602 don't <em>have</em> to do that.</p>
  603 <p>The macro set produces code for near functions (tiny, small and
  604 compact-model code) by default. You can have it generate far functions
  605 (medium, large and huge-model code) by means of coding
  606 <code>%define FARCODE</code>. This changes the kind of return instruction
  607 generated by <code>endproc</code>, and also changes the starting point for
  608 the argument offsets. The macro set contains no intrinsic dependency on
  609 whether data pointers are far or not.</p>
  610 <p><code>arg</code> can take an optional parameter, giving the size of the
  611 argument. If no size is given, 2 is assumed, since it is likely that many
  612 function parameters will be of type <code>int</code>.</p>
  613 <p>The large-model equivalent of the above function would look like this:</p>
  614 <pre>
  615 %define FARCODE 
  617 proc    _farproc 
  619 %$i     arg 
  620 %$j     arg     4 
  621         mov     ax,[bp + %$i] 
  622         mov     bx,[bp + %$j] 
  623         mov     es,[bp + %$j + 2] 
  624         add     ax,[bx] 
  626 endproc
  627 </pre>
  628 <p>This makes use of the argument to the <code>arg</code> macro to define a
  629 parameter of size 4, because <code>j</code> is now a far pointer. When we
  630 load from <code>j</code>, we must load a segment and an offset.</p>
  631 <h3 id="section-9.5">9.5 Interfacing to Borland Pascal Programs</h3>
  632 <p>Interfacing to Borland Pascal programs is similar in concept to
  633 interfacing to 16-bit C programs. The differences are:</p>
  634 <ul>
  635 <li>
  636 <p>The leading underscore required for interfacing to C programs is not
  637 required for Pascal.</p>
  638 </li>
  639 <li>
  640 <p>The memory model is always large: functions are far, data pointers are
  641 far, and no data item can be more than 64K long. (Actually, some functions
  642 are near, but only those functions that are local to a Pascal unit and
  643 never called from outside it. All assembly functions that Pascal calls, and
  644 all Pascal functions that assembly routines are able to call, are far.)
  645 However, all static data declared in a Pascal program goes into the default
  646 data segment, which is the one whose segment address will be in
  647 <code>DS</code> when control is passed to your assembly code. The only
  648 things that do not live in the default data segment are local variables
  649 (they live in the stack segment) and dynamically allocated variables. All
  650 data <em>pointers</em>, however, are far.</p>
  651 </li>
  652 <li>
  653 <p>The function calling convention is different &ndash; described below.</p>
  654 </li>
  655 <li>
  656 <p>Some data types, such as strings, are stored differently.</p>
  657 </li>
  658 <li>
  659 <p>There are restrictions on the segment names you are allowed to use
  660 &ndash; Borland Pascal will ignore code or data declared in a segment it
  661 doesn't like the name of. The restrictions are described below.</p>
  662 </li>
  663 </ul>
  664 <h4 id="section-9.5.1">9.5.1 The Pascal Calling Convention</h4>
  665 <p>The 16-bit Pascal calling convention is as follows. In the following
  666 description, the words <em>caller</em> and <em>callee</em> are used to
  667 denote the function doing the calling and the function which gets called.</p>
  668 <ul>
  669 <li>
  670 <p>The caller pushes the function's parameters on the stack, one after
  671 another, in normal order (left to right, so that the first argument
  672 specified to the function is pushed first).</p>
  673 </li>
  674 <li>
  675 <p>The caller then executes a far <code>CALL</code> instruction to pass
  676 control to the callee.</p>
  677 </li>
  678 <li>
  679 <p>The callee receives control, and typically (although this is not
  680 actually necessary, in functions which do not need to access their
  681 parameters) starts by saving the value of <code>SP</code> in
  682 <code>BP</code> so as to be able to use <code>BP</code> as a base pointer
  683 to find its parameters on the stack. However, the caller was probably doing
  684 this too, so part of the calling convention states that <code>BP</code>
  685 must be preserved by any function. Hence the callee, if it is going to set
  686 up <code>BP</code> as a frame pointer, must push the previous value first.</p>
  687 </li>
  688 <li>
  689 <p>The callee may then access its parameters relative to <code>BP</code>.
  690 The word at <code>[BP]</code> holds the previous value of <code>BP</code>
  691 as it was pushed. The next word, at <code>[BP+2]</code>, holds the offset
  692 part of the return address, and the next one at <code>[BP+4]</code> the
  693 segment part. The parameters begin at <code>[BP+6]</code>. The rightmost
  694 parameter of the function, since it was pushed last, is accessible at this
  695 offset from <code>BP</code>; the others follow, at successively greater
  696 offsets.</p>
  697 </li>
  698 <li>
  699 <p>The callee may also wish to decrease <code>SP</code> further, so as to
  700 allocate space on the stack for local variables, which will then be
  701 accessible at negative offsets from <code>BP</code>.</p>
  702 </li>
  703 <li>
  704 <p>The callee, if it wishes to return a value to the caller, should leave
  705 the value in <code>AL</code>, <code>AX</code> or <code>DX:AX</code>
  706 depending on the size of the value. Floating-point results are returned in
  707 <code>ST0</code>. Results of type <code>Real</code> (Borland's own custom
  708 floating-point data type, not handled directly by the FPU) are returned in
  709 <code>DX:BX:AX</code>. To return a result of type <code>String</code>, the
  710 caller pushes a pointer to a temporary string before pushing the
  711 parameters, and the callee places the returned string value at that
  712 location. The pointer is not a parameter, and should not be removed from
  713 the stack by the <code>RETF</code> instruction.</p>
  714 </li>
  715 <li>
  716 <p>Once the callee has finished processing, it restores <code>SP</code>
  717 from <code>BP</code> if it had allocated local stack space, then pops the
  718 previous value of <code>BP</code>, and returns via <code>RETF</code>. It
  719 uses the form of <code>RETF</code> with an immediate parameter, giving the
  720 number of bytes taken up by the parameters on the stack. This causes the
  721 parameters to be removed from the stack as a side effect of the return
  722 instruction.</p>
  723 </li>
  724 <li>
  725 <p>When the caller regains control from the callee, the function parameters
  726 have already been removed from the stack, so it needs to do nothing
  727 further.</p>
  728 </li>
  729 </ul>
  730 <p>Thus, you would define a function in Pascal style, taking two
  731 <code>Integer</code>&ndash;type parameters, in the following way:</p>
  732 <pre>
  733 global  myfunc 
  735 myfunc: push    bp 
  736         mov     bp,sp 
  737         sub     sp,0x40         ; 64 bytes of local stack space 
  738         mov     bx,[bp+8]       ; first parameter to function 
  739         mov     bx,[bp+6]       ; second parameter to function 
  741         ; some more code 
  743         mov     sp,bp           ; undo "sub sp,0x40" above 
  744         pop     bp 
  745         retf    4               ; total size of params is 4
  746 </pre>
  747 <p>At the other end of the process, to call a Pascal function from your
  748 assembly code, you would do something like this:</p>
  749 <pre>
  750 extern  SomeFunc 
  752        ; and then, further down... 
  754        push   word seg mystring   ; Now push the segment, and... 
  755        push   word mystring       ; ... offset of "mystring" 
  756        push   word [myint]        ; one of my variables 
  757        call   far SomeFunc
  758 </pre>
  759 <p>This is equivalent to the Pascal code</p>
  760 <pre>
  761 procedure SomeFunc(String: PChar; Int: Integer); 
  762     SomeFunc(@mystring, myint);
  763 </pre>
  764 <h4 id="section-9.5.2">9.5.2 Borland Pascal Segment Name Restrictions</h4>
  765 <p>Since Borland Pascal's internal unit file format is completely different
  766 from <code>OBJ</code>, it only makes a very sketchy job of actually reading
  767 and understanding the various information contained in a real
  768 <code>OBJ</code> file when it links that in. Therefore an object file
  769 intended to be linked to a Pascal program must obey a number of
  770 restrictions:</p>
  771 <ul>
  772 <li>
  773 <p>Procedures and functions must be in a segment whose name is either
  774 <code>CODE</code>, <code>CSEG</code>, or something ending in
  775 <code>_TEXT</code>.</p>
  776 </li>
  777 <li>
  778 <p>initialized data must be in a segment whose name is either
  779 <code>CONST</code> or something ending in <code>_DATA</code>.</p>
  780 </li>
  781 <li>
  782 <p>Uninitialized data must be in a segment whose name is either
  783 <code>DATA</code>, <code>DSEG</code>, or something ending in
  784 <code>_BSS</code>.</p>
  785 </li>
  786 <li>
  787 <p>Any other segments in the object file are completely ignored.
  788 <code>GROUP</code> directives and segment attributes are also ignored.</p>
  789 </li>
  790 </ul>
  791 <h4 id="section-9.5.3">9.5.3 Using <code>c16.mac</code> With Pascal Programs</h4>
  792 <p>The <code>c16.mac</code> macro package, described in
  793 <a href="#section-9.4.5">section 9.4.5</a>, can also be used to simplify
  794 writing functions to be called from Pascal programs, if you code
  795 <code>%define PASCAL</code>. This definition ensures that functions are far
  796 (it implies <code>FARCODE</code>), and also causes procedure return
  797 instructions to be generated with an operand.</p>
  798 <p>Defining <code>PASCAL</code> does not change the code which calculates
  799 the argument offsets; you must declare your function's arguments in reverse
  800 order. For example:</p>
  801 <pre>
  802 %define PASCAL 
  804 proc    _pascalproc 
  806 %$j     arg 4 
  807 %$i     arg 
  808         mov     ax,[bp + %$i] 
  809         mov     bx,[bp + %$j] 
  810         mov     es,[bp + %$j + 2] 
  811         add     ax,[bx] 
  813 endproc
  814 </pre>
  815 <p>This defines the same routine, conceptually, as the example in
  816 <a href="#section-9.4.5">section 9.4.5</a>: it defines a function taking
  817 two arguments, an integer and a pointer to an integer, which returns the
  818 sum of the integer and the contents of the pointer. The only difference
  819 between this code and the large-model C version is that <code>PASCAL</code>
  820 is defined instead of <code>FARCODE</code>, and that the arguments are
  821 declared in reverse order.</p>
  822 </div>
  823 </body>
  824 </html>