# Hardware and devices

GizHW gives a program access to the machine's devices. Discovery, device permissions and compute support are
separate: seeing a GPU or NPU does not prove that a model can execute on it.

## Inspect the machine

Start with `giz doctor`. It reports the toolchain, system requirements, available GPUs and setup problems.
This program reads the platform and hardware-monitor sensors exposed by the operating system:

```typescript gizlang file="examples/tour/devices.giz"
// gizhw: the machine's devices and sensors, read from the operating system.
import {System} from "gizlang:system";
import * as Device from "gizhw:device";

function main(sys: System): void {
    print(Device.platform(sys));
    for (const s of Device.sensors(sys).valueOr([])) { print(`${s.device} ${s.channel} ${s.value}`); }
}
```

Save it as `devices.giz` and run `giz devices.giz`. Its output depends on the host. Containers may expose no sensors.
An empty list is not a claim that the host has no devices.

## Choose an API

| Task | Owner | Next step |
| --- | --- | --- |
| CPU features, caches and memory nodes | `gizlang:machine` | [System internals](../internals/system.md) |
| Discover devices, sensors and board readings | `gizhw:device` | [Hardware reference](https://gizstack.com/docs/reference/gizhw) |
| Allocate device memory and execute compute kernels | `gizhw:gpu`, `gizhw:kernel` | [GPU tensors](compute.md#step-2-the-same-work-on-a-gpu) |
| Tensor math, gradients and model execution | `gizai` | [Compute and generative AI](compute.md) |
| Cameras, audio, video codecs, input, TPM and RDMA | The corresponding `gizhw` module | [Hardware reference](https://gizstack.com/docs/reference/gizhw) |
| File, socket or process I/O | `gizlang:system` | [Language guide](language.md#files-and-the-network) |

Device nodes and drivers have operating-system permissions. Pass the required `System` or opened device to the
function that uses it. Grant access to the device you need rather than running an entire application as root.

## Check support and diagnose a failure

1. Confirm the device is visible inside the environment that runs the program.
2. Check its driver and device-node permissions with `giz doctor` and the operating system's tools.
3. Run the small example for the API you need before loading a large model.
4. Check the operation and model's backend requirements in [Compute and generative AI](compute.md).
5. When reporting a failure, include the toolchain version, device and driver, diagnostic and smallest program.

The [compute internals](../internals/compute.md) distinguish backend implementation and measured hardware results.
Do not infer physical-device support from a code-generation test alone.

Hardware and devices

GizHW gives a program access to the machine's devices. Discovery, device permissions and compute support are separate: seeing a GPU or NPU does not prove that a model can execute on it.

Inspect the machine

Start with giz doctor. It reports the toolchain, system requirements, available GPUs and setup problems. This program reads the platform and hardware-monitor sensors exposed by the operating system:

typescript

// gizhw: the machine's devices and sensors, read from the operating system.
import {System} from "gizlang:system";
import * as Device from "gizhw:device";

function main(sys: System): void {
    print(Device.platform(sys));
    for (const s of Device.sensors(sys).valueOr([])) { print(`${s.device} ${s.channel} ${s.value}`); }
}

Save it as devices.giz and run giz devices.giz. Its output depends on the host. Containers may expose no sensors. An empty list is not a claim that the host has no devices.

Choose an API

Task	Owner	Next step
CPU features, caches and memory nodes	`gizlang:machine`	System internals
Discover devices, sensors and board readings	`gizhw:device`	Hardware reference
Allocate device memory and execute compute kernels	`gizhw:gpu`, `gizhw:kernel`	GPU tensors
Tensor math, gradients and model execution	`gizai`	Compute and generative AI
Cameras, audio, video codecs, input, TPM and RDMA	The corresponding `gizhw` module	Hardware reference
File, socket or process I/O	`gizlang:system`	Language guide

Device nodes and drivers have operating-system permissions. Pass the required System or opened device to the function that uses it. Grant access to the device you need rather than running an entire application as root.

Check support and diagnose a failure

Confirm the device is visible inside the environment that runs the program.
Check its driver and device-node permissions with giz doctor and the operating system's tools.
Run the small example for the API you need before loading a large model.
Check the operation and model's backend requirements in Compute and generative AI.
When reporting a failure, include the toolchain version, device and driver, diagnostic and smallest program.

The compute internals distinguish backend implementation and measured hardware results. Do not infer physical-device support from a code-generation test alone.