openeuler/maca-sdk repository overview

⁠Quick reference

• The official MACA (MetaX Accelerated Computing Architecture) SDK docker image.

• Maintained by: openEuler Intelligence SIG⁠.

• Where to get help: openEuler Intelligence SIG⁠, openEuler⁠.

⁠MACA SDK | openEuler

Current MACA SDK docker images are built on the openEuler⁠. This repository is free to use and exempted from per-user rate limits.

MACA (MetaX Accelerated Computing Architecture, also marketed as MXMACA) is the heterogeneous compute software stack developed by MetaX (沐曦)⁠ for the 曦云 (XiYun / C500) series general-purpose computing GPUs. It provides the runtime, compilers, operator libraries and toolchain that let you quickly build AI training, inference and HPC applications on top of MetaX GPUs.

Learn more in the MetaX Developer Community⁠.

⁠Supported tags and respective Dockerfile links

The tag of each maca-sdk docker image is composed of the SDK version and the openEuler base image version. The details are as follows

⁠Usage

In this usage, users can select the corresponding {Tag} and container startup options based on their requirements.

• Pull the openeuler/maca-sdk image from docker

  docker pull openeuler/maca-sdk:{Tag}
  

  Copy

• Start a maca-sdk instance

  docker run -it \
    --device /dev/dri \
    --device /dev/mxcd \
    --device /dev/fuse \
    --cap-add SYS_ADMIN \
    --group-add video \
    --network=host \
    -v /sys/kernel/debug:/sys/kernel/debug \
    -v /opt/mxdriver:/opt/mxdriver \
    -v /usr/bin/mx-smi:/usr/bin/mx-smi \
    --name mxsdk \
    openeuler/maca-sdk:{Tag}
  

  Copy

  InfiniBand/RDMA support is optional. If it is required, check which device nodes exist on the host with ls -1 /dev/infiniband, then add only the required nodes to the command above. A typical RDMA workload uses:

  --device /dev/infiniband/rdma_cm \
  --device /dev/infiniband/uverbs0
  

  Copy

  For hosts with multiple RDMA devices, also map each required user-verbs node (for example, /dev/infiniband/uverbs1). Management tools may additionally require /dev/infiniband/umad0 or /dev/infiniband/issm0 (and their numbered variants). Do not add nodes that do not exist on the host.

• Container startup options

  Option	Description
  --name mxsdk	Names the container mxsdk.
  --device /dev/dri	Maps the Direct Rendering Infrastructure (DRM) render nodes so the container can access the GPU graphics/compute context.
  --device /dev/mxcd	Maps the MetaX compute device (mxcd), the entry point used by MACA to submit compute tasks to the GPU.
  --device /dev/fuse	Maps the FUSE device so the container can use FUSE-based filesystems.
  --cap-add SYS_ADMIN	Grants the SYS_ADMIN capability required to mount FUSE filesystems inside the container. Only use this option with trusted containers.
  Optional: --device /dev/infiniband/rdma_cm	Maps the RDMA connection-manager node when InfiniBand/RDMA is used.
  Optional: --device /dev/infiniband/uverbs<N>	Maps a user-verbs node such as uverbs0; repeat this option for each RDMA device required by the workload.
  Optional: --device /dev/infiniband/umad<N>	Maps a userspace management-datagram node such as umad0; needed only by InfiniBand management tools.
  Optional: --device /dev/infiniband/issm<N>	Maps an InfiniBand subnet-management node such as issm0; needed only by subnet-manager tools.
  --group-add video	Adds the container's user to the host video group so it has the permissions required to access /dev/dri/*.
  --network=host	Shares the host network namespace. Required by some distributed training and RPC backends; remove if you prefer bridge networking.
  -v /sys/kernel/debug:/sys/kernel/debug	Mounts the host debugfs so driver/runtime diagnostics (e.g. profiling tools) can be collected.
  -v /opt/mxdriver:/opt/mxdriver	Mounts the host MetaX driver directory into the container. The MACA runtime must match the driver version installed on the host.
  -v /usr/bin/mx-smi:/usr/bin/mx-smi	Mounts the host mx-smi (MetaX System Management Interface) tool so you can query GPU status from inside the container.
  -it	Starts the container in interactive mode with a terminal.
  openeuler/maca-sdk:{Tag}	Specifies the Docker image to run, replace {Tag} with the specific version or tag of the openeuler/maca-sdk image you want to use.

• Verify that the GPU is visible inside the container

  mx-smi
  

  Copy

• View container running logs

  docker logs -f mxsdk
  

  Copy

• To get an interactive shell

  docker exec -it mxsdk /bin/bash
  

  Copy

⁠Question and answering

If you have any questions or want to use some special features, please submit an issue or a pull request on openeuler-docker-images⁠.