gen-fields

DCGM Fields Generator

This tool generates Go constants from the DCGM C header file dcgm_fields.h.

Overview

The generator parses dcgm_fields.h and generates a Go file with:

• Typed constants for each #define DCGM_FI_X <int> in the header.
• Typed const aliases for deprecated header aliases, so old DCGM_FI_* names remain source-compatible.
• dcgmFields: maps canonical name to field ID.
• legacyDCGMFields: maps backward-compatible names to the same IDs. Populated from two sources:
  • Hand-curated DCGM 1.x era lowercase names (e.g. dcgm_gpu_temp) listed in pkg/dcgm/legacy_fields.csv.
  • Deprecated-alias #define OLD NEW lines in the header, either inside an #ifdef DCGM_DEPRECATED block or preceded by a Deprecated: comment.
• Helper functions: GetFieldID, GetFieldIDOrPanic, IsLegacyField, IsCurrentField.

Usage

The generator is typically invoked via go generate or make generate:

# Via Make
make generate

# Via go generate
go generate ./...

Direct Usage

You can also run the generator directly:

go run cmd/gen-fields/main.go cmd/gen-fields/template.go \
    --legacy-fields pkg/dcgm/legacy_fields.csv \
    pkg/dcgm/dcgm_fields.h \
    pkg/dcgm/const_fields.go

Arguments:

1. Optional --legacy-fields CSV path for curated lowercase names; when omitted, the generator reads legacy_fields.csv from the output file's directory.
2. Path to dcgm_fields.h (input)
3. Path to const_fields.go (output)

How It Works

1. Parse header: reads dcgm_fields.h. Two shapes of #define are extracted:
   • #define DCGM_FI_X <int> -> canonical field, with preceding comment captured as its description.
   • #define DCGM_FI_OLD DCGM_FI_NEW -> deprecated alias. Recorded only when the alias is inside an #ifdef DCGM_DEPRECATED block OR its preceding comment contains Deprecated:. Other alias-style #defines (e.g. range sentinels) are silently skipped.
2. Resolve aliases: each recorded alias is mapped to its target field's canonical ID. The resolved alias feeds both Go const alias generation and legacy string lookup. If a target isn't a known field, generation fails so header churn can't silently drop previously-exposed names.
3. Read curated legacy names: lowercase DCGM 1.x names are read from legacy_fields.csv. DCGM_FI_* entries are not listed there; they re-derive from step 2 every run.
4. Emit Go code via template.go, then run gofmt -w on the output so make check-generate stays stable.

Output

The generated const_fields.go file contains:

const (
    DCGM_FI_DEV_GPU_TEMP_CELSIUS Short = 150

    // Deprecated DCGM field aliases retained for source compatibility.
    // DCGM_FI_DEV_GPU_TEMP is deprecated; use DCGM_FI_DEV_GPU_TEMP_CELSIUS.
    DCGM_FI_DEV_GPU_TEMP Short = DCGM_FI_DEV_GPU_TEMP_CELSIUS
    // ... etc
)

var dcgmFields = map[string]Short{
    "DCGM_FI_DEV_GPU_TEMP_CELSIUS": 150,
    // ... etc
}

var legacyDCGMFields = map[string]Short{
    // DCGM 1.x lowercase names from legacy_fields.csv:
    "dcgm_gpu_temp":   150,
    "dcgm_power_usage": 155,
    // Deprecated aliases resolved from dcgm_fields.h:
    "DCGM_FI_DEV_GPU_TEMP":               150,
    "DCGM_FI_DEV_NVLINK_BANDWIDTH_TOTAL": 449,
    // ... etc
}

func GetFieldID(fieldName string) (Short, bool) { ... }
func GetFieldIDOrPanic(fieldName string) Short { ... }
func IsLegacyField(fieldName string) bool     { ... }
func IsCurrentField(fieldName string) bool    { ... }

Template

The code generation template is defined in template.go and includes the full structure of the output Go file.

Updating Fields

When DCGM adds new fields:

1. Update pkg/dcgm/dcgm_fields.h with the latest version from DCGM
2. Run make generate
3. Review the diff in pkg/dcgm/const_fields.go
4. If a curated lowercase compatibility name is needed, update pkg/dcgm/legacy_fields.csv
5. Commit the header, generated file, and any legacy CSV changes

See CONTRIBUTING.md for detailed instructions.