Help system not yet completed.

Test it!
____для русских
Ещё не доделанная справочная система.
Протестируйте!

git-svn-id: svn://kolibrios.org@8061 a494cfbc-eb01-0410-851d-a64ba20cac60
This commit is contained in:
Alex2003 2020-09-11 16:11:33 +00:00
parent dd9ab58a5e
commit a1ac239480
11 changed files with 396 additions and 0 deletions

View File

@ -0,0 +1,33 @@
<html>
<head>
<title>Main</title>
<text><b>KolibriOS Help</b></text>
</head>
<body>
<h2>Help system for KolibriOS ver. 1.0 (for OS version 0.7.7.0 and newer)</h2>
<h3>Common topics</h3>
<ul>
<li><a href="\help\comm_topics\faq_problems.html">Solution of problems and FAQs</a></li>
<li><a href="\help\comm_topics\hard_support.html">Hardware support</a></li>
</ul>
<h3>Software development</h3>
<ul>
<li><a href="\help\soft_dev\sys_funct_main.html">List of system functions</a></li>
<li><a href="\help\soft_dev\debug.html">Debugging Applications Guide</a></li>
<li><a href="\help\soft_dev\fasm_manual.html">FASM manual</a></li>
</ul>
<h3>Using libraries</h3>
<ul>
<li><a href="\help\us_lib\ini.html">INI library</a></li>
<li><a href="\help\us_lib\open_dialog.html">OpenDialog library</a></li>
</ul>
<h3>Useful links</h3>
<ul>
<li><a href="kolibrios.org">KolibriOS official site</a></li>
<li><a href="wiki.kolibrios.org">Wiki of KolibriOS</a></li>
<li><a href="board.kolibrios.org">Forum of KolibriOS</a></li>
<li><a href="kolibri-n.org">Site of Kolibri N</a></li>
<li><a href="store.kolibri-n.org">KolibriOS Store</a></li>
</ul>
</body>
</html>

View File

