garnet/lib/magma/include/magma_abi/magma.h - fuchsia - Git at Google

 // Copyright 2016 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 #ifndef GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_
 #define GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_

 #include "magma_common_defs.h"
 #include <stdint.h>

 #if defined(__cplusplus)
 extern "C" {
 #endif

 // Performs a query and returns a result synchronously.
 // |file_descriptor| must correspond to an open device of class gpu.
 // |id| is one of MAGMA_QUERY_DEVICE_ID, or a vendor-specific id starting from
 // MAGMA_QUERY_FIRST_VENDOR_ID.
 // Data is returned in |value_out|.
 magma_status_t magma_query(int32_t file_descriptor, uint64_t id, uint64_t* value_out);

 // Opens a connection to a device and returns it in |connection_out|.
 // |file_descriptor| must correspond to an open device of class gpu.
 magma_status_t magma_create_connection(int32_t file_descriptor, magma_connection_t* connection_out);

 // Releases the given |connection|.
 void magma_release_connection(magma_connection_t connection);

 // Returns the first recorded error since the last time this function was called.
 // Clears the recorded error.
 // Incurs a round-trip to the system driver.
 magma_status_t magma_get_error(magma_connection_t connection);

 // Creates a context on the given |connection| and returns an id in |context_id_out|.
 // A context is required to submit command buffers.
 void magma_create_context(magma_connection_t connection, uint32_t* context_id_out);

 // Releases the context associated with |context_id|.
 void magma_release_context(magma_connection_t connection, uint32_t context_id);

 // Creates a memory buffer of at least the given |size| and returns a handle to it
 // in |buffer|.
 // The actual size is returned in |size_out|.
 magma_status_t magma_create_buffer(magma_connection_t connection, uint64_t size, uint64_t* size_out,
                                    magma_buffer_t* buffer_out);

 // Releases the given memory |buffer|.
 void magma_release_buffer(magma_connection_t connection, magma_buffer_t buffer);

 // Duplicates |buffer_handle|, giving another handle that can be imported into a connection.
 magma_status_t magma_duplicate_handle(uint32_t buffer_handle, uint32_t* buffer_handle_out);

 // Releases |buffer_handle|.
 magma_status_t magma_release_buffer_handle(uint32_t buffer_handle);

 // Returns a unique id for the given |buffer|.
 uint64_t magma_get_buffer_id(magma_buffer_t buffer);

 // Returns the size of the given |buffer|.
 uint64_t magma_get_buffer_size(magma_buffer_t buffer);

 // Cleans the cache for the region of memory specified by |buffer| at the given |offset|
 // and |size|, and write the contents to ram.
 // If |operation| is MAGMA_CACHE_OPERATION_CLEAN_INVALIDATE, then also invalidates
 // the cache lines, so reads will fetch from external memory.
 magma_status_t magma_clean_cache(magma_buffer_t buffer, uint64_t offset, uint64_t size,
                                  magma_cache_operation_t operation);

 // Configures the cache for the given |buffer|.
 // This must be set before the buffer is mapped anywhere.
 magma_status_t magma_set_cache_policy(magma_buffer_t buffer, magma_cache_policy_t policy);

 // Queries the cache policy for a buffer.
 magma_status_t magma_get_buffer_cache_policy(magma_buffer_t buffer,
                                              magma_cache_policy_t* cache_policy_out);

 // |is_mappable_out| is set to true if and only if the buffer is mappable with
 // magma_map or magma_map_aligned. |flags| must be 0.
 magma_status_t magma_get_buffer_is_mappable(magma_buffer_t buffer, uint32_t flags,
                                             magma_bool_t* is_mappable_out);

 // Creates a mapping for the given |buffer| on the cpu.
 // The cpu virtual address is returned in |addr_out|.
 // May be called multiple times.
 magma_status_t magma_map(magma_connection_t connection, magma_buffer_t buffer, void** addr_out);

 // Creates a mapping for the given |buffer| on the cpu with the given |alignment|, which
 // must be a power of 2 and at least PAGE_SIZE. The cpu virtual address is returned
 // in |addr_out|.
 magma_status_t magma_map_aligned(magma_connection_t connection, magma_buffer_t buffer,
                                  uint64_t alignment, void** addr_out);

 // Attempts to map the given |buffer| at a specific cpu virtual address |addr|.
 // Fails if the buffer was previously mapped, or if that address is unavailable.
 magma_status_t magma_map_specific(magma_connection_t connection, magma_buffer_t buffer,
                                   uint64_t addr, uint64_t offset, uint64_t length);

 // Releases a cpu mapping for the given |buffer|.
 // Should be paired with each call to one of the mapping interfaces.
 magma_status_t magma_unmap(magma_connection_t connection, magma_buffer_t buffer);

 // Maps |page_count| pages of |buffer| from |page_offset| onto the GPU in the connection's address
 // space at |gpu_va|.
 // |map_flags| is a set of flags from MAGMA_GPU_MAP_FLAGS that specify how the GPU can access
 // the buffer.
 void magma_map_buffer_gpu(magma_connection_t connection, magma_buffer_t buffer,
                           uint64_t page_offset, uint64_t page_count, uint64_t gpu_va,
                           uint64_t map_flags);

 // Releases the mapping at |gpu_va| from the GPU.
 // Buffers will also be implicitly unmapped when released.
 void magma_unmap_buffer_gpu(magma_connection_t connection, magma_buffer_t buffer, uint64_t gpu_va);

 // Ensures that |page_count| pages starting at |page_offset| from the beginning of the buffer
 // are backed by physical memory.
 void magma_commit_buffer(magma_connection_t connection, magma_buffer_t buffer, uint64_t page_offset,
                          uint64_t page_count);

 // Exports |buffer|, returning it in |buffer_handle_out|, so it may be imported into another
 // connection.
 magma_status_t magma_export(magma_connection_t connection, magma_buffer_t buffer,
                             uint32_t* buffer_handle_out);

 // Imports and takes ownership of the buffer referred to by |buffer_handle| into the given
 // |connection| and makes it accessible via |buffer_out|.
 magma_status_t magma_import(magma_connection_t connection, uint32_t buffer_handle,
                             magma_buffer_t* buffer_out);

 // Creates a buffer of the given |size| that may be submitted as command buffer.
 // The buffer is returned in |buffer_out|.
 magma_status_t magma_create_command_buffer(magma_connection_t connection, uint64_t size,
                                            magma_buffer_t* buffer_out);

 // Releases a command buffer without submitting it.
 void magma_release_command_buffer(magma_connection_t connection, magma_buffer_t command_buffer);

 // Submits a command buffer for execution on the GPU.
 // Note that the buffer referred to by |command_buffer| must contain a valid
 // magma_system_command_buffer and all associated data structures
 // Transfers ownership of |command_buffer|.
 void magma_submit_command_buffer(magma_connection_t connection, magma_buffer_t command_buffer,
                                  uint32_t context_id);

 // Submits a series of commands for execution on the GPU without using a command buffer.
 void magma_execute_immediate_commands(magma_connection_t connection, uint32_t context_id,
                                       uint64_t command_count,
                                       struct magma_system_inline_command_buffer* command_buffers);

 // Creates a semaphore which is returned in |semaphore_out|.
 magma_status_t magma_create_semaphore(magma_connection_t connection,
                                       magma_semaphore_t* semaphore_out);

 // Releases the given |semaphore|.
 void magma_release_semaphore(magma_connection_t connection, magma_semaphore_t semaphore);

 // Returns the object id for the given |semaphore|.
 uint64_t magma_get_semaphore_id(magma_semaphore_t semaphore);

 // Signals the given |semaphore|.
 void magma_signal_semaphore(magma_semaphore_t semaphore);

 // Resets the given |semaphore|.
 void magma_reset_semaphore(magma_semaphore_t semaphore);

 // Waits for all or one of |semaphores| to be signaled.
 // Returns MAGMA_STATUS_TIMED_OUT if |timeout_ms| expires first.
 // Does not reset any semaphores.
 magma_status_t magma_wait_semaphores(const magma_semaphore_t* semaphores, uint32_t count,
                                      uint64_t timeout_ms, magma_bool_t wait_all);

 // Exports |semaphore|, returning it in |semaphore_handle_out|, so it can be imported into another
 // connection.
 magma_status_t magma_export_semaphore(magma_connection_t connection, magma_semaphore_t semaphore,
                                       uint32_t* semaphore_handle_out);

 // Imports and takes ownership of the semaphore referred to by |semaphore_handle| into the given
 // |connection| and makes it accessible via |semaphore_out|.
 magma_status_t magma_import_semaphore(magma_connection_t connection, uint32_t semaphore_handle,
                                       magma_semaphore_t* semaphore_out);

 // Returns a uint32_t (zx_handle_t) 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.
 uint32_t magma_get_notification_channel_handle(magma_connection_t connection);

 // Returns MAGMA_STATUS_OK if a message is available on the notification channel before |timeout_ns|
 // expires.
 magma_status_t magma_wait_notification_channel(magma_connection_t connection, int64_t timeout_ns);

 // Reads a notification from the channel into |buffer| which has the given |buffer_size|.
 // Sets |*buffer_size_out| to 0 if there are no messages pending.
 magma_status_t magma_read_notification_channel(magma_connection_t connection, void* buffer,
                                                uint64_t buffer_size, uint64_t* buffer_size_out);

 #if defined(__cplusplus)
 }
 #endif

 #endif // GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_
	// Copyright 2016 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	#ifndef GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_
	#define GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_

	#include "magma_common_defs.h"
	#include <stdint.h>

	#if defined(__cplusplus)
	extern "C" {
	#endif

	// Performs a query and returns a result synchronously.
	// \|file_descriptor\| must correspond to an open device of class gpu.
	// \|id\| is one of MAGMA_QUERY_DEVICE_ID, or a vendor-specific id starting from
	// MAGMA_QUERY_FIRST_VENDOR_ID.
	// Data is returned in \|value_out\|.
	magma_status_t magma_query(int32_t file_descriptor, uint64_t id, uint64_t* value_out);

	// Opens a connection to a device and returns it in \|connection_out\|.
	// \|file_descriptor\| must correspond to an open device of class gpu.
	magma_status_t magma_create_connection(int32_t file_descriptor, magma_connection_t* connection_out);

	// Releases the given \|connection\|.
	void magma_release_connection(magma_connection_t connection);

	// Returns the first recorded error since the last time this function was called.
	// Clears the recorded error.
	// Incurs a round-trip to the system driver.
	magma_status_t magma_get_error(magma_connection_t connection);

	// Creates a context on the given \|connection\| and returns an id in \|context_id_out\|.
	// A context is required to submit command buffers.
	void magma_create_context(magma_connection_t connection, uint32_t* context_id_out);

	// Releases the context associated with \|context_id\|.
	void magma_release_context(magma_connection_t connection, uint32_t context_id);

	// Creates a memory buffer of at least the given \|size\| and returns a handle to it
	// in \|buffer\|.
	// The actual size is returned in \|size_out\|.
	magma_status_t magma_create_buffer(magma_connection_t connection, uint64_t size, uint64_t* size_out,
	magma_buffer_t* buffer_out);

	// Releases the given memory \|buffer\|.
	void magma_release_buffer(magma_connection_t connection, magma_buffer_t buffer);

	// Duplicates \|buffer_handle\|, giving another handle that can be imported into a connection.
	magma_status_t magma_duplicate_handle(uint32_t buffer_handle, uint32_t* buffer_handle_out);

	// Releases \|buffer_handle\|.
	magma_status_t magma_release_buffer_handle(uint32_t buffer_handle);

	// Returns a unique id for the given \|buffer\|.
	uint64_t magma_get_buffer_id(magma_buffer_t buffer);

	// Returns the size of the given \|buffer\|.
	uint64_t magma_get_buffer_size(magma_buffer_t buffer);

	// Cleans the cache for the region of memory specified by \|buffer\| at the given \|offset\|
	// and \|size\|, and write the contents to ram.
	// If \|operation\| is MAGMA_CACHE_OPERATION_CLEAN_INVALIDATE, then also invalidates
	// the cache lines, so reads will fetch from external memory.
	magma_status_t magma_clean_cache(magma_buffer_t buffer, uint64_t offset, uint64_t size,
	magma_cache_operation_t operation);

	// Configures the cache for the given \|buffer\|.
	// This must be set before the buffer is mapped anywhere.
	magma_status_t magma_set_cache_policy(magma_buffer_t buffer, magma_cache_policy_t policy);

	// Queries the cache policy for a buffer.
	magma_status_t magma_get_buffer_cache_policy(magma_buffer_t buffer,
	magma_cache_policy_t* cache_policy_out);

	// \|is_mappable_out\| is set to true if and only if the buffer is mappable with
	// magma_map or magma_map_aligned. \|flags\| must be 0.
	magma_status_t magma_get_buffer_is_mappable(magma_buffer_t buffer, uint32_t flags,
	magma_bool_t* is_mappable_out);

	// Creates a mapping for the given \|buffer\| on the cpu.
	// The cpu virtual address is returned in \|addr_out\|.
	// May be called multiple times.
	magma_status_t magma_map(magma_connection_t connection, magma_buffer_t buffer, void** addr_out);

	// Creates a mapping for the given \|buffer\| on the cpu with the given \|alignment\|, which
	// must be a power of 2 and at least PAGE_SIZE. The cpu virtual address is returned
	// in \|addr_out\|.
	magma_status_t magma_map_aligned(magma_connection_t connection, magma_buffer_t buffer,
	uint64_t alignment, void** addr_out);

	// Attempts to map the given \|buffer\| at a specific cpu virtual address \|addr\|.
	// Fails if the buffer was previously mapped, or if that address is unavailable.
	magma_status_t magma_map_specific(magma_connection_t connection, magma_buffer_t buffer,
	uint64_t addr, uint64_t offset, uint64_t length);

	// Releases a cpu mapping for the given \|buffer\|.
	// Should be paired with each call to one of the mapping interfaces.
	magma_status_t magma_unmap(magma_connection_t connection, magma_buffer_t buffer);

	// Maps \|page_count\| pages of \|buffer\| from \|page_offset\| onto the GPU in the connection's address
	// space at \|gpu_va\|.
	// \|map_flags\| is a set of flags from MAGMA_GPU_MAP_FLAGS that specify how the GPU can access
	// the buffer.
	void magma_map_buffer_gpu(magma_connection_t connection, magma_buffer_t buffer,
	uint64_t page_offset, uint64_t page_count, uint64_t gpu_va,
	uint64_t map_flags);

	// Releases the mapping at \|gpu_va\| from the GPU.
	// Buffers will also be implicitly unmapped when released.
	void magma_unmap_buffer_gpu(magma_connection_t connection, magma_buffer_t buffer, uint64_t gpu_va);

	// Ensures that \|page_count\| pages starting at \|page_offset\| from the beginning of the buffer
	// are backed by physical memory.
	void magma_commit_buffer(magma_connection_t connection, magma_buffer_t buffer, uint64_t page_offset,
	uint64_t page_count);

	// Exports \|buffer\|, returning it in \|buffer_handle_out\|, so it may be imported into another
	// connection.
	magma_status_t magma_export(magma_connection_t connection, magma_buffer_t buffer,
	uint32_t* buffer_handle_out);

	// Imports and takes ownership of the buffer referred to by \|buffer_handle\| into the given
	// \|connection\| and makes it accessible via \|buffer_out\|.
	magma_status_t magma_import(magma_connection_t connection, uint32_t buffer_handle,
	magma_buffer_t* buffer_out);

	// Creates a buffer of the given \|size\| that may be submitted as command buffer.
	// The buffer is returned in \|buffer_out\|.
	magma_status_t magma_create_command_buffer(magma_connection_t connection, uint64_t size,
	magma_buffer_t* buffer_out);

	// Releases a command buffer without submitting it.
	void magma_release_command_buffer(magma_connection_t connection, magma_buffer_t command_buffer);

	// Submits a command buffer for execution on the GPU.
	// Note that the buffer referred to by \|command_buffer\| must contain a valid
	// magma_system_command_buffer and all associated data structures
	// Transfers ownership of \|command_buffer\|.
	void magma_submit_command_buffer(magma_connection_t connection, magma_buffer_t command_buffer,
	uint32_t context_id);

	// Submits a series of commands for execution on the GPU without using a command buffer.
	void magma_execute_immediate_commands(magma_connection_t connection, uint32_t context_id,
	uint64_t command_count,
	struct magma_system_inline_command_buffer* command_buffers);

	// Creates a semaphore which is returned in \|semaphore_out\|.
	magma_status_t magma_create_semaphore(magma_connection_t connection,
	magma_semaphore_t* semaphore_out);

	// Releases the given \|semaphore\|.
	void magma_release_semaphore(magma_connection_t connection, magma_semaphore_t semaphore);

	// Returns the object id for the given \|semaphore\|.
	uint64_t magma_get_semaphore_id(magma_semaphore_t semaphore);

	// Signals the given \|semaphore\|.
	void magma_signal_semaphore(magma_semaphore_t semaphore);

	// Resets the given \|semaphore\|.
	void magma_reset_semaphore(magma_semaphore_t semaphore);

	// Waits for all or one of \|semaphores\| to be signaled.
	// Returns MAGMA_STATUS_TIMED_OUT if \|timeout_ms\| expires first.
	// Does not reset any semaphores.
	magma_status_t magma_wait_semaphores(const magma_semaphore_t* semaphores, uint32_t count,
	uint64_t timeout_ms, magma_bool_t wait_all);

	// Exports \|semaphore\|, returning it in \|semaphore_handle_out\|, so it can be imported into another
	// connection.
	magma_status_t magma_export_semaphore(magma_connection_t connection, magma_semaphore_t semaphore,
	uint32_t* semaphore_handle_out);

	// Imports and takes ownership of the semaphore referred to by \|semaphore_handle\| into the given
	// \|connection\| and makes it accessible via \|semaphore_out\|.
	magma_status_t magma_import_semaphore(magma_connection_t connection, uint32_t semaphore_handle,
	magma_semaphore_t* semaphore_out);

	// Returns a uint32_t (zx_handle_t) 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.
	uint32_t magma_get_notification_channel_handle(magma_connection_t connection);

	// Returns MAGMA_STATUS_OK if a message is available on the notification channel before \|timeout_ns\|
	// expires.
	magma_status_t magma_wait_notification_channel(magma_connection_t connection, int64_t timeout_ns);

	// Reads a notification from the channel into \|buffer\| which has the given \|buffer_size\|.
	// Sets \|*buffer_size_out\| to 0 if there are no messages pending.
	magma_status_t magma_read_notification_channel(magma_connection_t connection, void* buffer,
	uint64_t buffer_size, uint64_t* buffer_size_out);

	#if defined(__cplusplus)
	}
	#endif

	#endif // GARNET_LIB_MAGMA_INCLUDE_MAGMA_ABI_MAGMA_H_