Quick Start

This guide helps you quickly get started with the driver repository. The driver development and contribution process is shown in the figure below. We welcome and encourage you to contribute to the community and jointly enrich the project ecosystem.

graph LR
subgraph Development Phase
Environment Preparation
Repository Code Download
Driver Development
Compile and Deploy
Verification
end
subgraph Open Source Contribution Phase
Submit PR
CI Gate
Committer Review
Maintainer Review and Merge
end

User-->Environment Preparation-->Repository Code Download-->Driver Development-->Compile and Deploy-->Verification-->Submit PR-->CI Gate-->Committer Review-->Maintainer Review and Merge

1. Environment Deployment and Compilation: Set up development and runtime environment, compile source code, and deploy installation.

2. Debugging and Verification: Log viewing and setting guidance during development and runtime.

3. Development Guide: Guide for custom driver development, learn how to develop, compile, and verify code from scratch.

I. Environment Deployment and Compilation

1. Compile Environment Preparation

Driver supports source code compilation. Before source code compilation, complete the relevant environment preparation according to the following steps.

Driver source code compilation requires installing the following dependent software:

gcc
cmake
bash
kernel-headers
net-tools
openssl development library
pkg-config
patch
googletest (optional, only required when running UT tests, recommended version release-1.11.0)
makeself (required when compiling run package locally, download link)

If not installed, please obtain and install from the corresponding operating system vendor website based on the Linux distribution used.

# Using openeuler environment as example:
yum install -y tar net-tools kernel-headers-$(uname -r) kernel-devel-$(uname -r) openssl-devel pkg-config patch
yum install -y gcc gcc-c++ g++ cmake make libffi libffi-devel binutils binutils-devel elfutils elfutils-devel elfutils-libelf-devel

# Using ubuntu environment as example:
apt install -y tar net-tools linux-headers-$(uname -r) gcc g++ cmake make libffi-dev libssl-dev pkg-config patch

2. Source Code Download

Execute the following command to download Driver repository source code:

git clone https://gitcode.com/cann/driver.git

3. Source Code Compilation and Deployment

Compilation depends on open-source third-party libraries and Driver open-source binary libraries. After starting compilation, they will be automatically downloaded. Please keep the network accessible.

Recommended OS versions: linux v5.4, linux v5.10, or linux v6.8.

1. Execute source code compilation according to the following command:

bash build.sh --pkg --soc=${chip_type}

${chip_type} represents chip type, currently including ascend910b, ascend910_93, and ascend950.

After compilation, the Ascend-hdk-<chip_type>-driver-<version>_<os_version>-<arch>.run software package will be generated in the build_out directory.

Notes:

Before repeatedly executing this compilation command, you need to manually clean the files generated by the previous compilation, otherwise there may be cache.
ascend950 does not support compilation on ARM environment.

# Clean command
bash build.sh --make_clean

2. Deployment installation:

Execute the following command to install Driver package:

./Ascend-hdk-<chip_type>-driver-<version>_<os_version>-<arch>.run --full

<chip_type> represents chip type, currently including 910b, A3, and 950. <version> represents software package version number, for example 8.5.0. <os_version> represents operating system distribution version, for example Ubuntu20.04, openEuler22.03. <arch> represents chip architecture, with values including x86_64 and aarch64.

After installation, the user-compiled Driver software package will replace the Driver-related software in the installed CANN development kit package.

If you need to install firmware package, obtain the matching hardware product firmware package from Ascend official website, and install according to the matching version Installation Guide (after selecting installation scenario, refer to "Installing NPU Driver and Firmware" section).

4. Other Features

For more compilation parameters, run bash build.sh -h.

5. Software Package Uninstallation

Uninstall according to the matching version Uninstallation Guide (after selecting installation guide, refer to "Uninstallation" section).

II. Debugging and Verification

During development, if you encounter program debugging issues, you should first check the user-mode logs generated by application runtime on the Host side (hereinafter referred to as application logs), then check the kernel-mode logs on the Host side through "dmesg" or system log files. If the issue still cannot be located, use the msnpureport tool to export more detailed Device-side logs (hereinafter referred to as system logs).

Application logs and system logs default recording level is "ERROR". If "ERROR" level logs are insufficient for issue location, you can set a more detailed log level (such as "DEBUG") for in-depth analysis.

1. Log Viewing

View application logs: Please refer to the matching version Log Reference, get detailed instructions in the "Viewing Application Logs" section.
View Host-side kernel logs:
- To view "ERROR" level logs, execute the following command:
```
dmesg
```
  Or view "/var/log/messages" or "/var/log/syslog" based on operating system.
- To view "INFO", "WARNING", "EVENT" level logs generated during runtime, execute the following command to export logs:
```
/usr/local/Ascend/driver/tools/msnpureport -f
```
  After execution, a directory named with timestamp will be generated. The log file is located at: "./timestamp/slog/host/host_kernel.log".
View system logs: Please refer to the matching version Log Reference, get detailed instructions in the "Viewing System Logs" section.

2. Log Setting

Application log level setting: Please refer to Log Reference, get configuration method in the "Setting Application Log Level" section.
System log level setting: Please refer to Log Reference, get configuration method in the "Setting System Log Level" section.

III. Development Guide

This stage aims to familiarize you with driver development by adding new interfaces in driver code. Here we use adding DCMI interface as an example.

1. Modify Driver Code

Add a new dsmi interface in driver/src/ascend_hal/dmc/dsmi/dsmi_common/dsmi_common_interface.c file, code as follows:

int dsmi_get_host_device_connect_type(int device_id, unsigned int *connect_type)
{
    int ret;
    struct devdrv_device_info dev_info = { 0 };

    if (connect_type == NULL) {
        return DRV_ERROR_INVALID_VALUE;
    }

    /* drvGetDevInfo: Get NPU device information */
    ret = drvGetDevInfo((unsigned int)device_id, &dev_info);
    if (ret == (int)DRV_ERROR_RESOURCE_OCCUPIED) {
        return DRV_ERROR_RESOURCE_OCCUPIED;
    }

    *connect_type = dev_info.host_device_connect_type;
    return 0;
}

Also add interface declaration in driver/pkg_inc/dsmi_common_interface.h file.

/**
* @ingroup driver
* @brief host-device connect types
* @attention null
* @param [in]  device_id  device id
* @param [out] connect_type  host-device connect types
* @return  0 for success, others for fail
*/
int dsmi_get_host_device_connect_type(int device_id, unsigned int *connect_type);

Add a new dcmi interface in driver/src/custom/dev_prod/user/dcmi/dcmi_interface/src/dcmi_basic_info_intf.c file, code as follows:

int dcmi_get_host_device_connect_type(int device_id, unsigned int *connect_type)
    {
        int ret;
    
        if (dcmi_get_run_env_init_flag() != TRUE) {
            gplog(LOG_ERR, "not init.");
            return DCMI_ERR_CODE_NOT_REDAY;
        }
    
        if ((connect_type == NULL) || (device_id < 0)) {
            gplog(LOG_ERR, "para is invalid");
            return DCMI_ERR_CODE_INVALID_PARAMETER;
        }
    
        ret = dsmi_get_host_device_connect_type(device_id, connect_type);
        if (ret != DCMI_OK) {
            gplog(LOG_ERR, "call dsmi_get_host_device_connect_type failed. err is %d.", ret);
            return ret;
        }
    
        return DCMI_OK;
    }

2. Compile and Update Driver Package

Refer to Environment Deployment and Compilation section steps 1~2, recompile and install driver package.