# Accelerator

```cpp
#include <qbruntime/acc.h>

class mobilint::Accelerator
```

Represents an accelerator, i.e., an NPU, used for executing models.

> [!CAUTION]
>
> **Attention**
>
> For the `regulus-usb` device family, do not unplug the USB device while the runtime is running. Disconnecting a device that is in use may crash the program or cause unexpected misbehavior.

## Static functions

| Member | Description |
| --- | --- |
| [`create`](<#create>) ×5 | Creates an [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object for executing models, using device number 0. |

### create

```cpp
static std::unique_ptr<Accelerator> create(StatusCode &sc)
```

Creates an [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object for executing models, using device number 0.

This function is useful when only one device is attached, in which case the default device (device 0) will be used.

**Parameters**

- `sc` *\[out\]* — Reference to a [StatusCode](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/#statuscode>) that will be updated with the result of the creation.

**Returns**

A unique pointer to the created [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object.

```cpp
static std::unique_ptr<Accelerator> create(int dev_no, StatusCode &sc)
```

Creates an [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object for a specific device number.

The `dev_no` parameter represents the device number. For example, on Linux, if an ARIES NPU is attached as `/dev/aries0`, the device number is `0`.

This overload resolves the target device automatically (as if `"auto"` were passed), so creation fails when more than one kind of target device is present in the system (auto-resolution is ambiguous), or when no device numbered `dev_no` exists. On failure the function returns `nullptr` and writes the corresponding error code to `sc`.

**Parameters**

- `dev_no` *\[in\]* — The device number to associate with the [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>).
- `sc` *\[out\]* — Reference to a [StatusCode](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/#statuscode>) that will be updated with the result of the creation.

**Returns**

A unique pointer to the created [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object.

```cpp
static std::unique_ptr<Accelerator> create(const std::string &device_name, StatusCode &sc)
```

Creates an [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object for a specific target device using device number 0.

The `device_name` string selects target device to open; case-insensitive. Supported values:

- `"auto"`
- `"aries"`, `"aries-rb"`
- `"regulus"`, `"regulus-usb"`
- `"regulus-ra"`, `"regulus-ra-usb"`
- `"regulus-rb"`, `"regulus-rb-usb"`

Automatic resolution:

- `"auto"` resolves the target device automatically, but only when exactly one supported kind of target device is present in the system.
- A base name (`"aries"`, `"regulus"`, `"regulus-usb"`, ...) is a shorthand for every target device whose name begins with it (e.g. `"aries"` matches `"aries-rb"`). It resolves to the concrete target device automatically, but only when exactly one such matching target device is present.

Creation fails when `device_name` is unknown, when auto-resolution is ambiguous (more than one candidate), or when no matching device exists. On failure the function returns `nullptr` and writes the corresponding error code to `sc`.

**Parameters**

- `device_name` *\[in\]* — Device name to open (case-insensitive). See the list above.
- `sc` *\[out\]* — Reference to a [StatusCode](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/#statuscode>) that will be updated with the result of the creation.

**Returns**

A unique pointer to the created [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object.

```cpp
static std::unique_ptr<Accelerator> create(const std::string &device_name, int dev_no, StatusCode &sc)
```

Creates an [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object for a specific target device and device number.

The `device_name` string selects target device to open; case-insensitive. Supported values:

- `"auto"`
- `"aries"`, `"aries-rb"`
- `"regulus"`, `"regulus-usb"`
- `"regulus-ra"`, `"regulus-ra-usb"`
- `"regulus-rb"`, `"regulus-rb-usb"`

Automatic resolution:

- `"auto"` resolves the target device automatically, but only when exactly one supported kind of target device is present in the system.
- A base name (`"aries"`, `"regulus"`, `"regulus-usb"`, ...) is a shorthand for every target device whose name begins with it (e.g. `"aries"` matches `"aries-rb"`). It resolves to the concrete target device automatically, but only when exactly one such matching target device is present.

Creation fails when `device_name` is unknown, when auto-resolution is ambiguous (more than one candidate), or when no matching device exists. On failure the function returns `nullptr` and writes the corresponding error code to `sc`.

**Parameters**

- `device_name` *\[in\]* — Device name to open (case-insensitive). See the list above.
- `dev_no` *\[in\]* — The device number to associate with the [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>).
- `sc` *\[out\]* — Reference to a [StatusCode](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/#statuscode>) updated with the result.

**Returns**

A unique pointer to the created [Accelerator](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) object.

```cpp
static std::unique_ptr<Accelerator> create(int dev_no, bool verbose, StatusCode &sc)
```

> [!WARNING]
>
> **Deprecated**
>
> Use [`std::unique_ptr<Accelerator> create(int dev_no, StatusCode& sc)`](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/accelerator/index.md>) instead.

## Member functions

| Member | Description |
| --- | --- |
| [`Accelerator`](<#accelerator>) ×2 |  |
| [`operator=`](<#operator-assign>) ×2 |  |
| [`getDeviceName`](<#getdevicename>) | Returns the resolved device name of this accelerator. |
| [`allocatePinnedMemory`](<#allocatepinnedmemory>) | Allocates a pinned (zero-copy) memory buffer on the NPU device. |

### Accelerator

```cpp
Accelerator(const Accelerator &other)=delete
```

```cpp
Accelerator(Accelerator &&other) noexcept
```

### operator=

```cpp
Accelerator & operator=(const Accelerator &rhs)=delete
```

```cpp
Accelerator & operator=(Accelerator &&rhs) noexcept
```

### getDeviceName

```cpp
std::string getDeviceName() const
```

Returns the resolved device name of this accelerator.

When created with a automatic resolve such as `"auto"`, `"aries"`, this returns the real target device name that was resolved (e.g. `"aries-rb"`, `"regulus-ra-usb"`).

**Returns**

The resolved device name.

### allocatePinnedMemory

```cpp
template <typename T>
PinnedMemory<T> allocatePinnedMemory(const std::vector<int64_t> &shape, StatusCode &sc)
```

Allocates a pinned (zero-copy) memory buffer on the NPU device.

The returned buffer is mapped into both host and NPU address space so that inference can read/write it directly without an intermediate copy. Only supported on REGULUS SoC device (excluding USB); other target devices return `Model_IsNotSupportedHardware`.

**Template parameters**

- `T` — Element type of the buffer. Currently only `uint8_t` and `float` are supported.

**Parameters**

- `shape` *\[in\]* — [Buffer](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/buffer/index.md>) shape. All dimensions must be positive.
- `sc` *\[out\]* — Reference to a [StatusCode](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/#statuscode>) that will be updated with the result of the allocation.

**Returns**

The allocated [PinnedMemory](<https://docs.mobilint.com/runtime/en/v1.5/api/cpp/pinnedmemory/index.md>) handle. On failure the handle is empty and `sc` holds the error code.
