From c5510b619ff5855c1fa8ece138991ce378100e96 Mon Sep 17 00:00:00 2001 From: Frater <13979047+saintfrater@users.noreply.github.com> Date: Sat, 7 Feb 2026 14:39:15 +0100 Subject: [PATCH] api doc update --- doc/API.md | 32 +-------- doc/MEMORY_MAP.md | 111 +++++++++++++++++++++++++++++ readme.md | 17 ++++- src/gui/lib.asm | 173 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 301 insertions(+), 32 deletions(-) create mode 100644 doc/MEMORY_MAP.md diff --git a/doc/API.md b/doc/API.md index 884e4d8..392200c 100644 --- a/doc/API.md +++ b/doc/API.md @@ -4,34 +4,6 @@ Le système utilise plusieurs macro *GFX*,*GUI*, etc pour appeler les fonctions Les arguments sont passés sur la pile (Convention C : dernier argument empilé en premier, nettoyage par l'appelant géré par la macro). - * [CGA](/doc/CGA.md) controleur graphique - - -## BDA (Bios Data Area) Custom - -Le projet utilise une extension de la BDA standard IBM PC. - - Segment BDA Standard : 0x0040 (comme nous appelons le bios VGA, il faut garder cet espace "libre") - - Segment Données Custom : 0x0050 (Défini par BDA_DATA_SEG). - -## Structure des données (BDA 0x0050) - -Les structures sont définies dans bda.asm. - - OFFSET 0x0000 (Mouse) : État de la souris, coordonnées (x,y), buffer d'arrière-plan. - - OFFSET 0x0034 (Gfx) : Position courante du curseur texte, modes d'affichage. - -## Mapping Mémoire Global : - - 0000:0000 : IVT (Interrupt Vector Table) - - 0040:0000 : BDA Standard - - 0050:0000 : Variables Drivers (Souris, Gfx) - - 0800:0000 : Stack (0x8000 - 0x18000 approx) ou Code (selon boot.asm). - - B800:0000 : VRAM CGA. + * [CGA](/doc/CGA.md) : controleur graphique CGA + * [MEMORY MAP](/doc/MEMORY_MAP.md) : Plan de la mémoire \ No newline at end of file diff --git a/doc/MEMORY_MAP.md b/doc/MEMORY_MAP.md new file mode 100644 index 0000000..0d0f942 --- /dev/null +++ b/doc/MEMORY_MAP.md @@ -0,0 +1,111 @@ +# Memory Map / Cartographie Mémoire + +## 🇬🇧 English + +### Physical Memory Layout (Real Mode) + +The processor starts in Real Mode, addressing 1 MB of memory. + +| Physical Start | Physical End | Size | Description | Segment | Source File | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **`0x00000`** | **`0x003FF`** | 1 KB | **IVT** (Interrupt Vector Table) | `0x0000` | `boot.asm` / `generic.asm` | +| **`0x00400`** | **`0x004FF`** | 256 B | **BDA** (BIOS Data Area) Standard | `0x0040` | `common/bda.asm` | +| **`0x00500`** | **`0x005FF`** | ~256 B | **Custom BDA** (Driver Data) | `0x0050` | `common/bda.asm` | +| ... | ... | ... | *Free / Reserved* | | | +| **`0x08000`** | **`0x09FFF`** | 8 KB | **Stack Bottom** | `0x0800` | `boot.asm` | +| **`0x0A000`** | **`0x0AFFF`** | ~4 KB | **GUI RAM** (Widget Allocation) | `0x0A00` | `gui/lib.asm` | +| **`0x0B000`** | **`0x17FFE`** | ~52 KB | **Stack Top** (Grows downwards) | `0x0800` | `boot.asm` | +| ... | ... | ... | *Conventional RAM Free* | | | +| **`0xB8000`** | **`0xBFFFF`** | 32 KB | **VRAM** (CGA / MCGA) | `0xB800` | `drivers/gfx_cgam.asm` | +| **`0xC0000`** | **`0xDFFFF`** | 128 KB | **Option ROMs** (e.g., VGA BIOS) | `0xC000` | `boot.asm` | +| ... | ... | ... | *System Reserved* | | | +| **`0xF0000`** | **`0xFFFFF`** | 64 KB | **System BIOS ROM** (Code) | `0xF000` | `boot.asm` | + +### Detailed Zones + +#### Interrupt Vector Table (IVT) +* **Location**: `0000:0000` +* **Usage**: Interrupt pointer table (256 entries of 4 bytes). +* **Initialization**: + * `ivt_setup` fills the table with a default handler (`default_isr`). + * `ivt_setvector` installs specific IRQs (e.g., Timer on `INT 08h`). + +#### BIOS Data Area (BDA) +The project separates the standard IBM BDA from its own variables to avoid conflicts with the VGA BIOS loaded at `0xC000`. + +* **Standard BDA (`0040:0000`)**: Used mainly by the VGA BIOS (loaded via QEMU) to store video modes (`0x0049`) and column count (`0x004A`). +* **Custom BDA (`0050:0000`)**: Defined by `BDA_DATA_SEG`. Stores driver states: + * **Mouse**: Input buffer, status, coordinates, background buffer (for cursor). + * **Gfx**: Text cursor position, attributes. + +#### Stack & GUI RAM +* **Stack**: Segment `0x0800`, SP `0xFFFE`. Grows downwards from physical address `0x17FFE`. +* **GUI RAM**: Segment `0x0A00` (Physical `0x0A000`). +* **Layout**: The GUI RAM sits at the "bottom" of the stack segment's physical range, but since the stack starts at the top (`0x17FFE`) and grows down, there is approximately **56 KB** of safe space before collision. + +#### Video RAM (CGA High-Res) +* **Segment**: `0xB800` +* **Mode**: 640x200 Monochrome (1 bit per pixel). +* **Organization**: Interleaved. + * **Even Lines (0, 2, 4...)**: Offset `0x0000` - `0x1F3F` (Bank 0). + * **Odd Lines (1, 3, 5...)**: Offset `0x2000` - `0x3F3F` (Bank 1). + +#### ROM +* **Option ROMs (`0xC0000`)**: Scanned by `setup_load_rom` to initialize the VGA BIOS. +* **System ROM (`0xF0000`)**: Contains the compiled binary code. The Reset Vector is at `0xFFFF0`. + +--- + +## 🇫🇷 Français + +### Cartographie Mémoire Physique (Mode Réel) + +Le processeur démarre en mode réel, adressant 1 Mo de mémoire. + +| Adresse Physique (Début) | Adresse Physique (Fin) | Taille | Description | Segment | Fichier Source | +| :--- | :--- | :--- | :--- | :--- | :--- | +| **`0x00000`** | **`0x003FF`** | 1 Ko | **IVT** (Interrupt Vector Table) | `0x0000` | `boot.asm` / `generic.asm` | +| **`0x00400`** | **`0x004FF`** | 256 o | **BDA** (BIOS Data Area) Standard | `0x0040` | `common/bda.asm` | +| **`0x00500`** | **`0x005FF`** | ~256 o | **Custom BDA** (Données Drivers) | `0x0050` | `common/bda.asm` | +| ... | ... | ... | *Mémoire Libre / Réservée* | | | +| **`0x08000`** | **`0x09FFF`** | 8 Ko | **Bas de la Pile** (Stack Bottom) | `0x0800` | `boot.asm` | +| **`0x0A000`** | **`0x0AFFF`** | ~4 Ko | **GUI RAM** (Allocation Widgets) | `0x0A00` | `gui/lib.asm` | +| **`0x0B000`** | **`0x17FFE`** | ~52 Ko | **Haut de la Pile** (Stack Top) | `0x0800` | `boot.asm` | +| ... | ... | ... | *RAM Conventionnelle Libre* | | | +| **`0xB8000`** | **`0xBFFFF`** | 32 Ko | **VRAM** (CGA / MCGA) | `0xB800` | `drivers/gfx_cgam.asm` | +| **`0xC0000`** | **`0xDFFFF`** | 128 Ko | **Option ROMs** (ex: VGA BIOS) | `0xC000` | `boot.asm` | +| ... | ... | ... | *Réservé Système* | | | +| **`0xF0000`** | **`0xFFFFF`** | 64 Ko | **System BIOS ROM** (Code) | `0xF000` | `boot.asm` | + +### Détails des Zones + +#### Interrupt Vector Table (IVT) +* **Emplacement** : `0000:0000` +* **Usage** : Table des pointeurs d'interruption (256 entrées de 4 octets). +* **Initialisation** : + * `ivt_setup` remplit la table avec un handler par défaut (`default_isr`). + * `ivt_setvector` installe les IRQ spécifiques (ex: Timer sur `INT 08h`). + +#### BIOS Data Area (BDA) +Le projet sépare la BDA standard IBM de ses propres variables pour éviter les conflits avec le BIOS VGA chargé en `0xC000`. + +* **BDA Standard (`0040:0000`)** : Utilisée principalement par le BIOS VGA (chargé via QEMU) pour stocker les modes vidéo (`0x0049`) et le nombre de colonnes (`0x004A`). +* **Custom BDA (`0050:0000`)** : Définie par `BDA_DATA_SEG`. Stocke l'état des drivers : + * **Souris** : Buffer d'entrée, état, coordonnées, buffer de sauvegarde du fond (pour le curseur). + * **Gfx** : Position du curseur texte, attributs. + +#### Stack & GUI RAM +* **Stack** : Segment `0x0800`, SP `0xFFFE`. Grandit vers le bas depuis l'adresse physique `0x17FFE`. +* **GUI RAM** : Segment `0x0A00` (Physique `0x0A000`). +* **Organisation** : La RAM GUI se trouve "en bas" de la plage physique du segment de pile, mais comme la pile commence tout en haut (`0x17FFE`) et descend, il y a environ **56 Ko** d'espace libre avant collision. + +#### Video RAM (CGA High-Res) +* **Segment** : `0xB800` +* **Mode** : 640x200 Monochrome (1 bit par pixel). +* **Organisation** : Entrelacée (Interleaved). + * **Lignes Paires (0, 2, 4...)** : Offset `0x0000` à `0x1F3F` (Bank 0). + * **Lignes Impaires (1, 3, 5...)** : Offset `0x2000` à `0x3F3F` (Bank 1). + +#### ROM +* **Option ROMs (`0xC0000`)** : Espace scanné par `setup_load_rom` pour initialiser le BIOS VGA. +* **System ROM (`0xF0000`)** : Contient le code binaire compilé. Le Vecteur de Reset est situé à `0xFFFF0`. \ No newline at end of file diff --git a/readme.md b/readme.md index 4cb5e9a..1389797 100644 --- a/readme.md +++ b/readme.md @@ -74,6 +74,12 @@ To build and run this project, the following tools and components are required: --- +### API + +Get a look at the [API](/doc/API.md) for more information. + +--- + ### Build and Run #### Compilation @@ -205,6 +211,15 @@ Utilisé comme émulateur PC principal pour tester et déboguer le BIOS personna - **BIOS VGA de QEMU** Le BIOS VGA standard de QEMU (vgabios.bin) est utilisé pour initialiser le matériel vidéo, ce qui permet au projet de se concentrer sur le développement du BIOS sans réimplémenter la logique VGA complète. +---- + +### API + +Consultez la documentation de l'[API](/doc/API.md) pour plus d'informations. + +--- + + ### Compilation et exécution #### Compilation @@ -271,6 +286,4 @@ Ce projet est avant tout un **laboratoire d’apprentissage et d’exploration** 🚧 **Work in progress** Designed for experimentation, learning, and documentation. -parcourez l'[API](/doc/API.md) pour plus d'informations - --- diff --git a/src/gui/lib.asm b/src/gui/lib.asm index 12f583c..6457868 100644 --- a/src/gui/lib.asm +++ b/src/gui/lib.asm @@ -78,6 +78,179 @@ struc widget alignb 2 ; Alignement mémoire pour performance endstruc +; ============================================================================= +; SECTION : API ACTIONS +; ============================================================================= + +%macro GUI 1-* + %rep %0 - 1 + %rotate -1 + push %1 + %endrep + %rotate -1 + call word [cs:gui_api_table + ((%1)*2)] + add sp, (%0 - 1) * 2 +%endmacro + +%define GUI_CREATE 0 +%define GUI_DESTROY 1 +%define GUI_GET_STATE 2 +%define GUI_GET_TYPE 3 +%define GUI_GET_VAL 4 + +gui_api_table: + dw gui_api_create + dw gui_api_destroy + dw gui_api_get_state + dw gui_api_get_type + dw gui_api_get_val + +; ----------------------------------------------------------------------------- +; gui_api_create +; Crée un widget et retourne son ID +; Out: AX = ID ou -1 si erreur +; ----------------------------------------------------------------------------- +gui_api_create: + call gui_alloc_widget ; Returns GS:SI + jc .error + + ; ID = SI / widget_size + mov ax, si + xor dx, dx + mov cx, widget_size + div cx + ret + +.error: + mov ax, -1 + ret + +; ----------------------------------------------------------------------------- +; gui_api_get_state +; Arg1: ID +; Out: AX = State +; ----------------------------------------------------------------------------- +%define .id word [bp+4] +gui_api_get_state: + push bp + mov bp, sp + + mov ax, .id ; ID + call gui_get_widget_ptr + jc .err + + xor ax, ax + mov al, [gs:si + widget.state] + jmp .done + +.err: + mov ax, -1 +.done: + leave + ret +%undef .id + +; ----------------------------------------------------------------------------- +; gui_api_get_type +; Arg1: ID +; Out: AX = Type +; ----------------------------------------------------------------------------- +%define .id word [bp+4] +gui_api_get_type: + push bp + mov bp, sp + + mov ax, .id ; ID + call gui_get_widget_ptr + jc .err + + xor ax, ax + mov al, [gs:si + widget.type] + jmp .done + +.err: + mov ax, -1 +.done: + leave + ret +%undef .id + +; ----------------------------------------------------------------------------- +; gui_api_get_val +; Arg1: ID +; Out: AX = Attr Val +; ----------------------------------------------------------------------------- +%define .id word [bp+4] +gui_api_get_val: + push bp + mov bp, sp + + + mov ax, .id ; ID + call gui_get_widget_ptr + jc .err + + mov ax, [gs:si + widget.attr_val] + jmp .done + +.err: + mov ax, -1 +.done: + leave + ret +%undef .id + +; ----------------------------------------------------------------------------- +; gui_api_destroy +; Détruit un widget via son ID +; Arg1: ID +; Out: AX = 0 (OK), -1 (Error) +; ----------------------------------------------------------------------------- +%define .id word [bp+4] +gui_api_destroy: + push bp + mov bp, sp + + mov ax, .id ; ID + call gui_get_widget_ptr + jc .err + + call gui_free_widget + xor ax, ax + jmp .done + +.err: + mov ax, -1 +.done: + leave + ret +%undef .id + +; ----------------------------------------------------------------------------- +; gui_get_widget_ptr +; Helper interne : Convertit ID en Pointeur +; In: AX = ID +; Out: GS:SI = Ptr, CF=1 if error +; ----------------------------------------------------------------------------- +gui_get_widget_ptr: + cmp ax, GUI_MAX_WIDGETS + jae .error + + push dx + mov cx, widget_size + mul cx ; AX = Offset + mov si, ax + pop dx + + mov ax, GUI_RAM_SEG + mov gs, ax + + clc + ret +.error: + stc + ret + ; ============================================================================= ; SECTION : GESTION MÉMOIRE (ALLOCATION / LIBÉRATION) ; =============================================================================