home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / progasm / amisl082.arj / AMISLIB.DOC < prev    next >
Text File  |  1992-04-26  |  12KB  |  310 lines
  1. Alternate Multiplex Interrupt Specification Library
  2. Public Domain 1992 Ralf Brown
  3. Version 0.82
  4. LastEdit: 4/26/92
  5.  
  6. Files in this library:
  7.     AMISLIB.DOC    this file
  8.     AMIS.MAC    include file defining various macros
  9.     AMIS.ASM    the actual library code
  10.     AMITSRS.C    sample program to list resident programs using AMIS
  11.     FINDTSRS.C    function to find all TSRs matching a given name
  12.         POPUP.C         sample program to request popup of an AMIS TSR
  13.     REMOVE.C    sample program to remove a specific AMIS TSR
  14.     UNINSTAL.ASM    TSR remover for REMOVE.C
  15.     FASTMOUS.ASM    sample TSR
  16.     NOLPT.ASM    sample TSR
  17.     SWITCHAR.ASM    sample TSR
  18.     VGABLANK.ASM    sample TSR -- VGA screen blanker
  19.     NOTE.ASM    sample TSR -- popup note-taker
  20.     MAKEFILE    make all programs from the library sources
  21.  
  22. ------------------------------------------------------------------------
  23.  
  24. Advantages of AMISLIB:
  25.  
  26.     totally free
  27.     adds only 1K to the executable -- TSRs can be less than 1.5K on
  28.       disk and as little as 128 bytes in memory
  29.         up to 256 AMIS-compliant TSRs can be resident simultaneously
  30.           with no interrupt conflicts
  31.     resultant TSR can load itself into high memory (either MSDOS 5
  32.       upper memory blocks or XMS upper memory blocks); the user has
  33.       control over where TSR is allowed to load: high only, low only,
  34.       or high first then low; high memory may use either the first or
  35.       the best UMB; low memory may use either the low end or the high
  36.       end of conventional memory.
  37.     TSRs using AMISLIB or other AMIS-compliant code can be unloaded
  38.       in any order, and can be unloaded by programs other than the
  39.       TSR's original executable
  40.  
  41. Note: This is still a preliminary version of the library, so there might
  42.       be problems.  Please let me know if you find any....
  43.  
  44. ------------------------------------------------------------------------
  45.  
  46. To make use of this library, you basically need to do three things:
  47.  
  48.     1. To each source file that will make calls, add
  49.         INCLUDE AMIS.MAC
  50.     2. If using a memory model other than Tiny, you must provide a
  51.        public word variable '__psp' (in C, '_psp'--Turbo C provides
  52.        this automatically) whose contents are the PSP segment of
  53.        the program.
  54.     3. Link in AMIS.OBJ (assembled from AMIS.ASM) with the rest of
  55.        your object modules.
  56.  
  57. Limitations:
  58.     The ALTMPX and INSTALL_TSR macros must be invoked from the same
  59.     source file in order for the installer to properly fix up the
  60.     resident AMIS handler.    (If not, you will have to perform the
  61.     fixup yourself in an 'init' handler for INSTALL_TSR)
  62.  
  63. ------------------------------------------------------------------------
  64.  
  65. After an INCLUDE AMIS.MAC, the following definitions and macros are available:
  66.  
  67. AMIS_VERSION
  68.     100 times the version of the specification to which the library
  69.     conforms (i.e. 123 = version 1.2.3).
  70.  
  71. AMISLIB_VERSION
  72.     100 times the version of this library
  73.  
  74. RESIDENT_CODE
  75.     The name of the segment to ASSUME or use in overrides when accessing
  76.     data within the part of the program which will remain resident.
  77.  
  78. TGROUP
  79.     Group containing all resident segments in the TSR.    See also TSRgroup@.
  80.  
  81. TSRcode@
  82. TSRcodeEnd@
  83.     Delimit the code which will remain resident; some of the other
  84.     macros listed below will not function correctly unless within a
  85.     section of code delimited with TSRcode@ and TSRcodeEnd@.
  86.  
  87. TSRdata@
  88. TSRdataEnd@
  89.     Delimit the initialized data which will remain resident.  Requires the
  90.     use of TSRgroup@ to function properly.
  91.  
  92. TSRbss@
  93. TSRbssEnd@
  94.     Delimit the uninitialized data which will be placed in the resident
  95.     portion (but omitted from the disk image of the executable if
  96.     possible).    Requires the use of TSRgroup@ to function properly.
  97.  
  98. TSRgroup@
  99.     Declare TGROUP and force the correct ordering of TSRcode@, TSRdata@,
  100.     and TSRbss@.
  101.  
  102. DISPLAY_STRING
  103.     Output a '$'-terminated string to standard output via DOS.
  104.     Usage:
  105.     DISPLAY_STRING string,dataseg
  106.     Arguments:
  107.     string    the label of the string to be displayed
  108.     dataseg [opt] the segment of the string
  109.     Example:
  110.     DISPLAY_STRING banner
  111.     ...
  112.     ...
  113.     banner db "FOOBAR (c) 1992 Harry Q Bovik",13,10,"$"
  114.  
  115. CHECK_DOS_VER
  116.     Ensure that the program is running under the proper version of DOS,
  117.     and terminate with an error message specifying the minimum required
  118.     version if not.
  119.     Usage:
  120.     CHECK_DOS_VER  major,minor
  121.     Example:
  122.     CHECK_DOS_VER 2,00
  123.  
  124. IF_INSTALLED
  125.     Conditionally branch somewhere if the TSR is already installed.
  126.     Usage:
  127.     IF_INSTALLED rescode,rtype,dest
  128.     Arguments:
  129.     rescode     segment of TSR code within executable (to get signature
  130.          and hook list)
  131.     rtype     type of segment reference: REL = paras offset from CS
  132.                         RELBYTE = bytes offset from CS
  133.                         ABS = absolute segment number
  134.     dest     label to branch to if already installed
  135.     Return:
  136.     falls through with CF clear if not already installed
  137.     branches with CF set and AH = multiplex number if installed
  138.  
  139. INSTALL_TSR
  140.     Allocate memory for the resident code, copy the resident code to the
  141.     allocated memory, hook all interrupts used by the TSR, optionally
  142.     call an initialization function, and terminate back to DOS.
  143.     Usage:
  144.     INSTALL_TSR loc,ltype,siz,stype,extra,fit,high,init,if_inst,on_err,
  145.             more_flags
  146.     Arguments:
  147.     loc    location of resident code
  148.     ltype    type of above location: REL = para offset from CS
  149.                     RELBYTE = bytes offset from CS
  150.                     ABS = absolute paragraph number
  151.     siz    size of resident code
  152.     stype    type of above size: BYTE or PARA
  153.     extra    [opt] number of additional paragraphs needed in resident part
  154.     fit    [opt] FIRST or BEST (default) -fit allocation
  155.     high    [opt] HIGHONLY to only use UMBs, LOWONLY to only use
  156.             conventional memory, TOPMEM to allocate block at high 
  157.             end of conventional memory if no UMBs, TOPLOW
  158.             to only use top end of conventional memory
  159.     init    [opt] function to call after installing TSR but before exiting
  160.     if_inst [opt] label to branch to if already installed
  161.     on_err    [opt] label to branch to if unable to install
  162.     more_flags [opt] label of byte containing additional flags to be ORed
  163.            with those automatically set by <fit> and <high>
  164.     Notes:
  165.     If 'init' is specified, the indicated function will be called with
  166.         AX = segment at which TSR was loaded
  167.     The TOPMEM and TOPLOW options are reported to be incompatible with
  168.         Windows 3.0, and will most likely cause a crash if the TSR is
  169.         installed while shelled out from a program using SPAWNO or
  170.         another swapping spawn() replacement.  Then again, anyone who
  171.         attempts to install a TSR while shelled out of another program
  172.         deserves whatever happens.
  173.  
  174. UNINSTALL
  175.     Remove the TSR from memory.
  176.     Usage:
  177.     UNINSTALL rescode,rtype,on_err
  178.     Arguments:
  179.     rescode      segment of TSR code within executable (to get signature
  180.           and hook list)
  181.     rtype      type of segment reference: REL = paras offset from CS
  182.                          RELBYTE = bytes offset from CS
  183.                          ABS = absolute segment number
  184.     on_err      [opt] label to branch to if unable to remove from memory
  185.     Notes:
  186.     If 'on_err' is omitted, check CF after this macro to determine
  187.     whether the removal was successful (CF clear if successful, set
  188.     on error).
  189.  
  190. ISP_HEADER
  191.     Set up the Interrupt Sharing Protocol header for an interrupt.
  192.     Usage:
  193.     ISP_HEADER intr,reset,eoi
  194.     Arguments:
  195.     intr    interrupt number
  196.     reset    [opt] name of routine to perform hardware reset
  197.     eoi    [opt] if nonzero, this is the primary handler for a hardware int
  198.     Exported Labels: (for example "ISP_HEADER 00h,reset_func,0")
  199.     INT00h_handler (public), ORIG_INT00h (public), HWRESET_00h,
  200.     EOI_FLAG_00h
  201.     [in addition, hw_reset_00h would be present for ISP_HEADER 00h,,0]
  202.     Note:
  203.     This macro must be used inside a TSRcode@/TSRcodeEnd@ pair.
  204.     Example:
  205.         ISP_HEADER 21h
  206.         cmp    ah,4Bh    ; provide our own EXEC replacement
  207.         je    exec_call
  208.         jmp    ORIG_INT21h
  209.     exec_call:
  210.         ...
  211.  
  212. HOOKED_INTS
  213.     Declare the interrupts this TSR hooks.
  214.     Usage:
  215.     HOOKED_INTS  int1,int2,...,int32
  216.     Arguments:
  217.     up to 32 interrupt numbers
  218.     Exported Labels:
  219.     HOOKED_INT_LIST (public)
  220.     Notes:
  221.     This macro must be used inside a TSRcode@/TSRcodeEnd@ pair.
  222.     INT 2Dh need not be listed, as it is automatically added to the
  223.     end of the list of hooked interrupts.
  224.     Examples:
  225.         HOOKED_INTS        ; this TSR hooks only INT 2Dh
  226.     HOOKED_INTS 13h,21h,FFh    ; this TSR hooks INTs 13h, 21h, 2Dh, FFh
  227.  
  228. ALTMPX
  229.     Define the alternate multiplex interrupt handler for the program.
  230.     Usage:
  231.     ALTMPX manuf,prodname,version,descrip,priv,api,popup,remove,psp
  232.     Arguments:
  233.     manuf       one- to eight-character manufacturer's name
  234.     prodname   one- to eight-character product name
  235.     version       four-digit hex version number (hi byte = major, lo = minor)
  236.     descrip       [opt] string (max 63 char) describing the product
  237.     priv       [opt] name of routine to handle private INT 2Dh functions
  238.     api       [opt] name of FAR routine giving non-INT 2Dh API entry point
  239.     popup       [opt] name of function to call to request a popup
  240.     remove       [opt] name of function to call to remove TSR from memory
  241.     psp       [opt] if nonblank, set up patch word for memblk segment to
  242.              be returned if <remove> omitted; returns CS if both
  243.              <remove> and <psp> blank (in this case, INSTALL_TSR
  244.              must specify either TOPMEM or HIGHONLY)
  245.     Limitations on Routines:
  246.     <priv>    must be located in TSRcode@
  247.         input:    AL = function number (10h-FFh)
  248.             AH = multiplex number (ignore)
  249.             others available for handler
  250.         return: via IRET, with regs as appropriate for requested func
  251.     <api>    must be located in TSRcode@
  252.         input:    registers as desired (no limitations)
  253.         return: registers as desired (no limitations)
  254.     <popup> must be located in TSRcode@
  255.         input:    nothing
  256.         return: AL = status
  257.                 01h can not pop up now, try again later
  258.                 02h can not pop up yet, will do so when able
  259.                 03h already popped up
  260.                 04h unable to popup, user intervention required
  261.                     BX = standard reason code
  262.                     0000h unknown failure
  263.                     0001h int chain passes through memory
  264.                         which must be swapped out
  265.                     0002h swap-in failed
  266.                     CX = application's reason code if nonzero
  267.                 FFh TSR popped up and was exited by user
  268.                     BX = return value
  269.                     0000h no return value
  270.                     0001h TSR unloaded
  271.                     0002h-00FFh reserved
  272.                     0100h-FFFFh application-specific
  273.     <remove> must be located in TSRcode@
  274.         input:    DX:BX = return address if uninstall successful
  275.         return: AL = status
  276.                 01h unable to remove from memory
  277.                 02h can't remove now, will do so when able
  278.                 03h safe to remove, but no resident uninstaller
  279.                     (TSR still enabled)
  280.                     BX = segment of memory block
  281.                 04h safe to remove, but no resident uninstaller
  282.                     (TSR now disabled)
  283.                     BX = segment of memory block
  284.                 05h not safe to remove now, try again later
  285.                 FFh successful (DX:BX were ignored)
  286.         return at DX:BX with AX destroyed if successful and <remove>
  287.             honors specific return address
  288.         if <remove> omitted, ALTMPX returns AL=03h
  289.     Exported Labels:
  290.     INT2Dh_handler (public), ORIG_INT2Dh (public), HWRESET_2Dh,
  291.     EOI_FLAG_2Dh, hw_reset_00h, MULTIPLEX_NUMBER (public),
  292.     ALTMPX_SIGNATURE (public), ALTMPX$PSP [patch word if <psp> nonblank]
  293.     Note:
  294.     This macro must be used inside a TSRcode@/TSRcodeEnd@ pair.
  295.  
  296. ------------------------------------------------------------------------
  297.  
  298. For more details, see AMIS.MAC, AMIS.ASM, and the source to the example
  299. TSRs.
  300.  
  301. ------------------------------------------------------------------------
  302.  
  303.     Ralf Brown
  304.     School of Computer Science
  305.     Carnegie Mellon University
  306.     Pittsburgh, PA 15213-3890
  307.  
  308.     Ralf Brown 1:129/26.1
  309.     ralf+@cs.cmu.edu
  310.