home *** CD-ROM | disk | FTP | other *** search
/ PC Open 18 / pcopen18_giallo.iso / Msdos / Keybit6 / SOURCE.ZIP / AMIS.DOC < prev    next >
Encoding:
Text File  |  1996-02-22  |  8.0 KB  |  216 lines
  1. # Questo file è una versione ridotta del manuale della libreria AMIS 0.91
  2. # di Ralf Brown.  Sono descritte solo le macro utilizzate in KEYBIT Lite.
  3. #
  4. # La libreria completa è contenuta nel file  AMISL091.???  che può essere
  5. # prelevato da:
  6. #   -  tutti i mirror "SimTel" nella directory /pub/msdos/asmutl
  7. #   -  le migliori BBS FidoNet, tra cui The Bits (2:335/225)
  8. #
  9.  
  10.  
  11.  
  12. Alternate Multiplex Interrupt Specification Library
  13. Public Domain 1992 Ralf Brown
  14. Version 0.91
  15.  
  16.  
  17. To make use of this library, you basically need to do four things:
  18.  
  19.     1. To each source file that will make calls, add
  20.         INCLUDE AMIS.MAC
  21.     2. In the source file containing the program's entry point, add
  22.         @Startup M,NN,SSS
  23.        just after the above INCLUDE and
  24.         @Startup2 <Y>
  25.        at the program's entry point (see below for details).
  26.     3. Change the END line of the main source file to
  27.         END INIT
  28.     4. Link in AMIS.OBJ (assembled from AMIS.ASM) with the rest of
  29.        your object modules.
  30.  
  31.  
  32. ----------------------------------------------------------------------
  33.  
  34. After an INCLUDE AMIS.MAC, the following definitions and macros are available:
  35.  
  36.  
  37. @Startup
  38.     Declare all segments and provide some startup code.
  39.     Usage:    @Startup major,minor,stack
  40.     Arguments:
  41.     major    [opt] the minimum major version of DOS required to run
  42.     minor    [opt] the major minor version of DOS required to run
  43.     stack    [opt] the number of bytes of stack to provide at startup
  44.     Note:
  45.     If either <major> or <minor> is blank, the program will not
  46.     check the DOS version at startup.  If <stack> is blank, a
  47.     default stack of 256 bytes will be provided in memory models
  48.     other than Tiny (there is no stack in Tiny model, so this value
  49.     will be ignored).
  50.  
  51. @Startup2
  52.     Provide additional startup code at the program's actual entry
  53.     point.
  54.     Usage:    @Startup2 psp
  55.     Arguments:
  56.     psp    [opt] if non-blank, allocate a public variable named __psp
  57.     Note:
  58.     <psp> should be blank if some other module (such as the C
  59.     runtime library) provides a public variable named __psp.
  60.  
  61. TGROUP
  62.     Group containing all resident segments in the TSR.
  63.  
  64. TSRcode@
  65. TSRcodeEnd@
  66.     Delimit the code which will remain resident; some of the other
  67.     macros listed below will not function correctly unless within a
  68.     section of code delimited with TSRcode@ and TSRcodeEnd@.
  69.  
  70. DISPLAY_STRING
  71.     Output a '$'-terminated string to standard output via DOS.
  72.     Usage:
  73.     DISPLAY_STRING string,dataseg
  74.     Arguments:
  75.     string    the label of the string to be displayed
  76.     dataseg [opt] the segment of the string
  77.     Example:
  78.     DISPLAY_STRING banner
  79.     ...
  80.     ...
  81.     banner db "FOOBAR (c) 1992 Harry Q Bovik",13,10,"$"
  82.  
  83. # NOTA: la macro seguente è stata modificata.  Ora accetta anche il parametro
  84. #    tsr_code_len che permette di rendere opzionale l'installazione di una
  85. #    parte del codice.
  86. INSTALL_TSR
  87.     Allocate memory for the resident code, copy the resident code to the
  88.     allocated memory, hook all interrupts used by the TSR, optionally
  89.     call an initialization function, and terminate back to DOS.
  90.     Usage:
  91.     INSTALL_TSR tsr_code_len,extra,fit,high,init,if_inst,on_err,more_flags
  92.     Arguments:
  93.     tsr_code_len [opt] length of resident code in bytes
  94.     extra    [opt] number of additional paragraphs needed in resident part
  95.     fit    [opt] FIRST or BEST (default) -fit allocation
  96.     high    [opt] HIGHONLY to only use UMBs, LOWONLY to only use
  97.             conventional memory, TOPMEM to allocate block at high
  98.             end of conventional memory if no UMBs, TOPLOW
  99.             to only use top end of conventional memory
  100.     init    [opt] function to call after installing TSR but before exiting
  101.     if_inst [opt] label to branch to if already installed
  102.     on_err    [opt] label to branch to if unable to install
  103.     more_flags [opt] label of byte containing additional flags to be ORed
  104.            with those automatically set by <fit> and <high>
  105.     Notes:
  106.     If 'init' is specified, the indicated function will be called with
  107.         AX = segment at which TSR was loaded
  108.     If 'if_inst' is specified, the indicated function will be jumped at
  109.         with
  110.         AH = multiplex number
  111.         CX = version number
  112.     The TOPMEM and TOPLOW options are reported to be incompatible with
  113.         Windows 3.0, and will most likely cause a crash if the TSR is
  114.         installed while shelled out from a program using SPAWNO or
  115.         another swapping spawn() replacement.  Then again, anyone who
  116.         attempts to install a TSR while shelled out of another program
  117.         deserves whatever happens.
  118.  
  119. UNINSTALL
  120.     Remove the TSR from memory.
  121.     Usage:
  122.     UNINSTALL on_err
  123.     Arguments:
  124.     on_err      [opt] label to branch to if unable to remove from memory
  125.     Notes:
  126.     If 'on_err' is omitted, check CF after this macro to determine
  127.     whether the removal was successful (CF clear if successful, set
  128.     on error).
  129.  
  130. ISP_HEADER
  131.     Set up the Interrupt Sharing Protocol header for an interrupt.
  132.     Usage:
  133.     ISP_HEADER intr,reset,eoi
  134.     Arguments:
  135.     intr    interrupt number
  136.     reset    [opt] name of routine to perform hardware reset
  137.     eoi    [opt] if nonzero, this is the primary handler for a hardware int
  138.     Exported Labels: (for example "ISP_HEADER 00h,reset_func,0")
  139.     INT00h_handler (public), ORIG_INT00h (public), HWRESET_00h,
  140.     EOI_FLAG_00h
  141.     [in addition, hw_reset_00h would be present for ISP_HEADER 00h,,0]
  142.     Note:
  143.     This macro must be used inside a TSRcode@/TSRcodeEnd@ pair.
  144.     Example:
  145.     ISP_HEADER 21h
  146.         cmp    ah,4Bh    ; provide our own EXEC replacement
  147.         je    exec_call
  148.         jmp    ORIG_INT21h
  149.     exec_call:
  150.         ...
  151.  
  152. HOOKED_INTS
  153.     Declare the interrupts this TSR hooks.
  154.     Usage:
  155.     HOOKED_INTS  int1,int2,...,int32
  156.     Arguments:
  157.     up to 32 interrupt numbers
  158.     Exported Labels:
  159.     $AMIS$HOOKED_INT_LIST (public)
  160.     Notes:
  161.     This macro must be used inside a TSRcode@/TSRcodeEnd@ or
  162.     TSRdata@/TSRdataEnd@ pair.  INT 2Dh need not be listed, as it is
  163.     automatically added to the end of the list of hooked interrupts.
  164.     Examples:
  165.     HOOKED_INTS        ; this TSR hooks only INT 2Dh
  166.     HOOKED_INTS 13h,21h,FFh ; this TSR hooks INTs 13h, 21h, 2Dh, FFh
  167.  
  168. # NOTA: La macro seguente è stata modificata.  Ora include anche l'API
  169. #    di KEYBIT Lite (mettendola nella macro si risparmia qualche byte).
  170. ALTMPX
  171.     Define the alternate multiplex interrupt handler for the program.
  172.     Usage:
  173.     ALTMPX manuf,prodname,version,descrip,remove,psp
  174.     Arguments:
  175.     manuf       one- to eight-character manufacturer's name
  176.     prodname   one- to eight-character product name
  177.     version    four-digit hex version number (hi byte = major, lo = minor)
  178.     descrip    [opt] string (max 63 char) describing the product
  179.     remove       [opt] name of function to call to remove TSR from memory
  180.     psp       [opt] if nonblank, set up patch word for memblk segment to
  181.              be returned if <remove> omitted; returns CS if both
  182.              <remove> and <psp> blank (in this case, INSTALL_TSR
  183.              must specify either TOPMEM or HIGHONLY)
  184.     Notes:
  185.     This macro must be used inside a TSRcode@/TSRcodeEnd@ pair.
  186.     <remove> must be located in TSRcode@
  187.         input:    DX:BX = return address if uninstall successful
  188.         return: AL = status
  189.                 01h unable to remove from memory
  190.                 02h can't remove now, will do so when able
  191.                 03h safe to remove, but no resident uninstaller
  192.                     (TSR still enabled)
  193.                     BX = segment of memory block
  194.                 04h safe to remove, but no resident uninstaller
  195.                     (TSR now disabled)
  196.                     BX = segment of memory block
  197.                 05h not safe to remove now, try again later
  198.                 FFh successful (DX:BX were ignored)
  199.         return at DX:BX with AX destroyed if successful and <remove>
  200.             honors specific return address
  201.         if <remove> omitted, ALTMPX returns AL=03h
  202.     Exported Labels:
  203.     INT2Dh_handler (public), ORIG_INT2Dh (public), HWRESET_2Dh,
  204.     EOI_FLAG_2Dh, hw_reset_2Dh, $AMIS$MULTIPLEX_NUMBER (public),
  205.     ALTMPX_SIGNATURE (public), ALTMPX$PSP [patch word if <psp> nonblank]
  206.  
  207. ----------------------------------------------------------------------
  208.  
  209.     Ralf Brown            [valid until at least May 1, 1996]
  210.     813 Copeland Way, Suite 26
  211.     Pittsburgh, PA 15232-2217
  212.  
  213.     Internet: ralf@telerama.lm.com
  214.     FIDO:      Ralf Brown 1:129/26.1
  215.  
  216.