\brief Cleans, and optionally invalidates, the cache for the region of memory specified by the
given buffer, offset, and size, and write the contents to ram.
\param buffer A valid buffer.
\param offset An offset into the buffer. Must be less than or equal to the buffer’s size.
\param size Size of region to be cleaned. Offset + size must be less than or equal to the
buffer’s size.
\param operation One of MAGMA_CACHE_OPERATION_CLEAN or MAGMA_CACHE_OPERATION_CLEAN_INVALIDATE.
\brief Exports the given buffer, returning a handle that may be imported into a connection.
\param buffer A valid buffer.
\param buffer_handle_out The returned handle.
\brief Gets a platform handle for the given buffer. This can be used to perform a CPU mapping of
the buffer using the standard syscall. The handle may be released without invalidating
such CPU mappings.
\param buffer A valid buffer.
\param handle_out Pointer to the returned handle.
\brief Configures the cache for the given buffer.
\param buffer A valid buffer.
\param policy One of MAGMA_CACHE_POLICY_[CACHED|WRITE_COMBINING|UNCACHED].
\brief Sets a name for the buffer for use in debugging tools.
\param buffer A valid buffer.
\param name The 0-terminated name of the buffer. May be truncated.
\brief Adds a an array of buffers + offset to the pool. |offsets[n].buffer_id| is the koid of a
buffer that was previously imported using ImportBuffer(). The same buffer may be added to
multiple pools. The pool will hold on to a reference to the buffer even after
ReleaseBuffer is called. When dumped into this entry, counters will be written starting
at |offsets[n].offset| bytes into the buffer, and up to |offsets[n].offset| +
|offsets[n].size|. |offsets[n].size| must be large enough to fit all enabled counters.
Performance counter access must have been enabled using
magma_connection_enable_performance_counter_access before calling this method.
\param connection An open connection to a device.
\param pool_id An existing pool.
\param offsets An array of offsets to add.
\param offsets_count The number of elements in offsets.
\brief Sets the values of all listed performance counters to 0. May not be supported by some
hardware. Performance counter access must have been enabled using
magma_connection_enable_performance_counter_access before calling this method.
\param connection An open connection to a device.
\param counters An implementation-defined list of counters.
\param counters_count The number of entries in |counters|.
\brief Creates a memory buffer of at least the given size.
\param connection An open connection.
\param size Requested buffer size.
\param size_out The returned buffer’s actual size.
\param buffer_out The returned buffer.
\param id_out The buffer id of the buffer.
\brief Create a pool of buffers that performance counters can be dumped into. Performance
counter access must have been enabled using
magma_connection_enable_performance_counter_access before calling this method.
\param connection An open connection to a device.
\param pool_id_out A new pool id. Must not currently be in use.
\param notification_handle_out A handle that should be waited on.
\brief Triggers dumping of the performance counters into a buffer pool. May fail silently if
there are no buffers in the pool. |trigger_id| is an arbitrary ID assigned by the client
that can be returned in OnPerformanceCounterReadCompleted. Performance counter access
must have been enabled using magma_connection_enable_performance_counter_access before
calling this method.
\param connection An open connection to a device.
\param pool_id An existing pool
\param trigger_id An arbitrary ID assigned by the client that will be returned in
OnPerformanceCounterReadCompleted.
\brief Tries to enable access to performance counters. Returns MAGMA_STATUS_OK if counters were
successfully enabled or MAGMA_STATUS_ACCESS_DENIED if channel is for the wrong device and
counters were not successfully enabled previously.
\param connection An open connection to a device.
\param channel A handle to a channel to a gpu-performance-counter device.
\brief Enables a set of performance counters (the precise definition depends on the driver).
Disables enabled performance counters that are not in the new set. Performance counters
will also be automatically disabled on connection close. Performance counter access must
have been enabled using magma_connection_enable_performance_counter_access before calling
this method.
\param connection An open connection to a device.
\param counters An implementation-defined list of counters.
\param counters_count The number of entries in |counters|.
\brief Submits command buffers for execution on the hardware.
\param connection An open connection.
\param context_id A valid context id.
\param descriptor A pointer to the command descriptor.
\brief Submits a series of commands for execution on the hardware without using a command
buffer.
\param connection An open connection.
\param context_id A valid context ID.
\param command_count The number of commands in the provided buffer.
\param command_buffers An array of command_count magma_inline_command_buffer structs.
\brief Submits a series of commands for execution on the hardware without using a command
buffer.
\param connection An open connection.
\param context_id A valid context ID.
\param command_count The number of commands in the provided buffer.
\param command_buffers An array of command_count magma_inline_command_buffer structs.
\brief Incurs a round-trip to the system driver, used to ensure all previous messages have been
observed, but not necessarily completed. If a system driver error occurs, the connection
will be closed, and this interface will return the error.
\param connection An open connection.
\brief If a system driver error occurs, the connection will be closed, and this interface will
eventually return the error. This interface does not flush messages that may be pending
(see magma_connection_flush).
\param connection An open connection.
\brief Returns a handle that can be waited on to determine when the connection has data in the
notification channel. This channel has the same lifetime as the connection and must not
be closed by the client.
\param connection An open connection.
\brief Imports and takes ownership of the buffer referred to by the given handle. Takes
ownership of |buffer_handle| on both success and failure.
\param connection An open connection.
\param buffer_handle A valid handle.
\param size_out The size of the buffer in bytes.
\param buffer_out The returned buffer.
\param id_out The buffer id of the buffer.
\brief Imports and takes ownership of the semaphore referred to by the given handle. Takes
ownership of |semaphore_handle| on both success and failure.
\param connection An open connection.
\param semaphore_handle A valid semaphore handle.
\param flags Pass MAGMA_IMPORT_SEMAPHORE_ONESHOT to prevent auto-reset after wait.
\param semaphore_out The returned semaphore.
\param id_out The id of the semaphore.
\brief Maps a buffer range onto the hardware in the connection’s address space at the given
address. Depending on the MSD this may automatically commit and populate that range.
\param connection An open connection.
\param hw_va Destination virtual address for the mapping.
\param buffer A valid buffer.
\param offset Offset into the buffer.
\param length Length in bytes of the range to map.
\param map_flags A valid MAGMA_MAP_FLAGS value.
\brief Perform an operation on a range of a buffer
\param connection An open connection.
\param buffer A valid buffer.
\param options Options for the operation.
\param start_offset Byte offset into the buffer.
\param length Length (in bytes) of the region to operate on.
\brief Reads a notification from the channel into the given buffer. Message sizes may vary
depending on the MSD. If the buffer provided is too small for the message,
MAGMA_STATUS_INVALID_ARGS will be returned and the size of message will be returned in
the buffer_size_out parameter.
\param connection An open connection.
\param buffer Buffer into which to read notification data.
\param buffer_size Size of the given buffer.
\param buffer_size_out Returned size of the notification data written to the buffer, or 0 if
there are no messages pending.
\param more_data_out True if there is more notification data waiting.
\brief Reads one performance counter completion event, if available.
\param connection An open connection to a device.
\param pool_id An existing pool.
\param trigger_id_out The trigger ID for this event.
\param buffer_id_out The buffer ID for this event.
\param buffer_offset_out The buffer offset for this event.
\param time_out The monotonic time this event happened.
\param result_flags_out A set of flags giving more information about this event.
\brief Releases a pool of performance counter buffers. Performance counter access must have been
enabled using magma_connection_enable_performance_counter_access before calling this
method.
\param connection An open connection to a device.
\param pool_id An existing pool id.
\brief Removes every offset of a buffer from the pool. Performance counter access must have been
enabled using magma_connection_enable_performance_counter_access before calling this
method.
\param connection An open connection to a device.
\param pool_id An existing pool.
\param buffer A magma_buffer
\brief Releases the mapping at the given hardware address.
\param connection An open connection.
\param hw_va A hardware virtual address associated with an existing mapping of the given buffer.
\param buffer A valid buffer.
\brief Imports and takes ownership of a channel to a device. Takes ownership of |device_channel|
on both success and failure.
\param device_channel A channel connecting to a gpu class device.
\param device_out Returned device.
\brief Performs a query synchronously. On MAGMA_STATUS_OK, a given query |id| will return either
a buffer in |result_buffer_out|, or a value in |result_out|. A NULL pointer may be
provided for whichever result parameter is not needed.
\param device An open device.
\param id A vendor-specific ID.
\param result_buffer_out Handle to the returned buffer.
\param result_out Pointer to a uint64 result.
\brief Initializes logging, used for debug and some exceptional error reporting. This should be
called on Fuchsia; on other platforms it’s not needed and will just close the given
handle.
\param channel An open connection to the syslog service.
\brief Initializes tracing. This should be called on Fuchsia; on other platforms it’s not needed
and will just close the given handle.
\param channel An open connection to a tracing provider.
\brief Waits for at least one of the given items to meet a condition. Does not reset any
semaphores. When MAGMA_STATUS_OK is returned, results are returned in the items array.
MAGMA_STATUS_TIMED_OUT is returned if no conditions are met before the given timeout
expires. If the notification channel handle is included in the item list, and the magma
connection is closed, then MAGMA_STATUS_CONNECTION_LOST is returned.
\param items Array of poll items. Type should be either MAGMA_POLL_TYPE_SEMAPHORE or
MAGMA_POLL_TYPE_HANDLE. Condition may be set to MAGMA_POLL_CONDITION_SIGNALED OR
MAGMA_POLL_CONDITION_READABLE. If condition is 0 the item is ignored. Item results are
set to the condition that was satisfied, otherwise 0. If the same item is given twice the
behavior is undefined.
\param count Number of poll items in the array.
\param timeout_ns Time in ns to wait before returning MAGMA_STATUS_TIMED_OUT.
\brief Exports the given semaphore, returning a handle that may be imported into a connection
\param semaphore A valid semaphore.
\param semaphore_handle_out The returned handle.
\brief Creates an image buffer backed by a buffer collection given a DRM format and optional
modifier, as specified in the create info.
\param connection An open connection.
\param create_info Input parameters describing the image.
\param size_out The size of the image buffer in bytes
\param image_out The image buffer.
\param buffer_id_out The ID of the image buffer.
\brief Returns parameters for an image created with virtmagma_create_image.
\param connection An open connection.
\param image The image buffer.
\param image_info_out Output parameters describing the image.