@ -0,0 +1,123 @@
<html>
<head>
<title>Debugging Applications Guide</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\help_main.html">[To main]</a></text>
<text><a href="\help\soft_dev\fasm_manual.html"> [To the next point] </a></text>
<text><a href="\help\comm_topics\sys_funct_main.html"> [To the previous point] </a></text>
</head>
<body>
<h2>Debugging Applications Guide</h2>
<text><b>Introduction</b></br></br>
mtdbg is a debugger for the KolibriOS. This documentation describes the capabilities of the debugger and how to work with it. For questions, please visit our forum (board.kolibrios.org).</br></br>
<b>General description</b></br></br>
Mtdbg can only debug one program at a time. Let's call such a program loaded for debugging. If no program is loaded, the vast majority of debugging actions are not available.</br></br>
mtdbg is controlled by the command line entered from the keyboard. The command line is displayed at the bottom of the debugger window. The standard input keys Backspace, Delete, Home, End, left / right arrows are processed.</br>
Commands are not case sensitive. An arbitrary non-zero number of spaces is used as a separator.</br></br>
The debugger can be terminated at any time with the "quit" command (no arguments). However, you can just click on the close button in the upper left corner of the window.</br></br>
Running the debugger without command line parameters results in no program being loaded. Also, mtdbg can be run with the command line, in this case it will try to load the program with the name specified as the first command line argument and parameters specified as subsequent (if any).</br></br>
If no program is loaded, you can load the program with the command load &lt;full name of the executable file&gt; [&lt;arguments&gt;].</br>
For example:</br>
load / rd / 1 / example</br>
LOAD / rd / 1 / aclock w200 h200</br>
LoaD / hd0 / 1 / menuetos / dosbox / dosbox</br></br>
Everything after the first space after the name of the executable file is literally passed to the program as a command line.</br>
The load command reports the result in a message window (just above the command line window). If the program was loaded, then this will appear the corresponding message; if not successful, the message will indicate the reason for the error. The most likely one is "file not found" if the filename is incorrect.</br></br>
The debugger can load files with information about the names in the program (labels, global variables) - text files, each line of which has the form 0x &lt;hex_address_value&gt; &lt;name&gt; (lines that do not have this form are ignored). Such a file can be created manually or generated automatically when compiling the source by fasm.</br>
Explicit loading is performed with the command load-symbols &lt;full name of the symbol file&gt;.</br>
In addition, when executing the load command, the debugger checks for the existence of a file with the same name as the loaded binary and the extension .dbg (/rd/1/example.dbg for the first example above), and if there is one, loads it automatically (displaying the message "Symbols loaded" if everything is ok).</br></br>
It may happen that the downloaded program is packed. The general principle of packaging programs is the following: first, the source file is packed (by some compression algorithm), then a small code is assigned, which receives control when the program starts, unpacks the source code in memory, and then transfers control to it. If the program is packed, then its "real" code is not visible and for debugging you must first go through the unpacker code. mtdbg detects most of the existing packers (mxp, mxp_lzo, mxp_nrv, mtappack) and in this case offers to automatically go to the "real" code. It is recommended to agree (press 'y' or Enter), but you can refuse.</br>
In case of failure and in the case when the program is packed with something unknown, you can use the "unpack" command (no arguments). Call it only when you are sure that the program is packed and that control has not yet reached the main code! (Starting from Kolibri 0.6.5.0, this entire paragraph is no longer relevant, since applications can be packaged like any binaries with kpack and the unpacker code is in the kernel and unpacking is transparent for debugging.)</br></br>
The loaded program can be nailed with the "terminate" command (no arguments). The detach command (with no arguments) is detached from the program, after which the program continues to execute normally, as if the debugger was not present. After both of these commands, the program ceases to be debuggable.</br></br>
You can reload the program for debugging with the "reload" command (no arguments). If there is already a loaded program, then it is nailed and starts (from the very beginning) a new instance (with the same command line), in this case the command is similar to the commands terminate</br>
load &lt;last program name&gt; &lt;last program arguments&gt;</br>
Otherwise, the program that was debugged last (in the current session with mtdbg) (with the same command line) is loaded again, i.e. almost the same as load &lt;last program name&gt; &lt;last program arguments&gt;, but the reload command is shorter and more convenient in both cases; moreover, load considers that a new program is loaded, and transfers the data window (see below) to address zero, and reload saves the current address.</br></br>
The "help" command is always available, which can be abbreviated to "h".</br>
All teams are divided into groups:</br>
help with no arguments displays a list of command groups.</br>
help specifying a group displays a list of commands for that group with short comments.</br>
help with a command specifies information about the specified command.</br>
For example:</br>
help</br>
help control</br>
h LoaD</br></br>
The debugger window consists of the following items, listed from top to bottom:</br>
- status bar. If there is a loaded program, it shows its name and state ("Running" / "Paused"), if not, it says "No program loaded".</br>
- register window - shows the values of general-purpose registers, eip register and flags register. The latter is written in two ways: the full hex value and the states of individual flags: CF, PF, AF, ZF, SF, DF, OF. If the flag is cleared, then a small letter is displayed; if set, capitalized.</br></br>
Registers that have changed since the previous moment are highlighted in green.</br>
- data window (dump window) - shows the contents of the loaded program memory</br>
- code window (disassembler window) - shows the program code in the form of disassembled instructions</br>
- message box</br>
- command line window</br></br>
In the dump window, you can view data starting from any address, for this there is the d &lt;expression&gt; command.</br>
Command d without arguments scrolls down the dump window. The same applies to the code window and the u &lt;expression&gt; command or just u.</br>
For example:</br>
d esi - shows the data located at esi (for example, useful before executing the rep movsb instruction)</br>
d esp - shows the stack</br>
u eip - disassembles instructions starting with the current one</br></br>
Expressions in mtdbg can include</br>
- hexadecimal constants</br>
- the names of all general purpose registers (8 32-bit, 8 16-bit and 8 8-bit) and eip register; 16- and 8-bit register values are zero-expanded to 32 bits</br>
- four arithmetic operations +, -, *, / (with standard precedence) and brackets</br>
- [if there is information about symbols] names loaded from dbg file</br>
All calculations are done modulo 2 ^ 32.</br>
Examples of expressions:</br>
eax</br>
eip + 2</br>
ecx-esi-1F</br>
al + AH * bl</br>
ax + 2 * bH * (eip + a73)</br>
3 * esi * di / EAX</br>
Command ? &lt;expression&gt; evaluates the value of the specified expression.</br></br>
The values of the registers of the loaded program can be changed with the r command, which has two absolutely equivalent forms:</br>
r &lt;case&gt; &lt;expression&gt;</br>
r &lt;case&gt; = &lt;expression&gt;</br>
(in both cases, you can add spaces to your liking). As a register, you can specify any of the above - 24 general registers and eip.</br></br>
Let's say the load command has successfully loaded a program for debugging. Immediately after loading, the program is suspended and does not run.</br>
Pressing Ctrl + F7 (similar to the command line - the "s" command) takes one step in the loaded program, after which control returns to the debugger, which shows the new contents of registers and memory. The int 40h system call (as well as the sysenter and syscall instructions) counts as one step.</br>
Pressing Ctrl + F8 (similar to the command line - the "p" command) also takes a step in the loaded program, but procedure calls, line operations with the rep / repz / repnz prefix, and loops are performed as one step.</br>
Stepping instructions are used, as a rule, in separate sections of the program, when it is necessary, for example, to regularly monitor the values of registers and / or some variables in memory.</br>
The g &lt;expression&gt; command resumes the execution of the program and waits until control reaches eip = the corresponding address, and at this moment suspends the program. The "g" command with no arguments simply resumes program execution.</br></br>
You can pause the program execution with the "stop" command (without arguments).</br></br>
Usually it is required for the program to run normally, but when certain conditions are met, the program is suspended and the debugger takes control. The corresponding conditions are called breakpoints, breakpoint (s), in common parlance - breakpoints. The simplest type of breakpoints is to a specific address, i.e. abort execution on eip = &lt;specified value&gt;. These breakpoints are set with the bp &lt;expression&gt; command.</br></br>
Comment. If there is only one such breakpoint, it is more convenient to use the "g" command with an argument instead.</br></br>
Another type of breakpoints is by accessing a given area of memory. There can be no more than four such breakpoints (since the hardware capabilities of x86 processors are used, where only 4 such breakpoints are allowed).</br>
bpm &lt;expression&gt; - bryak to any access to the byte at the specified address</br>
bpm w &lt;expression&gt; - bryak to write a byte at the specified address</br>
bpmb, bpmw, bpmd &lt;expression&gt; - bryak to access, respectively, byte, word and doubleword at the specified address. bpm and bpmb are synonyms. When using bpmw, the bpmd address must be word-aligned (i.e. even) or double-word aligned (i.e., divisible by 4), respectively.</br>
bpmb, bpmw, bpmd w &lt;expression&gt; - similarly for write break.</br></br>
The list of set breakpoints can be viewed with the "bl" command, information about a specific breakpoint can be obtained with "bl &lt;number&gt;". Unnecessary breakpoints are removed with the "bc &lt;number&gt;" command, temporarily unnecessary ones can be disabled with the "bd &lt;number&gt;" command, when they are needed again, use the "be &lt;number&gt;" command.</br></br>
Remarks.</br></br>
When debugging your own programs, you can insert int3 instructions into the code (note that there is no space!). Such an instruction throws an exception on normal startup, which will lead to the termination of the process, but when working under the debugger, the debugger is simply activated (with the message "int3 command at xxx"). This allows you not to think about which addresses to use in the g and / or bp commands. You can also generate a file with information about symbols and load it, then not only there is no need to independently calculate the addresses for "g" and "bp", but also "u", "d", "?" will understand the indication of the label / variable name.</br>
All output and all input is hexadecimal. </br>
When the program is running, the register and data windows show information pertaining to the point before the resume; setting of register values in this mode is not possible. However, the "d" command in this mode shows the information that was correct at the time the command was issued.</br>
Written by diamond. Translated by Alex2003
</text>
</body>
</html>

