# 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.