ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / ASSEMBLY / AMISL083.ZIP / AMISLIB.DOC < prev next >

Wrap

Text File | 1992-05-02 | 11.8 KB | 315 lines

Alternate Multiplex Interrupt Specification Library Public Domain 1992 Ralf Brown Version 0.83 LastEdit: 5/2/92 Files in this library: AMISLIB.DOC this file TSRS.DOC usage instructions for sample TSRs and utilities AMIS.MAC include file defining various macros AMIS.ASM the actual library code AMITSRS.C sample program to list resident programs using AMIS FINDTSRS.C function to find all TSRs matching a given name POPUP.C sample program to request popup of an AMIS TSR REMOVE.C sample program to remove a specific AMIS TSR UNINSTAL.ASM TSR remover for REMOVE.C FASTMOUS.ASM sample TSR NOLPT.ASM sample TSR -- turn parallel port into bit bucket SWITCHAR.ASM sample TSR -- provide switchar() for MSDOS 5.0 VGABLANK.ASM sample TSR -- VGA screen blanker NOTE.ASM sample TSR -- popup note-taker MAKEFILE make all programs from the library sources ------------------------------------------------------------------------ Advantages of AMISLIB: totally free adds only 1K to the executable -- TSRs can be less than 1.4K on disk and as little as 128 bytes in memory up to 256 AMIS-compliant TSRs can be resident simultaneously with no interrupt conflicts resultant TSR can load itself into high memory (either MSDOS 5 upper memory blocks or XMS upper memory blocks); the user has control over where TSR is allowed to load: high only, low only, or high first then low; high memory may use either the first or the best UMB; low memory may use either the low end or the high end of conventional memory. TSRs using AMISLIB or other AMIS-compliant code can be unloaded in any order, and can be unloaded by programs other than the TSR's original executable Note: This is still a preliminary version of the library, so there might be problems. Please let me know if you find any.... ------------------------------------------------------------------------ To make use of this library, you basically need to do three things: 1. To each source file that will make calls, add INCLUDE AMIS.MAC 2. If using a memory model other than Tiny, you must provide a public word variable '__psp' (in C, '_psp'--Turbo C provides this automatically) whose contents are the PSP segment of the program. 3. Link in AMIS.OBJ (assembled from AMIS.ASM) with the rest of your object modules. Limitations: The ALTMPX and INSTALL_TSR macros must be invoked from the same source file in order for the installer to properly fix up the resident AMIS handler. (If not, you will have to perform the fixup yourself in an 'init' handler for INSTALL_TSR) ------------------------------------------------------------------------ After an INCLUDE AMIS.MAC, the following definitions and macros are available: AMIS_VERSION 100 times the version of the specification to which the library conforms (i.e. 123 = version 1.2.3). AMISLIB_VERSION 100 times the version of this library RESIDENT_CODE The name of the segment to ASSUME or use in overrides when accessing data within the part of the program which will remain resident. TGROUP Group containing all resident segments in the TSR. See also TSRgroup@. TSRcode@ TSRcodeEnd@ Delimit the code which will remain resident; some of the other macros listed below will not function correctly unless within a section of code delimited with TSRcode@ and TSRcodeEnd@. TSRdata@ TSRdataEnd@ Delimit the initialized data which will remain resident. Requires the use of TSRgroup@ to function properly. TSRbss@ TSRbssEnd@ Delimit the uninitialized data which will be placed in the resident portion (but omitted from the disk image of the executable if possible). Requires the use of TSRgroup@ to function properly. TSRgroup@ Declare TGROUP and force the correct ordering of TSRcode@, TSRdata@, and TSRbss@. DISPLAY_STRING Output a '$'-terminated string to standard output via DOS. Usage: DISPLAY_STRING string,dataseg Arguments: string the label of the string to be displayed dataseg [opt] the segment of the string Example: DISPLAY_STRING banner ... ... banner db "FOOBAR (c) 1992 Harry Q Bovik",13,10,"$" CHECK_DOS_VER Ensure that the program is running under the proper version of DOS, and terminate with an error message specifying the minimum required version if not. Usage: CHECK_DOS_VER major,minor Example: CHECK_DOS_VER 2,00 IF_INSTALLED Conditionally branch somewhere if the TSR is already installed. Usage: IF_INSTALLED rescode,rtype,dest Arguments: rescode segment of TSR code within executable (to get signature and hook list) rtype type of segment reference: REL = paras offset from CS RELBYTE = bytes offset from CS ABS = absolute segment number dest label to branch to if already installed Return: falls through with CF clear if not already installed branches with CF set and AH = multiplex number if installed INSTALL_TSR Allocate memory for the resident code, copy the resident code to the allocated memory, hook all interrupts used by the TSR, optionally call an initialization function, and terminate back to DOS. Usage: INSTALL_TSR loc,ltype,siz,stype,extra,fit,high,init,if_inst,on_err, more_flags Arguments: loc location of resident code ltype type of above location: REL = para offset from CS RELBYTE = bytes offset from CS ABS = absolute paragraph number siz size of resident code stype type of above size: BYTE or PARA extra [opt] number of additional paragraphs needed in resident part fit [opt] FIRST or BEST (default) -fit allocation high [opt] HIGHONLY to only use UMBs, LOWONLY to only use conventional memory, TOPMEM to allocate block at high end of conventional memory if no UMBs, TOPLOW to only use top end of conventional memory init [opt] function to call after installing TSR but before exiting if_inst [opt] label to branch to if already installed on_err [opt] label to branch to if unable to install more_flags [opt] label of byte containing additional flags to be ORed with those automatically set by <fit> and <high> Notes: If 'init' is specified, the indicated function will be called with AX = segment at which TSR was loaded If 'if_inst' is specified, the indicated function will be jumped at with AH = multiplex number CX = version number The TOPMEM and TOPLOW options are reported to be incompatible with Windows 3.0, and will most likely cause a crash if the TSR is installed while shelled out from a program using SPAWNO or another swapping spawn() replacement. Then again, anyone who attempts to install a TSR while shelled out of another program deserves whatever happens. UNINSTALL Remove the TSR from memory. Usage: UNINSTALL rescode,rtype,on_err Arguments: rescode segment of TSR code within executable (to get signature and hook list) rtype type of segment reference: REL = paras offset from CS RELBYTE = bytes offset from CS ABS = absolute segment number on_err [opt] label to branch to if unable to remove from memory Notes: If 'on_err' is omitted, check CF after this macro to determine whether the removal was successful (CF clear if successful, set on error). ISP_HEADER Set up the Interrupt Sharing Protocol header for an interrupt. Usage: ISP_HEADER intr,reset,eoi Arguments: intr interrupt number reset [opt] name of routine to perform hardware reset eoi [opt] if nonzero, this is the primary handler for a hardware int Exported Labels: (for example "ISP_HEADER 00h,reset_func,0") INT00h_handler (public), ORIG_INT00h (public), HWRESET_00h, EOI_FLAG_00h [in addition, hw_reset_00h would be present for ISP_HEADER 00h,,0] Note: This macro must be used inside a TSRcode@/TSRcodeEnd@ pair. Example: ISP_HEADER 21h cmp ah,4Bh ; provide our own EXEC replacement je exec_call jmp ORIG_INT21h exec_call: ... HOOKED_INTS Declare the interrupts this TSR hooks. Usage: HOOKED_INTS int1,int2,...,int32 Arguments: up to 32 interrupt numbers Exported Labels: HOOKED_INT_LIST (public) Notes: This macro must be used inside a TSRcode@/TSRcodeEnd@ pair. INT 2Dh need not be listed, as it is automatically added to the end of the list of hooked interrupts. Examples: HOOKED_INTS ; this TSR hooks only INT 2Dh HOOKED_INTS 13h,21h,FFh ; this TSR hooks INTs 13h, 21h, 2Dh, FFh ALTMPX Define the alternate multiplex interrupt handler for the program. Usage: ALTMPX manuf,prodname,version,descrip,priv,api,popup,remove,psp Arguments: manuf one- to eight-character manufacturer's name prodname one- to eight-character product name version four-digit hex version number (hi byte = major, lo = minor) descrip [opt] string (max 63 char) describing the product priv [opt] name of routine to handle private INT 2Dh functions api [opt] name of FAR routine giving non-INT 2Dh API entry point popup [opt] name of function to call to request a popup remove [opt] name of function to call to remove TSR from memory psp [opt] if nonblank, set up patch word for memblk segment to be returned if <remove> omitted; returns CS if both <remove> and <psp> blank (in this case, INSTALL_TSR must specify either TOPMEM or HIGHONLY) Limitations on Routines: <priv> must be located in TSRcode@ input: AL = function number (10h-FFh) AH = multiplex number (ignore) others available for handler return: via IRET, with regs as appropriate for requested func <api> must be located in TSRcode@ input: registers as desired (no limitations) return: registers as desired (no limitations) <popup> must be located in TSRcode@ input: nothing return: AL = status 01h can not pop up now, try again later 02h can not pop up yet, will do so when able 03h already popped up 04h unable to popup, user intervention required BX = standard reason code 0000h unknown failure 0001h int chain passes through memory which must be swapped out 0002h swap-in failed CX = application's reason code if nonzero FFh TSR popped up and was exited by user BX = return value 0000h no return value 0001h TSR unloaded 0002h-00FFh reserved 0100h-FFFFh application-specific <remove> must be located in TSRcode@ input: DX:BX = return address if uninstall successful return: AL = status 01h unable to remove from memory 02h can't remove now, will do so when able 03h safe to remove, but no resident uninstaller (TSR still enabled) BX = segment of memory block 04h safe to remove, but no resident uninstaller (TSR now disabled) BX = segment of memory block 05h not safe to remove now, try again later FFh successful (DX:BX were ignored) return at DX:BX with AX destroyed if successful and <remove> honors specific return address if <remove> omitted, ALTMPX returns AL=03h Exported Labels: INT2Dh_handler (public), ORIG_INT2Dh (public), HWRESET_2Dh, EOI_FLAG_2Dh, hw_reset_00h, MULTIPLEX_NUMBER (public), ALTMPX_SIGNATURE (public), ALTMPX$PSP [patch word if <psp> nonblank] Note: This macro must be used inside a TSRcode@/TSRcodeEnd@ pair. ------------------------------------------------------------------------ For more details, see AMIS.MAC, AMIS.ASM, and the source to the example TSRs. See also TSRS.DOC for usage information on the sample TSRs. ------------------------------------------------------------------------ Ralf Brown School of Computer Science Carnegie Mellon University Pittsburgh, PA 15213-3890 Ralf Brown 1:129/26.1 ralf+@cs.cmu.edu