View File

@ -0,0 +1,23 @@
<html>
<head>
<title>List of system functions</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\help_main.html">[To main]</a></text>
<text><a href="\help\soft_dev\debug.html"> [To the next point] </a></text>
<text><a href="\help\comm_topics\hard_support.html"> [To the previous point] </a></text>
</head>
<body>
<h2>System Function (for OS version 0.7.7.0 and newer)</h2>
<text>Number of the function is located in the register eax.</br>
The call of the system function is executed by "int 0x40" command.</br>
All registers except explicitly declared in the returned value, including eflags, are preserved.</text>
<ul>
<li><text><a href="\help\sys_funct\f69_main.html">Function 69 - Debugging</a></text></li>
<li><text><a href="\help\sys_funct\f70_main.html">Function 70 - Work with file system with long names support</a></text></li>
<li><text>lost</text></li>
<li><text>lost</text></li>
<li><text>lost</text></li>
<li><text>lost</text></li>
</ul>
</body>
</html>

View File

@ -0,0 +1,41 @@
<html>
<head>
<title>Sys. function 70</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\soft_dev\sys_funct_main.html">[Back to list system function]</a></text>
<text><a href="\help\sys_funct\f69_main.html"> [Previous page]</a></text>
<text> [Next page]</text>
</br>
<head>
<body>
<h2>System function 68 - debugging.</h2>
<text>A process can load other process as debugged by set of corresponding bit by call to subfunction 7 of function 70.</br>
A process can have only one debugger; one process can debug some others. The system notifies debugger on events occuring with debugged process.</br> Messages are written to the buffer defined by subfunction 0.</br></text>
<text>Format of a message:</br>
+0: dword: message code;</br>
+4: dword: PID of debugged process;</br>
+8: there can be additional data depending on message code.</br></br></text>
<text>Message codes:</br>
1 = exception in addition dword-number of the exception is given process is suspended;</br>
2 = process has terminated comes at any termination: both through the system function -1, and at "murder" by any other process (including debugger itself);</br>
3 = debug exception int 1 = #DB in addition dword-image of the register DR6 is given: bits 0-3: condition of the corresponding breakpoint (set by subfunction 9) is satisfied bit 14: exception has occured because of the trace mode (flag TF is set TF) process is suspended.</br></br></text>
<text>When debugger terminates, all debugged processes are killed. If debugger does not want this, it must previously detach by
subfunction 3.</br></br></text>
<text>All subfunctions are applicable only to processes/threads started from the current by function 70 with set debugging flag. Debugging of multithreaded programs is not supported yet.</br></br></text>
<text>The full list of subfunctions:</br>
subfunction 0 - define data area for debug messages</br>
subfunction 1 - get contents of registers of debugged thread</br>
subfunction 2 - set contents of registers of debugged thread</br>
subfunction 3 - detach from debugged process</br>
subfunction 4 - suspend debugged thread</br>
subfunction 5 - resume debugged thread</br>
subfunction 6 - read from the memory of debugged process</br>
subfunction 7 - write to the memory of debugged process</br>
subfunction 8 - terminate debugged thread</br>
subfunction 9 - set/clear hardware breakpoint</br></text>
</body>
</html>

