From 722375d20a699e935437100be3f87c2fbe710886 Mon Sep 17 00:00:00 2001 From: Alejandro Sior Date: Fri, 29 Jul 2022 11:45:41 +0200 Subject: docs: corrected style --- docs/man.7.scd | 3 ++- docs/verbs.7.scd | 6 ++++++ mem/docs/allocator.9.scd | 15 ++++++++------- mem/docs/framer.9.scd | 8 ++++---- mem/docs/vmap.9.scd | 21 +++++++++++---------- 5 files changed, 31 insertions(+), 22 deletions(-) diff --git a/docs/man.7.scd b/docs/man.7.scd index a705d90..20e10a2 100644 --- a/docs/man.7.scd +++ b/docs/man.7.scd @@ -10,11 +10,12 @@ The operating system aims to be self documenting. As such a manual is written de # SECTIONS - +``` 1. Utilities 3. Libraries 7. Miscellaneous 9. Kernel internals +``` # TODO diff --git a/docs/verbs.7.scd b/docs/verbs.7.scd index 1598342..b529293 100644 --- a/docs/verbs.7.scd +++ b/docs/verbs.7.scd @@ -14,7 +14,9 @@ The *init* verb initializes a structure; that is, upon success, it puts the obje The initialization function has the following signature: +``` [int] x_init(X*, ...) +``` where the return value can be used to communicate errors. See relevant documentation for implementation's meanings. @@ -26,7 +28,9 @@ The *drop* verb is the opposite of the init verb: it puts the object in a state The drop operation has the following signature: +``` [int] x_drop(X*, ...) +``` ## Install @@ -34,6 +38,8 @@ The *install* verb places and initializes an object at a specified location *add The install operation has the following signature: +``` X *x_install(void *addr, ...) +``` A notable example of a structure that gets to be installed is the MemFramer (mem/framer.h). This frame allocator is notably used for managing physical memory. Since it can be used at times when heap allocation is not yet available, the structure can be installed at the beginning of free regions. \ No newline at end of file diff --git a/mem/docs/allocator.9.scd b/mem/docs/allocator.9.scd index c70156a..2f196ad 100644 --- a/mem/docs/allocator.9.scd +++ b/mem/docs/allocator.9.scd @@ -34,29 +34,30 @@ When working with allocators, proper care must be taken in regards of the limita The *mem_alloc()* function is used to dispatch the allocation method call to the underlying implementation of the allocator. This function takes the following arguments: - _self_ The allocator that should be used - _n_ The minimal amount of char-sized units of memory the allocated region should span + - _self_ The allocator that should be used + - _n_ The minimal amount of char-sized units of memory the allocated region should span ## Reallocation The *mem_realloc()* function is used to dispatch the reallocation method call to the underlying implemention of the allocator. Reallocation consists in modifying the size of a previously allocated region. *mem_realloc()* takes the following arguments: - _self_ The allocator that should be used - _ptr_ The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()* - _n_ The new size of the allocated region, in char-sized units + - _self_ The allocator that should be used + - _ptr_ The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()* + - _n_ The new size of the allocated region, in char-sized units ## Freeing The *mem_free()* function is used to dispatch the free method call to the underlying imprlemention of the allocator. Freeing consists in indicating to the allocator that a region is no longer in use and that it can be reclaimed; this reclaimed memory could then, for example, be used as the result of other allocation requests by *mem_alloc()* or *mem_realloc()*. *mem_free()* takes the following arguments: - _self_ The allocator that should be used - _ptr_ The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()* + - _self_ The allocator that should be used + - _ptr_ The previously allocated region of memory, as returned by a previous call to *mem_alloc()* or *mem_realloc()* Proper care should be taken to only free region of memory that have been allocated by a previous call to the same allocator, this includes double frees. # RETURN VALUES *mem_alloc()* returns the beginning of the allocated region on success, nil on error or 0 provided. + *mem_realloc()* returns the beginning of the reallocated region on success, nil on error or 0 provided. Note: in case nil, the passed region is freed. # CODE REFERENCES diff --git a/mem/docs/framer.9.scd b/mem/docs/framer.9.scd index 1bc3670..a315a5b 100644 --- a/mem/docs/framer.9.scd +++ b/mem/docs/framer.9.scd @@ -26,9 +26,9 @@ void mem_framer_free(MemAllocator *self, void *ptr); A *MemFramer* can be installed in a particular region of usable memory to manage it using *mem_framer_install()*. It accepts the following arguments: - _addr_ The address at which the *MemFramer* will be installed - _end_ The address marking the end of the region of usable memory that has to be managed - _blksz_ The size of each individual frame + - _addr_ The address at which the *MemFramer* will be installed + - _end_ The address marking the end of the region of usable memory that has to be managed + - _blksz_ The size of each individual frame ## Allocating @@ -46,4 +46,4 @@ The *MemFramer* allocator and its related functions are defined in _mem/framer.c # SEE ALSO -memallocator(9) \ No newline at end of file +mem_allocator(9) \ No newline at end of file diff --git a/mem/docs/vmap.9.scd b/mem/docs/vmap.9.scd index 89faca7..4ef9c32 100644 --- a/mem/docs/vmap.9.scd +++ b/mem/docs/vmap.9.scd @@ -28,8 +28,8 @@ Translation is the action of taking a virtual address and obtaining its physical The *mem_vmap_translate()* function translates a virtual address into its physical one in software. This can be useful for a few reasons and this mechanism is used internally by MemVmap implementation themselves. *mem_vmap_translate()* takes the following arguments: - _inner_ The *MemVmap* to use - _virt_ The virtual address to translate + - _inner_ The *MemVmap* to use + - _virt_ The virtual address to translate If the translation lands on an unmapped region of the virtual address space, the miss flag is set. @@ -37,11 +37,11 @@ If the translation lands on an unmapped region of the virtual address space, the The *mem_vmap_map()* function maps a region of physical memory into the specified virtual address space, around a specified virtual address, with some flags. *mem_vmap_map()* takes the following arguments: - _inner_ The *MemVmap* to use - _phys_ The beginning of the physical memory region that will back the map - _virt_ The beginning of the virtual memory region to which the physical memory shall be mapped - _len_ The length of the region in char-sized units - _flags_ The flags with which the region must be mapped + - _inner_ The *MemVmap* to use + - _phys_ The beginning of the physical memory region that will back the map + - _virt_ The beginning of the virtual memory region to which the physical memory shall be mapped + - _len_ The length of the region in char-sized units + - _flags_ The flags with which the region must be mapped The mapping operation may fail for reasons, such as: - The requested mapping overlaps with a pre-existing mapping @@ -52,9 +52,9 @@ Unmapping is the inverse operation of mapping, it removes a particular map from The *mem_vmap_unmap()* function is used to perform the unmap operation on a particular address space at a specified virtual address. *mem_vmap_unmap()* takes the following arguments: - _inner_ The *MemVmap* to use - _virt_ The beginning of the virtual memory region that must be unmapped - _len_ The length of the virtual memory region that must be unmapped + - _inner_ The *MemVmap* to use + - _virt_ The beginning of the virtual memory region that must be unmapped + - _len_ The length of the virtual memory region that must be unmapped Note: it is not an error to unmap a region of virtual memory that is not already mapped. The unmap operation, if properly implemented, should not fail. @@ -71,6 +71,7 @@ XXX todo, unimplemented yet # RETURN VALUES *mem_vmap_translate()* returns a physical address on success, 0 in case of error or miss + *mem_vmap_map()* returns 0 in case of success, or a non-zero value in case of error Refer to mem/errors.h for the list of error codes pertaining to the _mem_ module -- cgit v1.2.3