Chapter 5

Phase 2: API Interface Standards

WIA-SEMI-001 Standard | Reading Time: ~35 minutes
Chapter Overview: Phase 2 builds on the data formats from Phase 1 to define standardized software interfaces for semiconductor control and monitoring. This chapter covers RESTful APIs, driver architectures, authentication mechanisms, and SDK design patterns that enable unified chip interaction.

5.1 API Design Principles

The WIA-SEMI-001 API interface standards follow industry best practices and modern design principles:

5.2 Core API Endpoints

5.2.1 Chip Information API

The information API provides read-only access to chip specifications and capabilities:

Endpoint Method Description Response
/api/v1/chip/info GET Get complete chip specification Full WIA-SEMI-001 JSON spec
/api/v1/chip/capabilities GET List available features Array of capability objects
/api/v1/chip/architecture GET Get architecture details CPU/GPU/NPU architecture info
/api/v1/chip/interfaces GET List available I/O interfaces Interface specifications 
// Example: Get chip information
GET /api/v1/chip/info HTTP/1.1
Host: chipname.local
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "wiaVersion": "1.0",
  "metadata": {
    "id": "WIA-SOC-2025-001",
    "manufacturer": {
      "name": "Example Semiconductor Corp"
    },
    "productName": "ExampleSoC Gen 5 Premium"
  },
  "architecture": {
    "type": "heterogeneous-multicore",
    "cpu": {
      "clusters": [
        {
          "name": "Performance",
          "coreCount": 2,
          "frequency": {"max": 3.8, "unit": "GHz"}
        }
      ]
    }
  }
}

5.2.2 Configuration API

The configuration API allows software to adjust chip parameters within safe limits:

Endpoint Method Description Parameters
/api/v1/config/power-mode PUT Set power/performance mode mode: performance|balanced|efficiency
/api/v1/config/frequency PUT Set frequency limits min, max (MHz)
/api/v1/config/thermal-limit PUT Set thermal throttling threshold temperature (°C)
/api/v1/config/power-limit PUT Set maximum power consumption limit (W) 
// Example: Set power mode to performance
PUT /api/v1/config/power-mode HTTP/1.1
Host: chipname.local
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "mode": "performance",
  "sustainedDuration": 60,
  "autoRevert": true
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "currentMode": "performance",
  "effectiveAt": "2025-01-15T10:30:00Z",
  "estimatedPower": {"value": 10.5, "unit": "W"}
}

5.2.3 Monitoring API

Real-time monitoring of chip state and performance:

Endpoint Method Description Update Frequency
/api/v1/monitor/power GET Current power consumption 100Hz max
/api/v1/monitor/temperature GET Temperature sensors 10Hz typical
/api/v1/monitor/frequency GET Current clock frequencies 100Hz max
/api/v1/monitor/utilization GET CPU/GPU/NPU utilization 10Hz typical
/api/v1/monitor/counters GET Performance counters On demand 
// Example: Get real-time temperature
GET /api/v1/monitor/temperature HTTP/1.1
Host: chipname.local
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "timestamp": "2025-01-15T10:30:15.234Z",
  "sensors": [
    {
      "location": "CPU-Performance-Core0",
      "temperature": {"value": 72.5, "unit": "°C"},
      "status": "normal"
    },
    {
      "location": "GPU",
      "temperature": {"value": 68.2, "unit": "°C"},
      "status": "normal"
    },
    {
      "location": "Junction",
      "temperature": {"value": 75.8, "unit": "°C"},
      "status": "normal",
      "throttleThreshold": {"value": 95, "unit": "°C"}
    }
  ]
}

5.3 WebSocket Streaming API

For high-frequency monitoring, WIA-SEMI-001 supports WebSocket streaming: 

// WebSocket connection for real-time telemetry
const ws = new WebSocket('wss://chipname.local/api/v1/stream/telemetry');

