Intelligent Computing LINGJUN:gRPC API reference

1.1 Proto files and client stub generation

The Device Plugin and the Exporter both communicate with Lingjun Runtime Kit over the same Unix Domain Socket (dp2mgr.sock) and share the same proto definitions. You can obtain the resource management and monitoring proto files from the Device Plugin component in the open source repository (path internal/grpc/api_outer.proto). The Controller uses a separate config-daemon.sock and a separate proto file, located at api/proto/config_service.proto in the Controller component (see Section 5).

The following examples generate client stubs in different languages:

# Go (recommended, consistent with the component source code)
protoc --go_out=plugins=grpc:. api_outer.proto

# Python
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. api_outer.proto

# Java
protoc --java_out=. --grpc-java_out=. api_outer.proto

1.2 Go invocation example

The following example follows the invocation approach in the Device Plugin source code:

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
)

socketPath := "unix:///run/amp/eKitC/xdm/sockets/dp2mgr.sock"
conn, err := grpc.Dial(socketPath, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
    log.Fatalf("connect failed: %v", err)
}
defer conn.Close()

client := NewXpuDeviceManagerServiceClient(conn)
// Example: query the xPU types supported by the node
resp, err := client.ListSupportedXPUType(context.Background(), &XPUTypeRequest{})

Note: The service and client names in the example (XpuDeviceManagerService) are generated from the proto definitions. Always refer to the proto files in the open source repository.

3.1 ListSupportedXPUType

Queries the xPU device types supported by the current node. Request: no parameters (empty request).

Response fields:

3.2 ListAndWatch

Streams node device lists and health status changes. Request: no parameters (empty request).

Response fields (streamed; each push contains the complete device list):

3.3 Allocate

The core resource allocation API. It allocates xPU resources to containers.

Request fields:

devices is a repeated field: each element corresponds to one independent GPU card, and multiple elements mean "allocate multiple cards to this container". Only homogeneous configurations are supported: all elements must use the same core/memory/slice values. If minor is left empty, Lingjun Runtime Kit automatically assigns an available card number.

Device allocation fields (devices[]):

extender field:

In the Allocate request, devices[].extender is a generic extension field (map<string, string>). It pairs with extenderResources in the ListAndWatch response, forming an upstream/downstream pair: ListAndWatch reports device topology upstream, and Allocate returns the scheduling decision of the scheduler downstream.

Currently defined keys:

Response fields:

Field conventions by scenario:

Key constraints:

• If core is left empty or set to 0, compute limits are disabled (the whole card is available). The valid range is 1–100, as a percentage of one card. For multiple cards, use the devices array (one card per element).

• The unit of memory in the Allocate request is GiB, while totalMemory returned by ListAndWatch uses MiB.

• Setting either core or memory to 0 means that compute or memory is not limited. If both are 0 and no other resources are requested, the container is treated as a CPU container.

• If minor is specified, the given card number is used (suitable for scenarios with an upper-level scheduler). If it is left empty, Lingjun Runtime Kit automatically assigns a card number.

• Valid values of slice are 1, 2, 3, 4, and 7. MIG partitioning currently supports the A100 and H800 GPU models.

featureGates and annotations fields: Both fields are reserved extension fields (featureGates is map<int32, bool>, and annotations is map<string, string>). No specific features are enabled in the current version. Design intent: featureGates will be used to enable feature gates on demand in later versions, and annotations carries additional context between the caller and Lingjun Runtime Kit. In standard usage, leave both fields empty. For custom development, you can use annotations to pass custom key-value pairs, which Runtime Kit passes through and returns in the response.

Request examples:

Whole-card allocation (two cards):

{ "id": "550e8400-e29b-41d4-a716-446655440000", "devices": [{ "minor": 1 }, { "minor": 2 }] }

Time-division multiplexing (50% compute + 4 GiB memory):

{ "id": "550e8400-e29b-41d4-a716-446655440001", "devices": [{ "minor": 1, "core": 50, "memory": 4 }] }

MIG spatial partitioning:

{ "id": "550e8400-e29b-41d4-a716-446655440004", "devices": [{ "minor": 1, "slice": 3, "memory": 4 }] }

3.4 extenderResources and topology information

In the ListAndWatch response, devices[].extenderResources is a generic extension field (map<string, string>) that the Device Plugin uses to pass additional device attributes beyond the standard fields to the scheduler.

Currently defined keys:

The topology value is a JSON string serialized from a per-device topology object. XDM collects the hardware and network topology and abstracts it into hierarchical ordinals sorted by distance. Through ListAndWatch, XDM passes the object to the Device Plugin in the extenderResources["topology"] field of each card. The Device Plugin translates the level segments into node annotations and labels, which the scheduler consumes. The object has the form {"levels": [...]}, where levels contains all topology levels of the card, and each element describes one topology level:

PPU M890P per-device example (GPU 0):

