Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / dosutils / xdosman.arj / CHAPT11.DOC < prev next >

Wrap

Text File | 1991-11-28 | 36.2 KB | 1,160 lines

Chapter 11. The X-DOS DEBUG Program Introduction The DEBUG command is a highly technical tool and a basic knowledge of assembly language would be advisable to gain the most from the features provided by this program. This section will cover all the features of DEBUG including several examples but will not be a guide in hexadecimal arithmetic or the programming of the 8088 microprocessor family, so if you are not already familiar with assembly language and computer programming you will certainly need third party literature covering these subjects. Purpose: This utility provides the user with a flexible environment for testing, modifying, viewing and creating executable programs (.COM and .EXE files) and binary files as well as a simple tool to view and modify disk data. Format: DEBUG [d:][path][filename [parameters]] Where [d:] is the drive from which to load a file into DEBUG. [path] is the path to the file to load into DEBUG. [filename] is the name of the file to load into DEBUG. If there is no existing file with the specified filename, DEBUG will display an error message. [parameters] are any parameters needed by the file being loaded into DEBUG. Starting DEBUG You can start DEBUG in two ways. One way is to run DEBUG without specifying a filename. In this case you either have to work with the current contents of the memory, input your own data from the keyboard or load data from the disk with the Load command, either from the command line or from the menu. The other way is to specify a filename including any necessary parameters along with the DEBUG command. You can then immediately start to execute, modify and display the contents of this file. Here is a short description of the two ways to start DEBUG: Starting DEBUG with No Command Line Parameters 11-1 To start DEBUG with no command line parameters you should type: DEBUG This will load DEBUG and display the DEBUG screen which is a full-screen split into four window areas. The lower window shows the command prompt which looks like this: Command : _ This is where you enter your commands to DEBUG. You did not specify a filename when you loaded DEBUG so you can not immediately run a program from within DEBUG. There are several things you can do at this stage though. You can display and/or modify the contents of memory or disks; you can type an assembly program directly into DEBUG, run it and/or save it to disk; you can load a file into DEBUG with the L command to give just a few examples. Starting Debug with Command Line Parameters To start DEBUG with command line parameters you should use the following format: DEBUG filename [parameters] This will load both DEBUG and the specified file into memory. The DEBUG display will look similar to the display of DEBUG when loaded without any parameters except that the information shown in the windows now reflects information about the loaded file. An example of loading a file including parameters into DEBUG from the command line would be: DEBUG FORMAT.EXE A: /360 It is important to note that the filename of the file you want to load into DEBUG must be specified including the extension. If the file does not reside in the current directory, you will have to specify a drive specification and path name to the file. When you load a file into DEBUG, the registers and flags are set to the following values: * The Instruction Pointer (IP) is set to HEX 0100 for COM files and to the starting CS:IP for EXE files. * The Stack Pointer (SP) is set to the bottom of the transient portion of the program loader or the end of the segment, depending on which one has the lowest value for COM files , or to the value available in the EXE header for EXE files. * The segment registers CS, DS, ES and SS are set to the segment right after the DEBUG program for COM files. For EXE files, DS and ES are set to the PSP segment. * The other registers AX, BX, CX, DX, BP, SI and DI are all set 11-2 to HEX 0000. * The flags are always set to the values; Nv, Up, Ei, Pl, Nz, Na, Po and Nc. The DEBUG Screen The X-DOS DEBUG command is a full-screen program with distinct windows for different functions. The display will enable you to monitor the debugging process with very little effort and contains all functions available with DEBUG. By typing the function key corresponding to the menu name,or by clicking on the menu name with a mouse, you will get a pull down menu with functions related to each of the menu listed in the menu bar. The upper-left window is the Assemble/Unassemble window. This is the area where unassembled code is displayed. The upper-right window is the Registers/Flags window. This area always shows the current status of the Registers and Flags. The registers can be changed manually. The middle window is the Dump area which displays the contents of a portion of memory. The Dump area is split in two sections; the left section shows the memory contents in hexadecimal and the right section shows the memory contents as ASCII characters. Alternatively, when using the Assemble command this window is the area where you can input assembler codes directly. The lower window is the Command window where the user types in commands to DEBUG. Each command must be followed by the [Enter] key in order to be executed. All commands typed in the command line are remembered by DEBUG in a circular buffer similar to the DOS prompt and can be recalled by using the up and down arrow. If you wish to cancel a command typed in, just press the [ESC] key. Quick Reference Guide of Debug Commands A [start-address]Assemble The Assemble command places the user in the middle DEBUG window and allows the user to assemble mnemonics directly into memory. BC [n] - Break-point Clear The BC command lets you clear a break point and thus free one of the 10 places reserved for break points. 11-3 BP [Start-address] ┼ Break Point The BP command lets you specify up to 10 break points in memory. BE [n] - Break-point Enable The BE command lets you enable a break point that was previously disabled with the BD command. BD [n] - Break-point Disable The BD command lets you disable a break point temporarily in case you wish to keep it in memory but not activated. It can be later reactivated with the BE command. C start-address end address destination ┼ Compare The Compare command compares two portions of memory. D [start-address] - Dump The Dump command displays 128 bytes from the optional starting address. E [start-address] - Edit Memory The Edit Memory command places the user in the Dump window. Here the user can change the byte values of memory either in hexadecimal or in ASCII. F start-address end-address values - Fill The Fill command will fill a specified part of memory with a 11-4 hexadecimal value. G [= start-address] - Go The Go command will execute a program in memory and stop execution at up to 10 different break points. H hexnumber1 hexnumber2 - Hex Calc The Hex Calc command will return the sum and difference between two hexadecimal numbers. I port - Input The Input command fetches one word/byte from the specified port. L address filename - Load The Load command loads a file into memory. M start-address end-address destination - Move The Move command moves a block of memory to a different address in memory. O port value - Output The Output command sends a one word/byte value to the specified port. P [=address] [value] - Process The Process command enables the user to execute a repeat string instruction, a loop instruction, a subroutine, or an interrupt before 11-5 stopping program execution. Q - Quit The Quit command terminates the DEBUG session and returns the user to the X-DOS prompt. R register - Register The Register command let you change the value of each register. The default value is given in the register window. RS - Segment The Segment command let you change the value of each segment. The default value is given in the segment window. RF - Flags The Flags command let you change the value of each individual flag by choosing 'S' for flag SET and 'R' for flag RESET. S start-address end-address values string - Search The Search command will search a range of memory for one or more hexadecimal values. T - Trace The Trace command executes a program one instruction at a time and return to the debug screen at each program step. 11-6 U [start-address] - Unassemble The Unassemble command disassembles the information in memory into corresponding mnemonics. W address length [filename] - Write The Write command writes a file or range of memory to a disk. Command Parameters Following is a description of the different parameters. Address refers to a specific location in memory. An address is a combination of a segment part and an offset part. The segment part of an address can be omitted in which case the default Data Segment (DS) is assumed except for the Break Point (BP), Load (L), Unassemble (U) and Write (W) commands. Both the segment and offset part are made up of four hexadecimal digits but the segment part can be referenced with the Segment Register letters (i.e. CS). When specifying both a segment and offset part of an address, the two parts must always be separated by a colon (:). Leading zeros can be omitted in the address specification. The following two addresses are therefore equivalent: 0054:0100 and 54:100 The specified address must always be a valid address or otherwise unpredictable results may occur. Note also, that the X-DOS debugger lets you replace an hexadecimal address by a segment and/or a register name. Break-point is a specified address where program execution will stop. Destination the address to which the Move (M) command moves a range of data, or the beginning address at which the Compare (C) command compares a specified range of memory. Drive is a one digit value describing a logical drive letter. 0=A:, 1=B:, 2=C: and so on. Filename 11-7 is any valid filename including extension. Include a drive specification and path in front of the filename if necessary. Hexnumber is any valid hexadecimal number consisting of up to 4 digits. Port specifies an 8 or 16-bit port address and can consist of from one to four hexadecimal digits. Register is any valid register specification. The register specifications are; AX, BX, CX, DX, BP, SP, SI, DI, IP, CS, DS, ES and SS. String is a range of ASCII characters enclosed in double quotes or HEXA characters with no quotes. For instances, the strings "HELLO" and 48454C4C4F are similar and valid. Value is a single byte value in hexadecimal notation. Special Function Keys The X-DOS debugger has defined the function keys as follow : F1 will display a global help on the DEBUG commands F2 will display the File functions menu F3 Will display the Disk functions menu F4 Will display the Memory/Flag/Segment/IO functions menu F5 Will display the Break Point functions menu F6 is similar to the G command F7 Is similar to the T command F8 is similar to the P command F9 output DEBUG screen to alternate screen if connected F10 will swap the user/debug screen Advanced Menu Commands Some of the commands in the DEBUG utility can only be activated by the Menu bar and not at the command line. These functions concern disk access and are summarized as follows: Change Drive The user can change the default drive that will be needed when loading Sectors, Clusters ... from disk. Simply type in the drive number. No network drives can be typed in. Load Sector Users can load a sector of the current drive in memory by 11-8 specifying the start and end sectors as well as the loading address. Here the sectors are the logical partitions sectors, starting at sector 0. Write Sectors Users can write a portion of memory to logical sectors on the disk. Remember that the writing will allways take place as full sectors. It is not possible to write half of a sector only. Load Boot The boot is the first sector of the disk. This function is equivalent to loading the sector 0 from the disk by using the Load Sector function. It is provided as a separate command for convenience. Write Boot It is also possible to write the boot record from a memory location. If you wish to change the boot ID, just load the boot at address 100 for instance, edit the memory with new values and rewrite the boot again. Load the File Allocation Table (FAT) The FAT is the area where the file cluster chains are kept. It follows the boot record in the disk format. This commands loads the entire FAT in memory. You do not have to specify a length. Write the FAT For some reason, you wish to edit manually the FAT, load it first with the Load FAT command, make the necessary modifications, and rewrite it. There is no need to specify sector number or length. Load Root Dir This function is similar to the Load FAT but reads the Root Directory. Write Root Dir This function is similar to the Write FAT but writes the Root directory. Load Cluster A cluster is the smallest allocation unit for a file. It can contain one or more sectors. The cluster number always starts at 2. When loading a cluster, just specify the first and the end cluster as well as the location where they should be loaded. Write Cluster. This function helps you write clusters to disk after being modified. Search Sector for Text This function will search the specified region of disk for a matching string of characters either in Hexadecimal or in ASCII. 11-9 Characters entered in hexadecimal should not be separated by space as this would represent the end of the string. For instance if you wish to find the characters 123 in the disk, you would input 313233 as a string to search. If you wish to input text in ASCII form, you will put it as "123". Command Reference A detailed reference to all the DEBUG commands which can be direclty entered in DEBUG is given on the following pages. A - Assemble Command The Assemble Command assembles 8086/8088 mnemonics into memory without needing to recompile a program before running it. The format of the Assemble Command is: A [start-address] You will be placed in the Data/Dump window which will now look similar to this: 2DD1:0100 _ DEBUG displays the starting address with both segment and offset part. Now you can enter your assembler mnemonics and press <> after every instruction and DEBUG will show the next address. If you type a mistake, DEBUG displays the error message Syntax Error and returns to the same address. When you have entered all desired mnemonics just press <> on an empty line and DEBUG will return you to the Command window. When you have entered enough lines of mnemonics to fill the window, DEBUG scrolls the Assemble display up one line at a time when you add new lines. There are several things to note when entering mnemonics directly in DEBUG since some situations differ from using an assembler. In DEBUG you must enter all numeric values in hexadecimal. * Word memory locations and byte memory locations can not be distinguished by DEBUG so you must clearly state the data type with a prefix which can be either WORD PTR or BYTE PTR. In * DEBUG you must specify the address for jumps and calls. * You must use square brackets ⌐[ ]¬ to refer to memory locations since DEBUG can not distinguish memory locations from immediate operands. Example: The following sample program will blank the screen when you run it and restore the screen again when you press a key. Try to type it in and run it to get a feel of the use of the Assemble command. Note however that if you have a monochrome system you will need to change the first line of the sample program to MOV 11-10 AX,B000. First type : A 100 to go into assemble mode and access the Assemble/Unassemble window. Then type in the following program: MOV AX,B800 MOV DS,AX MOV CX,07D0 MOV BX,1 MOV BYTE PTR[BX],0 ADD BX,2 LOOP 010B MOV AH,1 INT 16 JZ 0113 MOV CX,07D0 MOV BX,1 MOV BYTE PTR[BX],7 ADD BX,2 LOOP 011F RET After typing in these 16 lines press <> on an empty line to return to the Command window. Now you should give the program a name and save it to disk. To give the program the name BLANK.COM, type: W 100 28 BLANK.COM Leave DEBUG with the Quit (Q) command and test the BLANK.COM command by entering: 11-11 BLANK Your screen should blank. B - Break Point Command The Break Point command lets you specify one of 10 break points that can be set simultaneously by DEBUG, enable, disable or reset a break point. 3 commands are available to manage break points : BC, BP, BE, BD. The format of the Break Point command is: BP [address] When you press the G command to activate your program and the processor reaches the address where the break point is set, it will break and return to the DEBUG screen. Note that the break point is still valid if set with the BP command. The format of the BE,BC,BD commands are: Bx [break point number] Where x is either E, C or D and the breakpoint number is from 1 to 10. C Compare Command C - Compare Command The Compare command compares one memory section with another equal size memory section. The format of the Compare command is: COMPARE start-address end-address destination If the contents of the two memory sections are identical, DEBUG will just return the cursor to the normal command position and wait for another command. If, however, there are differences in the two memory sections, DEBUG will display information on the first occurrence of differences in a window. If you do not enter a segment when specifying the start-address and destination, DEBUG will assume the segment value as the current value of the DS register. D - Dump Command The dump command can display the contents of the memory in steps of 128 bytes. The format of the Dump command is: D [start-address] 11-12 The Dump window is located just below the Assemble/- Unassemble window and is separated into two areas; a hexadecimal display area and an ASCII display area. The ASCII display area will not show non-printable characters. Non-printable characters will be substituted with a period (.). If you do not specify a start-address for the Dump display, DEBUG will assume the start-address DS:0100. Subsequently issuing the D command will advance the Dump display in steps of 128 bytes. E - Edit Memory Command The Edit Memory command lets the user enter values into memory in either hexadecimal or ASCII format. The format of the Edit Memory command is: E start-address When you issue the Edit command, you will be placed in the Dump window in the hexadecimal area at your specified starting address. To change any of the memory locations just highlight them and type in the new values. Any changes in the hexadecimal Dump area will immediately be reflected in the ASCII area and vice versa. You can use the following keys to move around the area: Cursor Up - move 16 bytes above current location Cursor Down - move 16 bytes below current location Cursor Right - move 1 byte to the right Cursor Left - move 1 byte to the left PgUp - move 128 bytes above current location PgDn - move 128 bytes below current lcoation If you want to access the corresponding ASCII display area just press the <> key which can be used to switch between the hexadecimal and ASCII areas. When you have made your changes just press the <> key to return to the command window. F - Fill Command The Fill command will fill a specified range of memory with one hexadecimal. The format of the Fill command is: F start-address end-address value This command can be used to reset an area of memory to 0 for instance. The value parameter can only be a byte in hexadecimal. G - Go Command The Go command executes the current program in memory. The format of the Go command is: 11-13 G [=start-address] [break-point] When program execution is finished, DEBUG displays the message Program terminated normally. When you encounter this message you will have to reload the program before running it again. Issuing the Go command without any parameters will run the program currently in memory from the address generated with the CS and IP registers (CS:IP) without any interruptions as if it had been run from the DOS prompt. To issue the Go command in this manner just type: G You can also force DEBUG to execute a program from another starting point than the CS:IP address by specifying the =start- address parameter which is the offset part of the address. The segment part of the address will still be the contents of the CS register. An example of this type of program execution is: G=200 which will force DEBUG to start program execution at the CS:0200 address in memory. It is also possible to use break-points to stop program execution when DEBUG reaches a specific address in a program. The Go command accepts a break-point as a parameter. This break point is different from the Break points set with the BP command in that it is discarded once this Break point is reached, while the traditional break points remain enabled. DEBUG will stop program execution when it reaches either the specified break-point or the ones enabled. An example of starting a program with a specified break point address is: G 0133 DEBUG would stop program execution if it encountered any of the three break-point addresses. If none of the specified break- addresses are encountered, the program execution would continue until the program terminates. H - Hex Calc Command The hex calc command returns the sum and difference between two hexadecimal numbers. The format of the Hex Calc command is: H hexnumber1 hexnumber2 11-14 This command takes two hexadecimal parameters each of up to four digits. Then it adds the parameters and subtracts the second parameter from the first parameter and displays the sum and difference in a window. Example: If you type: H 100 AB DEBUG will display the result: Sum is 01AB Difference is 0055 where the result 01AB is the sum of the two parameters and the result 0055 is the difference between the two parameters. I - Input Command The Input command retrieves one or two byte from a specified port and displays it in the Command window. The format of the Input command is: I port Example: If you type I 0B you will read the contents of port 0B HEX. If we suppose that the contents of port 0B HEX is 43 HEX then DEBUG would read this byte and display the following in a window: [43] L - Load Command The Load command loads a file into memory for further manipulation. The format of the Load command is: L filename [address] When a file is loaded into memory in this manner it is always loaded beginning from the address defined by CS:0100 if it is a COM file or at the starting CS:IP for an EXE file. If you want to load a file that is not a .COM or .EXE file you have to specify the address. Suppose you want to load the COMMAND.COM file at address 100, you would type the command : L 100 COMMAND.COM M - Move Command The Move command moves a specified block of memory to a different 11-15 location in memory. The format of the Move command is: M start-address end-address destination The Move can command move data accross segment to another area. If no segment part of an address is specified, the DS segment is automatically assumed. If the end and destination segment address are not specified, they will have the value of the start address. Examples: The following example moves data from address 4000:300 trough address 8000:600 to the memory location beginning from address CS:AAAA: M 4000:300 8000:600 CS:AAAA To see the moved data you just type: D CS:AAAA O - Output port Command The Output to port command sends a byte or a word to the defined IO port. The format of the Output port command is: O port value Example: If you type: O A03 3F you will send the hexadecimal byte 3F to port A03 HEX. P - Process Command The Process command enables the user to execute a repeat string instruction, a loop instruction, a subroutine, or an interrupt before stopping program execution. The format of the Process command is: P The Process command works similar to the Trace (T) command. It singles steps through instructions until it encounters a subroutine, a loop instruction, a repeat string instruction or an interrupt in which case it finishes the execution of one of these before handing over control to the user. The program execution will start at the current CS:IP. 11-16 Q - Quit Command The Quit command exits DEBUG and returns to the X-DOS command line. The format of the Quit command is: Q The Quit command does not save the file you are currently working with when you exit DEBUG so you will have to remember to save any valid data before using the Quit command. R - Register/flag/segment Command The Register/flag/segment command lets the user modify the contents of any of the registers, flags and segments. The format of the Register/flag/segment command is: R for modifying registers RF for modifying flags RS for modifying segments The Register/flag/segment commands places the user in the appropriate Register/flag/segment window. Here the user can type in a new value for the specified register. The registers and segments are classified as follows: AX, BX, CX, DX are the normal data registers. SP is the Stack Pointer. BP is the Base Pointer. IP is the Instruction Pointer. SI is the Source Index. DI is the Destination Index. CS is the Code Segment. DS is the Data Segment. SS is the Stack Segment. ES is the Extra Segment. The flags are classified as shown in the table on the next page. FLAG DESCRIPTION SET CLEAR The Overflow flag OV NV The Direction flag DN UP The Interrupt flag EI DI The Sign flag NG PL The Zero flag ZR NZ The Auxiliary carry flag AC NA The Parity flag PE PO The Carry flag CY NC In order to change a flag to either Set or Reset, specify the value S or R to which ever level you wish for each individual flag. S - Search Command 11-17 The Search command will search a range of memory for one or more hexadecimal values or ASCII characters. The format of the Search command is: S start-address end-address string The Search command searches through memory for both hexadecimal values and character strings or any combination of both. Character strings must be included in double quotes. If you do not enter a segment part of the start-address, DEBUG assumes the Data Segment (DS). Examples: If you want to search through the area CS:100 to 500 for the three hexadecimal numbers 3A 06 7E, you should type: S CS:100 500 3A067E If you want to search for the ASCII characters XYZ in the memory range DS:100 to DS:FFFF, you should type: S 100 FFFF "XYZ" T - Trace Command The Trace command executes a program one instruction at a time. The format of the Trace command is: T The Trace command starts program execution from the address contained in CS:IP. It will break every time a 8086 instruction is executed and return to the DEBUG screen afterwards. While the instruction is being executed, the screen will swap to the user's screen. U - Unassemble Command The Unassemble command disassembles the information in memory into corresponding mnemonics. The format of the Unassemble command is: U [start-address] When you issue the Unassembly command, the unassembled code is shown in the Assembly/Unassembly window in the upper-left corner of your screen. 11-18 Issuing the Unassembly command repeatedly will continue to display new windows of unassembled code. If you do not specify a start-address for the unassembling, DEBUG will assume the current CS:IP. Example: If you want to Unassemble code starting from the default address CS:IP, you only need to type: U If you want to unassemble code starting from address CS:200, you should type: U 200 W - Write Command The Write command writes a file to a disk. The format of the Write command is: W filename [address length] The Write command will write the content of the memory to a file by the name given in the command line. This file will be overwritten. The user must specify the size and the address of the file to be written. Note that .EXE files cannot be written. 11-19