home *** CD-ROM | disk | FTP | other *** search
/ HomeWare 14 / HOMEWARE14.bin / prog / a86v371.arj / A10.DOC < prev    next >
Text File  |  1994-01-24  |  33KB  |  686 lines

  1. CHAPTER 10   RELOCATION AND LINKAGE
  2.  
  3.  
  4. A86 allows you to produce either .COM files, which can be run
  5. immediately as standalone programs, or .OBJ files, to be fed to
  6. the MS-DOS LINK program.  In this chapter I'll discuss .OBJ mode
  7. of A86.
  8.  
  9.  
  10. .OBJ Production Made Easy
  11.  
  12. I'll start by giving you the minimum amount of information you
  13. need to know to produce .OBJ files.  If you are writing short
  14. interface routines, and do not want to concern yourself with the
  15. esoterica of .OBJ files (segments, groups, publics, etc.), you
  16. can survive quite nicely by reading only this section.
  17.  
  18. There are two ways you can cause A86 to produce a .OBJ file as
  19. its object output.  One way is to explicitly give .OBJ as the
  20. output file name: for example, you can assemble the source file
  21. FOO.8 by giving the command "A86 FOO.8 FOO.OBJ".  The other way
  22. is to specify the switch +O (letter O not digit 0).  This is
  23. illustrated by the invocation "A86 +O FOO.8", which will have the
  24. same effect as the first invocation.
  25.  
  26. My design philosophy for .OBJ production is to accommodate two
  27. types of user.  The first type of user is writing new code, to
  28. link to other (usually high level language) modules.  That person
  29. should be able to write the module with a minimum of red tape,
  30. and have A86 do the right thing.  The second type of user has
  31. existing modules written for Intel/IBM assemblers, and wants to
  32. port them to A86.  A86 should recognize and act upon all the
  33. relocation directives (SEGMENT, GROUP, PUBLIC, EXTRN, NAME, END)
  34. given.  The assembly should work even if several files, assembled
  35. separately under the Intel/IBM assembler, are fed to a single A86
  36. assembly.  You'll see if you read on through this entire chapter
  37. that the multiple-files requirement causes A86 to interpret some
  38. of the relocation directives a little differently (while
  39. achieving compatible results).
  40.  
  41. Let's suppose you're writing new code: for example, an interface
  42. routine to the "C" language, that multiplies a 16-bit number by
  43. 10.  "C" pushes the input number onto the stack, before calling
  44. your routine.  Your code needs to get the number, multiply it by
  45. 10, and return the answer in the AX register.  You can code it:
  46.  
  47. _MUL10:          ; "C" expects all public names to start with "_"
  48.   PUSH BP        ; "C" expects BP to be preserved
  49.   MOV BP,SP      ; we use BP to address the stack
  50.   MOV AX,[BP+4]  ; fetch the number N, beyond BP and the ret addr
  51.   ADD AX,AX      ; 2N
  52.   MOV BX,AX      ; 2N is saved in BX
  53.   ADD AX,AX      ; 4N
  54.   ADD AX,AX      ; 8N
  55.   ADD AX,BX      ; 8N + 2N = 10N
  56.   POP BP         ; BP is restored
  57.   RET            ; go back to caller
  58.                                                              10-2
  59.  
  60. These 11 lines can be your entire source file!  If you name the
  61. file MUL10.8, A86 will create an object file MUL10.OBJ, that
  62. conforms to the standard SMALL model of computation for high
  63. level languages.  If you use RETF instead of RET (thus, by the
  64. way, getting the operand from BP+6 instead of BP+4), the object
  65. module will conform to the standard LARGE model of computation.
  66. All the red tape information required by the high level language
  67. is provided implicitly by A86.  I'll go through this information
  68. in detail later, but you should need to read about it only if
  69. you're curious.
  70.  
  71. What happens if you need to access symbols outside the module
  72. you're assembling?  If the type of the symbol is correctly
  73. guessed from the instruction that refers to it, then you can
  74. simply refer to it, and leave it undefined within the module. For
  75. example, if A86 sees the instruction CALL PRINT with PRINT
  76. undefined, it will assume that PRINT is a NEAR procedure.  If
  77. PRINT is never defined within the module, A86 will act as if you
  78. declared PRINT via the directive EXTRN PRINT:NEAR.  The address
  79. of PRINT will be plugged into your instruction by LINK when it
  80. combines A86's .OBJ file with the high level language's .OBJ
  81. files, to make the final program.
  82.  
  83. In general, the undefined operand to any CALL or JMP instruction
  84. is assumed to be NEAR.  The second (source) operand to a MOV or
  85. arithmetic instruction is assumed to be ABS (i.e., an immediate
  86. constant).  An undefined first (destination) operand is assumed
  87. to be a simple memory variable, of the same size (BYTE or WORD)
  88. as the register given in the second operand.  If your external
  89. symbol does not comply with these guidelines, you need to declare
  90. it with an EXTRN before you use it.  (You can also use EXTRN to
  91. declare types of non-complying forward references within your
  92. module, as you'll see later.)
  93.  
  94. If you'd like to link the MUL10 procedure to Turbo Pascal V4.0 or
  95. later, you need to append the line CODE SEGMENT PUBLIC to the top
  96. of the program, to name the program segment according to Turbo
  97. Pascal's expectations.  You may dispense with the leading
  98. underscore in the name MUL10-- Turbo Pascal does not require or
  99. expect it.
  100.  
  101. At this point, if you're a casual user, I think you've read
  102. enough to get going!  Read further only if you wish; or if you
  103. get stuck, and need to master the esoterica.
  104.                                                              10-3
  105.  
  106. Overview of Relocation and Linkage
  107.  
  108. When you assemble a program directly into a .COM file, the
  109. program has just two forms: the source program, that you can
  110. understand, and the .COM file, that the computer can "understand"
  111. (i.e., execute).  A .OBJ file is an intermediate format: neither
  112. you nor the (executing) computer can make sense out of a .OBJ
  113. file; only programs like LINK interpret .OBJ files.  The purpose
  114. of a .OBJ file is to allow you to assemble or compile just a part
  115. of a program.  The other parts (also in the form of .OBJ files)
  116. can be produced at a different time; often by a different
  117. assembler or compiler, whose source files are in a different
  118. language.  It's easy to see where the word "linkage" comes from:
  119. the LINK program puts the pieces of a program together.  The
  120. "relocation" comes because the assembler or compiler that makes a
  121. given program piece doesn't know how many other pieces will come
  122. before it, or how big the other pieces will be.  Each piece is
  123. constructed as if it started at location 0 within the program;
  124. then LINK "relocates" the piece to its true location.
  125.  
  126. Many of the relocation features of 86 assembly language are
  127. couched in terms of LINK's point of view, so we must look at the
  128. way LINK sees things.  LINK calls a .OBJ file an "object module",
  129. or just "module".  Each module has a NAME, that can be referred
  130. to when LINK issues diagnostic messages, such as error messages
  131. and symbol maps.  If a program symbol is used only within a
  132. single module, it does not need to be given to LINK, except
  133. possibly to pass along to a symbolic debugger.  On the other
  134. hand, if a program symbol is defined in one module and referenced
  135. in other modules, then LINK needs to know the name of the symbol,
  136. so it can resolve the references.  Such a symbol is PUBLIC in the
  137. module in which it is defined; it is "external" in the other
  138. modules, containing references to it.  Finally, exactly one
  139. module in a program must contain the starting location for the
  140. program; that module is called the "main module", and it must
  141. supply the starting address (which is not necessarily at the
  142. beginning of the module).
  143.  
  144. In the 86 family of microprocessors, the LINK system also does
  145. much to manage the memory segments that a program will fit into,
  146. and get its data from.  The (grotesquely ornate) level of support
  147. for segmentation was dictated by Intel, when it specified (and
  148. IBM and the compiler makers accepted) the format that .OBJ files
  149. will have.  I attended the fateful meeting at Intel, in which the
  150. crucial design decisions were made.  I regret to say that I sat
  151. quietly, while engineers more senior than I applied their fertile
  152. imaginations to construct fanciful scenarios which they felt had
  153. to be supported by LINK.  Let's now review the resulting
  154. segmentation model.
  155.                                                              10-4
  156.  
  157. The parts of a program, as viewed by LINK, come in three
  158. different sizes: they can be (1) pieces of a single segment, (2)
  159. an entire single segment, or (3) a sequence of consecutive
  160. segments in 86 memory.  Size (1) should have been called
  161. something like FRAGMENT, but is instead called SEGMENT.  Size (2)
  162. should have been called SEGMENT, but is instead called GROUP.
  163. Size (3) should have been called "group", but is instead called
  164. "class".  Let me cling to the sensible terminology for one more
  165. paragraph, while I describe the worst scenario Intel wanted to
  166. support; then when I discuss individual directives, I'll
  167. regretfully revert to the official terminology.
  168.  
  169. The scenario is as follows: suppose you have a program that
  170. occupies about 100K bytes of memory.  The program contains a core
  171. of 20K bytes of utility routines that every part of the program
  172. calls.  You'd like every part of the program to be able to call
  173. these routines, using the NEAR form to save memory.  By gum, you
  174. can do it!  You simply(!) slice the program into three fragments:
  175. the utility routines will go into fragment U, and the rest of the
  176. program will be split into equal-sized 40K-byte fragments A and
  177. B.  Now you arrange the fragments in 8086 memory in the order
  178. A,U,B.  The fragments A and U form a 60K-byte block, addressed by
  179. a segment register value G1, that points to the beginning of A.
  180. The fragments U and B form another 60K-byte block addressed by a
  181. segment register value G2, that points to the beginning of U.  If
  182. you set the CS register to G1 when A is executing, and G2 when B
  183. is executing, the U fragment is accessible at all times.  Since
  184. all direct JMPs and CALLs are encoded as relative offsets, the
  185. U-code will execute direct jumps correctly whether addressed by
  186. G1 with a huge offset, or G2 with a small offset.  Of course, if
  187. U contains any absolute pointers referring to itself (such as an
  188. indirect near JMP or CALL), you're in trouble.
  189.  
  190. It's now been over a decade since the fateful design meeting took
  191. place, and I can report that the above scenario has never taken
  192. place in the real world.  And I can state with some authority
  193. that it never will.  The reason is that the only programs that
  194. exceed 64K bytes in size are coded in high level language, not
  195. assembly language.  High-level-language compilers follow a very,
  196. very restricted segmentation model-- no existing model comes
  197. remotely close to supporting the scheme suggested by the
  198. scenario.  But the 86 assembly language can support it-- the
  199. directives "G1 GROUP A,U" and "G2 GROUP B,U", followed by chunks
  200. of code of the appropriate object size, headed by directives "A
  201. SEGMENT", "B SEGMENT", and "U SEGMENT".  The LINK program is
  202. supposed to sort things out according to the scenario; but I
  203. can't say (and I have my doubts) if it actually succeeds in doing
  204. so.
  205.  
  206. The concept of "class" was added as an afterthought, to implement
  207. the more sensible and usable features that outsiders thought
  208. GROUPs were implementing;  namely, the ability to specify that
  209. different (and disjoint!) segments occur consecutively in memory.
  210. This allows programs to be arranged in a consistent manner-- for
  211. example, with all program code followed by all static data
  212. segments followed by all dynamically allocated memory.
  213.                                                              10-5
  214.  
  215. The NAME Directive
  216.  
  217. Syntax:  NAME module_name
  218.  
  219. The NAME directive specifies that "module_name" be given to LINK
  220. as the name of the module produced by this assembly.  The symbol
  221. "module_name" can be used elsewhere in your program without
  222. conflict: it can even, if you like, be a built-in assembler
  223. mnemonic (e.g. "NAME MOV" is acceptable)!
  224.  
  225. If you do not provide a NAME directive, A86 will use the name of
  226. the output object file, without the .OBJ extension.   If you
  227. provide more than one NAME directive, A86 will use the last one
  228. given, with no error reported.
  229.  
  230.  
  231.  
  232. The PUBLIC Directive
  233.  
  234. Syntax:  PUBLIC  sym1, sym2, sym3, ...
  235.          PUBLIC
  236.  
  237. The PUBLIC directive allows you to explicitly list the symbols
  238. defined in this assembly, that can be used by other modules.  If
  239. you do not give any PUBLIC directives in your program, A86 will
  240. use every relocatable label and variable name in your program,
  241. except local labels (the redefinable labels consisting of a
  242. letter followed by digits: L7, M1, Q234, etc.).  Symbols EQUated
  243. to constants, and symbols defined within structures and DATA
  244. SEGMENTs, are not implicitly declared PUBLIC: you have to
  245. explicitly include them in a PUBLIC directive.
  246.  
  247. A86 maintains an internal flag, telling it whether to figure out
  248. for itself which symbols are PUBLIC, or to let the program
  249. explicitly declare them.  The flag starts out "implicit", and is
  250. set to "explicit" only if A86 sees a PUBLIC directive with no
  251. names at all, or a PUBLIC directive containing at least one name
  252. that would have been implicitly made PUBLIC.
  253.  
  254. If you are writing new code, you'll probably want to keep the
  255. flag "implicit".  You use the PUBLIC directive only for those
  256. symbols which have the form of local labels, but aren't (e.g., a
  257. memory variable I1987 for 1987 income); and for absolute values
  258. that are globally accessed -- e.g. specify "PUBLIC
  259. OPEN_FILES_LIMIT" for a symbol defined as "OPEN_FILES_LIMIT EQU
  260. 20".
  261.  
  262. If you are porting existing code, that code will already have
  263. PUBLIC directives in it, and A86 will go to "explicit" mode,
  264. duplicating the functionality of other assemblers.
  265.  
  266. The PUBLIC directive with no names is used to force "explicit"
  267. mode, thus causing (if there are no further PUBLICs with names)
  268. the .OBJ file to declare no symbols PUBLIC.
  269.                                                              10-6
  270.  
  271. There is another side effect to the PUBLIC directive: if a symbol
  272. is declared PUBLIC in a module, it had better be defined in that
  273. module.  If it isn't then A86 includes it in the .ERR listing of
  274. undefined symbols in the module, and suppresses output of the
  275. object file.
  276.  
  277.  
  278. The EXTRN Directive
  279.  
  280. Syntax:  EXTRN  sym1:type, sym2:type, ...
  281.  
  282. where "type" is one of:  BYTE WORD DWORD QWORD TBYTE FAR
  283. or synonymously:           B    W    D     Q     T     F
  284. or:                        NEAR  ABS
  285.  
  286. The EXTRN directive allows you to attach a type to a symbol that
  287. may not yet be defined (and may never be defined) within your
  288. program.  This is often necessary for the assembler to generate
  289. the correct instruction form when the symbol is used as an
  290. operand.  All the possible types except ABS are defined elsewhere
  291. in the A86 language, but I list them again here for convenience:
  292.  
  293.    B or BYTE:   byte-sized memory variable
  294.    W or WORD:   word (2 byte) sized memory variable
  295.    D or DWORD:  doubleword (4-byte) sized memory variable
  296.    Q or QWORD:  quadword (8-byte) sized memory variable
  297.    T or TWORD:  10-byte-sized memory variable
  298.    NEAR:        program label accessed within a segment
  299.    FAR:         program label accessed from outside this segment
  300.    ABS:         an absolute number (i.e., an immediate constant)
  301.  
  302. An example of EXTRN usage is as follows: suppose there is a word
  303. memory variable IFARK in your program.  The variable might be
  304. declared at the end of the program; or it might be defined in a
  305. module completely outside of this program.  Without an EXTRN
  306. directive, A86 will assemble an instruction such as "MOV
  307. AX,IFARK" as the loading of an immediate constant IFARK into the
  308. AX register.  If you place the directive "EXTRN IFARK:W" at the
  309. top of your program, you'll get the correct instruction form for
  310. MOV AX,IFARK-- moving a word-memory variable into the AX
  311. register.
  312.  
  313. A86 will allow more than one EXTRN directive for a given symbol,
  314. as long as the same type is given every time.  A86 will even
  315. allow an EXTRN directive for a symbol that has already been
  316. defined, as long as the type declared is consistent with the
  317. symbol's definition.  These allowances exist so that you can
  318. assemble multiple files written for another assembler, that had
  319. been fed separately to that assembler.
  320.                                                              10-7
  321.  
  322. Note that EXTRN is viewed quite differently by A86 than by other
  323. assemblers.  In fact, if it weren't for those other assemblers,
  324. I'd use the mnemonic DECLARE instead of EXTRN.  A86 doesn't
  325. really use EXTRN to determine which symbols are external-- it
  326. uses those symbols that are undefined at the end of assembly.  As
  327. I stated earlier in the chapter, an undefined symbol can be
  328. referenced without being declared via EXTRN. Conversely, a
  329. defined symbol can be declared (and redeclared) via EXTRN; being
  330. defined, such a symbol will not be specified "external" in the
  331. .OBJ file.
  332.  
  333. Because EXTRN is useful in forward reference situations, it is
  334. now recognized even when A86 is assembling a .COM file.
  335.  
  336. For those of you who are accustomed to the more traditional use
  337. of EXTRN, and who do not like external records to be created
  338. "behind your back", A86 offers the "+G16" option.  If you include
  339. "+G16" in the program invocation, A86 will require that all
  340. undefined symbols be explicitly declared via an EXTRN.  Any
  341. undefined, undeclared symbols will be included in the .ERR
  342. listing of undefined symbols, and object-file output will be
  343. suppressed.
  344.  
  345.  
  346. MAIN: The Starting Location for a Program
  347.  
  348. I've already stated that exactly one module in a program is the
  349. "main" module, containing the starting address of the entire
  350. program.  In A86 when assembling .OBJ files, the starting address
  351. is given by the label MAIN.  You simply provide the label "MAIN:"
  352. where you want the program to start.  The module containing MAIN
  353. is the main module.
  354.  
  355.  
  356. The END Directive
  357.  
  358. Syntax:  END
  359.          END start_addr
  360.  
  361. The END directive is used by other assemblers for two purposes,
  362. both of which are now a little silly.  The first purpose is to
  363. signal the end of assembly.  This was necessary back in the days
  364. when source files were input on media such as paper tape: you had
  365. to tell the assembler explicitly that the content of the tape has
  366. ended.  Today the operating system can tell you when you've
  367. reached the end of the file, so this function is an anachronism.
  368.  
  369. The second purpose of END is, nonsensically, to allow you to
  370. specify the starting location of the program.  I suppose the
  371. person who wrote the first assembler back in the 1950's was too
  372. short on memory to implement a separate START directive, or a
  373. MAIN label like A86 has, and decided to let END do double duty.
  374. I've always considered the example "END START" to have an
  375. Alice-in-Wonderland quality; it is fuel for the
  376. high-level-language snobs who like to attack assembly language.
  377. Please defeat the snobs, and use "MAIN:" if you are writing new
  378. code.
  379.                                                              10-8
  380.  
  381. For compatibility, A86 treats "END start_addr" exactly the same
  382. as if you had coded "MAIN EQU start_addr".  Note that if you want
  383. your program to assemble under both A86 and other assemblers, you
  384. can specify "END MAIN"-- A86 treats MAIN EQU MAIN as a legal
  385. redefinition of the symbol MAIN.
  386.  
  387. A86 ignores END when there is no starting-address operand, thus
  388. allowing assembly of multiple files written for other assemblers.
  389.  
  390.  
  391. The SEGMENT Directive
  392.  
  393. Syntax:  seg_name SEGMENT [align] [combine] ['class_name']
  394.  
  395. where "align" is one of:  BYTE   WORD   PARA   PAGE
  396. "combine" is one of:      PUBLIC  STACK  COMMON  MEMORY
  397.                             AT number
  398.  
  399. The SEGMENT directive says that assembled object code will
  400. henceforth go to a block of code whose name is "seg_name".
  401. "seg_name" is a symbol that represents a value that can be loaded
  402. into a segment register.  If "seg_name" is not declared in a
  403. GROUP directive, then its value should in fact be loaded into a
  404. segment register, in order to address the code.  If "seg_name" is
  405. declared in a GROUP directive, then the code is a part of the
  406. segment addressed by the name of the group.
  407.  
  408. A program can consist of any number of named segments, to be
  409. combined in numerous exotic ways to produce the final program.
  410. You can redirect your object output from one segment to another
  411. in your assembly, by providing a SEGMENT directive before each
  412. piece of code.  You can even return to a segment you started
  413. earlier, by repeating a SEGMENT with the same name-- the
  414. assembler just picks up where it left off, subject to some
  415. possible skipping for memory alignment, that I'll describe
  416. shortly.
  417.  
  418. The specifications following the word SEGMENT help to describe
  419. how the code in this module's part of the segment will be
  420. combined with code for the same segment name given in other
  421. modules; and also how this named segment will be grouped with
  422. other named segments.  Other assemblers require the
  423. specifications to be given in the order indicated.  A86 will
  424. accept any order, and will accept commas between the
  425. specifications if you want to provide them.  The only restriction
  426. is that "AT number" must be followed by a comma if it is not the
  427. last specification on the line.
  428.                                                              10-9
  429.  
  430. The "align" specification tells if each piece of code within the
  431. segment should be aligned so that its starting address is an even
  432. multiple of some number.  BYTE alignment means there is no
  433. requirement; WORD alignment requires each piece to start at a
  434. multiple of 2; PARA alignment, at a multiple of 16; PAGE
  435. alignment, at a multiple of 256.  For example, suppose you have a
  436. segment containing memory variables.  You can declare the segment
  437. with the statement "VAR_DATA SEGMENT WORD", which ensures that
  438. the segment is aligned to an even memory address.  That way you
  439. can insure that all 16-bit and bigger memory quantities in the
  440. segment are aligned to even addresses, for faster access on the
  441. 16-bit machines of the 86 family.
  442.  
  443. There are special rules governing alignment for multiple pieces
  444. of the same named segment within the same program module.  Other
  445. assemblers outlaw conflicting alignment specifications in this
  446. situation; A86 accepts them, and uses the strictest specification
  447. given.  Furthermore, the alignment given for any specification
  448. beyond the first will control the alignment for that piece of
  449. code within this module's chunk.  For example, if a program
  450. contains two pieces of code headed by "VAR_DATA SEGMENT WORD",
  451. A86 will insert a byte between the pieces if the first piece has
  452. an odd number of bytes.  This insures correct assembly for
  453. multiple files written for another assembler.
  454.  
  455. If no "align" type is given for any of the pieces of a named
  456. segment, an alignment of PARA is assumed.
  457.  
  458.  
  459. The "combine" specification tells how the chunk of code from this
  460. module will be combined with the chunks of the same named
  461. segment, that come from other modules.  Yes, I know, that sounds
  462. like what "align" does; but "combine" takes a different, more
  463. major point of view:
  464.  
  465. * PUBLIC is the kind of combination we've been talking about all
  466.   along: each piece of the segment is located off the end of the
  467.   previously linked piece, subject to possible gaps for
  468.   alignment.  The size of the segment is the sum of the sizes of
  469.   the pieces, plus the sizes of the gaps.
  470.  
  471. * STACK is a combination type reserved for the system's stack
  472.   segment.  To illustrate how STACK segment chunks are combined,
  473.   let's describe the only way a stack segment should ever be
  474.   used.  We'll call the segment STACK; and we declare it as
  475.   follows:
  476.  
  477.     STACK SEGMENT WORD STACK
  478.         DW 100 DUP (?)
  479.     TOP_OF_STACK:
  480.                                                             10-10
  481.  
  482.   The code just given declares a stack area of 200 bytes (100
  483.   words) for this module.  If identical code occurs in each of
  484.   three modules which are then linked together, the resulting
  485.   STACK segment will have 600 bytes (the sizes are added), but
  486.   TOP_OF_STACK will be the same address (600) for each module
  487.   (each piece is overlayed at the top of the segment).  That way,
  488.   every module can declare and access the top of the stack, which
  489.   is the only static part of the stack that any code should ever
  490.   refer to.
  491.  
  492. * COMMON is a type of memory area supported by FORTRAN.  Each
  493.   module's chunk of a COMMON segment starts at location 0, and
  494.   overlaps (usually duplicates) the pieces from all the other
  495.   modules.  The size of a COMMON segment is the size of the
  496.   largest chunk.
  497.  
  498. * MEMORY is supposed to be another kind of COMMON segment, that
  499.   is distinguished by automatically being located beyond all
  500.   other segments in memory.  The MS_DOS LINK program, however,
  501.   does not implement MEMORY segments, and instead treats them
  502.   identically to PUBLIC (not COMMON!) segments.  I can see no
  503.   useful purpose to the MEMORY combine type, since the
  504.   functionality can be achieved by putting a COMMON segment into
  505.   a 'class' by itself, that goes above all the other classes.  So
  506.   don't use MEMORY.
  507.  
  508.   Sorry, I don't support the assembly of multiple files written
  509.   for other assemblers, that contain STACK, COMMON, or MEMORY
  510.   segments.  If I did, I would have to detect the file breaks,
  511.   and duplicate the overlapping functionality of these segment
  512.   types.  Since I don't think anybody out there is using these
  513.   esoteric types, I didn't bother to support them to that extent.
  514.   Objections, anyone?
  515.  
  516. * "AT number" defines a non-combinable segment at the absolute
  517.   memory location whose segment register value is "number".  This
  518.   form is useful for initializing data in fixed locations, such
  519.   as the 86 interrupt vector (IVECTOR SEGMENT AT 0 followed by
  520.   ORG 4 * INT_NUMBER), or for reading fixed memory locations,
  521.   such as the BIOS variables area (BIOS_DATA SEGMENT AT 040).
  522.  
  523. The combine type specification can be repeated in subsequent
  524. pieces of a given segment, but if it is, it must be the same in
  525. all pieces.
  526.  
  527. Finally, if no combine type is ever given for a named segment in
  528. a module, that segment is non-combinable-- no other modules may
  529. define that segment; the code given in the one module constitutes
  530. the entire segment.
  531.                                                             10-11
  532.  
  533. The last specification available on a SEGMENT line is the class
  534. name, which is identified by being enclosed in single quotes.
  535. Unlike a segment name, which can be used as an instruction
  536. operand and hence cannot conflict with other assembler symbols, a
  537. class name can be assigned without regard to its usage elsewhere
  538. in the program.  It can even be a built-in A86 mnemonic.  In
  539. fact, both the SMALL and LARGE high-level-language models specify
  540. the class name 'CODE' for code segments, and the SMALL model
  541. specifies the class name 'DATA'.
  542.  
  543. If no class name is given for a segment, A86 specifies the null
  544. (zero length) string as the class name.
  545.  
  546.  
  547. DATA SEGMENT, STRUC and CODE SEGMENT Directives
  548.  
  549. The DATA SEGMENT and STRUC directives work in .OBJ mode exactly
  550. as they do in .COM mode-- they define a special assembly mode, in
  551. which declarations are made, but no object code is output.
  552. Offsets within DATA segments and structures are absolute, as in
  553. .COM mode.  Assembly resumes as before when an ENDS or CODE
  554. SEGMENT directive is encountered.
  555.  
  556. For MASM compatibility (especially in modules written to link to
  557. Turbo Pascal V4.0 programs), I now recognize the reserved symbols
  558. CODE, DATA, and STACK as ordinary relocatable segment names.  The
  559. ordinary functionality takes effect whenever a SEGMENT directive
  560. is given with CODE, DATA or STACK as the segment name, and with
  561. one or more relocatable parameters (e.g., PUBLIC) given after
  562. SEGMENT.
  563.  
  564.  
  565. The ENDS Directive
  566.  
  567. Syntax:  [seg_name] ENDS
  568.  
  569. The ENDS directive closes out the segment currently being
  570. assembled, and returns assembly to the segment being assembled
  571. before the last SEGMENT directive.  The "seg_name", if given,
  572. must match the name in that last SEGMENT directive.  ENDS allows
  573. you to "nest" segments inside one another.  For example, you can
  574. declare some static data variables that are specific to a certain
  575. section of code at the top of that section:
  576.  
  577.   _DATA SEGMENT BYTE PUBLIC 'DATA'
  578.       VAR1  DB ?
  579.       VAR2  DB ?
  580.   _DATA ENDS
  581.  
  582. These four lines can be inserted inside any other segment being
  583. assembled.  They will cause the two variable allocations to be
  584. tacked onto the segment _DATA; and assembly will then continue in
  585. whatever segment surrounded the four lines.  Observe that the
  586. "nesting" does not occur in the final program; only the
  587. presentation of the source code is nested.
  588.                                                             10-12
  589.  
  590. If you are not nesting segments inside one another, then the ENDS
  591. directive serves only to lend a clean, "block-structured"
  592. appearance to your source code.  It does not assist A86 in any
  593. particular way; in fact, it consumes a bit more object output
  594. memory (slightly reducing object output capacity) if you have
  595. ENDSs, rather than just starting up new segments with SEGMENT
  596. directives.
  597.  
  598.  
  599. Default Outer SEGMENT
  600.  
  601. Other assemblers outlaw any code outside of a SEGMENT
  602. declaration, forcing you to give a SEGMENT declaration before you
  603. can assemble anything.  A86 lets you assemble just your code; you
  604. don't have to worry about SEGMENTs if you don't want to.
  605.  
  606. If you do provide code outside of all SEGMENT declarations, A86
  607. performs the following steps, to find a reasonable place to put
  608. the code:
  609.  
  610. 1. If there are any segments explicitly declared whose name is or
  611.    ends with "_TEXT", then the first such segment declared is
  612.    used.  It is as if the SEGMENT declaration appeared at the top
  613.    of, rather than within, the program.
  614.  
  615. 2. If there is no such explicit segment, A86 creates a BYTE
  616.    PUBLIC segment of class 'CODE', and proceeds to construct a
  617.    name for the segment.  If there are no RETF instructions in
  618.    the outer segment, the name chosen is "_TEXT", conforming to
  619.    the SMALL model of computation.  If there is a RETF
  620.    instruction, the name chosen is "modulename_TEXT", where
  621.    "modulename" is the name of this module.  Recall that
  622.    "modulename" comes from the NAME directive if there is one;
  623.    from the name of the .OBJ file if there isn't.
  624.  
  625.  
  626. The GROUP Directive
  627.  
  628. Syntax:  group_name GROUP seg_name1, seg_name2, ...
  629.  
  630. The GROUP directive causes A86 to tell LINK that all the listed
  631. segments can fit into a single 64K-byte block of memory, and
  632. instruct LINK to make that fit.  (If they won't fit, LINK will
  633. issue an error message.)  Having declared the group, you can then
  634. use "group_name" as the segment register value that will allow
  635. simultaneous access to all the named segments.  The order of
  636. names given in the list does not necessarily determine the order
  637. in which the segments will finally appear within the group.
  638.  
  639. The most useful application of the GROUP directive is to allow
  640. you to structure the pieces of a program, all of whose code and
  641. data will fit into a single 64K segment.  You organize the pieces
  642. into SEGMENTs, and declare all the SEGMENTs to be within the same
  643. GROUP.  When the program starts, all segment registers are set to
  644. point to the GROUP, and you never have to worry about segment
  645. registers again in the program.
  646.                                                             10-13
  647.  
  648. WARNING: If your segments will be GROUPed in the final program,
  649. you should have the appropriate GROUP directive in every module
  650. assembled.  If you don't, then any memory pointers generated will
  651. be relative to the beginning of the individual named segments,
  652. not to the beginning of the whole group.
  653.  
  654. Because of the obscure scenario I described in the Overview
  655. section, Intel does not prohibit more than one GROUP from
  656. containing some of the same segments; so neither does A86.  Any
  657. pointers within a segment will be calculated from the beginning
  658. of the last GROUP within which the segment was declared.  But
  659. again, I have my doubts as to whether LINK will handle this
  660. correctly.
  661.  
  662.  
  663. The SEG Operator
  664.  
  665. Syntax:  SEG operand
  666.  
  667. The SEG operator returns the segment containing its operand-- a
  668. value suitable for loading into one of the segment registers. If
  669. the operand is an explicit far constant such as 01811:0100, the
  670. value returned is the lefthand component of the constant (01811
  671. in this example).  Otherwise, the result depends on A86's output
  672. mode:
  673.  
  674. When A86 is assembling to an OBJ file, the result is the named
  675. relocatable segment containing the operand.  SEG is most useful
  676. when the operand is not defined in this A86 module: in that case,
  677. the segment value will be plugged in by LINK.
  678.  
  679. When A86 is assembling to a COM file, SEG always returns the CS
  680. register, with one exception: symbols declared within a SEGMENT
  681. AT structure return the value of the containing segment.  COM
  682. files have no facility for explicitly specifying relocatable
  683. segments, so for compatibility A86 assumes that all non-absolute
  684. segment references are to the program's segment itself.
  685.  
  686.