====== How to use gPXE with QEMU ======

===== Step by step =====

  - Install Qemu
  - Compile or download gpxe.pdsk.
  - Type on the command line: <code> qemu -fda gpxe.pdsk -net nic -net user -bootp http://etherboot.org/gtest/gtest.gpxe </code>

===== Quick start =====
First make sure you have ''gpxe.pdsk'' or ''ns8390.pdsk''.  You can download them from [[http://rom-o-matic.net/|ROM-o-matic.net]] or [[download|build them yourself]].

Here is how to **boot over HTTP**:
<code>
qemu -bootp http://server/file gpxe.pdsk
</code>

Or to **boot using PXE**:
<code>
qemu -bootp tftp://10.0.2.2//pxefile -tftp /path/to/pxedir -fda gpxe.pdsk
</code>

QEMU's built-in TFTP server serves files from ''/path/to/pxedir'' at IP address 10.0.2.2.

NOTES:

The ''-bootp'' option was added in QEMU 0.9.1.  For versions of QEMU before 0.9.1, the instructions from [[http://git.etherboot.org/?p=gpxe.git;a=blob;f=contrib/bochs/README.qemu;hb=HEAD|contrib/bochs/README.qemu]] can be used.

gPXE will strip one of the slashes immediately to the left of the actual filename in the -bootp URI you see above.  QEMU 0.9.1 //demands// that there be a leading slash before the filename, so use the two slashes as you see them above unless your QEMU behaves differently.

===== Debugging gPXE with QEMU =====
The QEMU monitor (''CTRL+ALT+2'') supports debug commands to inspect registers and memory (try ''help'' or tab complete).

  * ''stop'' - Stops guest execution, continue using ''c''.
  * ''info registers'' - Prints the CPU state including all registers.
  * ''x'' - Dumps memory:
<code>
x/5ih 0x10000        Disassemble 5 instructions in 16-bit mode at physical address 0x10000
x/iw 0xf600 + 0xa00  Disassemble 1 instruction in 32-bit mode at physical address 0xf600 + 0xa00 = 0x10000
x/xw 0x10000         Dump 32-bit value at physical address 0x10000
x/xh 0x10000         Dump 16-bit value at physical address 0x10000
x/xb 0x10000         Dump 8-bit value at physical address 0x10000
</code>

==== Address calculation ====
The QEMU monitor (and GDB stub) only deals with paged or physical addresses.  Since gPXE does not use paging, QEMU does no address translation automatically.

**Physical addresses** can be used unmodified.  This is what QEMU expects you to enter.

**Real-mode addresses** need to be translated.  For example, 0400:f002 is (0x400 << 4) + 0xf002 = 0x13002 physical.

**Protected-mode addresses** need to be translated.  For example, we want to calculate the physical address of the EIP value:
<code>
EAX=00000000 EBX=00055398 ECX=000556d4 EDX=00055398
ESI=f824d8d0 EDI=000adc58 EBP=00009ce8 ESP=00002d7e
EIP=000004f5 EFL=00000202 [-------] CPL=0 II=0 A20=1 SMM=0 HLT=1
ES =9ce8 0009ce80 0000ffff 00009309
CS =9c8b 0009c8b0 0000ffff 00009b09
SS =9ce8 0009ce80 0000ffff 00009309
DS =9ce8 0009ce80 0000ffff 00009309
FS =9ce8 0009ce80 0000ffff 00009309
GS =9ce8 0009ce80 0000ffff 00009309
</code>
Since instructions are loaded from CS:EIP, we need 0x9c8b0 + 0x4f5 = 0x9cda5.

**Remember that QEMU understands expressions as addresses** (e.g. ''0x9c8b0 + 0x4f5'').