# SOLA Toolkit 安装指南

## 概述

SOLA Toolkit 是墨芯为计算卡提供的软件开发工具包，包含驱动、运行时库以及一系列工具，帮助开发和调试墨芯计算卡上的应用程序。本文介绍 SOLA Toolkit 的安装方法，以及在安装和卸载过程中需要注意的事项。

### 系统需求

SOLA 开发环境与主机开发环境紧密集成，包括主机编译器和 C 运行时库。下表列出了对 SOLA Toolkit 充分验证的 Linux 发行版，以及对应的 GNU 编译器套件（GNU Compiler Collection，GCC）和 GNU C 库（GNU C Library，GLIBC）版本。验证范围包括红帽企业 Linux（Red Hat Enterprise Linux，RHEL）；在其他 Linux 版本上，SOLA Toolkit 也可能运行，但功能无法保证。

| Linux 发行版     | 架构   | 内核版本                        | GCC 版本 | GLIBC 版本 |
| ---------------- | ------ | ------------------------------- | -------- | ---------- |
| AliOS 7.2        | x86_64 | 5.10                            | 9.2.1    | 2.17       |
| CentOS 8         | x86_64 | 4.18.0-80.el8.x86_64            | 8.5.0    | 2.28       |
| Debian 11        | x86_64 | 5.10.0                          | 10.2.1   | 2.31       |
| Debian 12        | x86_64 | 6.1.0-41-amd64                  | 12.2.0   | 2.36       |
| Kylin V10        | x86_64 | 4.19.90-52.22.v2207.ky10.x86_64 | 7.3.0    | 2.28       |
| openEuler 24.03  | x86_64 | 5.10.0-216.0.0.115              | 12.3.1   | 2.38       |
| RHEL 8.2/8.3     | x86_64 | 4.18.0                          | 8.3.1    | 2.28       |
| RHEL 8.6         | x86_64 | 4.18.0                          | 8.5.0    | 2.28       |
| RHEL 9.0         | x86_64 | 5.14.0                          | 11.5.0   | 2.34       |
| RHEL 9.3         | x86_64 | 5.14.0                          | 10.2.1   | 2.34       |
| Rocky Linux 10.0 | x86_64 | 6.12.0-55.21.1                  | 14.2.1   | 2.39       |
| Rocky Linux 9.3  | x86_64 | 5.14.0-362.8.1                  | 11.5.0   | 2.35       |
| Ubuntu 18.04     | x86_64 | 5.4.0                           | 7.5.0    | 2.27       |
| Ubuntu 20.04     | x86_64 | 5.4.0                           | 9.4.0    | 2.35       |
| Ubuntu 22.04     | x86_64 | 6.5.0                           | 11.4.0   | 2.35       |
| Ubuntu 24.04     | x86_64 | 6.8.0-136-generic               | 13.3.0   | 2.39       |

## 安装前操作

### 验证系统运行的 Linux 发行版及内核版本

推荐在验证的 Linux 发行版上运行 SOLA Toolkit。查看当前系统 Linux 发行版及其内核版本：

```bash
hostnamectl
```

确保系统安装了对应版本的内核头文件和开发包：

````{tabs}
```{tab} Ubuntu/Debian
```bash
sudo apt-get install linux-headers-$(uname -r)
```
```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
```bash
sudo dnf install kernel-devel-$(uname -r) kernel-headers-$(uname -r)
```
````

### 验证系统已安装 GCC

查看系统是否安装 GCC 编译器，且版本 ≥ GCC 6.x。

```bash
gcc --version
```

GCC 通常作为 Linux 操作系统的一部分随系统一起安装。如果显示错误信息，则需要从您的 Linux 发行版中安装开发工具，或者从网上获取 GCC 及其相关工具链的版本。

### 验证已安装的依赖软件

确保系统安装了以下依赖的软件：

````{tabs}
```{tab} Ubuntu/Debian
```bash
sudo apt-get install pciutils dkms libelf-dev kmod make tar
```
```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
```bash
sudo dnf install pciutils dkms elfutils-libelf-devel kmod make tar
```
````

