1# Magma Emugen Interface Definition 2 3The files in this directory were generated using 4third-party/fuchsia/magma/regen.py and reflect the standard magma protocol. 5However, as emugen does not have the ability to generate binding code for nested 6pointers, some method signatures must be modified to use a packed format. For 7clarity, these are defined alongside the original (disabled) signatures and 8labeled "fudge" methods. 9 10## Fudge Methods 11 12The following describes how fudge methods differ from their original methods. 13 14### `magma_device_query_fudge` 15 16If `magma_device_query` for the given query `id` returns a value in `result_out`, then the method populates the value and other fudge parameters are ignored. Otherwise, if `host_allocate` is 1, `result_buffer_mapping_id_inout` is populated with a host-allocated buffer mapping ID, and `result_buffer_size_inout` is populated with this buffer's size. If `host_allocate` is 0, the host looks at the value passed to `result_buffer_size_inout`. If the size is too small for the query data (including value `0`), `result_buffer_mapping_id_inout` is ignored and `result_buffer_size_inout` is set to the minimum buffer size required. Otherwise, `result_buffer_size_inout` is unchanged and the host uses `result_buffer_mapping_id_inout` to map and populate the result buffer contents. Note that as certain queries may return a variable amount of data, clients should query in a loop to ensure all data is successfully retrieved. 17 18#### Examples 19 20##### Basic Query 21 22```cpp 23uint64_t buffer_mapping_id = 0; 24uint64_t buffer_size = 0; 25uint64_t result = 0; 26magma_device_query_fudge( 27 device, 28 MAGMA_QUERY_VENDOR_ID, 29 /* host_allocate = */ 0, 30 &buffer_mapping_id, // Ignored and unchanged 31 &buffer_size, // Ignored and unchanged 32 &result); // Populated with VENDOR_ID 33``` 34 35##### Host-Allocated Query 36 37```cpp 38uint64_t buffer_mapping_id = 0; 39uint64_t buffer_size = 0; 40uint64_t result = 0; 41magma_device_query_fudge( 42 device, 43 MAGMA_QUERY_TOTAL_TIME, 44 /* host_allocate = */ 1, 45 &buffer_mapping_id, // Populated with mapping ID 46 &buffer_size, // Populated with buffer size 47 &result); // Ignored and unchanged 48``` 49 50##### Guest-Allocated Query 51 52Note that in the following example, the query always returns a fixed-size `magma_total_time_query_result_t`. Although the client could have allocated a buffer sufficiently large to hold this data up front, a loop is used to illustrate handling of variable-size queries, as may be encountered in vendor-specific queries. 53 54```cpp 55uint64_t buffer_mapping_id = 0; 56uint64_t buffer_size = 0; 57uint64_t result = 0; 58 59uint64_t allocated_size = 0; 60GuestBuffer buffer; 61do { 62 if (buffer_size > 0) { 63 CreateBufferWithMappingId(buffer_size, &buffer, &buffer_mapping_id); 64 allocated_size = buffer_size; 65 } 66 // On the first pass, buffer_mapping_id is ignored, 67 // and buffer_size populated with the required size. 68 // On subsequent passes, an allocated buffer and its 69 // size are passed. If the buffer is sufficiently large, 70 // the buffer contents are populated and the loop exits. 71 // Otherwise, a larger buffer is allocated and the query 72 // is attempted again. 73 magma_device_query_fudge( 74 device, 75 MAGMA_QUERY_TOTAL_TIME, 76 /* host_allocate = */ 0, 77 &buffer_mapping_id, 78 &buffer_size, 79 &result); // Ignored and unchanged 80} while (allocated_size < buffer_size); 81``` 82 83### `magma_connection_execute_command_fudge` 84 85This method has the same semantics as `magma_connection_execute_command`, however `descriptor` points to `descriptor_size` bytes that contain a packed `magma_command_descriptor_t` using the following tightly-packed format: 86 87```cpp 88uint32_t resource_count; 89uint32_t command_buffer_count; 90uint32_t wait_semaphore_count; 91uint32_t signal_semaphore_count; 92uint64_t flags; 93magma_exec_resource_t resources[resource_count]; 94magma_exec_command_buffer_t command_buffers[command_buffer_count]; 95uint64_t semaphore_ids[signal_semaphore_count]; 96``` 97 98### `magma_connection_execute_immediate_commands_fudge` 99 100This method has the same semantics as `magma_connection_execute_immediate_commands`, however `command_buffers` points to `command_buffers_size` bytes containing a list of packed `magma_inline_command_buffer_t` structs. The offset to each packed `magma_inline_command_buffer_t` is defined by the elements of `command_buffer_offsets`. Each `magma_inline_command_buffer_t` is encoded using the following tightly-packed format: 101 102```cpp 103uint64_t size; 104uint32_t semaphore_count; 105uint32_t padding; 106uint64_t semaphore_ids[semaphore_count]; 107uint8_t data[size]; 108``` 109 110### `magma_buffer_set_name_fudge` 111 112This method has the same semantics as `magma_buffer_set_name`, however `name_size` should be set to the number of bytes that should be used to define `name`. This should not include the terminating null character. 113 114#### Example 115 116```cpp 117magma_buffer_set_name_fudge(buffer, "MyBuf", 5); 118``` 119