From 4819016a3c485328067fe3e5745196c6933b8f9b Mon Sep 17 00:00:00 2001 From: David Nadlinger Date: Wed, 9 Nov 2022 21:06:14 +0000 Subject: [PATCH] firmware/ksupport: Document rpc_recv alignment requirements [nfc] --- artiq/firmware/ksupport/lib.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/artiq/firmware/ksupport/lib.rs b/artiq/firmware/ksupport/lib.rs index 2e7346c19..d9786ae3c 100644 --- a/artiq/firmware/ksupport/lib.rs +++ b/artiq/firmware/ksupport/lib.rs @@ -156,6 +156,21 @@ extern fn rpc_send_async(service: u32, tag: &CSlice, data: *const *const ()) }) } + +/// Receives the result from an RPC call into the given memory buffer. +/// +/// To handle aggregate objects with an a priori unknown size and number of +/// sub-allocations (e.g. a list of list of lists, where, at each level, the number of +/// elements is not statically known), this function needs to be called in a loop: +/// +/// On the first call, `slot` should be a buffer of suitable size and alignment for +/// the top-level return value (e.g. in the case of a list, the pointer/length pair). +/// A return value of zero indicates that the value has been completely received. +/// As long as the return value is positive, another allocation with the given number of +/// bytes is needed, so the function should be called again with such a buffer (aligned +/// to the maximum required for any of the possible types according to the target ABI). +/// +/// If the RPC call resulted in an exception, it is reconstructed and raised. #[unwind(allowed)] extern fn rpc_recv(slot: *mut ()) -> usize { send(&RpcRecvRequest(slot));