[meta-rockchip][PATCH v2 1/2] provide a filesystem overlay example

[meta-rockchip][PATCH v2 1/2] provide a filesystem overlay example

[Trevor Woerner]

Most implementations that use an A/B, full-partition update mechanism
(such as RAUC configured for this scenario) need some way of preserving
system configurations in a location that survives updates. The RAUC demo
provided in this layer is an example of a full-partition update,
therefore provide an example of using a filesystem overlay to preserve
the /etc and /home locations.

This example is gated by a configuration knob:

	RK_OVERLAY_DEMO

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes since v1:
- the commit message was updated to identify the locations that the demo
  will overlay (/etc and /home)
- the README blurb was updated:
  - to also indicate which locations will have an overlay in the demo
  - to indicate the kernel config requirement
  - to explain options on how to include the root's home directory in
    the overlay
- use the standard bitbake variable to place the unit files in the
  standard systemd system unit file location (/usr/lib/systemd)
- use RequiresMountsFor as the overlay mount unit's dependency mechanism
---
 README                                        | 50 +++++++++++++++++++
 conf/machine/include/rockchip-rauc.inc        |  1 +
 .../systemd/data-partition-overlay_1.0.bb     | 22 ++++++++
 .../recipes-core/systemd/files/etc.mount      | 12 +++++
 .../recipes-core/systemd/files/home.mount     | 12 +++++
 5 files changed, 97 insertions(+)
 create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/data-partition-overlay_1.0.bb
 create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount
 create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount

diff --git a/README b/README
index 6a13428d488d..c1d5d4ca1645 100644
--- a/README
+++ b/README
@@ -140,6 +140,56 @@ Notes:
 	this layer, perform the same steps as above except for the step enabling
 	RK_RAUC_DEMO.
 
+  /data overlay with RAUC
+	When using RAUC for whole-partition rootfs updates, you will need some
+	way of preserving some pieces of data between updates; this is why the
+	DEMO scheme provided in this layer also includes a /data partition.
+	Now that you have a /data partition that is not updated, you need some
+	way of storing your important data there and making it available,
+	seamlessly, into your system regardless of which slot is running.
+
+	One way of accomplishing this is to move your important files into
+	/data and providing symlinks back into each running bundle. But that
+	requires you to know ahead of time which files will be touched... which
+	quickly can become a game of whack-a-mole. A better alternative is to
+	use a filesystem overlay. With a filesystem overlay, multiple paths are
+	overlaid on top of each other behind the scenes so what you see is one
+	directory containing the aggregation of all layers. Filesystem overlays
+	have a concept of "bottom layers" and "upper layers", if you write a new
+	file into an overlay, the file will be written into the uppermost
+	layer, leaving the lower layers intact. If a file is modified, the
+	modifications are stored in the upper layer, occluding the lower layer.
+	Therefore, creating an overlay using locations in the /data partition
+	as the uppermost layer allows changes to persist across RAUC updates.
+
+	This layer includes a simple overlay scheme to demonstrate one way of
+	making use of this mechanism. To enable the demo included in this layer
+	RAUC must be enabled, then also enable:
+
+		RK_OVERLAY_DEMO
+
+	This demo includes overlays for both the /etc and /home directories.
+	With these overlays in place, you can change a user's password, or add
+	new users, and those changes will be available in subsequent updates.
+	By default bitbake places the root user's home directory in /home/root,
+	but systemd moves this to /root. The location of the root user's home
+	directory is stored in the
+
+		ROOT_HOME
+
+	variable. If you would like to use the overlay example provided in this
+	layer and also overlay the root user's home directory, simply define
+	this variable in your build to place the root user's home directory
+	under /home.
+
+	This feature requires overlay support to be enabled in the Linux
+	kernel. Specifically the following kernel config option must be either
+	=m or =y. By default this layer will use the in-kernel defconfig as a
+	base, which includes this option as a module, and kernel modules are
+	installed by default.
+
+		CONFIG_OVERLAY_FS
+
   HW video decoding with gstreamer
 
 	Most Rockchip SoCs have some integrated VPU, either Hantro, RKVDEC or
