doc: notes on x86 gdt and segmentation

2 files changed, 87 insertions, 35 deletions

diff --git a/boot/startup-x86_64.s b/boot/startup-x86_64.s
index 4855bf0..4f115e9 100644
--- a/boot/startup-x86_64.s
+++ b/boot/startup-x86_64.s
@@ -28,14 +28,11 @@ MAX_MEM: equ 512
 startup:
 	cld
 	cli
-	lgdt   [gdt_80]  ; set new segment descriptors
-
-	; global data segment
+	; setup GDT by loading GDT descriptor
+	; see docs/x86_gdt.txt
+	lgdt   [gdt_80]
+	; use the 3rd gdt entry for protected mode segmentations
 	mov    eax, 3 * 0x8
-	; 0x8 is the length of each entry these registers point to 4th entry the GDT
-	; (see also the code there) in x86 long mode these are dummy pointers which
-	; are not actually used in addressing. (don't use segmentation at all) all
-	; the addresses are physical addresses from 0.
 	mov    ds, ax
 	mov    es, ax
 	mov    fs, ax
@@ -89,20 +86,13 @@ activate_long_mode:
 	or	   eax, 1 << 31
 	mov    cr0, eax
 
+	; use the 2nd gdt entry (see definition below)
 	; jump to 64-bit code segment -> full activation of Long Mode
 	jmp    2 * 0x8 : longmode_start
 
-;
-;	system start, part 2 (in 64-bit Long Mode)
-;	1. clear BSS
-;	2. enable floating poitn unit
-;	3. set up idt
-;	4. (optional) enable SSE
-;	5. jump to rust main code
-;
-longmode_start:
 [BITS 64]
-	; clear BSS
+	;	system start, part 2 (in 64-bit Long Mode)
+longmode_start:
 	mov    rdi, ___BSS_START__
 clear_bss:
 	mov    byte [rdi], 0
@@ -128,30 +118,38 @@ init_sse:
 
 [SECTION .data]
 
-;
-; Segment descriptors
-;
-
 gdt:
-	dw	0,0,0,0   ; NULL descriptor
+	; see docs/x86_gdt.txt
+
+	; GDT[0] should always be NULL descriptor
+	dw	0,0,0,0
 
 	; 32-bit code segment descriptor
-	dw	0xFFFF	  ; 4Gb - (0x100000*0x1000 = 4Gb)
-	dw	0x0000	  ; base address=0
-	dw	0x9A00	  ; code read/exec
-	dw	0x00CF	  ; granularity=4096, 386 (+5th nibble of limit)
+	; limit=0xFFFF, base=0
+	; Types: P|Ring0|Code/Data|Exec|NonConforming|Readable|NotAccessed
+	; Flags: 4K|32-bit|Not Long Mode
+	dw	0xFFFF
+	dw	0x0000
+	dw	0x9A00
+	dw	0x00CF
 
 	; 64-bit code segment descriptor
-	dw	0xFFFF	  ; 4Gb - (0x100000*0x1000 = 4Gb)
-	dw	0x0000	  ; base address=0
-	dw	0x9A00	  ; code read/exec
-	dw	0x00AF	  ; granularity=4096, 386 (+5th nibble of limit), Long-Mode
+	; limit=0xFFFF, base=0
+	; Types: P|Ring0|Code/Data|Exec|NonConforming|Readable|NotAccessed
+	; Flags: 4K|-|LongMode|-
+	dw	0xFFFF
+	dw	0x0000
+	dw	0x9A00
+	dw	0x00AF
 
 	; data segment descriptor
-	dw	0xFFFF	  ; 4Gb - (0x100000*0x1000 = 4Gb)
-	dw	0x0000	  ; base address=0
-	dw	0x9200	  ; data read/write
-	dw	0x00CF	  ; granularity=4096, 386 (+5th nibble of limit)
+	; limit=0xFFFF, base=0
+	; Types:  Present|Ring0|Code/Data|NoExec|GrowUp|Writable|NotAccessed
+	; Flags:  4K|32-bit|Not Long Mode
+	dw	0xFFFF
+	dw	0x0000
+	dw	0x9200
+	dw	0x00CF
 
 gdt_80:
 	dw	4*8 - 1   ; GDT limit=24, 4 GDT entries - 1
@@ -160,7 +158,7 @@ gdt_80:
 
 [SECTION .bss]
 
-global init_stack:data (init_stack.end - init_stack)
+	global init_stack:data (init_stack.end - init_stack)
 init_stack:
 	resb STACKSIZE
 .end:
diff --git a/docs/x86_gdt.txt b/docs/x86_gdt.txt
new file mode 100644
index 0000000..556881d
--- /dev/null
+++ b/docs/x86_gdt.txt
@@ -0,0 +1,54 @@
+
+GDT, segmentation and long mode:
+
+in real mode (16 bit), the address is generated with SegBaseReg:Offset
+PhyAddr = (SegBaseReg << 4) + Offset SegBase:Offset could be CS:IP for
+instructions or DS for data etc. DS:SI for data.
+
+in protected/long mode, the segment base registers are not directly used
+to generate address. Instead they index into GDT. The pointed GDT entry
+describes the logical "Segment", including the "base" and "limit". PhyAddr
+= GDT[SegBaseReg].base + Offset
+
+Segmentation is obsolete and we will assume a "flat memory model", as most
+compilers do. That is, all the segments cover the full address space. The
+"Base" part of the segmentation is ignored and offset represents the full
+logical address. Nevertheless we can't really disable segmentation, so
+some we still have to manually set up some segmentations in the GDT.
+
+
+
+GDT Entry (Segment Descriptor) Format
+-------------------------------------
+word 0  limit [0:15]
+word 1  base  [0:15]
+word 2  base  [16:23]
+        AccessByte [0:7]
+word 3  limit [16:19]
+        flags [0:3]
+        base  [24:31]
+-------------------------------------
+
+limit: 20-bit value. unit either 1 byte or 4K page
+base : 32-bit value.
+
+to use a flat memory model (as we do here), set limit to 0xFFFF, base to
+0, and use 4k granularity in the access byte.
+
+AccessByte:
+0 - A   Accessed bit
+1 - RW  Readable bit for code seg, or Writable for data seg.
+        Write access is never allowed for code. Read access is always
+        allowed for data
+2 - DC  For data, Direction bit, 1 for grow down
+        For code, Conforming bit
+3 - E   Executable
+4 - S   Descriptor type. 0 for system segment and 1 for code/data segment
+[6:5]   DPL Descriptor Privilege Level. ring 0~3
+7 - P   Present Bit. Must be 1 for valie entries
+
+flags:
+0       Res 0
+1 - L   Long-mode code, 1 for 64-bit code. When L set, DB MBZ
+2 - DB  Size Flag for protected mode seg. 0 for 16 bit and 1 for 32 bit
+3 - G   Granularity of Limit. 0 for 1 byte and 1 for 4KiB