### 验证系统能正确识别墨芯计算卡

```bash
lspci | grep 1f36
```

(install-sola-toolkit)=
## 安装 SOLA Toolkit

### 选择安装方式

SOLA Toolkit 提供两种不同的安装方式：

- Runfile 安装（推荐）

  该方式使用独立于 Linux 发行版的 Runfile 安装包，不依赖 Linux 发行版的本地包管理器，可以在多个 Linux 发行版上使用。

- 包管理器安装

  该方式使用 Linux 发行版特定的安装包，依赖于 Linux 发行版的本地包管理器进行安装。安装包根据 Linux 发行版分为以下两种：
  - Deb 安装包：适用于 Ubuntu 和 Debian。
  - RPM 安装包：适用于 RHEL、AliOS、Kylin V10、Rocky Linux 9.3 和 openEuler。

```{admonition} 须知
:class: note

Linux 发行版特定的安装包和独立的 Runfile 安装包底层实现是同源的，所以安装和卸载都会互相影响。如果同时使用了两种不同类型的安装包进行安装，在卸载时可能会影响 Linux 发行版的本地包管理器的使用，所以建议使用同一种类型的安装包。
```

### Runfile 安装

使用独立的 Runfile 安装包安装 SOLA Toolkit，步骤如下：

1. 获取安装包。

   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/sola-toolkit/sola_3.18.0_x86_64.run
   ```

2. 安装 SOLA Toolkit。

   ```bash
   sudo sh sola_3.18.0_x86_64.run --driver --accept
   ```

   --driver（可选，推荐设置）
   : 安装 SOLA 驱动。如果未设置，执行以下命令手动安装 SOLA 驱动：

      ```bash
      cd /usr/local/sola/driver # 进入 SOLA 驱动程序的目录
      sudo sh setup.sh          # 安装 SOLA 驱动
      ```

   --accept（可选，推荐设置）
   : 同意最终用户许可协议。如果未设置，可在执行安装命令时阅读协议内容，并根据提示输入 `accept` 并按回车键确认后继续安装。

### 包管理器安装

使用 RPM 或 Deb 包进行安装时，会与 Linux 发行版的包管理器集成。

```{admonition} 须知
:class: note

使用 Deb 或 RPM 包安装时，默认您已同意最终用户许可协议（End User License Agreement，EULA）。EULA 内容详见 [《SOLA Toolkit 最终用户许可协议》](../eula/SOLA_Toolkit_EULA.md)。
```

1. 获取安装包。

   ````{tabs}
   ```{tab} Ubuntu/Debian
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/sola-toolkit/sola_3.18.0_amd64.deb
   ```
   ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
   ```bash
   wget https://moffett-oss-bucket.tos-cn-shanghai.volces.com/macs/v1.14/sola-toolkit/sola-3.18.0-1.x86_64.rpm
   ```
   ````

2. 安装 SOLA Toolkit。

   ````{tabs}
   ```{tab} Ubuntu/Debian
   ```bash
   sudo dpkg -i sola_3.18.0_amd64.deb
   ```
   ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
   ```bash
   sudo rpm -U sola-3.18.0-1.x86_64.rpm
   ```
   ````

(sola-toolkit-post-install-verification)=
## 安装后验证（必须）

SOLA Toolkit 安装完成后，必须进行以下验证操作确保设备正常运行。

### 验证固件版本

执行以下命令查询板载设备的固件版本：

```bash
mx-smi select -f firmware_version
```

建议使用最新固件版本以获得完整功能支持。升级方法详见《mx-mft 用户手册》中的{ref}`升级板载设备固件版本 <mx-mft-upgrade-board-firmware>`。

### 验证 SOLA Toolkit 版本和板卡相关信息

执行 `mx-smi` 命令，查看 SOLA Toolkit 版本和设备列表，与安装包版本一致即表示安装成功。

SOLA Toolkit 默认安装在 `/usr/local/sola-<version>` 路径下，并会自动创建一个指向该路径的软链接 `/usr/local/sola`。同时，以下可执行工具程序安装在 `/usr/bin` 目录下，供调试板卡使用。