diff --git a/conf/machine/include/rockchip-rauc.inc b/conf/machine/include/rockchip-rauc.inc
index a6f79503076b..3ea95298fed6 100644
--- a/conf/machine/include/rockchip-rauc.inc
+++ b/conf/machine/include/rockchip-rauc.inc
@@ -2,3 +2,4 @@
 # rauc demo configuration from this layer
 OVERRIDES .= "${@ ':rk-rauc-demo' if bb.utils.to_boolean(d.getVar('RK_RAUC_DEMO'), False) else ''}"
 IMAGE_INSTALL:append:rk-rauc-demo = " abd-partition"
+IMAGE_INSTALL:append:rk-rauc-demo = " ${@ 'data-partition-overlay' if bb.utils.to_boolean(d.getVar('RK_OVERLAY_DEMO'), False) else ''}"
diff --git a/dynamic-layers/rk-rauc-demo/recipes-core/systemd/data-partition-overlay_1.0.bb b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/data-partition-overlay_1.0.bb
new file mode 100644
index 000000000000..9b5a58328345
--- /dev/null
+++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/data-partition-overlay_1.0.bb
@@ -0,0 +1,22 @@
+SUMMARY = "Overlay Logic onto the /data partition"
+LICENSE = "OSL-3.0"
+LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/OSL-3.0;md5=438ec6d864bbb958a49df939a56511cf"
+
+inherit rk-rauc-demo-features-check systemd
+
+SYSTEMD_SERVICE:${PN} = "etc.mount home.mount"
+
+S = "${UNPACKDIR}"
+
+SRC_URI = " \
+        file://etc.mount \
+        file://home.mount \
+	"
+
+do_install() {
+	install -d ${D}${systemd_system_unitdir}
+	install -m 0644 ${UNPACKDIR}/etc.mount ${D}${systemd_system_unitdir}
+	install -m 0644 ${UNPACKDIR}/home.mount ${D}${systemd_system_unitdir}
+}
+
+RDEPENDS:${PN} += "abd-partition"
diff --git a/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount
new file mode 100644
index 000000000000..c006bd729060
--- /dev/null
+++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount
@@ -0,0 +1,12 @@
+[Unit]
+Description=OverlayFS mount for /etc to /data/overlay/etc
+RequiresMountsFor=/data
+
+[Mount]
+What=overlay
+Where=/etc
+Type=overlay
+Options=lowerdir=/etc,upperdir=/data/overlay/etc,workdir=/data/overlay-workdir/etc
+
+[Install]
+WantedBy=multi-user.target
diff --git a/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount
new file mode 100644
index 000000000000..e0f0a89109ca
--- /dev/null
+++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount
@@ -0,0 +1,12 @@
+[Unit]
+Description=OverlayFS mount for /home to /data/overlay/home
+RequiresMountsFor=/data
+
+[Mount]
+What=overlay
+Where=/home
+Type=overlay
+Options=lowerdir=/home,upperdir=/data/overlay/home,workdir=/data/overlay-workdir/home
+
+[Install]
+WantedBy=multi-user.target
-- 
2.51.0.193.g4975ec3473b4

[meta-rockchip][PATCH v2 2/2] abd-partition: place unit file in system location

[Trevor Woerner]

The system location for systemd unit files is in /usr/lib/systemd and
local or admin-created unit files, that are meant to take precedence
over the units in the system location, are to be placed in /etc/systemd.
Move these unit files to the system location instead of putting them in
the override location.

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes since v1:
- added
---
 .../rk-rauc-demo/recipes-core/systemd/abd-partition.bb        | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/dynamic-layers/rk-rauc-demo/recipes-core/systemd/abd-partition.bb b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/abd-partition.bb
