Documentation: migrate x86_64 readme to rst
This commit is contained in:
raiden00pl
Xiang Xiao
parent
bca8df7d65
commit
2ff700de92
@ -1,184 +0,0 @@
|
|||||||
README
|
|
||||||
======
|
|
||||||
|
|
||||||
This README file describes the contents of the build configurations available
|
|
||||||
for the NuttX QEMU x86_64 port.
|
|
||||||
|
|
||||||
Contents
|
|
||||||
========
|
|
||||||
|
|
||||||
* Creating a bootable disk
|
|
||||||
* QEMU/KVM
|
|
||||||
- Running QEMU/KVM
|
|
||||||
* Bochs
|
|
||||||
- Building Bochs
|
|
||||||
- Running Bochs
|
|
||||||
* Real machine
|
|
||||||
* Toolchain
|
|
||||||
* FAQ
|
|
||||||
* Configurations
|
|
||||||
- ostest
|
|
||||||
|
|
||||||
Creating a bootable disk
|
|
||||||
========================
|
|
||||||
|
|
||||||
This build supports multiboot2, which means that usual multiboot2 bootlaoders, e.g. grub can be used.
|
|
||||||
To create a bootable disk with grub2, create a directory named `iso` with grub configuration file and the compiled nuttx.elf.
|
|
||||||
|
|
||||||
##### Directory and file hierarchy
|
|
||||||
```
|
|
||||||
- iso/
|
|
||||||
- boot/
|
|
||||||
- grub/
|
|
||||||
- grub.cfg
|
|
||||||
- nuttx.elf
|
|
||||||
```
|
|
||||||
|
|
||||||
##### grub.cfg
|
|
||||||
|
|
||||||
The grub.cfg should contain the boot entry of NuttX.
|
|
||||||
```
|
|
||||||
set timeout=0
|
|
||||||
set default=0
|
|
||||||
menuentry "kernel" {
|
|
||||||
multiboot2 /boot/nuttx.elf
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
##### Making the disk
|
|
||||||
|
|
||||||
Use the following command to create the disk.
|
|
||||||
P.S. In some distros, `grub-mkrescue` is called `grub2-mkrescue`
|
|
||||||
```
|
|
||||||
grub-mkrescue -o boot.iso iso
|
|
||||||
```
|
|
||||||
|
|
||||||
QEMU/KVM
|
|
||||||
====
|
|
||||||
|
|
||||||
QEMU is a generic and open source machine emulator and virtual machine. Here are
|
|
||||||
some links (which will probably be mostly outdated by the time your read this):
|
|
||||||
|
|
||||||
Home Page: http://wiki.qemu.org/Main_Page
|
|
||||||
Downloads: http://wiki.qemu.org/Download
|
|
||||||
Documentation: http://wiki.qemu.org/Manual
|
|
||||||
|
|
||||||
KVM is the Linux kernel hypervisor.
|
|
||||||
It supports creations of virtual machines in Linux systems.
|
|
||||||
It is usually coupled with Qemu as its I/O supporting layer.
|
|
||||||
|
|
||||||
The qemu can be build from source or downloaded from distro repositories.
|
|
||||||
However, a modern CPU and KVM support are mandatory because the X2APIC is not available
|
|
||||||
in pure emulator mode.
|
|
||||||
This mean using this build with qemu in windows or old x86 machine can be frustrating.
|
|
||||||
In such case, looks the next section and use bochs emulator instead.
|
|
||||||
|
|
||||||
Running QEMU
|
|
||||||
------------
|
|
||||||
|
|
||||||
In the top-level NuttX directory:
|
|
||||||
|
|
||||||
qemu-system-x86_64 -cpu host -enable-kvm -m 2G -cdrom boot.iso -nographic -serial mon:stdio
|
|
||||||
|
|
||||||
This multiplex the qemu console and COM1 to your console.
|
|
||||||
Use control-a 1 and 2 to switch between.
|
|
||||||
Use control-a x to terminate the emulation.
|
|
||||||
|
|
||||||
P.S. Make sure that you CPU supports the mandatory features. Look at Real machine
|
|
||||||
section for more information.
|
|
||||||
|
|
||||||
Bochs
|
|
||||||
=====
|
|
||||||
|
|
||||||
Bochs is also a generic and open source machine emulator and virtualizer.
|
|
||||||
It does very comprehensive emulation of x86 platform, even the state-of-art processors.
|
|
||||||
Here are some links (which will probably be mostly outdated by the time your read this):
|
|
||||||
|
|
||||||
Home Page: http://bochs.sourceforge.net
|
|
||||||
|
|
||||||
The bochs can be build from source.
|
|
||||||
Unlike qemu, it does not rely on KVM to support modern hardware features, therefore it can
|
|
||||||
also be used under Windows.
|
|
||||||
When building bochs, remember to enable x86-64 support with "--enable-x86-64".
|
|
||||||
If you also want support for SIMD instructions, enable them with "--enable-avx --enable-evex".
|
|
||||||
|
|
||||||
Running Bochs
|
|
||||||
------------
|
|
||||||
|
|
||||||
First edit/check the .bochsrc
|
|
||||||
You can create one in the top-level NuttX directory or bochs will use the one in your $HOME.
|
|
||||||
Remember to change the CPU model to one with mandatory features and enable the COM port.
|
|
||||||
|
|
||||||
* Find and edit (You might adjust the IPS as you machine perform):
|
|
||||||
```
|
|
||||||
cpu: model=broadwell_ult, count=1, ips=50000000, reset_on_triple_fault=0, ignore_bad_msrs=0, msrs="msrs.def" a
|
|
||||||
ata0-master: type=cdrom, path="<PATH TO boot.iso>", status=inserted
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
* Add:
|
|
||||||
```
|
|
||||||
com1: enabled=1, mode=file, dev=com1.out
|
|
||||||
```
|
|
||||||
|
|
||||||
In the top-level NuttX directory:
|
|
||||||
|
|
||||||
```
|
|
||||||
bochs
|
|
||||||
```
|
|
||||||
|
|
||||||
The emulator will drop into debugger mode.
|
|
||||||
Enter 'c' to start the emulation.
|
|
||||||
COM port output will be in the com1.out file.
|
|
||||||
|
|
||||||
Real machine
|
|
||||||
============
|
|
||||||
|
|
||||||
This port should work on real x86-64 machine with a proper CPU.
|
|
||||||
The mandatory CPU features are:
|
|
||||||
* TSC DEADLINE or APIC timer
|
|
||||||
* PCID
|
|
||||||
* X2APIC
|
|
||||||
|
|
||||||
WARNING: IF you use TSC DEADLINE, make sure that your CPU's TSC DEADLINE timer is not buggy!
|
|
||||||
|
|
||||||
Toolchains
|
|
||||||
==========
|
|
||||||
|
|
||||||
Currently, only the Linux GCC toolchain is tested.
|
|
||||||
While building on a modern x86_64 PC, the default system GCC can be used.
|
|
||||||
|
|
||||||
Configurations
|
|
||||||
==============
|
|
||||||
|
|
||||||
Common Configuration Notes
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
1. Each Qemu-intel64 configuration is maintained in a sub-directory
|
|
||||||
and can be selected as follow:
|
|
||||||
|
|
||||||
tools/configure.sh qemu-intel64:<subdir>
|
|
||||||
|
|
||||||
Where <subdir> is one of the configuration sub-directories described in
|
|
||||||
the following paragraph.
|
|
||||||
|
|
||||||
2. These configurations use the mconf-based configuration tool. To
|
|
||||||
change a configurations using that tool, you should:
|
|
||||||
|
|
||||||
a. Build and install the kconfig-mconf tool. See nuttx/README.txt
|
|
||||||
see additional README.txt files in the NuttX tools repository.
|
|
||||||
|
|
||||||
b. Execute 'make menuconfig' in nuttx/ in order to start the
|
|
||||||
reconfiguration process.
|
|
||||||
|
|
||||||
3. By default, all configurations assume the Linux. This is easily
|
|
||||||
reconfigured:
|
|
||||||
|
|
||||||
CONFIG_HOST_LINUX=y
|
|
||||||
|
|
||||||
Configuration Sub-Directories
|
|
||||||
-----------------------------
|
|
||||||
|
|
||||||
ostest
|
|
||||||
|
|
||||||
The "standard" NuttX examples/ostest configuration.
|
|
||||||
@ -2,6 +2,165 @@
|
|||||||
qemu-intel64
|
qemu-intel64
|
||||||
============
|
============
|
||||||
|
|
||||||
.. include:: README.txt
|
This page file describes the contents of the build configurations available
|
||||||
:literal:
|
for the NuttX QEMU x86_64 port.
|
||||||
|
|
||||||
|
Creating a bootable disk
|
||||||
|
========================
|
||||||
|
|
||||||
|
This build supports multiboot2, which means that usual multiboot2 bootlaoders,
|
||||||
|
e.g. grub can be used. To create a bootable disk with grub2, create a directory
|
||||||
|
named ``iso`` with grub configuration file and the compiled ``nuttx.elf``.
|
||||||
|
|
||||||
|
Directory and file hierarchy::
|
||||||
|
|
||||||
|
- iso/
|
||||||
|
- boot/
|
||||||
|
- grub/
|
||||||
|
- grub.cfg
|
||||||
|
- nuttx.elf
|
||||||
|
|
||||||
|
The grub.cfg should contain the boot entry of NuttX::
|
||||||
|
|
||||||
|
set timeout=0
|
||||||
|
set default=0
|
||||||
|
menuentry "kernel" {
|
||||||
|
multiboot2 /boot/nuttx.elf
|
||||||
|
}
|
||||||
|
|
||||||
|
Making the disk
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Use the following command to create the disk.
|
||||||
|
P.S. In some distros, ``grub-mkrescue`` is called ``grub2-mkrescue``::
|
||||||
|
|
||||||
|
grub-mkrescue -o boot.iso iso
|
||||||
|
|
||||||
|
QEMU/KVM
|
||||||
|
========
|
||||||
|
|
||||||
|
QEMU is a generic and open source machine emulator and virtual machine. Here are
|
||||||
|
some links (which will probably be mostly outdated by the time your read this):
|
||||||
|
|
||||||
|
* Home Page: http://wiki.qemu.org/Main_Page
|
||||||
|
* Downloads: http://wiki.qemu.org/Download
|
||||||
|
* Documentation: http://wiki.qemu.org/Manual
|
||||||
|
|
||||||
|
KVM is the Linux kernel hypervisor.
|
||||||
|
It supports creations of virtual machines in Linux systems.
|
||||||
|
It is usually coupled with Qemu as its I/O supporting layer.
|
||||||
|
|
||||||
|
The qemu can be build from source or downloaded from distro repositories.
|
||||||
|
However, a modern CPU and KVM support are mandatory because the X2APIC is not
|
||||||
|
available in pure emulator mode.
|
||||||
|
This mean using this build with qemu in windows or old x86 machine can be
|
||||||
|
frustrating. In such case, looks the next section and use bochs emulator instead.
|
||||||
|
|
||||||
|
Running QEMU
|
||||||
|
------------
|
||||||
|
|
||||||
|
In the top-level NuttX directory::
|
||||||
|
|
||||||
|
qemu-system-x86_64 -cpu host -enable-kvm -m 2G -cdrom boot.iso -nographic -serial mon:stdio
|
||||||
|
|
||||||
|
This multiplex the qemu console and COM1 to your console.
|
||||||
|
|
||||||
|
Use control-a 1 and 2 to switch between.
|
||||||
|
Use control-a x to terminate the emulation.
|
||||||
|
|
||||||
|
P.S. Make sure that you CPU supports the mandatory features. Look at Real machine
|
||||||
|
section for more information.
|
||||||
|
|
||||||
|
Bochs
|
||||||
|
=====
|
||||||
|
|
||||||
|
Bochs is also a generic and open source machine emulator and virtualizer.
|
||||||
|
It does very comprehensive emulation of x86 platform, even the state-of-art processors.
|
||||||
|
Here are some links (which will probably be mostly outdated by the time your read this):
|
||||||
|
|
||||||
|
* Home Page: http://bochs.sourceforge.net
|
||||||
|
|
||||||
|
The bochs can be build from source.
|
||||||
|
Unlike qemu, it does not rely on KVM to support modern hardware features,
|
||||||
|
therefore it can also be used under Windows.
|
||||||
|
When building bochs, remember to enable x86-64 support with ``--enable-x86-64``.
|
||||||
|
If you also want support for SIMD instructions, enable them with ``--enable-avx --enable-evex``.
|
||||||
|
|
||||||
|
Running Bochs
|
||||||
|
-------------
|
||||||
|
|
||||||
|
First edit/check the ``.bochsrc``
|
||||||
|
You can create one in the top-level NuttX directory or bochs will use the one in your $HOME.
|
||||||
|
Remember to change the CPU model to one with mandatory features and enable the COM port.
|
||||||
|
|
||||||
|
* Find and edit (You might adjust the IPS as you machine perform)::
|
||||||
|
|
||||||
|
cpu: model=broadwell_ult, count=1, ips=50000000, reset_on_triple_fault=0, ignore_bad_msrs=0, msrs="msrs.def"
|
||||||
|
ata0-master: type=cdrom, path="<PATH TO boot.iso>", status=inserted
|
||||||
|
|
||||||
|
* Add::
|
||||||
|
|
||||||
|
com1: enabled=1, mode=file, dev=com1.out
|
||||||
|
|
||||||
|
* In the top-level NuttX directory::
|
||||||
|
|
||||||
|
bochs
|
||||||
|
|
||||||
|
The emulator will drop into debugger mode.
|
||||||
|
Enter ``c`` to start the emulation.
|
||||||
|
COM port output will be in the com1.out file.
|
||||||
|
|
||||||
|
Real machine
|
||||||
|
============
|
||||||
|
|
||||||
|
This port should work on real x86-64 machine with a proper CPU.
|
||||||
|
The mandatory CPU features are:
|
||||||
|
|
||||||
|
* TSC DEADLINE or APIC timer
|
||||||
|
* PCID
|
||||||
|
* X2APIC
|
||||||
|
|
||||||
|
WARNING: IF you use TSC DEADLINE, make sure that your CPU's TSC DEADLINE timer
|
||||||
|
is not buggy!
|
||||||
|
|
||||||
|
Toolchains
|
||||||
|
==========
|
||||||
|
|
||||||
|
Currently, only the Linux GCC toolchain is tested.
|
||||||
|
While building on a modern x86_64 PC, the default system GCC can be used.
|
||||||
|
|
||||||
|
Configurations
|
||||||
|
==============
|
||||||
|
|
||||||
|
Common Configuration Notes
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
1. Each Qemu-intel64 configuration is maintained in a sub-directory
|
||||||
|
and can be selected as follow::
|
||||||
|
|
||||||
|
tools/configure.sh qemu-intel64:<subdir>
|
||||||
|
|
||||||
|
Where ``<subdir>`` is one of the configuration sub-directories described in
|
||||||
|
the following paragraph.
|
||||||
|
|
||||||
|
2. These configurations use the mconf-based configuration tool. To
|
||||||
|
change a configurations using that tool, you should:
|
||||||
|
|
||||||
|
a. Build and install the kconfig-mconf tool. See nuttx/README.txt
|
||||||
|
see additional README.txt files in the NuttX tools repository.
|
||||||
|
|
||||||
|
b. Execute ``make menuconfig`` in nuttx/ in order to start the
|
||||||
|
reconfiguration process.
|
||||||
|
|
||||||
|
3. By default, all configurations assume the Linux. This is easily
|
||||||
|
reconfigured::
|
||||||
|
|
||||||
|
CONFIG_HOST_LINUX=y
|
||||||
|
|
||||||
|
Configuration Sub-Directories
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
ostest
|
||||||
|
------
|
||||||
|
|
||||||
|
The "standard" NuttX examples/ostest configuration.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user