home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / assemblr / asm / wasm / io.doc < prev    next >
Text File  |  1988-03-07  |  17KB  |  351 lines
  1.  
  2.  
  3.                               Description of IO.ASM
  4.  
  5.        IO.ASM is an attempt to provide a standard i/o interface for
  6.        assembler applications.  Ways to manipulate strings, read from the
  7.        keyboard, display to the screen, and perform file i/o are defined.
  8.        All of the routines have the following characteristics:
  9.  
  10.          1.  All registers are preserved. (1)
  11.          2.  No segment register values are assumed.
  12.          3.  Parameters are passed on the stack. (1)
  13.  
  14.        (1) A few routines pass parameters in the registers.
  15.  
  16.        The above characteristics make the routines very flexible.  For
  17.        instance, when calling them, the programmer does not have to worry
  18.        about setting up the segment registers or destroying uninvolved
  19.        registers.
  20.  
  21.        The flags are not necessarily preserved (except for the special
  22.        system flags, i.e. interrupt enable and single step interrupt).
  23.        The only significant flag that might be modified is the direction
  24.        flag (DF), which is sometimes cleared.
  25.  
  26.        The routines, as stated above, receive their parameters on the
  27.        stack.  This means that the parameters must be pushed on the stack
  28.        in the proper order before calling the routine.  Parameters are
  29.        also returned on the stack.  The Intel 8086 user's manual does not
  30.        recommended returning parameters on the stack, but it works too
  31.        conveniently to ignore.  Note that if parameters are returned on
  32.        the stack, they will have to be removed before any data below them
  33.        is accessible.  Because the stack is used so extensively, the
  34.        program using these routines should have a good sized stack
  35.        available, say no less than 200 bytes for IO.ASM plus any extra
  36.        needed by your program.
  37.  
  38.        Two different types of strings are defined by IO.ASM.  The first
  39.        is a sequence of characters preceded by a length byte.  The
  40.        advantages of this kind of string are that it can contain any
  41.        characters and be manipulated quickly.  The disadvantages are that
  42.        it is limited to a length of 255 characters and that it is more
  43.        trouble to declare (since you must count its characters and
  44.        manually specify its length).  The other string type is a sequence
  45.        of characters terminated by a byte 00.  This kind of string may be
  46.        any length and is easier to declare, but it can't contain byte
  47.        00's and is more trouble to manipulate.  The second type of string
  48.        is only used by routines that open, create, or delete files.
  49.  
  50.  
  51.        The following is a program fragment using the IO.ASM routines to
  52.        combine two strings and then display the result:
  53.  
  54.          ;put the location of DATA on the stack (destination)
  55.            Mov Ax, Offset Data  ;get offset of storage
  56.            Push Ax              ;put offset on stack
  57.            Push Cs              ;put segment on stack
  58.          ;
  59.          ;put first part of message on stack (source)
  60.            Mov Ax, Offset Mess1 ;get string offset
  61.            Push Ax              ;put offset on stack
  62.            Push Cs              ;put segment on stack
  63.          ;
  64.          ;copy the first part of the messge to DATA, note the
  65.          ;destination (location of DATA) is returned on the stack
  66.            Call Copy_Str_P             ;copy string to work area
  67.          ;
  68.          ;put second part of message on stack
  69.            Mov Ax, Offset Mess2 ;get string offset
  70.            Push Ax              ;put offset on stack
  71.            Push Cs              ;put segment on stack
  72.          ;
  73.          ;append second part of the messge to the first part,
  74.          ;the destination is returned on the stack
  75.            Call Append_Str_P   ;append string
  76.          ;
  77.          ;now display the string in DATA to the screen, the display
  78.          ;routine does not return the string location, thus the stack
  79.          ;is back to its original state
  80.            Call Display_Str_P  ;show string
  81.  
  82.  
  83.          Mess1 Db 12,'Squares are '    ;first part of message
  84.          Mess2 Db 11,'not round. '     ;second part of message
  85.          Data  Ds 256                  ;work area
  86.  
  87.                Include 'Io.Asm'        ;include procedure definitions
  88.  
  89.  
  90.                               Description of IO.MAC
  91.  
  92.        IO.MAC is set of macro definitions designed to make the use of
  93.        IO.ASM easier.  Generally speaking, there is a macro for each
  94.        routine or set of routines in IO.ASM.
  95.  
  96.        The one restriction that exists with IO.MAC is that the BP
  97.        register is not preserved and cannot be used to pass parameters,
  98.        as it is sometimes used to set up the parameters that are passed
  99.        to IO.ASM.
  100.  
  101.        With the macros defined in IO.MAC, the example for IO.ASM above
  102.        could be more easily written:
  103.  
  104.            Copy Data,,Mess1    ;copy first part of message to DATA
  105.            Append Data,,Mess2  ;copy second part of message to DATA
  106.            Display Data        ;display message
  107.  
  108.          Mess1 Db 12,'Squares are '    ;first part of message
  109.          Mess2 Db 11,'not round. '     ;second part of message
  110.          Data  Ds 256                  ;work area
  111.  
  112.                Include 'Io.Asm'        ;include the procedures
  113.                Include 'Io.Mac'        ;include the macros
  114.  
  115.  
  116.                   Description of Runtime Library Implementation
  117.  
  118.        WASM does not produce true object files.  To work around this
  119.        drawback, a software implementation for a runtime library is
  120.        provided.  The advantages of a runtime library are that a single
  121.        library can be used by many different programs (thus reducing
  122.        redundant code), and the library source code need not be
  123.        reassembled each time the program is reassembled (thus saving
  124.        time).  The only disadvantage to a runtime library is that the
  125.        application must be able to find and load the library during
  126.        execution.
  127.  
  128.        The goal of this runtime library implementation is to be able to
  129.        do is something like CALL SUBRT, where SUBRT is a near procedure
  130.        in a separately assembled file.  The interface should be
  131.        transparent, i.e. we want be able to pass parameters on the stack
  132.        or in registers to and from the routine.  This particular
  133.        implementation does not allow the flags to be passed to routines,
  134.        though it does allow flags to be returned.  Also, there is no
  135.        convenient way to directly access global data across the
  136.        interface, which doesn't really matter too much, since data is
  137.        normally passed in registers or on the stack.
  138.  
  139.        Three major components are needed to implement this runtime
  140.        library: a routine redirection table, the dispatch code, and the
  141.        library code.  The redirection table is made up of substitution
  142.        procedure headings, which make the program think that the
  143.        procedures have been declared within it.  The dispatch code is the
  144.        program half of the interface, and the library code is the library
  145.        half of the interface.  The basic sequence of events is as
  146.        follows: the redirection table accepts the initial procedural call
  147.        and sets a routine index and library information, then passes
  148.        control to the dispatcher code; the dispatcher code loads the
  149.        library (if it hasn't already been loaded) and passes control and
  150.        the routine index to the library code; the library code fixes up
  151.        the stack, finds and executes the routine (based on the index),
  152.        and returns directly back to the point where the routine was
  153.        originally called.
  154.  
  155.        A redirection table is defined for each library (the redirection
  156.        table for IO.ASM is IO.RED) and must be included in the program.
  157.        The dispatcher code is in DISPATCH.ASM and must also be included
  158.        in the program.  The library code is in LIBRARY.ASM and must be
  159.        included at the start of the library file.
  160.  
  161.        To use IO.ASM as a runtime library, just include the following
  162.        statements in your program:
  163.  
  164.            Include 'IO.RED'
  165.            Include 'DISPATCH.ASM'
  166.  
  167.  
  168.        The dispatch code automatically loads the library into a specially
  169.        allocated block of memory during execution.  When a .COM program
  170.        is loaded, all free memory is allocated to it, thus the program
  171.        must explicitly free some memory before calling any routines
  172.        defined in the library.  The most efficient way to do this with
  173.        the following code:
  174.  
  175.          ;--beginning of program, assume SS = ES = CS
  176.            Mov Bx, Offset Progend ;get offset of end code and data
  177.            Mov Sp, Bx          ;new top of stack
  178.            Mov Cl, 4           ;bits to shift
  179.            Shr Bx, Cl          ;perform shift, make paragraph form
  180.            Inc Bx              ;account for possible odd paragraph
  181.            Mov Ah, 4ah         ;DOS reallocation function number
  182.            Int 21h             ;execute
  183.             :
  184.             :                  ;program and data
  185.             :
  186.            Org +250            ;make room for stack
  187.          Progend               ;absolute end of program and data
  188.          ;--end of program
  189.  
  190.        This code works by calculating the actual number of bytes used by
  191.        the program and then reducing the present memory allocation to
  192.        just those bytes.  Since the default stack will probably be
  193.        outside of the allocated memory, the stack must be moved.  In this
  194.        case, the offset of the end of the program is increased with the
  195.        ORG statement to allow for a stack of that size and the stack
  196.        place immediately after the program.
  197.  
  198.        Assuming that IO.ASM has been assembled to a library file called
  199.        IO.BIN, the program now can use all the routines declared in
  200.        IO.ASM, just as if they had been declared in the program itself.
  201.        Incidentally, the name of the library, IO.BIN, is defined in the
  202.        redirection table, IO.RED.  SOUND.ASM is a sample program that
  203.        actually uses the IO.BIN runtime library.
  204.  
  205.        To create a runtime library, all you have to do is write the
  206.        procedures contained within the library and then write the
  207.        redirection table (it could be a separate file or placed right in
  208.        the program).
  209.  
  210.        A runtime library is differentiated from a normal program only by
  211.        its library header and the last byte being a negative checksum.
  212.        The first part of the library header is contained in the file
  213.        LIBRARY.ASM (the library code).  The second part of the header is
  214.        a sequential list of offsets that point to the routines to be
  215.        accessed.  The library code finds the routine by indexing into
  216.        this list of offsets.  The first offset is index zero, the second
  217.        is index one, etc.
  218.  
  219.  
  220.        The following is the source code for an example runtime library
  221.        that contains the routines SUB1 and SUB2:
  222.  
  223.          ;**********************************
  224.          ;=== library header ==============;----- this is required
  225.                                            ;      for a library, must
  226.          ;--- library code --------------- ;      come at start
  227.                                            ;
  228.                Include 'Library.Asm'       ;
  229.                                            ;
  230.         ;--- offsets to subroutines ------ ;
  231.                                            ;
  232.                Dw  Offset Sub1             ;
  233.                Dw  Offset Sub2             ;
  234.  
  235.          ;=== body of library =============;----- these are just
  236.                                            ;      standard procedure
  237.          ;--- procedure SUB1 ------------- ;      declarations
  238.                                            ;
  239.                Sub1  Proc Near             ;
  240.                 :                          ;
  241.           <procedure body>                 ;
  242.                 :                          ;
  243.                Ret                         ;
  244.                Endp    ;Sub1               ;
  245.                                            ;
  246.          ;--- procedure SUB2 ------------- ;
  247.                                            ;
  248.                Sub2  Proc Near             ;
  249.                 :                          ;
  250.           <procedure body>                 ;
  251.                 :                          ;
  252.                Ret                         ;
  253.                Endp    ;Sub1               ;
  254.  
  255.          ;=== library checksum ============;----- this is required
  256.                                            ;      for a library
  257.                Db  Neg $Chksum             ;
  258.          ;**********************************
  259.  
  260.        The redirection table and dispatch code must exist within the
  261.        program that's using the library.  The redirection table accepts
  262.        control after the CALL instruction and then passes control to the
  263.        dispatch code.  For each routine defined in the library, there
  264.        must be a label in the redirection table.  Once in the redirection
  265.        table, the BX register is pushed on the stack, the routine index
  266.        is loaded into BL, and the program jumps to a the redirection
  267.        table DISPATCH statement.  The DISPATCH statement is a macro that
  268.        defines the library file name and passes control to the the
  269.        dispatch code.  The DISPATCH macro and the dispatch code are both
  270.        contained in DISPATCH.ASM.  The index in BL is passed directly to
  271.        the library code to find the routine.  A redirection table is
  272.        needed for each runtime library being accessed, though only one
  273.        copy of DISPATCH.ASM is needed for any number of redirection
  274.        tables.
  275.  
  276.  
  277.        The following is a program that makes use of the example library
  278.        above.  It assumes that the library has been assembled to
  279.        SAMP.BIN:
  280.  
  281.          ;**********************************
  282.          ;=== body of program =============;
  283.                                            ;
  284.          ;--- reduce memory allocation --- ;
  285.                                            ;
  286.                Mov Ah, 4ah     ;function number
  287.                Mov Bx, 100h    ;get whole segment (includes stack)
  288.                Int 21h         ;execute, reduce allocation
  289.                                            ;
  290.          ;--- main program --------------- ;
  291.                                            ;
  292.                 :                          ;
  293.                Call Sub1       ;access external SUB1, etc.
  294.                 :                          ;
  295.                Call Sub2       ;access external SUB2, etc.
  296.                 :                          ;
  297.  
  298.          ;=== redirection table ===========;
  299.                                            ;
  300.          ;--- procedure substitutions ---- ;
  301.                                            ;
  302.          Sub1  Push Bx                     ;
  303.                Mov Bl, 0  ;set index, first offset in library header
  304.                Jmp Process                 ;
  305.          Sub2  Push Bx                     ;
  306.                Mov Bl, 1  ;set index, second offset in library header
  307.                Jmp Process                 ;
  308.                                            ;
  309.          ;--- transfer to dispatch ------- ;
  310.                                            ;
  311.          Process                           ;
  312.                Dispatch 'SAMP.BIN' ;specify library file name
  313.  
  314.          ;=== dispatch code ===============;
  315.                                            ;
  316.                Include 'Dispatch.Asm'      ;
  317.          ;**********************************
  318.  
  319.  
  320.        The dispatch code checks for several possible errors that can
  321.        occur when using a runtime library.  If an error is detected, a
  322.        message will be displayed and the program will be terminated.  The
  323.        error message contains a number that specifies the type of error,
  324.        which are as follows:
  325.  
  326.          Error
  327.          Number  Meaning
  328.          -----   --------------------------------------------------------
  329.           01     Could not allocate memory.  Not enough free memory is
  330.                  available to load the library.  Probably means that you
  331.                  forgot to reduce the initial memory allocation.
  332.  
  333.           02     Could not open library file.  Probably means that the
  334.                  library file was not found.  The name of the file to
  335.                  look for (including a drive and path) can be changed in
  336.                  the redirection table.
  337.  
  338.           03     Incompatible library version.  The library
  339.                  implementation version is incompatible with the
  340.                  dispatcher implementation version.  The library or
  341.                  dispatcher should be updated and reassembled.
  342.  
  343.           04     Error in library file. The library has an incorrect
  344.                  format or contains some other error, like a bad or
  345.                  nonexistent header or checksum.
  346.  
  347.           05     Unknown error.  Some kind of internal error or
  348.                  something.  This error should not normally happen.
  349.  
  350.  
  351.