HDebug V1.0 ©1991 Mick Tinker 21-Jul-91 ======================================= Copyright --------- This software is Copyright ©1991 Index Information Ltd. Permission is given to freely distribute V1.0 of this software provided: a) The software is only used for the purposes of developing software for use with the Harlequin 32 bit graphics card. b) No modifications are made to the software, specifically the copyright notices. c) The documentation, including this notice is distributed with the program. d) No charge other than media costs are made for the supply of the software and documentation. HDebug V1.0 is supplied with no warranties or guarantees as to its ability to perform its intended function and no responsibility will be taken for any fault or expence resulting from its use. Introduction ------------ HDebug is a debugging tool for use with the Harlequin 32 bit graphics card. It operates by patching all vectors of the harlequin.library or its cardless equivalent. When a call is made to the library requested information will be printed out, either to stdout or to a file. Because harlequin.device uses the harlequin.library to perform all of its drawing functions, it is just as practical to debug device operations as it is to debug library operations. This software will be of particular help to developers using the harlequin_cardless.library, which can be used to develop or adapt software for the Harlequin without requiring the presence of the actual card. Version 1.0 of HDebug is the initial release. While every attempt has been made to trap common program faults and supply useful information, it is anticipated that there will be room for additional improvements in the future. Feed-back from users will be an essential requirement to achieve improvements, so let us know what you need. Our aim is to help you produce the best and most reliable products for the Harlequin graphics card. Operation --------- Start the program from either CLI or Workbench. If started from CLI an optional filename can be specified for output. Output can be sent to the serial port to a comms package on another computer, this will allow the debug information to be displayed even when the program under development uses the whole of the Amiga's display. Another advantage of this method of debugging is that a crash will not destroy the most recent output, and with a suitable comms package a scroll-back facility will be available to allow a review of the events leading up to the crash. To start HDebug, with output going to a window on the workbench screen enter the following at a CLI or Shell: hdebug To start HDebug and send the output to a terminal program on another computer, first ensure the preferences setting for the serial connection matches the setting of the comms program on the computer connected to the serial port, then enter the following at a CLI or Shell: hdebug ser: Setup ----- When the program starts, all debugging information is turned off. The first stage if to turn on debugging for the functions that are of interest to you. Because of the overhead of checking call parameters and printing information, it is recommended that most functions are left off or set to just print failures and faults. To turn a function on place the mouse pointer over the function gadget in the HDebug window, click the left mouse button. The function can be turned of in the same manner. To change the level of information printed, click on the ALL/FAULT gadgets to the right of the function name gadgets. ALL will print all information for each function call. Because of the large amount of information printed there will be a significant reduction in speed, however this mode can be useful when tracing program flow and examining individual library calls. FAULT will only print information when a fault occurs or when clipping takes place. Strategy -------- While a program that runs may appear to be functioning perfectly it is still desirable to use HDebug to test for faults in function calls using the FAULT error reporting level. To maximise drawing speed only minimal error checks are performed within the library, HDebug will carry out the extended parameter checks that, once fixed, will not usually reoccur during normal application usage. If a crash or drawing fault is thought to be occuring during a screen operation first attempt to identify the circumstances that will reliably cause the fault to occur. Turn on FAULT level debugging and run the application, attempting to repeat the fault. If no error messages are printed it will be necessary to use the ALL level of debugging. HDebug may write information at two different times during debugging, before the function call - this will usually be the parameters passed to the function - and after the function has been called, which will be information returned by the function. Using a seperate computer and comm's program is especially useful when searching for difficult to locate faults, as when the failure occurs a review of the most recent actions can be made by examination of the scroll-back buffer. To ensure efficient execution a few tests using the ALL debug level may highlight unnecessary function calls. Optimisation ------------ During testing it may be a wise idea to review the way your application is written. The harlequin.library is written totally in assembler with the aim of ensuring maximum drawing efficiency. Quite often the largest overhead is caused by the function call and the initial clipping of the parameters, therefore a method of operation that minimises function calls will often result in a significant increase in performance. A horizontal or vertical line can be drawn much faster using HRectFill rather than multiple calls to HSetPixel or HWritePixel. If possible combine writing several lines into one operation, rather than writing each individual line. If possible when many operations have to be carried out use the library in preference to the device driver, as the call overhead is reduced by not having to perform message passing. Final Testing ------------- If you are developing an application please contact Amiga Centre Scotland, the developers and distributors of the Harlequin graphics card. As well as being able to assist with testing your finished product on various cards with different configurations they may be able to provide marketing assistance and advice. Index Information Ltd Amiga Centre Scotland 40a Woburn Avenue 4 Hart Street Lane Farnborough Edinburgh Hampshire EH1 3RN GU14 7EF Scotland England Tel: (0)31-557-4242 Fax: (0)31-557-3260 EMail: index@cix.compulink.co.uk mlowe@cix.compulink.co.uk