]> git.corax.cc Git - corax/commitdiff
kernel/arch: Reformat text flow of documentation
authorMatthias Kruk <m@m10k.eu>
Sat, 1 Aug 2020 15:59:20 +0000 (00:59 +0900)
committerMatthias Kruk <m@m10k.eu>
Sat, 1 Aug 2020 15:59:20 +0000 (00:59 +0900)
kernel/arch/paging.c

index d0eb3c4202393ea48766ec499d23f8ad6a311abb..e6b7e45bab75ad0b0f934b0494a56158b29a42ec 100644 (file)
@@ -60,8 +60,8 @@ static const char *_str_pg_mode[] = {
        "Intel64 mode"
 };
 
-static int _pg_dir_add_region(pg_dir_t*, void*, u32_t, region_type_t, page_attrs_t, region_opts_t);
-int _pg_dir_vpxlate(pg_dir_t*, u32_t, u32_t*);
+static int _pg_dir_add_region(pg_dir_t*, void*, u32_t, region_type_t,
+                             page_attrs_t, region_opts_t);
 int _pg_dir_pagesize(pg_dir_t*, u32_t, u32_t*);
 int _pg_dir_xfer(pg_dir_t*, void*, pg_dir_t*, void*, u32_t);
 static int _pg_dir_heap_map(pg_dir_t*, u32_t);
@@ -73,26 +73,26 @@ static int _pg_dir_heap_map(pg_dir_t*, u32_t);
  *  void* _phys_alloc(u32_t size, u32_t align);
  *
  * DESCRIPTION
