[PATCH 0/1] liveupdate: Add internal APIs for file preservation

[PATCH 0/1] liveupdate: Add internal APIs for file preservation

[Samiullah Khawaja]

Live update orchestrator file handlers depend on the preservation of
other files. To make sure that the dependency is preserved, the file
handlers needs to fetch the preservation token of the preserved
dependency. Similarly during restore, a file handler wants to fetch the
restored file of the dependency.

There are two known usecases of this,

- VFIO-Cdev preservation requires the preservation of iommufd. This is
  required by the IOMMU preservation series:
  https://lore.kernel.org/all/20260427175633.1978233-1-skhawaja@google.com/
- guest_memfd preservation requires the preservation of kvmfd. This is
  required by the guest_memfd preservation series:
  https://lore.kernel.org/all/20ae20f9d1a198b289444ebb4c824314cbba1bcf.1780676742.git.tarunsahu@google.com/

This patch was being sent as part of the IOMMU preservation series, but
now it is being sent separately.

Pasha Tatashin (1):
  liveupdate: luo_file: Add internal APIs for file preservation

 include/linux/liveupdate.h       | 21 ++++++++++
 kernel/liveupdate/luo_file.c     | 69 ++++++++++++++++++++++++++++++++
 kernel/liveupdate/luo_internal.h | 17 ++++++++
 3 files changed, 107 insertions(+)

base-commit: 34e8f02817e31826e76bb2ded48bf28fe921f20b
-- 
2.54.0.1136.gdb2ca164c4-goog

[PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Samiullah Khawaja]

From: Pasha Tatashin <pasha.tatashin@soleen.com>

Live update orchestrator file handlers depend on the preservation of
other files. To make sure that the dependency is preserved, the file
handlers needs to fetch the preservation token of the preserved
dependency. Similarly during restore, a file handler wants to fetch the
restored file of the dependency.

Add APIs that allows fetching token of dependency during preservation,
and fetching the restored file dependency during restore.

Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
Signed-off-by: Samiullah Khawaja <skhawaja@google.com>
---
 include/linux/liveupdate.h       | 21 ++++++++++
 kernel/liveupdate/luo_file.c     | 69 ++++++++++++++++++++++++++++++++
 kernel/liveupdate/luo_internal.h | 17 ++++++++
 3 files changed, 107 insertions(+)

diff --git a/include/linux/liveupdate.h b/include/linux/liveupdate.h
index 88722e5caf02..261f61998fce 100644
--- a/include/linux/liveupdate.h
+++ b/include/linux/liveupdate.h
@@ -25,6 +25,7 @@ struct file;
 /**
  * struct liveupdate_file_op_args - Arguments for file operation callbacks.
  * @handler:          The file handler being called.
+ * @session:          The session this file belongs to.
  * @retrieve_status:  The retrieve status for the 'can_finish / finish'
  *                    operation. A value of 0 means the retrieve has not been
  *                    attempted, a positive value means the retrieve was
@@ -45,6 +46,7 @@ struct file;
  */
 struct liveupdate_file_op_args {
 	struct liveupdate_file_handler *handler;
+	struct liveupdate_session *session;
 	int retrieve_status;
 	struct file *file;
 	u64 serialized_data;
@@ -243,6 +245,13 @@ int liveupdate_flb_get_incoming(struct liveupdate_flb *flb, void **objp);
 void liveupdate_flb_put_incoming(struct liveupdate_flb *flb);
 
 int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb, void **objp);
+/* kernel can internally retrieve files */
+int liveupdate_get_file_incoming(struct liveupdate_session *s, u64 token,
+				 struct file **filep);
+
+/* Get a token for an outgoing file, or -ENOENT if file is not preserved */
+int liveupdate_get_token_outgoing(struct liveupdate_session *s,
+				  struct file *file, u64 *tokenp);
 
 #else /* CONFIG_LIVEUPDATE */
 
@@ -292,5 +301,17 @@ static inline int liveupdate_flb_get_outgoing(struct liveupdate_flb *flb,
 	return -EOPNOTSUPP;
 }
 
