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.

// NOTE: DO NOT EDIT THIS FILE!
// It is automatically generated by //garnet/lib/magma/include/magma_abi/magma.h.gen.py

#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

///
/// \brief Performs a query and returns a result synchronously.
/// \param file_descriptor An open device of class gpu.
/// \param id Either MAGMA_QUERY_DEVICE_ID, or a vendor-specific id starting from
///        MAGMA_QUERY_VENDOR_PARAM_0.
/// \param value_out Returned value.
///
magma_status_t magma_query(
    int32_t file_descriptor,
    uint64_t id,
    uint64_t* value_out);

///
/// \brief Opens a connection to a device.
/// \param file_descriptor An open device of class gpu.
/// \param connection_out Returned connection.
///
magma_status_t magma_create_connection(
    int32_t file_descriptor,
    magma_connection_t* connection_out);

///
/// \brief Releases the given connection.
/// \param connection An open connection.
///
void magma_release_connection(
    magma_connection_t connection);

///
/// \brief Returns the first recorded error since the last time this function was called, and clears
///        the recorded error. Incurs a round-trip to the system driver
/// \param connection An open connection.
///
magma_status_t magma_get_error(
    magma_connection_t connection);

///
/// \brief Creates a context on the given connection.
/// \param connection An open connection.
/// \param context_id_out The returned context id.
///
void magma_create_context(
    magma_connection_t connection,
    uint32_t* context_id_out);

///
/// \brief Releases the context associated with the given id.
/// \param connection An open connection.
/// \param context_id A valid context id.
///
void magma_release_context(
    magma_connection_t connection,
    uint32_t context_id);

///
/// \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.
///
magma_status_t magma_create_buffer(
    magma_connection_t connection,
    uint64_t size,
    uint64_t* size_out,
    magma_buffer_t* buffer_out);

///
/// \brief Releases the given memory buffer.
/// \param connection An open connection.
/// \param buffer A valid buffer.
///
void magma_release_buffer(
    magma_connection_t connection,
    magma_buffer_t buffer);

///
/// \brief Duplicates the given handle, giving another handle that can be imported into a
///        connection.
/// \param buffer_handle A valid handle.
/// \param buffer_handle_out The returned duplicate handle.
///
magma_status_t magma_duplicate_handle(
    uint32_t buffer_handle,
    uint32_t* buffer_handle_out);

///
/// \brief Releases the given handle.
/// \param buffer_handle A valid handle.
///
magma_status_t magma_release_buffer_handle(
    uint32_t buffer_handle);

///
/// \brief Returns a unique id for the given buffer.
/// \param buffer A valid buffer.
///
uint64_t magma_get_buffer_id(
    magma_buffer_t buffer);

///
/// \brief Returns the actual size of the given buffer.
/// \param buffer A valid buffer.
///
uint64_t magma_get_buffer_size(
    magma_buffer_t buffer);

///
/// \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.
///
magma_status_t magma_clean_cache(
    magma_buffer_t buffer,
    uint64_t offset,
    uint64_t size,
    magma_cache_operation_t operation);

///
/// \brief Configures the cache for the given buffer.
/// \param buffer A valid buffer.
/// \param policy One of MAGMA_CACHE_POLICY_[CACHED|WRITE_COMBINING|UNCACHED].
///
magma_status_t magma_set_cache_policy(
    magma_buffer_t buffer,
    magma_cache_policy_t policy);

///
/// \brief Queries the cache policy for a buffer.
/// \param buffer A valid buffer.
/// \param cache_policy_out The returned cache policy.
///
magma_status_t magma_get_buffer_cache_policy(
    magma_buffer_t buffer,
    magma_cache_policy_t* cache_policy_out);

///
/// \brief Queries whether a buffer is mappable with magma_map or magma_map_aligned
/// \param buffer The given buffer.
/// \param flags Reserved for future use. Must be 0.
/// \param is_mappable_out The returned mappability value.
///
magma_status_t magma_get_buffer_is_mappable(
    magma_buffer_t buffer,
    uint32_t flags,
    magma_bool_t* is_mappable_out);

///
/// \brief Maps the given buffer's memory into the calling process's address space.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param addr_out The returned CPU virtual address for the start of the buffer.
///
magma_status_t magma_map(
    magma_connection_t connection,
    magma_buffer_t buffer,
    void** addr_out);

///
/// \brief Maps the given buffer's memory into the calling process's address space with a given
///        alignment.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param alignment The requested alignment. Must be a power of 2 and at least PAGE_SIZE.
/// \param addr_out The returned CPU virtual address for the start of the buffer.
///
magma_status_t magma_map_aligned(
    magma_connection_t connection,
    magma_buffer_t buffer,
    uint64_t alignment,
    void** addr_out);

///
/// \brief Maps a region of the given buffer's memory at the given CPU virtual address. Fails if the
///        buffer was previously mapped, or if the address range is unavailable.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param addr A valid CPU virtual address.
/// \param offset Offset into the buffer. Must be less than or equal to the buffer's size.
/// \param length Size of region to be mapped. Offset + length must be less than or equal to the
///        buffer's size.
///
magma_status_t magma_map_specific(
    magma_connection_t connection,
    magma_buffer_t buffer,
    uint64_t addr,
    uint64_t offset,
    uint64_t length);

///
/// \brief Releases a CPU mapping for the given buffer. Should be paired with each call to one of
///        the mapping interfaces.
/// \param connection An open connection.
/// \param buffer A valid buffer with at least one active CPU mapping.
///
magma_status_t magma_unmap(
    magma_connection_t connection,
    magma_buffer_t buffer);

