app_shmem: renamespace and document

The public APIs for application shared memory are now
properly documented and conform to zephyr naming
conventions.

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

doc/kernel/usermode/usermode_sharedmem.rst

@@ -37,11 +37,11 @@ The general usage is as follows. Define CONFIG_APP_SHARED_MEM=y in the
 proj.conf file in the project folder.  Include app_memory/app_memdomain.h
 in the userspace source file.  Mark the variable to be placed in
 a memory partition.  The two markers are for data and bss respectively:
-_app_dmem(id) and _app_bmem(id).  The id is used as the partition name.
+K_APP_DMEM(id) and K_APP_BMEM(id).  The id is used as the partition name.
 The resulting section name can be seen in the linker.map as
 "data_smem_id" and "data_smem_idb".
 
-To create a k_mem_partition, call the macro appmem_partition(part0)
+To create a k_mem_partition, call the macro K_APPMEM_PARTITION_DEFINE(part0)
 where "part0" is the name then used to refer to that partition.
 This macro only creates a function and necessary data structures for
 the later "initialization".
@@ -55,12 +55,12 @@ Example:
 .. code-block:: c
 
             /* create partition at top of file outside functions */
-            appmem_partition(part0);
+            K_APPMEM_PARTITION_DEFINE(part0);
             /* create domain */
             struct k_mem_domain dom0;
             /* assign variables to the domain */
