8000 Add bootstrap scripts and simplify GUIDE.md by fstanis · Pull Request #21 · fstanis/chuwi-minibook · GitHub
[go: up one dir, main page]

Skip to content

Add bootstrap scripts and simplify GUIDE.md - #21

Merged
fstanis merged 10 commits into
mainfrom
fork
Sep 17, 2026
Merged

fstanis merged 10 commits into
mainfrom
fork

Conversation

@fstanis
@fstanis fstanis commented Sep 13, 2026
Copy link
Copy Markdown
Owner

This upstrems the great work @4lun made in the Ubuntu fork, notably the boostrap script. It also writes an Arch version of the same script, which overall makes the installation much simpler on both distros.

4lun and others added 8 commits September 13, 2026 18:20
The script assumed Limine and mkinitcpio. Detect Limine or GRUB for the kernel
cmdline, and mkinitcpio, dracut or initramfs-tools for bundling the patched VBT,
so it also works on Debian and Ubuntu. Locate i915_vbt by glob rather than
hardcoding the PCI address, and make vbt_patch's CC overridable.
Installs the build dependencies, acpi_call, the four DKMS modules and the
patched iio-sensor-proxy, then adds the kernel cmdline arguments. Pins the
distro iio-sensor-proxy package so an upgrade cannot restore it and shadow the
fork, and bundles the goodix config into the initramfs, without which the driver
probes before the real root exists and falls back to its built-in config.
Idempotent, and each stage can be run on its own.
Both docs said flickering or colour banding after a VBT patch means the panel
does not support the rate. The panel has one timing descriptor, so patching
replaces the old rate rather than adding one, and a saved display config still
pinning the pre-patch rate makes the compositor fall back to a
driver-synthesised mode. Programmed for one rate and scanned out at another
produces identical symptoms, and immediately after patching the saved config is
guaranteed stale, so it is the more likely cause of the two.
Three fixes. The documented panel_orientation=right is not a value the DRM
parser accepts (only normal, upside_down, left_side_up, right_side_up, verified
against the tokens in the kernel image) and unrecognised values are ignored
silently rather than reported.

The section also said a compositor consuming orientation events needs nothing on
the kernel side. That holds for the desktop but not for an encrypted root, whose
passphrase prompt is drawn from the initramfs before any compositor exists. Note
which layer covers which surface, and that on GNOME/Wayland the kernel rotation
composes with the proxy rather than stacking.

Finally, record that stock GRUB cannot rotate its menu at all, checked against
2.14, and what it would take.
fbcon=rotate: is ignored under i915's fbdev emulation: it leaves fbcon/rotate at
0 and the console keeps the orientation DRM derives from panel_orientation,
which can land a quarter or half turn out. Writing rotate_all at runtime does
work, so set it from tmpfiles.d and drop the cmdline argument that only implied
a fix.

Expect to find the right value by trying all four rather than deriving it: they
do not compose additively, and fbcon/rotate reports the current console rather
than a global, so readings vary depending on which VT is active.
A cold boot is not a sufficient test of a patched rate. The DSI link is brought
up from scratch at boot but re-trained on resume, so a panel that is marginal at
the requested clock can run for hours and then fail on the first suspend, with
roughly half the scanlines missing and horizontal smearing on the rest.

The failure is easy to misread. The driver logs nothing at all, and because it
is not the stale-config problem, the mode really is the patched one, so that
check passes and points the wrong way. Forcing a modeset does not clear it; only
reverting does, and prolonged operation in that state can leave temporary image
retention on the panel.

Require a suspend cycle before considering a rate proven, and stop the bootstrap
script signing off by recommending a rate it deliberately does not apply.
…e states, note fbcon=rotate priority, and remove obsolete compositor proxy warnings.

- Add initramfs-tools hook to bundle_goodix_firmware to fix missing firmware; unify script formatting, variables, and grep usage.
- Fix vbt_patch Makefile to enforce clang default by evaluating CC origin instead of using ?=.
@fstanis fstanis assigned 4lun and unassigned 4lun Sep 14, 2026
@fstanis
fstanis requested review from 4lun and a lite review from Copilot September 15, 2026 22:32
Copilot AI left a comment
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved bootstrap, bootloader, and initramfs issues can prevent reliable installation or updates.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds Ubuntu and Arch bootstrap scripts, expands VBT tooling, and simplifies installation documentation.