///
/// \brief Maps a number of pages from the given buffer onto the GPU in the connection's address
///        space at the given address.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param page_offset Offset into the buffer in pages.
/// \param page_count Number of pages to map.
/// \param gpu_va Destination GPU virtual address for the mapping.
/// \param map_flags A valid MAGMA_GPU_MAP_FLAGS value.
///
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);

///
/// \brief Releases the mapping at the given address from the GPU.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param gpu_va A GPU virtual address associated with an existing mapping of the given buffer.
///
void magma_unmap_buffer_gpu(
    magma_connection_t connection,
    magma_buffer_t buffer,
    uint64_t gpu_va);

///
/// \brief Ensures that the given page range of a buffer is backed by physical memory.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param page_offset Page offset into the buffer.
/// \param page_count Number of pages to commit.
///
void magma_commit_buffer(
    magma_connection_t connection,
    magma_buffer_t buffer,
    uint64_t page_offset,
    uint64_t page_count);

///
/// \brief Exports the given buffer, returning a handle that may be imported into another
///        connection.
/// \param connection An open connection.
/// \param buffer A valid buffer.
/// \param buffer_handle_out The returned handle.
///
magma_status_t magma_export(
    magma_connection_t connection,
    magma_buffer_t buffer,
    uint32_t* buffer_handle_out);

///
/// \brief Imports and takes ownership of the buffer referred to by the given handle.
/// \param connection An open connection.
/// \param buffer_handle A valid handle.
/// \param buffer_out The returned buffer.
///
magma_status_t magma_import(
    magma_connection_t connection,
    uint32_t buffer_handle,
    magma_buffer_t* buffer_out);

///
/// \brief Creates a buffer of the given size that may be submitted as a command buffer.
/// \param connection An open connection.
/// \param size The requested size of the buffer.
/// \param buffer_out The returned buffer.
///
magma_status_t magma_create_command_buffer(
    magma_connection_t connection,
    uint64_t size,
    magma_buffer_t* buffer_out);

///
/// \brief Releases a command buffer without submitting it.
/// \param connection An open connection.
/// \param command_buffer A valid command buffer.
///
void magma_release_command_buffer(
    magma_connection_t connection,
    magma_buffer_t command_buffer);

///
/// \brief Submits a command buffer for execution on the GPU, and transfers ownership to the given
///        context.
/// \param connection An open connection.
/// \param command_buffer A valid buffer containing valid magma_system_command_buffer structures.
/// \param context_id A valid context ID.
///
void magma_submit_command_buffer(
    magma_connection_t connection,
    magma_buffer_t command_buffer,
    uint32_t context_id);

///
/// \brief Submits a series of commands for execution on the GPU 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_system_inline_command_buffer structs.
///
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);

///
/// \brief Creates a semaphore.
/// \param connection An open connection.
/// \param semaphore_out The returned semaphore.
///
magma_status_t magma_create_semaphore(
    magma_connection_t connection,
    magma_semaphore_t* semaphore_out);

///
/// \brief Releases the given semaphore.
/// \param connection An open connection.
/// \param semaphore A valid semaphore.
///
void magma_release_semaphore(
    magma_connection_t connection,
    magma_semaphore_t semaphore);

///
/// \brief Returnes a unique id for the given semaphore.
/// \param semaphore A valid semaphore.
///
uint64_t magma_get_semaphore_id(
    magma_semaphore_t semaphore);

///
/// \brief Signals the given semaphore.
/// \param semaphore A valid semaphore.
///
void magma_signal_semaphore(
    magma_semaphore_t semaphore);

///
/// \brief Resets the given semaphore.
/// \param semaphore A valid semaphore.
///
void magma_reset_semaphore(
    magma_semaphore_t semaphore);

///
/// \brief Waits for one or all provided semaphores to be signaled. Does not reset any semaphores.
/// \param semaphores Array of valid semaphores.
/// \param count Number of semaphores in the array.
/// \param timeout_ms Time to wait before returning MAGMA_STATUS_TIMED_OUT.
/// \param wait_all If true, wait for all semaphores, otherwise wait for any semaphore.
///
magma_status_t magma_wait_semaphores(
    const magma_semaphore_t* semaphores,
    uint32_t count,
    uint64_t timeout_ms,
    magma_bool_t wait_all);

///
/// \brief Exports the given semaphore, returning a handle that may be imported into another
///        connection
/// \param connection An open connection.
/// \param semaphore A valid semaphore.
/// \param semaphore_handle_out The returned handle.
///
magma_status_t magma_export_semaphore(
    magma_connection_t connection,
    magma_semaphore_t semaphore,
    uint32_t* semaphore_handle_out);

///
/// \brief Imports and takes ownership of the semaphore referred to by the given handle.
/// \param connection An open connection.
/// \param semaphore_handle A valid semaphore handle.
/// \param semaphore_out The returned semaphore.
///
magma_status_t magma_import_semaphore(
    magma_connection_t connection,
    uint32_t semaphore_handle,
    magma_semaphore_t* semaphore_out);

///
/// \brief 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.
/// \param connection An open connection.
///
uint32_t magma_get_notification_channel_handle(
    magma_connection_t connection);

///
/// \brief Returns MAGMA_STATUS_OK if a message is available on the notification channel before the
///        given timeout expires.
/// \param connection An open connection.
/// \param timeout_ns Time to wait before returning MAGMA_STATUS_TIMED_OUT.
///
magma_status_t magma_wait_notification_channel(
    magma_connection_t connection,
    int64_t timeout_ns);

///
/// \brief Reads a notification from the channel into the given buffer.
/// \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.
///
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_