Usage on the Docker Client

Usage Instruction

Ascend Docker Runtime supports both physical and virtual processors. Before mounting a virtual processor, virtualize the corresponding physical processor statically or dynamically by referring to Creating vNPUs.
You can run the ls /dev/davinci* and ls /dev/vdavinci* commands to query the IDs of available physical and virtual processors, respectively.
If you do not need to mount all content in the default configuration file /etc/ascend-docker-runtime.d/base.list of Ascend Docker Runtime, you can create a custom configuration file (for example, hostlog.list) to reduce the content to be mounted. For details, see (Optional) Configuring Custom Mounted Content.

Using Ascend Docker Runtime to Mount Processors

In the example, image-name:tag indicates the image name and tag. For details about other parameters, see Table 1.

Example 1: Mount a processor whose physical processor ID is 0 when starting a container.
```
docker run -it -e ASCEND_VISIBLE_DEVICES=0 image-name:tag /bin/bash
```
Example 2: Mount only NPU and management devices when starting a container. Do not mount driver-related directories.
```
docker run --rm -it -e ASCEND_VISIBLE_DEVICES=0 -e ASCEND_RUNTIME_OPTIONS=NODRV image-name:tag /bin/bash
```
Example 3: Mount a processor whose physical processor ID is 0 and read the mounted content of hostlog.list when starting a container.
```
docker run --rm -it -e ASCEND_VISIBLE_DEVICES=0 -e ASCEND_RUNTIME_MOUNTS=hostlog image-name:tag /bin/bash
```

Example 4: Mount a processor whose virtual processor ID is 100 when starting a container.

docker run -it -e ASCEND_VISIBLE_DEVICES=100 -e ASCEND_RUNTIME_OPTIONS=VIRTUAL image-name:tag /bin/bash

Example 5: Split four AI Cores from a processor whose physical processor ID is 0 as virtual devices and mount them to a container when starting the container.
```
docker run -it --rm -e ASCEND_VISIBLE_DEVICES=0 -e ASCEND_VNPU_SPECS=vir04 image-name:tag /bin/bash
```
Example 6: Mount a processor whose physical processor ID is 0 and allow for soft links in the mounted driver file when starting a container (applicable only to the Atlas 500 A2 edge station, Atlas 200I A2 accelerator module, and Atlas 200I DK A2 developer kit).
```
docker run --rm -it -e ASCEND_VISIBLE_DEVICES=0 -e ASCEND_ALLOW_LINK=True  image-name:tag /bin/bash
```

After a container is started, check whether related devices and drivers are successfully mounted. For details about the mounted directory of each model, see Default Content Mounted by Ascend Docker Runtime. Example command:

ls /dev | grep davinci* && ls /dev | grep devmm_svm && ls /dev | grep hisi_hdc && ls /usr/local/Ascend/driver && ls /usr/local/ |grep dcmi && ls /usr/local/bin

Using Ascend Docker Runtime to Mount Processors and Other Devices

Ascend Docker Runtime can be used to enable containers to run training, inference, or other jobs.

The following uses an Atlas 200I SoC A1 core board as an example to describe how to run an inference container. Change options in commands as required. Table 1 and Table 2 describe related options.

docker run -it -e ASCEND_VISIBLE_DEVICES=0 --device=/dev/xsmem_dev:rwm --device=/dev/event_sched:rwm --device=/dev/svm0:rwm --device=/dev/sys:rwm --device=/dev/vdec:rwm --device=/dev/vpc:rwm --device=/dev/log_drv:rwm --device=/dev/spi_smbus:rwm --device=/dev/upgrade:rwm --device=/dev/user_config:rwm --device=/dev/ts_aisle:rwm --device=/dev/memory_bandwidth:rwm -v /var/dmp_daemon:/var/dmp_daemon:ro -v /var/slogd:/var/slogd:ro -v /var/log/npu/conf/slog/slog.conf:/var/log/npu/conf/slog/slog.conf:ro -v /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 -v /usr/lib64/aicpu_kernels:/usr/lib64/aicpu_kernels:ro -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so:ro -v /sys/fs/cgroup/memory:/sys/fs/cgroup/memory:ro -v /usr/lib64/libyaml-0.so.2:/usr/lib64/libyaml-0.so.2:ro -v /etc/ascend_install.info:/etc/ascend_install.info -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info workload-image:v1.0 /bin/bash

