unified iomem=relaxed instructions

Signed-off-by: Leah Rowe <info@minifree.org>

site/devmem.md

@@ -0,0 +1,79 @@
+---
+title: Disabling /dev/mem protections
+x-toc-enable: true
+...
+
+This section applies to any program that makes use of lower memory
+below 1MB. This applies to `flashprog` and `dell-flash-unlock` plus any other
+tool that uses lower memory and/or port I/O
+
+Port I/O is up to you, BUT it is recommended that you re-disable lower memory
+access once you no longer need it, as this is a useful security layer against
+any wrongful operations that you may later inadvertently run as root.
+
+Also disable SecureBoot
+=======================
+
+If you're using a UEFI setup, it's probably because you're using
+a latter Intel platform and want to flash Canoeboot internally, from
+the factory firmware to Canoeboot.
+
+If the factory firmware implements UEFI, and this is how you boot when
+using the factory firmware, please ensure that *SecureBoot* is disabled,
+because it will interfere with lower memory accesses if left enabled.
+
+FLASH ERRORS (and workarounds)
+=======================
+
+**NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog)
+now, which is a fork of flashrom.**
+
+This section relates to installing Canoeboot on supported targets.
+
+Right out of the gate, some users may experience errors with flashprog when
+using the internal programmer. They are:
+
+/dev/mem access error
+---------------------
+
+NOTE: if running `flashprog -p internal` for software based flashing, and you
+get an error related to `/dev/mem` access, you should reboot with
+`iomem=relaxed` kernel parameter before running flashprog, or use a kernel that
+has `CONFIG_STRICT_DEVMEM` not enabled.
+
+On NetBSD and OpenBSD systems, the equivalent to `iomem=relaxed` in this case
+is `kernel.securelevel=-1`; see [NetBSD securelevel
+manual](https://wiki.netbsd.org/tutorials/kernel_secure_levels/)
+and [OpenBSD securelevel manual](https://man.openbsd.org/securelevel).
+
+ERROR: Could not get I/O privileges
+------------------------------------
+
+Error message: `ERROR: Could not get I/O privileges (Function not implemented)`
+
+If you get this while running `flashprog -p internal -w filename.rom` (or any
+internal flash operation), note: flashprog heavily uses ioperm/iopl functions
+to operate the internal flasher, at least on x86 machines.
+
+See: <https://lwn.net/Articles/804143/>
+
+Yeah, just enable `CONFIG_X86_IOPL_IOPERM` in your Linux kernel. This is
+a *build-time* option, so you must re-compile your kernel, or find a build that
+has this option enabled (IOPL emulation). Many default kernel configurations
+now disable this option.
+
+Here's a handy-dandy guide for building a kernel from source:
+<https://www.cyberciti.biz/tips/compiling-linux-kernel-26.html>
+
+**BSD users:** On OpenBSD and NetBSD if you get similar errors, note that it
+should work here, but you need to boot with `kern.securelevel=-1`.
+See: [NetBSD securelevel manual](https://wiki.netbsd.org/tutorials/kernel_secure_levels/)
+and [OpenBSD securelevel manpage](https://man.openbsd.org/securelevel).
+
+Otherwise, if you get such errors, it may just be that you're not root. You
+must run flashprog as root, at least to use the internal flasher (using external
+USB flashing dongles doesn't normally require root).
+
+NOTE: BSD kernels seem to still enable IOPL by default. However, many modern
+Linux setups disable it by default these days, so it may be in teh future
+that most users will start needing to compile their own kernels. (go BSD!)

site/docs/install/dell_internal.md

@@ -7,6 +7,14 @@ Make sure SecureBoot is disabled, if you're running a UEFI-based Latitude.
 Other steps also required, described on this page and in the `README.md`
 file included with `dell-flash-unlock`.
 
+Disable security before flashing
+================================
+
+Before internal flashing, you must first disable `/dev/mem` protections. Make
+sure to re-enable them after you're finished.
+
+See: [Disabling /dev/mem protection](devmem.md)
+
 Internal flashing
 =================
 
@@ -14,29 +22,8 @@ You can simply boot GNU+Linux or BSD, on the Dell Latitude you wish to flash, an
 run `flashprog` from there, for Canoeboot installation. Certain other steps
 are also required, documented in the steps below:
 
-Flashing from BSD
------------------
-
-Basically identical to GNU+Linux, except that you must
-set `kern.securelevel` to -1 on boot, which is equivalent to `iomem=relaxed`
-under GNU+Linux, for this purpose.
-
-The `dell-flash-unlock` utility will compile and run just fine. It has been
-tested on OpenBSD, NetBSD and FreeBSD. With this in mind, simply follow the
-GNU+Linux instrucctions but adapt accordingly.
-
-If unsure, just boot a live GNU+Linux distro via USB and run it all there.
-
-Flashing from GNU+Linux
--------------------
-
-MAKE SURE you boot with this Linux kernel parameter: `iomem=relaxed` - this
-disables memory protections, permitting `/dev/mem` access needed by flashprog.
-The flash is memory mapped and flashprog accesses it via `/dev/mem`.
-
 You can flash Canoeboot directly from the vendor (Dell) BIOS, without taking
-the machine apart. It can be done entirely from GNU+Linux. It will probably also
+the machine apart. It can be done entirely from GNU+Linux or BSD.
-work on BSD systems, but it has only been testing on GNU+Linux thus far.
 
 **NOTE (15 October 2023): The util is now called `dell-flash-unlock`, but it
 was previously called `e6400-flash-unlock`. Links have been updated.**

site/docs/install/ich9utils.md

@@ -202,10 +202,7 @@ Read on for more information. Use the `ro` files mentioned below, and your
 flash will be read-only in software (you can still externally re-flash and read
 the contents of flash).
 
-For ease of use, Canoeboot provides ROMs that are read-write by default. In
+For ease of use, Canoeboot provides ROMs that are read-write by default.
-practise, you can boot a GNU+Linux kernel with access to lower memory disabled
-which will make software re-flashing impossible (unless you reboot with such
-memory protections disabled, e.g. `iomem=relaxed` kernel parameter).
 
 ICH9 deblob utility {#ich9deblob}
 ===================

site/docs/install/index.md

@@ -11,52 +11,13 @@ now, as of 3 May 2024, which is a fork of flashrom.**
 
 This section relates to installing canoeboot on supported targets.
 
-FLASH ERRORS (and workarounds)
+**Disable security before flashing**
-+=======================
+================================
 
-Right out of the gate, some users may experience errors with flashprog when
+**Before internal flashing, you must first disable `/dev/mem` protections. Make
-using the internal programmer. They are:
+sure to re-enable them after you're finished.**
 
-/dev/mem access error
+**See: [Disabling /dev/mem protection](devmem.md)**
----------------------
-
-NOTE: if running `flashprog -p internal` for software based flashing, and you
-get an error related to `/dev/mem` access, you should reboot with
-`iomem=relaxed` kernel parameter before running flashprog, or use a kernel that
-has `CONFIG_STRICT_DEVMEM` not enabled.
-
-On NetBSD and OpenBSD systems, the equivalent to `iomem=relaxed` in this case
-is `kernel.securelevel=-1`; see [NetBSD securelevel
-manual](https://wiki.netbsd.org/tutorials/kernel_secure_levels/)
-and [OpenBSD securelevel manual](https://man.openbsd.org/securelevel).
-
-ERROR: Could not get I/O privileges
-------------------------------------
-
-Error message: `ERROR: Could not get I/O privileges (Function not implemented)`
-
-If you get this while running `flashprog -p internal -w filename.rom` (or any
-internal flash operation), note: flashprog heavily uses ioperm/iopl functions
-to operate the internal flasher, at least on x86 machines.
-
-See: <https://lwn.net/Articles/804143/>
-
-Yeah, just enable `CONFIG_X86_IOPL_IOPERM` in your Linux kernel. This is
-a *build-time* option, so you must re-compile your kernel, or find a build that
-has this option enabled (IOPL emulation). Many default kernel configurations
-now disable this option.
-
-Here's a handy-dandy guide for building a kernel from source:
-<https://www.cyberciti.biz/tips/compiling-linux-kernel-26.html>
-
-**BSD users:** On OpenBSD and NetBSD if you get similar errors, note that it
-should work here, but you need to boot with `kern.securelevel=-1`.
-See: [NetBSD securelevel manual](https://wiki.netbsd.org/tutorials/kernel_secure_levels/)
-and [OpenBSD securelevel manpage](https://man.openbsd.org/securelevel).
-
-Otherwise, if you get such errors, it may just be that you're not root. You
-must run flashprog as root, at least to use the internal flasher (using external
-USB flashing dongles doesn't normally require root).
 
 PRECAUTIONS
 ===========
@@ -475,14 +436,7 @@ Your flash chip is in an unknown state.
 If you see this, rejoice! It means that the flash was successful. Please do not
 panic. Shut down now, and wait a few seconds, then turn back on again.
 
-**WARNING: if flashprog complains about `/dev/mem` access, please
+If you *did* run flashrom and it failed to flash, but you set bucts to 1 and
-run `sudo ./bucts 0`. If flashprog is complaining about `/dev/mem`, it means
-that you have `CONFIG_STRICT_DEVMEM` enabled in your kernel. Reboot with the
-following kernel parameter added in your bootloader: `iomem=relaxed` and try
-again with the above instructions. DO NOT continue until the above works, and
-you see the expected flashprog output as indicated above.**
-
-If you *did* run flashprog and it failed to flash, but you set bucts to 1 and
 shut down, don't worry. Just remove the yellow coin-cell battery (it's underneath
 the keyboard, connected to the mainboard), wait a minute or two, reconnect the
 coin-cell and try again from scratch. In this instance, if flashprog didn't do

site/faq.md

@@ -5,6 +5,14 @@ x-toc-enable: true
 
 AKA Frequently Questioned Answers
 
+Disable security before flashing
+================================
+
+Before internal flashing, you must first disable `/dev/mem` protections. Make
+sure to re-enable them after you're finished.
+
+See: [Disabling /dev/mem protection](install/devmem.md)
+
 Important issues
 ================
 
@@ -36,29 +44,8 @@ Testing involves minimal effort and really helps out the project.
 See the [board maintainers documentation](/docs/maintain/testing.md)
 if you are interested in testing roms before they are released.
 
-Flashprog complains about DEVMEM access
+Uneven backlight on GM45 ThinkPads
---------------------------------------
+----------------------------------
-
-If running `flashprog -p internal` for software based flashing, and
-you get an error related to /dev/mem access, you should reboot with
-`iomem=relaxed` kernel parameter before running flashprog, or use a kernel
-that has `CONFIG_STRICT_DEVMEM` and `CONFIG_IO_STRICT_DEVMEM` not enabled.
-
-Example flashprog output with both `CONFIG_STRICT_DEVMEM` and `CONFIG_IO_STRICT_DEVMEM` enabled:
-```
-flashprog v0.9.9-r1955 on GNU+Linux 4.11.9-1-ARCH (x86_64)
-flashprog is free software, get the source code at https://flashprog.org
-
-Calibrating delay loop... OK.
-Error accessing high tables, 0x100000 bytes at 0x000000007fb5d000
-/dev/mem mmap failed: Operation not permitted
-Failed getting access to coreboot high tables.
-Error accessing DMI Table, 0x1000 bytes at 0x000000007fb27000
-/dev/mem mmap failed: Operation not permitted
-```
-
-Backlight darker on the left side of the screen
----------------------------------------------------------------------------------------------------------------
 
 We don't know how to detect the correct PWM value to use in
 coreboot, so we just use the default one in coreboot which has