View File

@ -0,0 +1,56 @@
<html>
<head>
<title>Sys. function 69</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\soft_dev\sys_funct_main.html">[Back to list system function]</a></text>
<text><a href="\help\sys_funct\f68_main.html"> [Previous page]</text>
<text><a href="\help\sys_funct\f70_main.html"> [Next page]</a></text>
</br>
<head>
<body>
<h2>System function 69 - debugging.</h2>
<text>A process can load other process as debugged by set of corresponding bit by call to subfunction 7 of function 70.</br>
A process can have only one debugger; one process can debug some others. The system notifies debugger on events occuring with debugged process.</br> Messages are written to the buffer defined by subfunction 0.</br></text>
<text>Format of a message:</br>
+0: dword: message code;</br>
+4: dword: PID of debugged process;</br>
+8: there can be additional data depending on message code.</br></br>
</text>
<text>Message codes:</br>
1 = exception in addition dword-number of the exception is given process is suspended;</br>
2 = process has terminated comes at any termination: both through the system function -1, and at "murder" by any other process (including debugger itself);</br>
3 = debug exception int 1 = #DB in addition dword-image of the register DR6 is given: bits 0-3: condition of the corresponding breakpoint (set by subfunction 9) is satisfied bit 14: exception has occured because of the trace mode (flag TF is set TF) process is suspended.</br></br>
</text>
<text>When debugger terminates, all debugged processes are killed. If debugger does not want this, it must previously detach by
subfunction 3.</br></br>
</text>
<text>All subfunctions are applicable only to processes/threads started from the current by function 70 with set debugging flag. Debugging of multithreaded programs is not supported yet.</br></br>
</text>
<text>The full list of subfunctions:</br>
subfunction 0 - define data area for debug messages</br>
subfunction 1 - get contents of registers of debugged thread</br>
subfunction 2 - set contents of registers of debugged thread</br>
subfunction 3 - detach from debugged process</br>
subfunction 4 - suspend debugged thread</br>
subfunction 5 - resume debugged thread</br>
subfunction 6 - read from the memory of debugged process</br>
subfunction 7 - write to the memory of debugged process</br>
subfunction 8 - terminate debugged thread</br>
subfunction 9 - set/clear hardware breakpoint</br></br>
</text>
<text>Value for register eax - 69 (SF_DEBUG).</br>
Values for register ebx:</br>
0 - SSF_SET_MESSAGE_AREA - subfunction 0 - define data area fror debug messages.</br>
1 - SSF_GET_REGISTERS - subfunction 1 - Get contents of registers of debugged thread.</br>
2 - SSF_SET_REGISTERS - subfunction 2 - Set contents of registers of debugged thread.</br>
3 - SSF_DETACH - subfunction 3 - detach from debugged process.</br>
4 - SSF_SUSPEND - subfunction 4 - suspend debugged thread.</br>
5 - SSF_RESUME - subfunction 5 - resume debugged thread.</br>
6 - SSF_READ_MEMORY - subfunction 6 - read from memory of debugged process.<br>
7 - SSF_WRITE_MEMORY - subfunction 7 - write to memory of debugged process.</br>
8 - SSF_TERMINATE - subfunction 8 - terminate debugged thread.</br>
9 - SSF_DEFINE_BREAKPOINT - subfunction 9 - set/clear hardware breakpoint.
</text>
<text>created 23.08.2020 by Alex2003</text>
</body>
</html>