Changes:

  • Adds distro-specific dependency and setup workflows.
  • Extends VBT handling for bootloaders and initramfs tools.
  • Updates guides, status checks, and build behavior.
File summaries
File Reviewed change Final review notes
vbt_patch/Makefile Defaults builds to Clang. No final comments.
tools/update-vbt-clock.sh Adds bootloader/initramfs detection and revert support. Critical (1 vote): preserve or validate ownership of the dracut drop-in. Moderate (3 votes): use distro-appropriate GRUB config generation. Moderate (1 vote): support Fedora’s GRUB command-line variable. Nit (2 votes): update revert documentation.
tools/gpu-status.sh Updates advanced-guide warning links. No final comments.
tools/check-status.sh Scopes DKMS checks to the running kernel. No final comments.
tools/bootstrap-ubuntu.sh Adds Ubuntu/Debian automated setup. Moderate (2 votes): install libdrm-dev. Moderate (1 vote): validate the GRUB command-line variable before modifying it.
tools/bootstrap-arch.sh Adds Arch automated setup. Critical (1 vote): use the glib2 package name instead of glib2-devel.
README.md Links standard and advanced guides. No final comments.
LICENSE.md Includes the advanced guide in documentation licensing. No final comments.
iio-sensor-proxy/Makefile Cleans Arch package builds. No final comments.
GUIDE.md Simplifies standard installation instructions. No final comments.
GUIDE-ADVANCED.md Adds manual installation and advanced configuration details. Nit (1 vote): document Goodix firmware bundling after module installation.
docs/vbt-patch.md Documents refresh-rate risks and VBT workflows. Nit (1 vote): update supported bootloaders, initramfs tools, and the VBT path description.
docs/thermald.md Updates guide anchors. No final comments.
docs/iio-sensor-proxy.md Adds desktop integration guidance. No final comments.
Review details

Suppressed comments (9)

GUIDE-ADVANCED.md:57

  • This manual sequence stops after make install, but the bootstrap scripts perform an additional initramfs-bundling step for goodix_ts. Following these instructions manually leaves goodix_9110_cfg.bin only on the root filesystem, so the driver can silently use its built-in configuration during early boot. Add generator-specific Goodix firmware bundling instructions after the module installs.
Each installs the same way:

cd modules/
sudo make install && sudo make enable

docs/vbt-patch.md:68

  • The script now detects GRUB and dracut/initramfs-tools, but the support statement later in this document still says it only supports Limine and mkinitcpio (docs/vbt-patch.md:188-190) and describes the old hard-coded VBT path. Update that reference while documenting this broader workflow so users do not incorrectly conclude their setup is unsupported.
> **Treat the refresh-rate patch as an experiment, not a default.** Panels vary
> between units, and a rate can run cleanly for hours from a cold boot and still
> fail on the first suspend/resume, taking a revert and a reboot to clear and
> leaving temporary image retention behind. Suspend-test before relying on it,
> and see "What rate to use" below. This is why the patch is not part of the
> `bootstrap-ubuntu.sh` / `bootstrap-arch.sh` scripts.

tools/bootstrap-arch.sh:200

  • The rebuild choice is based only on which commands are installed, not on the initramfs generator actually used to boot. On an Arch system that retains mkinitcpio/limine-mkinitcpio while using dracut, this always rebuilds the mkinitcpio images, leaving the Goodix firmware absent from the active dracut images. Detect the generator once and use that result for both configuration and rebuilding.
rebuild_initramfs() {
  if command -v limine-mkinitcpio &>/dev/null; then
    limine-mkinitcpio
  elif command -v mkinitcpio &>/dev/null; then
    mkinitcpio -P
  else
    dracut -f --regenerate-all
  fi

tools/bootstrap-ubuntu.sh:182

  • This chooses the Goodix initramfs integration from the existence of /etc/dracut.conf.d, while rebuild_initramfs() prefers update-initramfs whenever that command is installed. If both packages are present, this writes an unused dracut config and never installs the firmware through the initramfs-tools hook, so the touchscreen falls back to its built-in configuration. Select the generator using the same precedence as the rebuild function.
  if [[ -d /etc/dracut.conf.d ]]; then
    write_dracut_goodix_conf
  elif [[ -d /etc/initramfs-tools/hooks ]]; then
    write_initramfs_tools_goodix_hook

tools/bootstrap-ubuntu.sh:224

  • Unlike the Arch and VBT command-line paths, this sed is not preceded by a check that GRUB_CMDLINE_LINUX_DEFAULT exists. If /etc/default/grub is valid but omits that variable, sed silently changes nothing while the script reports the argument as added and continues. Validate the key (and the expected quoted format) before setting changed=1.
    sed -i "/^GRUB_CMDLINE_LINUX_DEFAULT=/s|\"$| ${arg}\"|" "${GRUB_CONF}"

tools/update-vbt-clock.sh:161

  • detect_initramfs has already selected dracut when this branch runs, but this code chooses update-initramfs merely because that command happens to exist. On systems with both generators installed, the script writes 90-vbt.conf for dracut and then rebuilds with the other generator, so the VBT is omitted. Dispatch on ${INITRAMFS} instead of probing for a different command here.
    dracut | initramfs-tools)
      if command -v update-initramfs &>/dev/null; then
        update-initramfs -u -k all
      else
        dracut -f --regenerate-all