If the driver version of the Atlas 200I SoC A1 core board is 1.0.0 (Ascend HDK 22.0.0) or earlier, you need to mount /dev/xsmem_dev and /dev/event_sched.
If the driver version of the Atlas 200I SoC A1 core board is later than 1.0.0 (Ascend HDK 22.0.0), you do not need to mount /dev/xsmem_dev and /dev/event_sched.

The following uses an Atlas 500 A2 edge station as an example to describe how to run an inference container. Change options in commands as required. Table 1 and Table 2 describe related options.
```
docker run --rm -it -e ASCEND_VISIBLE_DEVICES=0 -e ASCEND_ALLOW_LINK=True  workload-image:v1.0 /bin/bash
```

Not Using Ascend Docker Runtime to Mount Processors or Other Devices

The following uses an Atlas 200I SoC A1 core board as an example to describe how to run an inference container. Change options in commands as required. Table 2 describes related options.

docker run -it --device=/dev/davinci0:rwm --device=/dev/xsmem_dev:rwm --device=/dev/event_sched:rwm --device=/dev/svm0:rwm --device=/dev/sys:rwm --device=/dev/vdec:rwm --device=/dev/venc:rwm --device=/dev/vpc:rwm --device=/dev/davinci_manager:rwm --device=/dev/spi_smbus:rwm --device=/dev/upgrade:rwm --device=/dev/user_config:rwm --device=/dev/ts_aisle:rwm --device=/dev/memory_bandwidth:rwm -v /etc/sys_version.conf:/etc/sys_version.conf:ro -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi:ro -v /var/dmp_daemon:/var/dmp_daemon:ro -v /var/slogd:/var/slogd:ro -v /var/log/npu/conf/slog/slog.conf:/var/log/npu/conf/slog/slog.conf:ro -v /etc/hdcBasic.cfg:/etc/hdcBasic.cfg:ro -v /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 -v /usr/lib64/aicpu_kernels:/usr/lib64/aicpu_kernels:ro -v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so:ro -v /sys/fs/cgroup/memory:/sys/fs/cgroup/memory:ro -v /usr/lib64/libyaml-0.so.2:/usr/lib64/libyaml-0.so.2:ro -v /etc/ascend_install.info:/etc/ascend_install.info -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info workload-image:v1.0 /bin/bash

If the driver version of the Atlas 200I SoC A1 core board is 1.0.0 (Ascend HDK 22.0.0) or earlier, mount /dev/xsmem_dev and /dev/event_sched.
If the driver version of Atlas 200I SoC A1 core board is later than 1.0.0 (Ascend HDK 22.0.0), you do not need to mount /dev/xsmem_dev and /dev/event_sched.

The Atlas 500 A2 edge station does not use Ascend Docker Runtime to run inference jobs.

Parameter Description