View File

@ -0,0 +1,81 @@
<html>
<head>
<title>Sys. function 70</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\soft_dev\sys_funct_main.html">[Back to list system function]</a></text>
<text><a href="\help\sys_funct\f69_main.html"> [Previous page]</a></text>
<text> [Next page]</text>
</br>
<head>
<body>
<h2>System function 70 - Work with file system with long names support</h2>
<text>Parameters:</br>
Register eax = 70</br>
Register ebx = pointer to the information structure</br>
Returned value:</br>
Register eax = 0 - success; otherwise file system error code some subfunctions return value in other registers too.</br>
General format of the information structure:</br>
+0: dword: subfunction number</br>
+4: dword: offset in file or folder</br>
+8: dword: higher part of offset or flags</br>
+12 = +0xC: dword: size of data</br>
+16 = +0x10: dword: pointer to data</br>
+20 = +0x14: ?: path - zero terminated string</br>
or</br>
+20 = +0x14: byte: 0</br>
+21 = +0x15: dword: pointer to string</br>
Case sensitivity depends on filesystem.</br>
If a path not begins with '/', it is considered a relative.</br>
To get or set the current folder, use the sysfunction 30.</br>
'../' in the path means a lift by one folder relatively current folder.</br>
To set the encoding, put at the start of the string a byte with next values:</br>
1 = cp866</br>
2 = UTF-16LE</br>
3 = UTF-8</br>
otherwise will be used cp866. In an absolute path you may put this byte after the '/' or put an additional '/' before it.</br>
Also, you may use the sysfunction 80.</br>
Format of an absolute path: /base/number/dir1/dir2/.../dirn/file, where base/number identifies device, on which file is located:</br>
RD/1 = ramdisk</br>
FD/1 = first floppy drive, FD/2 = second floppy drive</br>
HD0/x, HD1/x, HD2/x, HD3/x = hard drives accordingly on IDE0 (Primary Master), IDE1 (Primary Slave), IDE2 (Secondary Master), IDE3 (Secondary Slave); x - partition number on the selected hard drive, starts from 1</br>
CD0/1, CD1/1, CD2/1, CD3/1 = same for cd</br>
SYS = system folder (encoding inaffected key), second key may be set by sysfunction 30.3.</br>
Examples:</br>
'/sys/example.asm',0</br>
'/rd/1/example.asm',0</br>
'/HD0/1/folder/file.txt',0</br>
'/hd2/2/pics/tanzania.bmp',0</br>
2,'/',0,'sys','/',0,'F',0,'I',0,'L',0,'E',0,0,0</br></br>
Available subfunctions:</br>
subfunction 0 - read file</br>
subfunction 1 - read folder</br>
subfunction 2 - create/rewrite file</br>
subfunction 3 - write to existing file</br>
subfunction 4 - set file size</br>
subfunction 5 - get attributes of file/folder</br>
subfunction 6 - set attributes of file/folder</br>
subfunction 7 - start application</br>
subfunction 8 - delete file/folder</br>
subfunction 9 - create folder</br>
For CD-drives due to hardware limitations only subfunctions 0,1,5 and 7 are available, other subfunctions return error with code 2.</br>
At the first call of subfunctions 0,1,5,7 to ATAPI devices(CD and DVD) the manual control of tray is locked due to caching drive data. Unlocking is made when subfunction 4 of function 24 is called for corresponding device.</br>
</br>
Value for register eax - 70 (SF_FILE).</br>
Values for register ebx:</br>
0 - SSF_READ_FILE - subfunction 0 - read file with long names support.</br>
1 - SSF_READ_FOLDER - subfunction 1 - read folder with long names support.</br>
2 - SSF_CREATE_FILE - subfunction 2 - create/rewrite file with long names support.</br>
3 - SSF_WRITE_FILE - subfunction 3 - write to existing file with long names support.</br>
4 - SSF_SET_END - subfunction 4 - set end of file.</br>
5 - SSF_GET_INFO - subfunction 5 - get information on file/folder.</br>
6 - SSF_SET_INFO - subfunction 6 - set attributes of file/folder.</br>
7 - SSF_START_APP - subfunction 7 - start application.</br>
8 - SSF_DELETE - subfunction 8 - delete file/folder.</br>
9 - SSF_CREATE_FOLDER - subfunction 9 - create folder.</br>
</text>
</body>
</html>

