Add helper to import an external fence (#24)

Author: averne

Primer.md

@@ -329,12 +329,15 @@ Command lists can be reused by other command lists as well. When `dkCmdBufCallLi
 ```c
 struct DkFence;
 DkResult dkFenceWait(DkFence* obj, int64_t timeout_ns);
+void dkFenceImport(DkFence* obj, uint32_t id, uint32_t value);
 ```
 
 Fences (`DkFence`) are opaque structs that contain GPU synchronization information, used to determine when work submitted to the GPU has finished executing. Each time they're scheduled to be signaled in a queue (`DkQueue`), either directly or indirectly through a command list, their contents are updated. Fences can be waited on by the GPU or CPU (using the `dkFenceWait` function). When a fence is waited on, the waiter (CPU or GPU) will be kept blocked until the point in which it's signaled (hence marking the completion of dependent work).
 
 Usually fences will be used in a signaling command prior to being waited on. If fences are to be potentially waited on before they're signaled (e.g. if they're used to wait on previous work, with no previous work having been submitted yet), they should be initialized to zero in order to ensure that any initial waits will correctly have no effect.
 
+Synchronization between the GPU and external engines (video processing, display, etc) can be achieved through the `dkFenceImport` function, which provides a way of integrating Host1x syncpoint functionality within deko3d. The `id` and `value` parameters respectively represent the syncpt index, and the threshold at which the work associated with the fence can be considered as completed. Note that those values are usually allocated and managed by the driver. More information on syncpoints can be found in the Tegra TRM, chapter 14 ("Host Subsystem").
+
 > **Warning**: Fence wait/signal commands recorded to a command list keep a pointer to the fence struct in the command buffer's bookkeeping memory. Please make sure the struct remains at the same valid memory address for the lifetime of the command list handle; otherwise submitting the command list handle to a queue will result in undefined behavior.
 
 ### Variables (`DkVariable`)

include/deko3d.h

@@ -1244,6 +1244,7 @@ uint32_t dkMemBlockGetSize(DkMemBlock obj);
 DkResult dkMemBlockFlushCpuCache(DkMemBlock obj, uint32_t offset, uint32_t size);
 
 DkResult dkFenceWait(DkFence* obj, int64_t timeout_ns);
+void dkFenceImport(DkFence* obj, uint32_t id, uint32_t value);
 
 void dkVariableInitialize(DkVariable* obj, DkMemBlock mem, uint32_t offset);
 uint32_t dkVariableRead(DkVariable const* obj);

include/deko3d.hpp

@@ -166,6 +166,7 @@ namespace dk
 	{
 		DK_OPAQUE_COMMON_MEMBERS(Fence);
 		DkResult wait(int64_t timeout_ns = -1);
+		void import(uint32_t id, uint32_t value);
 	};
 
 	struct Variable : public detail::Opaque<::DkVariable>
@@ -616,6 +617,11 @@ namespace dk
 		return ::dkFenceWait(this, timeout_ns);
 	}
 
+	inline void Fence::import(uint32_t id, uint32_t value)
+	{
+		::dkFenceImport(this, id, value);
+	}
+
 	inline void Variable::initialize(DkMemBlock mem, uint32_t offset)
 	{
 		::dkVariableInitialize(this, mem, offset);

source/dk_fence.cpp

@@ -69,3 +69,16 @@ DkResult dkFenceWait(DkFence* obj, int64_t timeout_ns)
 		timeout_us = timeout_ns / 1000;
 	return obj->wait(timeout_us);
 }
+
+void dkFenceImport(DkFence* obj, uint32_t id, uint32_t value) {
+	obj->m_type = DkFence::External;
+	obj->m_external.m_fence = {
+		.num_fences = 1,
+		.fences = {
+			{
+				.id    = id,
+				.value = value,
+			},
+		},
+	};
+}