+static inline int liveupdate_get_file_incoming(struct liveupdate_session *s,
+					       u64 token, struct file **filep)
+{
+	return -EOPNOTSUPP;
+}
+
+static inline int liveupdate_get_token_outgoing(struct liveupdate_session *s,
+						struct file *file, u64 *tokenp)
+{
+	return -EOPNOTSUPP;
+}
+
 #endif /* CONFIG_LIVEUPDATE */
 #endif /* _LINUX_LIVEUPDATE_H */
diff --git a/kernel/liveupdate/luo_file.c b/kernel/liveupdate/luo_file.c
index f428f720b53f..57f7f19fcfca 100644
--- a/kernel/liveupdate/luo_file.c
+++ b/kernel/liveupdate/luo_file.c
@@ -323,6 +323,7 @@ int luo_preserve_file(struct luo_file_set *file_set, u64 token, int fd)
 	mutex_init(&luo_file->mutex);
 
 	args.handler = fh;
+	args.session = luo_session_from_file_set(file_set);
 	args.file = file;
 	err = fh->ops->preserve(&args);
 	if (err)
@@ -380,6 +381,7 @@ void luo_file_unpreserve_files(struct luo_file_set *file_set)
 					   struct luo_file, list);
 
 		args.handler = luo_file->fh;
+		args.session = luo_session_from_file_set(file_set);
 		args.file = luo_file->file;
 		args.serialized_data = luo_file->serialized_data;
 		args.private_data = luo_file->private_data;
