Difference between revisions of "Writing applications for KolibriOS"
Jump to navigation
Jump to search
| (10 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
= Structure of an application = | = 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. | + | 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. |
| − | + | ||
| − | The KolibriOS API (Application Programming Interface) is | + | 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> |
| − | + | The KolibriOS API (Application Programming Interface) is an easy-to-learn set of functions with practically no hierarchical accesses. | |
| − | The operating of an application is based on events. | + | |
| − | + | 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> | |
| − | 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. | + | 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: | ||
| − | + | ||
| − | + | <syntaxhighlight> | |
| − | + | ;;;;;;;;;;;;;;;;;;;;;;;;; | |
| − | + | ; ; | |
| − | + | ; 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 | |
| − | + | ||
| − | + | ;;;;;;;;;;;;;;;;;;;;;;;; | |
| − | + | ; ; | |
| − | + | ; STATIC DATA ; | |
| − | + | ; ; | |
| − | + | ;;;;;;;;;;;;;;;;;;;;;;;; | |
| − | + | </syntaxhighlight> | |
| − | |||
| − | |||
| − | |||
= The header = | = 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 | + | 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. | Speaks for itself. | ||
| − | < | + | |
| − | + | <syntaxhighlight> | |
| − | </ | + | dd START ; start of execution |
| − | START is the label in your program where kernel will jump to after loading the program. | + | </syntaxhighlight> |
| − | You could use another name, but it's convenient to always use the same. | + | |
| − | < | + | 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> |
| − | This is the total size of the program code in bytes, its easy to use a label | + | 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. |
| − | 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 | + | <syntaxhighlight> |
| − | There, | + | dd 0x100000 |
| − | The xx bytes then are the number of bytes you want to use for the stack. | + | </syntaxhighlight> |
| − | Also note, this value can later be changed by using system functions | + | |
| − | < | + | 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> |
| − | Where the end of stack is (the value of esp at start of program). | + | dd 0x100000 ; stack position in memory area |
| − | Logically, this would be the same as the previous value. | + | </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. | |
| − | </ | + | |
| − | If you want to use parameters, this should be a pointer to a 1024 byte buffer, in | + | <syntaxhighlight> |
| − | If you | + | 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. | Path value, works the same as parameter. | ||
= System calls = | = System calls = | ||
| − | The System calls (API) are explained in various sources. There is the file syscalls.txt | + | 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. |
| − | 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. | + | 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. |
| − | 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 | + | |
| − | < | + | Now, we need to execute the function, this can be done with int 0x40: |
| − | + | ||
| − | </ | + | <syntaxhighlight> |
| − | But also with more modern instructions such as syscall, sysenter etc. | + | int 0x40 |
| − | It's convenient to use the mcall macro from macros.inc, then you can | + | </syntaxhighlight> |
| − | This macro also accepts parameters, first is eax, second is ebx, ...<br> | + | |
| − | Code for the above would be: | + | 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 = | = Coding Style = | ||
| − | It's | + | 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 = | = 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 == | == Simple example == | ||
| − | + | ||
| − | < | + | <syntaxhighlight> |
| − | |||
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; | ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; | ||
; ; | ; ; | ||
| Line 135: | 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 | ||
| − | |||
| − | |||
| − | + | db 'MENUET01' | |
| + | dd 0x01 | ||
| + | dd START | ||
| + | dd I_END | ||
| + | dd 0x100000 | ||
| + | dd 0x7fff0 | ||
| + | dd 0, 0 | ||
| − | + | ; The code area | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | 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 |
| − | + | ||
| − | |||
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 178: | 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 | ||
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 | |||