search

hexdump0815 / linux-mainline-on-arm-chromebooks

running linux mainline on arm chromebooks - for example: samsung xe303c12 and xe503c12 (snow and peach), acer c100, c101 and c201 (veyron speedy, minnie etc. and gru bob and kevin), medion s2013 and s2015 (veyron jaq, mighty etc.), acer cb5 311 (nyan big), lenovo n23, acer r13 (oak elm and hana), lenovo duet (kukui krane) and most probably many many more over time ...
144 stars 10 forks source link

readme

running linux mainline on arm chromebooks

kappa and juniper with velvet

intro

this is about running a real mainline linux system on arm chromebooks, so no chromeos and this is not about intel chromebooks - for those please have a look at the intel related links at the bottom of this page, those should help you getting a real linux running on them.

there are most probably three (maybe even more) reasons why one wants to run a real mainline linux system on arm chromebooks:

what you will find here is the try to support many of those arm chromebooks to some (and hopefully increasing) degree by providing disk images one can simply write to an sd card and run them from there (i.e. even while initially keeping chromeos on the device). at the beginning the focus will be to somehow cover as many of them as possible with a basic system, i.e. some useful x11 (with wayland as an option) desktop setup and extend the functionality step by step from there (i.e. trying to add things like accelerated video playback or add sound support where it is still missing etc.). in the current state most of the supported chromebooks are somehow useable for people with linux know-how, but i would not yet recommend them for typical end users who expects everything to work well and out of the box (this will hopefully change over time). this is a slowly evolving spare time project, so please do not expect wonders and things will take time, but it will steadily move forward. the detailed current state for the different arm chromebooks can be found at the corresponding links below. there are also some more links to other similar projects.

i'm open for generally useful suggestions and tested pull requests. i'm not so interested in very special feature requests ("please add this very uncommon driver to the kernel" or similar) or untested suggestions. instead i would like to encourage people to for instance build their own kernels or maybe even images - its not that complicated and all information should be around and spread across a few repositories here in a more or less readable format. for reports of success or failure with the images provided and everything else please create github issues. one thing is important to keep in mind: the most effort goes into trying to make sure that everything at least somehow works in the end and the least effort is required to get new ideas what can be done or added - i actually already have a very long list of things i would like to add :)

supported devices and linux distributions

currently xubuntu 22.04 (focal) and debian 12 (bookworm) are supported. older images are based on xubuntu 20.04 (focal) and debian 11 (bullseye).

the following chromebook types are more or less supported:

enabling developer mode

in order to boot anything else than chromeos on a chromebook one needs to enable the developer mode for it. a few things related to enabling the developer mode are important to know: first - in the process all data saved locally on the chromebook will be deleted, so important data should be backed up first - and second - in developer mode some of the advanced security features of chromeos are not enabled anymore. some more information about the developer mode and how to enable it on different devices can be found here: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_mode.md

