HackENS/liminix-fork
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

improve doc for outputs and hardware

Browse source 
Changed my mind about "installer" as a first-class concept, at least
in the current implementation. Not every documented output is an
installer
This commit is contained in:
Daniel Barlow 2023-11-12 17:15:58 +00:00
parent 262efaabe6
commit f61e737b54
11 changed files with 133 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
devices/belkin-rt3200/default.nix
View file

@ -6,17 +6,31 @@
This device is based on a 64 bit Mediatek MT7622 ARM platform,
and is "work in progress" in Liminix.
The factory flash image contains ECC errors that make it incompatible
with Liminix: you need to use the `OpenWrt UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to rewrite the partition layout before
you can flash Liminix onto it (or even use it with "tftpboot",
if you want the wireless to work).
.. note:: The factory flash image contains ECC errors that make it
incompatible with Liminix: you need to use the `OpenWrt
UBI Installer <https://github.com/dangowrt/owrt-ubi-installer>`_ to
rewrite the partition layout before you can flash
Liminix onto it (or even use it with
:ref:`system-outputs-tftpboot`, if you want the wireless
to work).
Hardware summary
================
- MediaTek MT7622BV (1350MHz)
- 128MB NAND flash
- 512MB RAM
- b/g/n wireless using MediaTek MT7622BV (MT7615E driver)
- a/n/ac/ax wireless using MediaTek MT7915E
'';
Installation
============
Installation is currently a manual process (you need a :ref:`serial <serial>` conection and
TFTP) following the instructions at :ref:`system-outputs-ubimage`
'';
system = {
crossSystem = {

40
devices/gl-ar750/default.nix
View file

@ -1,4 +1,4 @@
rec {
{
system = {
crossSystem = {
config = "mips-unknown-linux-musl";
@ -13,6 +13,9 @@ rec {
GL.iNet GL-AR750
****************
Hardware summary
================
The GL-AR750 "Creta" travel router features:
- QCA9531 @650Mhz SoC
@ -22,28 +25,32 @@ rec {
- 16MB NOR Flash
- supported in OpenWrt by the "ath79" SoC family
As with many GL.iNet devices, the stock vendor firmware
is a fork of OpenWrt, meaning that the plain binary
``firmware.bin`` that Liminix builds can be flashed using the
vendor web UI and the U-Boot emergency "unbrick" routine
The GL-AR750 has two distinct sets of wifi hardware. The 2.4GHz
radio is part of the QCA9531 SoC, i.e. it's on the same silicon as
the CPU, the Ethernet, the USB etc. The device is connected to the
host via AHB, the "Advanced High-Performance Bus" and it is
supported in Linux using the ath9k driver. The 5GHz support, on the
other hand, is provided by a QCA9887 PCIe (PCI embedded) WLAN chip:
I haven't looked closely at the router innards to see if this is
actually physically a separate board that could be unplugged, but
as far as Linux is concerned it behaves as one. This is
host via `AHB <https://en.wikipedia.org/wiki/Advanced_Microcontroller_Bus_Architecture>`_ and it is
supported in Linux using the ath9k driver. 5GHz wifi
is provided by a QCA9887 PCIe (PCI embedded) WLAN chip,
supported by the ath10k driver.
Installation
============
As with many GL.iNet devices, the stock vendor firmware
is a fork of OpenWrt, meaning that the binary created by
:ref:`system-outputs-flashimage` can be flashed using the
vendor web UI or the U-Boot emergency "unbrick" routine.
For flashing from an existing Liminix system (we believe that) it
is necessary to first boot into a :ref:`system-outputs-kexecboot`
system, otherwise you'll be overwriting flash partitions while
they're in use - and that might not end well.
Vendor web page: https://www.gl-inet.com/products/gl-ar750/
OpenWrt web page: https://openwrt.org/toh/gl.inet/gl-ar750
'';
installer = "flashimage";
module = {pkgs, config, ... }:
let
@ -95,7 +102,7 @@ rec {
FEATURE_DD_IBS_OBS = "y"; # ath10k_cal_data needs skip_bytes,fullblock
};
hardware = {
defaultOutput = installer;
defaultOutput = "flashimage";
loadAddress = "0x80060000";
entryPoint = "0x80060000";
flash = {
@ -145,9 +152,14 @@ rec {
url = "https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.15.71.tar.gz";
hash = "sha256-yhO2cXIeIgUxkSZf/4aAsF11uxyh+UUZu6D1h92vCD8=";
};
# Mainline linux 5.19 doesn't have device-tree support for
# this device or even for the SoC, so we use the extensive
# OpenWrt kernel patches
extraPatchPhase = ''
${openwrt.applyPatches.ath79}
'';
config = {
ATH79 = "y";
PCI = "y";

11
devices/gl-mt300a/default.nix
View file

@ -25,6 +25,17 @@
- assuming we want to use the wireless - we need to build MTD
support into the kernel even if we're using TFTP root.
Installation
============
The stock vendor firmware is a fork of OpenWrt, meaning that the
binary created by :ref:`system-outputs-flashimage` can be flashed
using the vendor web UI or the U-Boot emergency "unbrick" routine.
For flashing from an existing Liminix system (we think) it
is necessary to first boot into a :ref:`system-outputs-kexecboot`
system, otherwise you'll be overwriting flash partitions while
they're in use - and that might not end well.
Vendor web page: https://www.gl-inet.com/products/gl-mt300a/

20
devices/gl-mt300n-v2/default.nix
View file

@ -13,10 +13,22 @@
GL.iNet GL-MT300N-v2
********************
The GL-MT300N-v2 "Mango" is is very similar to the MT300A, but is
based on MT7628 instead of MT7620. It's also marginally cheaper
and comes in a yellow case not a blue one. It's different again
to the v1, which has only half the RAM.
The GL-MT300N-v2 "Mango" is is very similar to the :ref:`MT300A <GL.iNet GL-MT300A>, but is
based on the MT7628 chipset instead of MT7620. It's also marginally cheaper
and comes in a yellow case not a blue one. Be sure your device is
v2 not v1, which is a different animal and has only half as much RAM.
Installation
============
The stock vendor firmware is a fork of OpenWrt, meaning that the
binary created by :ref:`system-outputs-flashimage` can be flashed
using the vendor web UI or the U-Boot emergency "unbrick" routine.
For flashing from an existing Liminix system (we think) it
is necessary to first boot into a :ref:`system-outputs-kexecboot`
system, otherwise you'll be overwriting flash partitions while
they're in use - and that might not end well.
Vendor web page: https://www.gl-inet.com/products/gl-mt300n-v2/

2
doc/hardware.nix
View file

@ -16,7 +16,7 @@ let
:ref:`system-outputs-${d.installer}`
''
else "";
in (d'.description + installer))
in d'.description)
devices;
in
writeText "hwdoc" ''

2
doc/index.rst
View file

@ -12,7 +12,7 @@ Liminix
development
modules
hardware
installers
outputs
Indices and tables

8
doc/outputs.rst
View file

@ -1,12 +1,12 @@
Outputs
#######
Liminix *outputs* are artefacts that can be installed or run somehow
on a target device, or "installers" which run on a target device
to perform the installation.
Liminix *outputs* are artefacts that can be installed somehow on a
target device, or "installers" which run on the target device to
perform the installation.
There are different outputs because different target devices need
different artefacts or have different ways to get that artefact
different artefacts, or have different ways to get that artefact
installed. The options available for a particular device are described in
the section for that device.

16
doc/parse-options-outputs.fnl
View file

@ -2,10 +2,18 @@
;; (local { : view } (require :fennel))
(local outputs (collect [k v (ipairs arg)]
(values v true)))
(fn output? [option]
(match option.loc
["system" "outputs" & _] true
_ false))
(each [_ option (ipairs (yaml.load (io.read "*a")))]
(when (. outputs option.name)
(fn sorted-options [options]
(table.sort
options
(fn [a b] (< a.name b.name)))
options)
(each [_ option (ipairs (sorted-options (yaml.load (io.read "*a"))))]
(when (and (output? option) (not option.internal))
(print (.. ".. _" (string.gsub option.name "%." "-") ":") "\n")
(print option.description)))

18
modules/outputs.nix
View file

@ -17,26 +17,42 @@ in
];
options = {
system.outputs = {
# the convention here is to mark an output as "internal" if
# it's not a complete system (kernel plus userland, or installer)
# but only part of one.
kernel = mkOption {
type = types.package;
internal = true;
description = ''
kernel
******
Kernel vmlinux file (usually ELF)
'';
};
dtb = mkOption {
type = types.package;
internal = true;
description = ''
dtb
***
Compiled device tree (FDT) for the target device
'';
};
uimage = mkOption {
type = types.package;
internal = true;
description = ''
uimage
******
Combined kernel and FDT in uImage (U-Boot compatible) format
'';
};
manifest = mkOption {
type = types.package;
internal = true;
description = ''
Debugging aid. JSON rendition of config.filesystem, on
which can run "nix-store -q --tree" on it and find
@ -45,10 +61,10 @@ in
};
rootfs = mkOption {
type = types.package;
internal = true;
description = ''
root filesystem (squashfs or jffs2) image
'';
internal = true;
};
};
};

19
modules/outputs/ubimage.nix
View file

@ -20,18 +20,17 @@ in {
ubimage
*******
First-time installation of a UBIFS Liminix system presently can only
be done from the U-Boot command line (or from a ramdisk-based recovery
system: see "kexecboot" but we don't have detailed instructions for
this process yet).
This output provides a UBIFS filesystem image and a small U-Boot script
to make the manual installation process very slightly simpler. You will
need a serial connection and a network connection to a TFTP server
containing the filesystem image it creates.
These steps were tested on a Belkin RT3200 (also known as Linksys
E8450). Other devices may be set up differently, so use them as
inspiration and don't just paste them blindly. Consult the Liminix
manual for how to connect a serial cable to your device and get into
U-Boot
.. warning:: These steps were tested on a Belkin RT3200 (also known as
Linksys E8450). Other devices may be set up differently,
so use them as inspiration and don't just paste them
blindly.
1) determine which MTD device is being used for UBI and the partition name:
1) determine which MTD device is being used for UBI, and the partition name:
.. code-block:: console

18
modules/tftpboot.nix
View file

@ -17,11 +17,27 @@ in {
tftpboot = mkOption {
type = types.package;
description = ''
Directory containing files needed for TFTP booting
tftpboot
********
This output is intended for developing on a new device.
It assumes you have a serial connection and a
network connection to the device and that your
build machine is running a TFTP server.
The output is a directory containing kernel and
root filesystem image, and a script :file:`boot.scr` of U-Boot
commands that will load the images into memory and
run them directly,
instead of first writing them to flash. This saves
time and erase cycles.
It uses the Linux `phram <https://github.com/torvalds/linux/blob/master/drivers/mtd/devices/phram.c>`_ driver to emulate a flash device using a segment of physical RAM.
'';
};
boot-scr = mkOption {
type = types.package;
internal = true;
description = ''
U-Boot commands to load and boot a kernel and rootfs over TFTP.
Copy-paste into the device boot monitor