@@ -411,6 +413,7 @@ static int luo_file_freeze_one(struct luo_file_set *file_set,
 		struct liveupdate_file_op_args args = {0};
 
 		args.handler = luo_file->fh;
+		args.session = luo_session_from_file_set(file_set);
 		args.file = luo_file->file;
 		args.serialized_data = luo_file->serialized_data;
 		args.private_data = luo_file->private_data;
@@ -432,6 +435,7 @@ static void luo_file_unfreeze_one(struct luo_file_set *file_set,
 		struct liveupdate_file_op_args args = {0};
 
 		args.handler = luo_file->fh;
+		args.session = luo_session_from_file_set(file_set);
 		args.file = luo_file->file;
 		args.serialized_data = luo_file->serialized_data;
 		args.private_data = luo_file->private_data;
@@ -621,6 +625,7 @@ int luo_retrieve_file(struct luo_file_set *file_set, u64 token,
 	}
 
 	args.handler = luo_file->fh;
+	args.session = luo_session_from_file_set(file_set);
 	args.serialized_data = luo_file->serialized_data;
 	err = luo_file->fh->ops->retrieve(&args);
 	if (err) {
@@ -654,6 +659,7 @@ static int luo_file_can_finish_one(struct luo_file_set *file_set,
 		struct liveupdate_file_op_args args = {0};
 
 		args.handler = luo_file->fh;
+		args.session = luo_session_from_file_set(file_set);
 		args.file = luo_file->file;
 		args.serialized_data = luo_file->serialized_data;
 		args.retrieve_status = luo_file->retrieve_status;
@@ -671,6 +677,7 @@ static void luo_file_finish_one(struct luo_file_set *file_set,
 	guard(mutex)(&luo_file->mutex);
 
 	args.handler = luo_file->fh;
+	args.session = luo_session_from_file_set(file_set);
 	args.file = luo_file->file;
 	args.serialized_data = luo_file->serialized_data;
 	args.retrieve_status = luo_file->retrieve_status;
@@ -926,3 +933,65 @@ void liveupdate_unregister_file_handler(struct liveupdate_file_handler *fh)
 	list_del(&ACCESS_PRIVATE(fh, list));
 }
 EXPORT_SYMBOL_GPL(liveupdate_unregister_file_handler);
+
+/**
+ * liveupdate_get_token_outgoing - Get the token for a preserved file.
+ * @s:      The outgoing liveupdate session.
+ * @file:   The file object to search for.
+ * @tokenp: Output parameter for the found token.
+ *
+ * Searches the list of preserved files in an outgoing session for a matching
+ * file object. If found, the corresponding user-provided token is returned.
+ *
+ * This function is intended for in-kernel callers that need to correlate a
+ * file with its liveupdate token.
+ *
+ * Context: It must be called with session mutex acquired.
+ * Return: 0 on success, -ENOENT if the file is not preserved in this session.
+ */
+int liveupdate_get_token_outgoing(struct liveupdate_session *s,
+				  struct file *file, u64 *tokenp)
+{
+	struct luo_file_set *file_set = luo_file_set_from_session_locked(s);
+	struct luo_file *luo_file;
+	int err = -ENOENT;
+
+	list_for_each_entry(luo_file, &file_set->files_list, list) {
+		if (luo_file->file == file) {
+			if (tokenp)
+				*tokenp = luo_file->token;
+			err = 0;
+			break;
+		}
+	}
+
+	return err;
+}
+EXPORT_SYMBOL_GPL(liveupdate_get_token_outgoing);
+
+/**
+ * liveupdate_get_file_incoming - Retrieves a preserved file for in-kernel use.
+ * @s:      The incoming liveupdate session (restored from the previous kernel).
+ * @token:  The unique token identifying the file to retrieve.
+ * @filep:  On success, this will be populated with a pointer to the retrieved
+ *          'struct file'.
+ *
+ * Provides a kernel-internal API for other subsystems to retrieve their
+ * preserved files after a live update. This function is a simple wrapper
+ * around luo_retrieve_file(), allowing callers to find a file by its token.
+ *
+ * The caller receives a new reference to the file and must call fput() when it
+ * is no longer needed. The file's lifetime is managed by LUO and any userspace
+ * file descriptors.
+ *
+ * Context: It must be called with session mutex acquired of a restored session.
+ * Return: 0 on success. Returns -ENOENT if no file with the matching token is
+ *         found, or any other negative errno on failure.
+ */
+int liveupdate_get_file_incoming(struct liveupdate_session *s, u64 token,
+				 struct file **filep)
+{
+	return luo_retrieve_file(luo_file_set_from_session_locked(s),
+				 token, filep);
+}
+EXPORT_SYMBOL_GPL(liveupdate_get_file_incoming);
diff --git a/kernel/liveupdate/luo_internal.h b/kernel/liveupdate/luo_internal.h
index 875844d7a41d..08b198802e7f 100644
--- a/kernel/liveupdate/luo_internal.h
+++ b/kernel/liveupdate/luo_internal.h
@@ -79,6 +79,23 @@ struct luo_session {
 
 extern struct rw_semaphore luo_register_rwlock;
 
+static inline struct liveupdate_session *luo_session_from_file_set(struct luo_file_set *file_set)
+{
+	struct luo_session *session;
+
+	session = container_of(file_set, struct luo_session, file_set);
+
+	return (struct liveupdate_session *)session;
+}
+
+static inline struct luo_file_set *luo_file_set_from_session_locked(struct liveupdate_session *s)
+{
+	struct luo_session *session = (struct luo_session *)s;
+
+	lockdep_assert_held(&session->mutex);
+	return &session->file_set;
+}
+
 int luo_session_create(const char *name, struct file **filep);
 int luo_session_retrieve(const char *name, struct file **filep);
 int __init luo_session_setup_outgoing(void *fdt);
-- 
2.54.0.1136.gdb2ca164c4-goog

Re: [PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Pranjal Shrivastava]

On Sat, Jun 13, 2026 at 01:25:20AM +0000, Samiullah Khawaja wrote:
> From: Pasha Tatashin <pasha.tatashin@soleen.com>
> 
> Live update orchestrator file handlers depend on the preservation of
> other files. To make sure that the dependency is preserved, the file
> handlers needs to fetch the preservation token of the preserved
> dependency. Similarly during restore, a file handler wants to fetch the
> restored file of the dependency.
> 
> Add APIs that allows fetching token of dependency during preservation,
> and fetching the restored file dependency during restore.
> 
> Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
> Signed-off-by: Samiullah Khawaja <skhawaja@google.com>
> ---
>  include/linux/liveupdate.h       | 21 ++++++++++
>  kernel/liveupdate/luo_file.c     | 69 ++++++++++++++++++++++++++++++++
>  kernel/liveupdate/luo_internal.h | 17 ++++++++
>  3 files changed, 107 insertions(+)
>
[...]
> +EXPORT_SYMBOL_GPL(liveupdate_get_token_outgoing);
> +
> +/**
> + * liveupdate_get_file_incoming - Retrieves a preserved file for in-kernel use.
> + * @s:      The incoming liveupdate session (restored from the previous kernel).
> + * @token:  The unique token identifying the file to retrieve.
> + * @filep:  On success, this will be populated with a pointer to the retrieved
> + *          'struct file'.
> + *
> + * Provides a kernel-internal API for other subsystems to retrieve their
> + * preserved files after a live update. This function is a simple wrapper
> + * around luo_retrieve_file(), allowing callers to find a file by its token.
> + *
> + * The caller receives a new reference to the file and must call fput() when it
> + * is no longer needed. The file's lifetime is managed by LUO and any userspace
> + * file descriptors.
> + *
> + * Context: It must be called with session mutex acquired of a restored session.
> + * Return: 0 on success. Returns -ENOENT if no file with the matching token is
> + *         found, or any other negative errno on failure.
> + */
> +int liveupdate_get_file_incoming(struct liveupdate_session *s, u64 token,
> +				 struct file **filep)
> +{
> +	return luo_retrieve_file(luo_file_set_from_session_locked(s),
> +				 token, filep);
> +}
> +EXPORT_SYMBOL_GPL(liveupdate_get_file_incoming);

Thanks for modifying the comment (as discussed in [1]). 
This looks good now, along with the EXPORT_SYMBOL_GPL.

Reviewed-by: Pranjal Shrivastava <praan@google.com>

Thanks,
Praan

[1] https://lore.kernel.org/all/agr6yoyYYq2QFxjL@google.com/

Re: [PATCH 0/1] liveupdate: Add internal APIs for file preservation

[tarunsahu]

Hi,

Thankyou for sending it saperately, Now I can remove this from
guest_memfd series, And we can track it here.

I think it needs rebasing. I see it fails to apply to liveupdate/next
and mainline both.

Thanks

Samiullah Khawaja <skhawaja@google.com> writes:

> Live update orchestrator file handlers depend on the preservation of
> other files. To make sure that the dependency is preserved, the file
> handlers needs to fetch the preservation token of the preserved
> dependency. Similarly during restore, a file handler wants to fetch the
> restored file of the dependency.
>
> There are two known usecases of this,
>
> - VFIO-Cdev preservation requires the preservation of iommufd. This is
>   required by the IOMMU preservation series:
>   https://lore.kernel.org/all/20260427175633.1978233-1-skhawaja@google.com/
> - guest_memfd preservation requires the preservation of kvmfd. This is
>   required by the guest_memfd preservation series:
>   https://lore.kernel.org/all/20ae20f9d1a198b289444ebb4c824314cbba1bcf.1780676742.git.tarunsahu@google.com/
>
> This patch was being sent as part of the IOMMU preservation series, but
> now it is being sent separately.
>
> Pasha Tatashin (1):
>   liveupdate: luo_file: Add internal APIs for file preservation
>
>  include/linux/liveupdate.h       | 21 ++++++++++
>  kernel/liveupdate/luo_file.c     | 69 ++++++++++++++++++++++++++++++++
>  kernel/liveupdate/luo_internal.h | 17 ++++++++
>  3 files changed, 107 insertions(+)
>
> base-commit: 34e8f02817e31826e76bb2ded48bf28fe921f20b
> -- 
> 2.54.0.1136.gdb2ca164c4-goog

Re: [PATCH 0/1] liveupdate: Add internal APIs for file preservation

[Mike Rapoport]

Hi Sami,

On Sat, Jun 13, 2026 at 01:25:19AM +0000, Samiullah Khawaja wrote:
> Live update orchestrator file handlers depend on the preservation of
> other files. To make sure that the dependency is preserved, the file
> handlers needs to fetch the preservation token of the preserved
> dependency. Similarly during restore, a file handler wants to fetch the
> restored file of the dependency.

This will have to wait until -rc1 is out.
I'm thinking about taking it to a branch in the liveupdate tree and keeping
there until a patchset that uses it, be it iommu or kvm matures.
 
> There are two known usecases of this,
> 
> - VFIO-Cdev preservation requires the preservation of iommufd. This is
>   required by the IOMMU preservation series:
>   https://lore.kernel.org/all/20260427175633.1978233-1-skhawaja@google.com/
> - guest_memfd preservation requires the preservation of kvmfd. This is
>   required by the guest_memfd preservation series:
>   https://lore.kernel.org/all/20ae20f9d1a198b289444ebb4c824314cbba1bcf.1780676742.git.tarunsahu@google.com/

-- 
Sincerely yours,
Mike.

Re: [PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Pratyush Yadav]

Hi Sami,

On Sat, Jun 13 2026, Samiullah Khawaja wrote:

> From: Pasha Tatashin <pasha.tatashin@soleen.com>
>
> Live update orchestrator file handlers depend on the preservation of
> other files. To make sure that the dependency is preserved, the file
> handlers needs to fetch the preservation token of the preserved
> dependency. Similarly during restore, a file handler wants to fetch the
> restored file of the dependency.
>
> Add APIs that allows fetching token of dependency during preservation,
> and fetching the restored file dependency during restore.
>
> Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
> Signed-off-by: Samiullah Khawaja <skhawaja@google.com>

We discussed this once already on a call, but I'll write my argument out
here for everyone else to get a say as well.

While it isn't obvious, this patch implicitly defines a part of the uAPI
for live update. This patch says to VMMs (or other live update users)
that "you can restore dependent files in any order". That is, VMMs
don't have to restore the files in a topological sort order or
dependencies, they can do so in any order and the kernel will manage the
dependencies on its own.

But on the preservation side, VMMs still do need to follow the
topological order of dependencies. Because if they don't, the
liveupdate_get_token_outgoing() call will fail and preservation can't
proceed.

In simple words, if file type A depends on file type B, VMMs always need
to preserve B before A, because A's preservation will try to find B's
token, and if B is not preserved that will fail. On the _restore_ side
though, liveupdate_get_file_incoming() implicitly retrieves the file so
the VMM can restore then in any order.

I don't like this for a couple reasons. First, this makes the API
asymmetric. If the VMM needs to manage dependency order during
preservation anyway, why not do it on retrieve as well?

Second, the API is easier to misuse. The VMM can restore A but not B,
and then close the session. It will go on its merry way never knowing it
did something wrong. For example, guest_memfd depends on its VM FD. With
this patch, LUO will allow restoring guest_memfd without restoring the
VM FD. This makes the guest_memfd practically useless. Yes, it is a bug
in the VMM anyway, but if guest_memfd restore was denied, then it would
be easier to catch.

The kernel will keep itself safe in either case, but it will make the
API harder to misuse. And you can always _relax_ the ordering
requirement if there is a need in the future, but you can't go the other
way round.

So that's my question: do we enforce restore ordering? The code change
should be relatively simple. You just need to fail if the file is not
already restored in liveupdate_get_file_incoming().

In either case, please at least add a piece in the documentation about
this ordering. We should not leave it implicit.

[...]

-- 
Regards,
Pratyush Yadav

Re: [PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Pasha Tatashin]

On 06-26 13:57, Pratyush Yadav wrote:
> Hi Sami,
> 
> On Sat, Jun 13 2026, Samiullah Khawaja wrote:
> 
> > From: Pasha Tatashin <pasha.tatashin@soleen.com>
> >
> > Live update orchestrator file handlers depend on the preservation of
> > other files. To make sure that the dependency is preserved, the file
> > handlers needs to fetch the preservation token of the preserved
> > dependency. Similarly during restore, a file handler wants to fetch the
> > restored file of the dependency.
> >
> > Add APIs that allows fetching token of dependency during preservation,
> > and fetching the restored file dependency during restore.
> >
> > Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
> > Signed-off-by: Samiullah Khawaja <skhawaja@google.com>
> 
> We discussed this once already on a call, but I'll write my argument out
> here for everyone else to get a say as well.
> 
> While it isn't obvious, this patch implicitly defines a part of the uAPI
> for live update. This patch says to VMMs (or other live update users)
> that "you can restore dependent files in any order". That is, VMMs
> don't have to restore the files in a topological sort order or
> dependencies, they can do so in any order and the kernel will manage the
> dependencies on its own.

Avoiding a forced dependency ordering is a deliberate design choice in 
LUO, to avoid any kind of circular dependeces: A depends on B, B depends 
on C, and C depends on A.

To achieve this, LUO provides the .can_finish() callback. So, LUO does
two-phase verification:

1. It iterates through all tracked files and invokes .can_finish().
2. Only if *all* files return success does it proceed to invoke .finish().

If a VMM restores a file (such as guest_memfd) but fails to restore its
dependency (such as the VM FD), or attempts to close the session 
prematurely, the .can_finish() check for that file will fail (returning 
-EBUSY), and the entire finish sequence will abort. This guarantees 
kernel-enforced correctness at the session boundary and without forcing 
the VMM to execute restores in a strict sequential order, which anway 
would not make  any sense from kernel side due to circular dependecies 
issue, where topological sort does not exist.

> 
> But on the preservation side, VMMs still do need to follow the
> topological order of dependencies. Because if they don't, the
> liveupdate_get_token_outgoing() call will fail and preservation can't
> proceed.

Actually, preservation can also be performed in an order-independent manner.
While a handler can call liveupdate_get_token_outgoing() during .preserve(),
it can also defer this query until the .freeze() callback. Because .freeze()
is invoked after all files in the session have completed their .preserve() phase,
all dependency tokens are guaranteed to be available, completely eliminating any
topological ordering requirements during the initial preservation calls. It is
up to individual file handler implementations to decide whether they wish to
enforce ordering at .preserve() time or defer it to .freeze().

> In simple words, if file type A depends on file type B, VMMs always need
> to preserve B before A, because A's preservation will try to find B's
> token, and if B is not preserved that will fail. On the _restore_ side
> though, liveupdate_get_file_incoming() implicitly retrieves the file so
> the VMM can restore then in any order.
> 
> I don't like this for a couple reasons. First, this makes the API
> asymmetric. If the VMM needs to manage dependency order during
> preservation anyway, why not do it on retrieve as well?
> 
> Second, the API is easier to misuse. The VMM can restore A but not B,
> and then close the session. It will go on its merry way never knowing it
> did something wrong. For example, guest_memfd depends on its VM FD. With
> this patch, LUO will allow restoring guest_memfd without restoring the
> VM FD. This makes the guest_memfd practically useless. Yes, it is a bug
> in the VMM anyway, but if guest_memfd restore was denied, then it would
> be easier to catch.
> 
> The kernel will keep itself safe in either case, but it will make the
> API harder to misuse. And you can always _relax_ the ordering
> requirement if there is a need in the future, but you can't go the other
> way round.
> 
> So that's my question: do we enforce restore ordering? The code change
> should be relatively simple. You just need to fail if the file is not
> already restored in liveupdate_get_file_incoming().
> 
> In either case, please at least add a piece in the documentation about
> this ordering. We should not leave it implicit.

As explained above, the .can_finish() callback addresses this problem 
and prevents any misuse (such as closing a session with a missing VM FD 
dependency).

That said, I agree that these ordering semantics, deferred verification 
model, and the exact roles of .can_finish() and .freeze() should not 
remain implicit. It makes sense adding details to the documentation to 
clarify this behavior.

Pasha

Re: [PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Pratyush Yadav]

On Mon, Jun 29 2026, Pasha Tatashin wrote:

> On 06-26 13:57, Pratyush Yadav wrote:
>> Hi Sami,
>> 
>> On Sat, Jun 13 2026, Samiullah Khawaja wrote:
>> 
>> > From: Pasha Tatashin <pasha.tatashin@soleen.com>
>> >
>> > Live update orchestrator file handlers depend on the preservation of
>> > other files. To make sure that the dependency is preserved, the file
>> > handlers needs to fetch the preservation token of the preserved
>> > dependency. Similarly during restore, a file handler wants to fetch the
>> > restored file of the dependency.
>> >
>> > Add APIs that allows fetching token of dependency during preservation,
>> > and fetching the restored file dependency during restore.
>> >
>> > Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
>> > Signed-off-by: Samiullah Khawaja <skhawaja@google.com>
>> 
>> We discussed this once already on a call, but I'll write my argument out
>> here for everyone else to get a say as well.
>> 
>> While it isn't obvious, this patch implicitly defines a part of the uAPI
>> for live update. This patch says to VMMs (or other live update users)
>> that "you can restore dependent files in any order". That is, VMMs
>> don't have to restore the files in a topological sort order or
>> dependencies, they can do so in any order and the kernel will manage the
>> dependencies on its own.
>
> Avoiding a forced dependency ordering is a deliberate design choice in 
> LUO, to avoid any kind of circular dependeces: A depends on B, B depends 
> on C, and C depends on A.

Do we have anything like this in practice? IIUC IOMMUFD and VFIO FD have
sorted out their dependency order and we no longer have circular
dependencies there.

>
> To achieve this, LUO provides the .can_finish() callback. So, LUO does
> two-phase verification:
>
> 1. It iterates through all tracked files and invokes .can_finish().
> 2. Only if *all* files return success does it proceed to invoke .finish().
>
> If a VMM restores a file (such as guest_memfd) but fails to restore its
> dependency (such as the VM FD), or attempts to close the session 
> prematurely, the .can_finish() check for that file will fail (returning 
> -EBUSY), and the entire finish sequence will abort. This guarantees 
> kernel-enforced correctness at the session boundary and without forcing 
> the VMM to execute restores in a strict sequential order, which anway 
> would not make  any sense from kernel side due to circular dependecies 
> issue, where topological sort does not exist.
>
>> 
>> But on the preservation side, VMMs still do need to follow the
>> topological order of dependencies. Because if they don't, the
>> liveupdate_get_token_outgoing() call will fail and preservation can't
>> proceed.
>
> Actually, preservation can also be performed in an order-independent manner.
> While a handler can call liveupdate_get_token_outgoing() during .preserve(),
> it can also defer this query until the .freeze() callback. Because .freeze()
> is invoked after all files in the session have completed their .preserve() phase,
> all dependency tokens are guaranteed to be available, completely eliminating any
> topological ordering requirements during the initial preservation calls. It is
> up to individual file handler implementations to decide whether they wish to
> enforce ordering at .preserve() time or defer it to .freeze().

That is the worst of both worlds. I get your point that LUO doesn't want
to enforce dependency ordering. My arguments against that are somewhat
subjective so I can live with this.

But then you can't let file handlers enforce it as they wish. The
dependency ordering is uAPI because it directly affects how VMMs
preserve files. If the VMM has to keep track of dependencies for some
file types and doesn't have to do so for others, that is a terrible and
inconsistent API.

Ideally, LUO should handle the dependencies on its own. preserve() can
give LUO a list of files the preserved file depends on, and LUO makes
sure all the dependencies are present in the session at freeze. We would
also need a way of getting the dependent files back from LUO on
retrieve(). That would make sure the dependencies are properly enforced
both on freeze and finish, and the enforcement isn't left up to the file
handlers.

Unfortunately all that sounds fairly complicated so I am not sure if we
want to do that just yet, although I would like to hear your thoughts on
this.

>
>> In simple words, if file type A depends on file type B, VMMs always need
>> to preserve B before A, because A's preservation will try to find B's
>> token, and if B is not preserved that will fail. On the _restore_ side
>> though, liveupdate_get_file_incoming() implicitly retrieves the file so
>> the VMM can restore then in any order.
>> 
>> I don't like this for a couple reasons. First, this makes the API
>> asymmetric. If the VMM needs to manage dependency order during
>> preservation anyway, why not do it on retrieve as well?
>> 
>> Second, the API is easier to misuse. The VMM can restore A but not B,
>> and then close the session. It will go on its merry way never knowing it
>> did something wrong. For example, guest_memfd depends on its VM FD. With
>> this patch, LUO will allow restoring guest_memfd without restoring the
>> VM FD. This makes the guest_memfd practically useless. Yes, it is a bug
>> in the VMM anyway, but if guest_memfd restore was denied, then it would
>> be easier to catch.
>> 
>> The kernel will keep itself safe in either case, but it will make the
>> API harder to misuse. And you can always _relax_ the ordering
>> requirement if there is a need in the future, but you can't go the other
>> way round.
>> 
>> So that's my question: do we enforce restore ordering? The code change
>> should be relatively simple. You just need to fail if the file is not
>> already restored in liveupdate_get_file_incoming().
>> 
>> In either case, please at least add a piece in the documentation about
>> this ordering. We should not leave it implicit.
>
> As explained above, the .can_finish() callback addresses this problem 
> and prevents any misuse (such as closing a session with a missing VM FD 
> dependency).
>
> That said, I agree that these ordering semantics, deferred verification 
> model, and the exact roles of .can_finish() and .freeze() should not 
> remain implicit. It makes sense adding details to the documentation to 
> clarify this behavior.
>
> Pasha

-- 
Regards,
Pratyush Yadav

Re: [PATCH 1/1] liveupdate: luo_file: Add internal APIs for file preservation

[Pratyush Yadav]

On Mon, Jun 29 2026, Pratyush Yadav wrote:

> On Mon, Jun 29 2026, Pasha Tatashin wrote:
>
>> On 06-26 13:57, Pratyush Yadav wrote:
>>> Hi Sami,
>>> 
>>> On Sat, Jun 13 2026, Samiullah Khawaja wrote:
>>> 
>>> > From: Pasha Tatashin <pasha.tatashin@soleen.com>
>>> >
>>> > Live update orchestrator file handlers depend on the preservation of
>>> > other files. To make sure that the dependency is preserved, the file
>>> > handlers needs to fetch the preservation token of the preserved
>>> > dependency. Similarly during restore, a file handler wants to fetch the
>>> > restored file of the dependency.
>>> >
>>> > Add APIs that allows fetching token of dependency during preservation,
>>> > and fetching the restored file dependency during restore.
>>> >
>>> > Signed-off-by: Pasha Tatashin <pasha.tatashin@soleen.com>
>>> > Signed-off-by: Samiullah Khawaja <skhawaja@google.com>
[...]
>>
>> To achieve this, LUO provides the .can_finish() callback. So, LUO does
>> two-phase verification:
>>
>> 1. It iterates through all tracked files and invokes .can_finish().
>> 2. Only if *all* files return success does it proceed to invoke .finish().
>>
>> If a VMM restores a file (such as guest_memfd) but fails to restore its
>> dependency (such as the VM FD), or attempts to close the session 
>> prematurely, the .can_finish() check for that file will fail (returning 
>> -EBUSY), and the entire finish sequence will abort. This guarantees 
>> kernel-enforced correctness at the session boundary and without forcing 
>> the VMM to execute restores in a strict sequential order, which anway 
>> would not make  any sense from kernel side due to circular dependecies 
>> issue, where topological sort does not exist.
>>
>>> 
>>> But on the preservation side, VMMs still do need to follow the
>>> topological order of dependencies. Because if they don't, the
>>> liveupdate_get_token_outgoing() call will fail and preservation can't
>>> proceed.
>>
>> Actually, preservation can also be performed in an order-independent manner.
>> While a handler can call liveupdate_get_token_outgoing() during .preserve(),
>> it can also defer this query until the .freeze() callback. Because .freeze()
>> is invoked after all files in the session have completed their .preserve() phase,
>> all dependency tokens are guaranteed to be available, completely eliminating any
>> topological ordering requirements during the initial preservation calls. It is
>> up to individual file handler implementations to decide whether they wish to
>> enforce ordering at .preserve() time or defer it to .freeze().
>
> That is the worst of both worlds. I get your point that LUO doesn't want
> to enforce dependency ordering. My arguments against that are somewhat
> subjective so I can live with this.
>
> But then you can't let file handlers enforce it as they wish. The
> dependency ordering is uAPI because it directly affects how VMMs
> preserve files. If the VMM has to keep track of dependencies for some
> file types and doesn't have to do so for others, that is a terrible and
> inconsistent API.
>
> Ideally, LUO should handle the dependencies on its own. preserve() can
> give LUO a list of files the preserved file depends on, and LUO makes
> sure all the dependencies are present in the session at freeze. We would
> also need a way of getting the dependent files back from LUO on
> retrieve(). That would make sure the dependencies are properly enforced
> both on freeze and finish, and the enforcement isn't left up to the file
> handlers.
>
> Unfortunately all that sounds fairly complicated so I am not sure if we
> want to do that just yet, although I would like to hear your thoughts on
> this.

We had discussion about this in the live update bi-weekly today. The
conclusion we arrived at is to keep the current functionality. That is,
we don't enforce preservation dependency.

But that also means file handlers can't try to get their dependent file
in their preserve() callback, since that would implicitly enforce
ordering. They always _have_ to do it from their freeze() callback.

Similarly, on retrieve side, file handlers enforce their dependent files
are restored via the can_finish() callback only.

So I think the next steps for this series is to clearly document this
requirement for file handlers in the documentation for
liveupdate_get_token_outgoing() and liveupdate_get_file_incoming().

Also, I think you need some way of tracking if the file was explicitly
restored by userspace, which is something file handlers would then need
to call in their can_finish().

[...]

-- 
Regards,
Pratyush Yadav