[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 1/6] mm: document grub internal memory management structures
From: |
Daniel Axtens |
Subject: |
[PATCH 1/6] mm: document grub internal memory management structures |
Date: |
Thu, 25 Nov 2021 02:22:45 +1100 |
I spent more than a trivial quantity of time figuring out pre_size and
whether a memory region's size contains the header cell or not.
Document the meanings of all the properties. Hopefully now no-one else
has to figure it out!
Signed-off-by: Daniel Axtens <dja@axtens.net>
---
This version: thanks to Glenn Washburn for catching various issues.
---
include/grub/mm_private.h | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/include/grub/mm_private.h b/include/grub/mm_private.h
index c2c4cb1511c6..203533cc3d42 100644
--- a/include/grub/mm_private.h
+++ b/include/grub/mm_private.h
@@ -21,15 +21,27 @@
#include <grub/mm.h>
+/* For context, see kern/mm.c */
+
/* Magic words. */
#define GRUB_MM_FREE_MAGIC 0x2d3c2808
#define GRUB_MM_ALLOC_MAGIC 0x6db08fa4
+/* A header describing a block of memory - either allocated or free */
typedef struct grub_mm_header
{
+ /*
+ * The 'next' free block in this region's circular free list.
+ * Only meaningful if the block is free.
+ */
struct grub_mm_header *next;
+ /* The block size, not in bytes but the number of cells of
+ * GRUB_MM_ALIGN bytes. Includes the header cell.
+ */
grub_size_t size;
+ /* either free or alloc magic, depending on the block type. */
grub_size_t magic;
+ /* pad to cell size: see the top of kern/mm.c. */
#if GRUB_CPU_SIZEOF_VOID_P == 4
char padding[4];
#elif GRUB_CPU_SIZEOF_VOID_P == 8
@@ -48,11 +60,27 @@ typedef struct grub_mm_header
#define GRUB_MM_ALIGN (1 << GRUB_MM_ALIGN_LOG2)
+/* A region from which we can make allocations. */
typedef struct grub_mm_region
{
+ /* The first free block in this region. */
struct grub_mm_header *first;
+
+ /*
+ * The next region in the linked list of regions. Regions are initially
+ * sorted in order of increasing size, but can grow, in which case the
+ * ordering may not be preserved.
+ */
struct grub_mm_region *next;
+
+ /*
+ * A grub_mm_region will always be aligned to cell size. The pre-size is
+ * the number of bytes we were given but had to skip in order to get that
+ * alignment.
+ */
grub_size_t pre_size;
+
+ /* How many bytes are in this region? (free and allocated) */
grub_size_t size;
}
*grub_mm_region_t;
--
2.32.0
- [PATCH 0/6] Document mm, Daniel Axtens, 2021/11/24
- [PATCH 1/6] mm: document grub internal memory management structures,
Daniel Axtens <=
- [PATCH 4/6] mm: document grub_free, Daniel Axtens, 2021/11/24
- [PATCH 3/6] mm: grub_real_malloc: make small allocs comment match code, Daniel Axtens, 2021/11/24
- [PATCH 5/6] mm: document grub_mm_init_region, Daniel Axtens, 2021/11/24
- [PATCH 6/6] [RFC] docs: document mm, Daniel Axtens, 2021/11/24
- [PATCH 2/6] mm: clarify grub_real_malloc, Daniel Axtens, 2021/11/24