1# ESwap 2 3 4## Basic Concepts 5 6Enhanced Swap (ESwap) allows a custom partition to serve as a swap partition and uses a resident process zswapd to encrypt and swap the anonymous pages compressed by [zram](https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html) to the ESwap partition. In this way, a block of memory can be completely released to ensure the available memory (Memavailable) waterline. In addition to this reclaiming mechanism, the entire memory framework is enhanced to improve the reclaiming efficiency of anonymous pages and file pages and streamline the reclaiming ratio of these two types of pages to prevent refaults caused by excessive reclamation. 7 8 9## Configuring zram and ESwap 10 11>  **NOTE**<br> 12> Enable ESwap before zram is enabled. If ESwap is not used, you can enable zram alone. If a device does not have the storage device for swap-out or have the corresponding storage partition created, you can enable zram to reclaim memory using **zswapd**. 13 14### Enabling ESwap 151. Enable related configuration items and dependencies. 16 17 To enable ESwap, you must enable the corresponding configuration items and dependencies during kernel compilation. The configuration items related to ESwap are as follows: 18 19 ``` 20 CONFIG_HYPERHOLD=y // Enable Hyperhold 21 CONFIG_HYPERHOLD_DEBUG=y // Enable Hyperhold debug 22 CONFIG_HYPERHOLD_ZSWAPD=y // Enable the zswapd thread to reclaim Anon pages in background 23 CONFIG_HYPERHOLD_FILE_LRU=y // Enable Hyperhold FILE LRU 24 CONFIG_HYPERHOLD_MEMCG=y // Enable Memcg management in Hyperhold 25 CONFIG_ZRAM_GROUP=y // Enable Manage Zram objs with mem_cgroup 26 CONFIG_ZRAM_GROUP_DEBUG=y // Enable Manage Zram objs with mem_cgroup Debug 27 CONFIG_ZLIST_DEBUG=y // Enable Debug info for zram group list 28 CONFIG_ZRAM_GROUP_WRITEBACK=y // Enable write back grouped zram objs to Hyperhold driver 29 ``` 30 31 Enable the following dependencies: 32 33 ``` 34 CONFIG_MEMCG=y // Enable memory controller 35 CONFIG_SWAP=y // Enable paging of anonymous memory (swap) 36 CONFIG_ZSMALLOC=y // Enable memory allocator for compressed pages 37 CONFIG_ZRAM=y // Enable compressed RAM block device support 38 ``` 39 402. Create an ESwap device. 41 42 You can use any block device as the ESwap device. In this example, create the **hpdisk** file and mount it to the loop6 device. 43 44 ```Bash 45 // Run the dd command to create the hpdisk file for ESwap. In this example, the file size is 512 MB. Set the file size based on service requirements. 46 dd if=/dev/random of=/data/hpdisk bs=4096 count=131072 47 // Associate the hpdisk file with the ESwap device. 48 losetup /dev/block/loop6 hpdisk 49 ``` 50 513. Configure ESwap. 52 53 Bind the device created in step 2 as the ESwap device. 54 55 ```Bash 56 echo /dev/block/loop6 > /proc/sys/kernel/hyperhold/device 57 ``` 58 59 By default, ESwap encrypts the data swapped out. If the ESwap device created in step 2 supports inline encryption, you can disable the ESwap software encryption function. 60 61 ```Bash 62 // Check whether hardware-based encryption is supported and enabled. If yes, disable software encryption. Otherwise, do not disable software encryption. 63 echo 0 > /proc/sys/kernel/hyperhold/soft_crypt 64 ``` 65 66 >  **CAUTION**<br> 67 > For security purposes, all swapped content must be encrypted. If the ESwap device created does not support inline encryption or the inline encryption macro is not enabled during compilation, ESwap cannot be enabled after software encryption is disabled. 68 694. Enable ESwap. 70 71 After ESwap is enabled, the preceding configuration cannot be modified. 72 73 ```Bash 74 echo enable > /proc/sys/kernel/hyperhold/enable 75 ``` 76 77 78### Enabling zram 79 801. Initialize zram. 81 82 Configure the interaction between zram and ESwap and set the zram size. 83 84 ```Bash 85 // Enable the swap-in and swap-out functions from zram to ESwap. Perform this step before setting the zram size. 86 echo readwrite > /sys/block/zram0/group 87 // Set the zram size. In this example, the zram size is set to 512 MB. 88 echo 512M > /sys/block/zram0/disksize 89 ``` 90 91 >  **NOTE**<br> 92 > The parameters and functions of **/sys/block/zram0/group** are as follows: 93 > 94 > - **disable**: disables the function. 95 > - **readonly**: only records the cgroup information of the data but not swap it out. 96 > - **readwrite**: enables swap-in and swap-out from zram to ESwap. 97 982. Enable zram. 99 100 Use the zram device as the swap partition. 101 102 ```Bash 103 mkswap /dev/block/zram0 104 swapon /dev/block/zram0 105 ``` 106 107 108### Disabling ESwap and zram 109 1101. Disable ESwap. 111 112 ```Bash 113 echo disable > /proc/sys/kernel/hyperhold/enable 114 Or 115 echo force_disable > /proc/sys/kernel/hyperhold/enable 116 ``` 117 118 >  **NOTE**<br> 119 > The difference of the two commands is as follows: 120 > 121 > - **disable**: If there is no data in the ESwap partition, disable ESwap. Otherwise, changes ESwap to **readonly** mode. 122 > - **force_disable**: If there is no data in the ESwap partition, disable ESwap. Otherwise, changes ESwap to **readonly** mode and disable ESwap until all data in the ESWAP partition is read. 123 1242. Disable zram and zram group. 125 126 ```Bash 127 // If swapon is executed, run swapoff first. 128 swapoff /dev/block/zram0 129 echo 1 > /sys/block/zram0/reset 130 ``` 131 132 133## ESwap APIs 134 135ESwap provides APIs to control swap-in and swap-out policies and record the current status. These APIs are located in the directory to which memcg is mounted, for example, **/dev/memcg/**. 136 137| Category| API| Description| Reference Value| 138| -------- | -------- | -------- | -------- | 139| Control| [avail_buffers](#avail_buffers) | Sets the buffer range.| 300 250 350 200 | 140| | [zswapd_single_memcg_param](#zswapd_single_memcg_param) | Sets memcg configuration.| 300 40 0 0 | 141| | [zram_wm_ratio](#zram_wm_ratio) | Sets the zram swap-out waterline.| 0 | 142| Status| [zswapd_pressure_show](#zswapd_pressure_show) | Records the current buffer and refault.| NA | 143| | [stat](#stat) | Checks the real-time status of ESwap.| NA | 144| | [zswapd_vmstat_show](#zswapd_vmstat_show) | Records events during the zswapd running.| NA | 145 146>  **CAUTION**<br> 147> Only **avail_buffers** proactively wakes up zswapd because the buffer waterline is adjusted. Other control APIs do not proactively wake up zswapd, but their configuration takes effect only after zswapd is woken up. 148 149 150### avail_buffers 151 152The **avail_buffers** API sets the buffer range [min_avail_buffers, high_avail_buffers]. When the current buffer is less than the value of **min_avail_buffers**, zswapd will be woken up to reclaim anonymous pages. The expected amount of memory to reclaim is the difference between the value of **high_avail_buffers** and the current system buffer value. In fact, less memory is reclaimed due to reasons such as reclamation failure. 153 154The parameters include the following: 155 156- **avail_buffers** indicates the expected buffer value. 157- **free_swap_threshold** indicates the threshold of the free capacity of the swap partition. After zswapd is woken up to reclaim memory, press events, such as medium press and critical press, will be recorded based on the current system status and the settings of these two parameters. 158 159You can proactively adjust the values to trigger zswapd reclamation. 160 161**Example**: 162 163`echo 1000 950 1050 0 > /dev/memcg/memory.avail_buffers` 164 165**Default value**: 166 167``` 168avail_buffers: 0 169min_avail_buffers: 0 170high_avail_buffers: 0 171free_swap_threshold: 0 172``` 173 174**Limit**: 175 1760<=min_avail_buffers<=avail_buffers<=high_avail_buffers 177 1780<=free_swap_threashold 179 180The values are all integers. 181 182### zswapd_single_memcg_param 183 184**zswapd_single_memcg_param** sets the memcg configuration. The parameters include the following: 185 186- **score** indicates the current memcg reclamation priority. 187- **ub_mem2zram_ratio** indicates the memory compression ratio to zram. 188- **ub_zram2ufs_ratio** indicates the ratio of zram to ESwap. 189- **refault_threshold** indicates the refault threshold. 190 191You can modify the parameters to control zram compression and ESwap. 192 193**Example**: 194 195`echo 60 10 50 > memory.zswapd_single_memcg_param` 196 197**Default value**: 198 199``` 200memcg score: 300 201memcg ub_mem2zram_ratio: 60 202memcg ub_zram2ufs_ratio: 10 203memcg refault_threshold: 50 204``` 205 206**Limit**: 207 2080<=ub_mem2zram_ratio<=100 209 2100<=ub_zram2ufs_ratio<=100 211 2120<=refault_threshold<=100 213 214The values are all integers. 215 216### zram_wm_ratio 217 218**zram_wm_ratio** sets the zram swap-out waterline. When the size of the compressed anonymous page in the zram partition is greater than the total size of zram multiplied by **zram_wm_ratio**, the page is swapped out to the ESwap partition. The swap is performed after zswapd is woken up by the buffer waterline. The system defaults the value **0** as **37**. 219 220You can change the value as required. 221 222**Example**: 223 224`echo 30 > /dev/memcg/memory.zram_wm_ratio` 225 226**Default value**: 227 228``` 229zram_wm_ratio: 0 230``` 231 232**Limit**: 233 2340<=zram_wm_ratio<=100 235 236The value is an integer. 237 238### zswapd_pressure_show 239 240**zswapd_pressure_show** records the zswapd status. **buffer_size** indicates the current buffer size of the system, and **recent_refault** indicates the number of refaults occurred. 241 242 243### stat 244 245In addition to **memcg.stat**, the **stat** API is added with **Anon**, **File**, **zram**, and **Eswap** to monitor ESwap in real time. 246 247 248### zswapd_vmstat_show 249 250**zswapd_vmstat_show** records events occurred during the zswapd running. 251 252 253## Triggering zswapd 254 255You can run **cat /dev/memcg/memory.zswapd_pressure_show** to check the current buffer value. For example, if the current buffer value is 1200, you can adjust the buffer range to a value greater than 1200 to wake up zswapd. 256 257```Bash 258echo 1300 1250 1350 0 > /dev/memcg/memory.avail_buffers 259``` 260 261 262## ESwap Size 263 264Set zram and ESwap partition sizes based on service requirements and hardware features. For the rk3568 board whose RAM is 2 GB, the zram and ESwap partitions are set to 512 MB. 265
