From 2ff700de921d5bb3bb29e3d80087454aa981b099 Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Thu, 21 Dec 2023 19:15:47 +0100 Subject: [PATCH] Documentation: migrate x86_64 readme to rst --- .../qemu/boards/qemu-intel64/README.txt | 184 ------------------ .../x86_64/qemu/boards/qemu-intel64/index.rst | 163 +++++++++++++++- 2 files changed, 161 insertions(+), 186 deletions(-) delete mode 100644 Documentation/platforms/x86_64/qemu/boards/qemu-intel64/README.txt diff --git a/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/README.txt b/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/README.txt deleted file mode 100644 index b76337c675..0000000000 --- a/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/README.txt +++ /dev/null @@ -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="", 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: - - Where 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. diff --git a/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/index.rst b/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/index.rst index 04bcc426ce..74c4349133 100644 --- a/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/index.rst +++ b/Documentation/platforms/x86_64/qemu/boards/qemu-intel64/index.rst @@ -2,6 +2,165 @@ qemu-intel64 ============ -.. include:: README.txt - :literal: +This page file describes the contents of the build configurations available +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="", 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: + + Where ```` 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.