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.

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(), NOT to ANpuManager_allocAsync().

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() 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() for details.

The callback may be called from any thread. The user is responsible for accessing the cookie in a thread-safe manner.

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(), 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() to unmap any existing mappings to the buffer.

Even if a buffer is preempted, it must still be explicitly freed by calling ANpuBuffer_free() to clean up remaining resources.

Available since API level 37.

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

Loads a file into the buffer asynchronously.

There should not be any existing mapping (via ANpuBuffer_map()) 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.

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().

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() during this time window, it will still get -1 with errno set to ENOENT, even though when ANpuManager_OnPreempt has not been called yet.

Sets the priority of the buffer.

Available since API level 37.

Unmaps a previously mapped buffer.

The arguments are similar to munmap().

Available since API level 37.

Creates a new allocation request.

Fields are initialized to a default state.

Destroys an allocation request.

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.

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.

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().

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.

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.

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(). 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().

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().

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().

If never called, the default value is PROT_READ.

After the buffer is allocated, ANpuBuffer_map() may only be called with |prot| to be a subset of the value set by this function. If not, ANpuBuffer_map() fails and returns MAP_FAILED.

Sets the size of the buffer in bytes for an allocation request.

If never called, the default value is 0.

Asynchronously allocates multiple buffers.

Each ANpuBuffer*, after being received from the onAlloc callback, must be explicitly freed by calling ANpuBuffer_free(). This is the case even if the buffer is preempted by NpuManagerService.

Available since API level 37.

            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.

Tests if the provided requests are supported or not.

If a request is supported, ANpuManager_allocAsync() may still respond onAlloc with a failure due to other reasons, e.g., no memory. If a request is not supported, ANpuManager_allocAsync() 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.

The caller must not simultaneously write to this array during the execution of ANpuManager_isSupported(). Otherwise, the behavior is undefined.