userspace: document multiple mem domain init calls

k_mem_domain objects should not be initialized multiple times,
there's no support for memory domain life-cycles or freeing
memory that an arch_mem_domain_init() may have allocated.
Clearly document this.

The init function has to assume the provided domain is un-
initialized memory so it's not possible to robustly check
for this; a note is left in the arch_ definition to add an
assertion if feasible.

It's really unsafe to call an init function on any kernel
object more than once, but in this particular case if the
memory domain initialization resulted in the creation of
page tables or linked data structures really bad things can
happen. Currently no arch implements arch_mem_domain_init()
yet, but this is changing soon for x86.

One test case currently does this, it will be fixed in
a forthcoming patch.

Signed-off-by: Andrew Boie <andrew.p.boie@intel.com>

include/app_memory/mem_domain.h

@@ -117,6 +117,9 @@ struct k_mem_domain;
  * See documentation for k_mem_domain_add_partition() for details about
  * partition constraints.
  *
+ * Do not call k_mem_domain_init() on the same memory domain more than once,
+ * doing so is undefined behavior.
+ *
  * @param domain The memory domain to be initialized.
  * @param num_parts The number of array items of "parts" parameter.
  * @param parts An array of pointers to the memory partitions. Can be NULL

include/sys/arch_interface.h

@@ -533,6 +533,11 @@ int arch_mem_domain_max_partitions_get(void);
  * This function may fail if initializing the memory domain requires allocation,
  * such as for page tables.
  *
+ * The associated function k_mem_domain_init() documents that making
+ * multiple init calls to the same memory domain is undefined behavior,
+ * but has no assertions in place to check this. If this matters, it may be
+ * desirable to add checks for this in the implementation of this function.
+ *
  * @param domain The memory domain to initialize
  * @retval 0 Success
  * @retval -ENOMEM Insufficient memory