Re: [yocto-patches] [meta-rockchip][PATCH] provide a filesystem overlay example

[Trevor Woerner <twoerner@gmail.com>]

On Fri 2025-12-12 @ 11:47:55 AM, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Trevor,
> 
> On 12/11/25 10:03 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
> > system configurations. This example is gated by a configuration knob:
> > 
> > 	RK_OVERLAY_DEMO
> > 
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> >   README                                        | 28 +++++++++++++++++++
> >   conf/machine/include/rockchip-rauc.inc        |  1 +
> >   .../systemd/data-partition-overlay_1.0.bb     | 22 +++++++++++++++
> >   .../recipes-core/systemd/files/etc.mount      | 13 +++++++++
> >   .../recipes-core/systemd/files/home.mount     | 13 +++++++++
> >   5 files changed, 77 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..92dc072a0833 100644
> > --- a/README
> > +++ b/README
> > @@ -140,6 +140,34 @@ 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
> > +
> 
> You're overlaying two directories, so please make this explicit in the
> README. /etc and /home are overlaid. Now, is the root user's home directory
> in /home/root or in /root? Because you may want to overlay that as well?

It's in /root, good point! ...or I could put root's home directory under
/home?

In desktop Linux I guess it's common for /home to have lots of
sub-directories, and be NFS-mounted, etc in which case having root's
home handled separately is good, but there probably is no need for it
here?

> Additionally, CONFIG_OVERLAY_FS support likely needs to be enabled in the
> kernel for this to work, so mentioning this would be nice? (though we also
> didn't mention this for the VPU, so... :) ).

It's funny I didn't mention this, considering the other email thread in
progress ;-) The aarch64 defconfig includes:

	CONFIG_OVERLAY_FS=m

which is good enough to make this work. It also includes

	CONFIG_OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW=y

which might be questionable. The in-kernel documentation says:

	OVERLAY_FS_REDIRECT_ALWAYS_FOLLOW:

	    If this is enabled, then redirects are always followed by default.
	    Enabling this results in a less secure configuration. Enable this
	    option only when worried about backward compatibility with kernels
	    that have the redirect_dir feature and follow redirects even if
	    turned off.

> >     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..7d9a9e6de82b
> > --- /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}${sysconfdir}/systemd/system
> > +	install -m 0644 ${UNPACKDIR}/etc.mount ${D}${sysconfdir}/systemd/system/
> > +	install -m 0644 ${UNPACKDIR}/home.mount ${D}${sysconfdir}/systemd/system/
> 
> I see we have a couple of systemd_*unitdir variables in bitbake.conf, should
> we use one of those instead?

Good catch.

> > +}
> > +
> > +RDEPENDS:${PN} += "abd-partition"
> 
> Maybe add a comment this is necessary because of the data.mount requirement?

Sounds good, and yes.

> > 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..65b896563bef
> > --- /dev/null
> > +++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/etc.mount
> > @@ -0,0 +1,13 @@
> > +[Unit]
> > +Description=OverlayFS mount for /etc to /data/overlay/etc
> > +Requires=data.mount
> > +After=data.mount
> > +
> 
> I'm wondering if this cannot be handled by
> 
> RequiresMountsFor=/data
> 
> c.f. https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#RequiresMountsFor=

Okay, I'll try that. systemd unit files are such a labyrinth. Some AI
suggested the above ;-)

> > +[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..d6a384fa9c75
> > --- /dev/null
> > +++ b/dynamic-layers/rk-rauc-demo/recipes-core/systemd/files/home.mount
> > @@ -0,0 +1,13 @@
> > +[Unit]
> > +Description=OverlayFS mount for /home to /data/overlay/home
> > +Requires=etc.mount
> > +After=etc.mount
> > +
> 
> Why is this not data.mount too?

I did this patch one piece at a time. It took me less than an hour from
start of reading to getting /etc working. It then took me the rest of
the day to get /home added as well. The problem was with
ordering/dependencies.

If I ordered both /home and /etc overlays after data.mount it would
always fail; either one or both of the mounts would not appear in the
`mount` output or (worse) the overlays would appear to be mounted (they
would show up in the `mount` output) but one or both of the mounts would
not work.

The solution I found was to explicitly order them: data → etc → home. In
practice it didn't matter whether home or etc came first, they just
needed to be strongly ordered.

While trying to get this right, sometimes systemd itself would throw a:

	[ SKIP ] Ordering cycle found, skipping Ove…mount for /etc to /data/overlay/etc

on boot (sometimes for etc, sometime for home) which at least warned me
that something went wrong. Other times it didn't give the error, but
failed anyway.

tl;dr: it's a bit finicky ;-)

> Otherwise looks ok to me.

Thanks!

> Cheers,
> Quentin
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#2771): https://lists.yoctoproject.org/g/yocto-patches/message/2771
> Mute This Topic: https://lists.yoctoproject.org/mt/116736285/900817
> Group Owner: yocto-patches+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/yocto-patches/leave/13168745/900817/63955952/xyzzy [twoerner@gmail.com]
> -=-=-=-=-=-=-=-=-=-=-=-
> 
>