2 * librm: a library for interfacing to real-mode code
4 * Michael Brown <mbrown@fensystems.co.uk>
8 FILE_LICENCE ( GPL2_OR_LATER )
10 /* Drag in local definitions */
13 /* For switches to/from protected mode */
16 /* Size of various C data structures */
17 #define SIZEOF_I386_SEG_REGS 12
18 #define SIZEOF_I386_REGS 32
19 #define SIZEOF_REAL_MODE_REGS ( SIZEOF_I386_SEG_REGS + SIZEOF_I386_REGS )
20 #define SIZEOF_I386_FLAGS 4
21 #define SIZEOF_I386_ALL_REGS ( SIZEOF_REAL_MODE_REGS + SIZEOF_I386_FLAGS )
25 /****************************************************************************
26 * Global descriptor table
28 * Call init_librm to set up the GDT before attempting to use any
29 * protected-mode code.
31 * Define FLATTEN_REAL_MODE if you want to use so-called "flat real
32 * mode" with 4GB limits instead.
34 * NOTE: This must be located before prot_to_real, otherwise gas
35 * throws a "can't handle non absolute segment in `ljmp'" error due to
36 * not knowing the value of REAL_CS when the ljmp is encountered.
38 * Note also that putting ".word gdt_end - gdt - 1" directly into
39 * gdt_limit, rather than going via gdt_length, will also produce the
40 * "non absolute segment" error. This is most probably a bug in gas.
41 ****************************************************************************
44 #ifdef FLATTEN_REAL_MODE
45 #define RM_LIMIT_16_19__AVL__SIZE__GRANULARITY 0x8f
47 #define RM_LIMIT_16_19__AVL__SIZE__GRANULARITY 0x00
49 .section ".data16", "aw", @progbits
52 gdtr: /* The first GDT entry is unused, the GDTR can fit here. */
53 gdt_limit: .word gdt_length - 1
57 .org gdt + VIRTUAL_CS, 0
58 virtual_cs: /* 32 bit protected mode code segment, virtual addresses */
60 .byte 0, 0x9f, 0xcf, 0
62 .org gdt + VIRTUAL_DS, 0
63 virtual_ds: /* 32 bit protected mode data segment, virtual addresses */
65 .byte 0, 0x93, 0xcf, 0
67 .org gdt + PHYSICAL_CS, 0
68 physical_cs: /* 32 bit protected mode code segment, physical addresses */
70 .byte 0, 0x9f, 0xcf, 0
72 .org gdt + PHYSICAL_DS, 0
73 physical_ds: /* 32 bit protected mode data segment, physical addresses */
75 .byte 0, 0x93, 0xcf, 0
78 real_cs: /* 16 bit real mode code segment */
80 .byte 0, 0x9b, RM_LIMIT_16_19__AVL__SIZE__GRANULARITY, 0
83 real_ds: /* 16 bit real mode data segment */
85 .byte 0, 0x93, RM_LIMIT_16_19__AVL__SIZE__GRANULARITY, 0
88 .equ gdt_length, gdt_end - gdt
90 /****************************************************************************
91 * init_librm (real-mode far call, 16-bit real-mode far return address)
93 * Initialise the GDT ready for transitions to protected mode.
96 * %cs : .text16 segment
97 * %ds : .data16 segment
98 * %edi : Physical base of protected-mode code (virt_offset)
99 ****************************************************************************
101 .section ".text16", "ax", @progbits
105 /* Preserve registers */
109 /* Store _virt_offset and set up virtual_cs and virtual_ds segments */
111 movw $virtual_cs, %bx
113 movw $virtual_ds, %bx
115 movl %edi, _virt_offset
117 /* Negate virt_offset */
120 /* Store rm_cs and _text16, set up real_cs segment */
127 addr32 leal (%eax, %edi), %ebx
130 /* Store rm_ds and _data16, set up real_ds segment */
137 addr32 leal (%eax, %edi), %ebx
140 /* Set GDT and IDT base */
145 /* Restore registers */
151 .section ".text16", "ax", @progbits
160 idt_init: /* Reuse the return opcode here */
163 /****************************************************************************
164 * real_to_prot (real-mode near call, 32-bit virtual return address)
166 * Switch from 16-bit real-mode to 32-bit protected mode with virtual
167 * addresses. The real-mode %ss:sp is stored in rm_ss and rm_sp, and
168 * the protected-mode %esp is restored from the saved pm_esp.
169 * Interrupts are disabled. All other registers may be destroyed.
171 * The return address for this function should be a 32-bit virtual
175 * %ecx : number of bytes to move from RM stack to PM stack
177 ****************************************************************************
179 .section ".text16", "ax", @progbits
182 /* Make sure we have our data segment available */
186 /* Add _virt_offset, _text16 and _data16 to stack to be
187 * copied, and also copy the return address.
192 addw $16, %cx /* %ecx must be less than 64kB anyway */
194 /* Real-mode %ss:%sp => %ebp:%edx and virtual address => %esi */
200 addr32 leal (%eax,%edx), %esi
201 subl _virt_offset, %esi
203 /* Switch to protected mode */
210 data32 ljmp $VIRTUAL_CS, $1f
211 .section ".text", "ax", @progbits
214 /* Set up protected-mode data segments and stack pointer */
215 movw $VIRTUAL_DS, %ax
223 /* Record real-mode %ss:sp (after removal of data) */
228 /* Move data from RM stack to PM stack */
233 /* Publish virt_offset, text16 and data16 for PM code to use */
238 /* Return to virtual address */
241 /* Default IDTR with no interrupts */
242 .section ".data16", "aw", @progbits
246 .word 0xffff /* limit */
249 /****************************************************************************
250 * prot_to_real (protected-mode near call, 32-bit real-mode return address)
252 * Switch from 32-bit protected mode with virtual addresses to 16-bit
253 * real mode. The protected-mode %esp is stored in pm_esp and the
254 * real-mode %ss:sp is restored from the saved rm_ss and rm_sp. The
255 * high word of the real-mode %esp is set to zero. All real-mode data
256 * segment registers are loaded from the saved rm_ds. Interrupts are
257 * *not* enabled, since we want to be able to use prot_to_real in an
258 * ISR. All other registers may be destroyed.
260 * The return address for this function should be a 32-bit (sic)
261 * real-mode offset within .code16.
264 * %ecx : number of bytes to move from PM stack to RM stack
266 ****************************************************************************
268 .section ".text", "ax", @progbits
271 /* Add return address to data to be moved to RM stack */
274 /* Real-mode %ss:sp => %ebp:edx and virtual address => %edi */
280 leal (%eax,%edx), %edi
281 subl virt_offset, %edi
283 /* Move data from PM stack to RM stack */
287 /* Record protected-mode %esp (after removal of data) */
290 /* Load real-mode segment limits */
298 .section ".text16", "ax", @progbits
301 /* Switch to real mode */
305 ljmp *p2r_jump_vector
308 /* Set up real-mode data segments and stack pointer */
317 /* Reset IDTR to the real-mode defaults */
320 /* Return to real-mode address */
324 /* Real-mode code and data segments. Assigned by the call to
325 * init_librm. rm_cs doubles as the segment part of the jump
326 * vector used by prot_to_real. rm_ds is located in .text16
327 * rather than .data16 because code needs to be able to locate
330 .section ".data16", "aw", @progbits
332 .word p2r_jump_target
336 .section ".text16.data", "aw", @progbits
339 /****************************************************************************
340 * prot_call (real-mode far call, 16-bit real-mode far return address)
342 * Call a specific C function in the protected-mode code. The
343 * prototype of the C function must be
344 * void function ( struct i386_all_regs *ix86 );
345 * ix86 will point to a struct containing the real-mode registers
346 * at entry to prot_call.
348 * All registers will be preserved across prot_call(), unless the C
349 * function explicitly overwrites values in ix86. Interrupt status
350 * and GDT will also be preserved. Gate A20 will be enabled.
352 * Note that prot_call() does not rely on the real-mode stack
353 * remaining intact in order to return, since everything relevant is
354 * copied to the protected-mode stack for the duration of the call.
355 * In particular, this means that a real-mode prefix can make a call
356 * to main() which will return correctly even if the prefix's stack
357 * gets vapourised during the Etherboot run. (The prefix cannot rely
358 * on anything else on the stack being preserved, so should move any
359 * critical data to registers before calling main()).
362 * function : virtual address of protected-mode function to call
365 * pushl $pxe_api_call
368 * to call in to the C function
369 * void pxe_api_call ( struct i386_all_regs *ix86 );
370 ****************************************************************************
373 #define PC_OFFSET_GDT ( 0 )
374 #define PC_OFFSET_IDT ( PC_OFFSET_GDT + 8 /* pad to 8 to keep alignment */ )
375 #define PC_OFFSET_IX86 ( PC_OFFSET_IDT + 8 /* pad to 8 to keep alignment */ )
376 #define PC_OFFSET_RETADDR ( PC_OFFSET_IX86 + SIZEOF_I386_ALL_REGS )
377 #define PC_OFFSET_FUNCTION ( PC_OFFSET_RETADDR + 4 )
378 #define PC_OFFSET_END ( PC_OFFSET_FUNCTION + 4 )
380 .section ".text16", "ax", @progbits
384 /* Preserve registers, flags and GDT on external RM stack */
398 /* For sanity's sake, clear the direction flag as soon as possible */
401 /* Switch to protected mode and move register dump to PM stack */
402 movl $PC_OFFSET_END, %ecx
405 .section ".text", "ax", @progbits
408 /* Set up environment expected by C code */
412 leal PC_OFFSET_IX86(%esp), %eax
414 call *(PC_OFFSET_FUNCTION+4)(%esp)
415 popl %eax /* discard */
417 /* Switch to real mode and move register dump back to RM stack */
418 movl $PC_OFFSET_END, %ecx
421 .section ".text16", "ax", @progbits
424 /* Reload GDT and IDT, restore registers and flags and return */
428 addw $20, %sp /* also skip %cs and %ss */
434 /* popal skips %esp. We therefore want to do "movl -20(%sp),
435 * %esp", but -20(%sp) is not a valid 80386 expression.
436 * Fortunately, prot_to_real() zeroes the high word of %esp, so
437 * we can just use -20(%esp) instead.
439 addr32 movl -20(%esp), %esp
443 /****************************************************************************
444 * real_call (protected-mode near call, 32-bit virtual return address)
446 * Call a real-mode function from protected-mode code.
448 * The non-segment register values will be passed directly to the
449 * real-mode code. The segment registers will be set as per
450 * prot_to_real. The non-segment register values set by the real-mode
451 * function will be passed back to the protected-mode caller. A
452 * result of this is that this routine cannot be called directly from
453 * C code, since it clobbers registers that the C ABI expects the
454 * callee to preserve. Gate A20 will *not* be automatically
455 * re-enabled. Since we always run from an even megabyte of memory,
456 * we are guaranteed to return successfully to the protected-mode
457 * code, which should then call gateA20_set() if it suspects that gate
458 * A20 may have been disabled. Note that enabling gate A20 is a
459 * potentially slow operation that may also cause keyboard input to be
460 * lost; this is why it is not done automatically.
462 * librm.h defines a convenient macro REAL_CODE() for using real_call.
463 * See librm.h and realmode.h for details and examples.
466 * (32-bit) near pointer to real-mode function to call
469 ****************************************************************************
472 #define RC_OFFSET_PRESERVE_REGS ( 0 )
473 #define RC_OFFSET_RETADDR ( RC_OFFSET_PRESERVE_REGS + SIZEOF_I386_REGS )
474 #define RC_OFFSET_FUNCTION ( RC_OFFSET_RETADDR + 4 )
475 #define RC_OFFSET_END ( RC_OFFSET_FUNCTION + 4 )
477 .section ".text", "ax", @progbits
481 /* Create register dump and function pointer copy on PM stack */
483 pushl RC_OFFSET_FUNCTION(%esp)
485 /* Switch to real mode and move register dump to RM stack */
486 movl $( RC_OFFSET_RETADDR + 4 /* function pointer copy */ ), %ecx
489 .section ".text16", "ax", @progbits
492 /* Call real-mode function */
498 /* For sanity's sake, clear the direction flag as soon as possible */
501 /* Switch to protected mode and move register dump back to PM stack */
502 movl $RC_OFFSET_RETADDR, %ecx
505 .section ".text", "ax", @progbits
508 /* Restore registers and return */
513 /* Function vector, used because "call xx(%sp)" is not a valid
516 .section ".data16", "aw", @progbits
517 rc_function: .word 0, 0
519 /****************************************************************************
520 * Stored real-mode and protected-mode stack pointers
522 * The real-mode stack pointer is stored here whenever real_to_prot
523 * is called and restored whenever prot_to_real is called. The
524 * converse happens for the protected-mode stack pointer.
526 * Despite initial appearances this scheme is, in fact re-entrant,
527 * because program flow dictates that we always return via the point
528 * we left by. For example:
532 * Print a text string
542 * At point 1, the RM mode stack value, say RPXE, is stored in
543 * rm_ss,sp. We want this value to still be present in rm_ss,sp when
546 * At point 2, the RM stack value is restored from RPXE. At point 3,
547 * the RM stack value is again stored in rm_ss,sp. This *does*
548 * overwrite the RPXE that we have stored there, but it's the same
549 * value, since the code between points 2 and 3 has managed to return
551 ****************************************************************************
553 .section ".data", "aw", @progbits
558 pm_esp: .long _estack
560 /****************************************************************************
561 * Virtual address offsets
563 * These are used by the protected-mode code to map between virtual
564 * and physical addresses, and to access variables in the .text16 or
566 ****************************************************************************
568 /* Internal copies, created by init_librm (which runs in real mode) */
569 .section ".data16", "aw", @progbits
570 _virt_offset: .long 0
574 /* Externally-visible copies, created by real_to_prot */
575 .section ".data", "aw", @progbits