Subversion Repositories Kolibri OS

Introduction.

Introduzione.

mtdbg is a debugger for Kolibri operating system. This documentation describes

mtdbg è un debugger per il sistema operativo KolibriOS. Questo documento

debugger features and work with it. Feel free to ask on our board (mostly

scrivere sul forum (in russo, ma esiste anche una sezione inglese)

in Russian, but has an English forum) -- board.kolibrios.org.

 -- board.kolibrios.org.

General description.

Descrizione generica.

In each moment of time mtdbg can debug only one program. I will call it

mtdbg è in grado di fare il debug di un solo programma alla volta, se non

actions is disabled.

viene caricato nessun programma, il debug viene disabilitato.

mtdbg is controlled by command line, entering from keyboard. Command line

Il programma è a linea di comando, e accetta in input comandi da tastiera

is drawn in the bottom part of debugger window. Debugger handles standard

La linea di comando è posizionata in basso, e accetta in input tasti

input keys Backspace,Delete,Home,End,left/right arrows.

Backspace,Delete,Home,End,frecce sinistra/destra.

Commands are case-insensitive. Delimiter is arbitrary nonzero number of spaces.

non nullo di spazi.

At any moment mtdbg can be terminated by command "quit" (without arguments).

Per chiudere il debugger è sufficiente usare il comando "quit" senza

You can also simply press to close button in the right upper corner of window.

chiusura come per le altre applicazioni.

When debugger is started without command string parameters, no program is

Quando il debugger viene avviato senza argomenti, non viene caricato

loaded. Also mtdbg can be started with command string, in this case it tries

nessun programma. Se invece viene avviato con degli argomenti, mtdbg

to load program with the name pointed to in first parameter in command string

cercherà di caricare il programma indicato come primo argomento e con

and parameters pointed to following (if present).

eventuali parametri per il programma passati come argomenti successivi.

If no program is loaded, you can load a program with the command

momento con il comando

load  []

load  []

  LoaD  /hd0/1/menuetos/dosbox/dosbox

negli esempi, mtdbg caricherà il programma passato come primo argomenti,

All that stays after first space after executable file name, is exactly passed

un eventuale secondo argomento è il parametro da passare al programma

to program as command string.

che si vuole caricare.

The command "load" reports result in the messages window (a little higher

Il comando "load" restituisce in output nel "messages window", poco più

than command line window). If program was loaded successfully, there will

in alto della linea di comando, se il programma è stato caricato con

be the appropriate message; otherwise the message will contain error reason.

successo o meno. In caso di errore, verra mostrata la causa.

Most probable error is "file not found" if wrong file name is given.

caricare.

The debugger can load files with information on symbols in the program

programma  di cui si vuole effetuare il debug.

0x 

0x 

(lines, which do not have such format, are ignored). Such file can be created

(righe che non iniziano in questo modo vengono ignorate). Tali file si

by hand or generated automatically by fasm. Evident load can be done by command

esplicitamente con il comando

load-symbols 

load-symbols 

Furthermore, when the debugger executes the command "load", it checks for

Inoltre, quando viene eseguito il comando "load", mtdbg controllerà

presence of file with name as of loading binary and extension '.dbg'

estensione .dbg (nel primo esempio controlla la presenza  del file

(/rd/1/example.dbg in the first of examples above), and if such file exists,

/rd/1/example.dbg). Se tale file esiste, questo viene caricato

the debugger loads it automatically (with the message "Symbols loaded", if

messaggio "Symbols loaded", se il caricamento viene eseguito con

all is OK).

successo.

It can happen so that loaded program is packed. General principle of

compresso. La compressione funziona, in linea generale, nel

program packing is following: at first input file is packed (by some

seguente modo: il file di input viene compresso (da qualche

pack algorithm), then is appended small code which gets control at program

programma apposito), successivamente viene aggiunto un pezzo di codice

start, unpacks input code in the memory and then passes control to it.

che all'avvio del programma effettua una decompressione in memoria.

If program is packed, it "real" code is not visible and for debugging it is

Se un programma è stato compresso, il suo codice non è visibile al

needed previously to pass through unpacker code.

debugger, e deve venir prima decompresso.

mtdbg determines most of existing packers (mxp,mxp_lzo,mxp_nrv,mtappack)

(mxp,mxp_lzo,mxp_nrv,mtappack) e in questi casi suggerisce in automatico

and in this case suggests to automatically go to "real" code. It is recommended

di effettuare la decompressione per vedere il codice del programma.

to accept (press 'y' or ), but you can refuse too. At refusal and if

rifiutarla. Se non viene riconosciuto il metodo di compressione, è

program is packed by something unknown the command "unpack" (without arguments)

sempre possibile usare il comando unpack (senza argomenti).

can be used. Call it only in the case when you are sure that program is packed

Tale comando è da usare solamente se si è sicuro che il programma sia