| 可执行工具程序        | 说明                   |
| --------------------- | ---------------------- |
| sola-uninstall        | 卸载程序               |
| mx-smi                | 管理和监控设备的工具   |
| mx-qual               | 系统和设备质量检测工具 |
| mx-mft                | 设备固件管理工具       |
| mx-daemon             | 自动加载固件的守护进程 |
| moffett-bug-report.sh | 日志收集工具           |

关于如何使用 `mx-smi`、`mx-qual`、`mx-mft`，参见[《设备管理工具》](../tool/index.md)。

## 卸载 SOLA Toolkit

卸载 SOLA Toolkit 会卸载与它相关的所有组件，包括驱动程序、工具和库。根据不同的安装方式选择卸载方式：

- Runfile

  ```bash
  sudo sola-uninstall --all
  ```

- 包管理器

  ````{tabs}
  ```{tab} Ubuntu/Debian
  ```bash
  sudo dpkg -r sola
  ```
  ```{tab} RHEL/AliOS/Kylin V10/Rocky Linux/openEuler/CentOS 8
  ```bash
  sudo rpm -e sola
  ```
  ````

## 故障处理

(sola-uninstall-module-in-use)=
### 卸载 SOLA Toolkit 时提示内核模块被占用

卸载 SOLA Toolkit 时可能出现以下错误：

```text
rmmod: ERROR: Module moffett is in use
Error, uninstall moffett driver fail
```

稀疏处理单元 SPU（Sparse Processing Unit）设备或 `moffett` 内核模块正被进程或服务占用时，无法完成卸载。按以下步骤处理：

1. 查看是否有应用进程占用设备，并结束占用设备的进程。

   ```bash
   mx-smi list
   sudo lsof -f -- /dev/mf-*
   sudo kill -9 <PID>
   ```

2. 查看是否有推理服务、数据中心 SPU 管理器 DCSM（Data Center SPU Manager）或其他设备管理组件正在运行。如果正在运行，停止相应服务或组件：

   - 《TUILI 大语言模型推理服务》中的{ref}`结束推理服务 <stop-tuili-service>`
   - 《文本向量与重排服务》中的{ref}`停止 RAG 服务 <stop-rag-service>`
   - 《DCSM 用户手册》中的{ref}`停用 DCSM <disable-dcsm>`
   - 《DCSM Exporter 用户手册》中的{ref}`停用 DCSM Exporter <disable-dcsm-exporter>`（单独部署）
   - 《MOFFETT Device Plugin 用户手册》中的{ref}`更新 SOLA Toolkit 时停用节点上的 Device Plugin <disable-device-plugin-for-sola-upgrade>`（单独部署）
   - 《MOFFETT SPU Operator 用户手册》中的{ref}`节点选择性部署 <spu-operator-selective-deployment>`（SPU Operator 统一部署）

3. 查看 `moffett` 内核模块是否已加载。如果已加载，卸载该模块。

   ```bash
   lsmod | grep moffett
   sudo rmmod moffett
   ```

4. 重新执行 SOLA Toolkit 卸载命令。

(sola-driver-not-loaded)=
### 服务器重启后执行 `mx-smi` 命令时提示驱动未加载

执行 `mx-smi list` 命令时可能出现以下错误：

```text
[x] Unable to init moffett-smi, error code: 9, error message: driver not loaded
```

Linux 内核升级后，`moffett` 内核模块可能未加载到当前内核中。按以下步骤处理：

1. 查看 `mx-daemon` 服务状态。

   ```bash
   sudo systemctl status mx-daemon
   ```

   如果服务日志中出现类似以下信息，表示 `moffett` 内核模块未加载到当前内核路径：

   ```text
   modprobe: FATAL: Module moffett not found in directory /lib/modules/6.1.0-41-amd64
   ```

2. 查看当前内核版本。

   ```bash
   uname -r
   ```

3. 查看 `moffett` 内核模块是否已加载。

   ```bash
   lsmod | grep moffett
   ```

4. 如果命令输出为空，按照{ref}`安装 SOLA Toolkit <install-sola-toolkit>`中的步骤重新安装 SOLA Toolkit。