Clean up system address map definitions (#95)

* Rename/rework/clean up definitions related to system memory map to align with ACPI. * Rename `GET_USER_MEMORY` system call to `GET_ADDRESS_MAP` and be more consistent with naming. Unrelated cleanup: * Ensure there are no remaining tabs use for indentation. * Make sure no source file is set executable.
phaubertin · Dec 1, 2024 · c9537bc · c9537bc
1 parent 7a8e0e9
commit c9537bc
Show file tree

Hide file tree

Showing 65 changed files with 577 additions and 423 deletions.
diff --git a/doc/Doxyfile b/doc/Doxyfile
diff --git a/doc/init-process.md b/doc/init-process.md
@@ -230,7 +230,7 @@ An empty message with message number 4096 (JINUE_MSG_GET_MEMINFO)
 allows the initial process to request information from the loader
 regarding memory it has used to extract the initial RAM disk and for
 the initial process itself. This information should be used alongside
-the information from the [GET_USER_MEMORY](syscalls/get-user-memory.md)
+the information from the [GET_ADDRESS_MAP](syscalls/get-address-map.md)
 system call to determine what memory is available for use.
 
 Note the loader does not report information about memory it itself is
@@ -296,7 +296,7 @@ The memory information structure contains the following members:
 
 As long as the loader has exited, the initial process is free to 
 allocate memory anywhere that is described as user memory by the kernel 
-memory map (see the [GET_USER_MEMORY](syscalls/get-user-memory.md) 
+memory map (see the [GET_ADDRESS_MAP](syscalls/get-address-map.md) 
 system call) and that is not identified as in use by one of the segment 
 structures. It is also free to either map the extracted RAM disk for 
 its own use or instead reclaim that memory. However, early in its 
@@ -330,7 +330,7 @@ Segments may overlap in the following ways:
 * Future direction: if the RAM disk image has the right format and is
   uncompressed, the memory range of the extracted RAM disk might be
   identical to the RAM disk image as described by the
-  [GET_USER_MEMORY](syscalls/get-user-memory.md) system call, i.e. the
+  [GET_ADDRESS_MAP](syscalls/get-address-map.md) system call, i.e. the
   loader might be using the RAM disk image in place.
 
 #### The Mapping Structure

diff --git a/doc/layout.md b/doc/layout.md
@@ -96,7 +96,7 @@ looks like this:
   |         kernel command line           |                              | allocations
   +---------------------------------------+ bootinfo.cmdline             |
   |       BIOS physical memory map        |                              |
-  +---------------------------------------+ bootinfo.e820_map            |    
+  +---------------------------------------+ bootinfo.acpi_addr_map            |    
   |         kernel data segment           |                              |                ^
   |                                       |                              |                |
   +---------------------------------------+ bootinfo.data_physaddr     -+-       address |

diff --git a/doc/syscalls/README.md b/doc/syscalls/README.md
@@ -14,7 +14,7 @@
 | 5       | [YIELD_THREAD](yield-thread.md)         | Yield the Current Thread             |
 | 6       | [SET_THREAD_LOCAL](set-thread-local.md) | Set Thread-Local Storage             |
 | 7       | -                                       | Reserved                             |
-| 8       | [GET_USER_MEMORY](get-user-memory.md)   | Get User Memory Map                  |
+| 8       | [GET_ADDRESS_MAP](get-address-map.md)   | Get Memory Address Map               |
 | 9       | [CREATE_ENDPOINT](create-endpoint.md)   | Create IPC Endpoint                  |
 | 10      | [RECEIVE](receive.md)                   | Receive Message                      |
 | 11      | [REPLY](reply.md)                       | Reply to Message                     |

diff --git a/doc/syscalls/get-address-map.md b/doc/syscalls/get-address-map.md
@@ -0,0 +1,107 @@
+# GET_ADDRESS_MAP - Get Memory Address Map
+
+## Description
+
+This function writes the system and kernel memory address map to a buffer
+provided by the caller.
+
+Specifically, the data written in the buffer is a
+[jinue_addr_map_t structure](../../include/jinue/shared/types.h) (the header)
+followed by an array of
+[jinue_addr_map_entry_t structures](../../include/jinue/shared/types.h) (the map
+entries).
+
+Each map entry describes a contiguous block of memory. Some entries describe
+memory regions reported by the system firmware whereas other entries describe
+memory regions of interest reported by the kernel itself.
+
+The header contains a single 32-bit field (`num_entries`) that specifies the
+number of map entries. If the call fails with `JINUE_E2BIG`, which indicates the
+buffer it too small to receive the full memory map, the kernel still sets this
+field to the total number of map entries, as long as the buffer is at least
+large enough for the header.
+
+Each map entry contains the following fields, in this order:
+
+* `addr` (64 bits) the address of the start of the memory block.
+* `size` (64 bits) the size of the block, in bytes.
+* `type` (32 bits) the type of the block.
+
+The type numbers are described in the table below and are based on the
+[ACPI address range types](https://uefi.org/specs/ACPI/6.4_A/15_System_Address_Map_Interfaces.html).
+
+| Type Number | Name                            | Description                                                                                                                                                                                   |
+|-------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1           | `JINUE_MEMYPE_MEMORY`           | Memory available for use.<br><br>Equivalent to ACPI address range type `AddressRangeMemory`.                                                                                                  |
+| 2           | `JINUE_MEMYPE_RESERVED`         | Reserved, do not use.<br><br>Equivalent to ACPI address range type `AddressRangeReserved`.                                                                                                    |
+| 3           | `JINUE_MEMYPE_ACPI`             | ACPI tables are located in this range. Once the ACPI tables are no longer needed, this range can be used as normal memory.<br><br>Equivalent to ACPI address range type `AddressRangeACPI`.   |
+| 4           | `JINUE_MEMYPE_NVS`              | Reserved, do not use. Must be saved and restored across Non-Volatile Sleep (NVS).<br><br>Equivalent to ACPI address range type `AddressRangeNVS`.                                             |
+| 5           | `JINUE_MEMYPE_UNUSABLE`         | Reserved, do not use.<br><br>Equivalent to ACPI address range type `AddressRangeUnusable`.                                                                                                    |
+| 6           | `JINUE_MEMYPE_DISABLED`         | Reserved, do not use.<br><br>Equivalent to ACPI address range type `AddressRangeDisabled`.                                                                                                    |
+| 7           | `JINUE_MEMYPE_PERSISTENT`       | This range is available for use and has byte-addressable non-volatile memory rather that standard RAM.<br><br>Equivalent to ACPI address range type `AddressRangePersistent-Memory`.          |
+| 12/0xc      | `JINUE_MEMYPE_OEM`              | Reserved, do not use.<br><br>Equivalent to ACPI "OEM defined" address range type.                                                                                                             |
+| 0xf0000000  | `JINUE_MEMYPE_KERNEL_RESERVED`  | Memory reserved for kernel use. This address range cannot be mapped in user space.<br><br>Ranges of this type are page aligned.<br><br>See the Future Direction section below.                |
+| 0xf0000001  | `JINUE_MEMYPE_KERNEL_IMAGE`     | Kernel image.<br><br>This address range can be mapped read only in user space. There will be exactly one entry with this type. This range is page aligned.                                    |
+| 0xf0000002  | `JINUE_MEMYPE_RAMDISK`          | Compressed RAM disk image.<br><br>This address range can be mapped read only in user space. There will be exactly one entry with this type. This range is page aligned.                       |
+| 0xf0000003  | `JINUE_MEMYPE_LOADER_AVAILABLE` | This entry is a hint to the user space loader for memory that it can use for it's own needs. The [Get Memory Information](../init-process.md#get-memory-information-jinue_msg_get_meminfo) message provides a similar functionality for the initial process.<br><br>There will be exactly one entry with this type. This range is page aligned. |
+| Any Other   | N/A                             | Reserved, do not use. Should be treated in the same way as a `JINUE_MEMYPE_RESERVED` range.                                                                                                   |
+
+Notes:
+
+* The system ranges comes directly from the memory map provided by the system
+  firmware, without filtering or processing. No assumption should be made
+  regarding alignment, overlap, etc.
+* A memory manager in user space should use the information reported by this
+  function in conjunction with the information provided by the
+  [Get Memory Information](../init-process.md#get-memory-information-jinue_msg_get_meminfo)
+  message of the [Initial Process Execution Environment](../init-process.md) to
+  determine which memory ranges it can allocate to applications.
+
+## Arguments
+
+Function number (`arg0`) is 8.
+
+A pointer to the destination buffer is set in `arg1`. The size of the buffer is
+set in `arg2`.
+
+```
+    +----------------------------------------------------------------+
+    |                         function = 8                           |  arg0
+    +----------------------------------------------------------------+
+    31                                                               0
+    
+    +----------------------------------------------------------------+
+    |                        buffer address                          |  arg1
+    +----------------------------------------------------------------+
+    31                                                               0
+
+    +----------------------------------------------------------------+
+    |                         buffer size                            |  arg2
+    +----------------------------------------------------------------+
+    31                                                               0
+
+    +----------------------------------------------------------------+
+    |                         reserved (0)                           |  arg3
+    +----------------------------------------------------------------+
+    31                                                               0
+```
+
+## Return Value
+
+On success, this function returns 0 (in `arg0`). On failure, it returns -1 and
+an error number is set (in `arg1`).
+
+## Errors
+
+* JINUE_EINVAL if any part of the destination buffer belongs to the kernel.
+* JINUE_E2BIG if the output buffer is too small to fit the result.
+
+## Future Direction
+
+The memory map reported by this function is static and represents the situation
+at the start of the initial user space process. System calls will be added that
+will allow a memory manager in user space to give memory to or reclaim memory
+from the kernel. The user space memory manager will be responsible for keeping
+track of memory ownership changes that it causes. The memory map reported by
+this function, specifically the `JINUE_MEMYPE_KERNEL_RESERVED` entries, will not
+reflect these changes.
diff --git a/doc/syscalls/get-user-memory.md b/doc/syscalls/get-user-memory.md
diff --git a/include/assert.h b/include/assert.h
diff --git a/include/ctype.h b/include/ctype.h
diff --git a/include/errno.h b/include/errno.h
diff --git a/include/internals.h b/include/internals.h
diff --git a/include/inttypes.h b/include/inttypes.h
diff --git a/include/jinue/jinue.h b/include/jinue/jinue.h
@@ -37,7 +37,7 @@
 #include <jinue/shared/asm/logging.h>
 #include <jinue/shared/asm/machine.h>
 #include <jinue/shared/asm/mman.h>
-#include <jinue/shared/asm/memory.h>
+#include <jinue/shared/asm/memtype.h>
 #include <jinue/shared/asm/permissions.h>
 #include <jinue/shared/asm/stack.h>
 #include <jinue/shared/asm/syscalls.h>
@@ -65,7 +65,7 @@ void jinue_putc(char c);
 
 int jinue_puts(int loglevel, const char *str, size_t n, int *perrno);
 
-int jinue_get_user_memory(jinue_mem_map_t *buffer, size_t buffer_size, int *perrno);
+int jinue_get_address_map(const jinue_buffer_t *buffer, int *perrno);
 
 int jinue_mmap(
         int          process,

diff --git a/include/jinue/shared/asm/memtype.h b/include/jinue/shared/asm/memtype.h
@@ -0,0 +1,62 @@
+/*
+ * Copyright (C) 2023-2024 Philippe Aubertin.
+ * All rights reserved.
+
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 
+ * 3. Neither the name of the author nor the names of other contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef _JINUE_SHARED_ASM_MEMTYPE_H
+#define _JINUE_SHARED_ASM_MEMTYPE_H
+
+/* Assignments: use the same values as the ACPI/e820 address range types. Use
+ * the 0xf0000000 to 0xffffffff OEM defined range for custom values. */
+
+#define JINUE_MEMYPE_MEMORY             1
+
+#define JINUE_MEMYPE_RESERVED           2
+
+#define JINUE_MEMYPE_ACPI               3
+
+#define JINUE_MEMYPE_NVS                4
+
+#define JINUE_MEMYPE_UNUSABLE           5
+
+#define JINUE_MEMYPE_DISABLED           6
+
+#define JINUE_MEMYPE_PERSISTENT         7
+
+#define JINUE_MEMYPE_OEM                12
+
+#define JINUE_MEMYPE_KERNEL_RESERVED    0xf0000000
+
+#define JINUE_MEMYPE_KERNEL_IMAGE       (JINUE_MEMYPE_KERNEL_RESERVED + 1)
+
+#define JINUE_MEMYPE_RAMDISK            (JINUE_MEMYPE_KERNEL_RESERVED + 2)
+
+#define JINUE_MEMYPE_LOADER_AVAILABLE   (JINUE_MEMYPE_KERNEL_RESERVED + 3)
+
+#endif