and control has not already went to main code! [Starting from Kolibri 0.6.5.0,

compresso e che non sia già stato decompresso dal debugger.

this paragraph is no more actual, because one can pack applications as all

[A partire da Kolibri 0.6.5.0, questo paragrafo non è più attuale poiché

binary files with kpack and the unpacker code in this case is located in the

è possibile comprimere le applicazioni con kpack e il decompressore è

kernel and is transparent for debug.]

implementato a livello kernel, in modo da rendere il debug trasparente]

Loaded program can be terminated by the command "terminate" (without

Un programma caricato può essere terminato tramite il comando

arguments). The command "detach" (without arguments) detaches from program,

aggiuntivi "stacca" il programma dal debugger, nel senso che questo

after that program continues execution normally, as if there was no debugger.

non vi fosse mai stato.

After both this commands program stops to be debugged.

Dato uno di questi due comandi, l'attività di debug viene terminata.

It is possible to anew load program for debugging by the command "reload"

È possibile ricaricare il programma precedente con il comando "reload",

(without arguments). If there is already loaded program, it is terminated

senza parametri. Se nel frattempo è stato caricato un altro programma,

and new instance is started (from the beginning) (with the same command

questo viene terminato e viene ricaricato il programma precedente con

terminate

terminate

load  

load  

load  ,

Il vantaggio di reload sta nel fatto di essere più immediato e che viene

moreover, "load" thinks that new program is loaded and moves data window

mantenuto l'indirizzo di memoria, mentre con il comando load questo

(see below) to zero address, and "reload" keeps current address.

viene spostato all'indirizzo 0. (vedi sotto)

The command "help", which can be shorten to "h", is always available.

Il comando "help", oppure "h", è sempre disponibile.

All commands are divided on groups.

Tutti i comandi sono divisi in gruppi

"help" without arguments displays the list of command groups.

"help" senza argomenti mostra l'elenco dei comandi disponibili

comments.

"help" con il nome di un gruppo mostra i comandi relativi al gruppo

"help" with command name displays information about given command.

       comando

h LoaD

h LoaD

The debugger window consists from the following items enumerated from up

La finestra del debugger è composta dai seguenti elementi enumerati

to down:

dall'alto al basso:

- status string. If there is loaded program, shows its name and state

                 stato ("Running/Paused"), altrimenti "No program

  ("Running/Paused"), otherwise reports "No program loaded".

- registers window - Mostra valori di caratteri generico, valori di

- registers window - shows values of general-purpose registers, register eip

                     registro e stato delle singole flag:

  and states of single flags: CF,PF,AF,ZF,SF,DF,OF: if flag is cleared, then

                     allora è contrassegnata da lettere minuscole, se

  is displayed lower-case letter, if flag is set, then upper-case one.

                     registro che vengono modificati sono contrassegnati

  Registers which are changed from previous moment are highlighted in green.

- data window (dump window) - mostra la porzione di memoria contenente

- data window (dump window) - shows memory contains of loaded program

                              il programma caricato

- messages window

- messages window

- command line window

- command line window

Dump window can display data starting from any address, to this serves

Nella "Dump window" è possibile osservare i dati a partire da ogni

the command

indirizzo, usare il comando

d 

d 

The command "d" without arguments flicks dump window down.

Il comando "d", senza parametri mostra la "dump window".

The same is for code window and the command

In modo analogo funziona il seguente comando per la "code window"

u 

u 

or simply "u".

oppure "u".

Examples:

Esempi:

d esi - displays data at address esi (e.g. is useful before execution of

d esi - mostra i dati all'indirizzo esi (e.g. utile prima di eseguire

  instruction rep movsb)

        una istruzione rep movsb)

d esp - displays stack

d esp - mostra lo stack

u eip - disassembles instruction starting from the current

u eip - disassembla le istruzioni a partire dall'attuale indirizzo

Expressions in mtdbg can include

Le espressioni in mtdbg possono includere

- hexadecimal constants

- costanti esadecimali

- names of all general-purpose registers (8 32-bits, 8 16-bits and

- nomi generici dei registri degli indirizzi (8 32-bits, 8 16-bits e

  8 8-bits) and register eip; values of 16- and 8-bits registers are padded

  8 8-bits) e registri eip; valori di 16- e 8-bits sono riempiti nel

  with zeroes to 32 bits

  registro di 0 fino a raggiungere i 32 bit.

- four arithmetic operations +,-,*,/ (with standard priorities) and

  parentesi

  brackets

- [se sono stati caricati i simboli del programma] nomi, caricati dal

al+AH*bl

al+AH*bl

ax + 2* bH*(eip+a73)

ax + 2* bH*(eip+a73)

3*esi*di/EAX

3*esi*di/EAX

The command

Il comando

? 

? 

calculates value of specified expression.

calcola il valore della espressione passata come argomento.

Values of registers in loaded program can be changed by the command "r", which

I valori del registro caricato nel programma può essere modificato con

(in both cases you can place spaces as you want). Register can be any of

il comando "r" in uno dei seguenti modi (sono equivalenti)

above-mentioned - 24 general-purpose registers and eip.

r  

r =

Let us assume that the command "load" was successfully load program for

debugging.

