Skip to content

kernel_package_format.md

Latest commit

 

History

History
177 lines (146 loc) · 8.09 KB

kernel_package_format.md

File metadata and controls

177 lines (146 loc) · 8.09 KB
Raw

kernel_package data format

This document describes the on-disk format of a kernel_package inside the kernel_data repository. The normative source for each schema is the corresponding file in schemas/; the tables below are auto-generated from those schemas and must not be edited by hand.

Related documentation

Directory layout

<arch>/<op_class>/<sub_class>/<quant>/.../<kernel_package_name>/
├── .kernel_package/
│   ├── desc.yaml
│   ├── bench_result.yaml
│   ├── build_test_env.py
│   └── benchmark.py
└── src/...                              (source text only; full-overwrite on accept)
  • Path segments match ^[A-Za-z0-9._-]+$.
  • kernel ID = POSIX relative path to the kernel_package directory (no trailing slash).
  • .kernel_package/ must contain all four files; otherwise the package is invalid.
  • Kernel packages must be source-authored and generated-evidence-free, not merely binary-free. Git repositories and submission tarballs may contain implementation source, build scripts, authored metadata, and deterministic generation recipes only. Do not include model weights, generated tensors, golden test data, compiled objects, runtime traces, profiler exports, hardware/software census or environment dumps, benchmark or compiler logs, captured stdout/stderr, generated reports, or summaries, tables, and statistics derived from them. This prohibition applies regardless of whether the material is encoded as JSON, CSV, YAML, Markdown, plain text, or a binary format; renaming, truncating, converting, or manually summarizing it does not make it package content.
  • build_test_env.py is the required test-environment constructor. It must deterministically generate all test inputs, synthetic model weights, expected outputs, optional build products, manifests, and diagnostics under the runner's temporary workdir. benchmark.py may likewise create runtime logs and reports only there. These files are consumed for that run and discarded; never copy them back into the package, add them to Git, or include them in a submission tarball.
  • “Source text,” “flexible,” and “free-form” describe authored implementation layout or the schema shape of compact authored metadata. They do not permit arbitrary generated files, runtime evidence, trace excerpts, or derived summaries.

desc.yaml

Describes operator metadata. The description field is the most important field for third-party optimizers — it is read by automated agents that generate or tune kernel implementations.

Source: schemas/desc.json

Field Type Required Description
schema_version string ✓
name string ✓
category object ✓
category.arch string ✓
category.op_class string ✓
category.sub_class string ✓
category.quant string ✓
summary string ✓
description string ✓
io_signature array ✓
quantization object ✓
quantization.scheme string ✓
quantization.granularity enum: per_tensor per_block per_channel
quantization.block_size integer
quantization.group_size integer
reference_sources array ✓
status enum: normal frozen deprecated
min_arch_feature string
tags array
owner string

bench_result.yaml

Holds per-case best and current metric values. Only metrics_best and metrics_current are stored; full history is recoverable via git log.

Source: schemas/bench_result.json

Field Type Required Description
schema_version string ✓
kernel_id string ✓
cases array ✓

KERNEL_ZOO_TEST_CASE_METAS items

Each item of the KERNEL_ZOO_TEST_CASE_METAS list inside benchmark.py.

Source: schemas/test_case_meta.json

Field Type Required Description
test_case_id string ✓ Stable identifier for the test case; unique within a kernel_package.
params object ✓ Free-form parameters describing this case (dims, batch, etc.).
primary_metric string ✓ Must equal one of metrics[].name. Used as the headline metric for ranking and regression checks.
metrics array ✓
tolerance object ✓
tolerance.correctness_atol number ✓
tolerance.correctness_rtol number ✓

benchmark.py stdout

The exact JSON document that benchmark.py prints to stdout. Logs must go to stderr.

Source: schemas/benchmark_output.json

Field Type Required Description
schema_version string ✓
kernel_id string ✓
ran_at string ✓
runner_id string ✓
arch string ✓
overall object ✓
overall.accept boolean ✓
overall.accept_reason string ✓
overall.build_ok boolean ✓
cases array ✓

POST /api/submissions form fields

The multipart fields parsed into a dict and validated server-side.

Source: schemas/submission_envelope.json

Field Type Required Description
kernel_id string ✓ Existing kernel ID. Server validates existence separately.
submitter_id string ✓ Self-reported submitter identifier. No spaces.
package_filename string ✓ Original filename of the uploaded package; must end in .tar.gz.
optimization_summary string Free-text description of this submission's optimization points; included in the accepted-result commit message.

The uploaded package must be a gzipped tarball whose top-level directory is the kernel_id, and whose .kernel_package/ contains all four required files (desc.yaml, bench_result.yaml, build_test_env.py, benchmark.py). The tarball must obey the generated-evidence-free policy above: include authored source, metadata, and generation scripts only. Do not include generated test data, model weights, golden tensors, compiled artifacts, runtime traces, profiles, census data, logs, reports, or raw or summarized evidence in any encoding. The submitted bench_result.yaml is a seed used for validation only: on accept the server strips it from the tarball before writing the source area and preserves its own copy, so the scoreboard can never be overwritten by a submitter.

kernel_package directory manifest

A derived manifest computed by tools.kernel_package_meta.inspect_kernel_package.

Source: schemas/kernel_package_meta.json

Field Type Required Description
path string ✓
has_dot_kernel_package boolean ✓
required_files_present array ✓
required_files_missing array ✓