- *  The _phys_alloc() function dynamically allocates linear memory. This function is intended
- *  to be used for memory allocations before the kernel heap has been initialized. This memory
- *  allocator is very primitive and is meant for allocations that will never be freed, such as
- *  the kernel page directory. Allocations made by this allocator will be placed in memory after
- *  ther kernel's BSS segment. Once the kernel page directory has been created, this memory
- *  region will be included in the kernel heap segment. However, the kernel heap structures will
- *  be allocated in memory behind all physical alocations, which means that they will not be
- *  accounted for by the kernel heap.
+ *  The _phys_alloc() function dynamically allocates linear memory. This function is intended to
+ *  be used for memory allocations before the kernel heap has been initialized. This memory
+ *  allocator is very primitive and is meant for allocations that will never be freed, such as the
+ *  kernel page directory. Allocations made by this allocator will be placed in memory after the
+ *  kernel's BSS segment. Once the kernel page directory has been created, this memory region will
+ *  be included in the kernel heap segment. However, the kernel heap structures will be allocated
+ *  in memory behind all physical alocations, which means that they will not be accounted for by
+ *  the kernel heap.
  *  This function will allocate `size' bytes of memory from linear memory (which means physical
- *  memory in absence of paging). If alignment is desired (i.e. `align' is non-zero), the start
- *  of the allocation will be increased until the start address is aligned correctly, in creating
- *  an (`align' - 1) bytes sized memory hole in the worst case. The allocated memory will be
- *  zeroed by the allocator.
+ *  memory in absence of paging). If alignment is desired (i.e. `align' is non-zero), the start of
+ *  the allocation will be increased until the start address is aligned correctly, in creating an
+ *  (`align' - 1) bytes sized memory hole in the worst case. The allocated memory will be zeroed
+ *  by the allocator.
  *  This allocator does not perform any error checking. If there are problems with this allocator,
  *  that means that the machine does not have enough memory to allocate the kernel page directory.
- *  Since paging was introduced with the Intel 486 and my first one had 4MB of memory, it's fair to
- *  say that this is unlikely to happen on any machine.
+ *  Since paging was introduced with the Intel 486 and my first one had 4MB of memory, it's fair
+ *  to say that this is unlikely to happen on any machine.
  *
- *  You should not be using this function. If you find yourself using this allocator, you are almost
- *  certainly doing something wrong.
+ *  You should not be using this function. If you find yourself using this allocator, you are
+ *  almost certainly doing something wrong.
  *
  * RETURN VALUE
  *  The start address of the memory allocation
@@ -129,21 +129,21 @@ static void* _phys_alloc(u32_t size, u32_t align)
  *  void* pg_frame_alloc_start(void);
  *
  * DESCRIPTION
- *  The pg_frame_alloc_start() function attempts to allocate a page frame (i.e. a physical
- *  page) from the start of the frame map. The frame map is a global structure that tracks
- *  the availability of every 4KB page frame in the machine. Simply speaking, the first bit
- *  in the frame map represents the page frame at address 0x0, the second bit represents the
- *  page frame at address 0x1000, and so on.
- *  What this function does is, get the first zero bit in the frame map, set the bit, and
- *  return the address of the page frame.
+ *  The pg_frame_alloc_start() function attempts to allocate a page frame (i.e. a physical page)
+ *  from the start of the frame map. The frame map is a global structure that tracks the
+ *  availability of every 4KB page frame in the machine. Simply speaking, the first bit in the
+ *  frame map represents the page frame at address 0x0, the second bit represents the page frame
+ *  at address 0x1000, and so on.
+ *  What this function does is, get the first zero bit in the frame map, set the bit, and return
+ *  the address of the page frame.
  *
- *  This function is used exclusively to allocate heap space for the kernel. It should never
- *  be called directly, except from the code that is responsible for the kernel heap. For
- *  page frame allocations for processes, pg_frame_alloc_end() must be used instead.
+ *  This function is used exclusively to allocate heap space for the kernel. It should never be
+ *  called directly, except from the code that is responsible for the kernel heap. For page frame
+ *  allocations for processes, pg_frame_alloc_end() must be used instead.
  *
  * RETURN VALUE
- *  On success, the linear address of the newly allocated page frame is returned. In the case
- *  of an error, NULL will be returned.
+ *  On success, the linear address of the newly allocated page frame is returned. In the case of
+ *  an error, NULL will be returned.
  *
  * ERRORS
  *  This function does not return additional information about error conditions.
@@ -153,18 +153,18 @@ void* pg_frame_alloc_start(void)
        u32_t frm;
 
        for(frm = 0; frm < _nframes; frm++) {
+               u32_t addr;
+
                /* check if there's an unused frame in this dword */
-               if(~_frame_map[frm]) {
-                       u32_t addr;
-
-                       /* find the 0 bit in _frame_map[frm] */
-                       for(addr = frm << 17;
-                           addr < ((frm + 1) << 17);
-                           addr += PAGE_SIZE) {
-                               if(!_frame_get(addr)) {
-                                       _frame_set(addr);
-                                       return((void*)addr);
-                               }
+               if(!~_frame_map[frm]) {
+                       continue;
+               }
+
+               /* find the 0 bit in _frame_map[frm] */
+               for(addr = frm << 17; addr < ((frm + 1) << 17); addr += PAGE_SIZE) {
+                       if(!_frame_get(addr)) {
+                               _frame_set(addr);
+                               return((void*)addr);
                        }
                }
        }
@@ -179,17 +179,17 @@ void* pg_frame_alloc_start(void)
  *  void* pg_frame_alloc_end(void);
  *
  * DESCRIPTION
- *  The pg_frame_alloc_end() function attempts to allocate a page frame (i.e. a physical
- *  page) from the end of the frame map. This function works essentially the same way as
+ *  The pg_frame_alloc_end() function attempts to allocate a page frame (i.e. a physical page)
+ *  from the end of the frame map. This function works essentially the same way as
  *  pg_frame_alloc_start(), except that it scans the frame map backwards.
- *  This function is intended to allocate page frames for processes. This function should
- *  be used exclusively from code that is managing the page directories, page tables, and
- *  page allocations of processes. For page frame allocations for the kernel heap, the
- *  pg_frame_alloc_start() function must be used instead.
+ *  This function is intended to allocate page frames for processes. This function should be used
+ *  exclusively from code that is managing the page directories, page tables, and page allocations
+ *  of processes. For page frame allocations for the kernel heap, the pg_frame_alloc_start()
+ *  function *must* be used instead.
  *
  * RETURN VALUE
- *  On success, the linear address of the newly allocated page frame is returned. In the case
- *  of an error, NULL will be returned.
+ *  On success, the linear address of the newly allocated page frame is returned. In the case of
+ *  an error, NULL will be returned.
  *
  * ERRORS
  *  This function does not return additional information about error conditions.
@@ -199,16 +199,16 @@ void* pg_frame_alloc_end(void)
        u32_t frm;
 
        for(frm = _nframes - 1; frm >= 0; frm--) {
-               if(~_frame_map[frm]) {
-                       u32_t addr;
-
-                       for(addr = frm << 17;
-                           addr > ((frm - 1) << 17);
-                           addr -= PAGE_SIZE) {
-                               if(!_frame_get(addr)) {
-                                       _frame_set(addr);
-                                       return((void*)addr);
-                               }
+               u32_t addr;
+
+               if(!~_frame_map[frm]) {
+                       continue;
+               }
+
+               for(addr = frm << 17; addr > ((frm - 1) << 17); addr -= PAGE_SIZE) {
+                       if(!_frame_get(addr)) {
+                               _frame_set(addr);
+                               return((void*)addr);
                        }
                }
        }
@@ -223,19 +223,18 @@ void* pg_frame_alloc_end(void)
  *  void pg_frame_free(void *addr);
  *
  * DESCRIPTION
- *  The pg_frame_free() function releases the page frame that corresponds to the address
- *  passed in `addr'. This function clears the respective bit in the frame map, so that
- *  it may be allocated for other purposes. The position in the frame map is determined
- *  by means of a simple division, which means that any address that points into the frame
- *  may be passed to this function in order to free the frame. For example, passing any
- *  address in [0, 0x1000) will cause the first page frame to be released.
+ *  The pg_frame_free() function releases the page frame that corresponds to the address passed in
+ *  `addr'. This function clears the respective bit in the frame map, so that it may be allocated
+ *  for other purposes. The position in the frame map is determined by means of a simple division,
+ *  which means that any address that points into the frame may be passed to this function in
+ *  order to free the frame. For example, passing any address in [0, 0x1000) will cause the first
+ *  page frame to be released.
  *  This function may be used to release page frames obtained through either of the
  *  pg_frame_alloc_start() and pg_frame_alloc_end() functions.
  *
- *  This function does not perform any error checking. The caller is responsible not to
- *  pass any addresses that cause array accesses outside of the frame map. In other words,
- *  care should be taken not to pass values other than those obtained through either of the
- *  allocation functions.
+ *  This function does not perform any error checking. The caller is responsible not to pass any
+ *  addresses that cause array accesses outside of the frame map. In other words, care should be
+ *  taken not to pass values other than those obtained through either of the allocation functions.
  *
  * RETURN VALUE
  *  void
@@ -246,7 +245,6 @@ void* pg_frame_alloc_end(void)
 void pg_frame_free(void *addr)
 {
        _frame_clear((u32_t)addr);
-
        return;
 }