From a9da82b12116b27ae36db56305c0353b991cfd51 Mon Sep 17 00:00:00 2001 From: xzl Date: Tue, 16 Dec 2025 14:27:08 +0800 Subject: [PATCH 1/2] feat: add swap file docs --- docs/common/radxa-os/system-config/_swap.mdx | 99 +++++++++++++++++ docs/cubie/a5e/system-config/swap.md | 9 ++ docs/cubie/a5e/system-config/system_update.md | 6 ++ docs/cubie/a7a/system-config/swap.md | 9 ++ docs/cubie/a7a/system-config/system_update.md | 6 ++ docs/cubie/a7z/system-config/swap.md | 9 ++ docs/cubie/a7z/system-config/system_update.md | 6 ++ .../common/radxa-os/system-config/_swap.mdx | 101 ++++++++++++++++++ .../current/cubie/a5e/system-config/swap.md | 9 ++ .../cubie/a5e/system-config/system_update.md | 6 ++ .../current/cubie/a7a/system-config/swap.md | 9 ++ .../cubie/a7a/system-config/system_update.md | 6 ++ .../current/cubie/a7z/system-config/swap.md | 9 ++ .../cubie/a7z/system-config/system_update.md | 6 ++ 14 files changed, 290 insertions(+) create mode 100644 docs/common/radxa-os/system-config/_swap.mdx create mode 100644 docs/cubie/a5e/system-config/swap.md create mode 100644 docs/cubie/a7a/system-config/swap.md create mode 100644 docs/cubie/a7z/system-config/swap.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md diff --git a/docs/common/radxa-os/system-config/_swap.mdx b/docs/common/radxa-os/system-config/_swap.mdx new file mode 100644 index 000000000..b7c4ea56e --- /dev/null +++ b/docs/common/radxa-os/system-config/_swap.mdx @@ -0,0 +1,99 @@ +Radxa OS 默认会启用一个大小约为 **物理内存一半** 的 swap 分区，通常已经可以覆盖大部分日常使用场景。 + +当设备物理内存较小、偶尔会跑较大负载时，可以在此基础上**额外创建 swap 文件**，作为临时扩展和应急缓冲。 + +下面介绍如何在 Radxa 设备上添加一个简单的 swap 文件。 + +:::caution 注意 +swap 仅适合作为“兜底”，会降低性能并增加 eMMC/SD/SSD 的写入磨损，不建议长期依赖。 +::: + +## 一、什么时候需要 swap？ + +- 内存较小，偶尔会编译大工程 / 运行占用高的程序 +- 希望在内存突然吃紧时，系统不要直接 OOM 崩溃 + +如果你追求极致性能或担心闪存寿命，也可以选择完全不启用 swap。 + +## 二、查看当前内存与 swap 情况 + +```bash +free -h +sudo swapon --show +``` + +若 `swapon --show` 无输出，说明当前系统未启用 swap。 + +## 三、创建并启用 swap 文件（以 2G 为例） + +```bash +sudo fallocate -l 2G /swapfile # 创建文件 +sudo chmod 600 /swapfile # 只允许 root 访问 +sudo mkswap /swapfile # 格式化为 swap +sudo swapon /swapfile # 立即启用 +``` + +再次确认： + +```bash +swapon --show +free -h +``` + +## 四、设置开机自动启用 swap + +先备份 `fstab`（推荐）： + +```bash +sudo cp /etc/fstab /etc/fstab.bak +``` + +编辑 `fstab`： + +```bash +sudo vim /etc/fstab +``` + +在文件末尾添加一行： + +```bash +/swapfile none swap sw 0 0 +``` + +保存退出后，用下面命令测试配置是否正确： + +```bash +sudo swapoff /swapfile +sudo swapon -a +sudo swapon --show +``` + +能正常看到 `/swapfile`，说明 `fstab` 配置生效且无语法错误。 + +:::tip +`swapon -a` 会按照 `/etc/fstab` 中的配置重新启用所有 swap 设备，是检查配置是否正确的安全方法。 +::: + +## 五、禁用并删除 swap 文件 + +若后续不再需要该 swap 文件，可按以下步骤关闭并删除： + +1. 关闭 swap： + + ```bash + sudo swapoff /swapfile + ``` + +2. 编辑 `/etc/fstab`，删除或注释掉下面这一行： + + ```bash + /swapfile none swap sw 0 0 + ``` + +3. 删除文件： + + ```bash + sudo rm /swapfile + ``` + +完成以上操作后，系统将恢复为无该 swap 文件的状态。 diff --git a/docs/cubie/a5e/system-config/swap.md b/docs/cubie/a5e/system-config/swap.md new file mode 100644 index 000000000..6285c229e --- /dev/null +++ b/docs/cubie/a5e/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# 交换分区与 swap 文件 + + diff --git a/docs/cubie/a5e/system-config/system_update.md b/docs/cubie/a5e/system-config/system_update.md index 3e92fff7a..97d02bf4d 100644 --- a/docs/cubie/a5e/system-config/system_update.md +++ b/docs/cubie/a5e/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # 系统更新 +:::tip + +搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。 + +::: + diff --git a/docs/cubie/a7a/system-config/swap.md b/docs/cubie/a7a/system-config/swap.md new file mode 100644 index 000000000..6285c229e --- /dev/null +++ b/docs/cubie/a7a/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# 交换分区与 swap 文件 + + diff --git a/docs/cubie/a7a/system-config/system_update.md b/docs/cubie/a7a/system-config/system_update.md index cb0742d7c..f814f9adc 100644 --- a/docs/cubie/a7a/system-config/system_update.md +++ b/docs/cubie/a7a/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # 系统更新 +:::tip + +搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。 + +::: + diff --git a/docs/cubie/a7z/system-config/swap.md b/docs/cubie/a7z/system-config/swap.md new file mode 100644 index 000000000..6285c229e --- /dev/null +++ b/docs/cubie/a7z/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# 交换分区与 swap 文件 + + diff --git a/docs/cubie/a7z/system-config/system_update.md b/docs/cubie/a7z/system-config/system_update.md index cb0742d7c..f814f9adc 100644 --- a/docs/cubie/a7z/system-config/system_update.md +++ b/docs/cubie/a7z/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # 系统更新 +:::tip + +搭载较小内存版本的设备，在更新前需要设置更大的交换分区，具体操作请参考[交换分区与swap文件](./swap.md)。 + +::: + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx new file mode 100644 index 000000000..82ee77fd1 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx @@ -0,0 +1,101 @@ +Radxa OS enables a swap **partition** by default, with a size of about **half of the physical memory**, which is usually enough for most daily use cases. + +When the device has relatively small RAM and you occasionally run heavy workloads, you can **add an extra swap file** on top of the default swap partition as a temporary extension and safety buffer. + +The following describes how to add a simple swap file on a Radxa device. + +:::caution Note +Swap is only a **fallback** mechanism. It will slow down the system and increase write wear on eMMC/SD/SSD. Do not rely on it as a long‑term replacement for physical memory. +::: + +## 1. When do you need an extra swap file? + +- RAM is small, and you occasionally compile large projects or run memory‑hungry programs +- You want to reduce the chance of the system going OOM and crashing when memory usage spikes + +If you care about extreme performance or flash lifetime, you can also choose not to enable any additional swap. + +## 2. Check current memory and swap + +```bash +free -h +sudo swapon --show +``` + +If `swapon --show` prints nothing, it means no swap is currently enabled (or only a swap partition that is not active). + +## 3. Create and enable a swap file (2G example) + +```bash +sudo fallocate -l 2G /swapfile # create file +sudo chmod 600 /swapfile # only root can access +sudo mkswap /swapfile # format as swap +sudo swapon /swapfile # enable immediately +``` + +Verify: + +```bash +sudo swapon --show +free -h +``` + +You should see an extra swap entry, and the `Swap` line in `free -h` will increase accordingly. + +## 4. Enable the swap file at boot + +First, back up `fstab` (recommended): + +```bash +sudo cp /etc/fstab /etc/fstab.bak +``` + +Edit `fstab`: + +```bash +sudo nano /etc/fstab +``` + +Add the following line at the end of the file: + +```bash +/swapfile none swap sw 0 0 +``` + +Save and exit, then test whether the configuration works: + +```bash +sudo swapoff /swapfile +sudo swapon -a +sudo swapon --show +``` + +If `/swapfile` appears in the output, the `fstab` configuration is valid. + +:::tip +`swapon -a` re‑enables all swap devices according to `/etc/fstab`. It is a safe way to verify that your configuration is correct. +::: + +## 5. Disable and remove the swap file + +If you no longer need the swap file, follow these steps to disable and remove it: + +1. Turn off swap: + + ```bash + sudo swapoff /swapfile + ``` + +2. Edit `/etc/fstab` and remove or comment out the line: + + ```bash + /swapfile none swap sw 0 0 + ``` + +3. Delete the file: + + ```bash + sudo rm /swapfile + ``` + +After these steps, the system will go back to running without this swap file. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md new file mode 100644 index 000000000..0c2d7bc2b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# Swap Partition and Swap File + + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md index b3fd78d3f..e64efbef3 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # System Update +:::tip + +For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md). + +::: + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md new file mode 100644 index 000000000..0c2d7bc2b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# Swap Partition and Swap File + + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md index 36709c6fc..ea17467be 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7a/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # System Update +:::tip + +For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md). + +::: + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md new file mode 100644 index 000000000..0c2d7bc2b --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/swap.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 6 +--- + +import SWAP from '../../../common/radxa-os/system-config/\_swap.mdx'; + +# Swap Partition and Swap File + + diff --git a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md index 36709c6fc..ea17467be 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/cubie/a7z/system-config/system_update.md @@ -6,4 +6,10 @@ import SYSTEM_UPDATE from '../../../common/radxa-os/system-config/\_system_updat # System Update +:::tip + +For boards with smaller RAM, it is recommended to configure a larger swap space before performing a system update. For details, see [Swap Partition and Swap File](./swap.md). + +::: + From a1c8668cdc4d3ec87220e41052daaa17d7c10d82 Mon Sep 17 00:00:00 2001 From: xzl Date: Mon, 22 Dec 2025 14:24:49 +0800 Subject: [PATCH 2/2] feat: add code block hints. --- docs/common/radxa-os/system-config/_swap.mdx | 66 ++++++++++++--- .../common/radxa-os/system-config/_swap.mdx | 80 ++++++++++++++----- 2 files changed, 112 insertions(+), 34 deletions(-) diff --git a/docs/common/radxa-os/system-config/_swap.mdx b/docs/common/radxa-os/system-config/_swap.mdx index b7c4ea56e..4f7cccd39 100644 --- a/docs/common/radxa-os/system-config/_swap.mdx +++ b/docs/common/radxa-os/system-config/_swap.mdx @@ -17,57 +17,85 @@ swap 仅适合作为“兜底”，会降低性能并增加 eMMC/SD/SSD 的写 ## 二、查看当前内存与 swap 情况 -```bash + + +``` free -h sudo swapon --show ``` + + 若 `swapon --show` 无输出，说明当前系统未启用 swap。 ## 三、创建并启用 swap 文件（以 2G 为例） -```bash + + +``` sudo fallocate -l 2G /swapfile # 创建文件 sudo chmod 600 /swapfile # 只允许 root 访问 sudo mkswap /swapfile # 格式化为 swap sudo swapon /swapfile # 立即启用 ``` + + 再次确认： -```bash + + +``` swapon --show free -h ``` + + ## 四、设置开机自动启用 swap 先备份 `fstab`（推荐）： -```bash + + +``` sudo cp /etc/fstab /etc/fstab.bak ``` + + 编辑 `fstab`： -```bash + + +``` sudo vim /etc/fstab ``` + + 在文件末尾添加一行： -```bash + + +``` /swapfile none swap sw 0 0 ``` + + 保存退出后，用下面命令测试配置是否正确： -```bash + + +``` sudo swapoff /swapfile sudo swapon -a sudo swapon --show ``` + + 能正常看到 `/swapfile`，说明 `fstab` 配置生效且无语法错误。 :::tip @@ -80,20 +108,32 @@ sudo swapon --show 1. 关闭 swap： - ```bash + + +``` sudo swapoff /swapfile - ``` +``` + + 2. 编辑 `/etc/fstab`，删除或注释掉下面这一行： - ```bash + + +``` /swapfile none swap sw 0 0 - ``` +``` + + 3. 删除文件： - ```bash + + +``` sudo rm /swapfile - ``` +``` + + 完成以上操作后，系统将恢复为无该 swap 文件的状态。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx index 82ee77fd1..d46b0b16e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_swap.mdx @@ -5,72 +5,98 @@ When the device has relatively small RAM and you occasionally run heavy workload The following describes how to add a simple swap file on a Radxa device. :::caution Note -Swap is only a **fallback** mechanism. It will slow down the system and increase write wear on eMMC/SD/SSD. Do not rely on it as a long‑term replacement for physical memory. +Swap is only a **fallback** mechanism. It will slow down the system and increase write wear on eMMC/SD/SSD. Long‑term reliance on swap is not recommended. ::: -## 1. When do you need an extra swap file? +## 1. When do you need swap? - RAM is small, and you occasionally compile large projects or run memory‑hungry programs - You want to reduce the chance of the system going OOM and crashing when memory usage spikes -If you care about extreme performance or flash lifetime, you can also choose not to enable any additional swap. +If you care about extreme performance or flash lifetime, you can also choose not to enable swap at all. ## 2. Check current memory and swap -```bash + + +``` free -h sudo swapon --show ``` -If `swapon --show` prints nothing, it means no swap is currently enabled (or only a swap partition that is not active). + + +If `swapon --show` prints nothing, it means no swap is currently enabled. ## 3. Create and enable a swap file (2G example) -```bash + + +``` sudo fallocate -l 2G /swapfile # create file sudo chmod 600 /swapfile # only root can access sudo mkswap /swapfile # format as swap sudo swapon /swapfile # enable immediately ``` + + Verify: -```bash -sudo swapon --show + + +``` +swapon --show free -h ``` -You should see an extra swap entry, and the `Swap` line in `free -h` will increase accordingly. + ## 4. Enable the swap file at boot First, back up `fstab` (recommended): -```bash + + +``` sudo cp /etc/fstab /etc/fstab.bak ``` + + Edit `fstab`: -```bash -sudo nano /etc/fstab + + ``` +sudo vim /etc/fstab +``` + + Add the following line at the end of the file: -```bash + + +``` /swapfile none swap sw 0 0 ``` + + Save and exit, then test whether the configuration works: -```bash + + +``` sudo swapoff /swapfile sudo swapon -a sudo swapon --show ``` -If `/swapfile` appears in the output, the `fstab` configuration is valid. + + +If `/swapfile` appears in the output, the `fstab` configuration is valid and has no syntax errors. :::tip `swapon -a` re‑enables all swap devices according to `/etc/fstab`. It is a safe way to verify that your configuration is correct. @@ -82,20 +108,32 @@ If you no longer need the swap file, follow these steps to disable and remove it 1. Turn off swap: - ```bash + + +``` sudo swapoff /swapfile - ``` +``` + + 2. Edit `/etc/fstab` and remove or comment out the line: - ```bash + + +``` /swapfile none swap sw 0 0 - ``` +``` + + 3. Delete the file: - ```bash + + +``` sudo rm /swapfile - ``` +``` + + After these steps, the system will go back to running without this swap file.