同步檔案 API 指南¶
- 作者:
Gustavo Padovan <gustavo at padovan dot org>
本文件旨在指導裝置驅動程式編寫者瞭解 sync_file API 是什麼，以及驅動程式如何支援它。 Sync 檔案是 fences(struct dma_fence) 的載體，需要在驅動程式之間或跨程序邊界進行同步。
sync_file API 旨在用於向/從使用者空間傳送和接收 fence 資訊。 它使使用者空間能夠進行顯式 fencing，即生產者驅動程式（如 GPU 或 V4L 驅動程式）不是將 fence 附加到緩衝區，而是透過 sync_file 將與緩衝區相關的 fence 傳送到使用者空間。
然後可以將 sync_file 傳送到消費者（例如 DRM 驅動程式），在 fence 發出訊號之前，它不會將緩衝區用於任何事情，即，發出 fence 的驅動程式不再使用/處理緩衝區，因此它發出訊號表明該緩衝區已準備好使用。 對於消費者 -> 生產者週期部分，情況正好相反。
Sync 檔案允許使用者空間瞭解驅動程式之間緩衝區共享的同步。
Sync 檔案最初是在 Android 核心中新增的，但當前的 Linux 桌面可以從中受益匪淺。
in-fences 和 out-fences¶
Sync 檔案可以傳送到使用者空間或從使用者空間傳送。 當 sync_file 從驅動程式傳送到使用者空間時，我們稱其包含的 fences 為“out-fences”。 它們與驅動程式正在處理或將要處理的緩衝區相關，因此驅動程式建立一個 out-fence 以便能夠透過 dma_fence_signal() 通知何時完成使用（或處理）該緩衝區。 Out-fences 是驅動程式建立的 fences。
另一方面，如果驅動程式透過來自使用者空間的 sync_file 接收 fence，我們稱這些 fence 為“in-fences”。 接收 in-fences 意味著我們需要等待 fence 發出訊號，然後才能使用與 in-fences 相關的任何緩衝區。
建立 Sync 檔案¶
當驅動程式需要將 out-fence 傳送到使用者空間時，它會建立一個 sync_file。
介面
struct sync_file *sync_file_create(struct dma_fence *fence);
呼叫者傳遞 out-fence 並返回 sync_file。 這只是第一步，接下來需要在 sync_file->file 上安裝一個 fd。 所以它獲得一個 fd
fd = get_unused_fd_flags(O_CLOEXEC);
並將其安裝在 sync_file->file 上
fd_install(fd, sync_file->file);
現在可以將 sync_file fd 傳送到使用者空間。
如果建立過程失敗，或者由於任何其他原因需要釋放 sync_file，則應使用 fput(sync_file->file)。
從使用者空間接收 Sync 檔案¶
當用戶空間需要將 in-fence 傳送到驅動程式時，它會將 Sync 檔案的檔案描述符傳遞給核心。 然後，核心可以從中檢索 fences。
介面
struct dma_fence *sync_file_get_fence(int fd);
返回的引用歸呼叫者所有，之後必須使用 dma_fence_put() 處理掉。 如果發生錯誤，則返回 NULL。
參考文獻
struct sync_file在 include/linux/sync_file.h 中上面提到的所有介面都在 include/linux/sync_file.h 中定義