**Table 1** Ascend Docker Runtime parameters
Parameter	Description	Example
ASCEND_VISIBLE_DEVICES	If a task does not need to use NPU devices, set ASCEND_VISIBLE_DEVICES to void or leave it empty. If a task requires an NPU device, use ASCEND_VISIBLE_DEVICES to specify the NPU device to be mounted to the container. Otherwise, the NPU device fails to be mounted. If the device ID is used to specify a device, you can specify only one device or multiple devices at a time. If the processor ID is used to specify a device, you can specify multiple processors of the same type at a time.	ASCEND_VISIBLE_DEVICES=void indicates that the mounting function of Ascend Docker Runtime is not used and the NPU device, driver, and file directory are not mounted. Related mounting parameters also become invalid. Physical processors (NPUs) ASCEND_VISIBLE_DEVICES=0 indicates that NPU device 0 (/dev/davinci0) is mounted to the container. ASCEND_VISIBLE_DEVICES=1,3 indicates that NPU devices 1 and 3 are mounted to the container. ASCEND_VISIBLE_DEVICES=0-2 indicates that NPU devices 0 to 2 (including devices 0 and 2) are mounted to the container. The effect is the same as that of -e ASCEND_VISIBLE_DEVICES=0,1,2. ASCEND_VISIBLE_DEVICES=0-2,4 indicates that NPU devices 0 to 2 and device 4 are mounted to the container. The effect is the same as that of -e ASCEND_VISIBLE_DEVICES=0,1,2,4. ASCEND_VISIBLE_DEVICES=AscendXXX-Y: XXX indicates the NPU model. The value can be 910, 310, 310B, or 310P. Y indicates the NPU device ID. ASCEND_VISIBLE_DEVICES=Ascend910-1 indicates that NPU device 1 is mounted to the container. ASCEND_VISIBLE_DEVICES=Ascend910-1,Ascend910-3 indicates that NPU devices 1 and 3 are mounted to the container. NOTE: The NPU type must be the same as that used in the actual environment. Otherwise, the mounting fails. You cannot specify both the device ID and NPU in a parameter. That is, ASCEND_VISIBLE_DEVICES=0, Ascend910-1 is not supported. Virtual processors (vNPUs) Static virtualization: The mounting method is the same as that of physical processors. You only need to replace physical processor IDs with virtual processor IDs (vNPU IDs). Dynamic virtualization: ASCEND_VISIBLE_DEVICES=0 indicates that a certain number of AI Cores are allocated from NPU device 0. NOTE: A dynamic virtualization command can specify only one physical NPU ID for dynamic virtualization. It must be used together with ASCEND_VNPU_SPECS, to specify the number of AI Cores split on a specified NPU. It can be used together with ASCEND_RUNTIME_OPTIONS, but the value can only be NODRV, indicating that driver-related directories are not mounted.
ASCEND_ALLOW_LINK	Specifies whether soft links are allowed in the mounted file or directory. This parameter must be specified for the Atlas 500 A2 edge station, Atlas 200I A2 accelerator module, and Atlas 200I DK A2 developer kit. NOTE: Other devices such as Atlas training product, Atlas A2 training product, and Atlas 200I SoC A1 core boards can use this parameter. However, this parameter does not need to be specified because their default mounted content does not contain soft links.	If ASCEND_ALLOW_LINK is set to True, driver files with soft links can be mounted for the Atlas 500 A2 edge station, Atlas 200I A2 accelerator module, and Atlas 200I DK A2 developer kit. If ASCEND_ALLOW_LINK is set to False or this parameter is not specified, the Atlas 500 A2 edge station, Atlas 200I A2 accelerator module, and Atlas 200I DK A2 developer kit cannot use Ascend Docker Runtime.
ASCEND_RUNTIME_OPTIONS	Restricts the processor ID specified by ASCEND_VISIBLE_DEVICES. NODRV indicates that driver-related directories are not mounted. VIRTUAL indicates that the virtual processor is mounted. NODRV,VIRTUAL indicates that the virtual processor is mounted while driver-related directories are not mounted.	ASCEND_RUNTIME_OPTIONS=NODRV ASCEND_RUNTIME_OPTIONS=VIRTUAL ASCEND_RUNTIME_OPTIONS=NODRV,VIRTUAL
ASCEND_RUNTIME_MOUNTS	Name of the configuration file with content to be mounted. You can configure the files and directories to be mounted to the container in this file.	ASCEND_RUNTIME_MOUNTS=base ASCEND_RUNTIME_MOUNTS=hostlog ASCEND_RUNTIME_MOUNTS=hostlog,hostlog1,hostlog2 NOTE: By default, the /etc/ascend-docker-runtime.d/base.list configuration file is read. Change hostlog.list to the actual configuration file name. Multiple custom configuration files can be read. The file name must be in lowercase. Uppercase letters are not allowed.
ASCEND_VNPU_SPECS	Splits a certain number of AI Cores from a physical NPU device and specifies them as virtual devices. The following values are supported: vir01, vir02, vir02_1c, vir04, vir04_3c, vir04_4c_dvpp, and vir04_3c_ndvpp for Atlas inference product vir02, vir04, vir08, and vir16 for Atlas training product This parameter must be used together with ASCEND_VISIBLE_DEVICES that specifies the physical NPU device to be split. NOTE: If the value of ASCEND_RUNTIME_OPTIONS contains VIRTUAL, ASCEND_VNPU_SPECS does not take effect.	ASCEND_VNPU_SPECS=vir04 indicates that four AI Cores are used as virtual devices and mounted to the container. NOTE: The number following vir indicates the number of AI Cores. The number before c indicates the number of AI CPUs. dvpp indicates that all digital vision pre-processing (DVPP) modules (VPC, VDEC, JPEGD, PNGD, VENC and JPEGE) are included during virtualization. ndvpp indicates that DVPP hardware resources are excluded during virtualization.

