# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1705270678 -3600
# Node ID 3e3727528566d2e7664194aaf5a91514383623a0
# Parent  c0137675a035ef1969508f88eab9f447e2cb9817
Introduced a separate capability receiving operation for clients in place of
ipc_message_expect which reserves capability slots, this being appropriate only
for servers generally expecting capabilities in messages, being inappropriate
for message items representing flexpages.
Separated capability and dataspace import operations into client and server
variants, avoiding capability allocation in clients where such allocation will
occur explicitly in advance and where messages will also not be reused.

diff -r c0137675a035 -r 3e3727528566 libipc/include/ipc/message.h
--- a/libipc/include/ipc/message.h	Sun Jan 14 00:45:39 2024 +0100
+++ b/libipc/include/ipc/message.h	Sun Jan 14 23:17:58 2024 +0100
@@ -1,7 +1,7 @@
 /*
  * Interprocess communication message abstraction.
  *
- * Copyright (C) 2018, 2019, 2021, 2022 Paul Boddie <paul@boddie.org.uk>
+ * Copyright (C) 2018, 2019, 2021, 2022, 2024 Paul Boddie <paul@boddie.org.uk>
  *
  * This program is free software; you can redistribute it and/or
  * modify it under the terms of the GNU General Public License as
@@ -113,6 +113,7 @@
 void ipc_message_add_item(ipc_message_t *msg, l4_cap_idx_t cap);
 void ipc_message_add_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage);
 void ipc_message_add_page(ipc_message_t *msg, l4_umword_t hot_spot, l4_fpage_t fpage);
+void ipc_message_add_receive_capability(ipc_message_t *msg, l4_cap_idx_t /* cap */);
 void ipc_message_add_receive_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage);
 void ipc_message_add_string(ipc_message_t *msg, const char *value);
 void ipc_message_add_word(ipc_message_t *msg, l4_umword_t value);
@@ -137,6 +138,8 @@
 void ipc_message_export_capability(ipc_message_t *msg, int item, l4_cap_idx_t ref);
 void ipc_message_export_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t fpage);
 void ipc_message_export_page(ipc_message_t *msg, int item, l4_umword_t hot_spot, l4_fpage_t fpage);
+long ipc_message_import_and_expect_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref);
+long ipc_message_import_and_expect_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr);
 long ipc_message_import_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref);
 long ipc_message_import_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr);
 long ipc_message_import_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t *fpage);
diff -r c0137675a035 -r 3e3727528566 libipc/lib/src/message.c
--- a/libipc/lib/src/message.c	Sun Jan 14 00:45:39 2024 +0100
+++ b/libipc/lib/src/message.c	Sun Jan 14 23:17:58 2024 +0100
@@ -50,7 +50,9 @@
     ipc_cap_free_um(msg->to_discard[i]);
 }
 
-/* Initialise a message structure with the given number of expected items. */
+/* Initialise a message structure with the given number of expected items. This
+   function is primarily for the use of servers needing to reserve items that
+   might be sent in messages from clients. */
 
 long ipc_message_expect(ipc_message_t *msg, unsigned int expected_items)
 {
@@ -271,6 +273,15 @@
     ipc_message_export_fpage(msg, msg->items++, fpage);
 }
 
+/* Add the expectation of a capability. Note that a capability is accepted as a
+   parameter but ignored, this being for the convenience of code generation. */
+
+void ipc_message_add_receive_capability(ipc_message_t *msg, l4_cap_idx_t cap)
+{
+  (void) cap;
+  return _expect_capability(&msg->bregs, msg->receive_items++);
+}
+
 /* Add a receive window flexpage item to the message. */
 
 void ipc_message_add_receive_fpage(ipc_message_t *msg, l4_snd_fpage_t fpage)
@@ -486,7 +497,7 @@
 /* Import from the message the capability at the given item position, updating
    the buffer registers for future capabilities. */
 
-long ipc_message_import_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref)
+long ipc_message_import_and_expect_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref)
 {
   long err;
   int local;
@@ -504,7 +515,7 @@
 /* Import from the message a dataspace, mapping it to an address, updating the
    buffer registers for future capabilities. */
 
-long ipc_message_import_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr)
+long ipc_message_import_and_expect_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr)
 {
   long err;
   int local;
@@ -519,6 +530,24 @@
   return ipc_message_expect_capability(msg, item);
 }
 
+/* Import from the message the capability at the given item position. */
+
+long ipc_message_import_capability(ipc_message_t *msg, int item, l4_cap_idx_t *ref)
+{
+  int local;
+
+  return _import_capability(msg->tag, &msg->bregs, &msg->mregs, item, ref, &local);
+}
+
+/* Import from the message a dataspace, mapping it to an address. */
+
+long ipc_message_import_dataspace(ipc_message_t *msg, int item, l4re_ds_t *mem, l4_addr_t *addr)
+{
+  int local;
+
+  return _import_dataspace(msg->tag, &msg->bregs, &msg->mregs, item, mem, addr, &local);
+}
+
 /* Import from the message the flexpage at the given item position. */
 
 long ipc_message_import_fpage(ipc_message_t *msg, int item, l4_snd_fpage_t *fpage)