# NPU manager buffer ## Summary | ### Enumerations || |---|---| | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga901d27269e380251ccc4780fbb244864{ https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gga901d27269e380251ccc4780fbb244864aa950559d018f13dc239575d2eb966194 = 0, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gga901d27269e380251ccc4780fbb244864a1cf6dfbcf69ee525d858261b290fd79c = 500, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gga901d27269e380251ccc4780fbb244864a1f3e8bd7e2e76341c64650869b2e4574 = 1000 }` | enumThe range of relative priority of the buffer within the app. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gadb9fea7a5129d723905a8ad5d9dc4ab3{ https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ggadb9fea7a5129d723905a8ad5d9dc4ab3a9d3ae606e1788ab06fb0ad00d8001960, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ggadb9fea7a5129d723905a8ad5d9dc4ab3aee98514b12f5a4891a452760e9ddc178, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ggadb9fea7a5129d723905a8ad5d9dc4ab3af55c6aeb76a79983ee4ea551244c5eb0, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ggadb9fea7a5129d723905a8ad5d9dc4ab3ae3da689389b3233ab348d4a226b0bb2b, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ggadb9fea7a5129d723905a8ad5d9dc4ab3a2b5962d80a66351eca57d6f665adb917 }` | enumThe purpose of the buffer. | | ### Typedefs || |---|---| | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga17ddd64d81e8195cbc261c728ad9ac4e` | typedef `struct ANpuBuffer` | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gadd87c61835b7604fe540b032336f49be` | typedef `enum https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga901d27269e380251ccc4780fbb244864` The range of relative priority of the buffer within the app. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga58b110a2c9e761b6d7cf0d0049fb25e2` | typedef `enum https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gadb9fea7a5129d723905a8ad5d9dc4ab3` The purpose of the buffer. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gabcd58f750c94f2ee41173ac545a25705)(void *_Nullable cookie, int errorNum, ANpuBuffer *_Nullable buf)` | typedef `void(*` Callback function type when allocation and load is done. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga115c745f8b60be2258990ddb7ba6ded3` | typedef `struct ANpuManager_AllocRequest` | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga87ef0f64c164b3851b69ca5e2a1c60d4)(void *_Nullable cookie)` | typedef `void(*` Callback function type to delete the user cookie. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gacc3df5ef9cbc89fb243c6141759f06e0)(void *_Nullable cookie, int errorNum, ANpuBuffer *_Nonnull buf)` | typedef `void(*` Callback function type for buffer load. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga0007e424b0b3672075b0285de2b1f3f7)(void *_Nullable cookie)` | typedef `void(*` Callback function type for buffer preemption. | | ### Functions || |---|---| | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gafdda876ec553ca86132672840bd812ed(ANpuBuffer *_Nonnull const *_Nonnull buffers, size_t buffersLen)` | `int` Indicates that the buffers are not needed by the user and can be freed. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaae1c43bbf6dc0ff9f07e5cc02ae3d44d(ANpuBuffer *_Nonnull buf, int fdToOwn, int64_t fileOffset, int64_t segmentLength, int64_t bufferOffset, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gacc3df5ef9cbc89fb243c6141759f06e0 _Nonnull onLoad)` | `void` Loads a file into the buffer asynchronously. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b(ANpuBuffer *_Nonnull buf, void *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d addr, size_t length, int prot, int flags, off_t offset)` | `void *_Nonnull` Maps a buffer into the application's address space. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga0efffc7ae390dfc321e27204ee56615d(ANpuBuffer *_Nonnull buf, int32_t newBufferPriority)` | `int` Sets the priority of the buffer. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga41f43aa84c6fdcca6fd399f057d558d9(ANpuBuffer *_Nonnull buf, void *_Nonnull addr, size_t length)` | `int` Unmaps a previously mapped buffer. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga30de95c4c17ce8e0816f570b716ab5c1()` | `ANpuManager_AllocRequest *_Nonnull` Creates a new allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga618191b0e79bcdf47ded1ee67b4624ae(ANpuManager_AllocRequest *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d request)` | `void` Destroys an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga0a55f6d8a1df1d1f1f00185fd5281e9b(ANpuManager_AllocRequest *_Nonnull request, int32_t bufferPriority)` | `void` Sets the buffer priority for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gad03a95082aa180ffcdba0c31fcbf868a(ANpuManager_AllocRequest *_Nonnull request, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gadb9fea7a5129d723905a8ad5d9dc4ab3 bufferType)` | `void` Sets the purpose of the buffer for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8(ANpuManager_AllocRequest *_Nonnull request, void *https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d cookie, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga87ef0f64c164b3851b69ca5e2a1c60d4https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d cookieDeleter)` | `void` Sets the user cookie for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaefc61e0e39bedb6a2f5b8e81a02c1edc(ANpuManager_AllocRequest *_Nonnull request, int32_t deviceNumber)` | `void` Sets the device number for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gab4540d9f3892a0e5b3df2cf4b9331b9a(ANpuManager_AllocRequest *_Nonnull request, int fdToOwn, int64_t fileOffset, int64_t segmentLength, int64_t bufferOffset)` | `void` Sets the file segment to load for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaf3844bdbe943e305e06cacbd09a8b2cc(ANpuManager_AllocRequest *_Nonnull request, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gabcd58f750c94f2ee41173ac545a25705 _Nonnull onAlloc)` | `void` Sets the allocation callback for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga0569973a7d3caaf66d67f495fb60e321(ANpuManager_AllocRequest *_Nonnull request, https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga0007e424b0b3672075b0285de2b1f3f7https://developer.android.com/ndk/reference/group/ndk-binder#group___ndk_binder_1ga0890a8f74983b96e76f6b8748543032d onPreempt)` | `void` Sets the preemption callback for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga872d9d7c0ee1b7e426550ec6d4de4152(ANpuManager_AllocRequest *_Nonnull request, int32_t prot)` | `void` Sets the protection flags for the buffer to be allocated. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga05d7a10acf16477034c307896200a6eb(ANpuManager_AllocRequest *_Nonnull request, int64_t size)` | `void` Sets the size of the buffer in bytes for an allocation request. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f(ANpuManager_AllocRequest *_Nonnull const *_Nonnull requests, size_t requestsLen)` | `void` Asynchronously allocates multiple buffers. | | `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gad249e2319145325f7c7ba9d1e6fa4b32(ANpuManager_AllocRequest *_Nonnull const *_Nonnull requests, size_t requestsLen, bool *_Nonnull outIsSupported)` | `int` Tests if the provided requests are supported or not. | ## Enumerations ### ANpuBuffer_Priority Declared in `android/npumanager/buffer.h` ``` ANpuBuffer_Priority ``` The range of relative priority of the buffer within the app. These values defines the valid range for the buffer_priority field. The buffer_priority field must be within the range \[ANPUBUFFER_PRIORITY_MIN, ANPUBUFFER_PRIORITY_MAX\], inclusive. | Properties || |---|---| | `ANPUBUFFER_PRIORITY_DEFAULT` | Introduced in API 37. | | `ANPUBUFFER_PRIORITY_MAX` | Introduced in API 37. | | `ANPUBUFFER_PRIORITY_MIN` | Introduced in API 37. | ### ANpuBuffer_Type Declared in `android/npumanager/buffer.h` ``` ANpuBuffer_Type ``` The purpose of the buffer. For input/output buffers, use AHardwareBuffer instead. | Properties || |---|---| | `ANPUBUFFER_TYPE_AUXILIARY` | Introduced in API 37. | | `ANPUBUFFER_TYPE_CACHE` | Introduced in API 37. | | `ANPUBUFFER_TYPE_MODEL_EXECUTABLE` | Introduced in API 37. | | `ANPUBUFFER_TYPE_MODEL_WEIGHTS` | Introduced in API 37. | | `ANPUBUFFER_TYPE_UNKNOWN` | Introduced in API 37. | ## Typedefs ### ANpuBuffer Declared in `android/npumanager/buffer.h` ``` struct ANpuBuffer ANpuBuffer ``` ### ANpuBuffer_Priority Declared in `android/npumanager/buffer.h` ``` enum ANpuBuffer_Priority ANpuBuffer_Priority ``` The range of relative priority of the buffer within the app. These values defines the valid range for the buffer_priority field. The buffer_priority field must be within the range \[ANPUBUFFER_PRIORITY_MIN, ANPUBUFFER_PRIORITY_MAX\], inclusive. ### ANpuBuffer_Type Declared in `android/npumanager/buffer.h` ``` enum ANpuBuffer_Type ANpuBuffer_Type ``` The purpose of the buffer. For input/output buffers, use AHardwareBuffer instead. ### ANpuManager_AllocCallback Declared in `android/npumanager/buffer.h` ``` void(* ANpuManager_AllocCallback)(void *_Nullable cookie, int errorNum, ANpuBuffer *_Nullable buf) ``` Callback function type when allocation and load is done. The callback is invoked in response to [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f). Even when the request has `https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gab4540d9f3892a0e5b3df2cf4b9331b9a`, indicating that a file is to be loaded into the buffer, this callback is still used to indicate that the load is complete (or failed), not ANpuManager_LoadCallback. The callback may be invoked on any thread, including the current thread immediately inside [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) if an error is immediately detected. The cookie is borrowed, i.e. the user does not own the cookie and must not free it. See documentation of [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8) for details. Details Parameters `cookie` The user cookie previously set by [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8), or NULL if not set. The value of cookie is the one stored in the ANpuManager_AllocRequest at the time when [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) is called. Subsequent changes to the cookie in the ANpuManager_AllocRequest object after a given [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) is called has no effect on the callbacks generated from the given [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) call. The callback may be called from any thread. The user is responsible for accessing the cookie in a thread-safe manner. Details Parameters `errorNum` 0 if successful, or an errno on error. `buf` The buffer on success, or NULL on error. ``` On success, buf must be explicitly freed by calling ANpuBuffer_free(). This is the case even if the buffer is preempted by NpuManagerService. On error, the user must not call ANpuBuffer_free() with NULL. ``` ### ANpuManager_AllocRequest Declared in `android/npumanager/buffer.h` ``` struct ANpuManager_AllocRequest ANpuManager_AllocRequest ``` ### ANpuManager_CookieDeleter Declared in `android/npumanager/buffer.h` ``` void(* ANpuManager_CookieDeleter)(void *_Nullable cookie) ``` Callback function type to delete the user cookie. The deleter may be called from any thread. The user is responsible for deleting the cookie or decrementing the associated reference counts in a thread-safe manner.
Details Parameters `cookie` The user cookie previously set by [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8). This may be NULL if the provided cookie value is NULL. ### ANpuManager_LoadCallback Declared in `android/npumanager/buffer.h` ``` void(* ANpuManager_LoadCallback)(void *_Nullable cookie, int errorNum, ANpuBuffer *_Nonnull buf) ``` Callback function type for buffer load. NpuManager calls this function when the buffer load is done or has encountered an error. This callback is invoked in response to [ANpuBuffer_loadAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaae1c43bbf6dc0ff9f07e5cc02ae3d44d), NOT to [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f).
Details Parameters `cookie` The user cookie previously set by [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8), or NULL if not set. `errorNum` 0 if successful, or an errno on error. `buf` The buffer. This is the same buffer passed to [ANpuBuffer_loadAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaae1c43bbf6dc0ff9f07e5cc02ae3d44d), even if loading fails. ### ANpuManager_PreemptCallback Declared in `android/npumanager/buffer.h` ``` void(* ANpuManager_PreemptCallback)(void *_Nullable cookie) ``` Callback function type for buffer preemption. NpuManager calls this function when it needs to forcefully deallocate the buffer. After this callback is invoked, any subsequent attempts to map the buffer are expected to fail. Even if preempted, the buffer must still be explicitly freed by calling [ANpuBuffer_free()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gafdda876ec553ca86132672840bd812ed) to clean up remaining resources. Note: On race conditions, the preemption callback may be invoked after the caller has already freed the buffer. This callback will not be invoked while the application has the buffer mapped. The cookie is borrowed, i.e. the user does not own the cookie and must not free it. See documentation of [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8) for details. The callback may be called from any thread. The user is responsible for accessing the cookie in a thread-safe manner.
Details Parameters `cookie` The user cookie previously set by [ANpuManager_AllocRequest_setCookie()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga86536242623221252abf16c2c29850a8), or NULL if not set. ## Functions ### ANpuBuffer_free Declared in `android/npumanager/buffer.h` ``` int ANpuBuffer_free( ANpuBuffer *_Nonnull const *_Nonnull buffers, size_t buffersLen ) ``` Indicates that the buffers are not needed by the user and can be freed. If there are any existing mappings to the buffer via [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b), the mapping will continue to be valid until unmapped even after the buffer is freed. In this case, the associated memory will be freed after all mappings are unmapped. To prevent use-after-free bugs, the caller must not use pointers in *buffers* during or after this call in any of the ANpuBuffer_\* functions, except: - [ANpuBuffer_unmap()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga41f43aa84c6fdcca6fd399f057d558d9) to unmap any existing mappings to the buffer.
Even if a buffer is preempted, it must still be explicitly freed by calling [ANpuBuffer_free()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gafdda876ec553ca86132672840bd812ed) to clean up remaining resources. Available since API level 37.
Details Parameters `buffers` A list of buffers to free. Each item must not be NULL. ``` The list must not be modified during the execution of ANpuBuffer_free(). Otherwise, the behavior is undefined. The elements of the list must not be freed during the execution of ANpuBuffer_free() in a separate thread, or after the execution of ANpuBuffer_free() in any thread (i.e. no double-free). ``` `buffersLen` The length of the buffers list. **Returns** 0 on success, or -1 on error with errno set. ### ANpuBuffer_loadAsync Declared in `android/npumanager/buffer.h` ``` void ANpuBuffer_loadAsync( ANpuBuffer *_Nonnull buf, int fdToOwn, int64_t fileOffset, int64_t segmentLength, int64_t bufferOffset, ANpuManager_LoadCallback _Nonnull onLoad ) ``` Loads a file into the buffer asynchronously. There should not be any existing mapping (via [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b)) to the buffer. Otherwise, the callback is replied with an error. Available since API level 37. The position of the associated file description is not changed by this function. This must be non-NULL. Otherwise, the process will crash. Details Parameters `buf` The buffer to load into. `fdToOwn` The file descriptor of the file to load. Must be a valid file descriptor. The ownership of the fd is transferred to ANpuManager. Parameters `fileOffset` The offset of the file segment to load, starting from the beginning of the file. `segmentLength` The length of the file segment to load. Must be non-negative. `bufferOffset` The offset in the buffer to start loading to. Must be non-negative. `onLoad` The callback to be invoked when loading is finished or has encountered an error. See documentation of ANpuManager_LoadCallback for details about the arguments when the callback is invoked. ### ANpuBuffer_map Declared in `android/npumanager/buffer.h` ``` void *_Nonnull ANpuBuffer_map( ANpuBuffer *_Nonnull buf, void *_Nullable addr, size_t length, int prot, int flags, off_t offset ) ``` Maps a buffer into the application's address space. The arguments are similar to mmap(). The returned address must be unmapped by calling [ANpuBuffer_unmap()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga41f43aa84c6fdcca6fd399f057d558d9). Available since API level 37. There is a small time window between when the buffer is preempted and when ANpuManager_OnPreempt is called. If the app calls [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b) during this time window, it will still get -1 with errno set to ENOENT, even though when ANpuManager_OnPreempt has not been called yet. Details Parameters `buf` The buffer to map. `addr` see mmap(). `length` see mmap(). `prot` see mmap(). The value must be a subset of the value set by [ANpuManager_AllocRequest_setProtectionFlags()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1ga872d9d7c0ee1b7e426550ec6d4de4152). Otherwise, [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b) fails and returns MAP_FAILED. `flags` see mmap(). `offset` see mmap(). **Returns** The mapped address on success, or MAP_FAILED on error and errno is set. If the buffer was preempted, errno is set to ENOENT. ### ANpuBuffer_setPriority Declared in `android/npumanager/buffer.h` ``` int ANpuBuffer_setPriority( ANpuBuffer *_Nonnull buf, int32_t newBufferPriority ) ``` Sets the priority of the buffer. Available since API level 37.
Details Parameters `buf` The buffer to set the priority of. `newBufferPriority` The new priority of the buffer. The value must be within the range \[ANPUBUFFER_PRIORITY_MIN, ANPUBUFFER_PRIORITY_MAX\], inclusive. **Returns** 0 on success, or -1 on error with errno set. ### ANpuBuffer_unmap Declared in `android/npumanager/buffer.h` ``` int ANpuBuffer_unmap( ANpuBuffer *_Nonnull buf, void *_Nonnull addr, size_t length ) ``` Unmaps a previously mapped buffer. The arguments are similar to munmap(). Available since API level 37.
Details Parameters `buf` The buffer to unmap. `addr` see munmap(). `length` see munmap(). **Returns** 0 on success, or -1 on error with errno set. ### ANpuManager_AllocRequest_create Declared in `android/npumanager/buffer.h` ``` ANpuManager_AllocRequest *_Nonnull ANpuManager_AllocRequest_create() ``` Creates a new allocation request. Fields are initialized to a default state.
| Details || |---|---| | **Returns** | A new allocation request. | ### ANpuManager_AllocRequest_free Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_free( ANpuManager_AllocRequest *_Nullable request ) ``` Destroys an allocation request.
Details Parameters `request` The allocation request to destroy. If NULL, nothing happens. ### ANpuManager_AllocRequest_setBufferPriority Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setBufferPriority( ANpuManager_AllocRequest *_Nonnull request, int32_t bufferPriority ) ``` Sets the buffer priority for an allocation request. This is the relative priority of the buffer within the app. The value must be within the range \[ANPUBUFFER_PRIORITY_MIN, ANPUBUFFER_PRIORITY_MAX\], inclusive. If never called, the default value is ANPUBUFFER_PRIORITY_DEFAULT.
Details Parameters `request` The allocation request. `bufferPriority` The buffer priority. ### ANpuManager_AllocRequest_setBufferType Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setBufferType( ANpuManager_AllocRequest *_Nonnull request, ANpuBuffer_Type bufferType ) ``` Sets the purpose of the buffer for an allocation request. The default value is ANPUBUFFER_TYPE_UNKNOWN, which is invalid. Hence, this must be set with a valid buffer type before being sent to NpuManagerService. Otherwise, the request is responded with errorNum set to EINVAL.
Details Parameters `request` The allocation request. `bufferType` The buffer type. ### ANpuManager_AllocRequest_setCookie Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setCookie( ANpuManager_AllocRequest *_Nonnull request, void *_Nullable cookie, ANpuManager_CookieDeleter_Nullable cookieDeleter ) ``` Sets the user cookie for an allocation request. The user may use this cookie to identify the request. It is not dereferenced directly by the implementation of the NDK library. # Ownership of cookie
This donates the ownership of the cookie to ANpuManager. In other words, ANpuManager will be responsible for freeing the cookie with the provided deleter function. This assumes the caller owns the cookie before calling this function, and does not own the cookie after calling this function. In particular, to use the same cookie in multiple ANpuManager_AllocRequest objects, or in OnPreempt() to reuse the cookie in a new ANpuManager_AllocRequest object, reference count the cookie, and: - Before calling setCookie(), increment the reference count by 1. - In the deleter function, decrement the reference count by 1.
# Calling the deleter function
When ANpuManager decides to free the cookie: - If cookieDeleter is not NULL, it will be called with the cookie value. This will happen even if the cookie is NULL. In this case, the deleter must be able to handle NULL gracefully. - If the cookieDeleter is NULL, nothing will happen, even when the cookie is not NULL. This is useful if the user stores an arbitrary 64-bit integer value in the cookie (so it is not a real pointer.) However, if the cookie points to a heap object, it is strongly recommended to set the deleter so ANpuManager handles its lifetime properly and reduce UAF bugs.
# Other semantics of setCookie()
When setCookie() is called multiple times, the previous cookie will be deleted with the previous deleter function (if set) before the new cookie and the new deleter function are set. To clear the cookie, set both cookie and cookieDeleter to NULL. If never called, the default cookie and cookieDeleter are NULL. The deleter may be called from any thread. The user is responsible for deleting the cookie or decrementing the associated reference counts in a thread-safe manner. # Callbacks
The existing onAlloc and onPreempt callbacks must be able to handle the new cookie value after setCookie() is called. If not, modify the callbacks accordingly before sending them using [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f).
Details Parameters `request` The allocation request. `cookie` The user cookie to be owned by ANpuManager. `cookieDeleter` The deleter function to be called when ANpuManager is done with the cookie. ### ANpuManager_AllocRequest_setDeviceNumber Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setDeviceNumber( ANpuManager_AllocRequest *_Nonnull request, int32_t deviceNumber ) ``` Sets the device number for an allocation request. An identifier for the NPU that is involved with the work. The identifiers are vendor-specific and opaque to the ANpuManager. The default value is a negative value, which is invalid. Hence, this must be with a valid non-negative device number before being sent to NpuManagerService. Otherwise, the request is responded with errorNum set to EINVAL.
Details Parameters `request` The allocation request. `deviceNumber` The device number. ### ANpuManager_AllocRequest_setFileSegmentToLoad Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setFileSegmentToLoad( ANpuManager_AllocRequest *_Nonnull request, int fdToOwn, int64_t fileOffset, int64_t segmentLength, int64_t bufferOffset ) ``` Sets the file segment to load for an allocation request. Ownership: The ANpuManager_AllocRequest object takes ownership of the provided file descriptor. The caller must not close it manually. The ownership of the fd is transferred to ANpuManager. Details Parameters `request` The allocation request. `fdToOwn` The file descriptor of the file to load. Must be a valid file descriptor, or -1 to ask NpuManager to not load any file. Default value is -1. Parameters `fileOffset` The offset of the file segment to load, starting from the beginning of the file. Ignored if fdToOwn is -1. `segmentLength` The length of the file segment to load. Must be non-negative. Ignored if fdToOwn is -1. `bufferOffset` The offset in the buffer to start loading to. Must be non-negative. Ignored if fdToOwn is -1. ### ANpuManager_AllocRequest_setOnAlloc Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setOnAlloc( ANpuManager_AllocRequest *_Nonnull request, ANpuManager_AllocCallback _Nonnull onAlloc ) ``` Sets the allocation callback for an allocation request. Callback function to be invoked when allocation and load is finished or has encountered an error. setOnAlloc() must be called with a non-NULL value. Otherwise, the process will crash. setOnAlloc() must be called before calling [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f). Otherwise, the process will crash. See documentation of ANpuManager_AllocCallback for details about the arguments when the callback is invoked. The new callback must be able to handle any existing cookie value set by setCookie(), or NULL if setCookie() is never called. If not, modify the cookie or the callback accordingly before sending them using [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f).
Details Parameters `request` The allocation request. Must not be NULL; otherwise the process will crash. `onAlloc` The allocation callback. ### ANpuManager_AllocRequest_setOnPreempt Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setOnPreempt( ANpuManager_AllocRequest *_Nonnull request, ANpuManager_PreemptCallback_Nullable onPreempt ) ``` Sets the preemption callback for an allocation request. Callback function to be invoked when NpuManager needs to forcefully deallocate the buffer. This may be set to NULL, in which case NpuManager will not invoke any callback when preempting the buffer. Default value is NULL. When the buffer is preempted, any subsequent attempt to map the buffer will fail with errno set to ENOENT. See documentation of ANpuManager_PreemptCallback for details about the arguments when the callback is invoked. The new callback must be able to handle any existing cookie value set by setCookie(), or NULL if setCookie() is never called. If not, modify the cookie or the callback accordingly before sending them using [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f).
Details Parameters `request` The allocation request. `onPreempt` The preemption callback. ### ANpuManager_AllocRequest_setProtectionFlags Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setProtectionFlags( ANpuManager_AllocRequest *_Nonnull request, int32_t prot ) ``` Sets the protection flags for the buffer to be allocated. Note: This specifies the protection flags for the buffer, not the flags for the mmap call. The flags for the mmap call is passed via [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b). If never called, the default value is PROT_READ. After the buffer is allocated, [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b) may only be called with \|prot\| to be a subset of the value set by this function. If not, [ANpuBuffer_map()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gaeebda35ea1a28cdc9281a6db42fe359b) fails and returns MAP_FAILED.
Details Parameters `request` The allocation request. `prot` The protection flags. Either PROT_NONE, or the bitwise OR of one or more of PROT_READ, PROT_WRITE, PROT_EXEC. ### ANpuManager_AllocRequest_setSize Declared in `android/npumanager/buffer.h` ``` void ANpuManager_AllocRequest_setSize( ANpuManager_AllocRequest *_Nonnull request, int64_t size ) ``` Sets the size of the buffer in bytes for an allocation request. If never called, the default value is 0.
Details Parameters `request` The allocation request. `size` The size of the buffer. ### ANpuManager_allocAsync Declared in `android/npumanager/buffer.h` ``` void ANpuManager_allocAsync( ANpuManager_AllocRequest *_Nonnull const *_Nonnull requests, size_t requestsLen ) ``` Asynchronously allocates multiple buffers. Each ANpuBuffer\*, after being received from the onAlloc callback, must be explicitly freed by calling [ANpuBuffer_free()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gafdda876ec553ca86132672840bd812ed). This is the case even if the buffer is preempted by NpuManagerService. Available since API level 37.
Details Parameters `requests` A list of requests, each describing a buffer to allocate. ``` ANpuManager does not take ownership of the given request objects. The caller is responsible for calling the ANpuManager_AllocRequest_free() on them. The caller may call ANpuManager_AllocRequest_free() right after ANpuManager_allocAsync() is called. The caller does not need to wait for the response on the onAlloc callback to free the request. The onAlloc callback must not be NULL. Otherwise, the process will crash. A "snapshot" of the requests are taken; in other words, all parameters are recorded at the moment ANpuManager_allocAsync() is called. Any subsequent modification to the request objects will not be reflected in the allocation or in the callbacks. For example, if you call ANpuManager_AllocRequest_setCookie() after ANpuManager_allocAsync() is called, the old cookie value will be used when the onAlloc callback is invoked. The list must not be modified during the execution of ANpuManager_allocAsync(). Otherwise, the behavior is undefined. It is okay to modify the list after ANpuManager_allocAsync() returns, even before the onAlloc callback is invoked. The elements of the list must not be modified or freed during the execution of ANpuManager_allocAsync(), e.g. via the ANpuManager_AllocRequest_setXXX() functions and ANpuManager_AllocRequest_free(). Otherwise, the behavior is undefined. It is okay to modify or free the elements after ANpuManager_allocAsync() returns, even before the onAlloc callback is invoked. ``` `requestsLen` The length of the requests list. ### ANpuManager_isSupported Declared in `android/npumanager/buffer.h` ``` int ANpuManager_isSupported( ANpuManager_AllocRequest *_Nonnull const *_Nonnull requests, size_t requestsLen, bool *_Nonnull outIsSupported ) ``` Tests if the provided requests are supported or not. If a request is supported, [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) may still respond onAlloc with a failure due to other reasons, e.g., no memory. If a request is not supported, [ANpuManager_allocAsync()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gae742920b1c4314342650f363f9fe2b6f) guarantees to respond onAlloc with a failure. The following fields in the requests are ignored: - cookie - onAlloc - onPreempt
``` The list must not be modified during the execution of ANpuManager_isSupported(). Otherwise, the behavior is undefined. It is okay to modify the list after ANpuManager_isSupported() returns, even before the onAlloc callback is invoked. The elements of the list must not be modified or freed during the execution of ANpuManager_isSupported(), e.g. via the ANpuManager_AllocRequest_setXXX() functions and ANpuManager_AllocRequest_free(). Otherwise, the behavior is undefined. It is okay to modify or free the elements after ANpuManager_isSupported() returns, even before the onAlloc callback is invoked. ```
Details Parameters `requests` The allocation requests to test. The caller must not simultaneously write to this array during the execution of [ANpuManager_isSupported()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gad249e2319145325f7c7ba9d1e6fa4b32). Otherwise, the behavior is undefined. Details Parameters `requestsLen` The length of the requests list. `outIsSupported` The output boolean array to store the support status of each request. It must be valid for at least requestsLen elements for [ANpuManager_isSupported()](https://developer.android.com/ndk/reference/group/a-npu-buffer#group___a_npu_buffer_1gad249e2319145325f7c7ba9d1e6fa4b32) to write to. **Returns** 0 on successfully testing whether the requests are supported or not (even if some or all of them are not supported); results are stored in outIsSupported. Otherwise, if there is an error, returns -1 with with errno set, and results in outIsSupported should be ignored by the caller.