ws.onopen = () => {
  // Subscribe to specific metrics
  ws.send(JSON.stringify({
    action: 'subscribe',
    metrics: ['power', 'temperature', 'frequency'],
    sampleRate: 100 // Hz
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Telemetry:', data);
  /*
  {
    "timestamp": "2025-01-15T10:30:15.234Z",
    "power": {"value": 8.5, "unit": "W"},
    "temperature": {"value": 72.5, "unit": "°C"},
    "frequency": {
      "cpu": {"value": 3.2, "unit": "GHz"},
      "gpu": {"value": 950, "unit": "MHz"}
    }
  }
  */
};

5.4 Driver Architecture

WIA-SEMI-001 defines a standardized driver architecture for major operating systems:

5.4.1 Linux Driver Interface

// WIA-SEMI-001 Linux driver interface
#include 

// Device registration
struct wia_semi_chip_info {
    const char *manufacturer;
    const char *product_name;
    const char *chip_id;
    struct wia_semi_capabilities *caps;
};

// Power management operations
struct wia_semi_pm_ops {
    int (*set_power_mode)(struct device *dev, enum wia_power_mode mode);
    int (*get_power_consumption)(struct device *dev, u32 *milliwatts);
    int (*set_frequency_limit)(struct device *dev, u32 min_mhz, u32 max_mhz);
};

// Temperature monitoring operations
struct wia_semi_thermal_ops {
    int (*get_temperature)(struct device *dev, int sensor_id, int *temp_mc);
    int (*set_throttle_threshold)(struct device *dev, int temp_mc);
    int (*get_thermal_zone)(struct device *dev, struct thermal_zone_device **tz);
};

// Register driver
int wia_semi_register_driver(struct wia_semi_driver *driver);
void wia_semi_unregister_driver(struct wia_semi_driver *driver);

5.4.2 Windows Driver Model

// WIA-SEMI-001 Windows driver interface (WDM/KMDF)
#include 

// Device interface GUID
// {8E42B0D0-2F45-4C8E-A9F3-1B2C3D4E5F60}
DEFINE_GUID(GUID_DEVINTERFACE_WIA_SEMI,
    0x8e42b0d0, 0x2f45, 0x4c8e, 0xa9, 0xf3, 0x1b, 0x2c, 0x3d, 0x4e, 0x5f, 0x60);

typedef struct _WIA_SEMI_CHIP_INFO {
    UNICODE_STRING Manufacturer;
    UNICODE_STRING ProductName;
    UNICODE_STRING ChipId;
    WIA_SEMI_CAPABILITIES Capabilities;
} WIA_SEMI_CHIP_INFO, *PWIA_SEMI_CHIP_INFO;

// IOCTL codes
#define IOCTL_WIA_SEMI_GET_INFO \
    CTL_CODE(FILE_DEVICE_UNKNOWN, 0x800, METHOD_BUFFERED, FILE_ANY_ACCESS)

#define IOCTL_WIA_SEMI_SET_POWER_MODE \
    CTL_CODE(FILE_DEVICE_UNKNOWN, 0x801, METHOD_BUFFERED, FILE_ANY_ACCESS)

#define IOCTL_WIA_SEMI_GET_TELEMETRY \
    CTL_CODE(FILE_DEVICE_UNKNOWN, 0x802, METHOD_BUFFERED, FILE_READ_ACCESS)

5.5 SDK Design

WIA provides official SDKs for multiple languages, all following consistent patterns:

5.5.1 TypeScript/JavaScript SDK

import { WIASemiChip, PowerMode } from '@wia/semi-sdk';

// Connect to chip
const chip = new WIASemiChip({
  host: 'chipname.local',
  apiKey: process.env.WIA_API_KEY
});

// Get chip information
const info = await chip.getInfo();
console.log(`Connected to ${info.metadata.productName}`);

// Set power mode
await chip.config.setPowerMode(PowerMode.Performance);

// Monitor real-time telemetry
chip.monitor.on('telemetry', (data) => {
  console.log(`Power: ${data.power.value}W, Temp: ${data.temperature.value}°C`);
});

// Start streaming at 100Hz
await chip.monitor.startStreaming({
  metrics: ['power', 'temperature', 'frequency'],
  sampleRate: 100
});

5.5.2 Python SDK

from wia_semi import WIASemiChip, PowerMode

# Connect to chip
chip = WIASemiChip(
    host='chipname.local',
    api_key=os.environ['WIA_API_KEY']
)

# Get chip information
info = chip.get_info()
print(f"Connected to {info['metadata']['productName']}")

# Set power mode
chip.config.set_power_mode(PowerMode.PERFORMANCE)

# Get current temperature
temp = chip.monitor.get_temperature()
for sensor in temp['sensors']:
    print(f"{sensor['location']}: {sensor['temperature']['value']}°C")

# Stream telemetry
for telemetry in chip.monitor.stream_telemetry(sample_rate=100):
    print(f"Power: {telemetry['power']['value']}W")

5.6 Authentication and Security

WIA-SEMI-001 mandates secure authentication for all API access:

5.6.1 Authentication Methods

Method Use Case Security Level Token Lifetime
API Key Development, testing Medium No expiration
OAuth 2.0 Third-party applications High 1 hour (refreshable)
JWT Bearer Token Production systems High 15 minutes (refreshable)
Mutual TLS Critical infrastructure Very High Certificate lifetime

5.6.2 Authorization Scopes

Fine-grained permissions control what operations clients can perform: 

// Example: OAuth 2.0 token request
POST /oauth/token HTTP/1.1
Host: auth.wia.org
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=chip:read chip:monitor chip:config

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "chip:read chip:monitor chip:config"
}

5.7 Error Handling

Standardized error responses enable consistent error handling:

HTTP Status Error Code Description Example
400 INVALID_PARAMETER Invalid request parameter Frequency out of range
401 UNAUTHORIZED Missing or invalid authentication Expired token
403 FORBIDDEN Insufficient permissions Config requires admin scope
404 NOT_FOUND Resource doesn't exist Invalid sensor ID
429 RATE_LIMIT_EXCEEDED Too many requests Monitor API rate limit
503 THERMAL_THROTTLED Operation unavailable due to thermal state Can't increase frequency 
// Standard error response format
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Requested frequency 4.5 GHz exceeds maximum 3.8 GHz",
    "details": {
      "parameter": "maxFrequency",
      "requestedValue": 4500,
      "maximumValue": 3800,
      "unit": "MHz"
    },
    "timestamp": "2025-01-15T10:30:15Z",
    "requestId": "req_1234567890"
  }
}

Chapter Summary

Key Takeaways:

  1. Phase 2 defines RESTful APIs for chip information, configuration, and monitoring, providing unified software interfaces across all compliant chips.
  2. WebSocket streaming enables high-frequency real-time telemetry for power, temperature, and performance monitoring.
  3. Standardized driver interfaces for Linux and Windows simplify OS integration and enable consistent hardware abstraction.
  4. Official SDKs in multiple languages (TypeScript, Python, Java, C++) accelerate application development with consistent APIs.
  5. Comprehensive security through OAuth 2.0, JWT tokens, and mutual TLS protects chip access with fine-grained authorization scopes.

Review Questions

  1. What are the six core API design principles for WIA-SEMI-001?
  2. Which API endpoint would you use to get real-time power consumption data?
  3. Explain the difference between REST API polling and WebSocket streaming for telemetry.
  4. What are the four authentication methods supported by WIA-SEMI-001 and their use cases?
  5. How do authorization scopes control access to chip functionality?
  6. What information is included in standardized error responses?
Looking Ahead: In Chapter 6, we'll explore Phase 3, which defines communication protocols for chip-to-chip interactions, security, and coordinated system behavior.
© 2025 SmileStory Co., Ltd. / WIA