home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / GDT.ZIP / DEVHLP.DOC < prev    next >
Text File  |  1989-03-15  |  6KB  |  153 lines
  1. DEVHLP.SYS -- preliminary documentation
  2.  
  3.     This is abbreviated documentation for DEVHLP.SYS, an OS/2 device
  4. driver that gives normal OS/2 applications access to the DevHlp
  5. facilities.  In particular, DEVHLP.SYS gives OS/2 applications access
  6. to the PhysToUVirt DevHlp.
  7.  
  8.     Because it is a device driver, DEVHLP.SYS must be loaded from
  9. an OS/2 CONFIG.SYS file with the statement:
  10.  
  11.         DEVICE=DEVHLP.SYS
  12.  
  13.     Applications call DEVHLP.SYS using the OS/2DosDevIOCtl function
  14. call.  DosDevIOCtl takes five parameters:
  15.  
  16.         FAR PTR TO BUFFER -- receives data
  17.         FAR PTR TO BUFFER -- contains parameters
  18.         WORD -- function number
  19.         WORD -- category number
  20.         WORD -- device handle
  21.  
  22.     This requires that your application have a device handle to
  23. DEVHLP.SYS.  The ASCII string name of DEVHLP.SYS is "DEVHLPXX."  To
  24. get a device handle to DEVHLPXX, use the DosOpen call.  For example,
  25. from C:
  26.  
  27.         #define INCL_DOS
  28.         #define INCL_DOSDEVICES
  29.         #include "os2.h"
  30.         #include "devhlp.h"
  31.         ...
  32.         unsigned short devhlp = 0;
  33.         unsigned short action = 0;
  34.         ...
  35.         /* open up DEVHLP device */
  36.         if (DosOpen("DEVHLPXX", &devhlp, &action, 0, 0, 1, 0x40, 0))
  37.             return fail("Can't find DEVHLP.SYS");
  38.         /* at this point, devhlp contains device handle */  
  39.  
  40.     The category number used by DEVHLP.SYS is 128, and the function
  41. number is hex 60 (there are reasons for these seemingly arbitrary
  42. numbers, but we won't get into them here).
  43.  
  44.     The two far pointers required to call DEVHLP.SYS through
  45. DosDevIOCtl should each point to a 18-byte data structure.  The two
  46. far pointers can point to the _same_ 18-byte buffer, similar to
  47. the int86() interface used in MS-DOS C compilers.  The structure
  48. of this buffer is:
  49.  
  50.         typedef struct {
  51.             unsigned short ax, bx, cx, dx, si, di, ds, es, flags;
  52.             } REGS;
  53.             
  54.     For applications written in C, this data structure is defined in
  55. the #include file DEVHLP.H.  In addition, the last field, flags, is
  56. defined as a C bitfield for easy access to the carry flag.
  57.  
  58.     For example:
  59.         
  60.         ...
  61.         REGS regs;
  62.         ...
  63.         DosDevIOCtl(®s, ®s, 0x60, 128, devhlp);
  64.         ...
  65.             
  66.     For the input buffer, DEVHLP.SYS will use the AX, BX, CX, DX, and
  67. DI registers.  DEVHLP.SYS will load the *real* registers from these
  68. fields of the input buffer, and will call DevHlp.  Upon return from
  69. DevHlp, DEVHLP.SYS will store the contents of AX, BX, ES, DS, SI, DI,
  70. and the flags into the appropriate fields of the output data
  71. structure.  For example, here is a C function that provides a
  72. convenient way to call the PhysToUVirt DevHlp:
  73.  
  74.         #define MAKEUSHORT(l, h) (((USHORT)(l)) | ((USHORT)(h)) << 8)
  75.         #define MK_FP(seg,off)  ((void far *)(((ULONG)(seg) << 16) | (off)))
  76.         #define DevHlp_PhysToUVirt      0x17
  77.         #define UVirt_ReadWrite         1
  78.         ...
  79.         /* turn physical address into virtual address */
  80.         void far *PhysToUVirt(USHORT hi, USHORT lo, USHORT limit, BYTE type)
  81.         {
  82.             REGS regs;
  83.             USHORT ret;
  84.             regs.ax = hi;
  85.             regs.bx = lo;
  86.             regs.cx = limit;
  87.             regs.di = 0;
  88.             regs.dx = MAKEUSHORT(DevHlp_PhysToUVirt, type);
  89.             ret = DosDevIOCtl(®s, ®s, 0x60, 128, devhlp);
  90.             return (ret || regs.flags.carry) ? (void far *) 0 :
  91.                 MK_FP(regs.es, regs.bx);
  92.         }
  93.         ...
  94.         /* get read/write access to 20 bytes at 0FE008 */
  95.         ptr = PhysToUVirt(0xF, 0xE008, 20, UVirt_ReadWrite);
  96.  
  97.     The placement of values in the REGS data structure corresponds
  98. to what an OS/2 device driver would do to invoke the PhysToUVirt
  99. facility, as described in the OS/2 device drivers kit documentation
  100. or in Ray Duncan's ADVANCED PROGRAMMER'S GUIDE TO OS/2 (Microsoft
  101. Press, 1989):
  102.  
  103.         AX:BX -- 32-bit physical address
  104.         CX -- length in bytes
  105.         DH -- request type (0=executable, 1=read/write, 2=release)
  106.         DL -- 17 hex
  107.             
  108.     Similarly, an application must examine the output buffer in the
  109. same way that a device driver would examine the actual machine
  110. registers.  In the case of PhysToUVirt, after calling DevHlp:
  111.  
  112.         ; if function successful
  113.         CARRY FLAG -- clear
  114.         ES:BX -- virtual address
  115.             
  116.         ; if function unsuccessful
  117.         CARRY FLAG --set
  118.         AX -- error code
  119.             
  120.     Note that DEVHLP.SYS does not check the carry flag after calling
  121. DevHlp.  It does, however, place the flags in the output structure.  It
  122. is up to your application to check the carry flag to see if an error
  123. occurred (if you don't use DEVHLP.H, the carry flag is:  regs.carry & 1).
  124.  
  125.     DEVHLP.SYS performs no validation of your input parameters.
  126. However, DEVHLP.SYS *will* check to make sure that the pointers you
  127. passed in do in fact point to memory to which your application has
  128. legal rights.  If the pointers are not valid for your application, it
  129. will be terminated with a general protection (GP) fault.  For
  130. example, a guaranteed way to generate a GP fault:
  131.  
  132.         /* bad code! */
  133.         DosDevIOCtl(666L, 666L, 0x60, 128, devhlp);
  134.         
  135.     When you are done using DEVHLP.SYS, close the device handle with
  136. a call to DosClose:
  137.  
  138.         DosClose(devhlp);
  139.         
  140.     More thorough documentation on DEVHLP.SYS will be available soon.
  141. In the meantime, read the comments in DEVHLP.ASM, and examine the
  142. sample application GDT.C.  You may find GDT.EXE interesting in its
  143. own right (see the documentation GDT.DOC).
  144.             
  145. -- Andrew Schulman
  146.    32 Andrew (!) Street
  147.    Cambridge MA 02139
  148.    617-876-2102 (h)
  149.    617-57-8500 x7148 (w)
  150.  
  151.    4 January 1988
  152.  
  153.