Vulkan® Shader in TOSA Custom Operation Attributes

Overview

This schema defines the JSON attributes used to embed a Vulkan® shader inside a TOSA custom operation.

It supports:

Shader entry point definition
Workgroup configuration
Textual shader source (GLSL/HLSL)
Binary SPIR-V™ (base64 encoded)
Vulkan® resource binding metadata for inputs and outputs

The schema is designed to be:

Strongly validated
Vulkan® aligned
Deterministic in key naming
Forward-compatible

Top-Level Properties

entry_point (required)

Type: string

Name of the shader entry point.

"entry_point": "main"

workgroup_sizes (required)

Type: Array of exactly 3 positive integers

Represents the local workgroup size: [x, y, z]

Constraints:

Exactly 3 elements
Each value must be >= 1

Example:

"workgroup_sizes": [8, 8, 1]

Corresponds to:

layout(local_size_x = 8,
       local_size_y = 8,
       local_size_z = 1) in;

shader_language (optional)

Type: Enum

Allowed values:

“” (unspecified)
“SPIR-V”
“GLSL”
“HLSL”

Example:

"shader_language": "GLSL"

shader_code (optional)

Type: string

Validation depends on shader_language.

If shader_language == "SPIR-V":

Must be base64 encoded
Represents raw SPIR-V™ binary

Example:

"shader_language": "SPIR-V",
"shader_code": "AwIjBAAAAAEAAAABAAEAAAA..."

Otherwise (GLSL/HLSL):

Treated as plain text shader source

Example:

"shader_language": "GLSL",
"shader_code": "void main() { }"

push_constants (optional)

Type: string

Comma-separated “name: size” pairs describing push constant layout.

Example:

"push_constants": "scale: 4, bias: 4"

Future versions may represent this as structured JSON.

Input / Output Resource Attributes

Resources are described using indexed attribute names.

Naming Convention

input_<index>_<property>
output_<index>_<property>

Where:

<index> is a non-negative integer
Leading zeros are not allowed - Valid: input_0, input_1, input_10 - Invalid: input_01

Example:

"input_0_vkformat": "VK_FORMAT_R32_SFLOAT",
"input_0_vkdescriptortype": "VK_DESCRIPTOR_TYPE_STORAGE_BUFFER",
"input_0_binding": 0,
"input_0_descriptorset": 0

Resource Properties

Each indexed input/output may define the following.

_vkformat

Type: string

Vulkan® format (e.g., VK_FORMAT_R32_SFLOAT).

Example:

"input_0_vkformat": "VK_FORMAT_R32G32B32A32_SFLOAT"

_vkdescriptortype

Type: string

Must follow Vulkan® naming convention:

VK_DESCRIPTOR_TYPE_[A-Z0-9_]+

Examples:

VK_DESCRIPTOR_TYPE_STORAGE_BUFFER
VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER
VK_DESCRIPTOR_TYPE_STORAGE_TENSOR_EXT

_type

Type: string

Logical resource type.

Examples:

“Tensor”
“Image”
“Buffer”

_binding

Type: Integer >= 0

Vulkan® binding index.

Example:

"input_0_binding": 0

_descriptorset

Type: Integer >= 0

Descriptor set index.

Example:

"input_0_descriptorset": 0

Complete Example — GLSL

{
  "entry_point": "main",
  "workgroup_sizes": [8, 8, 1],
  "shader_language": "GLSL",
  "shader_code": "void main() { }",

  "input_0_vkformat": "VK_FORMAT_R32_SFLOAT",
  "input_0_vkdescriptortype": "VK_DESCRIPTOR_TYPE_STORAGE_BUFFER",
  "input_0_binding": 0,
  "input_0_descriptorset": 0,

  "output_0_vkformat": "VK_FORMAT_R32_SFLOAT",
  "output_0_vkdescriptortype": "VK_DESCRIPTOR_TYPE_STORAGE_BUFFER",
  "output_0_binding": 1,
  "output_0_descriptorset": 0
}

Complete Example — SPIR-V™

{
  "entry_point": "main",
  "workgroup_sizes": [16, 16, 1],
  "shader_language": "SPIR-V",
  "shader_code": "AwIjBAAAAAEAAAABAAEAAAA...",

  "input_0_vkformat": "VK_FORMAT_R32G32B32A32_SFLOAT",
  "input_0_vkdescriptortype": "VK_DESCRIPTOR_TYPE_STORAGE_BUFFER",
  "input_0_binding": 0,
  "input_0_descriptorset": 0
}