HGGC-Samples is a collection of sample programs for HGGC developers, demonstrating various features of the T-Head SAIL toolkit. The current version supports SAIL 2.1.

For system requirements and installation instructions for the T-Head SAIL toolkit, please refer to the T-Head SAIL SDK Installation Guide.

Use git to clone the HGGC samples repository (see command below).

git clone git@github.com:t-head/hggc-samples.git

If you prefer not to use git, the simplest approach is to click the "Download ZIP" button on the repository page to download the archive of the current version, then extract and use these samples.

HGGC samples use CMake for building. Please follow the Linux build instructions below.

Ensure that CMake (version 3.20 or later) is installed. If necessary, install it via the package manager:

For example: sudo apt install cmake

Navigate to the root directory of the cloned repository and create a build directory:

mkdir build && cd build

Configure the project with CMake:

cmake ..

By default, HGGC samples are built for both ppu001 (--gpu-architecture=ppu_10) and ppu0015 (--gpu-architecture=ppu_15) PPU architectures. To build for a specific architecture only, set CMAKE_HG_ARCHITECTURES at configure time:

cmake -DCMAKE_HG_ARCHITECTURES=ppu_10 ..

Build the samples:

make -j$(nproc)

Run the samples from their respective subdirectories within the build directory. You may also perform the above steps from any subdirectory of the samples repository, or from an individual sample directory.

A small number of samples use instructions that are only available on ppu001 hardware. These samples are automatically built for ppu001 (ppu_10) only, even when the default dual-architecture configuration is used. Their README files indicate this limitation under Supported PPU Architectures.

Note that HGGC samples are not a validation suite for HGGC. They do not cover edge cases, do not fully cover the runtime and driver APIs, and are not intended for performance benchmarking. We provide the run_tests.py script to run all samples as a quick sanity check.

This Python 3 script searches for all .out executables in the subdirectory you specify (automatically excluding temporary files generated by the CMake build system) and matches application names against command-line arguments specified in test_args.json. It accepts the following command-line arguments:

Application configuration is loaded from test_args.json and matched against executable names.

When test_args.json is loaded, the script detects the target PPU architecture from the Compute Capability reported by ppu-smi -q and skips samples whose skip_arch list includes that architecture. You can override the detected architecture with --arch. Samples that require more than one PPU are also skipped automatically when fewer devices are available.

The script returns 0 on success and the first non-zero error code encountered on test failure. A summary list of failed samples is also printed if any failures occur.

Configuration example:

{
    "multi_device_collab": {
        "min_ppus": 2
    },
    "aiu_gemm": {
        "skip_arch": ["ppu0015"]
    }
}

Below is a set of example commands for building and testing all samples.

First, build:

mkdir build && cd build
cmake ..
make -j$(nproc)

Then run the test script:

# Basic usage (auto-loads test_args.json if present)
python3 run_tests.py --dir ./build --output ./test

# Explicit configuration file
python3 run_tests.py --dir ./build --output ./test --config test_args.json

# Parallel execution
python3 run_tests.py --dir ./build --output ./test --parallel 4

# Disable configuration loading
python3 run_tests.py --dir ./build --output ./test --no-config

# Override target architecture for skip checks
python3 run_tests.py --dir ./build --output ./test --arch ppu0015

If all applications run successfully, you will see output similar to:

Test Summary:
Ran N test runs for N executables.
All test runs passed!

If some samples fail, you will see output similar to:

Test Summary:
Ran N test runs for N executables.
Failed runs (2):
  acdnn_conv_activation: Failed (code 1)
  multi_device_collab: Failed (code 1)

You can inspect the stdout logs in the output directory (typically APM_<application_name>.txt or APM_<application_name>.run<n>.txt) to determine what may have gone wrong. If you believe a sample has failed unreasonably on your system, please file an issue in the samples repository.

Basic HGGC samples for beginners, demonstrating core concepts of using HGGC and the HGGC Runtime API.

Utility samples demonstrating how to query device capabilities and measure Zhenwu PPU/CPU bandwidth.

Samples demonstrating HGGC-related algorithms and common problem-solving techniques.

Samples demonstrating HGGC features.

Samples demonstrating how to use HGGC platform libraries.

Samples demonstrating performance optimization.

Some HGGC samples depend on third-party applications and/or libraries, or on features provided by the HGGC toolkit and drivers, in order to build or execute. These dependencies are listed below.

If a third-party library that a sample depends on is available on the system but not installed, that sample will be automatically skipped during the build.

Dependencies for each sample are listed in the "Dependencies" section of its README.

The following third-party dependencies are required by some HGGC samples. When available, these dependencies are typically already installed on the system or can be installed via the system package manager (Linux) or third-party websites.

MPI (Message Passing Interface) is an API for inter-process data communication in distributed systems. MPI compilers can be installed via the Linux distribution's package manager or obtained from online resources such as Open MPI.

OpenMP is an API for multiprocess programming that can be installed via the Linux distribution's package manager, is typically pre-installed with GCC, or can be obtained from the OpenMP website.

Some HGGC samples demonstrate the following HGGC features.

Multi-Block Cooperative Groups (MBCG) extend Cooperative Groups and the HGGC programming model to express inter-thread-block synchronization.

Multi-Device Cooperative Groups extend Cooperative Groups and the HGGC programming model, enabling thread blocks executing on multiple Zhenwu PPUs to cooperate and synchronize.

HGRTC (HGGC Runtime Compilation) is a runtime compilation library for HGGC C++.

UVM (Unified Virtual Memory) allows the CPU and Zhenwu PPU to access the same memory without explicit copying. UVM is only available on Linux systems.

FP16 is a 16-bit floating-point format. 1 bit is used for the sign, 5 bits for the exponent, and 10 bits for the mantissa.

hgcc supports C++11 features.

For answers to common HGGC questions, please refer to the SAIL Toolkit Release Notes.

HGGC-Samples is a collection of sample programs developed by T-Head (Shanghai) Semiconductor Co., Ltd. and licensed under the Apache License, Version 2.0.

See the NOTICE file for more information.