home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c082_122 / 6.ddi / DOC.ZIP / DBGBOARD.TD < prev    next >
Encoding:
Text File  |  1992-06-10  |  17.2 KB  |  459 lines
  1. /*************************************************************************/
  2.                TURBO DEBUGGER HARDWARE DEBUGGER INTERFACE
  3.                ==========================================
  4.  
  5. Hardware debugging boards greatly speed up certain types of breakpoints;
  6. in particular, those that watch for an area of memory or a program variable
  7. to change. Turbo Debugger has a general interface for accessing these boards.
  8.  
  9. This appendix describes how to write a device driver that Turbo Debugger
  10. can communicate with in order to make use of the capabilities of a
  11. particular hardware debugger. This information is intended for vendors
  12. of hardware debuggers who want to make their boards usable with Turbo 
  13. Debugger. (Note that you must know the general architecture of DOS 
  14. device drivers. Refer to the DOS Technical Reference for more information 
  15. on how to write device drivers.)
  16.  
  17.  
  18. TDH386.SYS: 80386 hardware device driver
  19. ----------------------------------------
  20. The Turbo Debugger distribution disk contains the file TDH386.SYS,
  21. which is a hardware device driver that lets Turbo Debugger use the
  22. debug registers on the 80386 processor. You can use this driver by
  23. copying it to your DOS disk and putting the following line in your
  24. CONFIG.SYS file:
  25.  
  26.    DEVICE = TDH386.SYS
  27.  
  28. Turbo Debugger will then use the hardware assistance of the 80386
  29. whenever it can to speed up breakpoint processing.
  30.  
  31. This means, of course, that you can only use this device driver if
  32. your system uses the 80386 processor or higher.
  33.  
  34.  
  35. Setting hardware breakpoints
  36. ----------------------------
  37. If you need information on using the Turbo Debugger hardware debugging
  38. features, see the file HDWDEBUG.TD.
  39.  
  40.  
  41. Hardware debugger overview
  42. --------------------------
  43. The device driver interface provides device-independent access to the
  44. capabilities of different hardware debuggers. To accomplish this, the
  45. common features of several hardware debuggers have been combined into
  46. one generic hardware debugger. Turbo Debugger then uses this abstract
  47. model to make requests to the device driver. 
  48.  
  49. A particular board might not be able to support all the operations 
  50. specified by the abstract interface. In this case, the device driver 
  51. can inform Turbo Debugger that a requested operation can't be performed. 
  52. A hardware board also might offer more capabilities than the abstract 
  53. interface defines. In this case, Turbo Debugger can't make use of the 
  54. added features of the board.
  55.  
  56. Because we expect the device driver interface to encompass new features
  57. in future releases, we have defined an "implementation level" status
  58. field that the device driver returns when requested. This lets Turbo
  59. Debugger know what the device driver is capable of doing and provides
  60. compatibility with older drivers, while allowing new drivers to take
  61. advantage of capabilities in future releases of the interface.
  62.  
  63. The hardware debugger interface breaks the capabilities of debugger
  64. boards into three main areas of functionality:
  65.  
  66. o memory and I/O access breakpoints
  67.  
  68. o instruction trace-back memory
  69.  
  70. o extra onboard memory for symbol tables
  71.  
  72. This version of the interface supports only the first category. Future
  73. releases will define an interface that accesses the other features.
  74. When you write a device driver, keep in mind that these other
  75. capabilities will be supported at a later date.
  76.  
  77.  
  78. Device driver interface
  79. -----------------------
  80. The device driver is an ordinary character-type device driver named
  81. TDH386.SYS. You must put the following statement in your CONFIG.SYS
  82. file in order for the driver to be loaded when you boot the system:
  83.  
  84.    DEVICE = <drvrname.ext>
  85.  
  86. <drvrname.ext> is the name of the device driver file you have created.
  87.  
  88.  
  89. Device driver function calls
  90. ----------------------------
  91. The device driver must support the following function calls:
  92.  
  93.  
  94. INIT (command code = 0)
  95.   Called once when the device driver is first loaded. Your code for this
  96.   function must make sure that the hardware board is disabled and in a
  97.   quiescent state.
  98.  
  99.  
  100. READ (command code = 4)
  101.   Called by Turbo Debugger to read the status block from the last
  102.   command sent to the device driver. You should keep the last status in
  103.   a data area inside the driver and return as many bytes as requested.
  104.   Each time a read is issued, you must start sending from the beginning
  105.   of the status block, even if the previous read request was not long
  106.   enough to send the entire block.
  107.  
  108.   The section "Status blocks returned by the device driver" describes
  109.   the various status blocks the device driver can return in response to
  110.   different command blocks.
  111.  
  112.  
  113. READNOWAIT (command code = 5)
  114.   Returns the first byte of the status block. The busy bit should always
  115.   be set to 0, indicating that data is available at all times.
  116.  
  117.  
  118. READSTATUS (command code = 6)
  119.   Always sets the busy bit to 0, indicating that a subsequent read
  120.   request would complete immediately.
  121.  
  122.  
  123. READFLUSH (command code = 7)
  124.   Simply sets the done bit in the return status.
  125.  
  126.  
  127. WRITE (command code = 8)
  128.   Called by Turbo Debugger to send a command to the device driver. The
  129.   command will have a variable length depending on the command type.
  130.   You can either copy the data into a work area inside the device
  131.   driver or access it directly using the data pointer that is part 
  132.   of the device driver request.
  133.  
  134.  
  135. The following function calls are command blocks Turbo Debugger can 
  136. send to the device driver:
  137.  
  138.  
  139. WRITEVERIFY (command code = 9)
  140.   Does the same thing as WRITE (command code 8).
  141.  
  142.  
  143. WRITESTATUS (command code = 10)
  144.   Simply sets the done bit in the return status.
  145.  
  146.  
  147. WRITEFLUSH (command code = 11)
  148.   Simply sets the done bit in the return status.
  149.  
  150. All other function calls should set the error bit (bit 15) in the
  151. return status word, and put an "Unknown command" error code (3) in the
  152. low byte of the status word.
  153.  
  154.  
  155. Command blocks sent to driver
  156. -----------------------------
  157. All command blocks sent to the device driver by the WRITE function
  158. call start with a byte that describes the operation to perform. The
  159. subsequent bytes provide additional information for the particular
  160. command.
  161.  
  162. When a hardware breakpoint is set, it is the device driver's
  163. responsibility to check that it has been handed an acceptable
  164. parameter block. It can't just ignore fields that request an operation
  165. it can't perform. You must check each field to make sure that the
  166. hardware can support the requested operation, and if it can't, you
  167. must set the appropriate return code.
  168.  
  169. The first byte can contain one of the following command codes:
  170.  
  171. 0   Install vectors
  172. 1   Get hardware capabilities
  173. 2   Enable the hardware breakpoints
  174. 3   Disable the hardware breakpoints
  175. 4   Set a hardware breakpoint
  176. 5   Clear a hardware breakpoint
  177. 6   Set I/O base address, resets hardware
  178. 7   Remove vectors
  179.  
  180. The following commands send additional data after the command code:
  181.  
  182. 0 (Install vectors)
  183.   
  184.   4 bytes     Far pointer to vector routine
  185.  
  186.               This is a 32-bit pointer, the first word being the offset,
  187.               and the second being the segment. You must save this address
  188.               to enable the device driver to jump to it when a hardware
  189.               breakpoint occurs. This routine should also install any
  190.               interrupt vectors that the device driver needs. Turbo Debugger
  191.               calls this routine once when it first starts up. The Remove
  192.               Vectors (code 10) function is called once by Turbo Debugger
  193.               when it no longer needs to use the hardware debugger device
  194.               driver. At this time, you should replace any vectors that you
  195.               took over when function 0 was called and make sure the hardware
  196.               is disabled.
  197.  
  198.  
  199. 4 (Set a hardware breakpoint)
  200.  
  201.   1 byte      Breakpoint type
  202.  
  203.               0   Memory read
  204.               1   Memory write
  205.               2   Memory read or write
  206.               3   I/O read
  207.               4   I/O write
  208.               5   I/O read or write
  209.               6   Instruction fetch
  210.  
  211.   1 byte      Address-matching mode
  212.  
  213.               0   Match any address, don't care
  214.               1   Equal to test value
  215.               2   Not equal to test value
  216.               3   Above test value
  217.               4   Below test value
  218.               5   Below or equal to test value
  219.               6   Above or equal to test value
  220.               7   Within inclusive range
  221.               8   Outside range
  222.  
  223.   4 bytes     Low address
  224.  
  225.               A memory address in 32-bit linear form. If the address-matching
  226.               mode requires one or more addresses to test against, any single 
  227.               value or the low value of multiple addresses comes here.
  228.  
  229.   4 bytes     High address
  230.  
  231.               A memory address, in 32-bit linear form. If the address-matching
  232.               mode requires two addresses to test against a range, the second 
  233.               and higher value comes here.
  234.  
  235.   2 bytes     Pass count
  236.  
  237.   1 byte      Data-matching size: 1 = byte, 2 = word, 4 = doubleword
  238.  
  239.   1 byte      Source of matched bus cycle:
  240.  
  241.               1   CPU
  242.               2   DMA
  243.               3   Either CPU or DMA
  244.                  
  245.   1 byte      Data-matching mode
  246.  
  247.               0   Match any data, don't care
  248.               1   Equal to test value
  249.               2   Not equal to test value
  250.               3   Above test value
  251.               4   Below test value
  252.               5   Below or equal to test value
  253.               6   Above or equal to test value
  254.               7   Within inclusive range
  255.               8   Outside range
  256.  
  257.   4 bytes     Low data value
  258.  
  259.               If the data-matching mode requires one or more data values, 
  260.               this field supplies the first or only value. The data-matching
  261.               size determines how many bytes of this field are significant.
  262.  
  263.   4 bytes     High data value
  264.  
  265.               If the data-matching mode requires two data values, this field
  266.               supplies the second value. The data-matching size determines 
  267.               how many bytes of this field are significant.
  268.  
  269.   4 bytes     Data mask
  270.  
  271.               If the hardware supports it, this field controls which bits in
  272.               the data are examined for the match condition.
  273.  
  274.  
  275. 5 (Clear a hardware breakpoint)
  276.  
  277.   1 byte      The handle of the breakpoint to clear. The handle was given
  278.               to Turbo Debugger by command 4 (Set Hardware Breakpoint).
  279.  
  280.  
  281. 6 (Set I/O board base address)
  282.  
  283.   2 bytes     The base address of the hardware debugger board.
  284.  
  285.  
  286. Status blocks returned by device driver
  287. ---------------------------------------
  288. The READ function call returns the status block from the device
  289. driver. Different commands written to the device driver result in
  290. various status blocks being built to report what happened. All the
  291. status blocks start with a single byte that describes the overall
  292. result of the requested operation. The subsequent bytes return
  293. additional information particular to the command that generated the
  294. status block.
  295.  
  296. The following status codes can be returned in the first byte:
  297.  
  298. 0   Command was successful.
  299.  
  300. 1   Invalid handle supplied.
  301.  
  302. 2   Full, can't set any more breakpoints.
  303.  
  304. 3   Breakpoint was too complex for the hardware.
  305.  
  306.     The breakpoint could never be set because the hardware is not capable
  307.     of supporting the combination of bus cycle, address, and data-matching
  308.     that Turbo Debugger requested.
  309.  
  310. 4   Command can't be performed due to restrictions imposed by a
  311.     previous command.
  312.  
  313.     The command could have been performed if it weren't for some previous
  314.     operation's preventing it. This could happen, for example, if the
  315.     hardware only permits a single data match value, but Turbo Debugger
  316.     tries to set a second hardware breakpoint with a different data match
  317.     value than the first breakpoint.
  318.  
  319. 5   The device driver can't find the hardware board.
  320.  
  321. 6   A hardware failure has occurred.
  322.  
  323. 7   An invalid command code was sent to the driver.
  324.  
  325. 8   The driver hasn't been initialized with function code 0, so
  326.     nothing can be done yet.
  327.  
  328. The following commands return additional status information after the
  329. status code byte:
  330.  
  331. 1 (Get hardware capabilities)
  332.  
  333.   2 bytes     Device driver interface version number. The current 
  334.               version is 1.
  335.  
  336.   2 bytes     Device driver software version number.
  337.  
  338.               For each released version of your device driver that behaves
  339.               differently, this field should contain a different number. 
  340.               This lets Turbo Debugger take special measures if necessary, 
  341.               based on this field.
  342.  
  343.   1 byte      Maximum number of hardware breakpoints that this
  344.               driver and board combination can support.
  345.  
  346.   1 byte      Configuration bits
  347.  
  348.               Bit  Meaning when set
  349.               ---  ----------------
  350.                0   can distinguish between CPU and DMA accesses
  351.                1   can detect DMA transfers
  352.                2   has data mask
  353.                3   breakpoints have hardware pass counter
  354.                4   can match on data as well as address
  355.  
  356.   1 byte      Breakpoint types supported (bit mask)
  357.  
  358.               Bit  Function
  359.               ---  --------
  360.                0   Memory read
  361.                1   Memory write
  362.                2   Memory read or write
  363.                3   I/O read
  364.                4   I/O write
  365.                5   I/O read or write
  366.                6   Instruction fetch
  367.  
  368.   2 bytes     Addressing match modes supported (bit mask)
  369.  
  370.               Bit  Function
  371.               ---  --------
  372.                0   Match any address, don't care
  373.                1   Equal to test value
  374.                2   Not equal to test value
  375.                3   Above test value
  376.                4   Below test value
  377.                5   Below or equal to test value
  378.                6   Above or equal to test value
  379.                7   Within inclusive range
  380.                8   Outside range
  381.  
  382.   2 bytes     Data-matching modes supported (bit mask)
  383.  
  384.               Bit  Function
  385.               ---  --------
  386.  
  387.                0   Match any data, don't care
  388.                1   Equal to test value
  389.                2   Not equal to test value
  390.                3   Above test value
  391.                4   Below test value
  392.                5   Below or equal to test value
  393.                6   Above or equal to test value
  394.                7   Within inclusive range
  395.                8   Outside range
  396.  
  397.   1 byte      Maximum data match length
  398.  
  399.               Set to 1, 2, or 4 depending on the widest data match or 
  400.               mask that the hardware can perform.
  401.  
  402.   2 bytes     Size of onboard memory in kilobytes.
  403.  
  404.   2 bytes     Maximum number of trace-back events that can be recalled.
  405.  
  406.   2 bytes     Address of hardware breakpoint enable byte
  407.  
  408.               Specifies the segment address where Turbo Debugger must 
  409.               write a byte with a value of 1 to enable hardware breakpoints. 
  410.               The field must contain 0 if the device driver does not or 
  411.               cannot support this capability. If it is supported, this 
  412.               byte lets Turbo Debugger inform the device driver that it 
  413.               has finished writing to the address space of the program 
  414.               being debugged, and that subsequent accesses can cause 
  415.               hardware breakpoints.
  416.  
  417. 4 (Set a hardware breakpoint)
  418.  
  419.   1 byte      A handle that Turbo Debugger will use to refer to this
  420.               breakpoint in the future. The device driver also uses this 
  421.               handle when calling back into Turbo Debugger after a hardware
  422.               breakpoint has occurred. The handle must be greater than or
  423.               equal to zero (0). Negative values (top bit on) indicate a
  424.               special condition when the device driver calls Turbo Debugger
  425.               with a hardware breakpoint.
  426.  
  427. -2 (Recursive entry)
  428.  
  429.   1 byte      The special value FE (hex) can be returned by the hardware
  430.               device driver if it has been recursively entered while 
  431.               processing a hardware breakpoint. This can happen if a 
  432.               hardware breakpoint has been set in the 6 bytes below the
  433.               current top of stack in the program being debugged. If
  434.               Turbo Debugger receives this entry code, it displays a
  435.               message that the device driver can't proceed because of
  436.               a breakpoint's being set near the top of the stack.
  437.  
  438.  
  439. Device driver call into Turbo Debugger
  440. --------------------------------------
  441. When the hardware board and the device driver software have determined
  442. that a hardware breakpoint has occurred, control must be transferred
  443. to the address inside Turbo Debugger that was specified with command
  444. code 0 (Set Hardware Breakpoint Vector).
  445.  
  446. The vector address must be jumped to with the CPU state exactly as it
  447. was when the hardware breakpoint occurred, but with the program's AX
  448. register pushed on the stack and an entry code now in the AH register.
  449. The entry code can be
  450.  
  451. >= 0        The handle of the triggered breakpoint
  452.  
  453. -1 (FF)     The breakout button was pressed
  454.  
  455. Turbo Debugger will never return to the device driver once it is
  456. jumped into from a hardware breakpoint.
  457.  
  458. /**************************** END OF FILE ********************************/
  459.