dymokomi/luce-gpu
Source of release 0.5.7
0.5.7 / src / gpu / metal / submission.lucb
#==============================================================================================
#
# submission - Serials, completion and GPU times of Metal submissions
#
# DESCRIPTION:
# Frames' passes, uploads, copies and reads are encoded into the device's open command
# buffer, committed once at a surface's present, a read, a compute pass, a wait on its
# submission or after `metal_open_limit` uses, so a frame of many passes is one
# submission. Every command buffer luce-gpu commits on a device's queue gets the next
# serial in a ring of the last `timed_submissions`. The ring
# retains a submission's command buffers only while they run: once they complete it keeps
# their GPU start and end times and whether they failed, and lets them go, so frames'
# drawables return to their layer at once. A submission leaving the ring is waited for
# first, so one no longer in it has finished.
#
#==============================================================================================
## A recent submission: its serial, its command buffers while they run, and
## once they have finished, its GPU times and whether it failed.
struct MetalSubmission:
var serial: u64
var commands: void*[]
var count: usize
var start: u64
var end: u64
var failed: bool
## The first failed command buffer's MTLCommandBufferError code.
var failure: u64
## How many encodings (passes, uploads, copies) the open command buffer takes
## before it is committed on its own: what bounds the latency and the upload
## ring for a program that renders offscreen without presenting or reading.
let metal_open_limit: usize = 64
## The device's open command buffer, made when none is: everything encoded
## into it is one submission, whose serial is reserved now.
func metal_open(device: MetalDevice*) -> void*!:
if let command = device.open:
device.open_uses += 1
return command
let command = metal_ptr(metal_required(device.queue), metal_sel("commandBuffer")) else error(failed, "could not create a Metal command buffer")
# Kept past the caller's autorelease pool until it is committed.
metal_void(command, metal_sel("retain"))
device.open = command
device.open_uses = 1
device.serial += 1
device.open_serial = device.serial
return command
## Commit the open command buffer once it has taken enough encodings.
func metal_encoded(device: MetalDevice*):
if device.open_uses >= metal_open_limit: metal_flush(device)
## Commit the open command buffer, if any, as its reserved submission.
func metal_flush(device: MetalDevice*):
let command = device.open else return
device.open = none
device.open_uses = 0
metal_void(command, metal_sel("commit"))
let buffers = new void*[1] --- in memory.heap catch failure:
# Out of host memory: the work runs; only its time is lost.
_ = failure
metal_void(command, metal_sel("release"))
return
buffers[0] = command
metal_record_at(device, device.open_serial, buffers, 1)
metal_ring_trim(device)
## Record `buffers`, committed in order and retained, as the next submission
## (after the open command buffer, which is committed first); the ring owns
## them from here. Its serial.
func metal_record_all(device: MetalDevice*, buffers: void*[], count: usize) -> u64:
device.serial += 1
metal_record_at(device, device.serial, buffers, count)
return device.serial
func metal_record_at(device: MetalDevice*, serial: u64, buffers: void*[], count: usize):
let slot = &device.submissions[(usize)(serial % (u64)timed_submissions)]
metal_submission_finish(slot, true)
*slot = MetalSubmission(serial = serial, commands = buffers, count = count)
metal_submissions_harvest(device)
func metal_release_buffers(buffers: void*[], count: usize):
for index in 0..<count:
metal_void(buffers[index], metal_sel("release"))
free(buffers) in memory.heap
## Keep a finished submission's times and status and let its command buffers
## go; with `wait`, wait for them first, else leave a running one alone.
func metal_submission_finish(slot: MetalSubmission*, wait: bool):
if slot.count == 0: return
for index in 0..<slot.count:
let command = slot.commands[index]
if wait:
metal_void(command, metal_sel("waitUntilCompleted"))
# MTLCommandBufferStatusCompleted (4) or Error (5).
elif metal_uint(command, metal_sel("status")) < 4:
return
slot.start = metal_nanoseconds(metal_double(slot.commands[0], metal_sel("GPUStartTime")))
slot.end = metal_nanoseconds(metal_double(slot.commands[slot.count - 1], metal_sel("GPUEndTime")))
for index in 0..<slot.count:
if metal_uint(slot.commands[index], metal_sel("status")) != 4 and not slot.failed:
slot.failed = true
slot.failure = metal_failure_code(slot.commands[index])
metal_release_buffers(slot.commands, slot.count)
var none_left: void*[]
slot.commands = none_left
slot.count = 0
## Let every finished submission's command buffers go.
func metal_submissions_harvest(device: MetalDevice*):
for index in 0..<timed_submissions:
metal_submission_finish(&device.submissions[index], false)
func metal_submissions_destroy(device: MetalDevice*):
metal_flush(device)
for index in 0..<timed_submissions:
metal_submission_finish(&device.submissions[index], true)
## The ring slot holding `serial`, or none once it left the ring (finished).
func metal_submission_slot(device: MetalDevice*, serial: u64) -> MetalSubmission*?:
if serial == 0: return none
# Asking about the open command buffer's work commits it.
if device.open != none and serial >= device.open_serial: metal_flush(device)
let slot = &device.submissions[(usize)(serial % (u64)timed_submissions)]
return slot if slot.serial == serial else none
func metal_submission_done(device: MetalDevice*, serial: u64) -> bool:
let slot = metal_submission_slot(device, serial) else return true
metal_submission_finish(slot, false)
return slot.count == 0
func metal_submission_wait(device: MetalDevice*, serial: u64) -> !:
let slot = metal_submission_slot(device, serial) else return
metal_submission_finish(slot, true)
if slot.failed:
error(execution_failed, metal_failure_reason(slot.failure))
func metal_submission_time(device: MetalDevice*, serial: u64) -> GpuTime?:
let slot = metal_submission_slot(device, serial) else return none
metal_submission_finish(slot, false)
if slot.count > 0: return none
return GpuTime(start = slot.start, end = slot.end)
## The MTLCommandBufferError code of a failed command buffer; 0 when it has no error.
func metal_failure_code(command: void*) -> u64:
let failure = metal_ptr(command, metal_sel("error")) else return 0
return metal_uint(failure, metal_sel("code"))
## What failed, by MTLCommandBufferError code, so a failure names its cause.
func metal_failure_reason(code: u64) -> str:
match code:
2: return "the GPU failed while running submitted work: a command buffer ran too long (Metal timeout)"
3: return "the GPU failed while running submitted work: a page fault, a shader reading or writing outside a resource"
4: return "the GPU failed while running submitted work: the process's GPU access was revoked"
7: return "the GPU failed while running submitted work: not permitted (a background process may not use the GPU)"
8: return "the GPU failed while running submitted work: out of GPU memory"
9: return "the GPU failed while running submitted work: a resource it used was invalid (destroyed or purged)"
10: return "the GPU failed while running submitted work: a memoryless attachment was loaded or stored"
11: return "the GPU failed while running submitted work: the device was removed"
12: return "the GPU failed while running submitted work: a shader's call stack overflowed"
_: return "the GPU failed while running submitted work (Metal internal error)"
## Metal reports GPU times as host-time seconds.
func metal_nanoseconds(seconds: f64) -> u64:
return (u64)(seconds * 1000000000.0) if seconds > 0.0 else 0