system/serenity
system/serenity
1
0
Fork 0
mirror of https://github.com/SerenityOS/serenity synced 2024-07-05 22:54:55 +00:00
Code Issues Projects Releases Wiki Activity

Meta: Update bare metal installation guide

Browse Source
This commit is contained in:
Dan MacDonald 2020-12-10 20:20:54 +00:00 committed by Andreas Kling
parent c139b7fe78
commit 0e8702c310
1 changed files with 6 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Documentation/INSTALL.md
View File

@ -2,18 +2,18 @@
## DISCLAIMER
Whilst it is possible to run Serenity on physical x86-compatible hardware, it is not yet ready to be used by non-technical users who aren't prepared to report bugs or assist with its development. For this reason, there are currently no pre-built install images so a bare-metal installation requires that you build an installation image from source under Linux. Any Linux distribution capable of running GCC 8 (or newer) should be sufficient to build Serenity. Current hardware support is extremely limited.
Whilst it is possible to run Serenity on physical x86-compatible hardware, it is not yet ready to be used by non-technical users who aren't prepared to report bugs or assist with its development. For this reason, there are currently no pre-built install images so a bare-metal installation requires that you build an installation image from source. Current hardware support is extremely limited. Most successful installations have been on Pentium 4 era hardware.
## Hardware support and requirements
Storage-wise Serenity requires a >= 500 MB parallel ATA or SATA IDE disk. Some older SATA chipsets already operate in IDE mode whilst some newer ones will depend upon adjusting a BIOS option to run your SATA controller in IDE (sometimes referred to as Legacy or PATA) mode. SATA AHCI, SCSI, SAS, eMMC and NVME are all presently unsupported.
Storage-wise Serenity requires a >= 2 GB parallel ATA or SATA IDE disk. Some older SATA chipsets already operate in IDE mode whilst some newer ones will depend upon adjusting a BIOS option to run your SATA controller in IDE (sometimes referred to as Legacy or PATA) mode. SATA AHCI, SCSI, SAS, eMMC and NVME are all presently unsupported.
You must be willing to wipe your disk's contents to allow for writing the Serenity image so be sure to back up any important data on your disk first! Serenity uses the GRUB2 bootloader so it should be possible to multiboot it with any other OS that can be booted from GRUB2 post-installation.
Serenity currently has no support for USB but some machines will emulate PS/2 keyboards and mice in the BIOS via USB. BIOS USB PS/2 emulation can be buggy so having real PS/2 input devices is recommended. A minimum of 32 MB RAM and a Pentium III class CPU are required.
At present there is no real GPU support so don't expect OpenGL, Vulkan nor accelerated video playback and encoding support. Serenity currently relies upon VESA BIOS extensions to provide its display output and so it only runs on BIOS-based PCs. There is no WiFi support and the only physical network card chipset currently supported is the RTL8139. The sole sound card supported is the SoundBlaster 16.
At present there is no real GPU support so don't expect OpenGL, Vulkan nor accelerated video playback and encoding support. Serenity currently relies upon VESA BIOS extensions to provide its display output and so it only runs on BIOS-based PCs. There is no WiFi support and the only physical network card chipset currently supported is the RTL8139. The sole sound card supported is the SoundBlaster 16 ISA.
## Creating a Serenity GRUB disk image
@ -22,12 +22,10 @@ Before creating a Serenity disk image, you need to build the OS as described in
The final step is copying **grub_disk_image** onto the disk you wish to boot Serenity off using a command such as:
```
$ sudo dd if=grub_disk_image of=/dev/sdx bs=8M
$ sudo dd if=grub_disk_image of=/dev/sdx bs=64M && sync
```
Replace **/dev/sdx** with the target device. The **bs=8M** argument is optional but will speed up the data transfer.
Serenity doesn't output any kernel boot messages to the display device so if it fails to boot you will need a serial port and a null modem cable to discover the cause of the failure.
Replace **/dev/sdx** with the target device. The **bs=64M** argument is optional but will speed up the data transfer.
## Troubleshooting Serenity boot issues with Linux using a null modem (serial) cable
@ -47,4 +45,4 @@ $ cu -s 57600 -l /dev/ttyUSB0
## Troubleshooting boot issues without a serial port
Serenity is a graphical OS and thus boots directly to the desktop. If your computer doesn't have a serial port and it fails to boot, you can force Serenity to boot into text mode by selecting the **SerenityOS (text mode)** option in GRUB.
If your computer fails to boot and it doesn't have a serial port, you can force Serenity to boot into text mode by editing **Kernel/Arch/i386/Boot/boot.S** and removing **| MULTIBOOT_VIDEO_MODE** from the end of the **multiboot_flags** before building Serenity. This debug source tweak differs from the Serenity text mode GRUB boot option which boots you directly into a text mode shell.