unified: Tweak mem_map API parameters

- Reorders parameters where necessary
 - Adds buffer alignment parameter to K_MEM_MAP_DEFINE()

Change-Id: Ifa1a09c62492cd6db8bdd83f31a5ca5ba072b484
Signed-off-by: Peter Mitsis <peter.mitsis@windriver.com>

doc/kernel_v2/memory/maps.rst

@@ -63,14 +63,14 @@ A memory map is defined using a variable of type :c:type:`struct k_mem_map`.
 It must then be initialized by calling :cpp:func:`k_mem_map_init()`.
 
 The following code defines and initializes a memory map that has 6 blocks
-of 400 bytes each.
+of 400 bytes each and is aligned to a 4-byte boundary..
 
 .. code-block:: c
 
     struct k_mem_map my_map;
-    char my_map_buffer[6 * 400];
+    char __aligned(4) my_map_buffer[6 * 400];
 
-    k_mem_map_init(&my_map, 6, 400, my_map_buffer);
+    k_mem_map_init(&my_map, my_map_buffer, 400, 6);
 
 Alternatively, a memory map can be defined and initialized at compile time
 by calling :c:macro:`K_MEM_MAP_DEFINE()`.
@@ -80,7 +80,7 @@ that the macro defines both the memory map and its buffer.
 
 .. code-block:: c
 
-    K_MEM_MAP_DEFINE(my_map, 6, 400);
+    K_MEM_MAP_DEFINE(my_map, 400, 6, 4);
 
 Allocating a Memory Block
 =========================

include/kernel.h

@@ -1196,8 +1196,7 @@ struct k_mem_map {
 	_DEBUG_TRACING_KERNEL_OBJECTS_NEXT_PTR(k_mem_map);
 };
 
-#define K_MEM_MAP_INITIALIZER(obj, map_num_blocks, map_block_size, \
+#define K_MEM_MAP_INITIALIZER(obj, map_buffer, map_block_size, map_num_blocks) \
-			      map_buffer) \
 	{ \
 	.wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
 	.num_blocks = map_num_blocks, \
@@ -1208,15 +1207,32 @@ struct k_mem_map {
 	_DEBUG_TRACING_KERNEL_OBJECTS_INIT \
 	}
 
-#define K_MEM_MAP_DEFINE(name, map_num_blocks, map_block_size) \
+/**
-	char _k_mem_map_buf_##name[(map_num_blocks) * (map_block_size)]; \
+ * @brief Define a memory map
-	struct k_mem_map name \
+ *
-		__in_section(_k_mem_map_ptr, private, mem_map) = \
+ * This declares and initializes a memory map whose buffer is aligned to
-		K_MEM_MAP_INITIALIZER(name, map_num_blocks, \
+ * a @a map_align -byte boundary. The new memory map can be passed to the
-				      map_block_size, _k_mem_map_buf_##name)
+ * kernel's memory map functions.
+ *
+ * Note that for each of the blocks in the memory map to be aligned to
+ * @a map_align bytes, then @a map_block_size must be a multiple of
+ * @a map_align.
+ *
+ * @param name Name of the memory map
+ * @param map_block_size Size of each block in the buffer (in bytes)
+ * @param map_num_blocks Number blocks in the buffer
+ * @param map_align Alignment of the memory map's buffer (power of 2)
+ */
+#define K_MEM_MAP_DEFINE(name, map_block_size, map_num_blocks, map_align)   \
+	char __aligned(map_align)                                           \
+		_k_mem_map_buf_##name[(map_num_blocks) * (map_block_size)]; \
+	struct k_mem_map name                                               \
+		__in_section(_k_mem_map_ptr, private, mem_map) =            \
+		K_MEM_MAP_INITIALIZER(name, _k_mem_map_buf_##name,          \
+				      map_block_size, map_num_blocks)
 
-extern void k_mem_map_init(struct k_mem_map *map, int num_blocks,
+extern void k_mem_map_init(struct k_mem_map *map, void *buffer,
-			   int block_size, void *buffer);
+			   int block_size, int num_blocks);
 extern int k_mem_map_alloc(struct k_mem_map *map, void **mem, int32_t timeout);
 extern void k_mem_map_free(struct k_mem_map *map, void **mem);
 

include/legacy.h

@@ -395,8 +395,8 @@ static inline int task_mem_map_alloc(kmemory_map_t map, void **mptr,
 #define task_mem_map_used_get k_mem_map_num_used_get
 
 #define DEFINE_MEM_MAP(name, map_num_blocks, map_block_size) \
-	K_MEM_MAP_DEFINE(_k_mem_map_obj_##name, \
+	K_MEM_MAP_DEFINE(_k_mem_map_obj_##name, map_block_size, \
-			 map_num_blocks, map_block_size); \
+			 map_num_blocks, 4); \
 	struct k_mem_map *const name = &_k_mem_map_obj_##name
 
 

kernel/unified/mem_map.c

@@ -75,14 +75,14 @@ static int init_mem_map_module(struct device *dev)
  * Initializes the memory map and creates its list of free blocks.
  *
  * @param map Address of memory map.
- * @param num_blocks Number of blocks.
- * @param block_size Size of each block, in bytes.
  * @param buffer Pointer to buffer used for the blocks.
+ * @param block_size Size of each block, in bytes.
+ * @param num_blocks Number of blocks.
  *
  * @return N/A
  */
-void k_mem_map_init(struct k_mem_map *map, int num_blocks, int block_size,
+void k_mem_map_init(struct k_mem_map *map, void *buffer,
-		    void *buffer)
+		    int block_size, int num_blocks)
 {
 	map->num_blocks = num_blocks;
 	map->block_size = block_size;
@@ -100,9 +100,9 @@ void k_mem_map_init(struct k_mem_map *map, int num_blocks, int block_size,
  *
  * @param map Pointer to memory map object.
  * @param mem Pointer to area to receive block address.
- * @param timeout Maximum time (nanoseconds) to wait for allocation to complete.
+ * @param timeout Maximum time (milliseconds) to wait for allocation to
- *        Use K_NO_WAIT to return immediately, or K_FOREVER to wait as long as
+ *        complete.  Use K_NO_WAIT to return immediately, or K_FOREVER to wait
- *        necessary.
+ *        as long as necessary.
  *
  * @return 0 if successful, -ENOMEM if failed immediately, -EAGAIN if timed out
  */

scripts/sysgen

@@ -788,8 +788,8 @@ def kernel_main_c_maps():
             name = map[0]
             blocks = map[1]
             block_size = map[2]
-            kernel_main_c_out("K_MEM_MAP_DEFINE(_k_mem_map_obj_%s, %s, %s);\n" %
+            kernel_main_c_out("K_MEM_MAP_DEFINE(_k_mem_map_obj_%s, %s, %s, 4);\n" %
-                              (name, blocks, block_size))
+                              (name, block_size, blocks))
 
 
 def kernel_main_c_pools():