i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Generate developer docs with Sphinx

Browse Source 
An effort was started some time ago to consolidate all internal
documentation in the git tree. However, this was just an accumulation of
files in various formats without any strucutre or way to browse it,
which results in no one even knowing that we have docs here.

This converts most of the files to restructuredtext and uses Sphinx to
generate an HTML browsable user manual (with a table of content and a
first attempt to put things in a global hierarchy).

There are almost no changes to the documentation content in this commit
(some obviously obsolete things were removed). The plan is to get the
toolchain up and running to make these docs easily available, and only
then see about improving the content. We can migrate some things off the
wiki and website, and rework the table of contents to have some more
hierarchy levels because currently it's a bit messy.

Change-Id: I924ac9dc6e753887ab56f18a09bdb0a1e1793bfd
Reviewed-on: https://review.haiku-os.org/c/haiku/+/4370
Reviewed-by: Niels Sascha Reedijk <[email protected]>
This commit is contained in:
Adrien Destugues
2021-08-27 11:41:17 +00:00
committed by Adrien Destugues
parent 7f8195344a
commit a5061ecec5
146 changed files with 10937 additions and 12069 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/develop/kernel/vm/swap_file_support → docs/develop/kernel/vm/swap_file_support.rst
+42 -40
View File
@@ -1,31 +1,34 @@
Haiku swap file support
Swap file
#######################
This article describes how to use swap file in Haiku and how the swap system
works.
This section describes how to use swap file in Haiku and how the swap system
works.
1. How to use a swap file?
How to use a swap file?
=======================
Like BeOS, Haiku uses "/var/swap" as default swap file. It is created
Like BeOS, Haiku uses "/var/swap" as default swap file. It is created
during the boot process and its size is twice the size of physical memory by
default. You can change its size through the VirtualMemory preference
application and your settings will take effect after restarting the system.
The default swap file "/var/swap" may not satisfy your need. Haiku allows
The default swap file "/var/swap" may not satisfy your need. Haiku allows
adding/removing a swap file dynamically. (This is *NOT* implemented yet, since
I do not know how to add bin commands "swapon" and "swapoff" in the system.
It needs to be done in the future.)
2. How swap system works?
The virtual memory subsystem of Haiku is very similar to that of FreeBSD,
How swap system works?
======================
The virtual memory subsystem of Haiku is very similar to that of FreeBSD,
therefore our swap system implementation is borrowed from FreeBSD.
A swap system has two main functions: (1) maintain a map between anonymous
A swap system has two main functions: (1) maintain a map between anonymous
pages and swap space, so we can page in/out when needed. (2) manage the
allocation/deallocation of swap space. Let's see how these are implemented in
Haiku.
In order to maintain a map between pages and swap space, we need to record
In order to maintain a map between pages and swap space, we need to record
the pages' swap address somewhere. Here we use swap blocks. A "swap_block"
structure contains swap address information for 32 (value of SWAP_BLOCK_PAGES)
consecutive pages from a same cache. So whenever we look for a page in swap
@@ -34,33 +37,33 @@ Here we use hash table. All swap blocks in the system are arranged into a global
hash table. The hash table uses a cache's address and page index in this cache
as hash key.
Here is an example. Suppose a page has been paged out to swap space and now
its cache wants to page it in. It works as follows: look up the swap hash table
using address of the cache and page index as hash key, if successful, we get
the swap block containing the this page's swap address. Then search the swap
block to get the exact swap address of this page. After that, we can read the
Here is an example. Suppose a page has been paged out to swap space and now
its cache wants to page it in. It works as follows: look up the swap hash table
using address of the cache and page index as hash key, if successful, we get
the swap block containing the this page's swap address. Then search the swap
block to get the exact swap address of this page. After that, we can read the
page from swap file using vfs functions.
I draw a picture and hope it could help you understand the above words. If
the pic becomes a mess on your computer, please set the tab width of your text
editor to 4.
I draw a picture and hope it could help you understand the above words.
.. code-block:: text
___________________________________________________________
sSwapHashTable |__________|___NULL___|___NULL___|___________|____NULL____|
| |
| |
| |
| |
___V___ ___V___
swap_block /----|__0__| /--------|__5__|
swap_block /----|__0__| /--------|__5__|
| |__3__|--------\ | /---|__6__|
| |_..._| | | | |_..._|
| |__2__|----\ | | | |__20_|--------------->
| |_..._| | | | |_..._|
| |__2__|----\ | | | |__20_|--------------->
| | | | |
| _____________V___V_________V____V_________________________
swap_file `->|slot|slot|slot|slot|slot|slot|slot|slot|slot|slot|....|
|_0__|_1__|_2__|_3__|_4__|_5__|_6__|_7__|_8__|_9__|____|__
| _____________V___V_________V____V_________________________
swap_file `->|slot|slot|slot|slot|slot|slot|slot|slot|slot|slot|....|
|_0__|_1__|_2__|_3__|_4__|_5__|_6__|_7__|_8__|_9__|____|__
The swap system also manages allocation/deallocation of swap space. In our
The swap system also manages allocation/deallocation of swap space. In our
implementation, each swap file is divided into page-sized slots(called "swap
pages") and a swap file can be seen as an array of many swap pages(see the
above picture). Swap page is the unit for swap space allocation/deallocation
@@ -72,29 +75,28 @@ swap file is: 0-99, 101-200, 202-301) Why leave a page gap between swap files?
Because in this way, we can easily tell if two adjacent pages are in a same
swap file. (See the code in VMAnonymousCache::Read()).
The efficiency of the FreeBSD swap system lies in a special data structure:
The efficiency of the FreeBSD swap system lies in a special data structure:
radix bitmap(i.e. bitmap using radix tree for hinting.) It can operate well no
matter how much fragmentation there is and no matter how large a bitmap is
used. I have ported the radix bitmap structure to Haiku, so our swap system
will have a good performance. More information on radix bitmap, please look
at the source code.
Swap space allocation takes place when we swap anonymous pages out.
Swap space allocation takes place when we swap anonymous pages out.
In order to make the allocation less probable to fail, anonymous cache will
reserve swap space when it is initialized. If there is not enough swap space
left, physical memory will be reserved. Swap space deallocation happens when
available swap space is low. The page daemon will scan a number of pages and
if the scanned page has swap space assigned, its swap space will be freed.
3. Acknowledgement
Special thanks to my mentor Ingo. He is a knowledged person and always
Acknowledgement
---------------
Special thanks to my mentor Ingo. He is a knowledged person and always
gives me encouragement. Without his consistent and illuminating instructions,
this project would not have reached its present status.
If you find bugs or have suggestions for swap system, you can contact me
If you find bugs or have suggestions for swap system, you can contact me
via [email protected]. Thanks in advance.
Zhao Shuai
[email protected]
2008-08-21
Zhao Shuai - [email protected] - 2008-08-21