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