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