diff --git a/fuchsia_paver.md b/fuchsia_paver.md new file mode 100644 index 0000000000000000000000000000000000000000..8fb6a0c4c4640851490c4975da90913accd4d75d --- /dev/null +++ b/fuchsia_paver.md @@ -0,0 +1,109 @@ +# Putting Fuchsia on a Device + +One of the best ways to experience Fuchsia is by running it on actual hardware. +This guide will help you get Fuchsia installed on your device. Fuchsia has good +support for a few different hardware platforms including the Acer Switch 12, +Intel NUC, and Google Pixelbook (not to be confused with the Chromebook Pixel). +The install process is not currently compatible with ARM-based targets. The +Fuchsia install process, called 'paving', requires two machines, the machine on +which you want to run Fuchsia ("target") and the machine on which you build +Fuchsia ("host"). Host and target must be able to communicate over a local area +network. On your host system you will build Fuchsia, create a piece of install +media, and stream a large portion of the system over the network to the target. + +The `fx` command will be used throughout these instructions. If you have fx +mapped into your command path you can follow the instructions verbatim. If you +don't have fx in your path, it can be found at `//scripts/fx` and you'll need +to use the appropriate relative path in the supplied commands. Many of fx +commands are relatively thin wrappers around build actions in GN coupled with +tool invocations. If your use case isn't quite served by what's currently +available there may a few GN targets you can build or some GN templates you can +extend to allow you to build what you need. + +## TL;DR + +Read this all before? Here are the common case commands +1. `fx set x86-64` +2. `fx full-build` +3. Make the install media + * [[ insert USB drive into host ]] + * `fx mkvbootzedboot <usb_drive_device_path>` +4. Boot and pave + * [[ move USB drive to target ]] + * `fx boot-paver <efi|vboot|nuc|cros|..>` + +## Building + +Detailed instructions for obtaining and building Fuchsia are available from the +[Getting Started](getting_started.md) guide, but we'll assume here that the +target system is x86-based and that you want to build a complete system. To +configure our build for this we can run `fx set x86-64` and then build with +`fx full-build`. + +## Creating install media + +To create your install media we recommend using a USB drive since these are +well-supported as boot media by most systems. Note that the install media +creation process **will be destructive** to the USB drive being used. Insert the +USB drive and then run `fx mkvbootzedboot <device_path>`, which on Linux is +typically something like /dev/sd<X> where X is a letter and on Mac is typically +something like /dev/disk<N> where 'N' is a number. **Be careful not to select +the wrong device**. Once this is done, remove the USB drive. + +## Paving + +Now we'll build the artifacts to transfer over the network during the paving +process. What is transferred is dependent on the target device. For UEFI based +systems (like Intel NUC or Acer Switch 12) our output target type is 'efi'. For +ChromeOS-based systems (like Pixelbook) that use vboot-format images the target +type is 'vboot'. To build our output set you can run +`fx boot-paver <target_type>`, ie. `fx boot-paver efi`. + +Insert the install media into the target device that you want to pave. The target +device's boot settings may need to be changed to boot from the USB device and +this is typically device-specific. For the guides provided here, **only** go +through the steps to set the boot device, don't continue with any instructions on +creating install media. +* [Acer Switch Alpha 12](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/acer12.md) +* [Intel NUC](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/nuc.md) +* [Google Pixelbook](hardware/pixelbook.md) + +Paving should occur automatically after the device is booted into Zedboot from the +USB drive. After the paving process completes the system should boot into the +Zircon kernel. After paving, the whole system is installed on storage. At this +point the USB key can and should be removed. Future boots can be done entirely +from local storage. If you need to re-pave, select Zedboot from Gigaboot (UEFI +systems) or plug the USB drive into your target machine (vboot systems) and run +`fx boot-paver <target_type>`. + +## Troubleshooting + +In some cases paving may fail because you have a disk layout that is incompatible. +In these cases you will see a message that asks you to run +'install-disk-image wipe'. If it is incompatible because it contains an older +Fuchsia layout put there by installer (vs the paver) you can fix this by killing +the boot-paver process on the host, switching to a different console (Alt+F3) on +the target, and running `install-disk-image wipe`. Then reboot the target, +re-run `fx boot-paver <target_type>` on the host, and the pave should succeed. + +## Running without a persistent /data partition + +It is possible to run the system without a persistent data partition. When this is +done /data is backed by a RAM filesystem and thus the device is kind of running in +an incognito mode. To create a device without a persistent data partition you can +start the boot-paver with the '--no-data' option, for example +`fx boot-paver <target_type> --no-data`. If the device already has a data +partition, running paver this way will **not** remove it. To remove the persistent +data partition, don't run bootserver, boot the device into Zedboot, switch to a +command line (Alt+F3), and run `install-disk-image wipe`. Then reboot the +device into Zedboot and start boot server with +`fx boot-paver <target_type> --no-data`. + +## Changing boot target (localboot, netboot, etc) default + +For EFI-based systems, it is possible to change the default boot option of the +system paved on the target between local booting and Zedboot for network booting. +By default the system boots locally with a 1-second delay in Gigaboot to allow you +to select a different mode. To change this default to Zedboot, supply the +`--always_zedboot` option when calling `fx boot-paver <target_type>` or +`fx build-paver`. diff --git a/getting_started.md b/getting_started.md index e68c7c1bd1e5edc13f4344e9eb430f3f7f2cefc8..c792dd58ce01919d870ec7457d779d87263f1cb1 100644 --- a/getting_started.md +++ b/getting_started.md @@ -112,22 +112,10 @@ To override the default behaviors, pass flags to `fx set`: ## Boot Fuchsia -### Boot from hardware +### Installing and booting from hardware -There are three options for booting Fuchsia on hardware: network booting (see -below), booting from USB (see below), or [installing](https://fuchsia.googlesource.com/install-fuchsia/+/master/README.md) -Fuchsia on internal storage. In all cases you'll need to put some code on the -target hardware, using a USB drive is a good option for doing this. - -If you want to netboot or create a bootable USB drive, but not install Fuchsia, -you can use the [build-bootable-usb-gigaboot.sh script](https://fuchsia.googlesource.com/scripts/+/master/build-bootable-usb-gigaboot.sh). -If you plan to netboot, pass the `-m` and `-f` options to skip copying over the -Zircon kernel and Fuchsia system images since the bootserver will supply these. - -* [Acer Switch Alpha 12](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/acer12.md) -* [Intel NUC](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/nuc.md) - -Once your hardware is configured, you can run `fx boot` to start the bootserver. +To get Fuchsia running on hardware requires using the paver, which these +[instructions](fuchsia_paver.md) will help you get up and running with. ### Boot from QEMU diff --git a/glossary.md b/glossary.md index dbcfbfd3e9d27e40b0bfbbffa9a2ccb66edf7c1a..b50e8fff94ac0b9d9740538e337b08512db2933c 100644 --- a/glossary.md +++ b/glossary.md @@ -215,9 +215,10 @@ should be generated by more featureful systems, such as [GN](#gn) in Fuchsia. - [Ninja rules in GN](https://chromium.googlesource.com/chromium/src/tools/gn/+/HEAD/docs/reference.md#ninja_rules) - [Fuchsia build overview](build_overview.md) -#### **Paver** #### +#### **Paver** -TODO(raggi): add definition +A tool in Zircon that installs partition images to internal storage of a device. +- [Guide for installing Fuchsia with paver](fuchsia_paver.md). #### **Peridot** diff --git a/hardware/pixelbook.md b/hardware/pixelbook.md new file mode 100644 index 0000000000000000000000000000000000000000..07e1d23bd39e77d176264ef870ac479d04add39e --- /dev/null +++ b/hardware/pixelbook.md @@ -0,0 +1,27 @@ +# Preparing to install Fuchsia on Pixelbook + +## Putting your device into developer mode +***WARNING: This will erase any state stored locally on your Pixelbook*** + +1. Power off the Pixelbook +2. Go into recovery mode by holding down Refresh+Esc while powering on the device. +3. Go into developer mode by pressing Ctrl+D. +4. Wait for the device to re-configure itself, this may take a while + +## Booting from USB + +1. Boot into ChromeOS +2. At the welcome or login screen press Ctrl+Alt+Refresh/F3 to enter a command shell. +3. Enter 'chronos' as the user with a blank password +4. Enable USB booting by running `sudo crossystem dev_boot_usb=1` +5. (optional) Default to USB booting by running `sudo crossystem dev_default_boot=usb`. +6. Reboot + +If you didn't make USB booting the default (step 5), you will need to press +Ctrl+U at the grey 'warning OS-not verified' screen when you power on your +device. If the device tries to boot from USB, either because that is the default +or you pressed Ctrl+U, and the device fails to boot from USB you'll hear a +fairly loud <BEEP>. Note that ChromeOS bootloader USB enumeration during has +been observed to be slow. If you're having trouble booting from USB, it may be +helpful to remove other USB devices until the device is through the bootloader +and also avoid using a USB hub.