"Fossies" - the Fresh Open Source Software Archive

Member "fasm/tools/fas.txt" (9 Feb 2020, 23496 Bytes) of package /linux/misc/fasm-1.73.22.tgz:


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

    1 
    2                                 flat assembler
    3                        Symbolic information file format
    4 
    5 
    6    Table 1  Header
    7   /-------------------------------------------------------------------------\
    8   | Offset | Size    | Description                                          |
    9   |========|=========|======================================================|
   10   |   +0   |  dword  | Signature 1A736166h (little-endian).                 |
   11   |--------|---------|------------------------------------------------------|
   12   |   +4   |  byte   | Major version of flat assembler.                     |
   13   |--------|---------|------------------------------------------------------|
   14   |   +5   |  byte   | Minor version of flat assembler.                     |
   15   |--------|---------|------------------------------------------------------|
   16   |   +6   |  word   | Length of header.                                    |
   17   |--------|---------|------------------------------------------------------|
   18   |   +8   |  dword  | Offset of input file name in the strings table.      |
   19   |--------|---------|------------------------------------------------------|
   20   |  +12   |  dword  | Offset of output file name in the strings table.     |
   21   |--------|---------|------------------------------------------------------|
   22   |  +16   |  dword  | Offset of strings table.                             |
   23   |--------|---------|------------------------------------------------------|
   24   |  +20   |  dword  | Length of strings table.                             |
   25   |--------|---------|------------------------------------------------------|
   26   |  +24   |  dword  | Offset of symbols table.                             |
   27   |--------|---------|------------------------------------------------------|
   28   |  +28   |  dword  | Length of symbols table.                             |
   29   |--------|---------|------------------------------------------------------|
   30   |  +32   |  dword  | Offset of preprocessed source.                       |
   31   |--------|---------|------------------------------------------------------|
   32   |  +36   |  dword  | Length of preprocessed source.                       |
   33   |--------|---------|------------------------------------------------------|
   34   |  +40   |  dword  | Offset of assembly dump.                             |
   35   |--------|---------|------------------------------------------------------|
   36   |  +44   |  dword  | Length of assembly dump.                             |
   37   |--------|---------|------------------------------------------------------|
   38   |  +48   |  dword  | Offset of section names table.                       |
   39   |--------|---------|------------------------------------------------------|
   40   |  +52   |  dword  | Length of section names table.                       |
   41   |--------|---------|------------------------------------------------------|
   42   |  +56   |  dword  | Offset of symbol references dump.                    |
   43   |--------|---------|------------------------------------------------------|
   44   |  +60   |  dword  | Length of symbol references dump.                    |
   45   \-------------------------------------------------------------------------/
   46 
   47   Notes:
   48 
   49     If header is shorter than 64 bytes, it comes from a version that does not
   50     support dumping some of the structures. It should then be interpreted
   51     that the data for missing structures could not be provided, not that the
   52     size of that data is zero.
   53 
   54     Offsets given in header generally mean positions in the file, however
   55     input and output file names are specified by offsets in the strings table,
   56     so you have to add their offset to the offset of strings table to obtain
   57     the positions of those strings in the file.
   58 
   59     The strings table contains just a sequence of ASCIIZ strings, which may
   60     be referred to by other parts of the file. It contains the names of
   61     main input file, the output file, and the names of the sections and
   62     external symbols if there were any.
   63 
   64     The symbols table is an array of 32-byte structures, each one in format
   65     specified by table 2.
   66 
   67     The preprocessed source is a sequence of preprocessed lines, each one
   68     in format as defined in table 3.
   69 
   70     The assembly dump contains an array of 28-byte structures, each one in
   71     format specified by table 4, and at the end of this array an additional
   72     double word containing the offset in output file at which the assembly
   73     was ended.
   74 
   75     It is possible that file does not contain assembly dump at all - this
   76     happens when some error occured and only the preprocessed source was
   77     dumped. If error occured during the preprocessing, only the source up to
   78     the point of error is provided. In such case (and only then) the field
   79     at offset 44 contains zero.
   80 
   81     The section names table exists only when the output format was an object
   82     file (ELF or COFF), and it is an array of 4-byte entries, each being an
   83     offset of the name of the section in the strings table.
   84     The index of section in this table is the same, as the index of section
   85     in the generated object file.
   86 
   87     The symbol references dump contains an array of 8-byte structures, each
   88     one describes an event of some symbol being used. The first double word
   89     of such structure contains an offset of symbol in the symbols table,
   90     and the second double word is an offset of structure in assembly dump,
   91     which specifies at what moment the symbol was referenced.
   92 
   93 
   94    Table 2  Symbol structure
   95   /-------------------------------------------------------------------------\
   96   | Offset | Size  | Description                                            |
   97   |========|=======|========================================================|
   98   |   +0   | qword | Value of symbol.                                       |
   99   |--------|-------|--------------------------------------------------------|
  100   |   +8   | word  | Flags (table 2.1).                                     |
  101   |--------|-------|--------------------------------------------------------|
  102   |  +10   | byte  | Size of data labelled by this symbol (zero means plain |
  103   |        |       | label without size attached).                          |
  104   |--------|-------|--------------------------------------------------------|
  105   |  +11   | byte  | Type of value (table 2.2). Any value other than zero   |
  106   |        |       | means some kind of relocatable symbol.                 |
  107   |--------|-------|--------------------------------------------------------|
  108   |  +12   | dword | Extended SIB, the first two bytes are register codes   |
  109   |        |       | and the second two bytes are corresponding scales.     |
  110   |--------|-------|--------------------------------------------------------|
  111   |  +16   | word  | Number of pass in which symbol was defined last time.  |
  112   |--------|-------|--------------------------------------------------------|
  113   |  +18   | word  | Number of pass in which symbol was used last time.     |
  114   |--------|-------|--------------------------------------------------------|
  115   |  +20   | dword | If the symbol is relocatable, this field contains      |
  116   |        |       | information about section or external symbol, to which |
  117   |        |       | it is relative - otherwise this field has no meaning.  |
  118   |        |       | When the highest bit is cleared, the symbol is         |
  119   |        |       | relative to a section, and the bits 0-30 contain       |
  120   |        |       | the index (starting from 1) in the table of sections.  |
  121   |        |       | When the highest bit is set, the symbol is relative to |
  122   |        |       | an external symbol, and the bits 0-30 contain the      |
  123   |        |       | the offset of the name of this symbol in the strings   |
  124   |        |       | table.                                                 |
  125   |--------|-------|--------------------------------------------------------|
  126   |  +24   | dword | If the highest bit is cleared, the bits 0-30 contain   |
  127   |        |       | the offset of symbol name in the preprocessed source.  |
  128   |        |       | This name is a pascal-style string (byte length        |
  129   |        |       | followed by string data).                              |
  130   |        |       | Zero in this field means an anonymous symbol.          |
  131   |        |       | If the highest bit is set, the bits 0-30 contain the   |
  132   |        |       | offset of the symbol name in the strings table, and    |
  133   |        |       | this name is a zero-ended string in this case (as are  |
  134   |        |       | all the strings there).                                |
  135   |--------|-------|--------------------------------------------------------|
  136   |  +28   | dword | Offset in the preprocessed source of line that defined |
  137   |        |       | this symbol (see table 3).                             |
  138   \-------------------------------------------------------------------------/
  139 
  140 
  141    Table 2.1  Symbol flags
  142   /-----------------------------------------------------------------\
  143   | Bit | Value | Description                                       |
  144   |=====|=======|===================================================|
  145   |  0  |     1 | Symbol was defined.                               |
  146   |-----|-------|---------------------------------------------------|
  147   |  1  |     2 | Symbol is an assembly-time variable.              |
  148   |-----|-------|---------------------------------------------------|
  149   |  2  |     4 | Symbol cannot be forward-referenced.              |
  150   |-----|-------|---------------------------------------------------|
  151   |  3  |     8 | Symbol was used.                                  |
  152   |-----|-------|---------------------------------------------------|
  153   |  4  |   10h | The prediction was needed when checking           |
  154   |     |       | whether the symbol was used.                      |
  155   |-----|-------|---------------------------------------------------|
  156   |  5  |   20h | Result of last predicted check for being used.    |
  157   |-----|-------|---------------------------------------------------|
  158   |  6  |   40h | The prediction was needed when checking           |
  159   |     |       | whether the symbol was defined.                   |
  160   |-----|-------|---------------------------------------------------|
  161   |  7  |   80h | Result of last predicted check for being defined. |
  162   |-----|-------|---------------------------------------------------|
  163   |  8  |  100h | The optimization adjustment is applied to         |
  164   |     |       | the value of this symbol.                         |
  165   |-----|-------|---------------------------------------------------|
  166   |  9  |  200h | The value of symbol is negative number encoded    |
  167   |     |       | as two's complement.                              |
  168   |-----|-------|---------------------------------------------------|
  169   | 10  |  400h | Symbol is a special marker and has no value.      |
  170   \-----------------------------------------------------------------/
  171 
  172   Notes:
  173 
  174     Some of those flags are listed here just for completness, as they
  175     have little use outside of the flat assembler. However the bit 0
  176     is important, because the symbols table contains all the labels
  177     that occured in source, even if some of them were in the
  178     conditional blocks that did not get assembled.
  179 
  180 
  181    Table 2.2  Symbol value types
  182   /-------------------------------------------------------------------\
  183   | Value | Description                                               |
  184   |=======|===========================================================|
  185   |   0   | Absolute value.                                           |
  186   |-------|-----------------------------------------------------------|
  187   |   1   | Relocatable segment address (only with MZ output).        |
  188   |-------|-----------------------------------------------------------|
  189   |   2   | Relocatable 32-bit address.                               |
  190   |-------|-----------------------------------------------------------|
  191   |   3   | Relocatable relative 32-bit address (value valid only for |
  192   |       | symbol used in the same place where it was calculated,    |
  193   |       | it should not occur in the symbol structure).             |
  194   |-------|-----------------------------------------------------------|
  195   |   4   | Relocatable 64-bit address.                               |
  196   |-------|-----------------------------------------------------------|
  197   |   5   | [ELF only] GOT-relative 32-bit address.                   |
  198   |-------|-----------------------------------------------------------|
  199   |   6   | [ELF only] 32-bit address of PLT entry.                   |
  200   |-------|-----------------------------------------------------------|
  201   |   7   | [ELF only] Relative 32-bit address of PLT entry (value    |
  202   |       | valid only for symbol used in the same place where it     |
  203   |       | was calculated, it should not occur in the symbol         |
  204   |       | structure).                                               |
  205   \-------------------------------------------------------------------/
  206 
  207   Notes:
  208 
  209     The types 3 and 7 should never be encountered in the symbols dump,
  210     they are only used internally by the flat assembler.
  211 
  212     If type value is a negative number, it is an opposite of a value
  213     from this table and it means that the symbol of a given type has
  214     been negated.
  215 
  216 
  217    Table 2.3  Register codes for extended SIB
  218   /------------------\
  219   | Value | Register |
  220   |=======|==========|
  221   |  23h  | BX       |
  222   |-------|----------|
  223   |  25h  | BP       |
  224   |-------|----------|
  225   |  26h  | SI       |
  226   |-------|----------|
  227   |  27h  | DI       |
  228   |-------|----------|
  229   |  40h  | EAX      |
  230   |-------|----------|
  231   |  41h  | ECX      |
  232   |-------|----------|
  233   |  42h  | EDX      |
  234   |-------|----------|
  235   |  43h  | EBX      |
  236   |-------|----------|
  237   |  44h  | ESP      |
  238   |-------|----------|
  239   |  45h  | EBP      |
  240   |-------|----------|
  241   |  46h  | ESI      |
  242   |-------|----------|
  243   |  47h  | EDI      |
  244   |-------|----------|
  245   |  48h  | R8D      |
  246   |-------|----------|
  247   |  49h  | R9D      |
  248   |-------|----------|
  249   |  4Ah  | R10D     |
  250   |-------|----------|
  251   |  4Bh  | R11D     |
  252   |-------|----------|
  253   |  4Ch  | R12D     |
  254   |-------|----------|
  255   |  4Dh  | R13D     |
  256   |-------|----------|
  257   |  4Eh  | R14D     |
  258   |-------|----------|
  259   |  4Fh  | R15D     |
  260   |-------|----------|
  261   |  80h  | RAX      |
  262   |-------|----------|
  263   |  81h  | RCX      |
  264   |-------|----------|
  265   |  82h  | RDX      |
  266   |-------|----------|
  267   |  83h  | RBX      |
  268   |-------|----------|
  269   |  84h  | RSP      |
  270   |-------|----------|
  271   |  85h  | RBP      |
  272   |-------|----------|
  273   |  86h  | RSI      |
  274   |-------|----------|
  275   |  87h  | RDI      |
  276   |-------|----------|
  277   |  88h  | R8       |
  278   |-------|----------|
  279   |  89h  | R9       |
  280   |-------|----------|
  281   |  8Ah  | R10      |
  282   |-------|----------|
  283   |  8Bh  | R11      |
  284   |-------|----------|
  285   |  8Ch  | R12      |
  286   |-------|----------|
  287   |  8Dh  | R13      |
  288   |-------|----------|
  289   |  8Eh  | R14      |
  290   |-------|----------|
  291   |  8Fh  | R15      |
  292   |-------|----------|
  293   |  94h  | EIP      |
  294   |-------|----------|
  295   |  98h  | RIP      |
  296   \------------------/
  297 
  298 
  299    Table 3  Preprocessed line
  300   /--------------------------------------------------------------------------\
  301   | Offset | Size  | Value                                                   |
  302   |========|=================================================================|
  303   |   +0   | dword | When the line was loaded from source, this field        |
  304   |        |       | contains either zero (if it is the line from the main   |
  305   |        |       | input file), or an offset inside the preprocessed       |
  306   |        |       | source to the name of file, from which this line was    |
  307   |        |       | loaded (the name of file is zero-ended string).         |
  308   |        |       | When the line was generated by macroinstruction, this   |
  309   |        |       | field contains offset inside the preprocessed source to |
  310   |        |       | the pascal-style string specifying the name of          |
  311   |        |       | macroinstruction, which generated this line.            |
  312   |--------|-------|---------------------------------------------------------|
  313   |   +4   | dword | Bits 0-30 contain the number of this line.              |
  314   |        |       | If the highest bit is zeroed, this line was loaded from |
  315   |        |       | source.                                                 |
  316   |        |       | If the highest bit is set, this line was generated by   |
  317   |        |       | macroinstruction.                                       |
  318   |--------|-------|---------------------------------------------------------|
  319   |   +8   | dword | If the line was loaded from source, this field contains |
  320   |        |       | the position of the line inside the source file, from   |
  321   |        |       | which it was loaded.                                    |
  322   |        |       | If line was generated by macroinstruction, this field   |
  323   |        |       | contains the offset of preprocessed line, which invoked |
  324   |        |       | the macroinstruction.                                   |
  325   |        |       | If line was generated by instantaneous macro, this      |
  326   |        |       | field is equal to the next one.                         |
  327   |--------|-------|---------------------------------------------------------|
  328   |  +12   | dword | If the line was generated by macroinstruction, this     |
  329   |        |       | field contains offset of the preprocessed line inside   |
  330   |        |       | the definition of macro, from which this one was        |
  331   |        |       | generated.                                              |
  332   |--------|-------|---------------------------------------------------------|
  333   |  +16   | ?     | The tokenized contents of line.                         |
  334   \--------------------------------------------------------------------------/
  335 
  336   Notes:
  337 
  338     To determine, whether this is the line loaded from source, or generated by
  339     macroinstruction, you need to check the highest bit of the second double
  340     word.
  341 
  342     The contents of line is no longer a text, which it was in source file,
  343     but a sequence of tokens, ended with a zero byte.
  344     Any chain of characters that aren't special ones, separated from other
  345     similar chains with spaces or some other special characters, is converted
  346     into symbol token. The first byte of this element has the value of 1Ah,
  347     the second byte is the count of characters, followed by this amount of
  348     bytes, which build the symbol.
  349     Some characters have a special meaning, and cannot occur inside the
  350     symbol, they split the symbols and are converted into separate tokens.
  351     For example, if source contains this line of text:
  352 
  353       mov ax,4
  354 
  355     preprocessor converts it into the chain of bytes, shown here with their
  356     hexadecimal values (characters corresponding to some of those values are
  357     placed below the hexadecimal codes):
  358 
  359       1A 03 6D 6F 76 1A 02 61 78 2C 1A 01 34 00
  360             m  o  v        a  x  ,        4
  361 
  362     The third type of token that can be found in preprocessed line is the
  363     quoted text. This element is created from chain of any bytes other than
  364     line breaks that are placed between the single or double quotes in the
  365     original text. First byte of such element is always 22h, it is followed
  366     by double word which specifies the number of bytes that follow, and the
  367     value of quoted text comes next. For example, this line from source:
  368 
  369       mov eax,'ABCD'
  370 
  371     is converted into (the notation used is the same as in previous sample):
  372 
  373       1A 03 6D 6F 76 1A 03 65 61 78 2C 22 04 00 00 00 41 42 43 44 00
  374             m  o  v        e  a  x  ,                 A  B  C  D
  375 
  376     This data defines two symbols followed by symbol character, quoted text
  377     and zero byte that marks end of line.
  378     There is also a special case of symbol token with first byte having the
  379     value 3Bh instead of 1Ah, such symbol means that all the line elements
  380     that follow, including this one, have already been interpreted by
  381     preprocessor and are ignored by assembler.
  382 
  383 
  384    Table 4  Row of the assembly dump
  385   /-------------------------------------------------------------------------\
  386   | Offset | Size  | Description                                            |
  387   |========|=======|========================================================|
  388   |   +0   | dword | Offset in output file.                                 |
  389   |--------|-------|--------------------------------------------------------|
  390   |   +4   | dword | Offset of line in preprocessed source.                 |
  391   |--------|-------|--------------------------------------------------------|
  392   |   +8   | qword | Value of $ address.                                    |
  393   |--------|-------|--------------------------------------------------------|
  394   |  +16   | dword | Extended SIB for the $ address, the first two bytes    |
  395   |        |       | are register codes and the second two bytes are        |
  396   |        |       | corresponding scales.                                  |
  397   |--------|-------|--------------------------------------------------------|
  398   |  +20   | dword | If the $ address is relocatable, this field contains   |
  399   |        |       | information about section or external symbol, to which |
  400   |        |       | it is relative - otherwise this field is zero.         |
  401   |        |       | When the highest bit is cleared, the address is        |
  402   |        |       | relative to a section, and the bits 0-30 contain       |
  403   |        |       | the index (starting from 1) in the table of sections.  |
  404   |        |       | When the highest bit is set, the address is relative   |
  405   |        |       | to an external symbol, and the bits 0-30 contain the   |
  406   |        |       | the offset of the name of this symbol in the strings   |
  407   |        |       | table.                                                 |
  408   |--------|-------|--------------------------------------------------------|
  409   |  +24   | byte  | Type of $ address value (as in table 2.2).             |
  410   |--------|-------|--------------------------------------------------------|
  411   |  +25   | byte  | Type of code - possible values are 16, 32, and 64.     |
  412   |--------|-------|--------------------------------------------------------|
  413   |  +26   | byte  | If the bit 0 is set, then at this point the assembly   |
  414   |        |       | was taking place inside the virtual block, and the     |
  415   |        |       | offset in output file has no meaning here.             |
  416   |        |       | If the bit 1 is set, the line was assembled at the     |
  417   |        |       | point, which was not included in the output file for   |
  418   |        |       | some other reasons (like inside the reserved data at   |
  419   |        |       | the end of section).                                   |
  420   |--------|-------|--------------------------------------------------------|
  421   |  +27   | byte  | The higher bits of value of $ address.                 |
  422   \-------------------------------------------------------------------------/
  423 
  424 
  425   Notes:
  426 
  427     Each row of the assembly dump informs, that the given line of preprocessed
  428     source was assembled at the specified address (defined by its type, value
  429     and the extended SIB) and at the specified position in output file.