on a normal chromebook with a built in keyboard the following procedure will initiate the switch to developer mode (see: https://chromium.googlesource.com/chromiumos/docs/+/master/debug_buttons.md#firmware-keyboard-interface):

for more tablet style chromebooks without a fixed keyboard (like the lenovo duet for instance) the following procedure will initiate the switch to developer mode (see: https://chromium.googlesource.com/chromiumos/docs/+/master/debug_buttons.md#firmware-menu-interface):

afterwards preparing everything for booting from sd card or usb looks like this by going to the command prompt (see: https://chromium.googlesource.com/chromiumos/docs/+/master/developer_mode.md#shell):

now the chromebook should be able to boot one of the bootable images provided here for the corresponding device type and written properly to an sd card or usb disk. for writing disk images to such a medium there is plenty of information available on the web about how to do it on the different operating systems. After booting into the image, you can expand the root partition using /scripts/extend-rootfs.sh.

updating to the latest chromeos version without going through the initial login procedure

in case someone wants to update chromeos to the latest version on a new or freshly reset into developer mode chromebook without having to go through the initial login and setup sequence, then it should work like this:

setting gbb flags, enabling ccd and the magic suzyqable

it is possible to set parameters like the above to enable booting from usb also as default in the chromebook firmware via the so called gbb flags. this is definitely recommended as soon as one wants to install a regular linux onto the internal emmc storage of a chromebook (and wiping the chromeos on it). the reason for this is that at least some chromebooks tend to drain the battery if not used for a longer time and settings like the above for allowing usb booting and the enabled developer mode get lost if the battery gets completely empty in such cases. so one might end up in a situation where booting from usb/sd card is no longer possible as the corresponding flags were reset to their default to not allow booting from those devices. as there is no chromeos anymore on the emmc it is not possible to change the flags to enable booting from usb/sd again and the only way out is to restore cromeos via restore image onto the internal emmc storage wiping the regular linux installation there (and loosing all of its data) which is not really what one wants. due to this it is in the end highly recommended to set those flags to default to allow usb/sd booting and enabled developer mode, so that it will still work even if the battery gets completely drained. in case one gets into the above described situation that the usb booting flags get lost due to battery drain there might be some last option to get access to the installed linux on emmc back without having to restore chromeos to it by using a special hand crafted restore image as described here: https://www.chromium.org/chromium-os/developer-information-for-chrome-os-devices/workaround-for-battery-discharge-in-dev-mode/ - i'm not sure if this procedure is still working for the latest chromeos and firmware versions, but it might be worth a try at least in such cases.

the problem with this is that it is not really that easy as chromebooks have by default some form of write protection enabled for the area of the firmware where those gbb flags are stored as part of the chromeos security setup. disabling this write protection requires opening the chromebook and removing a certain screw (in most cases) or metallic sticker (for instance in case of the snow chromebook), which is bridging some contacts to keep the write protection active. a search on the internet should bring up a lot of information about where to find this special screw for different chromebook types and how this screw usually looks like (for the ones without explicit documentation). this method to enable/disable the write protection was used on all older chromebooks, but all newer ones do it in a different way which does not longer require the device to be opened, but requires a special usb-c cable to disable the write protection - the suzyqable - instead. this cable has on top of that a few other nice use cases: it provides access to the serial console of the chromebook, to the ec firmware console and to the so called cr50 console. all this together is called 'ccd' for closed case debugging. if a certain chromebook supports ccd can be seen in the last column of this table: https://www.chromium.org/chromium-os/developer-information-for-chrome-os-devices - more information about how to disable the write protection via suzyqable on supported systems can be found here: https://wiki.mrchromebox.tech/Firmware_Write_Protect#Disabling_WP_on_CR50_Devices_via_CCD

after following the mrchromebox guide from above to open the ccd, the following commands given at the ccd prompt will ensure maximum openness and least risk of not being able to get out of a bricked situation (but please be aware that this will give quite a bit of power to everyone having physical access to the device):

and finally some more detailed links around those topics:

back to the gbb flags ... lets assume the write protection has been disabled in one way or another. the following are the steps to set the gbb flags in the desired way:

on older chromebooks (at least the 32bit versions) it is also possible to replace the initial developer mode sceen with a simple black screen with the small text 'developer mode warning' in the middle of the screen by doing the following steps before re-enabling the write protection above (make sure you have saved a copy of your initial bios.bin file somewhere outside of your chromebook beforehand):

it seems to be possible to do a similar cleanup of the intial developer mode screen on newer devices as well according to https://www.reddit.com/r/chromeos/comments/hbajeg/bios_bitmaps_question/fv8uncy/ - i tried it on an elm chromebook and it worked using the following commands:

it is a good idea to put the bios.bin.org and vbgfx.bin.org to a safe place in case one wants to revert the changes one day (i did not really like the result and actually reverted it back to the original state by flashing back the bios.bin.org). maybe it is even possible to replace the default bitmaps with custom own ones similar to how it is described at https://jcs.org/2016/08/26/openbsd_chromebook for the old gbb bitmaps. after looking closer at this it looks like this is more complex than initially expected - see: https://github.com/hexdump0815/imagebuilder/blob/61a5297fde1431bf28ff390aeabe6b4eab52f223/todo.txt#L9-L14

in case someone wants to ccd lock and ccd unlocked chromebook again it can be dones via the following steps:

some advanced hints for cr50/suzyqable enabled chromebooks

the following are just some hints about some extra things possible with chromebooks with a cr50 which are thus suzyqable ready - most of those hints require a ccd-opened and/or write protect disabled chromebook (as usual doing anything like this is at your own risk):

different boot options: u-boot, kpart

there are two boot strategies used in the arm chromebook bootable images: chainloaded u-boot and native chromeos kpart kernels. actually there is the third options to install a self-built low level libreboot or coreboot bootloader, but this options is quite complicated, risky and not supported for many arm chromebooks and thus not used and discussed here.

booting via chainloaded u-boot is used by images for the 32bit armv7l chromebooks. here the low level bootloader is loading u-boot (another very common bootloader for arm systems) instead of the linux kernel and u-boot then will load the actual kernel. the advantage of this setup is that it is possible to create boot menus for selecting different kernels etc.

the native chromeos kpart booting works by packaging the used mainline kernel in the same way the regular chromeos kernel is packaged (kpart - i.e. the format for the kernel partition) and putting it this way into the kernel partition, so that the chromebook will boot it just like a regular chromeos kernel. this approached is used for the 64bit aarch64 chromebooks as there is no mainline u-boot available for them, which could be chainloaded. the disadvantages of this approach are that the resulting kernel image can be at max 32mb in size (16mb for 32bit armv7l systems) which can be quite small for systems with initrd and that the kernel cmdline args are fixed built into this kernel image and thus it is not very flexible. the advantage of this approach is that such a kernel image can contain multiple dtb files for different hardware and the proper one will be selected automatically at boot. an important feature of chromeos kernel partitions is that there might be multiple of them and they can be given a priority and a counter for failed boots which to some degree gives the opportunity for relatively failsafe test booting of new kernels without the risk of completely bricking a system. the bootable images discussed here for this reason have two kernel partitions of which only the first is currently used right now - the second one os there for test booting other kernels if done with the proper settings.

using and adjusting the bootable images

the bootable images discussed here can either be bootable directly without any further changes after writing the image to an sd card or usb disk (important side note: not all chromebooks can boot from both media - some can only boot from sd card, on some not all usb connectors are bootable and not all chromebooks have an sd card slot at all). for some of the images some extra steps are required to adjust the image for a specific model of the supprted hardware - those additional steps are usually described in the system specific readme and they are usually one or both of the following: adjusting the dtb file in the extlinux.conf boot configuration file or installing the proper u-boot version. the extlinux.conf file can be found in the "extlinux" directory of the third partition (boot) of the written image and is a simple text file which usually contains some comments on what might require adjustment. alternative u-boot versions can be found in the "extra" directory of the same partition and are written with the dd command to the first partition (the primary kernel partition).

storing chromebooks and avoiding battery drain

maybe the following situations seem familiar when dealing with chromebooks: a chromebook was fully charged and not used for a while and afterwards the battery is already fully discharged - or - a chromebook is turned off and put into a shelf, maybe on top of another laptop or similar device and a moment later it turned on again on its own or a day later the battery is completely discharged.

the reason for the first situation is that even if a chromebook is turned off the embedded controller is still running in some low power mode and thus draining the battery slowly until it is empty after a few weeks or months usually. this happens as chromebooks usually do not have those small extra bios batteries other systems often have to keep components like an embedded controller or real time clock alive when they are powered off.

the second situation comes from the fact that chromebooks often have small magnetic sensors for sensing the opening of the lid (which has a corresponding small magnet on it) to power them on in this case. those magnetic sensors can easily get confused by other strong magnets (for instance from another laptop) and as a result the chromebook will power on even if the lid has not really been opened. if this stays unnoticed it might run then until the battery gets drained in the worst case.

a way to avoid such situations when storing a chromebook for a longer time while not using it is a special mode most newer chromebooks can be put into to avoid such behaviour: the battery disconnect mode or battery cutoff mode. it looks like it seems to be available for most chromebooks with a built in keyboard built after around 2014/2015 - older models do not seem to support it. to enter this mode the refresh button (the one in the top row with the round circle) has to be pressed for a few seconds together with the power button while the charger is connected and then the charger has to be removed while still pressing those buttons together. afterwards the chromebook will not power on anymore neither by pressing the power button nor by opening the lid until a charger is connected. it can then be stored for a very long time with only very minimal battery drain. in theory it should work by pressing the power together with the volume up button and removing the power supply for 5 seconds for tablet style chromebooks without a builtin keyboard like the lenovo duet (krane), but it did not work for me for this device. what kind of worked for the lenovo duet was to set "crossystem battery_cutoff_request=1" as root in chromeos in developer mode while there is no power supply connected and reboot - this way it did not seem to respond to lid open events, but can still be powered on using the power button. not sure yet, if this can somehow also be initiated from linux without having to run chromeos. it looks like on older chromebooks sometimes "ectool batterycutoff" can put the chromebook into battery cutoff mode (tested to work on a hp chromebook 14 g1 - nyan blaze and other older chromebooks, seems to be working back to snow and spring even).

some usefule links regarding those topics:

some useful links about chromebooks, chromeos versions, recovery images etc.

other related projects

for arm chromebooks:

for other arm laptops:

for intel chromebooks: