home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / tbones07.zip / TBONES07.DOC < prev    next >
Text File  |  1991-01-20  |  18KB  |  405 lines
  1. ***************************************************************************
  2. *                                      *
  3. *                             T-BONES                                     *
  4. *                           Version 0.7                                   *
  5. *                         January 20, 1991                                *
  6. *                                                                         *
  7. *       SKELETAL ASM PROGRAMS TO HELP IN PROGRAMMING YOUR OWN TSRs        *
  8. *                                      *
  9. *             Copyright (C) 1990, 1991 by Robert Curtis Davis             *
  10. *                                                                         *
  11. *      Internet E-mail address: sonny@trantor.harris-atd.com           *
  12. *                                                                         *
  13. *                         US Mail: 430 Bahama Drive                       *
  14. *                                  Indialantic, FL 32903                  *
  15. *                                      *
  16. ***************************************************************************
  17.  
  18. ONE-LINE DESCRIPTION:
  19. --------------------
  20.         TBONESxx.ZIP - Skeletal ASM programs for your own TSRs.
  21.  
  22. ***************************************************************************
  23.  
  24. DISCLAIMER:
  25. ----------
  26.     T-BONES is currently under development and this is a preliminary
  27. version. This software is not warranted to be suitable for any purpose and
  28. the author will not be held responsible for any damages arising directly or 
  29. indirectly from its use. By the act of using this software, the user agrees 
  30. to these conditions.
  31.  
  32. ***************************************************************************
  33.  
  34. DESCRIPTION:
  35. -----------
  36.     T-BONES is a set of skeletal Assembly Language programs which
  37. can be used as starting points in developing Terminate-but-Stay-
  38. Resident (TSR) programs for your DOS computer.
  39.  
  40.  
  41. BACKGROUND:
  42. ----------
  43.     In examining some software packages useful in learning about TSRs,
  44. I couldn't seem to find one that provided skeletal ASM programs into
  45. which I could easily drop my own Interrupt-triggered or Hot Key-triggered
  46. routines. It was toward the provision of these bare-bones programs which
  47. had already taken care of all the various details (initialization, saving
  48. old interrupt vectors, installing new interrupt vectors, going resident,
  49. determining if DOS code was interrupted, determining if DOS is at
  50. "Busy idle", determining if the TSR is already installed, etc.) necessary
  51. in some TSRs, that I undertook the writing of the programs in T-BONES
  52. as an aid to my own TSR programming efforts.
  53.     Also, I recognized that not all the features enumerated are
  54. necessary in every TSR. For example, if you are not going to use
  55. DOS calls in your routine, checking to be sure DOS is at idle may be
  56. unnecessary. Therefore, I have included TSRINT and TSRKEY which are
  57. very simple and leave it up to you to stay out of DOS's way.
  58.     Anyway, it is my hope, based upon feedback from users, to provide 
  59. a set of useful skeletal TSR Assembly Language programs that
  60. make it relatively easy for programmers to drop their own routines
  61. into place without having to start all over from scratch on every TSR.
  62.  
  63. ------------------------------------------
  64. PERMITTED DISTRIBUTION AND USAGE OF TBONES:
  65.  
  66.         No current restrictions are placed on the distribution either of the
  67. TBONES package itself (please pass it on to anyone who might use it) or on TSRs
  68. you might develop using this TBONES software package. But please leave
  69. somewhere in your program an acknowledgement of TBONES' help in making the
  70. TSR. Other than that, feel free to modify the ASM file (filename, comments,
  71. output messages, TSR signature, etc.) to make it "look" and "feel" as you
  72. wish.
  73.  
  74. ------------------------------------------
  75. TBONES' COST:
  76.  
  77.         I presently ask only that you send me (preferably by E-mail) a free
  78. copy of any generally-useful TSR that you develop using TBONES. That way,
  79. I am paid in useful software only if TBONES itself proves genuinely useful
  80. to you.
  81.  
  82. ------------------------------------------------------------------------------
  83.  
  84.  
  85.     T-BONES currently consists of:
  86.  
  87.         (1) README:
  88.                 Quick start information. Read this to find out if TBONES
  89.                 might be of use to you.
  90.  
  91.         (2) TBONES07.DOC:
  92.                 This complete documentation file.
  93.  
  94.         (3) TSRINT.ASM:
  95.                 Assembly Language skeletal program for use in
  96.                 developing a TSR program that is triggered into
  97.                 action by "Hooking" to a user-specified Interrupt.
  98.                 Raw program with NO features to keep you out of
  99.                 trouble with DOS nonreentrancy.
  100.  
  101.         (4) TSRINT.COM:
  102.                 Executable Hooked Interrupt TSR code obtained by
  103.                 assembling TSRINT.ASM (with MASM), linking (with DOS'
  104.                 LINK), and conversion from .EXE to .COM form using DOS'
  105.                 EXE2BIN. The commands necessary to convert TSRINT.ASM
  106.                 to TSRINT.COM are:
  107.  
  108.                         MASM TSRINT;
  109.                         LINK TSRINT;     (Ignore the No Stack warning)
  110.                         EXE2BIN TSRINT TSRINT.COM
  111.  
  112.                 Or, if working with Borland's TASM package:
  113.                         TASM /ml TSRINT
  114.                         TLINK /x/t TSRINT
  115.  
  116.         (5) TSRKEY.ASM:
  117.                 Assembly Language skeletal program for use in
  118.                 developing a TSR program that is triggered into
  119.                 action by a user-specified "Hot Key" combination.
  120.                 Raw program with NO features to keep you out of
  121.                 trouble with DOS nonreentrancy.
  122.  
  123.         (6) TSRKEY.COM:
  124.                 Executable HotKey TSR code obtained by assembling
  125.                 TSRKEY.ASM (with MASM), linking (with DOS' LINK), and
  126.                 conversion from .EXE to .COM form using DOS'
  127.                 EXE2BIN. The commands necessary to convert TSRKEY.ASM
  128.                 to TSRKEY.COM are:
  129.  
  130.                         MASM TSRKEY.ASM;
  131.                         LINK TSRKEY.OBJ;
  132.                         EXE2BIN TSRKEY.EXE TSRKEY.COM
  133.  
  134.                 Or, if working with Borland's TASM package:
  135.                         TASM /ml TSRKEY
  136.                         TLINK /x/t TSRKEY
  137.  
  138.  
  139.         (7) TSRBONES.ASM:
  140.                 TSRBONES is the flagship program in this package.
  141.                 It is an Assembly Language skeletal program for use in
  142.                 developing a TSR program that is triggered into
  143.                 action by a user-specified "Hot Key" combination
  144.                 WHEN DOS IS AT "BUSY IDLE" Int 28h. When DOS is
  145.                 at "Busy Idle", it is safe to use DOS Function calls
  146.                 ABOVE 0Ch without incurring problems with DOS'
  147.                 non-reentrancy. The code also prevents multiple
  148.                 installations. The TSR also will not trigger if the CPU
  149.                 is busy servicing a hardware interrupt (IRQ0 - IRQ7).
  150.  
  151.         (8) TSRBONES.COM:
  152.                 Executable HotKey "DOS-OK" TSR code obtained by
  153.                 assembling TSRBONES.ASM (with MASM), linking (with
  154.                 DOS' LINK), and conversion from .EXE to .COM form
  155.                 using DOS' EXE2BIN. The commands necessary to convert
  156.                 TSRBONES.ASM to TSRBONES.COM are:
  157.  
  158.                         MASM TSRBONES.ASM;
  159.                         LINK TSRBONES.OBJ;
  160.                         EXE2BIN TSRBONES TSRBONES.COM
  161.  
  162.                 Or, if working with Borland's TASM package:
  163.                         TASM /ml TSRBONES
  164.                         TLINK /x/t TSRBONES
  165.  
  166.         (9) HISTORY:
  167.                 The revision history for the TBONES package.
  168.  
  169. ******************************************************************************
  170.  
  171. ASSEMBLERS:
  172.  
  173.         The following assemblers are known to successfully assemble the
  174.         ASM files in TBONES:
  175.  
  176.                 - ARROWSOFT Public Domain Assembler v1.00d (64K Model)
  177.                 - MASM v1.0 and v4.00
  178.                 - TASM v1.00
  179.  
  180. ******************************************************************************
  181. TSR .COM FILES:
  182.  
  183. TSRINT:
  184. ------
  185.         TSRINT, as distributed, hooks to Interrupt 05h, which is
  186. triggered by the Print Screen Key. The routine included in the distributed
  187. code for TSRINT simply rings the terminal Bell signal whenever Int 05h is
  188. executed, i.e, whenever the Print Screen key is pressed. You, of course,
  189. will replace or expand upon this simple routine so that your TSR performs
  190. your desired function.
  191.  
  192. TSRKEY:
  193. ------
  194.         TSRKEY, as distributed, is set to trigger on CTRL-ALT-K
  195. as a Hot Key combination. The routine included in the distributed
  196. code for TSRKEY simply rings the terminal Bell signal whenever the CTRL
  197. and ALT keys are held down and then the "K" key depressed. You, of course,
  198. will replace or expand upon this simple routine so that your TSR performs
  199. your desired function in response to your specified Hot Key combination.
  200.  
  201. TSRBONES:
  202. --------
  203.         TSRBONES, as distributed, is set to trigger on CTRL-ALT-B
  204. as a Hot Key combination. The routine included in the distributed
  205. code for TSRBONES simply rings the terminal Bell signal whenever the CTRL
  206. and ALT keys are held down and then the "B" key depressed AND either
  207. the InDOS Flag is zero OR DOS is at "Busy Idle" (Int28h) AND no hardware
  208. interrupt (IRQ0 - IRQ7) is being serviced. In addition, the TSR is not
  209. allowed to trigger if DOS is handling a Critical Error, or if a disk
  210. access is underway (i.e., if INT 13h is active). Furthermore, the code for
  211. TSRBONES detects prior installation and does not permit multiple installations
  212. of the TSR.
  213.         You, of course, will replace or expand upon the simple Bell ringing
  214. routine so that your TSR performs your desired function in response to your
  215. specified Hot Key combination.
  216.  
  217. ****************************************************************************
  218.  
  219. NOTES ON T-BONES:
  220. ----------------
  221.  
  222. - Learning how TSRs work:
  223.  
  224.     In learning to program TSRs, I have written these programs in the
  225. order: TSRINT, TSRKEY, several programs leading to TSRBONES. This is the order
  226. of increasing capability and complexity. I believe that a study of the source
  227. programs in that order might help you in your own quest to learn how TSRs 
  228. work.
  229.  
  230.         TSRBONES is the flagship program of the TBONES package. It incorporates
  231. all the tricks I CURRENTLY KNOW about in making a TSR coexist safely and robust-
  232. ly with DOS and with other TSRs. If you detect important oversights on my part
  233. about these complex matters, I would appreciate your telling me.
  234.  
  235.     If you know that your TSR is simple enough that DOS reentrancy is 
  236. not of concern, you might decide to use the very RAW frameworks of TSRINT 
  237. or TSRKEY, for triggering on an Interrupt or on a Hot Key respectively. You
  238. might then decide to enhance them by incorporating one or more desired features
  239. out of the TSRBONES source code.
  240.  
  241.         If you want maximum bells-and-whistles, robustness, and protection
  242. for your TSR from problems with DOS reentrancy and interference with other
  243. CPU tasks, use TSRBONES.
  244.  
  245.         TSRBONES requires only about 240 more resident bytes than the simple
  246. TSRKEY. You may well view that as a small price to pay for the safer, more
  247. robust, and capable code of TSRBONES.
  248.  
  249.     I might add that I do not pretend that my own knowledge of TSRs
  250. (or of Assembly Language) is yet complete, and I would appreciate any 
  251. comments you might send to me via E-mail on problems or bugs or bad practice 
  252. that you detect in the included code.
  253.  
  254.  
  255. - Protecting against problems with DOS non-reentrancy:
  256.  
  257.     Be aware that the simple skeletal programs, TSRINT and TSRKEY, in 
  258. T-BONES do NOTHING to protect you from problems caused by DOS' non-reentrancy.
  259. Basically, this means that if your TSR interrupts your processor while it is 
  260. executing code that DOS provides to perform some function, then you SHOULD NOT
  261. PROGRAM YOUR TSR TO RE-ENTER ANY CODE PROVIDED BY DOS. If your processor
  262. WERE to re-enter DOS code, it might modify memory locations used by DOS
  263. and therefore when your TSR is exited and the processor attempts to pick
  264. up where it left off in the DOS code it was executing when your TSR
  265. interrupted it, unpredictable (and even disastrous) effects can result.
  266.  
  267.         These guidelines can help keep you out of trouble if you use
  268. TSRINT or TSRKEY:
  269.  
  270.     1. Don't use DOS functions ( accessed via Int 21h ) unless you
  271.         HAVE to.
  272.  
  273.     2. If you MUST use DOS functions read a good DOS programming
  274.                 reference and study the code in TSRBONES.ASM to learn
  275.                 more about the following techniques:
  276.  
  277.         a) Monitoring the InDOS flag to see when it is safe to
  278.             call a DOS function. See the description of
  279.             Function 34h of Int 21h in a DOS programming
  280.             reference to learn how to monitor this flag.
  281.  
  282.                 b) Monitoring the Critical Error flag. This flag can
  283.                         keep you out of trouble with DOS in some cases
  284.                         when InDOS erroneously indicates OK to enter DOS.
  285.  
  286.                 c) Monitoring Int 28h to detect DOS' "Busy Wait" for
  287.             console I/O. It is safe to enter DOS for anything
  288.             except console I/O when DOS is in a "Busy Wait".
  289.             Even though the InDOS flag will indicate the
  290.             processor is in DOS code when this "Busy Wait"
  291.             is occurring, Int 28h can be used to give the OK
  292.             to make non-console-I/O DOS calls (Int21h Functions
  293.             above 0Ch).
  294.  
  295.                 d) Hooking BIOS Int13h to keep track of when time-critical
  296.                         disk access is occurring so your TSR does not
  297.                         intrude.
  298.  
  299.  
  300. - No check for prior installation in TSRINT and TSRKEY:
  301.  
  302.         A shortcoming of the raw programs, TSRINT and TSRKEY, is that those
  303. TSRs don't check for prior installations of themselves. Thus, they depend
  304. upon you not to waste memory in installing them multiple times.
  305.  
  306.  
  307. *****************************************************************************
  308.  
  309. SOURCES OF FURTHER INFORMATION ON PROGRAMMING TSRs:
  310.  
  311.     BOOKS:
  312.         -----
  313.         One of the best treatments I know of on the complex considerations
  314. in writing a robust TSR appears in:
  315.  
  316.                 _Inside DOS: A Programmer's Guide_
  317.                 Author: Michael J. Young
  318.                 Publisher: SYBEX, 490 pp., (C)1988, 1990.
  319.                 Chapter 11: "Memory Residency" pp. 321-360.
  320.  
  321.         A book which contains a wealth of information useful in designing
  322. good TSRs is:
  323.                 _Undocumented DOS: A Programmer's Guide to Reserved
  324.                                    MS-DOS Functions and Data Structures_
  325.                 by Andrew Schulman, Raymond J. Michels, Jim Kyle,
  326.                    Tim Paterson, David Maxey, and Ralf Brown.
  327.                 Publisher: Addison-Wesley Publishing Company, Inc., (C)1990.
  328.                 Chapter 5: "Memory Resident Software: Pop-ups and
  329.                             Multitasking" by Michels, Paterson, and
  330.                                              Schulman.
  331.  
  332.         I also have learned much from the book:
  333.  
  334.                 _DOS Programmer's Reference, 2nd Edition_
  335.                 by Terry Dettmann and revised for 2nd Edition by Jim Kyle
  336.                 (C)1989 by QUE Corporation, Programming Series
  337.  
  338.         I have found it indispensable as a source for detailed DOS programming
  339. information.
  340.  
  341.         The Waite Group's _Microsoft Macro Assembler Bible_ by Nabaiyoti
  342. Barkakati has been most useful on Assembly Language matters.
  343.  
  344.  
  345.         RALF BROWN'S INTERRUPT LIST:
  346.         ---------------------------
  347.         Ralf Brown maintains an astounding file which is chock-full of
  348. detailed, absolutely-indispensable information for DOS programmers on
  349. Hardware, BIOS, DOS, and other interrupts. This file is available free for
  350. the downloading from many BBS's, as well as via anonymous ftp from most major
  351. archival sites on the Internet. You should not be without this file, which is
  352. widely-known as "Ralf Brown's Interrupt List". Ask about it. You will find it.
  353. As of this writing, INTER191.ZIP is the most recent version. In general,
  354. INTERxyy.ZIP is release x of year yy.
  355.  
  356.  
  357.         TSRDEMO2:
  358.         --------
  359.     TSRDEMO2 by Thomas Brandenborg of Denmark provides valuable data
  360. to anyone learning to safely program TSRs. His .ASM source program is
  361. a "sample demonstration of a safe approach for writing TSR programmes."
  362. This program is available on Compuserve Forums, as well as on many BBSs.
  363. Mr. Brandenborg might be reached at:
  364.  
  365.         Thomas Brandenborg
  366.         Lundbyesgade 11
  367.         DK-8000 Aarhus C
  368.         DENMARK
  369.  
  370.  
  371.     TesSeRact(TM):
  372.         -------------
  373.     A lot of helpful information in developing TSRs which overcome
  374. the shortcomings above, and others, can be obtained from the TesSeRact(TM)
  375. development team. This group provides data on how to produce TSRs compliant 
  376. with the TesSeRact standards. These standards are intended to make TSRs 
  377. peacefully coexist with DOS and with each other in a bullet-proof, safe, 
  378. robust manner. You can learn much from this team that you will need to know in 
  379. programming complex TSRs.
  380.     For  information about TesSeRact, contact the TesSeRact Development 
  381. Team at:                                             
  382.  
  383.           TesSeRact Development Team
  384.           c/o Chip Rabinowitz
  385.           2084 Woodlawn Avenue
  386.           Glenside, PA 19038
  387.           1-215-884-3373
  388.  
  389.           Compuserve:         70731,20
  390.           MCIMAIL:  315-5415
  391.  
  392.      This MCIMAIL  Account has  been provided  to the TesSeRact Development
  393.      Team by Borland International, Inc.  The TesSeRact Development Team is
  394.      in no  way associated with Borland International, Inc.  TesSeRact is a
  395.      trademark of the TesSeRact Development Team.
  396.  
  397. *****************************************************************************
  398.  
  399. KNOWN BUGS:
  400. ----------
  401.         None. (Now just how long might THAT last? :-)
  402.  
  403.                               -END-
  404. 
  405.