Skip to content

Commit

Permalink
Meta: Update install guide with instructions for booting into text mo…
Browse files Browse the repository at this point in the history
  • Loading branch information
danboid authored and awesomekling committed Nov 11, 2019
1 parent 6dab257 commit 0e80b7f
Showing 1 changed file with 10 additions and 4 deletions.
14 changes: 10 additions & 4 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,17 @@ Whilst it is possible to run Serenity on physical x86-compatible hardware, it is

## Hardware support and requirements

Storage-wise Serenity requires a >= 500 MB parallel ATA IDE disk. You may also be able to use a SATA disk if your BIOS has the 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 disks contents to allow for writing the Serenity image so be sure to back up any wanted 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.
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.

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. 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.

## Creating a Serenity GRUB disk image

Before creating a Serenity disk image, you need to build the OS as described in the **"How do I build and run this?"** section of the [Serenity ReadMe](https://github.com/SerenityOS/serenity/blob/master/ReadMe.md). Follow those instructions up to and including running **./makeall.sh**. After the OS has built, run **sudo ./build-image-grub.sh** to replace the qemu **_disk_image** file in the Kernel directory with one that has GRUB2 installed that can be booted on a real PC.
Before creating a Serenity disk image, you need to build the OS as described in the **"How do I build and run this?"** section of the [Serenity ReadMe](https://github.com/SerenityOS/serenity/blob/master/ReadMe.md). Follow those instructions up to and including running **./makeall.sh**. After the OS has built, run **sudo ./build-image-grub.sh** to replace the qemu **_disk_image** file in the Kernel directory with one that has GRUB2 installed that can be booted on a real PC. Alternately, you can run **sudo ./build-gpt-image-grub.sh** to create an image that uses GPT partitioning.

The final step is copying **_disk_image** onto the disk you wish to boot Serenity off using a command such as:

Expand All @@ -27,7 +29,7 @@ Replace **/dev/sdx** with the target device. The **bs=8M** argument is optional

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.

## Debugging Serenity boot issues using Linux
## Troubleshooting Serenity boot issues with Linux using a null modem (serial) cable

Many guides on the internet recommend using `screen` to monitor or interact with a serial console under Linux. Using `screen` is an option but it is quite tricky to copy and paste the output from a `screen` console when there is more than one screens worth of text. So, unless you are already experienced with `screen` it is recommended you use `cu`.

Expand All @@ -42,3 +44,7 @@ Once you are logged in with a user who is a member of the **dialout** group, you
```
$ 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 editing **Kernel/Arch/i386/Boot/boot.S** and removing **| MULTIBOOT_VIDEO_MODE** from the end of the **multiboot_flags** line before (re)running **makeall.sh**.

0 comments on commit 0e80b7f

Please sign in to comment.