home *** CD-ROM | disk | FTP | other *** search
- ******************************************************************************
- Quick Start with XLIB
- ******************************************************************************
-
- The user manual is largely dedicated to cover specifics of XLIB which will
- not be of concern to many programmers. A few notes are added here to expedite
- matters for these programmers.
- If you are not an assembly language programmer, then consider using EASYX
- rather than XLIB. EASYX does not require use or knowledge of assembly
- language. The documentation for EASYX is in the file EASYX.DOC.
- If you are familiar with assembly language, then start by reading the file
- DONTREAD.ME. This file is for those who don't particularly enjoy reading 60
- page user manuals. It is an excellent tutorial. You will probably be ready
- to program with XLIB after working through the tutorial.
-
- ******************************************************************************
- A Note to Previous XLIB Users
- ******************************************************************************
-
- Version 4.0 is the fifth generation of XLIB. We appreciate those who have
- labored with us through earlier generations when we were stomping several
- bugs and correcting deficiencies.
- Thanks to your patience and help, XLIB is now a solid product. It is
- presently being used in several high tech industries. We feel that XLIB is
- the easiest way available to program in protected mode under DOS, and it
- remains far less expensive than retail DOS extenders.
-
- TechniLib
-
- ******************************************************************************
- Registering XLIB
- ******************************************************************************
-
- XLIB may be registered for $40/copy. Registrants will be sent a registered
- copy of the XLIB archive along with a printed copy of the user manual. The
- registration fee is $60 for those who have used or intend to use technical
- support. The additional charges do not pertain to those reporting problems
- with XLIB.
- There are three ways to register XLIB:
-
- 1) By credit card through Public (software) Library:
-
- You can order with MC, Visa, Amex, or Discover from Public (software)
- Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398
- or by CIS Email to 71355,470. You can also mail credit card orders to PsL
- at P.O.Box 35705, Houston, TX 77235-5705. The product identification number
- for XLIB is 11077.
-
- PHONE NUMBERS ABOVE ARE FOR ORDERS ONLY. Any questions about the status of
- the shipment of the order, refunds, registration options, product details,
- technical support, volume discounts, dealer pricing, site licenses, etc,
- should NOT be directed to PsL. Direct all such questions to TechniLib.
-
- 2) Through CompuServe:
-
- Use GO SWREG (shareware registration). The program identification number
- is 1778. The program title is XLIB 4.0.
-
- 3) By mail to TechniLib:
-
- Complete and mail the form in REGISTER.FRM
-
- ******************************************************************************
- Improvements in XLIB Version 4.0 Over Version 3.0
- ******************************************************************************
-
- Additions:
-
- The principal improvement in version 4.0 is the inclusion of libraries
- with exception trapping capabilities. XLIB 4.0 can trap all protected-mode
- exceptions. If DPMI 1.0 is installed, then real-mode exceptions can be
- trapped as well. These libraries also contain new functions for managing
- debug watchpoints.
- XLIB 3.0 was limited in that it did not allow the main program to spawn
- other processes. This limitation has been corrected.
- The global descriptor table has been made public in version 4.0.
- PMPRINT.ASM has been replaced with PMIO.INC. The latter contains better
- print routines as well as new keyboard and speaker routines. PMIO.INC is
- designed for either MASM or TASM.
- The MOVMEM routine in EASYX has been redesigned to be faster and to be
- reentrant. This routine may now be called in the main thread, in interrupt
- handlers, or both.
- Microsoft BASIC 7.0 files have been included to illustrate usage of EASYX.
-
- Corrections:
-
- Version 4.0 corrects certain bugs and makes accommodations for anomalies
- in BIOS and common resident software.
- The most severe bug in version 3.0 was a mistake in the include file
- XLIB.INC. The combine type on segment DSEG was set to FAR_DATA, whereas it
- should have been DATA.
- A second bug caused the machine to crash with a call to INITXLIB when
- certain memory managers were used with the NOEMS option.
- Version 3.0 did not preserve the interrupt flag through mode switches.
- Instead it always enabled interrupts after the switch. This lead to awkward
- situations when attempting to use SWITCHPM and SWITCHRM in interrupt handlers.
- Version 4.0 always preserves the interrupt flag through a mode switch.
- A bug prevented SWITCHPM and SWITCHRM from being reentrant under VCPI.
- This bug existed in both versions 3.0 and 3.1. This would have caused a
- problem if nested mode switches were being performed, as would be the case
- with calls to DEFLECTPM or other mode switches within interrupt handlers.
- Certain versions of SMARTDRV.EXE do not restore the global descriptor
- table register. Version 3.0 was not prepared for this
- Certain BIOS software interrupts return with interrupts enabled. Neither
- version 3.0 nor version 3.1 were prepared for this anomaly. It caused the
- machine to hang upon certain hardware interrupts, keypresses in particular.
- The other bugs were applicable only when running XLIB in the absence of
- VCPI and DPMI (HIMEM.SYS only or no memory manager at all). Accesses to
- extended memory failed in some cases. In some cases the machine was left in
- an unstable state.
-
- ******************************************************************************
- Upgrades
- ******************************************************************************
-
- Previous registrants can upgrade to XLIB version 4.0 for $10. Send
- all such orders directly to TechniLib.
-
- ******************************************************************************
- Communicating with TechniLib Via Electronic Mail
- ******************************************************************************
-
- You can communicate with TechniLib via CompuServe electronic mail. Direct
- mail to account 74730,167.
-
- ******************************************************************************
- Instructions for Constructing Protected-Mode Libraries for Microsoft
- ******************************************************************************
-
- The following batch file uses Microsoft LIB to combine an OBJ file with
- XLIB.LIB to produce a protected-mode library. Call the batch file using the
- base name of the OBJ file as the argument. This base name will also be given
- to the library. It is assumed that the OBJ file and XLIB.LIB are in the
- current directory. LIB.EXE is assumed to be in the ..\BIN directory.
-
- @echo on
- del %1.lib
- ..\bin\lib %1.lib /noi +%1.obj+xlib.lib;
-
- The following batch file uses Microsoft LINK and LIB to combine an OBJ
- file with XLIB.LIB to produce a protected-mode library and quick library for
- Microsoft BASIC 7.0. Call the batch file using the base name of the OBJ
- file as the argument. This base name will also be given to the library and
- the quick library. It is assumed that all files apart from LINK.EXE and
- LIB.EXE are in the current directory. The current directory must also
- contain the file QBXQLB.LIB (included in the BASIC distribution disks).
- LINK.EXE and LIB.EXE are assumed to be in the ..\BIN directory.
-
- @echo on
- del %1.qlb
- del %1.lib
- ..\bin\link /q/nopackf xlib.lib+%1.obj,%1.qlb,,qbxqlb.lib;
- ..\bin\lib %1.lib +xlib.lib+%1.obj;
-
- The following command may be used to create a quick library from EASYX.LIB.
- The quick library is called EASYX.QLB:
-
- ..\bin\link /q/nopackf easyx.lib,easyx.qlb,,qbxqlb.lib;
-
- ******************************************************************************
- Instructions for Constructing Libraries and Linking with Borland
- ******************************************************************************
-
- The following batch file uses TLINK to link an OBJ file from TASM with
- XLIBB.LIB to produce a DOS-extended executable. The base name of the OBJ
- is supplied as an argument to the batch file. The executable will be given
- the same base name as the OBJ file. It is assumed that the OBJ file is in
- the current directory and that TLINK is in the ..\BIN directory.
-
- @echo on
- ..\bin\tlink /3/c %1.obj,,,xlibb.lib
-
- The following batch file uses Borland TLIB to combine an OBJ file with
- XLIBB.LIB to produce a protected-mode library. Call the batch file using the
- base name of the OBJ file as the argument. This base name will also be given
- to the library. It is assumed that XLIBB.LIB and the OBJ file are in the
- current directory. TLIB is assumed to be in the ..\BIN directory.
-
- @echo on
- del %1.lib
- ..\bin\tlib /C %1.lib +xlibb.lib+%1.obj
-
- Borland C and Turbo C users can compile within the IDE; however, they must
- use the command line linker because an option will be needed which is not
- included in the IDE linker. In particular, the /3 option will be needed to
- enable processing of 32-bit segments. The appropriate commands to TLINK will
- depend upon the memory model being used. The following batch command will
- link a program called MYPROG with a library call MYLIB under the large memory
- model. The batch command must be issued from the directory containing
- MYPROG.OBJ. It is assumed that TLINK is in the ..\BIN directory and that
- MYLIB.LIB is in the ..\LIB directory. It is also assumed that all of the C
- link libraries are in the ..\LIB directory. The resulting executable will be
- called MYPROG.EXE and the map file will be called MYPROG.MAP. The command
- line is lengthy and is therefore broken into two lines below.
-
-
- --------------------- model specification
- . ----------------- obj file name
- . | ---------- exe file name
- . | | --- map file name
- . ______ ______ ______
- ..\bin\tlink /3/c ..\lib\c0l myprog,myprog,myprog,
-
- ..\lib\mylib ..\lib\fp87 ..\lib\mathl ..\lib\cl
- ----- . .
- | -------------- model specification
- ----------------------------------------- lib file name
-
- To link under the small memory model, replace "l" with "s" at the model
- specification characters. Use "m" for the medium model; "c" for the compact
- model, and "h" for the huge model.
-
- ******************************************************************************
- NOEMS and Equivalent Options
- ******************************************************************************
-
- Numerous of you could never get previous versions of XLIB initialized
- because you were running your memory managers with the NOEMS or equivalent
- option. This problem should be corrected under version 4.0, but we suggest
- that you avoid NOEMS. If you want the upper memory area used by the page
- frame than try FRAME=NONE or equivalent option.
- When EMS is present, VCPI has control of the machine. This means that
- XLIB must work cooperatively with VCPI when performing switches to protected
- mode; otherwise, XLIB would cause a protection violation (exception #13).
- VCPI is a subset of EMS. When you declared NOEMS, it appeared to former
- version of XLIB that VCPI was absent. The latter assumption was false,
- because the memory manager was hiding VCPI behind the NOEMS option. XLIB
- then proceeded to perform uncooperative mode switches. This then generated
- the exception. Version 4.0 takes measures to detect a deceptive memory
- manager.
-
- ******************************************************************************
- General Debugging Instructions
- ******************************************************************************
-
- Neither Turbo Debugger nor Codeview will be able to debug protected-mode
- instructions. However, you should still be able to use the debuggers for
- real-mode areas of your programs. Just step over calls to protected-mode
- procedures.
- Debuggers tend to have problems when XLIB is initialized for DPMI. Use
- VCPI instead. You do this by setting bit 0 of IFLAGS. Of course, a VCPI
- driver needs to be loaded. EMM386, QEMM386, and 386MAX all have VCPI. You
- cannot run VCPI in Windows or OS/2.
- In the event that you can debug under DPMI, then you will have to remember
- that XLIBE and XLIBEB attempt to trap exceptions in real mode, including
- debug exceptions and breakpoints. You better turn these features off by
- setting bit 1 of IFLAGS. This disables all exception trapping and prevents
- remap of hardware interrupts.
- Be sure to read the documentation about the new debugging functions in
- XLIBE.LIB and XLIBEB.LIB. These can be used in protected mode. The new
- exception handlers are going to make life much easier also.
-
- ******************************************************************************
- Instructions for Debugging in the Borland IDE
- ******************************************************************************
-
- To run the IDE debugger, XLIB should be initialized for VCPI. However,
- under the default behavior of the IDE, a VCPI program will not be able to
- allocate extended memory within the IDE. There are potentially two reasons
- for this. First, the default behavior of the DPMI kernel under which the
- IDE operates is to claim all EMS memory and convert it to DPMI memory.
- Since VCPI seeks extended memory through EMS, no extended memory will appear
- to be available. To limit the memory consumption of the DPMI kernel,
- include a statement such as the following in the batch file used to invoke
- the IDE:
-
- set dpmimem=maxmem 2000
-
- This statement limits the memory usage of the DPMI kernel to 2000Kb. If
- EMS memory exceeds this amount, then EMS memory will be available to the
- IDE. However, EMS memory will not be available to a VCPI program running
- within the IDE if the IDE has itself consumed all EMS memory. Therefore,
- one may have to limit EMS memory usage of the IDE. This can be done in the
- OPTIONS|ENVIRONMENT|STARTUP menu of the IDE. Typically, EMS memory usage
- should be set to zero here.
-
- ******************************************************************************
- Known Bugs/Peculiarities in Memory Managers
- ******************************************************************************
-
- 1) All versions of QDPMI appear to map physical address spaces incorrectly.
- The actual mapping call will succeed; however, this call affects QDPMI
- internally such that subsequent calls to allocate extended memory do not
- function correctly. This means that MAPIO and PMMAPIO will not work
- reliably with QDPMI.
-
- 2) Version 1.03 of QDPMI does not handle exceptions properly. The exception
- handler receives the wrong value for the interrupted SS on the stack.
- As a consequence, XLIB will not be able to terminate a program after an
- exception under this version of QDPMI. Reboot will be necessary. This
- problem may also exist in previous versions.
-
- 3) QDPMI apparently does not function properly when the NOEMS option has been
- used on QEMM. NOEMS typically should not be used with any memory manager.
- If you need the space normally allocated to the EMS page frame, then set
- FRAME=NONE (or equivalent option) instead of using NOEMS.
-
- 4) 386MAX versions 6.X and 7.0 leave interrupts disabled after calls to
- certain VCPI memory management functions. This means that when VCPI is
- being used, interrupts will be disabled after calls to PMGETMEM, PMFREEMEM,
- PMRESETMEM, and PMMAPIO.
-
- 5) 386MAX version 7.0 does not properly report the virtual debug status
- register (virtual DR6) upon debug exceptions. Consequently, the DR6
- value presented by the XLIBE exception handler will not be valid. This
- version also fails to clear debug breakpoints upon termination, as required
- of DPMI 1.0 hosts. XLIBE corrects the latter problem by clearing
- breakpoints itself when terminating.
-
- 6) 386MAX version 7.0 apparently mismanages exception #13 from real mode.
- When the XLIBE exception handler attempts to terminate after such
- exceptions, a second exception #13 occurs. This has not proven to be a
- major problem. Simply ignore the second exception.
-
- ******************************************************************************
- Real-Mode Exception Trapping with DPMI Version 1.0
- ******************************************************************************
-
- DPMI 1.0 enables XLIBE to trap exception in real mode. This makes XLIBE
- potentially useful to programmers who would otherwise have no interest in
- protected-mode programming. Simply place a call to INITXLIB early in your
- program and link with XLIBE.LIB (XLIBEB.LIB for Borland users) to implement
- this feature.
- 386MAX version 7.X is the only DPMI 1.0 host of which we are presently
- aware. Notwithstanding the bugs mentioned above, it is an outstanding
- product.
-
- ******************************************************************************
- Contracted Programming and Consultation
- ******************************************************************************
-
- TechniLib will perform contract programming at competitive rates.
- TechniLib will also serve as a consultant to other programmers. Contact
- TechniLib through the channels presented above.
-
- ******************************************************************************
- Improvements in XLIB Version 2.0 Over Version 1.0
- ******************************************************************************
-
- 1) Procedures enabling protected-mode programming in C using inline assembly.
- 2) Protected-mode file routines which can transfer extended memory to files
- or files to extended memory. Sequential and random access are supported.
- 3) Better interrupt management services.
- 4) User-defined descriptors.
- 5) More descriptors.
- 6) More configurability.
- 7) Minor bug fixes
- 8) Better documentation.
-
- ******************************************************************************
- Improvements in XLIB Version 3.0 Over Version 2.0
- ******************************************************************************
-
- 1) Files included in Borland formats.
- 2) EASYX library included for those unfamiliar with assembly langauge.
- 3) MAPIO and PMMAPIO procedures added to XLIB for accessing memory-mapped
- input/output devices.
- 4) Better documentation
-