tools/update-vbt-clock.sh:177

  • --revert has no record of which files or arguments this invocation created, so it unconditionally deletes /lib/firmware/vbt and removes the kernel argument from both bootloader configs. A pre-existing VBT or manually configured i915.vbt_firmware=vbt is valid input to this command and will be destroyed; this also contradicts docs/vbt-patch.md:185-186, which says the firmware remains. Track ownership/backups and only undo changes made by this tool.
  rm -f "${FIRMWARE_VBT}" "${DRACUT_CONF}"

  if [[ -f "${LIMINE_CONF}" ]]; then
    sed -i "s| ${CMDLINE_ARG}||g" "${LIMINE_CONF}"
  fi

tools/update-vbt-clock.sh:116

  • The initramfs-tools branch does not add /lib/firmware/vbt to any initramfs-tools configuration or hook. Unlike the mkinitcpio/dracut branches, the stock hooks do not reliably include this arbitrary VBT filename, so i915.vbt_firmware=vbt will fall back to the BIOS VBT after reboot and the requested rate is silently not applied. Add a dedicated initramfs-tools hook and remove it during revert.
    initramfs-tools)
      # initramfs-tools pulls /lib/firmware in via the stock hooks.
      ;;

tools/update-vbt-clock.sh:141

  • The GRUB branch only accepts GRUB_CMDLINE_LINUX_DEFAULT, but Fedora's standard /etc/default/grub uses GRUB_CMDLINE_LINUX instead. Since the advanced guide documents Fedora's GRUB/dracut workflow, this guard exits before adding i915.vbt_firmware=vbt on Fedora, so the patched VBT is never selected. Support the distro's actual command-line variable (and append to that key) rather than requiring the Ubuntu-specific name.
      if ! grep -qE '^GRUB_CMDLINE_LINUX_DEFAULT=' "${GRUB_CONF}"; then
        echo "Could not find GRUB_CMDLINE_LINUX_DEFAULT in ${GRUB_CONF}" >&2
        exit 1
      fi
      sed -i "/^GRUB_CMDLINE_LINUX_DEFAULT=/s|\"$| ${CMDLINE_ARG}\"|" \
  • Files reviewed: 15/16 changed files
  • Comments generated: 5
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread tools/bootstrap-arch.sh Resolved
Comment thread tools/update-vbt-clock.sh Resolved
Comment thread tools/bootstrap-ubuntu.sh Resolved
Comment thread tools/update-vbt-clock.sh Resolved
Comment thread tools/update-vbt-clock.sh Resolved
iio-sensor-proxy has required libdrm since panel orientation detection
landed in #13, but the apt list predates that and nothing in it pulls
libdrm-dev in transitively, so on a clean install meson setup failed
with: Dependency "libdrm" not found.
initramfs-tools only copies firmware a module declares in modinfo, and
i915 doesn't declare "vbt", so the patched VBT never made it into the
initramfs there. Write a hook for it like the goodix one, and remove it
on revert. Ubuntu 26.04 was unaffected: its update-initramfs is a dracut
shim.

update-grub doesn't exist on Arch, so fall back to grub-mkconfig as
bootstrap-arch.sh does.

Docs updated for the current revert behaviour and supported setups.
@4lun 4lun left a comment
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@fstanis seems good to me, thanks for including the changes, I'll leave to you for merge 👍

Note: stacked a few small changes to address bits raised by copilot, plus a bit for initramfs-tools

@fstanis
fstanis merged commit 1aa5895 into main Sep 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

0