-            _app_dmem(part0) int var1;
+            K_APP_DMEM(part0) int var1;
-            _app_bmem(part0) static volatile int var2;
+            K_APP_BMEM(part0) static volatile int var2;
 
             int main()
             {
@@ -78,7 +78,7 @@ app_macro_support.h:
 
 .. code-block:: c
 
- FOR_EACH(appmem_partition, part0, part1, part2);
+ FOR_EACH(K_APPMEM_PARTITION_DEFINE, part0, part1, part2);
 
 Similarly, the appmem_init_part_* can also be used in the macro:
 

include/app_memory/app_memdomain.h

@@ -34,17 +34,27 @@
 	__attribute__((aligned(MEM_DOMAIN_ALIGN_SIZE), \
 		section("data_smem_" #id "b")))
 
-/*
+/**
- * Qualifier to collect any object preceded with _app
+ * @brief Place data in a partition's data section
- * and place into section "data_smem_".
+ *
- * _app_dmem(#) is for variables meant to be stored in .data .
+ * Globals tagged with this will end up in the data section for the
- * _app_bmem(#) is intended for static variables that are
+ * specified memory partition. This data should be initalized to some
- * initialized to zero.
+ * desired value.
+ *
+ * @param id Name of the memory partition to associate this data
  */
-#define _app_dmem(id) \
+#define K_APP_DMEM(id) \
 	__attribute__((section("data_smem_" #id)))
 
-#define _app_bmem(id) \
+/**
+ * @brief Place data in a partition's bss section
+ *
+ * Globals tagged with this will end up in the bss section for the
+ * specified memory partition. This data will be zeroed at boot.
+ *
+ * @param id Name of the memory partition to associate this data
+ */
+#define K_APP_BMEM(id) \
 	__attribute__((section("data_smem_" #id "b")))
 
 /*
@@ -77,7 +87,19 @@ struct app_region {
 #define smem_size_assign(name)
 #endif	/* CONFIG_MPU_REQUIRES_POWER_OF_TWO_ALIGNMENT */
 
-#define appmem_partition(name) \
+/**
+ * @brief Define an application memory partition with linker support
+ *
+ * Defines a k_mem_paritition with the provided name.
+ * This name may be used with the K_APP_DMEM and K_APP_BMEM macros to
+ * place globals automatically in this partition.
+ *
+ * NOTE: placeholder char variable is defined here to prevent build errors
+ * if a partition is defined but nothing ever placed in it.
+ *
+ * @param name Name of the k_mem_partition to declare
+ */
+#define K_APPMEM_PARTITION_DEFINE(name) \
 	extern char *data_smem_##name; \
 	extern char *data_smem_##name##b; \
 	smem_size_declare(name);		  \

samples/userspace/shared_mem/src/main.c

@@ -27,7 +27,7 @@
  */
 
 /* prepare the memory partition structures  */
-FOR_EACH(appmem_partition, part0, part1, part2, part3, part4);
+FOR_EACH(K_APPMEM_PARTITION_DEFINE, part0, part1, part2, part3, part4);
 /* prepare the memory domain structures  */
 struct k_mem_domain dom0, dom1, dom2;
 /* each variable starts with a name defined in main.h

samples/userspace/shared_mem/src/main.h

@@ -24,20 +24,20 @@ void enc(void);
 void pt(void);
 void ct(void);
 
-#define _app_user_d _app_dmem(part0)
+#define _app_user_d K_APP_DMEM(part0)
-#define _app_user_b _app_bmem(part0)
+#define _app_user_b K_APP_BMEM(part0)
 
-#define _app_red_d _app_dmem(part1)
+#define _app_red_d K_APP_DMEM(part1)
-#define _app_red_b _app_bmem(part1)
+#define _app_red_b K_APP_BMEM(part1)
 
-#define _app_enc_d _app_dmem(part2)
+#define _app_enc_d K_APP_DMEM(part2)
-#define _app_enc_b _app_bmem(part2)
+#define _app_enc_b K_APP_BMEM(part2)
 
-#define _app_blk_d _app_dmem(part3)
+#define _app_blk_d K_APP_DMEM(part3)
-#define _app_blk_b _app_bmem(part3)
+#define _app_blk_b K_APP_BMEM(part3)
 
-#define _app_ct_d _app_dmem(part4)
+#define _app_ct_d K_APP_DMEM(part4)
-#define _app_ct_b _app_bmem(part4)
+#define _app_ct_b K_APP_BMEM(part4)
 
 /*
  * Constant

tests/kernel/mem_protect/userspace/src/main.c

@@ -38,7 +38,7 @@ K_SEM_DEFINE(expect_fault_sem, 0, 1);
  * ztest and this test suite. part1 and part2 are for
  * subsequent test specifically for this new implementation.
  */
-FOR_EACH(appmem_partition, part0, part1, part2);
+FOR_EACH(K_APPMEM_PARTITION_DEFINE, part0, part1, part2);
 
 /*
  * Create memory domains. dom0 is for the ztest and this
@@ -48,10 +48,10 @@ FOR_EACH(appmem_partition, part0, part1, part2);
 struct k_mem_domain dom0;
 struct k_mem_domain dom1;
 
-_app_dmem(part0) static volatile bool give_uthread_end_sem;
+K_APP_DMEM(part0) static volatile bool give_uthread_end_sem;
-_app_dmem(part0) bool mem_access_check;
+K_APP_DMEM(part0) bool mem_access_check;
 
-_app_bmem(part0) static volatile bool expect_fault;
+K_APP_BMEM(part0) static volatile bool expect_fault;
 
 #if defined(CONFIG_X86)
 #define REASON_HW_EXCEPTION _NANO_ERR_CPU_EXCEPTION
@@ -65,7 +65,7 @@ _app_bmem(part0) static volatile bool expect_fault;
 #else
 #error "Not implemented for this architecture"
 #endif
-_app_bmem(part0) static volatile unsigned int expected_reason;
+K_APP_BMEM(part0) static volatile unsigned int expected_reason;
 
 /*
  * We need something that can act as a memory barrier
@@ -312,15 +312,15 @@ static void write_kernel_data(void)
 /*
  * volatile to avoid compiler mischief.
  */
-_app_dmem(part0) volatile int *priv_stack_ptr;
+K_APP_DMEM(part0) volatile int *priv_stack_ptr;
 #if defined(CONFIG_X86)
 /*
  * We can't inline this in the code or make it static
  * or local without triggering a warning on -Warray-bounds.
  */
-_app_dmem(part0) size_t size = MMU_PAGE_SIZE;
+K_APP_DMEM(part0) size_t size = MMU_PAGE_SIZE;
 #elif defined(CONFIG_ARC)
-_app_dmem(part0) s32_t size = (0 - CONFIG_PRIVILEGED_STACK_SIZE -
+K_APP_DMEM(part0) s32_t size = (0 - CONFIG_PRIVILEGED_STACK_SIZE -
 			       STACK_GUARD_SIZE);
 #endif
 
@@ -377,7 +377,7 @@ static void write_priv_stack(void)
 }
 
 
-_app_bmem(part0) static struct k_sem sem;
+K_APP_BMEM(part0) static struct k_sem sem;
 
 /**
  * @brief Test to pass a user object to system call
@@ -582,7 +582,7 @@ static void user_mode_enter(void)
 
 /* Define and initialize pipe. */
 K_PIPE_DEFINE(kpipe, PIPE_LEN, BYTES_TO_READ_WRITE);
-_app_bmem(part0) static size_t bytes_written_read;
+K_APP_BMEM(part0) static size_t bytes_written_read;
 
 /**
  * @brief Test to write to kobject using pipe
@@ -634,7 +634,7 @@ static void read_kobject_user_pipe(void)
  */
 
 /* Create bool in part1 partitions */
-_app_dmem(part1) bool thread_bool;
+K_APP_DMEM(part1) bool thread_bool;
 
 static void shared_mem_thread(void)
 {

tests/ztest/include/ztest_test.h

@@ -144,8 +144,8 @@ static inline void unit_test_noop(void)
 
 /* definitions for use with testing application shared memory   */
 #ifdef CONFIG_APP_SHARED_MEM
-#define APPDMEMP0 _app_dmem(part0)
+#define APPDMEMP0 K_APP_DMEM(part0)
-#define APPBMEMP0 _app_bmem(part0)
+#define APPBMEMP0 K_APP_BMEM(part0)
 #else
 #define APPDMEMP0
 #define APPBMEMP0