Difference between revisions of "Writing applications for KolibriOS"

From KolibriOS wiki
Jump to navigation Jump to search
 
(18 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
= Writing applications for KolibriOS =
+
= Structure of an application =
−
 
+
 
−
 
+
KolibriOS's application structure is not specifically reserved for asm programming, the header can be produced with practically any other language. However, the overall application programming design is intended for easy 32 bit asm programming. The GUI is extremely easy to handle with especially asm language.
−
== Structure of an application ==
+
 
−
     
+
Programming for KolibriOS is easy as you first learn the basic structure of an application. At this point I assume you have some experience in assembly language.<br>
−
Programming for KolibriOS is easy as you first learn the basic structure of an application. At this point I assume you have some experience in assembly language.
+
The KolibriOS API (Application Programming Interface) is an easy-to-learn set of functions with practically no hierarchical accesses.
−
 
+
 
−
The KolibriOS API (Application Programming Interface) is a easy-to-learn set of functions with practically no hierarchial accesses.
+
The operating of an application is based on events. The application is notified by the OS with the event type and the application acts accordingly.<br>
−
 
+
There are three event types an application is expected to handle by default: window redraw, keypress and buttonpress.
−
The operating of an application is based on events.
+
 
−
 
 
−
The application is notified by the OS with the event type and the application acts accordingly. There are three event types an application is expected to handle by default: window redraw, keypress and buttonpress.
 
−
 
 
 
Flow chart and structure of an application with default events:
 
Flow chart and structure of an application with default events:
−
 
 
−
  ;;;;;;;;;;;;;;;;;;;;;;;;;
 
−
  ;                      ;
 
−
  ;    HEADER DATA      ;
 
−
  ;                      ;
 
−
  ;;;;;;::;;;;;;;;;;;;;;;;;
 
−
 
 
−
START:
 
−
 
 
−
  call draw_window
 
−
 
 
−
  ;;;;;;;;;;;;;;;;::;;;;;;;
 
−
  ;                      ;
 
−
  ;  WAIT UNTIL EVENT    ;  <-----------------------------------------------I
 
−
  ;                      ;                                                  I
 
−
  ;;;;;::;;;;;;;;;;;;;;;;;;                                                  I
 
−
                                                                            I
 
−
  ;;;;;;;::;;;;;;;;;;;;;;;;                                                  I
 
−
  ;                      ;    redraw  ->  call draw_window            -> I
 
−
  ;    READ EVENT TYPE    ; ->  key      ->  read keypress    -> process  -> I
 
−
  ;                      ;    button  ->  read buttonpress -> process  -> I
 
−
  ;;;;;::;;;;;;;;;;;;;;;;;;
 
−
 
 
−
 
 
−
draw_window:
 
−
 
 
−
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
−
  ;                            ;
 
−
  ;  DRAW STATIC WINDOW PARTS  ;
 
−
  ;                            ;
 
−
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
−
 
 
−
  ret
 
−
 
 
−
 
 
−
DATA AREA:
 
−
 
 
−
  ;;;;;;;;;;;;;;;;;;;;;;;;
 
−
  ;                      ;
 
−
  ;    STATIC DATA      ;
 
−
  ;                      ;
 
−
  ;;;;;;;;;;;;;;;;;;;;;;;;
 
  
−
== Assembly example ==
+
<syntaxhighlight>
−
    
+
;;;;;;;;;;;;;;;;;;;;;;;;;
−
    
+
;                      ;
−
A heavily commented assembly language realization of the above structure.
+
;    HEADER DATA      ;
−
    
+
;                      ;
−
KolibriOS system calls can be executed with the 'int 0x40' command, altough it is better to use the mcall macro. The function number should be in eax register and other registers are used if necessary.  
+
;;;;;;::;;;;;;;;;;;;;;;;;
−
Details of all currently available system calls are at the section (1g) System functions.
+
 
−
 
+
START:
−
<asm>
+
        call   draw_window
−
 
+
 
 +
;;;;;;;;;;;;;;;;;;;;;;;;;
 +
;                      ;
 +
;  WAIT UNTIL EVENT   ;  <-----------------------------------------------I
 +
;                      ;                                                  I
 +
;;;;;;;;;;;;;;;;;;;;;;;;;                                                  I
 +
;                                                                          I
 +
;;;;;;;;;;;;;;;;;;;;;;;;;                                                  I
 +
;                      ;    redraw  ->  call draw_window            -> I
 +
;    READ EVENT TYPE    ; ->  key      ->  read keypress   -> process  -> I
 +
;                      ;    button  ->  read buttonpress -> process  -> I
 +
;;;;;;;;;;;;;;;;;;;;;;;;;
 +
 
 +
draw_window:
 +
 
 +
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 +
;                            ;
 +
;  DRAW STATIC WINDOW PARTS  ;
 +
;                            ;
 +
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 +
 
 +
        ret
 +
 
 +
;;;;;;;;;;;;;;;;;;;;;;;;
 +
;                      ;
 +
;    STATIC DATA      ;
 +
;                      ;
 +
;;;;;;;;;;;;;;;;;;;;;;;;
 +
</syntaxhighlight>
 +
 
 +
= The header =
 +
 
 +
<syntaxhighlight>
 +
db 'MENUET01'
 +
</syntaxhighlight>
 +
 
 +
Since KolibriOS still is more or less API compatible with MenuetOS, it has the same header. There is also an older version of the header which uses 'MENUET00', but it should not be used anymore.
 +
 
 +
<syntaxhighlight>
 +
dd 0x01 ; header version
 +
</syntaxhighlight>
 +
 
 +
Speaks for itself.
 +
 
 +
<syntaxhighlight>
 +
dd START ; start of execution
 +
</syntaxhighlight>
 +
 
 +
START is the label in your program where kernel will jump to after loading the program. You could use another name, but it's convenient to always use the same.
 +
 
 +
<syntaxhighlight>
 +
dd I_END ; size of image
 +
</syntaxhighlight>
 +
 
 +
This is the total size of the program code in bytes, its easy to use a label which you place at the end of the code.
 +
 
 +
<syntaxhighlight>
 +
dd 0x100000
 +
</syntaxhighlight>
 +
 
 +
This is the amount of ram that will be reserved for your app. You could use a static value as shown here, or you could use I_END + xx bytes. There, I_END would be the label to the end of code + all static declarations you made after the code. The xx bytes then are the number of bytes you want to use for the stack. Also note, this value can later be changed by using system functions.
 +
 
 +
<syntaxhighlight>
 +
dd 0x100000 ; stack position in memory area
 +
</syntaxhighlight>
 +
 
 +
Where the end of stack is (the value of esp at start of program). Logically, this would be the same as the previous value.
 +
 
 +
<syntaxhighlight>
 +
dd 0x0 ; Parameters
 +
</syntaxhighlight>
 +
 
 +
If you want to use parameters, this should be a pointer to a 1024 byte buffer, in which those parameters will be written by the kernel. If you don't want to use them, set this dword to 0.
 +
 
 +
<syntaxhighlight>
 +
dd 0x0 ; Path
 +
</syntaxhighlight>
 +
 
 +
Path value, works the same as parameter.
 +
 
 +
= System calls =
 +
 
 +
The System calls (API) are explained in various sources. There is the file syscalls.txt which you can find in KolibriOS itself, but also in the zip file of the distribution.< If you understand russian, you can also find system calls on this wiki.
 +
 
 +
To execute a system call, you first need to fill the registers with the correct value. Say we want to wait a couple of milliseconds, we need to use system function 5 and place the time we want to wait in ebx.
 +
 
 +
<syntaxhighlight>
 +
        mov    eax, 5
 +
        mov    ebx, 10
 +
</syntaxhighlight>
 +
 
 +
Now, we need to execute the function, this can be done with int 0x40:
 +
 
 +
<syntaxhighlight>
 +
        int    0x40
 +
</syntaxhighlight>
 +
 
 +
But also with more modern instructions such as syscall, sysenter etc. It's convenient to use the mcall macro from macros.inc, then you can choose to use int 0x40 or another method, at compile time. This macro also accepts parameters, first is eax, second is ebx, ...<br> Code for the above would be:
 +
 
 +
<syntaxhighlight>
 +
        mcall  5, 10
 +
</syntaxhighlight>
 +
 
 +
= Coding Style =
 +
 
 +
It's advisable to use the coding style, as described here: [[Style]]
 +
 
 +
= The API =
 +
You can find the latest API documentation in /kernel/docs/ in the SVN repository ([http://websvn.kolibrios.org/listing.php?repname=Kolibri+OS&path=%2Fkernel%2Ftrunk%2Fdocs%2F WebSVN])<br>
 +
Inside KolibriOS, you can find sysfuncs.txt (english version) or sysfuncr (russian version) in DOCKPACK program.<br>
 +
These files also come with the so called distribution kit, in documents folder.
 +
 
 +
= Assembly examples =
 +
 
 +
Some examples are listed on this page, more can be found on the SVN server in the folder /programs/develop/examples/ ([http://websvn.kolibrios.org/listing.php?repname=Kolibri+OS&path=%2Fprograms%2Fdevelop%2Fexamples%2F WebSVN])
 +
 
 +
== Simple example ==
 +
 
 +
<syntaxhighlight>
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
;                                                  ;
 
;                                                  ;
Line 73: Line 146:
 
;                                                  ;
 
;                                                  ;
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
−
 
+
 
 +
format binary as ""                    ; Binary file format without extenstion
 +
 
 +
use32                                  ; Tell compiler to use 32 bit instructions
 +
 
 +
org 0x0                                ; the base address of code, always 0x0
 +
 
 
; The header
 
; The header
−
 
 
−
use32                          ; Tell compiler to use 32 bit instructions
 
  
−
        org    0x0            ; the base address of code, always 0x0
+
db 'MENUET01'
 +
dd 0x01
 +
dd START
 +
dd I_END
 +
dd 0x100000
 +
dd 0x7fff0
 +
dd 0, 0
  
−
        db      'MENUET01'      ; 8 byte id for application
+
; The code area
−
        dd      0x01            ; header version
 
−
        dd      START          ; start of execution
 
−
        dd      I_END          ; size of image
 
−
        dd      0x100000        ; Amount of memory to use
 
−
                                ; You can access memory from 0x0 to
 
−
                                ; value defined here. The relocation
 
−
                                ; of code is done with selectors
 
−
                                ; set by the OS.
 
−
        dd      0x7fff0        ; stack position in memory area
 
−
        dd      0x0            ; Parameter passing value
 
−
                                ; if set to other than zero, possible
 
−
                                ; parameters are transferred at start.
 
−
        dd      0x0            ; Path passing value, works same as parameter passing
 
−
 
 
  
−
; The code area
+
include 'macros.inc'
  
−
        include 'macros.inc'
 
−
 
 
−
 
 
 
START:                                  ; start of execution
 
START:                                  ; start of execution
−
 
 
 
         call    draw_window            ; draw the window
 
         call    draw_window            ; draw the window
  
−
 
 
 
; After the window is drawn, it's practical to have the main loop.
 
; After the window is drawn, it's practical to have the main loop.
 
; Events are distributed from here.
 
; Events are distributed from here.
−
 
+
 
 
event_wait:
 
event_wait:
−
 
 
−
 
 
 
         mov    eax, 10                ; function 10 : wait until event
 
         mov    eax, 10                ; function 10 : wait until event
−
         mcall
+
         mcall                           ; event type is returned in eax
−
                                        ; event type is returned in eax
+
 
−
 
 
 
         cmp    eax, 1                  ; Event redraw request ?
 
         cmp    eax, 1                  ; Event redraw request ?
 
         je      red                    ; Expl.: there has been activity on screen and
 
         je      red                    ; Expl.: there has been activity on screen and
Line 123: Line 184:
 
         je      key                    ; Expl.: User has pressed a key while the
 
         je      key                    ; Expl.: User has pressed a key while the
 
                                         ; app is at the top of the window stack.
 
                                         ; app is at the top of the window stack.
−
 
+
 
 
         cmp    eax, 3                  ; Event button in buffer ?
 
         cmp    eax, 3                  ; Event button in buffer ?
 
         je      button                  ; Expl.: User has pressed one of the
 
         je      button                  ; Expl.: User has pressed one of the
 
                                         ; applications buttons.
 
                                         ; applications buttons.
−
 
+
 
 
         jmp    event_wait
 
         jmp    event_wait
−
 
+
 
−
 
 
−
 
 
 
;  The next section reads the event and processes data.
 
;  The next section reads the event and processes data.
−
 
 
−
 
 
−
  red:                                  ; Redraw event handler
 
  
 +
red:                                    ; Redraw event handler
 
         call    draw_window            ; We call the window_draw function and
 
         call    draw_window            ; We call the window_draw function and
 
         jmp    event_wait              ; jump back to event_wait
 
         jmp    event_wait              ; jump back to event_wait
−
 
 
−
  key:                                  ; Keypress event handler
 
  
−
         mov    eax,2                   ; The key is returned in ah. The key must be
+
key:                                    ; Keypress event handler
 +
         mov    eax, 2                 ; The key is returned in ah. The key must be
 
         mcall                          ; read and cleared from the system queue.
 
         mcall                          ; read and cleared from the system queue.
 
         jmp    event_wait              ; Just read the key, ignore it and jump to event_wait.
 
         jmp    event_wait              ; Just read the key, ignore it and jump to event_wait.
−