View File

@ -0,0 +1,39 @@
<html>
<head>
<title>INI library</title>
<text><b>KolibriOS Help</b></text>
<text><a href="\help\help_main.html">[Back to main]</a></text>
<text><a href="\help\us_lib\open_dialog.html"> [To the next point] </a></text>
<text><a href="\help\soft_dev\fasm_manual.html"> [To the previous point] </a></text>
</br>
</head>
<body>
<h2>INI library</h2>
<text>
INI files are text files with the following structure:</br>
[name of the first section]</br>
Parameter1 = value1</br>
Parameter2 = Value2</br>
;comment</br>
[name of the second section]</br>
Parameter3 = Value3</br></br>
All lines starting with the character ';' are considered comments and are ignored.</br></br>
Keyboard shortcut syntax:</br>
arbitrary number of modifiers Ctrl / Alt / Shift / LCtrl / LAlt / LShift / RCtrl / RAlt / RShift, followed by a latin letter, number or key name.</br>
Proper names have the following keys:</br>
F1 - F12</br>
Home End; PgUp; PgDn; Ins, she is Insert; Del, she is Delete;</br>
Tab Plus Esc Enter Backspace Space (space);</br>
Left (left arrow); Right (right arrow); Up (up arrow); Down (down arrow).</br>
You can write a string with any case of characters. Individual parts are written either together or separated by a plus.</br>
For example:</br>
Ctrl + Alt + Backspace</br>
RCtrl + RShift</br>
Shiftift</br>
f10</br>
Shiftalt5</br>
</text>
</body>
</html>