{
  "levels": [
    {"level": 1,  "name": "pcieSwitches",    "topo1": [0],  "peers": [0, 1]},
    {"level": 2,  "name": "numaNodes",       "topo2": [0],  "peers": [0, 1]},
    {"level": 3,  "name": "cpuSockets",      "topo3": [0],  "peers": [0, 1, 2, 3]},
    {"level": 11, "name": "hyperNode",       "topo11": "hypernode-001"},
    {"level": 21, "name": "leafSwitch",      "topo21": "asw-001"},
    {"level": 22, "name": "pointOfDelivery", "topo22": "pod-g13-p1"}
  ]
}

The three intra-node layers of M890P (pcieSwitches / numaNodes / cpuSockets) carry peers and topoN, while the rack layer (hyperNode) and the network layers (leafSwitch / pointOfDelivery) carry only topoN string identifiers. The Device Plugin and the scheduler translate the device indexes carried by topo1 into concrete GPU↔RDMA device mappings; other levels are translated in the same way.

PPU 810E per-device example (GPU 0; includes intra-node interconnect layers + PCIe layers + network layers):

{
  "levels": [
    {"level": 1,  "name": "icnLink2",        "topo1": [0],  "peers": [0, 3]},
    {"level": 2,  "name": "icnLink4",        "topo2": [0],  "peers": [0, 1, 2, 3]},
    {"level": 3,  "name": "icnLink8",        "topo3": [0],  "peers": [0, 1, 2, 3, 4, 5, 6, 7]},
    {"level": 4,  "name": "pcieSwitches",    "topo4": [4],  "peers": [0, 1, 2, 3]},
    {"level": 5,  "name": "numaNodes",       "topo5": [1],  "peers": [0, 1, 2, 3, 8, 9, 10, 11]},
    {"level": 6,  "name": "cpuSockets",      "topo6": [0]},
    {"level": 21, "name": "leafSwitch",      "topo21": "ASW-VM-SQA-G10-P2-S25"},
    {"level": 22, "name": "pointOfDelivery", "topo22": "VM-SQA-G10-P2"}
  ]
}

Within an 810E node, the levels first cover the inter-card interconnect layers (icnLink2 / icnLink4 / icnLink8, where peers reflect the actual link connections and are not necessarily consecutive), then the PCIe physical layers (pcieSwitches / numaNodes / cpuSockets), and optionally the network layers (leafSwitch / pointOfDelivery).

Field semantics (level/topoN abstraction contract):

Sorting the levels by level in ascending order arranges them from nearest to farthest. The scheduler uses this ordering to prefer combinations with the shortest topology distance in multi-card and cross-node scenarios. Level segments that a device model does not have (for example, no rack segment) are omitted.

3.5 Release

Releases the device allocation records of a container (the reverse operation of Allocate). The Device Plugin calls this API when a container is destroyed, and XDM then reclaims the device resources used by the container.

Request fields:

Response fields:

Request example:

{ "id": "550e8400-e29b-41d4-a716-446655440000" }

Response example:

{ "status": 0, "message": "" }

4.1 ListGpuInfo

Gets static information about GPU devices on the node, such as the model, UUID, and driver version.

Request fields:

Response fields:

4.2 ExporterGetDataList

Pulls a metric snapshot in a single call, filtered by device and metric ID. This API is suitable for periodic metric collection.

Request fields:

Response fields (dataList[]):

4.3 ExporterDataStream

A streaming API over a persistent connection. The core service (XDM) continuously pushes metric updates at each collection interval. The request and response formats match ExporterGetDataList. Clients must implement reconnection with exponential backoff (recommended settings: initial interval 1 second, multiplier 2, maximum 30 seconds).

4.4 ExporterGetConfig

Gets the Exporter collection configuration.

Response fields:

4.5 ExporterGetStatus

Queries the running status of the Exporter.

Response fields:

5.1 Enable

Enables Runtime Kit features on the node. Request: EnableRequest {} (no parameters).

Response fields (EnableResponse):

5.2 Disable

Disables Runtime Kit features on the node. Request: DisableRequest {} (no parameters). Response: DisableResponse (the fields match EnableResponse).

5.3 QueryStatus

Queries whether Runtime Kit features are enabled on the node. Request: QueryStatusRequest {} (no parameters).

Response fields (QueryStatusResponse):

Invocation example (Go):

// Connect to the config-daemon Unix socket
conn, err := grpc.Dial(
    "unix:///run/amp/eKitC/xdm/sockets/config-daemon.sock",
    grpc.WithTransportCredentials(insecure.NewCredentials()),
)
client := configpb.NewAmpConfigServiceClient(conn)

// Enable
resp, err := client.Enable(ctx, &configpb.EnableRequest{})

// Query the status
status, err := client.QueryStatus(ctx, &configpb.QueryStatusRequest{})
fmt.Println("enabled:", status.Enabled)