.. SPDX-License-Identifier: GPL-2.0-or-later
.. depthcharge-tools README file
.. Copyright (C) 2019-2023 Alper Nebi Yasak <alpernebiyasak@gmail.com>
.. See COPYRIGHT and LICENSE files for full copyright information.
=================
Depthcharge-Tools
=================
This project is a collection of tools that ease and automate interacting
with depthcharge_, the Chrome OS bootloader.
Depthcharge is built into the firmware of Chrome OS boards, uses a
custom verified boot flow and usually cannot boot other operating
systems as is. This means someone who wants to use e.g. Debian_ on these
boards need to either replace the firmware or work their system into
`the format depthcharge expects`_. These tools are about the latter.
Right now these are developed on and tested with only a few boards,
but everything will attempt to work on other boards based on my best
guesses.
.. _depthcharge: https://chromium.googlesource.com/chromiumos/platform/depthcharge
.. _the format depthcharge expects: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/disk_format.md#Google-ChromeOS-devices
.. _Debian: https://www.debian.org/
mkdepthcharge
=============
The mkdepthcharge_ tool is intended to wrap mkimage_ and vbutil_kernel_
to provide reasonable defaults to them, hide their idiosyncrasies and
automate creating a depthcharge-bootable partition image appropriate for
the running architecture. An example invocation on a Samsung Chromebook
Plus (v1, arm64) could be::
$ mkdepthcharge -o depthcharge.img --compress lzma \
--cmdline "console=tty1 root=/dev/mmcblk0p2 rootwait" -- \
/boot/vmlinuz.gz /boot/initrd.img rk3399-gru-kevin.dtb
Here, mkdepthcharge would automatically extract and recompress the
kernel, create a FIT image, put command line parameters into a file,
create an empty bootloader, and provide defaults for vboot keys and
other arguments while building the partition image.
.. _mkdepthcharge: https://github.com/alpernebbi/depthcharge-tools/blob/master/mkdepthcharge.rst
.. _mkimage: https://dyn.manpages.debian.org/jump?q=unstable/mkimage
.. _vbutil_kernel: https://dyn.manpages.debian.org/jump?q=unstable/vbutil_kernel
depthchargectl
==============
The depthchargectl_ tool goes a step further and aims to fully automate
bootable image creation and Chrome OS kernel partition management, even
the board-specific and distro-specific parts. With proper integration
with your distribution, depthchargectl can keep your system bootable
across kernel and initramfs changes without any interaction on your
part. Even without such integration, a single command automates most of
the work::
# Use --allow-current if you only have one Chrome OS kernel partition.
$ sudo depthchargectl write --allow-current
Building depthcharge image for board 'Samsung Chromebook Plus' ('kevin').
Built depthcharge image for kernel version '5.10.0-6-arm64'.
Wrote image '/boot/depthcharge/5.10.0-6-arm64.img' to partition '/dev/mmcblk1p1'.
Set partition '/dev/mmcblk1p1' as next to boot.
# After a reboot, you or an init service should run this.
$ sudo depthchargectl bless
Set partition '/dev/mmcblk1p1' as successfully booted.
.. _depthchargectl: https://github.com/alpernebbi/depthcharge-tools/blob/master/depthchargectl.rst
Installation
============
This depends on the ``pkg_resources`` Python package which is usually
distributed with ``setuptools``. The tools can run a number of programs
when necessary, which should be considered dependencies:
- ``futility`` (``vbutil_kernel``), ``cgpt``, ``crossystem``
- ``mkimage``, ``fdtget``, ``fdtput``
- ``lz4``, ``lzma``
- ``gzip``, ``lzop``, ``bzip2``, ``xz``, ``zstd``
(optional, for unpacking compressed ``/boot/vmlinuz``)
The ``rst2man`` program (from ``docutils``) should be used to convert
the ``mkdepthcharge.rst`` and ``depthchargectl.rst`` files to manual
pages. However, this is not automated here and has to be done manually.
This project (or at least ``depthchargectl``) is meant to be integrated
into your operating system by its maintainers, and the best way to
install it is through your OS' package manager whenever possible.
Debian
------
An official `depthcharge-tools Debian package`_ is available upstream,
since Debian 12 (bookworm). You can install it like any other package::
$ sudo apt install depthcharge-tools
It includes the necessary system hooks and services to make and keep
your Chromebook bootable, enabled by default. These however do not
trigger on the depthcharge-tools installation, but on kernel and
initramfs changes. To trigger these hooks manually, run::
$ sudo update-initramfs -u
.. _depthcharge-tools Debian package: https://packages.debian.org/sid/depthcharge-tools
Alpine Linux
------------
Thanks to the efforts in supporting `postmarketOS on ChromeOS Devices`_,
there is an official `depthcharge-tools package for Alpine Linux`_. You
should be able to install it as::
$ sudo apk add depthcharge-tools
However, this doesn't include any system hooks or services to keep your
Chromebook bootable.
.. _postmarketOS on ChromeOS Devices: https://wiki.postmarketos.org/wiki/Chrome_OS_devices
.. _depthcharge-tools package for Alpine Linux: https://pkgs.alpinelinux.org/package/edge/testing/x86/depthcharge-tools
Pip
---
Python binary wheels are uploaded to PyPI_, and it should be possible to
install the python package using `pip`. However, this does not install
the manual pages, bash/zsh completions, systemd/init.d service files,
and OS-specific kernel/initramfs hooks.
You can install in `--user` mode, but this makes it quite hard to use
`depthchargectl` as root. As root privileges are necessary to manipulate
system block devices this limits you a bit::
$ pip install --user depthcharge-tools
Although inadvisable, you can install as root to overcome that caveat.
Alternatively, see the `PYTHONPATH` hack in one of the later sections.
.. _PyPI: https://pypi.org/project/depthcharge-tools/
Configuration
=============
You can configure depthcharge-tools with the |CONFIG_FILE| file, or by
putting similar fragments in the |CONFIGD_DIR| directory. See the
config.ini_ file for the built-in default configuration.
Settings in the ``[depthcharge-tools]`` section are the global defaults
from which all commands inherit. Other than that, config sections have
inheritence based on their names i.e. those in the form of ``[a/b/c]``
inherit from ``[a/b]`` which also inherits from ``[a]``. Each subcommand
reads its config from such a subsection.
Currently the following configuration options are available::
[depthcharge-tools]
enable-system-hooks: Write/remove images on kernel/initramfs changes
vboot-keyblock: The kernel keyblock file for verifying and signing images
vboot-private-key: The private key (.vbprivk) for signing images
vboot-public-key: The public key for (.vbpubk) verifying images
[depthchargectl]
board: Codename of a board to build and check images for
ignore-initramfs: Do not include an initramfs in the image
images-dir: Directory to store built images
kernel-cmdline: Kernel commandline parameters to use
zimage-initramfs-hack = How to support initramfs on x86 boards
For longer explanations check the manual pages of each command for
options named the same as these.
.. |CONFIG_FILE| replace:: ``/etc/depthcharge-tools/config``
.. |CONFIGD_DIR| replace:: ``/etc/depthcharge-tools/config.d``
.. _config.ini: https://github.com/alpernebbi/depthcharge-tools/blob/master/depthcharge_tools/config.ini
Installation for development
============================
If you want to use development versions, you can clone this repository
and install using pip::
$ pip3 install --user -e /path/to/depthcharge-tools
Hopefully, you should be able to use depthchargectl with just that::
$ depthchargectl build --output depthcharge.img
Building depthcharge image for board 'Samsung Chromebook Plus' ('kevin').
Built depthcharge image for kernel version '5.10.0-6-arm64'.
depthchargectl.img
Most ``depthchargectl`` functionality needs root as it handles disks and
partitions, and you need special care while invoking as root::
$ depthchargectl() {
sudo PYTHONPATH=/path/to/depthcharge-tools \
python3 -m depthcharge_tools.depthchargectl "$@"
}
$ depthchargectl list /dev/mmcblk0
S P T PATH
1 2 0 /dev/mmcblk0p2
1 1 0 /dev/mmcblk0p4
0 0 15 /dev/mmcblk0p6
Or you can add a similar invocation to the /usr/local/bin files, so that
it's available to both normal users and root::
$ sudo tee /usr/local/bin/depthchargectl <<EOF
#!/bin/sh
export PYTHONDONTWRITEBYTECODE=1
export PYTHONPATH=/path/to/depthcharge-tools
exec python3 -m depthcharge_tools.depthchargectl "\$@"
EOF
$ sudo chmod +x /usr/local/bin/depthchargectl
License
=======
Copyright (C) 2019-2023 Alper Nebi Yasak <alpernebiyasak@gmail.com>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>
See COPYRIGHT and LICENSE files for full copyright information.
Raw data
{
"_id": null,
"home_page": "https://github.com/alpernebbi/depthcharge-tools",
"name": "depthcharge-tools",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "ChromeOS ChromiumOS depthcharge vboot vbutil_kernel",
"author": "Alper Nebi Yasak",
"author_email": "alpernebiyasak@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0e/3d/a398343cda5f7d197fa90828e7943a5c552ef9abc17a6a88a913218eb265/depthcharge-tools-0.6.2.tar.gz",
"platform": null,
"description": ".. SPDX-License-Identifier: GPL-2.0-or-later\n\n.. depthcharge-tools README file\n.. Copyright (C) 2019-2023 Alper Nebi Yasak <alpernebiyasak@gmail.com>\n.. See COPYRIGHT and LICENSE files for full copyright information.\n\n=================\nDepthcharge-Tools\n=================\nThis project is a collection of tools that ease and automate interacting\nwith depthcharge_, the Chrome OS bootloader.\n\nDepthcharge is built into the firmware of Chrome OS boards, uses a\ncustom verified boot flow and usually cannot boot other operating\nsystems as is. This means someone who wants to use e.g. Debian_ on these\nboards need to either replace the firmware or work their system into\n`the format depthcharge expects`_. These tools are about the latter.\n\nRight now these are developed on and tested with only a few boards,\nbut everything will attempt to work on other boards based on my best\nguesses.\n\n.. _depthcharge: https://chromium.googlesource.com/chromiumos/platform/depthcharge\n.. _the format depthcharge expects: https://chromium.googlesource.com/chromiumos/docs/+/HEAD/disk_format.md#Google-ChromeOS-devices\n.. _Debian: https://www.debian.org/\n\n\nmkdepthcharge\n=============\nThe mkdepthcharge_ tool is intended to wrap mkimage_ and vbutil_kernel_\nto provide reasonable defaults to them, hide their idiosyncrasies and\nautomate creating a depthcharge-bootable partition image appropriate for\nthe running architecture. An example invocation on a Samsung Chromebook\nPlus (v1, arm64) could be::\n\n $ mkdepthcharge -o depthcharge.img --compress lzma \\\n --cmdline \"console=tty1 root=/dev/mmcblk0p2 rootwait\" -- \\\n /boot/vmlinuz.gz /boot/initrd.img rk3399-gru-kevin.dtb\n\nHere, mkdepthcharge would automatically extract and recompress the\nkernel, create a FIT image, put command line parameters into a file,\ncreate an empty bootloader, and provide defaults for vboot keys and\nother arguments while building the partition image.\n\n.. _mkdepthcharge: https://github.com/alpernebbi/depthcharge-tools/blob/master/mkdepthcharge.rst\n.. _mkimage: https://dyn.manpages.debian.org/jump?q=unstable/mkimage\n.. _vbutil_kernel: https://dyn.manpages.debian.org/jump?q=unstable/vbutil_kernel\n\n\ndepthchargectl\n==============\nThe depthchargectl_ tool goes a step further and aims to fully automate\nbootable image creation and Chrome OS kernel partition management, even\nthe board-specific and distro-specific parts. With proper integration\nwith your distribution, depthchargectl can keep your system bootable\nacross kernel and initramfs changes without any interaction on your\npart. Even without such integration, a single command automates most of\nthe work::\n\n # Use --allow-current if you only have one Chrome OS kernel partition.\n $ sudo depthchargectl write --allow-current\n Building depthcharge image for board 'Samsung Chromebook Plus' ('kevin').\n Built depthcharge image for kernel version '5.10.0-6-arm64'.\n Wrote image '/boot/depthcharge/5.10.0-6-arm64.img' to partition '/dev/mmcblk1p1'.\n Set partition '/dev/mmcblk1p1' as next to boot.\n\n # After a reboot, you or an init service should run this.\n $ sudo depthchargectl bless\n Set partition '/dev/mmcblk1p1' as successfully booted.\n\n.. _depthchargectl: https://github.com/alpernebbi/depthcharge-tools/blob/master/depthchargectl.rst\n\n\nInstallation\n============\nThis depends on the ``pkg_resources`` Python package which is usually\ndistributed with ``setuptools``. The tools can run a number of programs\nwhen necessary, which should be considered dependencies:\n\n- ``futility`` (``vbutil_kernel``), ``cgpt``, ``crossystem``\n- ``mkimage``, ``fdtget``, ``fdtput``\n- ``lz4``, ``lzma``\n- ``gzip``, ``lzop``, ``bzip2``, ``xz``, ``zstd``\n (optional, for unpacking compressed ``/boot/vmlinuz``)\n\nThe ``rst2man`` program (from ``docutils``) should be used to convert\nthe ``mkdepthcharge.rst`` and ``depthchargectl.rst`` files to manual\npages. However, this is not automated here and has to be done manually.\n\nThis project (or at least ``depthchargectl``) is meant to be integrated\ninto your operating system by its maintainers, and the best way to\ninstall it is through your OS' package manager whenever possible.\n\n\nDebian\n------\nAn official `depthcharge-tools Debian package`_ is available upstream,\nsince Debian 12 (bookworm). You can install it like any other package::\n\n $ sudo apt install depthcharge-tools\n\nIt includes the necessary system hooks and services to make and keep\nyour Chromebook bootable, enabled by default. These however do not\ntrigger on the depthcharge-tools installation, but on kernel and\ninitramfs changes. To trigger these hooks manually, run::\n\n $ sudo update-initramfs -u\n\n.. _depthcharge-tools Debian package: https://packages.debian.org/sid/depthcharge-tools\n\n\nAlpine Linux\n------------\nThanks to the efforts in supporting `postmarketOS on ChromeOS Devices`_,\nthere is an official `depthcharge-tools package for Alpine Linux`_. You\nshould be able to install it as::\n\n $ sudo apk add depthcharge-tools\n\nHowever, this doesn't include any system hooks or services to keep your\nChromebook bootable.\n\n.. _postmarketOS on ChromeOS Devices: https://wiki.postmarketos.org/wiki/Chrome_OS_devices\n.. _depthcharge-tools package for Alpine Linux: https://pkgs.alpinelinux.org/package/edge/testing/x86/depthcharge-tools\n\n\nPip\n---\nPython binary wheels are uploaded to PyPI_, and it should be possible to\ninstall the python package using `pip`. However, this does not install\nthe manual pages, bash/zsh completions, systemd/init.d service files,\nand OS-specific kernel/initramfs hooks.\n\nYou can install in `--user` mode, but this makes it quite hard to use\n`depthchargectl` as root. As root privileges are necessary to manipulate\nsystem block devices this limits you a bit::\n\n $ pip install --user depthcharge-tools\n\nAlthough inadvisable, you can install as root to overcome that caveat.\nAlternatively, see the `PYTHONPATH` hack in one of the later sections.\n\n.. _PyPI: https://pypi.org/project/depthcharge-tools/\n\n\nConfiguration\n=============\nYou can configure depthcharge-tools with the |CONFIG_FILE| file, or by\nputting similar fragments in the |CONFIGD_DIR| directory. See the\nconfig.ini_ file for the built-in default configuration.\n\nSettings in the ``[depthcharge-tools]`` section are the global defaults\nfrom which all commands inherit. Other than that, config sections have\ninheritence based on their names i.e. those in the form of ``[a/b/c]``\ninherit from ``[a/b]`` which also inherits from ``[a]``. Each subcommand\nreads its config from such a subsection.\n\nCurrently the following configuration options are available::\n\n [depthcharge-tools]\n enable-system-hooks: Write/remove images on kernel/initramfs changes\n vboot-keyblock: The kernel keyblock file for verifying and signing images\n vboot-private-key: The private key (.vbprivk) for signing images\n vboot-public-key: The public key for (.vbpubk) verifying images\n\n [depthchargectl]\n board: Codename of a board to build and check images for\n ignore-initramfs: Do not include an initramfs in the image\n images-dir: Directory to store built images\n kernel-cmdline: Kernel commandline parameters to use\n zimage-initramfs-hack = How to support initramfs on x86 boards\n\nFor longer explanations check the manual pages of each command for\noptions named the same as these.\n\n.. |CONFIG_FILE| replace:: ``/etc/depthcharge-tools/config``\n.. |CONFIGD_DIR| replace:: ``/etc/depthcharge-tools/config.d``\n.. _config.ini: https://github.com/alpernebbi/depthcharge-tools/blob/master/depthcharge_tools/config.ini\n\n\nInstallation for development\n============================\nIf you want to use development versions, you can clone this repository\nand install using pip::\n\n $ pip3 install --user -e /path/to/depthcharge-tools\n\nHopefully, you should be able to use depthchargectl with just that::\n\n $ depthchargectl build --output depthcharge.img\n Building depthcharge image for board 'Samsung Chromebook Plus' ('kevin').\n Built depthcharge image for kernel version '5.10.0-6-arm64'.\n depthchargectl.img\n\nMost ``depthchargectl`` functionality needs root as it handles disks and\npartitions, and you need special care while invoking as root::\n\n $ depthchargectl() {\n sudo PYTHONPATH=/path/to/depthcharge-tools \\\n python3 -m depthcharge_tools.depthchargectl \"$@\"\n }\n\n $ depthchargectl list /dev/mmcblk0\n S P T PATH\n 1 2 0 /dev/mmcblk0p2\n 1 1 0 /dev/mmcblk0p4\n 0 0 15 /dev/mmcblk0p6\n\nOr you can add a similar invocation to the /usr/local/bin files, so that\nit's available to both normal users and root::\n\n $ sudo tee /usr/local/bin/depthchargectl <<EOF\n #!/bin/sh\n export PYTHONDONTWRITEBYTECODE=1\n export PYTHONPATH=/path/to/depthcharge-tools\n exec python3 -m depthcharge_tools.depthchargectl \"\\$@\"\n EOF\n\n $ sudo chmod +x /usr/local/bin/depthchargectl\n\n\nLicense\n=======\nCopyright (C) 2019-2023 Alper Nebi Yasak <alpernebiyasak@gmail.com>\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 2 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see <https://www.gnu.org/licenses/>\n\nSee COPYRIGHT and LICENSE files for full copyright information.\n",
"bugtrack_url": null,
"license": "GPL2+",
"summary": "Tools to manage the Chrome OS bootloader",
"version": "0.6.2",
"project_urls": {
"Homepage": "https://github.com/alpernebbi/depthcharge-tools"
},
"split_keywords": [
"chromeos",
"chromiumos",
"depthcharge",
"vboot",
"vbutil_kernel"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3af586ed28912db7761c1a85f815cd4b379a1ba0be1d38a7cb1c56513a6ea812",
"md5": "d519ca4e3083f123e356dab0dd5e8749",
"sha256": "460bbdad52b443acbb06d91c38eb8493937b2b520637699dd6049a0215f9b9d3"
},
"downloads": -1,
"filename": "depthcharge_tools-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d519ca4e3083f123e356dab0dd5e8749",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 87830,
"upload_time": "2023-06-30T15:27:27",
"upload_time_iso_8601": "2023-06-30T15:27:27.085595Z",
"url": "https://files.pythonhosted.org/packages/3a/f5/86ed28912db7761c1a85f815cd4b379a1ba0be1d38a7cb1c56513a6ea812/depthcharge_tools-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e3da398343cda5f7d197fa90828e7943a5c552ef9abc17a6a88a913218eb265",
"md5": "53dc3b6f037fc6a3ccc977c03d32b4f2",
"sha256": "0e5e79eecaaa50381a8ae2e47a203582e96698d29e8aa4926caf853dc5c4f1af"
},
"downloads": -1,
"filename": "depthcharge-tools-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "53dc3b6f037fc6a3ccc977c03d32b4f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 94378,
"upload_time": "2023-06-30T15:27:28",
"upload_time_iso_8601": "2023-06-30T15:27:28.933123Z",
"url": "https://files.pythonhosted.org/packages/0e/3d/a398343cda5f7d197fa90828e7943a5c552ef9abc17a6a88a913218eb265/depthcharge-tools-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-30 15:27:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alpernebbi",
"github_project": "depthcharge-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "depthcharge-tools"
}
JSON