index d5cb42738e72..65a52395dfff 100644
--- a/dynamic-layers/rk-rauc-demo/recipes-core/systemd/abd-partition.bb
+++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/abd-partition.bb
@@ -21,8 +21,8 @@ do_install() {
 	install -m 0644 ${UNPACKDIR}/35-rootfsB.conf ${D}${sysconfdir}/repart.d/
 	install -m 0644 ${UNPACKDIR}/45-data.conf ${D}${sysconfdir}/repart.d/
 
-	install -d ${D}${sysconfdir}/systemd/system
-	install -m 0644 ${UNPACKDIR}/data.mount ${D}${sysconfdir}/systemd/system/
+	install -d ${D}${systemd_system_unitdir}
+	install -m 0644 ${UNPACKDIR}/data.mount ${D}${systemd_system_unitdir}
 }
 
 RDEPENDS:${PN} += "e2fsprogs-mke2fs"
-- 
2.51.0.193.g4975ec3473b4

Re: [yocto-patches] [meta-rockchip][PATCH v2 1/2] provide a filesystem overlay example

[Quentin Schulz]

Hi Trevor,

On 12/12/25 7:24 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Most implementations that use an A/B, full-partition update mechanism
> (such as RAUC configured for this scenario) need some way of preserving
> system configurations in a location that survives updates. The RAUC demo
> provided in this layer is an example of a full-partition update,
> therefore provide an example of using a filesystem overlay to preserve
> the /etc and /home locations.
> 
> This example is gated by a configuration knob:
> 
> 	RK_OVERLAY_DEMO
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [meta-rockchip][PATCH v2 1/2] provide a filesystem overlay example

[Trevor Woerner]

On Fri 2025-12-12 @ 01:24:19 PM, Trevor Woerner wrote:
> Most implementations that use an A/B, full-partition update mechanism
> (such as RAUC configured for this scenario) need some way of preserving
> system configurations in a location that survives updates. The RAUC demo
> provided in this layer is an example of a full-partition update,
> therefore provide an example of using a filesystem overlay to preserve
> the /etc and /home locations.
> 
> This example is gated by a configuration knob:
> 
> 	RK_OVERLAY_DEMO
> 
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes since v1:
> - the commit message was updated to identify the locations that the demo
>   will overlay (/etc and /home)
> - the README blurb was updated:
>   - to also indicate which locations will have an overlay in the demo
>   - to indicate the kernel config requirement
>   - to explain options on how to include the root's home directory in
>     the overlay
> - use the standard bitbake variable to place the unit files in the
>   standard systemd system unit file location (/usr/lib/systemd)
> - use RequiresMountsFor as the overlay mount unit's dependency mechanism
> ---
>  README                                        | 50 +++++++++++++++++++
>  conf/machine/include/rockchip-rauc.inc        |  1 +
>  .../systemd/data-partition-overlay_1.0.bb     | 22 ++++++++
>  .../recipes-core/systemd/files/etc.mount      | 12 +++++
>  .../recipes-core/systemd/files/home.mount     | 12 +++++
>  5 files changed, 97 insertions(+)
>  create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/data-partition-overlay_1.0.bb
>  create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount
>  create mode 100644 dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount

Pushed to meta-rockchip, master branch.

Re: [meta-rockchip][PATCH v2 2/2] abd-partition: place unit file in system location

[Trevor Woerner]

On Fri 2025-12-12 @ 01:24:20 PM, Trevor Woerner wrote:
> The system location for systemd unit files is in /usr/lib/systemd and
> local or admin-created unit files, that are meant to take precedence
> over the units in the system location, are to be placed in /etc/systemd.
> Move these unit files to the system location instead of putting them in
> the override location.
> 
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes since v1:
> - added
> ---
>  .../rk-rauc-demo/recipes-core/systemd/abd-partition.bb        | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Pushed to meta-rockchip, master branch.