Supponendo che sia stato caricato un programma con successo per il

Immediately after loading program is suspended and does not execute.

debug, subito dopo il programma verrà sospeso e non più eseguito.

Press Ctrl+F7 (command-line analog is the command "s") to make one step

Premendo Ctrl+F7 (oppure dalla linea di comando "s") è possibile far

in loaded program, after that control returns to debugger which displays

immediatamente, e il debugger mostrerà i nuovi valori nel registro e in

new contains of registers and memory. The system call "int 40h" is considered

memoria.

as one step.

Premendo Ctrl+F8 (oppure dalla linea di comando "p") permette di

Pressing Ctrl+F8 (command-line analog is the command "p") also makes step in

eseguire il programma, e chiamate a procedure esterne, cicli e altre

loaded program, but procedure calls, string operations with prefix

strutture di controllo oppure operazioni con prefisso rep/repz/repnz

rep/repz/repnz and 'loop' cycles are executed as one step.

verranno interpretate come una singola azione.

The one-step commands are used usually on single program sections,

Solitamente si chiede di eseguire azioni singole su sezioni di

when it is needed, for example, to regularly trace registers value and/or

programmi, ad esempio per tenere traccia dei valori in memoria e nel

some variables in memory.

registro.

The command

g 

g 

riprende l'esecuzione del programma e attende che il controllo vada a

resumes program execution and waits until control goes to eip=given address,

eip=indirizzo dato, e in quel momento sospende il programma.

and in this moment suspends program. The command "g" without arguments

Se il comando "g" viene dato senza argomenti, viene semplicemente

simply resumes execution.

Per sospendere l'esecuzione del programma è sufficiente usare il comando

To suspend program use the command "stop" (without arguments).

"stop", senza parametri o argomenti.

In the typical situation it is required that program is executed normally,

quando sono soddisfatte alcune condizioni, il programma viene sospeso e

but when some conditions are satisfied, program suspends and debugger receives

invia un segnale al debugger. Tali condizioni sono chiamate

control. The corresponding conditions are called breakpoints or simply breaks.

L'utilizzo principale dei breakpoints è quello di interrompere

Primary type of breakpoints is to concrete address, i.e. stop execution at

l'esecuzione del programma in determinati punti. I breakpoint si

eip=. Such breakpoints are set by the command

impostano con il comando

bp 

bp 

Note that if there is only one such breakpoint, there is more convenient to use

Si noti che se è presente un solo breakpoint, allora è più conveniente

the command "g" with argument instead.

usare il comando "g" con parametri.

Other type of breakpoints is on access to given memory area. Maximum

Vi sono altri tipi di breakpoint che permettono di accedera ad una data

numbers of such breakpoints is 4 (because hardware features of x86 processors

causa limitazioni hardware.

are used and they allows only 4).

                    indirizzo dato

bpm  - breaks at any access to byte at given address

                      indirizzo dato

bpm w  - breaks at write to byte at given address

                               dword all'indirizzo dato. bpm e bpmb sono

bpmb,bpmw,bpmd  - breaks to access correspondingly to byte, word

                               gli indirizzi devono essere del tipo

or dword at given address. bpm ¨ bpmb are synonyms. When bpmw,bpmd are used,

                               corrispondenti al tipo di dato, quindi

address must be aligned according to correspondingly word bound (i.e. be even)

                               per i word è dispari, per i dword è

or dword bound (i.e. be divisible by 4).

                               divisibile per 4.

bpmb,bpmw,bpmd w  - similar to break on write.

bpmb,bpmw,bpmd w  - simile al break in scrittura.

Per vedere la lista dei breakpoints impostati, usare il comando "bl",

To see the list of set breakpoints use the command "bl", to obtain information

per ottenere informazioni su un particolare breakpoint, usare il

on concrete breakpoint use "bl ". Unnecessary breakpoints can be

comando "bl ".

deleted with the command "bc ", temporarily unnecessary can be

È possibile rimuovere i breakpoint con il comando "bc ", oppure

disabled by the command "bd ", when they will be needed again,

disabilitati momentaneamente con il comando "bd " e riabilitati

con "be "

Remarks.

Note.

1. When debugging your own programs you can put in code instructions

1. Quando si effettua il debug di un proprio programma, è possibile

   int3 (pay attention to absence of space!). Such instruction causes

   mettere nel codice istruzione int3. Queste istruzioni creano delle

   exception at normal run, which leads to process termination, but

   eccezioni durante la normale esecuzione, che porta alla terminazione

   at work under debugger it is simply activated (with the message

   del programma, ma durante l'attività di debug permette di non dover

   "int3 command at xxx"). This feature allows to not think about addresses

   pensare agli indirizzi di memoria da usare nei comandi g e bp.

   to use in the commands g and/or bp.

2. La notazione standard per l'output e input è quella esadecimale.

2. All output and all input is oriented on hexadecimal scale of notation.

3. Quando il programma viene eseguito, la finestra del registro e dei

3. When program is executed, registers and data window shows information

   dati mostrano delle informazioni prima dell'avvio. Non si possono