**Table 2** Description of other parameters
Parameter	Parameter Description
/dev/xsmem_dev	Mounts the device that manages the memory to the container.
/dev/event_sched	Mounts the device for event scheduling to the container.
/dev/ts_aisle	Mounts the device corresponding to the aicpudrv driver to the container.
/dev/svm0	Mounts the device for memory management to the container.
/dev/sys	Mounts the DVPP-related device to the container.
/dev/vdec	Mounts the DVPP-related device to the container.
/dev/vpc	Mounts the DVPP-related device to the container.
/dev/log_drv	Mounts the device that records logs to the container.
/dev/upgrade	Mounts the device that obtains the Ascend system configuration and firmware information to the container.
/dev/spi_smbus	Mounts the device that uses out-of-band SPI communication to the container.
/dev/user_config	Mounts the device that is related to the management user configuration to the container.
/dev/memory_bandwidth	Mounts the device that is related to the memory bandwidth to the container.
-v /var/slogd:/var/slogd	Mounts the log process file of the host to the container in read-only mode.
-v /var/dmp_daemon:/var/dmp_daemon	Mounts the DMP daemon to the container.
-v /var/log/npu/conf/slog:/var/log/npu/conf/slog	Mounts the NPU log module to the container.
-v /usr/lib64/libyaml-0.so.2:/usr/lib64/libyaml-0.so.2:ro	Mounts the .so file of libyaml on the host to the container.
-v /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools	Mounts /usr/local/Ascend/driver/tools (driver-related tool directory) to the container.
-v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64	Mounts /usr/local/Ascend/driver/lib64 (dynamic library directory of the driver dependency) to the container.
-v /usr/lib64/libtensorflow.so:/usr/lib64/libtensorflow.so	Mounts /usr/lib64/libtensorflow.so (AI CPU operator library file of TensorFlow) to the container.
-v /usr/lib64/aicpu_kernels:/usr/lib64/aicpu_kernels	Mounts /usr/lib64/aicpu_kernels (AI CPU operator library directory) to the container.
-v /sys/fs/cgroup/memory:/sys/fs/cgroup/memory:ro	Mounts the /sys/fs/cgroup/memory directory required for querying the host memory usage to the container in read-only mode.
-v /etc/ascend_install.info:/etc/ascend_install.info	Mounts the host installation information file /etc/ascend_install.info to the container.
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info	Mounts the host version information file /usr/local/Ascend/driver/version.info to the container. Modify the file according to your actual requirements.
workload-image:v1.0	Indicates the generated image file.
/bin/bash	Starts the interactive Bash Shell in the container.

Parent topic: Containerization Feature Guide